🗂

Nushell カスタム補完について

2022/12/06に公開約4,000字

カスタム補完

カスタム補完を使用すると、カスタム コマンドと補完という 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を例にカスタム補完を記述してみます。
pueuepueue 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.nuexport extern "git push"の後に、追記します。
現在、pueueのグループは2つ(daily, default)ある状態です。

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

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

❯ | pueue status -g d
daily               default     

Discussion

ログインするとコメントできます