Document custom completion options and styling (#1726)

Document the fact that custom completers can return a record with an options field, as well as the fact that each individual suggestion can include a style, for changing the color of that suggestion.

Author: ysthakur

book/custom_completions.md

@@ -21,19 +21,52 @@ my-command
 The first line defines a custom command which returns a list of three different animals. These are the possible values for the completion.
 
 ::: tip
-The completion command must return a Nushell `list` of the possible completion values. If a completer does not return a valid list, the default completer will be used. The default completer returns a list of files and subdirectories of the current directory.
-
-To suppress completions for an argument (for example, an `int` that can accept any integer), define a completer that returns an empty list (`[ ]`).
+To suppress completions for an argument (for example, an `int` that can accept any integer), define a completer that returns an empty list (`[ ]`). At the moment, invalid values such as `null` will also suppress completions, but this may change in the future.
 :::
 
-In the second line of the example above, `string@animals` tells Nushell two things—the shape of the argument for type-checking and the completer which will suggest possible values for the argument.
+In the second line, `string@animals` tells Nushell two things—the shape of the argument for type-checking and the completer which will suggest possible values for the argument.
 
 The third line is demonstration of the completion. Type the name of the custom command `my-command`, followed by a space, and then the <kbd>Tab</kbd> key. This displays a menu with the possible completions. Custom completions work the same as other completions in the system, allowing you to type `e` followed by the <kbd>Tab</kbd> key to complete "eel" automatically.
 
 ::: tip
 When the completion menu is displayed, the prompt changes to include the `|` character by default. This can be changed using `$env.config.menus.marker`.
 :::
 
+## Options for Custom Completions
+
+If you want to choose how your completions are filtered and sorted, you can also return a record rather than a list. The list of completion suggestions should be under the `completions` key of this record. Optionally, it can also have, under the `options` key, a record containing the following optional settings:
+
+- `sort` - Set this to `false` to stop Nushell from sorting your completions. By default, this is `true`, and completions are sorted according to `$env.config.completions.sort`.
+- `case_sensitive` - Set to `true` for the custom completions to be matched case sensitively, `false` otherwise. Used for overriding `$env.config.completions.case_sensitive`.
+- `completion_algorithm` - Set this to either `prefix` or `fuzzy` to choose how your completions are matched against the typed text. Used for overriding `$env.config.completions.algorithm`.
+- `positional` - When prefix matching is used, setting this to `false` will use substring matching instead. `true` by default.
+
+Here's an example demonstrating how to set these options:
+
+```nu
+def animals [] {
+    {
+        options: {
+            case_sensitive: false,
+            completion_algorithm: prefix,
+            positional: false,
+            sort: false,
+        },
+        completions: [cat, rat, bat]
+    }
+}
+def my-command [animal: string@animals] { print $animal }
+```
+
+Now, if you try to complete `A`, you get the following completions:
+
+```nu
+>| my-command A
+cat                 rat                 bat
+```
+
+Because we made matching case-insensitive and used `positional: false`, 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).
+
 ## Modules and Custom Completions
 
 Since completion commands aren't meant to be called directly, it's common to define them in modules.
@@ -125,15 +158,20 @@ export extern "git push" [
 
 Custom completions will serve the same role in this example as in the previous examples. The examples above call into two different custom completions, based on the position the user is currently in.
 
-## Custom Descriptions
+## Custom Descriptions and Styles
 
-As an alternative to returning a list of strings, a completion function can also return a list of records with a `value` and `description` field.
+As an alternative to returning a list of strings, a completion function can also return a list of records with a `value` field as well as optional `description` and `style` fields. The style can be one of the following:
+
+- A string with the foreground color, either a hex code or a color name such as `yellow`. For a list of valid color names, see `ansi --list`.
+- A record with the fields `fg` (foreground color), `bg` (background color), and `attr` (attributes such as underline and bold). This record is in the same format that `ansi --escape` accepts. See the [`ansi`](/commands/docs/ansi) command reference for a list of possible values for the `attr` field.
+- The same record, but converted to a JSON string.
 
 ```nu
 def my_commits [] {
     [
-        { value: "5c2464", description: "Add .gitignore" },
-        { value: "f3a377", description: "Initial commit" }
+        { value: "5c2464", description: "Add .gitignore", style: red },
+        # "attr: ub" => underlined and bolded
+        { value: "f3a377", description: "Initial commit", style: { fg: green, bg: "#66078c", attr: ub } }
     ]
 }
 ```
@@ -149,10 +187,10 @@ def my-command [commit: string@my_commits] {
 
 ... be aware that, even though the completion menu will show you something like
 
-```nu
->_ my-command <TAB>
-5c2464  Add .gitignore
-f3a377  Initial commit
+```ansi
+>_ [36mmy-command[0m <TAB>
+[1;31m5c2464[0m  [33mAdd .gitignore[0m
+[1;4;48;2;102;7;140;32mf3a377  [0m[33mInitial commit[0m
 ```
 
 ... only the value (i.e., "5c2464" or "f3a377") will be used in the command arguments!