Skip to content

custom_completions.md

Latest commit

 

History

History
291 lines (217 loc) · 12.5 KB

custom_completions.md

File metadata and controls

291 lines (217 loc) · 12.5 KB

Custom Completions

Custom completions allow you to mix together two features of Nushell: custom commands and completions. With them, you're able to create commands that handle the completions for positional parameters and flag parameters. These custom completions work both for custom commands and known external, or extern, commands.

A completion is defined in two steps:

  • Define a completion command (a.k.a. completer) that returns the possible values to suggest (either strings or records)
  • Attach the completer to the type annotation (shape) of another command's argument using <shape>@<completer>

Here's a simple example:

# Completion command
def animals [] { ["cat", "dog", "eel" ] }
# Command to be completed
def my-command [animal: string@animals] { print $animal }
my-command
# => cat                 dog                 eel

The first line defines a custom command which returns a list of three different animals. These are the possible values for the completion.

::: tip To suppress completions for an argument (for example, an int that can accept any integer), define a completer that returns an empty list ([ ]). :::

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 Tab 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 Tab key to complete "eel" automatically.

::: tip When the completion menu is displayed, the prompt changes to include the | character by default. To change the prompt marker, modify the marker value of the record, where the name key is completion_menu, in the $env.config.menus list. See also the completion menu configuration. :::

::: tip To fall back to Nushell's built-in file completions, return null rather than a list of suggestions. :::

The completer can also return records rather than strings to further customize its suggestions (the list of suggestions can include both strings and records mixed together). The record must contain a value field containing the suggestion value. It can also contain the following optional fields:

  • description: A short description to be displayed alongside the suggestion
  • span: For choosing which part of the buffer to replace (elaborated on below)
  • style: For overriding the style used for the suggestion value (elaborated on below)
  • display_override: For overriding the displayed suggestion text in the completion menu, as well as more complicated styling (elaborated on below)

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.
  • filter - Set this to false to stop Nushell from filtering your completions. This is true by default. Note that when filtering is disabled, sorting also becomes disabled.
  • 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 prefix, substring, or fuzzy to choose how your completions are matched against the typed text. Used for overriding $env.config.completions.algorithm.

Here's an example demonstrating how to set these options:

def animals [] {
    {
        options: {
            case_sensitive: false,
            completion_algorithm: substring,
            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:

>| my-command A
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).

Modules and Custom Completions

Since completion commands aren't meant to be called directly, it's common to define them in modules.

Extending the above example with a module:

module commands {
    def animals [] {
        ["cat", "dog", "eel" ]
    }

    export def my-command [animal: string@animals] {
        print $animal
    }
}

In this module, only the the custom command my-command is exported. The animals completion is not exported. This allows users of this module to call the command, and even use the custom completion logic, without having access to the completion command itself. This results in a cleaner and more maintainable API.

::: tip Completers are attached to custom commands using @ at parse time. This means that, in order for a change to the completion command to take effect, the public custom command must be reparsed as well. Importing a module satisfies both of these requirements at the same time with a single use statement. :::

Context Aware Custom Completions

It is possible to pass the context to the completion command. This is useful in situations where it is necessary to know previous arguments or flags to generate accurate completions.

Applying this concept to the previous example:

module commands {
    def animals [] {
        ["cat", "dog", "eel" ]
    }

    def animal-names [context: string] {
        match ($context | split words | last) {
            cat => ["Missy", "Phoebe"]
            dog => ["Lulu", "Enzo"]
            eel => ["Eww", "Slippy"]
        }
    }

    export def my-command [
        animal: string@animals
        name: string@animal-names
    ] {
        print $"The ($animal) is named ($name)."
    }
}

Here, the command animal-names returns the appropriate list of names. $context is a string where the value is the command-line that has been typed so far.

>| my-command
cat                 dog                 eel
>| my-command dog
Lulu                Enzo
>my-command dog enzo
The dog is named Enzo

On the second line, after pressing the tab key, the argument "my-command dog" is passed to the animal-names completer as context.

::: tip Completers can also obtain the current cursor position on the command-line using:

def completer [context:string, position:int] {}

:::

Completers can also choose which part of the buffer should be replaced by each suggestion using the span field. Here's a not-particularly-realistic example command with a completer:

def comp [context: string] {
    let foo_pos = $context | str index-of "foo"
    [
        {
            value: "bar",
            span: (if $foo_pos != -1 {
                { start: $foo_pos, end: ($context | str length) }
            } else {
                null
            })
        },
        {
            value: "other-command",
            span: { start: 0, end: ($context | str length) }
        }
    ]
}
def my-command [...arg: string@comp] {}

Now, try typing in a few arguments that include "foo" and hit tab.

>_ my-command blech foo garply <TAB>
bar                 other-command
  • If you select bar, your buffer will look like my-command blech bar. That's because we replaced everything from where foo began (start: $foo_pos) to the cursor ($context | str length).
  • If you select other-command, your buffer will look like other-command. That's because we replaced everything, from the start (0) to the cursor ($context | str length).

::: tip Note

The start and end are relative to the beginning of the command, not the beginning of the buffer. Hence, this completer will work even if the command is part of a pipeline, e.g., ls | my-command foo <TAB>.

:::

Custom Completion and extern

A powerful combination is adding custom completions to known extern commands. These work the same way as adding a custom completion to a custom command: by creating the custom completion and then attaching it with a @ to the type of one of the positional or flag arguments of the extern.

If you look closely at the examples in the default config, you'll see this:

export extern "git push" [
    remote?: string@"nu-complete git remotes",  # the name of the remote
    refspec?: string@"nu-complete git branches" # the branch / refspec
    ...
]

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.

Customizing Suggestions Visually

To change how suggestions look, suggestions can include a style field and/or a display_override field.

The style field is used to set the style for the suggestion value (not the description). It overrides the suggestion style for the menu (which can be set globally when adding the menu in $env.config.menus). 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 command reference for a list of possible values for the attr field.
  • The same record, but converted to a JSON string.

The display_override field can be used to set the text that's displayed as the suggestion value in the completion menu. It can contain ANSI escapes, meaning that it can also be used for styling the suggestion value. You can, however, set both style and display_override.

def my_commits [] {
    [
        {
            value: "5c2464",
            display_override: "HEAD",
            description: "Add .gitignore",
            style: red
        },
        {
            value: "f3a377",
            display_override: $"origin/(ansi blue)main", # Include styling in display_override
            description: "Initial commit",
            style: { fg: white, bg: "#66078c", attr: ub } # "attr: ub" => underlined and bolded
        },
    ]
}

::: tip Note With the following snippet:

def my-command [commit: string@my_commits] {
    print $commit
}

... be aware that, even though the completion menu will show you something like

>_ �[36mmy-command�[0m <TAB>
�[31mHEAD�[0m         �[33mAdd .gitignore�[0m
�[1;4;48;2;102;7;140;32m�[37morigin/�[34mmain  �[0m�[33mInitial commit�[0m

... only the value (i.e., "5c2464" or "f3a377") will be used in the command arguments! :::

External Completions

External completers can also be integrated, instead of relying solely on Nushell ones.

For this, set the external_completer field in config.nu to a closure which will be evaluated if no Nushell completions were found.

$env.config.completions.external = {
    enable: true
    max_results: 100
    completer: $completer
}

You can configure the closure to run an external completer, such as carapace.

An external completer is a function that takes the current command as a string list, and outputs a list of records with value and description keys, like custom completion functions. When the closure returns null, it defaults to file completion.

::: tip Note This closure will accept the current command as a list. For example, typing my-command --arg1 <tab> will receive [my-command --arg1 " "]. :::

This example will enable carapace external completions:

let carapace_completer = {|spans|
    carapace $spans.0 nushell ...$spans | from json
}

More examples of external completers can be found in the cookbook.