Yash マニュアル: complete 組込みコマンド
Author: magicant
Description: Yash の complete 組込みコマンドについて

# Complete 組込みコマンド

Complete 組込みコマンドは行編集におけるコマンドライン補完の方式を表示・設定します。

## 構文

- `complete [-C コマンド] [-O オプション] [-Xabcdfghjkuv] [-F 関数] [-D 説明] [-W 単語] [文字列…]`
- `complete -P [-C コマンド] [-O オプション]`
- `complete -R [-C コマンド] [-O オプション]`
- `complete -G [-W 単語] 文字列…`

## 説明

`-P` (`--print`) オプションを付けて実行すると、complete コマンドはこれまでに設定された補完方式の設定を標準出力に出力します。出力はコマンドとして実行することで設定内容を復元できるようになっています。デフォルトではすべての設定内容を出力しますが、`-C` (`--target-command`) オプションおよび `-O` (`--target-option`) オプションを指定するとそのコマンド・オプションに関する設定のみ出力します。

`-R` (`--remove`) オプションを付けて実行すると、complete コマンドはこれまでに設定された補完方式の設定を消去します。デフォルトではすべての設定を消去しますが、`-C` オプションおよび `-O` オプションを指定するとそのコマンド・オプションに関する設定のみ消去します。

`-P` オプションも `-R` オプションも付けずに `-C` オプションを付けて実行すると、`-C` オプションで指定したコマンドに対する補完方式の設定を行います。補完方式設定用のオプションおよびオペランド (下記参照) が、そのコマンドの引数の補完の仕方を指定します。`-O` オプションも共に指定した場合は、そのオプションに対する設定となります。補完方式設定用のオプションおよびオペランドはオプションの引数の補完方法を指定します。補完方式の設定は累積的です。すなわち、設定はそれまでの設定を上書きするのではなく、前の設定に追加されます。

`-P` オプションも `-R` オプションも `-C` オプションも付けずに実行すると、現在行っている補完に対する補完候補を生成します。これは生成関数 (下記 `-F` オプション参照) の中でのみ行えます。`-G` (`--delegate`) オプションを指定しない場合、指定した補完方式設定用のオプションおよびオペランドに従って候補を生成します。`-G` を指定した場合、指定した文字列が現在補完を行おうとしている (入力途中の) コマンド・引数であるとして補完を試みます。

## オプション

`-C コマンド`, `--target-command=コマンド`
  補完の仕方を設定・表示・削除する対象となるコマンドを指定します。
`-O オプション`, `--target-option=オプション`
  補完の仕方を設定・表示・削除する対象となるオプションを指定します。オプションには、短いオプションと長いオプションとがあります。
  - 短いオプションは、一文字からなります。複数の短いオプションは一つのハイフンの後にまとめて指定できます (例えば `-a -b` は `-ab` とできます)。短いオプションは、ハイフンを除いたオプション一文字として `-O` オプションの引数に指定します (例えば `-O a` または `--target-option=a`)。
  - 長いオプションは、ハイフンで始まる複数の文字列からなります。複数の長いオプションを一つにまとめて指定することはできません。長いオプションは、先頭のハイフンを含めたオプション全体を `-O` オプションの引数として指定します (例えば `-O -Wall` または `--target-option=--help`)。
`-P`, `--print`
  これまでに行った補完の仕方の設定内容を出力します。
`-R`, `--remove`
  これまでに行った補完の仕方の設定を削除します。
`-X`, `--intermixed`
  コマンドの引数の補完の仕方を設定する際にこのオプションを指定すると、そのコマンドではオペランドの後にオプションを指定可能であるとみなします。(デフォルトでは、最初のオペランド以降の引数はすべてオペランドとして補完されます)
`-D 説明`, `--description=説明`
  補完の仕方を設定する際にこのオプションを指定すると、このオプションで指定した説明が補完の際に候補の説明として表示されます。
  - オペランド (下記参照) と共に指定した場合は、そのオペランドが補完候補として使われる際の説明として使われます。
  - オペランドがない場合は、コマンドまたはオプションを補完する際にそれらの説明として使われます。`-O` オプションと共に指定した場合は、そのオプションの説明として、そうでない場合は、`-C` オプションで指定したコマンドの説明として使われます。
`-G`, `--delegate`
  指定したオペランド (文字列…) が現在補完を行おうとしている入力途中のコマンド・引数であるとみなして補完候補を生成します。
  このオプションは補完関数の中でのみ使えます。
`-W`, `--word=単語`
  補完を行おうとしている入力途中のコマンドまたは引数の値を単語に変更します。単語は補完関数に渡された最後の位置パラメータから先頭の何文字かを取り除いたものになっていなければなりません。
  このオプションは補完関数の中でのみ使えます。このオプションの効果は補完関数が終了するまで持続します。

### 補完方式設定のためのオプション

以下のオプションは、コマンドのオペランドまたはオプションの引数を補完するための候補の種類を指定します。

`-a`, `--alias`
  エイリアス (`--normal-alias --global-alias` に同じ)
`--array-variable`
  配列
`--bindkey`
  Bindkey コマンドで利用可能な行編集コマンド
`-b`, `--builtin`
  組込みコマンド (`--special-builtin --semi-special-builtin --regular-builtin` に同じ)
`-c`, `--command`
  コマンド (`--builtin --external-command --function` に同じ)
`-d`, `--directory`
  ディレクトリ
`--executable-file`
  実行可能ファイル
`--external-command`
  外部コマンド
`-f`, `--file`
  ファイル (ディレクトリ含む)
`--finished-job`
  終了したジョブのジョブ ID
`--function`
  関数
`--global-alias`
  グローバルエイリアス
`-g`, `--group`
  (ファイルのパーミッションなどにおける) グループ
`-h`, `--hostname`
  ホスト名
`-j`, `--job`
  ジョブ ID
`-k`, `--keyword`
  シェルの予約語
`--normal-alias`
  通常の (グローバルでない) エイリアス
`--regular-builtin`
  通常の組込みコマンド
`--running-job`
  実行中のジョブのジョブ ID
`--scalar-variable`
  (配列を除いた通常の) 変数
`--semi-special-builtin`
  準特殊組込みコマンド
`--signal`
  シグナル
`--special-builtin`
  特殊組込みコマンド
`--stopped-job`
  停止中のジョブのジョブ ID
`-u`, `--username`
  ユーザのログイン名
`-v`, `--variable`
  変数
`-F 関数`, `--generator-function=関数`
  補完候補の生成関数の名前を指定します。このオプションを指定すると、コマンドのオペランドまたはオプションの引数を補完する際に関数が実行されます。このとき関数の引数として、既に入力されているコマンド名・引数が渡されます (最後の引数は、補完の対象となっている途中まで入力された引数です)。関数の中で complete コマンドを `-C`, `-P`, `-R` オプションを付けずに補完方式設定のためのオプションまたはオペランドを指定して実行すると、そのオプションまたはオペランドに従って補完候補が動的に追加されます。

## オペランド

Complete コマンドのオペランドは、各オペランドがそれぞれ補完候補として扱われます。

## 終了ステータス

エラーがない限り complete コマンドの終了ステータスは 0 です。ただし、complete コマンドの中で生成関数を実行した場合は、その関数の終了ステータスが complete コマンドの終了ステータスになります。

## 例

Rmdir コマンドは `-p` オプションを取り、オペランドとしてディレクトリ名を受け付けます:

- `complete -C rmdir -d`
- `complete -C rmdir -O p`

このとき `-p` オプションに説明を付加する場合は、以下のようにします。

- `complete -C rmdir -O p -D '親ディレクトリも削除する'`

オプションとオペランドを以下のように同時に指定してはいけません。このように指定すると、`-p` オプションがディレクトリ名を引数として受け取るものとみなされてしまいます。

- `complete -C rmdir -O p -d # 間違った例`

GNU core utilities の ls コマンドの `-a` オプションと `--all` オプションのように、一つのコマンドに同じ意味を持つ短いオプションと長いオプションがある場合は、それらを同時に指定できます。複数の短いオプションまたは複数の長いオプションを同時に指定することは (それらが同じ意味であるかにかかわらず) できません:

- `complete -C ls -O a -O --all # 正しい例`
- `complete -C less -O --silent -O --quiet # 間違った例`

オプションが引数を取る場合は、その引数の種類をオプションで指定します。例えば cd コマンドの `--default-directory` オプションはディレクトリ名を引数として受け取ります:

- `complete -C cd -O --default-directory -d`

コマンドのオペランドまたはオプションの引数の値が固定化されている場合は、オペランドでそれを直接指定します。例えば GNU core utilities の ls コマンドの `--color` オプションは、`always`, `auto`, `force`, `if-tty`, `never`, `no`, `none`, `tty`, `yes` という九つの値を引数として受け取ります:

- `complete -C ls -O --color always auto force if-tty never no none tty yes`

これらの値に説明を付け加えたい場合は、同じ説明を与えたい値ごとに指定します。

- `complete -C ls -O --color -D '常にカラー表示する' always force yes`
- `complete -C ls -O --color -D '常にカラー表示しない' never no none`
- `complete -C ls -O --color -D '出力が端末ならカラー表示する' auto if-tty tty`

なお、`--color` オプションに対する説明も指定できます (オペランドを指定していない点に注意):

- `complete -C ls -O --color -D '出力をカラー表示するか設定する'`

## 補足

POSIX には complete コマンドに関する規定はありません。