Move Zoxide completer to cookbook (#1934)

Author: ysthakur

.vuepress/configs/sidebar/en.ts

@@ -154,6 +154,7 @@ export const sidebarEn: SidebarConfig = {
         '/cookbook/parsing',
         '/cookbook/foreign_shell_scripts',
         '/cookbook/pattern_matching',
+        '/cookbook/custom_completers',
         '/cookbook/external_completers',
         '/cookbook/modules',
         '/cookbook/files',

book/custom_completions.md

@@ -69,29 +69,6 @@ cat                 rat                 bat
 
 Because we made matching case-insensitive, Nushell will find the substring "a" in all of the completion suggestions. Additionally, because we set `sort: false`, the completions will be left in their original order. This is useful if your completions are already sorted in a particular order unrelated to their text (e.g. by date).
 
-## Another Practical Example - Zoxide Path Completions
-
-[Zoxide](https://github.com/ajeetdsouza/zoxide) allows easily jumping between visited folders in the system. It's possible to autocomplete matching folders with this completer:
-
-```nu
-def "nu-complete zoxide path" [context: string] {
-    let parts = $context | split row " " | skip 1
-    {
-      options: {
-        sort: false,
-        completion_algorithm: prefix,
-        positional: false,
-        case_sensitive: false,
-      },
-      completions: (zoxide query --list --exclude $env.PWD -- ...$parts | lines),
-    }
-  }
-
-def --env --wrapped z [...rest: string@"nu-complete zoxide path"] {
-  __zoxide_z ...$rest
-}
-```
-
 ## Modules and Custom Completions
 
 Since completion commands aren't meant to be called directly, it's common to define them in modules.

cookbook/custom_completers.md

@@ -0,0 +1,62 @@
+---
+title: Custom Completers
+---
+
+# Custom Completers
+
+## Zoxide Path Completions
+
+[Zoxide](https://github.com/ajeetdsouza/zoxide) allows easily jumping between visited folders in the system. It's possible to autocomplete matching folders with this completer:
+
+```nu
+def "nu-complete zoxide path" [context: string] {
+    let parts = $context | split row " " | skip 1
+    {
+      options: {
+        sort: false,
+        completion_algorithm: substring,
+        case_sensitive: false,
+      },
+      completions: (^zoxide query --list --exclude $env.PWD -- ...$parts | lines),
+    }
+  }
+
+def --env --wrapped z [...rest: string@"nu-complete zoxide path"] {
+  __zoxide_z ...$rest
+}
+```
+
+Do note that the above completer probably won't work with multiple keywords because each completion suggestion is a full path. Something like `z nu <TAB>` might provide `/home/user/nushell` as a suggestion, and if you select this suggestion, your commandline will be replaced with `z nu /home/user/nushell` rather than `z /home/user/nushell`. Running `z nu /home/user/nushell` will now fail.
+
+Below is a more convoluted completer that provides odd-looking suggestions but does work with multiple keywords.
+
+```nu
+def "nu-complete zoxide path" [context: string] {
+    let parts = $context | str trim --left | split row " " | skip 1 | each { str downcase }
+    let completions = (
+        ^zoxide query --list --exclude $env.PWD -- ...$parts
+            | lines
+            | each { |dir|
+                if ($parts | length) <= 1 {
+                    $dir
+                } else {
+                    let dir_lower = $dir | str downcase
+                    let rem_start = $parts | drop 1 | reduce --fold 0 { |part, rem_start|
+                        ($dir_lower | str index-of --range $rem_start.. $part) + ($part | str length)
+                    }
+                    {
+                        value: ($dir | str substring $rem_start..),
+                        description: $dir
+                    }
+                }
+            })
+    {
+        options: {
+            sort: false,
+            completion_algorithm: substring,
+            case_sensitive: false,
+        },
+        completions: $completions,
+    }
+}
+```