🗂

Nushell カスタム補完について

2022/12/06に公開

カスタム補完

カスタム補完を使用すると、カスタムコマンドと補完という Nushell の 2 つの機能を組み合わせることができます。それらを使用すると、位置パラメーターとフラグパラメーターの補完を処理するコマンドを作成できます。これらのカスタム補完は、カスタムコマンドと既知の外部 (extern) コマンドの両方で機能します。

カスタムコマンドには 2 つの部分があります。補完を処理するコマンドと、このコマンドを@を使用して別のコマンドのタイプに関連付けるコマンドです。

❯ def animals [] { ["cat", "dog", "eel" ] }
❯ def my-command [animal: string@animals] { print $animal }
❯ | my-command 
cat                 dog                 eel

最初の行では、3 種類の動物のリストを返すカスタムコマンドを作成します。これらは補完で使用したい値です。このコマンドを作成したら、それを使用して、他のカスタムコマンドと extern の補完を提供できます。

2 行目では、string@animals を使用しています。これは Nushell に 2 つのことを伝えます: 型チェック用の引数の形状と、ユーザーがその位置で値を完成させたい場合に使用するカスタム補完です。

3 行目に、カスタムコマンド my-command の名前を入力し、その後にスペースを押してから <tab> キーを押します。これにより、補完が表示されます。カスタム補完は、システム内の他の補完と同じように機能し、e に続けて <tab> キーを押すと、「eel」が自動的に補完されます。

カスタム補完をコードのパブリック API から遠ざけたい場合があります。このために、モジュールとカスタム補完を組み合わせることができます。

上記の例をモジュールに入れましょう。

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

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

このモジュールでは、カスタムコマンド my-command のみをエクスポートし、カスタム補完動物はエクスポートしないように選択しました。これにより、このモジュールのユーザーは、カスタム補完にアクセスせずに、コマンドを呼び出したり、カスタム補完ロジックを使用したりできます。これにより、API をよりクリーンに保ちながら、同じメリットをすべて提供できます。

@を使用したカスタム補完タグは、コマンドが最初に解析されるときにロックインされるため、これが可能になります。

強力な組み合わせは、既知の extern コマンドにカスタム補完を追加することです。これらは、カスタムコマンドにカスタム補完を追加するのと同じように機能します。つまり、カスタム補完を作成し、extern の位置引数またはフラグ引数のいずれかの型に@を付けてアタッチします。

デフォルト設定の例をよく見ると、次のように表示されます。

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

カスタム補完は、この例でも前の例と同じ役割を果たします。上記の例では、ユーザーが現在いる位置に基づいて、2 つの異なるカスタム補完を呼び出します。
文字列のリストを返す代わりに、補完関数は値と説明フィールドを含むレコードのリストを返すこともできます。

def my_commits [] {
    [
        { value: "5c2464", description: "Add .gitignore" },
        { value: "f3a377", description: "Initial commit" }
    ]
}

実例

外部コマンドのタスク管理ツールのpueueを例にカスタム補完を記述してみます。
pueueのpueue statusのオプションは以下の通り。

❯ pueue status --help
pueue-status 
Display the current status of all tasks

USAGE:
    pueue status [OPTIONS]

OPTIONS:
    -g, --group <GROUP>    Only show tasks of a specific group
    -h, --help             Print help information
    -j, --json             Print the current state as json to stdout. This does not include the
                           output of tasks. Use `log -j` if you want everything

上記ヘルプ内容に基づいて、カスタム補完を記述します。次の"nu-complete pueue group"は現在のpueueのグループを列挙するものです。pueue statusでは、グループを指定でオプション-gにグループ名を与えます、ここではグループ名の補完を行うようにしています。ヘルプのコマンドの説明、オプションの説明をコメントにします。フラグはlong name形式を先に、続いてshort nameをカッコ内に記述して引数がある場合は、:の後に型、および候補リストを@でアタッチします。

# Custom completions for pueue command
# Get Group list
def "nu-complete pueue group" [] {
    ^pueue group | parse -r 'Group \"(?<name>.+)\"' | get name 
}

# Display the current status of all tasks
export extern "pueue status" [
    --group(-g):string@"nu-complete pueue group"  # Only show tasks of a specific group
    --help(-h)                              # Print help information
    --json(-j)                              # Print the current state as json to stdout. This does not include the output of tasks. Use `log -j` if you want everything
]

上記をconfig.nuのexport extern "git push"の後に、追記します。
現在、pueueのグループは２つ(daily, default)ある状態です。

❯ pueue group
Group "daily" (1 parallel): running
Group "default" (3 parallel): running

ここでpueue status -g と入直したところで、補完(TABキー)とすると下記のようにグループ名の補完候補が示され、カスタム補完が有効に動作することがわかります。

❯ | pueue status -g d
daily               default

help pueue statusとすると、ちゃんとNushellのヘルプがでます。

❯ help pueue status
Display the current status of all tasks

Usage:
  > pueue status {flags} 

Flags:
  -g, --group <Custom(String, 331)> - Only show tasks of a specific group
  -h, --help - Print help information
  -j, --json - Print the current state as json to stdout. This does not include the output of tasks. Use `log -j` if you want everything

カスタム補完

実例

Discussion