ZSHCOMPSYS(1) ZSHCOMPSYS(1) NAME zshcompsys - zsh 補完システム DESCRIPTION 訳注: ○は独自追加。△は怪しい意訳。□は原文からばっさり改 変。日本語追加部分は文責広瀬雄二(yuuji(@)gentei.org)。 ここではzshの「新しい」補完システム compsys について 述 べ る。 この補完システムは zshcompwid(1) で述べたシェル関数の 集合体で構築されている。 この補完システムは,コンテクストやカーソル位置によってうま く処理を切り替えるようにできている。最初から多くのコマンド に対する補完プログラムが用意されているのでユーザは初 期 設 定(次 のINITIALIZATION節) 以上のことは知らなくても随分楽が できるようになっている(□)。 コンテクストとは,どんな補完を施すのかを決めるコマンドライ ン上の文脈のことで, The context that decides what comple- tion is to be performed may be o 引数位置かオプション位置の場合: そのコマンドライ ン 位 置がどんな補完が要求されるべき場所なのか。たとえ ば,「rmdir の第1引数位置」ならディレクトリ名。 o 特別なコンテクスト: シェルの文法固有のルールが適 用 さ れる場所か。たとえば,「コマンド位置の単語」だと か,「配列の添字」だとか。 コンテクストそのものの詳細は追って述べる。 コマンド名やコンテクストだけでなく,この補完システムではス タ イル と タグ という概念を使用する。これらは,ユーザが補 完システムの挙動を調整するためのものである。 「タグ」は,ユーザが補完させたいであろう様々な単語群をいく つかの種別に分類するためのものである。たとえば, less (□) と打ったら,そのあとに入れ て 欲 し い の は ディ レ ク ト リ(directories)よ り も ファ イル(files)のほうだろう。この files と directories がタグである(□ 訳注: 原文が冒頭と 言 う流れを全く無視しているので根本的に変えた) (読まんでええ ここから) Tags play a dual role. They serve as a classification system for the matches, typically indicating a class of object that the user may need to distinguish. For example, when completing arguments of the ls command the user may prefer to try files before directories, so both of these are tags. They also appear as the rightmost element in a context specification. (こ こまで) 「スタイル」はユーザがその値を自分で変えて,補完システムの 様 々 な動き,たとえばマッチする単語の出力を変えたりするな zsh 4.3.2 March 2, 2006 1 ZSHCOMPSYS(1) ZSHCOMPSYS(1) ど,様々な挙動をコントロールすることができる。 (訳注: ここ も原文が冗長。冒頭なのでさらっと) (読 ま ん で ええ) Styles modify various operations of the completion system, such as output formatting, but also what kinds of completers are used (and in what order), or which tags are examined. Styles may accept arguments and are manipulated using the zstyle command described in see zshmodules(1). (ここまで) 大雑把に言えば,タグは補完すべきものが何なのか,スタイルは それらをどう補完するかを決めるものである(□)。 (読 まんでええ) In summary, tags describe what the comple- tion objects are, and style how they are to be completed. At various points of execution, the completion system checks what styles and/or tags are defined for the current context, and uses that to modify its behavior. The full description of context handling, which determines how tags and other elements of the context influence the behaviour of styles, is described below in COMPLETION SYSTEM CONFIG- URATION. (ここまで) 補完要求が発生すると,まず振り分け関数(ディスパッチャ)が呼 ばれ…… (訳注: というこの段落もここにあってもちっとも分か りやすくないので飛ばす) When a completion is requested, a dispatcher function is called; see the description of _main_complete in the list of control functions below. This dispatcher decides which function should be called to produce the completions, and calls it. The result is passed to one or more completers, functions that implement individual completion strategies: simple completion, error correction, completion with error correction, menu selection, etc. (ここまで) 多くのシェル関数があるが, `comp' で始まるものは直接呼ばれ るもの,`_' で始まるものは補完プログラムから呼ばれるもので ある。後者のシェル関数は補完の挙動を決定するもので,たいて いは「ウィジェット」としてキーストロークに割り当てられる。 INITIALIZATION zshが完全な形でインストールさ れ て い れ ば, ユ ー ザ は compinitを 呼 ぶ だ けで初期化が終わる(次節参照)。ただし, compinstallを実行して補完システムのさらなる機能を設定す る こともできる。 通 常 compinstall は .zshrc ファイルにコードを追加する。そ れに書けなければ別のファイルに書いてそのことを通知する。た zsh 4.3.2 March 2, 2006 2 ZSHCOMPSYS(1) ZSHCOMPSYS(1) だし追加したコードが実際に動くかどうかは自己責任で確認すべ きで,たとえば .zshrc の途中で return する可能性があるとき は足されたコードをもっと前の位置に動かす必要がある。足され たコードを(コメント行を含めて)まるごといじらないようにして お けば,どこに移動しても将来 compinstall を再実行したとき に正しく場所を検出して修正してくれるが,もしそのコード群に 手 動で何か足したときは次の compinstall でそれは消されるの で注意されたい(zstyleで始まる行はやんわりと処理される)。 新しく足されたコー ド は 次 にzshを 起 動 し た と き か, .zshrcをsourceすれば有効になる。ただし, compinstallによっ て削られた定義があるときは,その違いはシェルを再起動しない 限りわからない。 最初に compinstall を実行する前に, fpath 変数に登録された ディレクトリ群のどれかに compinstall があることを確認す る 必 要があるかもしれないが,正常にzshがインストールされた状 態で fpath の値を勝手に削ったりしていなければ問題ないは ず で ある(△)。 `autoload -U compinstall' でautoloadできるは ずである。 compinstall を起動すると .zshrc 情報表示とと も にプロンプトが出るのでいつでも中止できる。最後の最後に確認 が出るところまで一切 .zshrc は上書きされない。 compinitの起動 ここでは,使用中のシェル環境で直接 compinit を呼んで補完を 初 期化する方法について述べる。もし compinstall が完了して いれば .zshrc の中で自動的に呼ばれることになる。 compinit コマンドもやはり fpath 変数に登録されているディレ ク ト リ 群 のどれかに存在する必要がある。登録されていれば `autoload -U compinit; compinit' で実行できるはずであ る。 compinitは い く つ かのシェル関数定義と必要なシェル関数の autoload定義処理と新しい補完システムで使うウィジェットを定 義 し なおす。もし menu-select ウィジェット(zsh/complistモ ジュール)を使うのであれば, compinit より先にそのモジュ ー ルをロードしておくようにする。補完スタイル(後述)が補完とと もに展開も行なうように 設 定 さ れ て い て, TABキ ー に expand-or-complete を割り当てているときは compinit はそれ を complete-word に変えて展開が正しく行なわれるよ う に す る。 な お, 古い補完ウィジェットをそのまま使いたいときは,ウィ ジェットの名前にピリオド `.' を付けた名前をどれかのキー に 割 り 当 てればよい。たとえば, `.exapnd-or-complete' とす る。 デフォルトで compinit は読み込んだ設定をダンプしたも の を ファイルに書き出し 2回目以降の処理が高速に済むようにしてい る。これを無効化するには compinit に -D オプションを付けて 呼べばよい。ダンプファイルは .zcompdump という名前で,各種 初期化ファイル群と同じディレクトリ($ZDOTDIRか $HOME)に置か れ る。 こ の ファイル名は -d オプションで変更できる。次回 compinit はダンプファイルをロードし,完全な初期化 は し な zsh 4.3.2 March 2, 2006 3 ZSHCOMPSYS(1) ZSHCOMPSYS(1) い。 補 完 定義ファイルが更新されたときは compinit がそれを認識 し,ダンプファイルを作り直す。ただし,関数名や補完定義ファ イ ルの1行目にある #compdef の引数を変えたときは,手動でダ ンプファイルを消して,次の compinit に新規に作り直させてし まうのが一番面倒がない。この更新チェック機能は -C オプショ ンで無効化され,その場合ダンプファイルがない場合のみ作り直 す。 実際のダンプ処理は下請けで呼ばれる compdump 関数が行なって いる。手動で明示的にダンプファイルを作りたい場合以外は呼ぶ 必要はないだろう(□)。 変 数 _compdir にディレクトリ名を代入しておくと, compinit はそのディレクトリを補完定義関数のある場所と見なす。 セキュリティ確保のため, compinit はスーパーユーザ,または ユ ー ザ自身の所有でないファイル,所有者以外にも書き込める ディレクトリかどうかを調べる。該当する場合は compinit が本 当に使うか確認する。こうした検査をやめ,みつかったファイル を確認なし使わせたい場合は -u オプション,危険なファイルを 黙って無視させたい場合は -i オプション,セキュリティチェッ クを完全にスキップさせたい場合は -C オプションを指定すれば よい。 セ キュリティチェックは compaudit 関数を起動すればいつでも 行なえる。起動時にディレクトリを指定すればそのディレクトリ を,指定しなければ fpath と _compdir が検査される(□大分省 略)。 compinit のときと厳密に同じ場所を調べ さ せ る に は _compdir 変数に空文字列を代入してから呼ぶこと。 オートロードファイル 先述のとおり,補完で使用するオートロード関数はアンダースコ アで始める約束とし,それらのファイルが fpath/FPATH 変数 の 指 し 示 す ディ レクトリに存在しなければならない(繰り返す がzshが正常にインストールされていればそうなっているはず で ある)。 インストールが不完全で, compinit がアンダースコアで始まる ファイルを20個以上探せなかった場合は, _compdir 変数の値を 追加して探す。もしそこに Base というサブディレクトリがみつ かれば,同じ階層のすべてのサブディレクトリを,さらに Base の下に Core というサブディレクトリがみつかれば,そこにある すべてのサブディレクトリを追加する。これは,zshのソース 配 布に含まれるディレクトリを想定した挙動で,これを活かすには _compinit にソースを展開したディレクト リ の ./Completion ディレクトリを代入しておけばよいことになる(○)。 compinit は, fpath/FPATHにあるすべてのファイルの1行目を調 べ,特定のタグがあれば処理し,なければ無視する。 タグの書式は以下のどれか: zsh 4.3.2 March 2, 2006 4 ZSHCOMPSYS(1) ZSHCOMPSYS(1) #compdef names... [ -[pP] patterns... [ -N names... ] ] そのファイルをautoload登録し,names を補完すると き に そ こ に定義されている関数が呼ばれるように設定す る。 namesは引数入力を補完して欲しいコマンドの名 前 か, -context- という書式で指定する特別なコンテクス ト(文脈) 指定のどれかを書く。 (or one of a number of special contexts in the form -context- described below.) nameの部分には `cmd=service' という記述も書け,その 場合 cmd を補完するときに,service を補完するときと 同じ挙動をするようになる。これは,そこで定義して い る 補完用関数の挙動を変えるために利用できる。実際に はその関数が呼ばれるときに,どのコマンドの補完を す る ために呼ばれたのかを変数 $service に代入してくれ るので,関数作成時にはその値で処理を切り替えると よ い。もちろんその値を使わなくても構わない(□)。 #compdef の行に -p か -P オプションがある場合は,後 続する引数(群)がパターンとして解釈され,そのパタ ー ン(の どれか)にマッチするコマンド(または文脈)に対す る補完をするときに関数が呼ばれるようになる。 -p は 他 の補完を試す前, -P は試したあとに呼ばれるパター ンを指定する。よって, -P はデフォルトの挙動を指 定 するときに使える。 -N オプションは, -p や -P オプションに続けて書いた パターンのあとに指定して,以後の引数はパターン指 定 でないことを指示する。 #compdef -k style key-sequences... 内部ウィジェット style と同様に振る舞うウィジェット を作り key-sequences に割り当てる。 style には, 補 完機能を持つ内部ウィジェットのどれか,すなわち com- plete-word, delete-char-or-list, expand-or-com- plete, expand-or-complete-prefix, list-choices, menu-complete, menu-expand-or-complete, reverse-menu-complete の ど れかを指定する。もし, zsh/complist モジュール( zshmodules(1)参照) がロ ー ドされている場合は menu-select も指定可能。 key-sequences で指定したどれかのキーがタイプされる とそのファイルで定義されている関数がマッチ単語を 生 成 するために呼ばれる。ただし,指定したキーストロー クに既に別の機能が割り当ててある場合はそのキーへ の 割 り 当 ては行なわれない。作成されるウィジェットは ファイル名と同じ名前で, bindkeyコマンドで普通に 割 り当てできるものとなる。 #compdef -K widget-name style key-sequences ... -kと 同様だが,ひとつの widget-name と style の組み 合わせに対し,ひとつの key-sequences だけが指定でき る。この3つの引数の組み合わせを何個でも書ける。その 場合 widget-name が重複しないようにする。最初の文字 zsh 4.3.2 March 2, 2006 5 ZSHCOMPSYS(1) ZSHCOMPSYS(1) が `_' で始まっていない場合は補われる。 widget-name の名前は,他のウィジェットと衝突しないようにしな け れ ばならないので,関数名に由来した名前を付けるとよ い。たとえば, #compdef -K _foo_complete complete-word "^X^C" \ _foo_list list-choices "^X^D" (実際には1行で記述する) のような名前付けをする。 こ の例の場合, _foo_complete ウィジェットを補完用と定 義して, `^X^C'に割り当て, _foo_list ウィジェッ ト を一覧出力用に定義して `^X^D' に割り当てている。 #autoload [ options ] #autoload タグはその関数をautoload登録するのみで, 他の処理は行なわないことを指示する。典型的には, 補 完 関数の下請け関数をautoload化したりするために用い る。 options を続けて 書 く と そ れ を そ の ま ま autoloadコ マンドに渡す。たとえば, +X を書いて,そ の関数を直ちにロードさせたりできる。オートロード の 際 には常に -U,-z オプションが暗黙のうちに有効化さ れる。 タグに書く # 文字もタグ名に含まれるため,その後に空白を 書 い てはいけない。 #compdef タグは後述する compdef 関数で処 理される。 compdef関数は補完用関数名を明示的に指定する必要 があるが,タグの方は暗黙のうちに決められるという点が異って いる。 どのような文脈で呼ばれる関数が定義されるかのコンテクスト指 定 は 下記のいずれか: (The special contexts for which com- pletion functions can be defined are:) -array-value- 配列への代入時の右辺の位置 (`foo=(...)') -brace-parameter- 中括弧内での変数名の展開 (`${...}') -assign-parameter- 変数代入時の変数名(`='の左側) -command- コマンド位置での単語 -condition- 条件式 (`[[...]]') 内の単語 -default- 他の補完が定義されていないときのデフォルトの補完 -equal- イコール記号で始まる単語 zsh 4.3.2 March 2, 2006 6 ZSHCOMPSYS(1) ZSHCOMPSYS(1) -first- すべての補完に先だって呼ばれる。呼ばれる関数では そ の 後本来呼ばれる補完機能をキャンセルするための変数 _compskip に値を設定できる。意味ある値は,all: その 後 の補完機能は一切呼ばない, patterns という文字列 を含む文字列: パターン補完関数(訳注: なに そ れ???) を 呼 ば な い,default と いう文字列を含む文字列: `-default-' コンテクスト用の補完関数を呼ばない(その コマンド用の補完関数は呼ぶ),のいずれかである。 -math- `((...))' の内部のような数式コンテクスト -parameter- 変数名展開(`$...') -redirect- リダイレクション記号の後の単語 -subscript- 変数の添字の中味. -tilde- `~' 記号の後でスラッシュより前の単語 -value- 代入の右側 上記のどのコンテクストにもデフォルトの補完関数が用意されて いて,それらはコンテクスト名の前に _ を付けた名前になっ て い る。 たとえば, `-tilde-' 用のデフォルト関数は `_tilde' である(□)。 -redirect- と -value- コンテクストには追加で,コンテクスト 依存の情報を指定できる(内部的には _dispatch 関数で処理され る)。追加情報はカンマで区切って指定する。 -redirect- コンテ ク ス ト で は, 追 加 情 報 は `-redi- rect-,op,command' の形式で指定する。ここで op はリダイレク ション記号,command はそのコマンドラインに書かれたコマンド である。コマンドラインにコマンドが書かれていない状態の指定 は command 欄は空となる。訳 注: command の 部 分 に は, `cmd=service' という記述も書ける。 -value- コンテクストの追加情報は `-value-,name,command' と いう形式で指定する。ここで name は変数名である。もし連想配 列の要素で補完を行なう場合,例えば `assoc=(key ' のと き, name は `name-key' に展開される。また,`make CFLAGS=' ま でタイプして補完した場合などは, command の部分がそのコ マンド(つまり make)になり,それ以外の場合は空になる(□)。 このコンテクスト追加情報は,すべて厳密に決めたものからだん だん緩いコンテクストへと順次試されるので,必ずしもすべて厳 密に決めたコンテクスト追加情報を与えておく必要はない。要す る にたとえば, `foo=' という補完を行なうとき,その補 zsh 4.3.2 March 2, 2006 7 ZSHCOMPSYS(1) ZSHCOMPSYS(1) 完を受け持つ _value という関数はまず `-value-,foo,' という コンテクストを調べる(最後のカンマの右側は command が空とい う こ と を 意 味 し て い る)。 続 い て `-value-,foo,-default-',`-value-,-default-,-default-' と いう順番にそのコンテクストでの補完が定義されているかを調べ て行く。 例(1): compdef '_files -g "*.log"' '-redirect-,2>,-default-' `2> ' という文字列の後では,とくにそのコマンド用の補 完が定義されていないコマンドのときには `*.log' にマッチ す るファイル名を補う。 例(2): compdef _foo -value-,-default-,-default- 変 数 への代入で,とくに指定のない場合は _foo 関数が補完す る。通常は _value 関数がその処理をしている。 上記例(1)と同じルールはスタイル(後述)を用いて以下のよう に も指定できる。 zstyle ':completion:*:*:-redirect-,2>,*:*' file-patterns '*.log' zstyle コマンドがスタイルを定義するものである(□)。 Functions 以下の関数群は compinit 呼出しにより定義される。 compdef [ -an ] function names... [ -[pP] patterns... [ -N names... ] ] compdef -d names... compdef -k [ -an ] function style key-sequences... compdef -K [ -an ] function name style key-sequences ... 第1の 書式は,指定したコンテクスト(#compdef記法のと きと同様の指定)のときの補完に function 関数を呼ぶこ とを定義する。 や はり #compdef 記法のときと同様引数は, `cmd=ser- vice' のようにも書ける。ただしその場合既に #compdef で 別の `cmd1=service' が定義されていなければならな い(訳注: $serviceで挙動を変えるような関数になってい ないといきなり `cmd=service' で別名定義しても挙動が 怪しいから)。 引数の function には関数でなく,シェルの文を含む 文 字 列を書くこともできる。その文字列は補完単語群を生 成するため内部コマンド eval で評価される。これ は, 単 純 が ゆえいちいち関数を定義したくない場合に便利 で,たとえば foo コマンドの引数として単に `.h' ファ zsh 4.3.2 March 2, 2006 8 ZSHCOMPSYS(1) ZSHCOMPSYS(1) イルだけを補完させたいのであれば, compdef '_files -g "*.h"' foo とすればよい(訳注: _files関数はファイルの補完単語を 生成する既定の関数)。 -n オプションは,そのコマンドやコンテクスト用に既に 補 完が定義されている場合に上書き設定しないことを指 示する。 -d オプションはコマンドやコンテクスト用の補完定義を 削除する。 #compdef のときと同様,names の部分には -p, -P and -N オプションを指定できる(意味も #compdef のとき と 同じ(パターン指定の切り替え)□)。 パ タ ー ン コ ン テ クストで呼ばれる関数では,変数 $_compskip に値を設定してその他の補完関数が呼ばれる か を制御できる。 `patterns' という文字列を含む文字 列を指定するとパターン関数(訳注: って何???)が呼ばれ なくなり, `all' という文字列を含む文字列を指定する と他の関数が全く呼ばれなくなる。 -k と -K オプションの書式は #compdef のときと同じ。 明 示 的 に 関数を指定するかどうかの違い(訳注: 要実 験)。 どの書式でも適用可能なオプション -a は function を オートロード化する。 autoload -U function と等価。 compdef 関数を用いて,既存の補完関数を新しいコマンドに適用 させることもできる。たとえは, compdef _pids foo とすると,foo というコマンドの引数補完で _pids 関数を呼 び プロセスIDを補完させられるようになる。 ちなみに,後述する _gnu_generic 関数は `--help' オプション を受け付けるコマンドの補完をある程度自動的に行なう(□)。 CONFIGURATION この節ではまず補完システムの動き方の概要を述べ,続いてどの タイミングでどう補完単語を生成させるかをユーザが設定する方 法について詳しく説明していく。 概要 コマンドラインのどこかで呼び出された補完機能は,最初にコン テ ク ス ト を 調べる。コマンドの単語(たとえば `grep' なの か,`zsh なのか),カーソル位置の単語が引数に見なされるよう zsh 4.3.2 March 2, 2006 9 ZSHCOMPSYS(1) ZSHCOMPSYS(1) な オ プション(たとえば zsh の `-o' オプションはシェルオプ ションを引数に取る) などなど。 こうしたコンテクスト情報はコロンで区切られた複数のフィール ドを持つ文字列に圧縮される。以後コンテクストと言ったらその 文字列で表現する。コンテクストはem(スタイル)というコンテク ス ト に影響を受けるオプションを探すために用いられ,それに よって補完システムを設定する(訳注: うーん漠然としすぎ じゃ ん)。 検索に使われるコンテクストは,同じ補完システムを呼ぶ 場合でも様々な値に変わる(△)。 コンテクストを表す文字列は,先頭にあるコロン文字に続けて常 に決まったフィールドを持つ以下のようなものである。 :completion:function:completer:command:argum ent:tag. 各フィールドの意味は以下のとおり。 o completion という文字列そのもの(□): o function: 通 常 の補完システム経由でなく,名前つき ウィジェットから補完が呼ばれた場合の関数名。たい て い は 空 だ が,predict-on のような特殊ウィジェット や,zshのソースディレクトリの Widget ディレクトリに ある関数によってなんらかの値がセットされる。 o completer: 稼動中のコンプリータで,関数名の先頭のア ンダースコアをとり,途中にあるアンダースコアをハ イ フ ンに変えた名前。コンプリータはどのように補完する かを統轄するもので,もっとも単純な `complete' を 始 め, 綴り修正,その後のコンプリータの挙動を変えるた めのものなどいくつかある。「Control Functions」の節 参照。 o command ま たは -context-: #compdef タグや compdef のところで登場したもの。サブコマンドを持つコマン ド の 補完のときには,このフィールドにコマンド名とサブ コマンド名をハイフンで繋いだものがセットされる。 た とえば,cvs の add サブコマンドの補完を行なうときに は,このフィールドが cvs-add になる。 o argument: どのコマンドライン,オプション引数の補 完 をしているのかを示す文字列。コマンドの(オプション引 数でない) n番目の引数ならば, argument-n に,optと い うオプションの n 番目の引数ならば, option-opt-n となる。ただし,コマンドラインが標準的なUnix流オ プ ショ ン・引数表記ルールで解析される場合のみ有効で, これがセットされない場合も少なくない(□)。 zsh 4.3.2 March 2, 2006 10 ZSHCOMPSYS(1) ZSHCOMPSYS(1) o tag: マッチさせる対象物の種別を区別させるために使う もので,詳細は次に挙げる例で説明する(□□)。 コ ンテクストは,補完機能が働く入口のところで :completion: (と必要なら関数名var(function))だけが足された状態 か ら 始 まって,各種関数が呼ばれる毎にどんどん構築されていく。そう してコンプリータが completer 要素を足し,コンテクスト補 完 が add と argument オプションを足し,最後に,どういう種類 の単語を補完したいのかが判明した時点で tag が足される。 一例を挙げる。 :completion::complete:dvips:option-o-1:files というコンテクストは,dvips コマンドの -o オ プ ショ ン の 第1引 数 で は通常(ファイル)補完を試みることを示している。 よって, dvips -o ... というコマンドラインでの補完関数はファイル名を生成する。 与えられたコンテクストにおいてどんな種類の補完を実行できる か は,上の例で出てきた files を始めとする「タグ」という文 字列で表現される。どの補完関数も任意のタグ名を使って構わな いが,一般的なものはあらかじめ決められている(一覧を後述)。 ?????????????????????????????ここは削ってよい箇所 通常補完機能は,補完関数から渡された順番ですべてのタグに対 し て試される。この順番は tag-order スタイルで変更できる。 補完は渡されたタグを渡された順番に行なうだけに 限 定 で き る(△)。 実際に,どういうコンテクストでどういうタグの補完をさせるか を知るためのキー割り当て可能な内部コマンド _complete_help を使って見ることができる。(訳注: _complete_help はデフォル トで ^Xh に割り当てられているので,これを `dvips -o ' まで 入 力 し た ところでタイプしてみるとよい。) これを用いると tag-order やその他のスタイルの詳細が分かる。後述する`Bind- able Command'の節参照。 「スタイル」とはどのようにマッチするものを生成するかを決定 する,シェルオプションをより一層強力にしたようなもので,文 字列で表される値を何個でも持たせられる。スタイルは内部コマ ンドの zstyle (zshmodules(1) 参照) で変更できる。 適合するスタイルを探すとき,補完システムはタグ名を含んだ完 全なコンテクスト名を利用する。従って,スタイルの値を探す手 順は2つで構成される。 (1) コンテクスト(パターンで書くの も 可),(2) ス タ イル名そのもの(正確に与える)。訳注: えええ え??? When looking up styles the 補完システム uses full context names, including the tag. Looking up the value of a style therefore consists of two things: the context, zsh 4.3.2 March 2, 2006 11 ZSHCOMPSYS(1) ZSHCOMPSYS(1) which may be matched as a pattern, and the name of the style itself, which must be given exactly. たとえば,多くの補完関数はマッチす る 単 語 群 を 一 覧 表 示(list-choices□)する方法として,簡素バージョン,お節介バ ージョンの2つを持っていて,どちらを選ぶかは verbose スタイ ルの値で変更できるようになっている。そういう風に作ってある 補完関数すべてでお節介バージョンを選びたければ, zstyle ':completion:*' verbose yes を初期化ファイル(おそらく .zshrc) に入れるとよい。この文は 補完システム(completion)内のすべて(*)のコンテクストの ver- bose スタイルに yes をセットしている。実際にはすべて で な く,* よりも限定的に設定しているスタイル指定にマッチするコ ンテクストであればそちらが使用される。補完システム以外に影 響 を与えるといけないので,パターンとしては `*' だけでなく `:completion:*' を与えるべきである(□)。 ちなみに,compinstall を使って多くの汎用スタイルを設定する ことができる。 style の 使用をより限定的に指定する例として,内部コマンド kill の補完を示す。この補完では verbose スタイルがセットさ れ ていると (マッチする単語の一覧表示のときに□),ジョブの テキストとプロセスのコマンドラインをすべて出力し,スタイル が オフのときはジョブ番号とPIDのみを出力する。スタイルをオ フにしたい場合は, zstyle ':completion:*:*:kill:*' verbose no とする。もし,もっと限定的にしたいのであ れ ば `jobs' か `processes' タ グ を 明示的に指定する。ジョブに関してだけ verbose スタイルをオフにしたければ次のようにすればよい。 zstyle ':completion:*:*:kill:*:jobs' verbose no zstyle の -e オプションを用いると,補完関数に関数的な文 を 直接指定できる(□)。 zstyle -e ':completion:*' hosts 'reply=($myhosts)' こ れは,ホスト名補完が必要なときに hosts スタイルの値を変 数 myhosts から取得させる。もし myhosts の値が変動するなら 有用かもしれない。他の有用な例については後述する file-list スタイルを参照。ただし,-eオプションは速度低下の恐れがある の で menu や list-rows-first スタイルと組み合わせない方が よい。 マッチするスタイル定義が複数あるような場合どれが選ばれるか は, zstyleでそれらを定義した順番ではなく,どちらがより限 定的なルールで書かれているかによって決まる。たとえば,リテ ラ ル 文 字 列はパターンを使用したものより優先されるので, `:completion::complete:foo' は, `:completion::complete:*' zsh 4.3.2 March 2, 2006 12 ZSHCOMPSYS(1) ZSHCOMPSYS(1) よりも限定的と見なされる。また,パターンを用いているものど うしでは,より長い(詳細な)パターンを使っているもののほうが 短い(大雑把な)パターンよりも優先される(□)。 スタイル名は,タグ名と同様各補完関数で任意に決められるが, これもまた既定のものがあるので次とその次の節で一覧を示す。 標準タグ 下記一覧のうちいくつかは,特殊なスタイルを探すときに使われ るだけで,マッチする単語の種別を示すものではない。 accounts users-hosts スタイルを探すために用いられる(△???) all-expansions _expand コンプリータが,1つの文字列にマッチするもの すべてを挿入するときに用いられる all-files すべてのファイル名(△???)(下記 globbed-files タグも 参照) arguments コマンドに対する引数 arrays 配列変数名 association-keys 連想配列のキー(連想配列変数の添字を補完する場合に使 われる) bookmarks ブッ ク マークを補完するときに使われる (e.g. URL や (zftp) モジュール) builtins 内部コマンドの名前 characters 1文字 (stty コマンドで制御文字を入力する部分や, 開 き大括弧の後でキャラクタクラスを書く場合など) colormapids XのカラーマップID colors 色の名前 commands 外部コマンドの名前で,cvsのような複雑なコマンドの補 完でサブコマンド一覧を得るためなどに用いる contexts 内部コマンド zstyle に与えるコンテクスト文字列 zsh 4.3.2 March 2, 2006 13 ZSHCOMPSYS(1) ZSHCOMPSYS(1) corrections _approximate と _correct コンプリータが,適当な修正 のために使う。 cursors Xプログラムのカーソル名 default デ フォルトのタグ: 別のより限定的なタグが有効な場合 のデフォルトを与えるために使われる(△???)。このタグ は コンテクスト文字列の function フィールドがセット されている場合のみ有効。 used in some contexts to provide a way of supplying a default when more spe- cific tags are also valid. Note that this tag is used when only the function field of the context name is set descriptions マッチの種別を記述するため format スタイルの値を 調 べるときに使う devices デバイスファイルの名前 directories ディレクトリ名 directory-stack ディレクトリスタックのエントリ displays Xのディスプレイ名 domains ネットワークドメイン名 expansions コ マンドライン上の1語を展開した結果生ずる語を1個ず つ順番に出すためのタグで,_expandコンプリータによっ て使われる。 extensions Xサーバのエクステンション file-descriptors ファイルディスクリプタ files ファ イル名補完で用いられる汎用ファイル名マッチのタ グ fonts Xのフォント名 fstypes mountコマンドなどで用いるファイルシステムタイプの名 zsh 4.3.2 March 2, 2006 14 ZSHCOMPSYS(1) ZSHCOMPSYS(1) 前 functions 関 数名 -- 通常はシェル関数だが特定のコマンドは別の 種類の関数を把握する globbed-files パターンマッチで生成されるファイル名 groups グループ名 history-words ヒストリリストにある単語 hosts ホスト名 indexes 配列の添字 jobs ジョブ名(内部コマンド`jobsで得られるもの) interfaces ネットワークインタフェース名 keymaps zshのキーマップ名 keysyms Xのkeysyms libraries システムライブラリ名 limits リソースリミット local-directories cd コマンド等の引数補完時の,カレントディレクトリに あるサブディレクトリ (path-directoriesも参照) manuals manにあるマニュアル名 mailboxes メイルフォルダ名 maps マップ名(NISマップなど) messages メッ セージ用の format スタイルを調べるときに使われ る modifiers Xのモディファイア名(訳 注: Shift, Control, Mod1, Mod2, ...) zsh 4.3.2 March 2, 2006 15 ZSHCOMPSYS(1) ZSHCOMPSYS(1) modules モジュール名 (zsh モジュール) my-accounts users-hosts スタイルを調べるときに使われる named-directories 名前つきディレクトリ names すべての種類の名前 newsgroups USENET のニュースグループ nicknames NISマッ プのニックネーム(訳注: マップ名tt(passwd)は ニックネーム) options コマンドオプション original _approximate,_correct,_expand コンプリータが最 初 の文字列をマッチとして提示するときに使われる other-accounts users-hosts スタイルを調べるときに使われる packages でびあんのぱっけーじ parameters 変数名 path-directories cdな どのディレクトリ移動系内部コマンドの引数を補完 するときに, cdpath変数に登録されたディレクトリ群か らみつかるサブディレクトリ (local-directoriesと比較 せよ) paths expand,ambiguous,special-dirs スタイルの値を調 べ るときに使われる(△???) pods Perl pods(ドキュメントファイル) ports ネットワークポート prefixes プレフィクス(URLのものなど) printers プリントキューの名前 zsh 4.3.2 March 2, 2006 16 ZSHCOMPSYS(1) ZSHCOMPSYS(1) processes プロセスID processes-names killallコマンドで指定するプロセス名を生成するときに command スタイルを調べるときに使われる sequences シーケンス(mhのシーケンス(連番)) sessions zftp モジュールの「セッション」 signals シグナル名 strings 文字列(cdコマンドでカレントディレクトリの一部置換を 行なうときなど) styles 内部コマンドtt(zstyle)用のスタイル名 suffixes ファイル名の拡張子 tags タグ名 (e.g. rpm タグ) targets Makefileのターゲット名 time-zones タイムゾーン types 種 別を表すもの何でも(たとえば xhost コマンドで指定 するアドレスタイプなど) urls URL補完時に urls と local スタイルを参照するのに 使 われる users ユーザ名 values 指 定したリストにある複数の値の候補から必ずひとつだ けが補完されるような補完候補の集合 variant _pick_variant 関数が,インストールされているコマ ン ド の種類を決めるときに実際に起動するコマンドを決め るときに参照される。訳注: このタグに対する command ス タイルの値にコマンド名が設定されていたらそれを起 動する(_call_program関数の役目)。 visuals X visuals(訳注: ってなに???) zsh 4.3.2 March 2, 2006 17 ZSHCOMPSYS(1) ZSHCOMPSYS(1) warnings format スタイルから警告を探すために使われる widgets zshのウィジェット名 windows X のウィンドウID zsh-options zshのシェルオプション 標準スタイル これから説明する「スタイル」のうちいくつかは,設定すべき値 が真偽値となっている。 `true',`on',`yes',`1' という文字 列はどれも `true'(真)を 意 味 す る も の と し て 使 え, `false',`off',`no',`0' と い う 文 字 列 は ど れ も `false'(偽)を意味するものとして使える。それ以外の値を設 定 したときの挙動は,とくにことわりのない限り未定義となってい る。値がセットされていないときの値は true か false のい ず れかである。 また以下のスタイルのうちいくつかは,マッチの種別に応じて決 まっているタグ群にたいして照合され,それでみつからなければ デフォルトタグに対するそのスタイルが参照される。 もっ と も 身 近 な ス タ イ ル に menu, list-colors, list-packed, last-promoptがある(□)。 defaultタグをテストするとき,コンテクストの function フィ ールドだけがセットされる。それによってデフォルトタグを使う ようなスタイルは次のようなコンテクスト定義で書くこと に な る。 zstyle ':completion:*:default' menu ... accept-exact 現 在のコンテキスト用のタグにくわえてデフォルトタグ に対しても調べられる。この値が `true' なら,コマ ン ド ライン上の単語が補完候補のどれかに完全一致してい たらそれを確定したものと見なす(たとえ,その単語で補 完 さ れ る可能性を持つ候補がものが他にあったとして も)。 パス名補完のとき(そのときのタグは `paths'),この ス タ イルには真偽値に加えて任意個のパターンを持たせて よく,その場合与えたパターンのどれかにマッチする パ ス がコマンドライン上にタイプされていたらそれを即確 定する。その場合,確定されるパス名の後ろにさらに 多 く の パ スを入力していて,確定したあとにマッチする ファイルがないとしても確定する。 訳注: わからんね。実例で示す。 less /u/li/ で補完す zsh 4.3.2 March 2, 2006 18 ZSHCOMPSYS(1) ZSHCOMPSYS(1) ると /u*/li*/ で探すので,/usr/lib,/usr/libexec が 両方候補に入る。しかし /usr/lib/ としっかり打ってか ら 補完したなら libexec の方は入れずに /usr/lib/ で 確定させたいなら zstyle ':completion:*:*:less:*' \ accept-exact /usr/lib としておく。ただしこうすると,libexec のほうにあ る ファ イルを補完させたくて /usr/lib/postf と打ったと しても /usr/lib の部分が確定されてしまっているの で アウト。訳注終わり。 このスタイルは _expand コンプリータにもつかえ,その 場合チルダか変数名で始まるものを展開するかどうか を 決める。たとえば,変数 foo と foobar が定義されてい たとして, `$foo' という単語が(その値に)展開され る の は accept-exact が true の場合だけで,そうでない ときは $foo を $foobar に展開する可能性が残される。 また,もし値を `continue' にしておけば, _expand は 展開結果をマッチとして追加し,補完システムに継続 を 許可する。 訳注: _expand を呼ぶようにしてから実験。 zstyle ':completion:*' completer _expand _complete zstyle ':completion::expand:*' substitute true foo='This is foo' foobar='FOOBAR' echo $foo[Tab] zstyle ':completion::expand:*' accept-exact continue これは `$foo' と `$foobar' を選ばせる。 zstyle ':completion::expand:*' accept-exact true これは `$foo' を即確定して展開して完了。 zstyle ':completion::expand:*' accept-exact continue これは `$foo' を展開したものに加え, `$foobar' と最 初の `$foo' を候補としてメニュー補完する。 訳注終わり。 add-space _expand コンプリータによって 使 わ れ る。 こ れ が true(デ フォルト) のとき,展開の直後にスペース(語が ディレクトリ名ならスラッシュ)が挿入される。また,値 と して `file' を代入しておくとコンプリータは実在す るファイルにのみスペースを追加する。 true, `file' い ずれかを持たせる場合,`subst' を組み合わせること ができ,その場合コン プ リ ー タ は, `$(...)' や `${...}' 置換の展開結果には空白を足さない。 (訳注: 理屈は分かるがこれもそうならんぞ??? zsh 4.3.2 March 2, 2006 19 ZSHCOMPSYS(1) ZSHCOMPSYS(1) zstyle ':completion:*' add-space false しても,必ず空白が入るのは何故だ。) _prefix コ ン プリータはこの値を真偽値としてのみ使 い,サフィクスの前に空白をいれるかどうかだ け 決 め る。 ambiguous 補完後の後に / などを補うものがある場合,メニュー補 完では,複数マッチがあったとしてもとりあえず 1つ 目 のマッチに / を付けて提示するが,このスタイルをセッ トすると複数マッチがある場合は一意に決まらない部 分 に カ ー ソ ル を戻して提示する(□)。このスタイルは paths タグで常に参照される。 assign-list イコール記号の後の値代入の部分で,通常は1つのファイ ル 名だけ補完するが,このスタイルがセットされている 場合はPATH変数のようにコロン区切りの後を別のファ イ ル 名とみなして補完する。スタイルの値はそう補完すべ き変数にマッチするパターンのリスト。 デフォルトでは値にコロンが既に含まれていればONに な る。 ということで,これを明示的に指定しなくても快適 じゃん。 auto-description 1つの引数を取るオプション自身の説明文字列が補完定義 に 与えられていないとき,そのオプションの引数の方に 説明文字列があればそれオプション自身の説明として 使 う。 スタイルの値に含ませる %d がその文字列に置き換 えられる(□)。 avoid-completer _all_matches コンプリータが使用する。現在挿入すべき 単 語を生成するときに,使わないコンプリータのリスト を列挙する(□)。 デフォルト値は `_expand _old_list _correct _approx- imate' で全マッチ単語挿入で要らなさそうなものを生成 するコンプリータを入れておく(□)。 cache-path 補完単語のキャッシュを保存するパス名を指定する。 デ フォ ル トは $ZDOTDIRが定義されている場合は `$ZDOT- DIR/.zcompcache', そ う で な い 場 合 は `$HOME/.zcompcache'。 ただし, use-cache スタイルが セットされていないときは使われない。 cache-policy キャッシュの再構築をいつするかを決める関数 を 決 め る。後述する _cache_invalid の項を参照。 zsh 4.3.2 March 2, 2006 20 ZSHCOMPSYS(1) ZSHCOMPSYS(1) call-command make,ant といった,マッチ単語生成に該当コマンドを 直接呼ぶようなもののときに,遅くなったり,makeが 実 際 に仕事を始めちゃったりする問題を避けるために使わ れる。trueであれば,実際のコマンドを呼んでマッチ 単 語を生成する(場合もある□)。デフォルトは false。 command 外 部コマンドを呼んでマッチ単語を生成するような多く の補完で使われ,呼ぶコマンドを変えるために 使 わ れ る。値を `-' で始めるとデフォルトのコマンドラインの 前に補われる(builtinや command を明示的に前置させた いときに便利)。 た とえば,kill でPIDを補うときの一覧はpsを呼んで得 ているがこのスタイルの値に ps t$TTY などを入れて お け ば, 現在のTTYの PIDだけに限定できたりする(□)。 PIDの補完で言えば,実際の補完関数がPID部分を抽出 で き るよう出力が関数の期待どおりに得られるよう注意が 必要(□)。 コマンドを呼ぶのでそれが短い時間で確実に終わるよ う にすることにも注意が必要。訳注: ものすごく変えた。 command-path 補 完 の ときに用いるコマンド検索の値。デフォルトは path 変数の値。 commands OSの初期化スクリプト(/etc/init.d や /etc/rc.d な ど に あるもの) のサブコマンドを補完する関数が使う。そ れらのスクリプトに与えるサブコマンドの一覧を指定 す る。デフォルトは `start' と `stop'(□)。 complete _expand_alias 関数を割り当て可能コマンド(デフォルト で ^Xa) として呼び出したときに使われる。入力した 単 語に完全にマッチするエイリアスがなかったときに,(続 けてタイプすると)マッチするもの一覧を出す(□)。 completer コンプリータとして用いる関数を(文字列で)列挙す る。 指 定 で き るコンプリータは後述する `Control Func- tions' 節参照。 各文字列は,コンプリ ー タ 関 数, ま た は `func- tion:name' という書式が許されている。前者の場合は, コンテクストの completer フィールドは,その関数の先 頭のアンダースコアを取り,残りのアンダースコア(もし あれば)をすべてハイフンに変えた文字列に変えた名前に なる。後者の場合,function は呼ぶべきコンプリータの 名前となるが,呼ばれるときのコンテク ス ト の com- pleter フィールドは nameとなる。ただし,name がハイ フンで始まるときはその前にコンプリータ関数本来の コ zsh 4.3.2 March 2, 2006 21 ZSHCOMPSYS(1) ZSHCOMPSYS(1) ンテクスト名が追加される(□)。つまり, zstyle ':completion:*' completer _complete _complete:-foo と いうコンプリータ登録の場合,補完システムは _com- plete コンプリータを2回呼ぶことになり,1回目はコ ン テクストの completer フィールド名 complete で, 2回 目はフィールド名 complete-foo で呼ばれる。 同じコンプリータを2度以上使うなら `functions:name' の 書式を使って回毎に違うコンテクスト名で呼ばせなけ れば意味がない(_ignored と _prefix コンプリータに関 してはこの限りでない)。 こ の スタイルのデフォルト値は `_complete _ignored' で,「補完」のみを,1回目は ignored-patterns スタイ ルと $fignore 変数の値を考慮して,2回目はそれなしで 行なう。 condition _list コンプリータがマッチするものの挿入を無条件 で 遅 れ さ せ る か 決 め る ために使う。デフォルトは `true'(???)。 disabled _expand_alias コンプリータとそのキー割り当て可能 コ マンドが使い,`true' の場合は無効化されたエイリアス も補完する。デフォルトは `false'。 disable-stat _cvs 関数がタグなしでこの値を用いて,相応の場所にあ る 修正ファイルを生成するために zsh/stat モジュール を使うかどうかを決める。`trule' ならモジュールを 使 わず ls コマンドを使う。 domains 補 完に使うネットワークドメイン名のリスト。セットさ れていない場合は /etc/resolv.conf ファイルから取 得 される。 expand こ のスタイルは,パス名のように複数の部分から成って いる文字列を補完するときに使われる。 この値のうち1つが `prefix' という文字列であれ ば(完 全一致),後半部分が補完できなくても前半部分が補完で きるならできるだけ展 開 さ れ る。 訳 注: た と え ば,/u/i/hoge を補完するとき /u*/i*/hoge* がなくて も /u*/i* で補完できるなら /usr/include/hoge に展開 する。 こ の値のうち1つが `suffix' という文字列であれば(完 全一致),途中に一意に定まらない部分があったと し て も, その後ろにある部分にマッチする名前が足される。 これにより結果の文字列は,一意に定まる前の最長の 文 zsh 4.3.2 March 2, 2006 22 ZSHCOMPSYS(1) ZSHCOMPSYS(1) 字 列となる。このとき,メニュー補完を用いてマッチす るものすべてを循環させることもできる。訳 注: /home 以下に yuka,yukita,yuuji ディレクトリがあり,それ ぞれに .z で始まるファイルとして .zshenv,.zshrc が あ るとする。このときに /h/y/.z で complete-word す ると, suffix でないときは /home/yu までが補完さ れ る が, suffix の と き は .z の 部分も頑張って /home/yu/.zsh に展開される。 fake どのコンテクストでも使えるスタイル。指定したコン テ ク ストで必ず追加で補完対象に含まれるような文字列を 指定する。指定する値は `value:description' の形式で 記述し,コロンの後ろに説明文字列を書く(コロンを含め て省略可能)。説明文字列にコロンを入れたいときはバッ ク スラッシュでクォートする。説明文字列は補完リスト 表示のときに出される。 どこでも呼ばれる可能性があるので,コンテクスト指 定 を 十分に限定的にすることが大切。ファイル名や変数名 で似たような追加候補を入れたい と き に つ い て は fake-files や fake-parameters 参照のこと。訳注: と にかく決まった単語を決まったコマンドの補完で使い た いときに便利なスタイル。 fake-always fake スタイルと同じ働きだが,ignored-patterns スタ イルを適用しない点だけ異なる。無視するパタ ー ン を `*' にセットすることでマッチ単語群を完全にオーバー ライドすることができる。 This works identically to the fake style except that the ignored-patterns style is not applied to it. This makes it possible to override a set of matches completely by setting the ignored patterns to `*'. 以下に,単に分割タグのように表示のためだけに用い る 勝 手なデータをもつ任意のタグを補わせる方法を示す。 この例では,tag-order スタイルを使って,標準コン プ リ ータの complete が cd コマンドの引数を補完すると きに named-directories タグを2回に分けて呼 ん で い る。 named-directories-normal タ グは普通に候補を持つが named-directories-mine タグは自分のおきまりのディレ クトリ群だけを候補に持つようにしている。 named-directories-mine contains a fixed set of directories. This has the effect of adding the match group `extra directories' with the given com- pletions. zstyle ':completion::complete:cd:*' tag-order \ 'named-directories:-mine:extra\ directories named-directories:-normal:named\ directories *' zstyle ':completion::complete:cd:*:named-directories-mine' \ zsh 4.3.2 March 2, 2006 23 ZSHCOMPSYS(1) ZSHCOMPSYS(1) fake-always mydir1 mydir2 zstyle ':completion::complete:cd:*:named-directories-mine' \ ignored-patterns '*' 訳注: んでもこれを fake-always から fake にしても違 いが分からないのだが…… fake-files こ のスタイルはファイルの補完に使われ,タグなしで参 照される(△)。値は `dir:names...' の形式で指定 し, names(複数ある場合は空白で区切る)という名前のファイ ル(群)が dir に(実在しなくても)あるものして候補に含 める。 こ れはたとえばオートマウントディレクトリ(□)のよう にアクセスするまで一覧に出てこないパ ス 名 の 補 完 や,xビッ トだけあってrビットがないディレクトリにあ る読みだし可能ファイルの名前を補完したいと き に 便 利。 訳 注: たとえば,a2ps や psnup の結果をほとんどの場 合 /tmp/hoge.ps,/tmp/hoge2.ps,/tmp/hoge3.ps, … に リ ダ イレクトで書き出しているような場合,既存の ファイルがなくても > のあとに /tmp/hoge.ps を補完さ せたい。そのようなときは, zstyle ':completion::*:-redirect-,>,(a2ps|psnup):*' \ fake-files "/tmp:hoge.ps `echo hoge{2..9}.ps`" と設定しておくと,a2ps foo > の後ろで /tmp/hoge.ps などが補完候補となる。 fake-parameters 変数名を補完する関数で使われる。値には,まだ未定 義 で も補完候補に入れる変数名を列挙する。指定する名前 にはコロンに続け て 変 数 の 型(`scalar',`array', `integer'等)を 補助的に追記できる。型を与えておくと その型が要求されているコンテクストでのみその変数 が 補完される。型指定のない変数は常に補完される。 file-list こ のスタイルは,標準の機構を用いて得られた補完候補 ファイル群を一覧表示するときに,ls -lに似たロングリ ス ト出力とするかどうかを決める。この機能はファイル の情報を得るためにシェルモジュール zsh/stat を使 用 す る。このモジュールは外部コマンドの stat より優先 されることになるが,それを避けたい場合は zmodload -i zsh/stat disable stat と初期化ファイルに書いておくとよい。 このスタイルに設定できる値は,true(また は `all'): zsh 4.3.2 March 2, 2006 24 ZSHCOMPSYS(1) ZSHCOMPSYS(1) あ らゆる状況でロングフォーマットで出す, `insert': ファイル名を挿入するとき, `list': ファイル名を挿入 せずに一覧を出すとき,のいずれか(△どう使いわけるの かいまいち)。 厳密には(□),この値は上記の値のどれかに,オプ ショ ン で =num を付けたもの,を配列にしたものにしてよ い。 num は,ロングフォーマット表示にする場合の最大 マッチ数を表す。たとえば, zstyle ':completion:*' file-list list=20 insert=10 と すると,マッチするものが20個までなら一覧出力をロ ングフォーマットにし, 10個までなら挿入する(あい ま い補完の例のように一覧がallで出るようになってるもの と見なす(△何???))。また, zstyle -e ':completion:*' file-list '(( ${+NUMERIC} )) && reply=(true)' とすると,数引数を付けて呼び出した場合に常にロン グ フォ ーマット,そうでないときショートフォーマットが 使われる。 (訳注: △△ほんにわからん) file-patterns 標準ファイル名補完関数である _files が使用する。 こ のスタイルがセットされていない場合は,最大で3つのタ グ,`globbed-files',`directories',`all-files' が, _files の呼び主の求めているファイル種別に応じ て渡される。最 初 の2つ,`globbed-files',`directo- ries' は,通常いっしょに渡されて,サブディレクトリ 内のファイルを簡単に補完できるようにしている。 file-patterns スタイルは,デフォルトタグ(通常は使わ れない)の代わりのものを生み出すために使える(△□)。 このスタイル値は,`pattern:tag' という要素 の 集 合 で, 各要素は同じ形式の要素をスペースで区切って列挙 したものでも構わない(□)。 pattern はファイル名生成を行なうために使 わ れ る。 `%p' と書くとその部分が _files 関数に渡されたパター ン(群) に置き換えられる。パターンにコロン自身が含ま れ るときはバックスラッシュでエスケープする必要があ る。複数のパターンを書く必要があるときはそれらの パ タ ーン全体を確固で括って,その中にパターンをカンマ で区切って書けばよい。 tagの部分で指定されたタグ群は,_filesによって別のス タ イルを照合するときに渡される。別のパターンに同じ タグ値を指定したとき,そ れ ら は 同 時 に 渡 さ れ る(△)。`:tag' を省略したときは `files' タグが使わ れる。 tag 指定のさらに後ろにさらにコロンを付けて説明文 字 列 を追記することもできる。説明文字列を定義しておく zsh 4.3.2 March 2, 2006 25 ZSHCOMPSYS(1) ZSHCOMPSYS(1) と,補完関数のデフォルトの説明の代わり に, format ス タイルの `%d' に置き換えられる。説明文字列自身に `%d' を入れておくと,それは補完関数のデフォルトの説 明文字列に置き換えられる。 たとえば,rm コマンドの引数の補完で,最初はオブジェ クトファイルだけ補完を試み,マッチしない場合のみ す べてのファイルを補完したい場合は以下のようにする。 zstyle ':completion:*:*:rm:*' file-patterns \ '*.o:object-files' '%p:all-files' デ フォルトの補完機能の挙動,すなわち,パターンに位 置するものと, (パターンとは無関係の)ディレクトリを 最 初に,その後ですべてのファイルを提示する,という 挙動を,「最初にパターンにマッチするものだ け 提 示 し, そのあとでディレクトリとすべてのファイルを…」 と変えたい場合は zstyle ':completion:*' file-patterns \ '%p:globbed-files' '*(-/):directories' '*:all-files' と指定すればよい。 This works even where there is no special pattern: _files matches all files using the pattern `*' at the first step and stops when it sees this pattern. Note also it will never try a pattern more than once for a single completion attempt. 補完関数実行時には,EXTENDED_GLOB オプションが セッ ト されるので,パターン中に`#',`~' や `^' などがあ れば,それらは特別な働きをする。 file-sort 標準ファイル補完関数が,候補一覧表示の出力順を決 め る ためにこのスタイルをタグなしで使用する。メニュー 補完も同じ順番となる。設定できる値は, `size': ファ イ ルサイズでソート, `links': リンクカウントでソー ト, `modification'(`time' または `date'): 修正時刻 で ソ ー ト, `access': 最終アクセス時刻でソート, `inode'(`change'): inode情報更新時刻でソート,の ど れか。 上 記の値以外,またはセットされていないときはファイ ル名でソートし,値に `reverse' という文字列を含む場 合は逆順でソートする。 filter 訳注: 急いでるので飛ばします。 This is used by the LDAP plugin for e-mail address completion to specify the attributes to match against when filtering entries. So for example, if the style is set to `sn', matching is done against zsh 4.3.2 March 2, 2006 26 ZSHCOMPSYS(1) ZSHCOMPSYS(1) surnames. Standard LDAP filtering is used so nor- mal completion matching is bypassed. If this style is not set, the LDAP plugin is skipped. You may also need to set the command style to specify how to connect to your LDAP server. force-list 一 覧出力が普通なら抑制されるようなときでも,必ず一 覧出力を強制実行する。 たとえば,通常一覧出力はマッチするものが2個以上ある 場 合に出てくる (訳注: AUTOLIST オプションが有効(デ フォルト)の状態で complete-word した場合など)。この ス タイルを `always' にセットすると,たとえマッチす るものが1個であっても一覧出力する。スタイル値に整数 を 指 定 すると,マッチするものの個数がその数以上に なったときに,たとえそれらが同じ文字列を挿入する 場 合 でも一覧出力される(△訳注:それってどういうときな の???) In this case the list will be shown if there are at least that many matches, even if they would all insert the same string. このスタイルはデフォルトタグだけでなく,現在の補 完 で有効な各タグで確かめられる。 format descriptions タグに対してこのスタイルが設定されてい るとき,その値は一覧出力の上に表示される。値の文 字 列 中の `%d' は,マッチ対象に対する短い説明文に置き 換えられる。他に,`%B',`%S',`%{...%}' も使える。 現在の補完で有効なすべてのタグで確かめられ,その あ と で descriptions タグに対して確かめられる。これに より違う種類の補完対象には違う書式文字列を定義で き る。 また,もっと多くの `%' 記法が使えるコンプリータもあ り,その場合はそのコンプリータ関数の Note also that some completer functions define additional `%'-sequences. These are described for the com- pleter functions that make use of them. いくつかの補完関数では,messages タグに対するこのス タイル値を設定することで表示メッセージを変 更 で き る(その場合 `%d' は補完関数により出されるメッセージ に置換される)。 warnings タグに対するこのスタイル値は,マッチするも のがなかった場合に参照される。その場合,`%d' はマッ チが期待されたものに対する説明をスペースで区切っ て 並べたものに置き換えられる(△どういうとき??)。 `%D' は同じ説明をスペースではなく改行で区切って並べた も のに置き換えられる。 `%d' にprintf風の桁幅指定や,エスケープシーケンスが zsh 4.3.2 March 2, 2006 27 ZSHCOMPSYS(1) ZSHCOMPSYS(1) 使うこともできる。 zsh/zutil モジュールで定義されて い る 内 部 コマンドの zformat によって処理される。 zshmodules(1)参照. glob _expand コンプリータで使われる。この値が `true'(デ フォ ルト値) のときは直前の置換の結果に対してさらに グロッビングを試みる(substituteスタイルも 参 照)(△ □)。 global _expand_alias コンプリータとそのキー割り当て可能コ マンドが,グローバルエイリアスを展開するかどうか を 決める。デフォルトは `true'。 group-name 補 完システムでは別の種類のマッチ対象をグループごと に分けて一覧出力することができる。このスタイルを 用 い てタグごとに別々のグループ名を付けられる。たとえ ば,コマンドラインのコマンド位置で補完さ せ る と, シェ ル内部コマンド,外部コマンド,エイリアス,シェ ル関数, (代入のための)変数名,が有効な補完対象とし て 生成される。ここで,外部コマンドとシェル関数を候 補一覧表示で分けたい場合にはこうする: zstyle ':completion:*:*:-command-:*:commands' group-name commands zstyle ':completion:*:*:-command-:*:functions' group-name functions これで,同じタグを持つものが同じグループ内に表示 さ れる。 グ ループ名を持たないすべてのマッチ対象は -default- という名前のグループに入れられる(訳注: 次の文の下に あったがここに移動した)。 グ ループ名に空文字列を指定すると,マッチ対象のタグ 名がグループ名に使われる。したがって,すべての マッ チ種別を別々に表示させたいなら zstyle ':completion:*' group-name '' としておくとよい。 訳注: これを試すときには, zstyle ':completion:*:descriptions' format '%BCompleting%b %U%d%u' などとしておくと効果が分かりやすい。 group-order group-name スタイルと併せて使い,分類されたグループ の一覧出力での順番を指定する(補完そのものを決 め る tag-order と比較せよ□)。名前を持つグループは指定し た順番で表示され,その他のものは補完関数で定義さ れ た順番で表示される。 zsh 4.3.2 March 2, 2006 28 ZSHCOMPSYS(1) ZSHCOMPSYS(1) た と え ば,コマンド位置で補完したときに内部コマン ド,シェル関数,外部コマンドをその順番で一覧に出 し たいなら下記のようにする。 zstyle ':completion:*:*:-command-:*' group-order \ builtins functions commands groups UNIXの グ ル ープ名のリスト。セットされていなければ YPデータベース,または `/etc/group' から取 得 さ れ る。 hidden こ の 値 が `true' のときは,指定したコンテクストで マッチしたものは一覧表示されなくなる。ただし,そ の マッ チに対して format スタイルでセットされた説明文 は表示される。説明文も出さないようにするにはこの ス タイル値を `all' に設定する。 た だし,一覧表示が出されないだけで補完はされる。補 完対象からも外したいときは後述の tag-order スタイル をいじることで調整できる(□)。 hosts 補 完に現れるべきホスト名のリスト。この値をセットし ていない場合,ホスト名は `/etc/hosts' から取得さ れ る hosts-ports ホ スト名とネットワークポート番号を受け取るコマンド の引数補完で使用される。値は `host:port' の形式で指 定 する。有効なポートはホスト名の有無によって決めら れる。同じホストに複数のポートが現れてよい(△訳 注: どこで使われるか分からん。telnetは違うみたいだ)。 ignore-line こ のスタイルは現在の補完で有効なすべてのタグについ て調べられる。もし設定値が `true' の場合は,候補 対 象 のうち既にコマンドラインに入力されているものは除 外される。`current' の場合は現在入力中の単語に完 全 一致するものは補完候補から除外する (訳注: foo,foo- bar,foobaz があるとして, foo まで打ってか らTAB押 すなら,もう全部打っちゃった foo は補完されてもうれ しくない)。 `current-shown' は `current' とほぼ同じ だ が,入力中の単語にマッチするもの一覧が表示されて いる場合のみ完全一致する候補を除外する。 `other' は コ マンドラインにあるカーソル位置以外の単語を補完候 補から除外する。 ちなみに,accept-exact スタイルは,既に打ったものに 完 全 一 致するパスコンポーネントは確定,という意味 で,既に打ったものに完全一致するのは除外する `cur- rent' と `current-shown' はちょうどこれの逆みたいな 感じになっている(□)。 便利な局面が多いこのスタイル だ が,`:completion:*' の よ う な 広 範 囲 に及ぶコンテクストで `true' や zsh 4.3.2 March 2, 2006 29 ZSHCOMPSYS(1) ZSHCOMPSYS(1) `other' を設定するのはうれしくないだろう。 な ぜ な ら, たとえばあるコマンドに対して同じオプションを複 数回指定したいときに,2回以降が補完できなくなってし まうからである。 ignore-parents こ のスタイルはパス名補完を行なう関数からタグなしで 照合され,ディレクトリ名を補うときに,現在の単語 に 含 まれている場所やカレントディレクトリを除外するか を決める。設定できる値は下記の1つ,または2つ両方。 parent 入力中の単語に含まれるディレクトリは無 視 す る。 たとえば, foo/../ で補完するなら,すで に foo が含まれているのでこれを除外する。 pwd カレントディレクトリを除外する。たと え ば, ../ で補完するとき,カレントディレクトリ以外 のものを候補とする。 上記の値に加えて,さらに以下のどちらか,または両 方 を含めることもできる。 .. 補 完中の単語が `../' を含む場合のみ該当する ディレクトリを無視する。 directory 対象をディレクトリに限定して補完しているとき だけ該当ディレクトリを無視する。ディレクトリ に限定していないときは無視 し な い。 訳 注: zstyleや 補 完システムで,その引数を "*(-/)" で検索している場合のみ該当ディレクトリを無視 させる。例: zstyle ':completion:*:*:foo:*' \ ignore-parents pwd directory zstyle ':completion:*:*:foo:*' \ file-patterns '*(-/)' 2行目のあるなしで挙動が変わる。訳注終わり。 除 外 指 定 された値は,下記 ignored-patterns スタイルと同 様,_ignored コンプリータで候補として復活する(訳注: つまり 除外指定したものしかマッチするものがなければ復活して選ばれ る)。 ignored-patterns 補完対象から除外したいパターンのリスト。とはい え, こ れで指定したパターンにマッチする候補が完全に捨て られるわけではなく,それらを復 活 さ せ る た め に _ignored コンプリータを completer スタイルに追加し ておくこともできる。このスタイル は, シェ ル 変 数 $fignore の柔軟バージョンといえる。 補 完関数実行時には,EXTENDED_GLOB オプションがセッ zsh 4.3.2 March 2, 2006 30 ZSHCOMPSYS(1) ZSHCOMPSYS(1) トされるので,パターン中に`#',`~' や `^' などが あ れば,それらは特別な働きをする。 insert _all_matches コンプリータが,たんに別のマッチに一覧 を足すのではなく,マッチする単語すべてを挿入する か を決める。 訳注: 以下の例で。 zle -C all-matches complete-word _generic bindkey '^Xa' all-matches zstyle ':comple- tion:all-matches:*' completer _all_matches _com- plete zstyle ':completion:all-matches:*' insert true 訳注終わり。 insert-ids kill や wait 内部コマンドの引数などでプロセスIDを補 完するときに,コマンドの名前は適切なプロセスIDに 変 換 されうる。このとき,プロセス名が一意に定まらない と問題が起きる。 訳注: kill などの後ろにコマンド名を打ってTABを押 す と 補完関数は ps コマンドなどの出力からそのコマンド 名にマッチする PIDを引いて来て,一意に定まる前に す ぐ コ マンドライン上の単語をPID数値に書き換えてしま い,メニュー補完を始めて次 のTABキ ー で マッ チ す るPIDを循環させる。普段メニュー補完を使っていない人 は,マッチするものが最初に出てくると一意に決まっ た の かと思ってすぐリターンを押してしまいやすく,危険 である。この挙動はこのスタイル値が未定義 か,`menu' にセットされているものである。訳注終わり。 こ のスタイル値を `single' にすると,一意に定まるま ではコマンドライン上のコマンド名をPIDに書き換 え な い(□)。 それ以外の単語にしておくと,ユーザの入力が 対応するIDに共通なプレフィクスより長くなってから メ ニュー補完が始まる(訳注: どうもそうはならない感じだ なあ???)。 insert-tab この値が `true' のとき,カーソルの左側に非空白文 字 が な い 状態で TABキーを押すと,補完を始める代わり にTAB文字を挿入する。 `false' ならそのような場所 で も補完を行なう。 値 として `pending' または `pending=val' を設定する こともでき,その場合処理待ちの入力がある場合には 補 完でなくTAB文字を挿入する。 valを指定した場合は,入 力待ちの文字数の閾値を設定できる(□)。これはTAB文字 を 含むものを端末にペーストするときに便利である。た だしこれは zsh/zle モジュールで定義され る PENDING 変 数の値を頼りにしているが,これはすべてのプラット zsh 4.3.2 March 2, 2006 31 ZSHCOMPSYS(1) ZSHCOMPSYS(1) フォームで正確に設定されるとは限らない点に注意さ れ たい。 デフォルトは `true' だが,内部コマンド vared の中で は `false' である。 insert-unambiguous _match と _approximate コンプリータで使われる。これ ら のコンプリータは既入力文字列が補完結果と似通う部 分がほとんどなくなることもあるので,メニュー補完 に 移行することが多い。 し かし,このスタイルを `true' にするとコンプリータ は,最低限ユーザが入力したのと同じ文字数だけのあ い ま いでない初期文字列がみつからない限りメニュー補完 には移行しない。 (訳注: この項目末尾に詳細追記) _approximate コンプリータの場合は,コンテクス ト の completer フィ ー ル ド は 既に correct-num または approximate-num (numは許容エラー数)のどちらかがセッ トされている。 _match コンプリータの場合は,このスタイル値を `pat- tern' にすることもでき,その場合コマンドライン上 の パ ターンはあいまいさなくマッチしなければ,そのまま にされる。 訳 注: zstyle ':completion:*' completer _expand _complete _match _approximate な ど と し て _match,_approximate が使われるようにしておく。カレ ン ト ディ レ ク ト リ に MACHINES,META-FAQ,con- fig.sub,configure がある状態で MAT だ け 入 力 し てTABすると MACHINES と META-FAQ で循環するメニュー 補完に突入する。 ま た,cinf ま で 打っ てTABす る と,config.sub と configure で循環するメニュー補完 に突入する。しかし, zstyle ':completion:*' \ insert-unambiguous true すると,MAT のほうは3文字のままインクリメンタル補完 にはできないのでメニュー補完に突入するが,cinf のほ うは,conf に直せば configまで補完してインクリメ ン タ ル 補 完が続けられるのでメニュー補完には移行しな い。訳注終わり。 keep-prefix _expand コンプリータで使われる。`true' のときはチル ダ や変数展開を含むプレフィクスを保とうとする。ゆえ に,たとえば,`~/f*' は `/home/user/foo' ではなく, `~/foo' に展開される。スタイル値を `changed'(デフォ ルト値) にすると,プレフィクスは,展開結果とコマ ン ド ラインの元の文字列に別の変更があった場合だけ変更 されない。その他の値を設定するとプレフィクスを無 条 zsh 4.3.2 March 2, 2006 32 ZSHCOMPSYS(1) ZSHCOMPSYS(1) 件で展開する。 スタイル値が true のときの _expand の挙動によって, 1回展開したものがプレフィクスの復元で元と同じになっ てしまった場合には _expand を中止し,その結果残りの コンプリータが呼ばれることになる場合がある。 last-prompt シェルオプション ALWAYS_LAST_PROMPT の,より柔軟 な バ ージョン。この値が `true' だと,補完システムは一 覧表示したのち,最初のコマンドライン位置に戻ろう と す る。このスタイルは現在の補完で有効なすべてのタグ について調べられ,そののちデフォルトタグで調べら れ る。 カ ーソルを戻すのはそのスタイルがすべて `true' だった場合。ただし,ALWAYS_LAST_PROMPT と違い,数引 数の影響を受けない点が異なる点に注意。 known-hosts-files sshの known_hosts ファイルと互換性のある書式で書か れたホスト名とIPアドレス(use-ipスタイルがセットされ て いる場合) を探すために使われるファイルのリスト。 セットされていない場合 は /etc/ssh/ssh_known_hosts と ~/.ssh/known_hosts が用いられる。 list キ ー割り当て可能コマンド _history_complete_word に よって使われる。 `true' にセットされている場合は と くに効果がない。 `false' にセットされているとマッチ するものが一覧表示されなくなる。これは,一覧表示 機 能を制御するオプション,とくに AUTO_LIST をオーバー ライドする。コンテクストは 常 に `:completion:his- tory-words' で始まる。 list-colors zsh/complist モジュールがロードされている場合に,こ のスタイルは色付け指定として使われる。 zshmodules(1) の `The zsh/complist Module' 節で解説 されている ZLS_COLORS と ZLS_COLOURS 変数の利用を置 き換えるがただし文法は同じである。 (訳注: 初 期 化 ファ イ ルに古い ZLS_COLROS や ZLS_COLOURS の設定が あってもunsetされ,補完システムの list-colors が 優 先される。) このスタイルが default タグに対してセットされている と,その値はすべての場所で使われるものと見 な さ れ る。 他のタグに対してセットされていれば,そのタグに よって決まる補完対象のみの設定になる。この使いわ け を うまく活用するには, group-name スタイルに空文字 列を設定しておく。 上述のタグごとの固有スタイル 設 定 だ け で な く, group-nameタ グで明示的に指定されたグループ名を使う こともできる。それには ZLS_COLORS や ZLS_COLOURS 変 数 で許されている `(group)' 記法と default タグの使 zsh 4.3.2 March 2, 2006 33 ZSHCOMPSYS(1) ZSHCOMPSYS(1) 用を組み合わせる(△訳注: 試したけどよう分からん)。 GNU ls 用に設定してある設定を使うこともできる。それ には以下のようにする。 zstyle ':completion:*:default' list-colors ${(s.:.)LS_COLORS} (訳注: (s.:.) でコロン区切りをsplitしている) デ フォルトの彩色は GNU ls コマンドと同じで,それを 望む場合はスタイル値に空文字列を設定すればよい。 list-grouped `true' (デフォルト) にセットすると補完システムは 一 覧 表示をグルーピングマッチを利用してよりコンパクト にしようと試みる。たとえば,コマンドに対す る オ プ ショ ンの説明文字列(verboseスタイルが `true' のとき に表示される)が同じものどうしは1つのエントリとし て 出現する。 (訳注: 導入以後 `false' に戻ることもなさ そうだからこのスタイルは気にしなくてよかろう) list-packed default タグに加えて,現在のコンテクストで有効な タ グ す べてで調べられる。`true' にセットされていると LIST_PACKED オプションがセットされているかのよう に 一覧表示される。`false' は普通どおり。 list-prompt default タグに対して設定されていると,候補一覧表示 のときに画面からあふれるときに1画面ごとにプロンプト を 出して止まる。スタイル値に空でない文字列が設定さ れているとその文字列がプロンプトとして用いられ る。 (zsh/complist モジュール(zshmodules(1))も参照). 値 に は `%' で始まるエスケープシーケンスも使える。 `%l' または `%L' は,表示されている最後の行数/全 行 数。 `%m' ま たは `%M' は,表示されている最後の項 番/全項目数。 `%p' または `%P' は,表示されている位 置 の パ ー セ ン テ ージ (先頭なら `Top',末尾なら `Bottom')に置き換えられる。いずれの場合も小文字の方 は プロンプト表示幅が変動するが,大文字の方は右側に スペースを詰めた固定幅になる。 `%S' と `%s' は 強 調, 強 調 解 除, `%B' と `%b' は太字,太字解除, `%U',と `%u' は下線,下線解除に使え る。 `%{...%}' はエスケープシーケンスを表示幅0と見なすために括る。 プロンプトを出すのをやめるには zstyle -d してこの値 を 削除するだけではだめで,変数 LISTPROMPT を unset する必要がある。 list-rows-first list-packed スタイルと 同 じ よ う に 調 べ ら れ, LIST_ROWS_FIRST オプションと同様,補完一覧表示を横 zsh 4.3.2 March 2, 2006 34 ZSHCOMPSYS(1) ZSHCOMPSYS(1) 進みにする。 (訳注: デフォルトの一覧表示は ls と 同 じ縦進み) list-suffixes ファ イ ル 名補完を行なう関数で使われる。 `true' に セットすると,補完を既に入力された複数のパスコン ポ ー ネントを含めた文字列に対して行なわれ,一意に定ま らないコンポーネントが表示される。セットしないと 補 完は最初のあいまいなパスコンポーネントで止まる。 list-separator 訳 注: スタイルはいったんやめて次のセクション行きま す。 The value of this style is used in completion listing to separate the string to complete from a description when possible (e.g. when completing options). It defaults to `--' (two hyphens). local This is for use with functions that complete URLs for which the corresponding files are available directly from the filing system. Its value should consist of three strings: a hostname, the path to the default web pages for the server, and the directory name used by a user placing web pages within their home area. For example: zstyle ':completion:*' local toast \ /var/http/public/toast public_html Completion after `http://toast/stuff/' will look for files in the directory /var/http/pub- lic/toast/stuff, while completion after `http://toast/~yousir/' will look for files in the directory ~yousir/public_html. mail-directory If set, zsh will assume that mailbox files can be found in the directory specified. It defaults to `~/Mail'. match-original This is used by the _match completer. If it is set to only, _match will try to generate matches with- out inserting a `*' at the cursor position. If set to any other non-empty value, it will first try to generate matches without inserting the `*' and if that yields no matches, it will try again with the `*' inserted. If it is unset or set to the empty string, matching will only be performed with the `*' inserted. matcher こ のスタイルはカレントコンテクストでの正当なタグす zsh 4.3.2 March 2, 2006 35 ZSHCOMPSYS(1) ZSHCOMPSYS(1) べてで独立に参照される。この値は matcher-list で 設 定されているマッチ仕様に追加される。書式は zshcomp- wid(1) の `Matching Control' 節参照。 matcher-list このスタイルにはすべての場所で適用されるマッチ仕 様 を 設 定する。マッチ仕様については zshcompwid(1) の `Matching Control' 節参照。このスタイルには(シェ ル の)単語的に複数の値を設定でき,選択されたコンプリー タで順次この値を適用する。たとえば,もし, 普 通 の マッ チングを行なってそれで見つからなければ始めて大 文字小文字無視でマッチさせる補完をさせたければ, zstyle ':completion:*' matcher-list '' 'm:{a-zA-Z}={A-Za-z}' のようにする。デフォルトでは2つ目以降の仕様指定はそ れ以前のものを上書きするが,指定の先頭に + を付ける と追加する。これにより重複なしで徐々にマッチング 規 則を緩くしていくのが可能となっている。たとえば, zstyle ':completion:*' matcher-list '' '+m{a-Z}={A-Z}' '+m{A-Z}={a-z}' と すると,最初は,文字そのままでマッチさせ,それで だめなら小文字を大文字に変換してマッチ,それでも だ め なら小文字を大文字に変換することも追加で行なって マッチ,という風になる。特定のコンプリータ だ け に マッ チ仕様の指定を行なうこともでき,その場合はコン テクスト第3フィールド(つまりcompleterの位置)にそ の コンプリータを書けばよい。たとえば, _complete コン プリータと _prefix コンプリータを使っている場合で, _complete コンプリータだけに大文字小文字無視マッチ を適用させたいなら, zstyle ':completion:*' completer _complete _prefix zstyle ':completion:*:complete:*' matcher-list \ '' 'm:{a-zA-Z}={A-Za-z}' のようにする。 User-defined names, as explained for the completer style, are available. This makes it possible to try the same completer more than once with different match specifications each time. For example, to try normal completion without a match specification, then normal completion with case-insensitive matching, then correction, and finally partial-word completion: zstyle ':completion:*' completer _complete _correct _complete:foo zstyle ':completion:*:complete:*' matcher-list \ '' 'm:{a-zA-Z}={A-Za-z}' zstyle ':completion:*:foo:*' matcher-list \ 'm:{a-zA-Z}={A-Za-z} r:|[-_./]=* r:|=*' If the style is unset in any context no match spec- ification is applied. Note also that some zsh 4.3.2 March 2, 2006 36 ZSHCOMPSYS(1) ZSHCOMPSYS(1) completers such as _correct and _approximate do not use the match specifications at all, though these completers will only ever called once even if the matcher-list contains more than one element. Where multiple specifications are useful, note that the entire completion is done for each element of matcher-list, which can quickly reduce the shell's performance. As a rough rule of thumb, one to three strings will give acceptable performance. On the other hand, putting multiple space-separated values into the same string does not have an appre- ciable impact on performance. max-errors This is used by the _approximate and _correct com- pleter functions to determine the maximum number of errors to allow. The completer will try to gener- ate completions by first allowing one error, then two errors, and so on, until either a match or matches were found or the maximum number of errors given by this style has been reached. If the value for this style contains the string `numeric', the completer function will take any numeric argument as the maximum number of errors allowed. For example, with zstyle ':completion:*:approximate:::' max-errors 2 numeric two errors are allowed if no numeric argument is given, but with a numeric argument of six (as in `ESC-6 TAB'), up to six errors are accepted. Hence with a value of `0 numeric', no correcting comple- tion will be attempted unless a numeric argument is given. If the value contains the string `not-numeric', the completer will not try to generate corrected com- pletions when given a numeric argument, so in this case the number given should be greater than zero. For example, `2 not-numeric' specifies that cor- recting completion with two errors will usually be performed, but if a numeric argument is given, cor- recting completion will not be performed. The default value for this style is `2 numeric'. max-matches-width This style is used to determine the trade off between the width of the display used for matches and the width used for their descriptions when the verbose style is in effect. The value gives the number of display columns to reserve for the zsh 4.3.2 March 2, 2006 37 ZSHCOMPSYS(1) ZSHCOMPSYS(1) matches. The default is half the width of the screen. This has the most impact when several matches have the same description and so will be grouped together. Increasing the style will allow more matches to be grouped together; decreasing it will allow more of the description to be visible. menu 現在の補完で定義されているタグのコンテクストで, こ の 値が `true' のときはメニュー補完が用いられる。タ グつきで指定されている値は,`default' タグのもの よ りも優先する。 If none of the values found in this way is true but at least one is set to `auto', the shell behaves as if the AUTO_MENU option is set. If one of the values is explicitly set to false, menu completion will be explicitly turned off, overriding the MENU_COMPLETE option and other set- tings. In the form `yes=num', where `yes' may be any of the true values (`yes', `true', `on' and `1'), menu completion will be turned on if there are at least num matches. In the form `yes=long', menu comple- tion will be turned on if the list does not fit on the screen. This does not activate menu completion if the widget normally only lists completions, but menu completion can be activated in that case with the value `yes=long-list' (Typically, the value `select=long-list' described later is more useful as it provides control over scrolling.) Similarly, with any of the `false' values (as in `no=10'), menu completion will not be used if there are num or more matches. The value of this widget also controls menu selec- tion, as implemented by the zsh/complist module. The following values may appear either alongside or instead of the values above. If the value contains the string `select', menu selection will be started unconditionally. In the form `select=num', menu selection will only be started if there are at least num matches. If the values for more than one tag provide a number, the smallest number is taken. Menu selection can be turned off explicitly by defining a value containing the string`no-select'. zsh 4.3.2 March 2, 2006 38 ZSHCOMPSYS(1) ZSHCOMPSYS(1) It is also possible to start menu selection only if the list of matches does not fit on the screen by using the value `select=long'. To start menu selection even if the current widget only performs listing, use the value `select=long-list'. To turn on menu completion or menu selection when a there are a certain number of matches or the list of matches does not fit on the screen, both of `yes=' and `select=' may be given twice, once with a number and once with `long' or `long-list'. Finally, it is possible to activate two special modes of menu selection. The word `interactive' in the value causes interactive mode to be entered immediately when menu selection is started; see the description of the zsh/complist module in zshmod- ules(1)for a description of interactive mode. Including the string `search' does the same for incremental search mode. To select backward incre- mental search, include the string `search-back- ward'. muttrc If set, gives the location of the mutt configura- tion file. It defaults to `~/.muttrc'. numbers This is used with the jobs tag. If it is `true', the shell will complete job numbers instead of the shortest unambiguous prefix of the job command text. If the value is a number, job numbers will only be used if that many words from the job descriptions are required to resolve ambiguities. For example, if the value is `1', strings will only be used if all jobs differ in the first word on their command lines. old-list こ のスタイルは _oldlist コンプリータによって使われ る。値が `always' のときは、一覧を出す標 準 的 ウィ ジェッ トが今回マッチしたもののリストを保持するよう になる。 This is used by the _oldlist completer. If it is set to `always', then standard widgets which perform listing will retain the current list of matches, however they were generated; this can be turned off explicitly with the value `never', giving the behaviour without the _oldlist com- pleter. If the style is unset, or any other value, then the existing list of completions is displayed if it is not already; otherwise, the standard com- pletion list is generated; this is the default behaviour of _oldlist. However, if there is an old list and this style contains the name of the com- pleter function that generated the list, then the zsh 4.3.2 March 2, 2006 39 ZSHCOMPSYS(1) ZSHCOMPSYS(1) old list will be used even if it was generated by a widget which does not do listing. たとえば、カーソルの下に修正案一 覧 を 出 す _cor- rect_word ウィ ジェット(^Xc)を呼び出した場合を考え る。普通は次に ^D を押すとコマンドライン上の単語 で 普 通 の補完をする場合の候補一覧を出すが、 _oldlist と組み合わせると生成済みの修正案リストを表示する。 As another example consider the _match completer: with the insert-unambiguous style set to `true' it inserts only a common prefix string, if there is any. However, this may remove parts of the origi- nal pattern, so that further completion could pro- duce more matches than on the first attempt. By using the _oldlist completer and setting this style to _match, the list of matches generated on the first attempt will be used again. old-matches _all_matches コンプリータが使用する。 This is used by the _all_matches completer to decide if an old list of matches should be used if one exists. This is selected by one of the `true' values or by the string `only'. If the value is `only', _all_matches will only use an old list and won't have any effect on the list of matches cur- rently being generated. If this style is set it is generally unwise to call the _all_matches completer unconditionally. One possible use is for either this style or the com- pleter style to be defined with the -e option to zstyle to make the style conditional. old-menu This is used by the _oldlist completer. It con- trols how menu completion behaves when a completion has already been inserted and the user types a standard completion key such as TAB. The default behaviour of _oldlist is that menu completion always continues with the existing list of comple- tions. If this style is set to `false', however, a new completion is started if the old list was gen- erated by a different completion command; this is the behaviour without the _oldlist completer. For example, suppose you type ^Xc to generate a list of corrections, and menu completion is started in one of the usual ways. Usually, or with this style set to false, typing TAB at this point would start trying to complete the line as it now appears. With _oldlist, it instead continues to zsh 4.3.2 March 2, 2006 40 ZSHCOMPSYS(1) ZSHCOMPSYS(1) cycle through the list of corrections. original This is used by the _approximate and _correct com- pleters to decide if the original string should be added as a possible completion. Normally, this is done only if there are at least two possible cor- rections, but if this style is set to `true', it is always added. Note that the style will be examined with the completer field in the context name set to correct-num or approximate-num, where num is the number of errors that were accepted. packageset This style is used when completing arguments of the Debian `dpkg' program. It contains an override for the default package set for a given context. For example, zstyle ':completion:*:complete:dpkg:option--status-1:*' \ packageset avail causes available packages, rather than only installed packages, to be completed for `dpkg --status'. path The function that completes color names uses this style with the colors tag. The value should be the pathname of a file containing color names in the format of an X11 rgb.txt file. If the style is not set but this file is found in one of various stan- dard locations it will be used as the default. pine-directory If set, specifies the directory containing PINE mailbox files. There is no default, since recur- sively searching this directory is inconvenient for anyone who doesn't use PINE. ports A list of Internet service names (network ports) to complete. If this is not set, service names are taken from the file `/etc/services'. prefix-hidden This is used for certain completions which share a common prefix, for example command options begin- ning with dashes. If it is `true', the prefix will not be shown in the list of matches. The default value for this style is `false'. prefix-needed This, too, is used for matches with a common pre- fix. If it is set to `true' this common prefix zsh 4.3.2 March 2, 2006 41 ZSHCOMPSYS(1) ZSHCOMPSYS(1) must be typed by the user to generate the matches. In the case of command options, this means that the initial `-', `+', or `--' must be typed explicitly before option names will be completed. The default value for this style is `true'. preserve-prefix This style is used when completing path names. Its value should be a pattern matching an initial pre- fix of the word to complete that should be left unchanged under all circumstances. For example, on some Unices an initial `//' (double slash) has a special meaning; setting this style to the string `//' will preserve it. As another example, setting this style to `?:/' under Cygwin would allow com- pletion after `a:/...' and so on. range This is used by the _history completer and the _history_complete_word bindable command to decide which words should be completed. If it is a singe number, only the last N words from the history will be completed. If it is a range of the form `max:slice', the last slice words will be completed; then if that yields no matches, the slice words before those will be tried and so on. This process stops either when at least one match was been found, or max words have been tried. The default is to complete all words from the his- tory at once. regular This style is used by the _expand_alias completer and bindable command. If set to `true' (the default), regular aliases will be expanded but only in command position. If it is set to `false', reg- ular aliases will never be expanded. If it is set to `always', regular aliases will be expanded even if not in command position. rehash If this is set when completing external commands, the internal list (hash) of commands will be updated for each search by issuing the rehash com- mand. There is a speed penalty for this which is only likely to be noticeable when directories in the path have slow file access. remote-access If set to false, certain commands will be prevented from making Internet connections to retrieve remote zsh 4.3.2 March 2, 2006 42 ZSHCOMPSYS(1) ZSHCOMPSYS(1) information. This includes the completion for the CVS command. It is not always possible to know if connections are in fact to a remote site, so some may be pre- vented unnecessarily. remove-all-dups The _history_complete_word bindable command and the _history completer use this to decide if all dupli- cate matches should be removed, rather than just consecutive duplicates. select-prompt If this is set for the default tag, its value will be displayed during menu selection (see the menu style above) when the completion list does not fit on the screen as a whole. The same escapes as for the list-prompt style are understood, except that the numbers refer to the match or line the mark is on. A default prompt is used when the value is the empty string. select-scroll This style is tested for the default tag and deter- mines how a completion list is scrolled during a menu selection (see the menu style above) when the completion list does not fit on the screen as a whole. If the value is `0' (zero), the list is scrolled by half-screenfuls; if it is a positive integer, the list is scrolled by the given number of lines; if it is a negative number, the list is scrolled by a screenful minus the absolute value of the given number of lines. The default is to scroll by single lines. separate-sections This style is used with the manuals tag when com- pleting names of manual pages. If it is `true', entries for different sections are added separately using tag names of the form `manual.X', where X is the section number. When the group-name style is also in effect, pages from different sections will appear separately. This style is also used simi- larly with the words style when completing words for the dict command. It allows words from differ- ent dictionary databases to be added separately. The default for this style is `false'. show-completer Tested whenever a new completer is tried. If it is true, the completion system outputs a progress mes- sage in the listing area showing what completer is being tried. The message will be overwritten by zsh 4.3.2 March 2, 2006 43 ZSHCOMPSYS(1) ZSHCOMPSYS(1) any output when completions are found and is removed after completion is finished. single-ignored 1つしかマッチがないときに _ignored コンプリー タ に よっ て使われる。このスタイル値を `show' にしておく と,唯一のマッチは挿入されず表示される。 `menu' に し ておくと,唯一のマッチと元の文字列がマッチとして 加えられ,メニュー補完を開始する。 sort Many completion widgets call _description at some point which decides whether the matches are added sorted or unsorted (often indirectly via _wanted or _requested). This style can be set explicitly to one of the usual true or false values as an over- ride. If it is not set for the context, the stan- dard behaviour of the calling widget is used. The style is tested first against the full context including the tag, and if that fails to produce a value against the context without the tag. If the calling widget explicitly requests unsorted matches, this is usually honoured. However, the default (unsorted) behaviour of completion for the command history may be overridden by setting the style to true. _expand コンプリータの場合,`true' にセットされてい るとつねにソートする。`menu' の場合は展開結果を一個 ずつメニュー補完で提示する場合のみソートし,全て の 展開結果を一括で挿入する場合にはソートしない。 訳 注: 複数の語を含む配列変数の展開結果中,実在する ファイル名と同じものがあると,それらだけ先頭に寄 せ られる。 special-dirs Normally, the completion code will not produce the directory names `.' and `..' as possible comple- tions. If this style is set to `true', it will add both `.' and `..' as possible completions; if it is set to `..', only `..' will be added. The following example sets special-dirs to `..' when the current prefix is empty, is a single `.', or consists only of a path beginning with `../'. Otherwise the value is `false'. zstyle -e ':completion:*' special-dirs \ '[[ $PREFIX = (../)#(|.|..) ]] && reply=(..)' squeeze-slashes If set to `true', sequences of slashes in filename zsh 4.3.2 March 2, 2006 44 ZSHCOMPSYS(1) ZSHCOMPSYS(1) paths (for example in `foo//bar') will be treated as a single slash. This is the usual behaviour of UNIX paths. However, by default the file comple- tion function behaves as if there were a `*' between the slashes. stop If set to `true', the _history_complete_word bind- able command will stop once when reaching the beginning or end of the history. Invoking _his- tory_complete_word will then wrap around to the opposite end of the history. If this style is set to `false' (the default), _history_complete_word will loop immediately as in a menu completion. strip-comments If set to `true', this style causes non-essential comment text to be removed from completion matches. Currently it is only used when completing e-mail addresses where it removes any display name from the addresses, cutting them down to plain user@host form. subst-globs-only _expand コンプリータが使う。`true' の場合,グロッビ ン グと置換両方がコマンドラインにあるときに,置換だ けうまくいってもグロッビングがうまく行かない場合 に は 置 換 も し なかったことにする(□)。訳注: たとえ ば,`file=foo' のときに, ${file}.* で _expand した とする。このとき, foo.* にマッチするものがあれば, 通常通り展開結果をコマンドラインに挿入するが, マッ チするものがなければ ${file} 自体も展開しないことに する。 デフォルト値は `true'。 suffix _expand コンプリータで使われる。チルダまたは変数 展 開 のとき, `true' の場合はサフィクスを持たない場合 のみ展開される。 i.e. if it is something like `~foo' or `$foo' rather than `~foo/' or `$foo/bar', unless that suffix itself contains characters eli- gible for expansion. デフォルト値は `true'。 tag-order This provides a mechanism for sorting how the tags available in a particular context will be used. The values for the style are sets of space-sepa- rated lists of tags. The tags in each value will be tried at the same time; if no match is found, the next value is used. (See the file-patterns style for an exception to this behavior.) For example: zsh 4.3.2 March 2, 2006 45 ZSHCOMPSYS(1) ZSHCOMPSYS(1) zstyle ':completion:*:complete:-command-:*' tag-order \ 'commands functions' specifies that completion in command position first offers external commands and shell functions. Remaining tags will be tried if no completions are found. In addition to tag names, each string in the value may take one of the following forms: - If any value consists of only a hyphen, then only the tags specified in the other values are generated. Normally all tags not explicitly selected are tried last if the specified tags fail to generate any matches. This means that a single value consisting only of a single hyphen turns off comple- tion. ! tags... A string starting with an exclamation mark specifies names of tags that are not to be used. The effect is the same as if all other possible tags for the context had been listed. tag:label ... Here, tag is one of the standard tags and label is an arbitrary name. Matches are generated as normal but the name label is used in contexts instead of tag. This is not useful in words starting with !. If the label starts with a hyphen, the tag is prepended to the label to form the name used for lookup. This can be used to make the completion system try a certain tag more than once, supplying different style set- tings for each attempt; see below for an example. tag:label:description As before, but description will replace the `%d' in the value of the format style instead of the default description supplied by the completion function. Spaces in the description must be quoted with a backslash. A `%d' appearing in description is replaced with the description given by the completion function. In any of the forms above the tag may be a pattern or several patterns in the form `{pat1,pat2...}'. zsh 4.3.2 March 2, 2006 46 ZSHCOMPSYS(1) ZSHCOMPSYS(1) In this case all matching tags will be used except for any given explicitly in the same string. One use of these features is to try one tag more than once, setting other styles differently on each attempt, but still to use all the other tags with- out having to repeat them all. For example, to make completion of function names in command posi- tion ignore all the completion functions starting with an underscore the first time completion is tried: zstyle ':completion:*:*:-command-:*' tag-order \ 'functions:-non-comp *' functions zstyle ':completion:*:functions-non-comp' ignored-patterns '_*' On the first attempt, all tags will be offered but the functions tag will be replaced by func- tions-non-comp. The ignored-patterns style is set for this tag to exclude functions starting with an underscore. If there are no matches, the second value of the tag-order style is used which com- pletes functions using the default tag, this time presumably including all function names. The matches for one tag can be split into different groups. For example: zstyle ':completion:*' tag-order \ 'options:-long:long\ options options:-short:short\ options options:-single-letter:single\ letter\ options' zstyle ':completion:*:options-long' ignored-patterns '[-+](|-|[^-]*)' zstyle ':completion:*:options-short' ignored-patterns '--*' '[-+]?' zstyle ':completion:*:options-single-letter' ignored-patterns '???*' With the group-names style set, options beginning with `--', options beginning with a single `-' or `+' but containing multiple characters, and sin- gle-letter options will be displayed in separate groups with different descriptions. Another use of patterns is to try multiple match specifications one after another. The matcher-list style offers something similar, but it is tested very early in the completion system and hence can't be set for single commands nor for more specific contexts. Here is how to try normal completion without any match specification and, if that gener- ates no matches, try again with case-insensitive matching, restricting the effect to arguments of the command foo: zsh 4.3.2 March 2, 2006 47 ZSHCOMPSYS(1) ZSHCOMPSYS(1) zstyle ':completion:*:*:foo:*' tag-order '*' '*:-case' zstyle ':completion:*-case' matcher 'm:{a-z}={A-Z}' First, all the tags offered when completing after foo are tried using the normal tag name. If that generates no matches, the second value of tag-order is used, which tries all tags again except that this time each has -case appended to its name for lookup of styles. Hence this time the value for the matcher style from the second call to zstyle in the example is used to make completion case-insen- sitive. It is possible to use the -e option of the zstyle builtin command to specify conditions for the use of particular tags. For example: zstyle -e '*:-command-:*' tag-order ' if [[ -n $PREFIX$SUFFIX ]]; then reply=( ) else reply=( - ) fi' Completion in command position will be attempted only if the string typed so far is not empty. This is tested using the PREFIX special parameter; see zshcompwid for a description of parameters which are special inside completion widgets. Setting reply to an empty array provides the default behaviour of trying all tags at once; setting it to an array containing only a hyphen disables the use of all tags and hence of all completions. If no tag-order style has been defined for a con- text, the strings `(|*-)argument-* (|*-)option-* values' and `options' plus all tags offered by the completion function will be used to provide a sen- sible default behavior that causes arguments (whether normal command arguments or arguments of options) to be completed before option names for most commands. urls This is used together with the the urls tag by functions completing URLs. If the value consists of more than one string, or if the only string does not name a file or direc- tory, the strings are used as the URLs to complete. If the value contains only one string which is the name of a normal file the URLs are taken from that file (where the URLs may be separated by white space or newlines). zsh 4.3.2 March 2, 2006 48 ZSHCOMPSYS(1) ZSHCOMPSYS(1) Finally, if the only string in the value names a directory, the directory hierarchy rooted at this directory gives the completions. The top level directory should be the file access method, such as `http', `ftp', `bookmark' and so on. In many cases the next level of directories will be a filename. The directory hierarchy can descend as deep as nec- essary. For example, zstyle ':completion:*' urls ~/.urls mkdir -p ~/.urls/ftp/ftp.zsh.org/pub/development allows completion of all the components of the URL ftp://ftp.zsh.org/pub/development after suitable commands such as `netscape' or `lynx'. Note, how- ever, that access methods and files are completed separately, so if the hosts style is set hosts can be completed without reference to the urls style. See the description in the function _urls itself for more information (e.g. `more $^fpath/_urls(N)'). use-cache If this is set, the completion caching layer is activated for any completions which use it (via the _store_cache, _retrieve_cache, and _cache_invalid functions). The directory containing the cache files can be changed with the cache-path style. use-compctl If this style is set to a string not equal to false, 0, no, and off, the completion system may use any completion specifications defined with the compctl builtin command. If the style is unset, this is done only if the zsh/compctl module is loaded. The string may also contain the substring `first' to use completions defined with `compctl -T', and the substring `default' to use the comple- tion defined with `compctl -D'. Note that this is only intended to smooth the tran- sition from compctl to the new completion system and may disappear in the future. Note also that the definitions from compctl will only be used if there is no specific completion function for the command in question. For example, if there is a function _foo to complete arguments to the command foo, compctl will never be invoked for foo. However, the compctl version will be zsh 4.3.2 March 2, 2006 49 ZSHCOMPSYS(1) ZSHCOMPSYS(1) tried if foo only uses default completion. use-ip By default, the function _hosts that completes host names strips IP addresses from entries read from host databases such as NIS and ssh files. If this style is true, the corresponding IP addresses can be completed as well. This style is not use in any context where the hosts style is set; note also it must be set before the cache of host names is gen- erated (typically the first completion attempt). use-perl Various parts of the function system use awk to extract words from files or command output as this universally available. However, many versions of awk have arbitrary limits on the size of input. If this style is set, perl will be used instead. This is almost always preferable if perl is available on your system. Currently this is only used in completions for `make', but it may be extended depending on autho- rial frustration. users This may be set to a list of usernames to be com- pleted. If it is not set all usernames will be completed. Note that if it is set only that list of users will be completed; this is because on some systems querying all users can take a prohibitive amount of time. users-hosts The values of this style should be of the form `user@host' or `user:host'. It is used for commands that need pairs of user- and hostnames. These com- mands will complete usernames from this style (only), and will restrict subsequent hostname com- pletion to hosts paired with that user in one of the values of the style. It is possible to group values for sets of commands which allow a remote login, such as rlogin and ssh, by using the my-accounts tag. Similarly, values for sets of commands which usually refer to the accounts of other people, such as talk and finger, can be grouped by using the other-accounts tag. More ambivalent commands may use the accounts tag. users-hosts-ports Like users-hosts but used for commands like telnet and containing strings of the form `user@host:port'. zsh 4.3.2 March 2, 2006 50 ZSHCOMPSYS(1) ZSHCOMPSYS(1) verbose If set, as it is by default, the completion listing is more verbose. In particular many commands show descriptions for options if this style is `true'. word This is used by the _list completer, which prevents the insertion of completions until a second comple- tion attempt when the line has not changed. The normal way of finding out if the line has changed is to compare its entire contents between the two occasions. If this style is true, the comparison is instead performed only on the current word. Hence if completion is performed on another word with the same contents, completion will not be delayed. CONTROL FUNCTIONS compinit は,補完を行なう関数すべてのウィジェットを再定義 して,与えられたウィジェット関数 _main_complete を呼ぶよう に す る。この関数は,マッチするものを生成する「コンプリー タ」と呼ばれる関数を呼 ぶ ラッ パ ー と なっ て い る。 も し,`_main_complete' が引数つきで呼ばれたときには,それら は補完関数と見なされ,その順番で呼ばれることになる。引数な し なら,補完を試みる関数は completer スタイルから取得され る。たとえば,通常の補完関数をまず呼んで,それでマッチする も のがなければ綴違い修正関数を呼ばせたければ,compinit し たあとで zstyle ':completion:*' completer _complete _correct とする。このスタイルのデフォルト値は `_complete _ignored' で,通常の補完を,まず ignored-patterns スタイルの効果あり で,続いて効果なしで,という順番で試みる。 _main_complete 関数は各コンプリータ関数のリターンコードを見て,次のコンプ リータを呼ぶかどうか決める。リターンコード0なら,残りの コ ンプリータは呼ばずに _main_complete 関数自体から抜ける。 も し _main_complete の最初の引数がハイフン1字なら,引数は コンプリータの名前とは見なされず, 2つ目の引数はコンテクス ト の completer フィールドの値に,残りの引数はマッチするも のを生成する関数名とその引数と見なされる。 以下のコンプリータ関数は配布物に含まれているものだが,ユー ザは自分専用のものを書くことができる。関数名はアンダースコ アで始まるが,コンテクストでは先頭のアンダースコアは取り除 か れ る こ とに注意せよ。たとえば,基本の補完は `:comple- tion::complete:...' というコンテクストで実行される。 _all_matches このコンプリータは,「それ以外のマッチすべて」か ら な る文字列を追加するために使われる。これは以後呼ば れるコンプリータに影響を与えるためのものなので, 一 連 のコンプリータの先頭に登場する必要がある。マッチ zsh 4.3.2 March 2, 2006 51 ZSHCOMPSYS(1) ZSHCOMPSYS(1) するものすべ て の リ ス ト は avoid-completer と old-matches スタイルの影響を受ける。 後 述する _generic 関数を利用して _all_matches 自身 にキーを割り当てるとよい。たとえば以下のよ う に す る。 zle -C all-matches complete-word _generic bindkey '^Xa' all-matches zstyle ':completion:all-matches:*' old-matches only zstyle ':completion:all-matches::::' completer _all_matches 註: これだけでは補完はされない。最初に候補一覧を出 してから ^Xa を押してマッチするものすべてを出す。 _approximate 基本コンプリータの _complete に似ているが,補完に綴 り 修正を受けることを許可する。許される間違いの上限 の個数は max-errors スタイルで指定する。個数の数 え 方 については zshexpn(1) 参照。通常このコンプリータ は,普通の _complete コンプリータのあとでだけ試行さ れる。 zstyle ':completion:*' completer _complete _approximate と すると普通の補完で補完候補を得られなかった場合に 限り修正補完をする。もし,修正により補完候補がみ つ かっ た場合はコンプリータはそれらを巡回できるようメ ニュー補完を開始する。 このコンプリータは,修正候補と元の文字列を生成す る ときに corrections と original タグを利用する。前者 用の format スタイルには `%e' と `%o' を含ませる こ と ができ,それぞれ修正に要したエラー数および,元の 文字列,に置き換えられる。 訳注: こんな感じ。 zstyle ':completion:*:approximate*:*:*:corrections' \ format '%B%d (errors=%e) (original=%o)%b' zstyle ':completion:*' completer _complete _approximate 訳注終わり。 このコンプリータは max-errors スタイルで指定され た 最 大エラー数を徐々に増やして行くので,もし「エラー 修正数1」でみつかったら,修正数2以上のものは出て こ な い。修正数2でみつかった場合は3以上が出ない…,以 下同様。またコンテクストのコンプリータ名のところ に は,現在試行されているエラー修正数が,修正数1のとき は `approximate-1',修正数2のときは `approximate-2'…,と変わるようになっている。 _approximate を別の関数から呼ぶときは -a オプション zsh 4.3.2 March 2, 2006 52 ZSHCOMPSYS(1) ZSHCOMPSYS(1) に 続 け て 許 容エラー数を渡すことができる。引数は max-errors スタイルと同じ書式で,1つの文字 列 に す る。 こ の コ ン プ リ ータ(と後述の _correct コンプリー タ)は,とくに大きな許容エラー数を指定して呼んだとき に 厖 大なコストがかかる可能性を持つ。そこで, com- pleter スタイルを定義するときに, zstyle の -e オプ ションを使って,全く同じ文字列に対して2回連続で補完 しようとしたときにそうしたコンプリータが呼ばれる よ うにすることもできる。例: zstyle -e ':completion:*' completer ' if [[ $_last_try != "$HISTNO$BUFFER$CURSOR" ]]; then _last_try="$HISTNO$BUFFER$CURSOR" reply=(_complete _match _prefix) else reply=(_ignored _correct _approximate) fi' ここではzleと補完ウィジェット内部で使える HISTNO 変 数と,BUFFER,CURSOR 特殊変数を使い,直前に補完した と きとコマンドラインが同じかどうか調べ,そのときだ け _ignored,_correct,_approximate コンプリータ が 呼ばれるようにしている。 _complete コ ンテクストに即した方法で,すべての補完候補を生成 するコンプリータ。つまり,compdef 関数(解説済 み)で 定 義 した設定とすべての特殊変数の現在の値を使う(訳 注: 分からない人にとっては「つまり…」になってな い やん乱暴だなあ)。通常の補完動作を与えているのがこの コンプリータである。 コマンドの引数を補完するために _complete はユーティ リ ティ 関数の _normal を呼び,今度はそれが特別な関 数(後述)を探し出 す 役 割 を 受 け 持 つ。 こ の と き(□),`-context-' という形式の様々なコンテクスト がはっきりと区別される。これらコンテクストなどに つ い ては文書前半の #compdef タグの引数の説明に書かれ ている。 固有のコンテクスト用の関数を探す前に, _complete は 変数 `compcontext' がセットされているか調べる。たと えば自作関数で入力に vared を使ったりする局面などで は 通常の補完関数の振り分け(dispatch)をオーバーライ ドできると便利でそのようなときに `compcontext' 変数 が 使える。もし値に配列を入れておけば,各要素は補完 候補となり, `values' タグと `value' デスクリプショ ン(△)を 用いて補完されるようになる(△ 訳注: 分かん ないけど飛ばす)。 また,連想配列の値を入れておけば,各キーが 補 完 候 zsh 4.3.2 March 2, 2006 53 ZSHCOMPSYS(1) ZSHCOMPSYS(1) 補,値(value)がそれに対応する説明文字列として使われ る。また,コロンを含んだ文字列を `tag:descr:action' のような形式で入れておくとそれは, If it is set to an associative array, the keys are used as the possible completions and the values (if non-empty) are used as descriptions for the matches. If `compcontext' is set to a string con- taining colons, it should be of the form `tag:descr:action'. In this case the tag and descr give the tag and description to use and the action indicates what should be completed in one of the forms accepted by the _arguments utility function described below. 最後に,コロンなしの文字列を入れておくと,その値 が コ ンテクストとして使われ,それ用の関数が呼ばれるこ とになる。この目的のために,-command-line- という名 前 の特別なコンテクストがあり,それはコマンドライン 全体(コマンドとその引数)を補完する(△???)。これは補 完 システム自体は使用していないが,明示的に呼ばれる と処理される。 訳注: あら,_complete の説明終わっちゃっ た。 こ れ じゃ 分からんよなあ。わからんけど,分かるような説明 も書けんか。訳注終わり。 _correct 現在の語に対する補完ではなく,綴り「修正」のみを 生 成 する。 _approximate に似ているが,カーソル位置以 降に文字を補うことはせず,既に入力し終えた単語の ス ペ ルチェック(&修正)のように機能する。 _approximate に基づくコンプリータだが,コンテクストのコンプリ ー タフィールドは correct となる。 For example, with: zstyle ':completion:::::' completer _complete _correct _approximate zstyle ':completion:*:correct:::' max-errors 2 not-numeric zstyle ':completion:*:approximate:::' max-errors 3 numeric correction will accept up to two errors. If a numeric argument is given, correction will not be performed, but correcting completion will be, and will accept as many errors as given by the numeric argument. Without a numeric argument, first cor- rection and then correcting completion will be tried, with the first one accepting two errors and the second one accepting three errors. When _correct is called as a function, the number of errors to accept may be given following the -a option. The argument is in the same form a values to the accept style, all in one string. zsh 4.3.2 March 2, 2006 54 ZSHCOMPSYS(1) ZSHCOMPSYS(1) This completer function is intended to be used without the _approximate completer or, as in the example, just before it. Using it after the _approximate completer is useless since _approxi- mate will at least generate the corrected strings generated by the _correct completer -- and probably more. _expand This completer function does not really perform completion, but instead checks if the word on the command line is eligible for expansion and, if it is, gives detailed control over how this expansion is done. For this to happen, the completion system needs to be invoked with complete-word, not expand-or-complete (the default binding for TAB), as otherwise the string will be expanded by the shell's internal mechanism before the completion system is started. Note also this completer should be called before the _complete completer function. The tags used when generating expansions are all-expansions for the string containing all possi- ble expansions, expansions when adding the possible expansions as single matches and original when adding the original string from the line. The order in which these strings are generated, if at all, can be controlled by the group-order and tag-order styles, as usual. The format string for all-expansions and for expan- sions may contain the sequence `%o' which will be replaced by the original string from the line. The kind of expansion to be tried is controlled by the substitute, glob and subst-globs-only styles. It is also possible to call _expand as a function, in which case the different modes may be selected with options: -s for substitute, -g for glob and -o for subst-globs-only. _expand_alias If the word the cursor is on is an alias, it is expanded and no other completers are called. The types of aliases which are to be expanded can be controlled with the styles regular, global and dis- abled. This function is also a bindable command, see the section `Bindable Commands' below. _history Complete words from the shell's command history. zsh 4.3.2 March 2, 2006 55 ZSHCOMPSYS(1) ZSHCOMPSYS(1) This completer can be controlled by the remove-all-dups, and sort styles as for the _his- tory_complete_word bindable command, see the sec- tion `Bindable Commands' below and the section `Completion System Configuration' above. _ignored The ignored-patterns style can be set to a list of patterns which are compared against possible com- pletions; matching ones are removed. With this completer those matches can be reinstated, as if no ignored-patterns style were set. The completer actually generates its own list of matches; which completers are invoked is determined in the same way as for the _prefix completer. The sin- gle-ignored style is also available as described above. _list This completer allows the insertion of matches to be delayed until completion is attempted a second time without the word on the line being changed. On the first attempt, only the list of matches will be shown. It is affected by the styles condition and word, see the section `Completion System Con- figuration' above. _match This completer is intended to be used after the _complete completer. It behaves similarly but the string on the command line may be a pattern to match against trial completions. This gives the effect of the GLOB_COMPLETE option. Normally completion will be performed by taking the pattern from the line, inserting a `*' at the cur- sor position and comparing the resulting pattern with the possible completions generated. This can be modified with the match-original style described above. The generated matches will be offered in a menu completion unless the insert-unambiguous style is set to `true'; see the description above for other options for this style. Note that matcher specifications defined globally or used by the completion functions (the styles matcher-list and matcher) will not be used. _menu This completer was written as simple example func- tion to show how menu completion can be enabled in shell code. However, it has the notable effect of disabling menu selection which can be useful with _generic based widgets. It should be used as the first completer in the list. Note that this is zsh 4.3.2 March 2, 2006 56 ZSHCOMPSYS(1) ZSHCOMPSYS(1) independent of the setting of the MENU_COMPLETE option and does not work with the other menu com- pletion widgets such as reverse-menu-complete, or accept-and-menu-complete. _oldlist This completer controls how the standard completion widgets behave when there is an existing list of completions which may have been generated by a spe- cial completion (i.e. a separately-bound completion command). It allows the ordinary completion keys to continue to use the list of completions thus generated, instead of producing a new list of ordi- nary contextual completions. It should appear in the list of completers before any of the widgets which generate matches. It uses two styles: old-list and old-menu, see the section `Completion System Configuration' above. _prefix This completer can be used to try completion with the suffix (everything after the cursor) ignored. In other words, the suffix will not be considered to be part of the word to complete. The effect is similar to the expand-or-complete-prefix command. The completer style is used to decide which other completers are to be called to generate matches. If this style is unset, the list of completers set for the current context is used -- except, of course, the _prefix completer itself. Furthermore, if this completer appears more than once in the list of completers only those completers not already tried by the last invocation of _prefix will be called. For example, consider this global completer style: zstyle ':completion:*' completer \ _complete _prefix _correct _prefix:foo Here, the _prefix completer tries normal completion but ignoring the suffix. If that doesn't generate any matches, and neither does the call to the _cor- rect completer after it, _prefix will be called a second time and, now only trying correction with the suffix ignored. On the second invocation the completer part of the context appears as `foo'. To use _prefix as the last resort and try only nor- mal completion when it is invoked: zstyle ':completion:*' completer _complete ... _prefix zstyle ':completion::prefix:*' completer _complete zsh 4.3.2 March 2, 2006 57 ZSHCOMPSYS(1) ZSHCOMPSYS(1) The add-space style is also respected. If it is set to `true' then _prefix will insert a space between the matches generated (if any) and the suf- fix. Note that this completer is only useful if the COM- PLETE_IN_WORD option is set; otherwise, the cursor will be moved to the end of the current word before the completion code is called and hence there will be no suffix. bashcompinit This function provides compatibility with bash's programmable completion system. When run it will define the functions, compgen and complete which correspond to the bash builtins with the same names. It will then be possible to use completion specifications and functions written for bash. BINDABLE COMMANDS できるだけ直感に添えるよう作られたコンテクスト依存の補完だ けでなく,他の特殊なウィジェットがあり,キーに割り当てるこ とができる。以下にそれら一覧を示す。 _bash_completions _bash_complete-word と _bash_list-choices の2つの ウィジェットによって使われる関数で,bashの補完コ マ ン ドと互換のある機能を提供している。呼び出しキーの 最後のストロークで補完対象を切り替える。 `!' ならコ マ ン ド 名,`$' な ら 環境変数名, `@' ならホスト 名,`/' ならファイル名, `~' ならユーザ名を補 完 す る。 bashで は `\e' のあとにそれらのキーを押せば補 完, `\^X' のあとに押せば一覧表示となるが,これらの うちいくつかはzshの標準キーバインドとかち合うのでデ フォルトでは `\e~' と `^X~' だけキーに割り当てて あ る。 残りのキーをbashと同じバインドで足すには以下の ようにする。 for key in '!' '$' '@' '/' '~'; do bindkey "\e$key" _bash_complete-word bindkey "^X$key" _bash_list-choices done This includes the bindings for `~' in case they were already bound to something else; the comple- tion code does not override user bindings. _correct_filename (^XC) Correct the filename path at the cursor position. Allows up to six errors in the name. Can also be called with an argument to correct a filename path, independently of zle; the correction is printed on standard output. zsh 4.3.2 March 2, 2006 58 ZSHCOMPSYS(1) ZSHCOMPSYS(1) _correct_word (^Xc) Performs correction of the current argument using the usual contextual completions as possible choices. This stores the string `correct-word' in the function field of the context name and then calls the _correct completer. _expand_alias (^Xa) This function can be used as a completer and as a bindable command. It expands the word the cursor is on if it is an alias. The types of alias expanded can be controlled with the styles regular, global and disabled. When used as a bindable command there is one addi- tional feature that can be selected by setting the complete style to `true'. In this case, if the word is not the name of an alias, _expand_alias tries to complete the word to a full alias name without expanding it. It leaves the cursor directly after the completed word so that invoking _expand_alias once more will expand the now-com- plete alias name. _expand_word (^Xe) Performs expansion on the current word: equivalent to the standard expand-word command, but using the _expand completer. Before calling it, the function field of the context is set to `expand-word'. _generic This function is not defined as a widget and not bound by default. However, it can be used to define a widget and will then store the name of the widget in the function field of the context and call the completion system. This allows custom completion widgets with their own set of style set- tings to be defined easily. For example, to define a widget that performs normal completion and starts menu selection: zle -C foo complete-word _generic bindkey '...' foo zstyle ':completion:foo:*' menu yes select=1 Note in particular that the completer style may be set for the context in order to change the set of functions used to generate possible matches. If _generic is called with arguments, those are passed through to _main_complete as the list of completers in place of those defined by the completer style. _history_complete_word (\e/) Complete words from the shell's command history. zsh 4.3.2 March 2, 2006 59 ZSHCOMPSYS(1) ZSHCOMPSYS(1) This uses the list, remove-all-dups, sort, and stop styles. _most_recent_file (^Xm) Complete the name of the most recently modified file matching the pattern on the command line (which may be blank). If given a numeric argument N, complete the Nth most recently modified file. Note the completion, if any, is always unique. _next_tags (^Xn) This command alters the set of matches used to that for the next tag, or set of tags, either as given by the tag-order style or as set by default; these matches would otherwise not be available. Succes- sive invocations of the command cycle through all possible sets of tags. _read_comp (^X^R) Prompt the user for a string, and use that to per- form completion on the current word. There are two possibilities for the string. First, it can be a set of words beginning `_', for example `_files -/', in which case the function with any arguments will be called to generate the completions. Unam- biguous parts of the function name will be com- pleted automatically (normal completion is not available at this point) until a space is typed. Second, any other string will be passed as a set of arguments to compadd and should hence be an expres- sion specifying what should be completed. A very restricted set of editing commands is avail- able when reading the string: `DEL' and `^H' delete the last character; `^U' deletes the line, and `^C' and `^G' abort the function, while `RET' accepts the completion. Note the string is used verbatim as a command line, so arguments must be quoted in accordance with standard shell rules. Once a string has been read, the next call to _read_comp will use the existing string instead of reading a new one. To force a new string to be read, call _read_comp with a numeric argument. _complete_debug (^X?) This widget performs ordinary completion, but cap- tures in a temporary file a trace of the shell com- mands executed by the completion system. Each com- pletion attempt gets its own file. A command to view each of these files is pushed onto the editor buffer stack. zsh 4.3.2 March 2, 2006 60 ZSHCOMPSYS(1) ZSHCOMPSYS(1) _complete_help (^Xh) 現 在のカーソル位置でのコンテクストの各フィールド情 報を表示する。 1より大きな数引数をつけ る と(`ESC-2 ^Xh' など) そこで参照されるスタイルとそのときのコン テクストもすべて表示される。 ただし,スタイルに関する情報はユーザが独自に設定 し た スタイルなどで変わりうるので不完全であることに注 意。 _complete_tag (^Xt) This widget completes symbol tags created by the etags or ctags programmes (note there is no connec- tion with the completion system's tags) stored in a file TAGS, in the format used by etags, or tags, in the format created by ctags. It will look back up the path hierarchy for the first occurrence of either file; if both exist, the file TAGS is pre- ferred. You can specify the full path to a TAGS or tags file by setting the parameter $TAGSFILE or $tagsfile respectively. The corresponding comple- tion tags used are etags and vtags, after emacs and vi respectively. UTILITY FUNCTIONS ここでは補完関数を書くときに有用なユーティリティ関数につい て述べる。 If functions are installed in subdirectories, most of these reside in the Base subdirectory. 配布に含ま れるコマンド用の補完関数例のように,候補一覧を生成するユー ティリティ関数はすべて,候補を生成したならゼロ,しなかった なら非ゼロを返すという決まりに従っている。 また,_main_complete 関数は補完を行なう直前と直後にそれ ぞ れ配列 compprefuncs,配列 comppostfuncs に列挙された関数を 呼ぶ。各関数は明示的に自分自身を配列に再代入しない限り 1度 だ け呼ばれる(訳注: それがユーティリティ関数とどう関連する か書いてクレー???)。 _all_labels [ -x ] [ -12VJ ] tag name descr [ command args ... ] 下 記 _next_label 関数(該当箇所の説明にループを構築 する例がある) への手軽なインタフェース関 数。 com- mand とその引数が補完候補を生成するために呼ばれる。 name に保存されたオプションは自動的に,args に追 加 さ れ(commandにも渡され)る。通常それらは command 直 後に挿入されるが,args のどれかがハイフンのみの場合 は その直前に入れられる。ハイフンが最後の引数のとき は,最後のハイフンを削除する(△なじぇ)。こ れ に よ り,compadd や他のユーティリティ関数を1回だけ呼んで 補完候補を生成する よ う な ほ と ん ど の 場 所 で _all_labels を使えるようになる(△???: はにゃ)。 zsh 4.3.2 March 2, 2006 61 ZSHCOMPSYS(1) ZSHCOMPSYS(1) たとえば, local expl ... if _requested foo; then ... _all_labels foo expl '...' compadd ... - $matches fi と すると, _all_labelsが生成したものより優先される ような追加オプションを compaddにつけて, matches 変 数にある値を補完するようになる(△んむ???)。 _alternative [ -C name ] spec ... 複 数のタグが利用可能な単純なケースで有用。本質的に これは _tags 関数(後述)で説明するループのようなもの を実装している。 使用するタグとそのとき遂行する処理は spec で `tag:descr:action' という書式で指定する。 tag は _tags を使って与えられ,もしタグが要求された ら action が descr を説明文字列として伴って実行され る。 action は,下記 _arguments 関数が受け付けるも のと同じ (ただし `->state' と `=...' を除く)。 たとえば,action は単純な関数呼び出しでよく, _alternative \ 'users:user:_users' \ 'hosts:host:_hosts' とすると,ユーザ名とホスト名を補完候補とし て 提 示 し, そ れ らはそれぞれ _users,_hosts 関数が生成す る。 _arguments 関数のように,この関数は _all_labels を す べてのタグセットに関して繰り返してアクションを実 行するために使う。特別な処理は付加的な有効タグが あ る 場 合のみ(たとえば, _alternative から呼ばれた関 数)される(△なんのこっちゃ???)。 _tags 関数と同様,-C オプションで argument コンテク ストフィールドに別のものを与えられる。 訳 注: _tags 関数が分からないとこれを理解するのは困 難。上記の users, hosts の例を _tags のループで書く と,おそらくこのようになる。 local expl ret=1 zsh 4.3.2 March 2, 2006 62 ZSHCOMPSYS(1) ZSHCOMPSYS(1) _tags users hosts while _tags; do _requested users expl 'user' _users && ret=0 _requested hosts expl 'host' _hosts && ret=0 (( ret )) || return ret done _arguments [ -nswWACRS ] [ -O name ] [ -M matchspec ] [ : ] spec ... こ の関数は,標準的なUNIXのオプションと引数の流儀に 従うコマンドの完全な仕様を補完システムに教えるた め に 使う。以下に示す書式を使って個々のコマンドのオプ ション・引数のセットを指定して行くわけだが, _argu- ment 自身へのオプションなのか対象となるコマンドのオ プション指定なのか紛らわしくなるので,区別しやす く す るためにそれらの間にコロンひとつを挟んでも構わな い(□訳注: ちゅーかこのマニュアル自身が _arguments へ のオプションなのか,それによって補完されるコマン ドのオプションなのか判別しやすい工夫をしてないの が 痛い。気をつけて読んでくだされ。)。 _arguments 自身 へのオプションは1字オプションだが必ず別の単語で指定 しなければならない(つまり -s -w をまとめて -sw とす るのは不可(□))。 _arguments に -n オプションを指定すると,変数 NOR- MARG に配列変数 words 中の最初の普通の引数の位置, つまりオプション指定が終わった最初の引数の位置, を 代 入するようになる。普通の引数まで辿り着かない場合 NORMARG は -1 になる。呼び主となる関数では,-n オプ ションが渡されたら必ず `integer NORMARG' する必要が ある。そうしておかないと変数が使われない(△???)。 訳注: 以下で登場する messages は,補完寺に補完対 象 を 説明する文として使われるが,デフォルトでは出てこ ない(と思う)。 zstyle ':completion:*:descriptions' \ format '[[Completing %B%d%b]]' などとして説明文字列が出てくるようにしておこう。 訳 注終わり。 n:message:action n::message:action 第var(n)番目の普通の引数(の情報)を記述する。 message は,補完候補一覧の上に 表 示 さ れ, action はこの位置で補完されるべきものを指示 する(方法については後述)。 ::とコロ ン2つ を message の 前 に 付けた場合は,その引数が任 意(optional)であることを指示する。また,mes- sage が空白文字だけを含むときには補完候補一 覧の上には何も表示されない。た だ し,action で何か説明の文字列を足している場合はそれが表 示される。 zsh 4.3.2 March 2, 2006 63 ZSHCOMPSYS(1) ZSHCOMPSYS(1) :message:action ::message:action 上記と同様。ただし,何番目 か に か か わ ら ずem(次の)引数についての記述となる。もしすべ ての引数を正しい順番で書くならば, nを省略し たこの書き方だけ並べればよい(□)。 *:message:action *::message:action *:::message:action 上 記2つの記法による(オプションでない)引数に ついての記述がない引数は,ここで書いた記述に 従う。何番目の引数かの指定をとくに行なわない 書き方。 :: とコロン2つを message の前に書くと,特 殊 配 列変数 words と特殊変数 CURRENT は,(オプ ションでない)普通の引数を指すよう action実行 時(評 価 時)に修正される。 ::: とコロン3つを message の前に書くと,この記法でカバーされる 普通の引数だけを指すように修正される。 (△訳 注???: どういうときに役立つか分からん) optspec optspec:... 補完対象のコマンドのオプションを記述する。コ ロ ンを付けた場合,そのオプションは1つ以上の 引数を取ることを意味する。コロンなしの場合, そのオプションには引数がないことを意味する。 デフォルトではオプション名は2文字以上でも よ い ものとみなすが, _arguments自身の -s を指 定すると,補完対象のコマンドのオプショ ン は 1字だけと見なす。ただし,たとえば `--prefix' のように, -- で始まるオプションはやは り1つ の 完全なオプション名と見なす。これはGNU標準 に適っている。 -s と -w を両方指定すると,引数を取る1字オプ ショ ンが交ざっていたとしても,1字オプション どうしをまとめて指定できるものと見なす。たと え ば, あ る コマンドの -a オプションが引数 を1つ取るものだとして, -sなしのとき: `-ab' はそれで1つのオプション(処理されない), -sあ りのとき: `-ab' は1つのオプ ショ ン と 引 数 `b', -s と -w のとき: `-ab' は -a オプショ ンと -b オプションの指定で,さらにその後引数 が来るものと期待される…,のように補完時の解 釈が変わる。 これらのルール解釈は,-W を指定するともっ と 深 遠な領域へ: -W をつけると,同じ単語内に現 れる引数のあとでも1字オプションを補完でき る ようになる。しかしその位置で実際に補完が行な zsh 4.3.2 March 2, 2006 64 ZSHCOMPSYS(1) ZSHCOMPSYS(1) われるかどうかは,遂行される action に依存す る。より深く制御したい場合は _guard のような ユーティリティ関数をアクションの一部に使うと よい。 (訳注: -W の違いが分からない…。) さ て,最初の optspec で利用できる書き方を以 下に示す。オプションに引数があってもなくても 構わない。 *optspec こ の optspec は下記のいずれかであ る。これは,optspec が繰り返してもよ い ことを意味する。通常は(繰り返しは 自動的に避けられるので□),コマン ド ラインのカーソルより左側に入力済みの オプションは候補一覧から外れる。 (訳 注: 複 数回指定する可能性のあるオプ ションにはハイフンの直前に * を指 定 しておく) -optname +optname オ プ ショ ン 指 定 の最も単純な形式 で,optspec にマイナスかプラスで始ま る オ プ ショ ン そ のものを書く(例: `-foo')。オプションの最初の引数(がも し あるならそれ)はem(別の)単語として そのオプションの直後に来る必要 が あ る(△訳注: コロン要らないの?)。 `-+optname' または `+-optname' とい う形式で書けば,-optname と +optname 両方のオプション指定が有効だと指定で きる。 下記のいずれの書式も,先頭の `-' は `+' に置き換えたり組み合わせたりでき る。 -optname- そのオプションの第1引数が同じ単語 内 でそのオプションの直後に書くべきであ ることを示す。たとえ ば,`-foo-:...' と書くと,補完されたオプションとその 引数は,`-fooarg' のようになる。 -optname+ 上記と似ているが,そのオプショ ン の 第1引 数は,同じ単語内のオプション直 後に来ても,次の単語に来てもよいこと を 示す。たとえば, `-foo+:...' の場 合,補完されたオプション と 引 数 は `-fooarg' または `-foo arg' のどちら ででも指定されうることを示す。 zsh 4.3.2 March 2, 2006 65 ZSHCOMPSYS(1) ZSHCOMPSYS(1) -optname= そのオプションの第1引数は,次の単 語 として指定するか,同じ単語内でイコー ルで区切って指定するかどちらかである ことを示す。たとえば, `-foo=arg' ま たは `-foo arg' のどちらででも指定さ れうる。 -optname=- そのオプションへの引数が必ず同一単語 内でイコールを使って与えられるべきこ と を示す(訳注: 上と同じだが次の単語 では不可という場合)。 optspec[explanation] これまで説明した上記すべての optspec には,そのオプションの説明文字列を大 括弧で括って `-q[query operation]' のように追加指定することができる。 オプション一覧表示のときに,この説明 文字列をいっしょに表示するかどうかは verbose スタイルで決定する。 説 明 文 字 列 の 指 定 が な い が,auto-description スタイルが セッ ト されていて optspec にひとつだけ引 数の指定がある場合は,そのスタイルの 値 が 表示される。その文字列中にある `%d' は optspec の後ろにある optarg の最初の message に置き換えられる(下 記参照)。 オプションとして `+' や `=' 自身そのものを書きた い 場合はたとえば `-\+' のようにクォートする。 optspec の後ろに続く optarg は,以下のいずれかの形 式で記述する。 :message:action ::message:action そのオプションに対する引数に関する指定: mes- sage と action は普通の引数に対する記述と同 じように処理される。コロン1つで始まるほう は 必 ず 引 数を要求し,コロン2つのほうは引数が あってもなくてもよいことを意味する。 訳注: 「オプションに対する引数があってもなく て も いい?」というのはたとえば,configureの --enable-hoge=yes が --enable-hoge だけで も いいような場合がある。そういう場合は --enable-hoge='[Quiet]::Quiet Mode:(yes no)' zsh 4.3.2 March 2, 2006 66 ZSHCOMPSYS(1) ZSHCOMPSYS(1) などとするとよい。訳注終わり。 そのオプションが複数の引数を必要とするなら, この記法を引数の数だけ繰り返してよい。 つ ま り, :message1:action1:message2:action2 とす ると2引数を取るオプションの指定となる。 :*pattern:message:action :*pattern::message:action :*pattern:::message:action 複数の引数の記述: 複数の引数を取るようなオプ ションに対するこの形式の optarg は最後にだけ 書くことができる(訳注: そうでないとどこか ら 次のオプションや残りの引数を取っていいか分か らない)。もし pattern が空(つまり :*:)の場合 は,コマンドラインの残りのすべての引数をここ に書いた action の方法で補完することを指定す る。 pattern を指定した場合は,そのパターン にマッチする語を含む引数までは action で補完 する。 訳注: たとえば,find の -exec オプションのよ うに, \; までをコマンドと見なす,のようなも のはこれで指定する。訳注終わり。 複 数のコロンは普通の引数に対する `*:...' と 同じように処理される -- コロン2つなら特殊 配 列 変 数 words と特殊変数 CURRENT は,(オプ ションでない)普通の引数を指すよう action実行 時(評 価時)に修正される。コロン3つならそれら 変数が,この記法でカバーされる普通の引数だけ を指すように修正される。 以上でコロンそのものを値に含ませたい場合はバックスラッシュ でクォートして `\:' のように書く。 上記いずれの書式でも,その前に括弧内に列挙したオプションや 引数の番号を置くことができる。そのオプションをコマンドライ ンで書いたときに括弧内に列挙したオプションや引数を候補から 外すことを意味する。たとえば,`(-two -three 1)-one:...' と 書くと `-one' というオプションを補完候補に含めると同時に, コマンドラインにそれを書いたらそれより後ろの方では -two オ プションも,`-three オプションも第1引数で補完すべきも の, い ずれも補完しないようにする。また,`(-foo):...' は普通の 引数の補完指定の前に `-foo' を置いたもので,もし普通の引数 を入力したあとには -foo は補完しないことを意味する。 除外されるオプションリストには他の項目も書くことができ,そ の場の指定がマッチするときには該当項目が除外されるようにで き る。 ア ス タ リ ス ク1つ (*) は,残りの引数すべて(つま り`*:...' のような形),コロン1つ (:) は,普通の(オプション で ない)引数すべて,ハイフン1つ (-) は,すべてのオプション に対する指定となる。たとえば,`(*)' をオプションの前に書い た場合,そのオプションがコマンドライン中に挿入されたら,そ zsh 4.3.2 March 2, 2006 67 ZSHCOMPSYS(1) ZSHCOMPSYS(1) れより後ろには「残りの引数」 (上記の `:*' で始ま る spec) を補完しないことを意味する。 (訳注: 候補から外す目的で括弧 内に列挙する指定を「除外リスト」と呼ぶことにする。) こうした指定の再利用を助ける目的で上記記法の前に `!' を 付 け る記法が用意されている。 `!' を前置したオプションは補完 されなくなる。これが有用なケースは,引数が配列で与えられ, かつ _arguments 関数が何度も,次第により限定的なコンテクス ト用に呼ばれるようなときである。たとえば最初の呼び出 し が `_arguments $global_options' で, そ の 後 の 呼び出しが `_arguments !$^global_options' という形式で呼んだりする 場 合である(訳注: 降って涌いたようなこの段落何?)。 上記の一連の記法で出てきた action は,補完候補をどのように 生成するかを記述する。いずれも action の部分が,すべてのラ ベルを処理するために _all_labels 関数を呼んで実行される(た だし `->string' の場合を除く)。関数呼び出しが新しいもの を 導入しない限りタグの特別な処理は必要とされない(△ ???)。 action の部分の書式は以下の通り。 ` ' (クォートなしの空白1つ) そ の引数は必須だが,マッチを生成できないまたは生成 しない方がよいものであることを指定 す る。 こ の 場 合,message は表示されるものの候補一覧は表示されな い。ただし,この場合でも message の終端を示すコロン は必要で,省略してよいのは message,action 両方とも 省略する場合である。 訳注: `--name:Your Name: :' とすると --name の後 ろ では補完しない。 (item1 item2 ...) 補完候補となる単語そのものの列挙。例: :foo:(foo bar baz) ((item1\:desc1 ...)) 上 記と同様だが,補完候補の各単語に対する注釈を付加 する。コロンを必ずバックスラッシュでクォートする こ とに注意。たとえば, :foo:((a\:bar b\:baz)) と す る と, コ ン テ ク ストで value タグとともに description スタイルがセットされている場合にこれ ら の注釈が表示される。 ->string この形式では,_arguments は引数とオプションの処理を して呼出し側の関数に return するときに,状態変数 を セッ トするようになる。呼出し側の関数では,変数値を 使って補完生成を調節できる。これはたとえば,ステ ー トマシンを実装する関数などで使うことができる。 zsh 4.3.2 March 2, 2006 68 ZSHCOMPSYS(1) ZSHCOMPSYS(1) `->string' に 遭遇すると _arguments 関数は,string の先頭末尾の空白をすべて除去し,配列 state にすべて の string の値を入れてどんなアクションが取られるべ きか分かるようにする。 ちゃんと振る舞う他の補完関数もそうだ が,_arguments 関 数はデフォルトでは補完候補を追加できればゼロを, そうでなければ非ゼロを返す。しかし,もし -R オ プ ショ ンを指定した場合 _arguments 関数は,リターンコ ード300を返し,$state の値を見て処理を切り替える よ う呼び側関数に伝える。 $state だけでなく,_arguments 関数はグローバル変数 `context', `line',`opt_args' をセットする(後述)。 また, PREFIX や words のような特殊変数は変更せず, 呼び側の関数にそれらの変数の処 理 を 完 全 に 任 せ る(□)。 それゆえ,少なくとも1つ `->string' を含んだアクショ ンをつけて _arguments 関数を呼ぶ関数では,適切な ロ ーカル変数宣言をしておく必要がある。つまり, local context state line typeset -A opt_args として,_arguments 関数がグローバル変数を変えてしま うのを防ぐ(△使い方は???)。 {eval-string} 中括弧内に書かれた文字列は候補単語を生成するシェ ル コードとしてevalされる。 eval-string 自身が開括弧で も開中括弧でも始まっていない場合それは,実行前に 別 の単語に分割される。 訳 注: 補完候補を生成する方法載ってないじゃん。ここ では別の補完候補生成関数を使うか,候補を追加する た め の compadd 関数を直接使う。次の例は,--time オプ ション(仮)に与える引数に現在の時刻文字列を補完候 補 にする。 '--time:現在時刻:{compadd `date +"%H\:%M\:%S"`}' 訳注終わり。 = action action の前に `= ' (イコール記号と1つのスペース) が あると, _arguments 関数は現在のコン テ ク ス ト の argument フィールドの中味を特殊配列変数 words の先 頭要素の位置に挿入し,特殊変数 CURRENT の値をインク リ メントする。こうすることで補完コマンドラインにダ ミーの単語を挿入しつつも,実際に補完が起きている 場 所は変えないという効果が得られる。 この手法が役立つのは,上記引数指定記述のコロン2つと zsh 4.3.2 March 2, 2006 69 ZSHCOMPSYS(1) ZSHCOMPSYS(1) コロン3つを続けて書いたもの,つまり action の操作す るコマンドライン上の単語(words)を制限するものと組み 合わせる場合である。たとえば, action 自身が,限 ら れ た範囲の引数に対して _arguments を呼ぶ場合,この 手法で,二回目に _arguments が呼ばれるときの範囲 に 適 切なコマンド名をもぐりこませて行解析がうまくいく ようにする。 word... word... 上記の action 記法に当てはまらないものすべて。 action が空白で始まる場合は残りの単語群が修正さ れ ずに実行される。 空 白で始まらない場合は,最初の単語の後ろにいくつか の文字列( のちに compadd のオプションとして渡 さ れ る)を追加して実行される。これらは _arguments によっ て指定された $state が補完コマンドに正しく伝わる こ とを保証する(△???)。 こ れ らの付加的な引数は配列変数 `expl から取得され る。この変数は action を実行する前に設定され,そ の 中で参照されうる。 訳 注: よ ーわからん。飛ばす。でも便利そうだ。あと で。 They ensure that the state specified by _arguments, in particular the descriptions of options and argu- ments, is correctly passed to the completion com- mand. These additional arguments are taken from the array parameter `expl'; this will be set up before executing the action and hence may be referred to inside it, typically in an expansion of the form `$expl[@]' which preserves empty elements of the array. action 実行時に設定される変数について示す。 配列 `line' は,コマンドライン中にあるコマンド名とその普通 の引数を集めたもの,つまりすべてのオプションとオプションの 引数を取り除いたものとなる。 連想配列 `opt_args' にはオプションが代入される。このとき, オプション名はキー,その引数は値(バリュー)として入る。引数 を2つ以上取るオプションの引数は1つの文字列にコロン区切りで 格 納 される。引数の値にコロンが含まれていたときはバックス ラッシュでエスケープされる。 変数 `context' は,`->string' の形式の action を実行するた め に呼び側の関数に戻るときにセットされる。それには $state に対応した配列がセットされる。各要素はコンテクストの argu- ment フィールドに適した名前,つまり,`option-opt-n' という 値であればそれは -opt というオプションの n番 目 の 引 数, zsh 4.3.2 March 2, 2006 70 ZSHCOMPSYS(1) ZSHCOMPSYS(1) `argument-n' という値であればそれは n番目の引数,という風 になる。「残りの」引数,つまりリストの最後で位置指定なしで 定義されているものに関しては,n は文字列 `rest' になる。 たとえば,あるコマンドの -o オプションに対する引数の補完中 なら `option-o-1',普通の(オプションでな い)第2引 数 な ら `argument-2' という具合にセットされる。 さ らに,action の評価中は curcontext 変数のコンテクスト名 には, context 変数に入れられるのと同じ文字列が足される(△ 未確認)。 (訳 注: さて,コマンドにはつけるオプションによって文法がか なり変わるものがある。そのような場合,オプションと引数の組 み合わせをグループ化して別々に管理することができる。) オプ ションと引数の組み合わせのセットを,1つのハイフンで区 切っ て複数持たせることも可能である。その場合,最初のハイフンま でに書いたセットは,残りのセットすべてで共有される。 2つ目 以降のセットの記述の単語はそのセットの名前を意味し,それを 上述の「除外リスト」に書くことができる(□)。名前は単独で書 い て も よいし,上で述べられている possible values のどれ か1つの前でもよい(△訳注: described aboveってど れ だ よ。 aboveとbelowばっ かでまったくわからんぞ)。後者の場合は `-' をその名前と残りの名前の間に書く必要がある。 It is possible to specify multiple sets of options and arguments with the sets separated by single hyphens. The specifications before the first hyphen (if any) are shared by all the remaining sets. The first word in every other set provides a name for the set which may appear in exclu- sion lists in specifications, either alone or before one of the possible values described above. In the second case a `-' should appear between this name and the remain- der. 例を示す。 _arguments \ -a \ - set1 \ -c \ - set2 \ -d \ ':arg:(x2 y2)' は,2つのセットを定義している。コマンドラインが `-c' を 含 む ときは,`-d' オプションと `':arg:(x2 y2)'' により期待さ れる引数は補完候補にはならない。逆に,`-d' オプションや 引 数が入力された場合は `-c' オプションが候補から外れる。しか し,`-a' の後ろではいずれの場合も有効なオプションと見な さ れる。 ハイフンで分割したセットは互いに排他的な補完関係となるが, セット間の排他だけでなくセット内の排他も同時に指定できる。 zsh 4.3.2 March 2, 2006 71 ZSHCOMPSYS(1) ZSHCOMPSYS(1) セット名を `(name)' のように括弧で括って書くと,そのセット の中の補完候補は,そのセット内の他の候補に対しても別のセッ トの候補に対しても排他的となる。つまり,複数のセットの中か ら,選ばれるものはただひとつという関係を書ける。これは,排 他的なオプションにエイリアスがある場合などに有用で, _arguments \ -a -b \ - '(compress)' \ {-c,--compress}'[compress]' \ - '(uncompress)' \ {-d,--decompress}'[decompress]' と 書くと,compress セットと uncompress セットは同時には補 完されず,なおかつ compress セットで補完する場合も `-c' と `--compress' は同時には補完されなくなる(□この段落原文から 相当変えた)。 もっとも,複数のセットを持たせると補完のためのコードがそれ ぞれ別々に解析しなければならないので遅くなることからどうし ても必要な場合以外は使用を控えるのが望ましい(□)。別解とし ては,排他的な関係を持つオプションの指定を `-foo:*:...' の ように書いて,残りの引数をすべて rest-arguments として読み 切ってもらう方法がある(□)。 _arguments 関数のオプションについて列挙する(□)。 -S オプション: `--' をオプションの終わりと自動判定する。た とえば, foobar -a -- -b にある `-b' は引数と見なされる。`--' 自身は引数と も オ プ ションとも見なされない。 -Aオプション: オプションでない引数の後ろではオプションの補 完をやめる。与えた単語が普通の引数でないと判断するためのパ ターンを -A オプションの引数として指定する。たとえば,opt- spec にオプションとして登録していないものでも「ハイフン で 始 ま る も の は なんでも普通の引数と見なさない」のであれ ば,`-A "-*"' と指定する。 -O オプション: `-O name' のように指定し, action を実行 す るために呼ばれる関数群に,nameという名の配列変数に含まれる 要素を引数として渡す。これはたとえば,すべての action に対 し て共通の「tt(compadd)用オプション」を渡したいときなどに 有用(△??? 例をクレー)。 -M オプション: '-M spec' のように指定し,オプション名と 値 の 補完時の「マッチ仕様」を決める。(訳注: 「マッチ仕様」は zshcompwid(1) に) この指定は最初のオプション仕様記述の前に来なければな ら な い。デフォルト値は `r:|[_-]=* r:|=*' で,これは `_' と `-' zsh 4.3.2 March 2, 2006 72 ZSHCOMPSYS(1) ZSHCOMPSYS(1) の後ろでは「部分マッチ」を許可することを意味する。た と え ば, `-f-b' を補完したときは `-f*-b*' というパターンにマッ チするもので補完するので `-foo-bar' など に 補 完 さ れ う る(□)。 -C オプション: `->state' のアクションを使う場合に curcon- text 変数の値をその場に応じた値に変えるよう _arguments に 指示する。この変数は現在のコンテクストに追随するための変数 で,これを使用する関数では修正した値を返してしまったりする ことのないようローカル変数化し,以下のようにして正しく初期 値設定する必要がある。 local curcontext="$curcontext" 複数の state を同時に当てはめることができないときなどに 有 用(△???実 例 を ク レー)。 This is useful where it is not possible for multiple states to be valid together. 訳注: 例えば cmd というコマンド引数での補完 で _arguments を 使い,その中に '-foo:foo option:->foo' があったとする。 -foo オプションを入力し終えその引数位置で呼ばれた と き の $curcontext が :complete:cmd:option-foo-1 となる。 -C なし だと :complete:cmd: のまま変わらない。訳注終わり。 `--' オプション: (□)GNUのコマンドのオプション流儀のおまか せオプション。 `--help' というオプションでヘルプ出力が出て くるようなものに対しその出力を取り込んでオプション解析を自 動で行なう。もちろん,ヘルプ出力にちゃんと対応していないコ マンドにこれを使うと危険。 対象コマンドのオプションそのものだけでな く, `--opt=val' という書き方が正当と見なされるオプションならそのオプション の引数の種別の推測も試みる。完全自動での推測がうまくいかな い場合はヒントを与えて,ヘルプ出力から,あるオプションの引 数の種別を推測しやすくすることもできる。ヒ ン ト は `pat- tern:message:action' という形式で与える(通常の引数使用指定 は使われない点に注意)。 pattern のマッチングはヘルプ出力中の,あるオプションに対す る説明文に対して適用され,マッチした場合はそのオプションの 引数補完時には,指定した message と action が利用される。 たとえば, _arguments -- '*\*:toggle:(yes no)' \ '*=FILE*:file:_files' \ '*=DIR*:directory:_files -/' \ '*=PATH*:directory:_files -/' とすると,ヘルプ行の説明文がアスタリスクで終わってるものの 引数は `yes' と `no' で, `=FILE' という文字列が含まれてい るものの引数はファイルで, `=DIR' や `=PATH' が含まれて い る も の の引数はディレクトリで補完する。実は最後の3つはデ フォルトで組み込まれているので明示的に与える必要はない。よ zsh 4.3.2 March 2, 2006 73 ZSHCOMPSYS(1) ZSHCOMPSYS(1) くあるヘルプ行の例として -C, --directory=DIR change to directory DIR の ようなものがあるが,これだと `--directory' の引数はディ レクトリを補完するが `-C' の後ろではうまくいかない。 また,_arguments はオプションの引数が任意かどうかも推測 す る が明示的に指定したい場合はヒントのところで message の前 のコロンを 2個にすればよい。 pattern が `(-)' で終わっている場合は………パス, If the pattern ends in `(-)', this will removed from the pattern and the action will be used only directly after the `=', not in the next word. This is the behaviour of a normal specification defined with the form `=-'. `_arguments --' には,それ専用の追加オプションがある(こ こ から□)。 -- -i オプション: 解析に使うヘルプ出力中で無視すべきパター ンを指定する。たとえば,configure オプションなどで一般的な 記法の説明として --enable-FEATURE not include FEATURE... の よ うな行があったりする。これは抽象例であって実際のオプ ションではないので無視したい。このようなときは,無視したい パターンを与える。たとえば, _arguments -- -i \ "(--(en|dis)able-FEATURE*)" とすると,`--enable-FEATURE' と `--disable-FEATURE' という オプションは無視する。 -- -s オプション: `-s pair' の形で指定して,オプションエイ リアスを定義する。 pair の部分にはパターンとその置き換え語 を指定する。たと え ば,configure の ヘ ル プ 出 力 に は `--enable-foo' の 説 明 し か な いにもかかわらず実際には `--disable-foo' も容認される。このような場合は, _arguments -- -s "(#--enable- --disable-)" とするることで,`--disable-*' のほうも補完されるよう に な る。 (ここまで□) ここで _arguments 関数の一般的な使用例を示す。 _arguments '-l+:left border:' \ '-format:paper size:(letter A4)' \ '*-copy:output file:_files::resolution:(300 600)' \ ':postscript file:_files -g \*.\(ps\|eps\)' \ '*:page number:' zsh 4.3.2 March 2, 2006 74 ZSHCOMPSYS(1) ZSHCOMPSYS(1) こ の 例は,ここで定義している関数が補完するコマンドのオプ ションにある, `-l',`-format',`-copy' の3つのオプショ ン について記述している。最初のものは引数をひとつ取り,引数補 完時に使う説明として `left border' を使い,補完候補は何 も 提 示 し な い よ う 指定している。また `+' の指定があるの で,`-l' オプションの引数は `-l' にくっつけて書いても, 次 の引数に書いてもよいことを意味している。 次 の `-format' は,説明文字列を `paper size' にし,補完候 補を `letter' と `A4' にしている。 `-copy' オプションは `*' によって,そのオプションがコマ ン ド ラ インに何回現れても補完することを意味し,また `output file' と `ressolution' に相当する2つの引数を取ることを意味 し て い る。 た だし, 2つ目の引数は省略可能である(コロン が2つ)。 最後の2つは,そのコマンドの普通の(オプションでない)引数 と し て補完されることを意味している。第1引数では説明文字列を `postscript files' として,ファイル名が `ps か `eps' で 終 わるものを補完する。最後の記述は,残りすべての引数で,説明 文字列を `page numbers' として補完せずに入力させることを意 味している。 _cache_invalid cache_identifier 補 完キャッシュの再構築が必要なときにゼロを返す。現 在のコンテクストの cache-policy スタイルを参照し て 判定を下す。 This should provide a function name which is run with the full path to the relevant cache file as the only argument. Example: _example_caching_policy () { # rebuild if cache is more than a week old oldp=( "$1"(Nmw+1) ) (( $#oldp )) } _call_function return name [ args ... ] 関 数 name が定義されていれば,引数 args を付けて呼 び,終了コードを変数 return に格納する。 return を 空にするかハイフンにすると無視される。 _call_function 関数自身の終了コードは,関数 name が 存在して呼べたらゼロ,そうでなければ非ゼロとなる。 _call_program tag string ... 訳注: ★これ結構重要なのになー★。 外部コマンドを呼ぶ。ただ呼ぶだけでなく,ユーザが 呼 び 出すべき外部コマンドをオーバーライドしやすいよう zsh 4.3.2 March 2, 2006 75 ZSHCOMPSYS(1) ZSHCOMPSYS(1) な機構を備えている。とくに指定がなければ string を 外 部コマンドとして呼び出し,その終了コードを返す。 ただし,tag に対する command スタイルが定義されてい る 場 合 はその値(文字列)を外部コマンドとして呼び出 す。呼び出したコマンドからの出力は,スペース区切 り で連結される。 訳 注: 例: cvs の サ ブ コ マ ン ド名一覧は `cvs --help-commands' として得ている。でも「commit じゃ なくて ci がいい!」と思っているなら外部コマンド呼び 出しを変えてしまえばよい。 _cvs 関数定義には, $(_call_program commands cvs --help-commands 2>&1) と い う 部 分 が あ る が, こ れ は,':comple- tion:*:cvs:*:commands' コンテクストの command タグ で上書きできるので, cvs 本来のヘルプ画面 の `com- mit' を `ci' に置換したヘルプ画面を出すような偽コマ ンド(仮に cvshelpfake とする)を作っておいて, zstyle ':completion:*:cvs:*:commands' \ command cvshelpfake などとしておく。 _cvs の場合,cvs のサブコマンド を 初 めて補完するときにこのコマンドを呼ぶのでコンテク ストのコマンド名のところがちゃんと `cvs' になってい る が,補完定義によっては空だったり,別のコマンド名 だったりする場合があるので注意が必要。訳注終わり。 _combination [ -s pattern ] tag style spec ... field opts ... 「ホ スト名とユーザ名」などのように,複数の値の組み 合わせの補完を行なうときに使う。 style の部分には構 成 す べ きペアのスタイルを指定する。このスタイルは tag が指定されたコンテクストで照合される。 スタイル名はたとえば, `users-hosts-ports' の よ う に, フィールド名をハイフンで区切ったもので構成され る。 値が既に確定しているものに対するフィ ー ル ド に は `field=pattern' という書式の spec が与えられる。た とえば,もしそれまで入力したコマンドラインでユー ザ `pws' を指定したならば,`users=pws' という引数が現 れるべきである。 訳注: ようするに spec 引数は(普通は)補完時に動的 に 生 成されるもので, _combination を呼び出すときには コマンドライン上に入力したユーザ名やホスト名を自 動 的 に 取 得 して,それを使って `users=pws' のような spec をそこに生成すると,ユーザが `pws' に合致す る よ うなホスト(とそのポート)だけを補完候補に選んでく れる。 zsh 4.3.2 March 2, 2006 76 ZSHCOMPSYS(1) ZSHCOMPSYS(1) この関数の使い方については _combination 関数を定 義 し ているファイルの使用例を見るのがいちばん速い。こ こは読んでも分からん。てことで,飛ばす。訳 注 終 わ り。 The matches generated will be taken from the value of the style. These should contain the possible values for the combinations in the appropriate order (users, hosts, ports in the example above). The different fields the values for the different fields are separated by colons. This can be altered with the option -s to _combination which specifies a pattern. Typically this is a character class, as for example `-s "[:@]"' in the case of the users-hosts style. Each `field=pattern' specification restricts the completions which apply to elements of the style with appropriately match- ing fields. If no style with the given name is defined for the given tag, or if none of the strings in style's value match, but a function name of the required field preceded by an underscore is defined, that function will be called to generate the matches. For example, if there is no `users-hosts-ports' or no matching hostname when a host is required, the function `_hosts' will automatically be called. If the same name is used for more than one field, in both the `field=pattern' and the argument that gives the name of the field to be completed, the number of the field (starting with one) may be given after the fieldname, separated from it by a colon. All arguments after the required field name are passed to compadd when generating matches from the style value, or to the functions for the fields if they are called. _describe [ -oO | -t tag ] descr name1 [ name2 ] opts ... -- ... この関数は補完候補と説明文字列を関連付ける。 This function associates completions with descrip- tions. Multiple groups separated by -- can be sup- plied, potentially with different completion options opts. descr は 候 補 一 覧の上に出る説明文字列で,これは descriptions タグに対する format スタイルが定義され ているときに表示される。 descr の後ろには,1個か2個 の配列変数の名前が続き,さらに後ろに compadd に渡す オ プションが続く。 1個目の配列は,補完候補の単語と zsh 4.3.2 March 2, 2006 77 ZSHCOMPSYS(1) ZSHCOMPSYS(1) それに対する説明文字列 を `completion:description' の 書 式 で書いた要素を含むものである。 2個目の配列 は,1個目の配列と要素数が同じもので, 1個目配列に対 応 する補完候補単語として completion の代わりに 2個 目配列の対応する要素を追加する(△どういうときに役立 つの???)。説明文字列は1個目の配列にあったものがその まま残る。 配列の後ろにはいくつかのオプション を 指 定 す る。 Finally, a set of completion options can appear. 最 初の引数の前に `-o' オプションを指定すると,追加 する候補をそのコマンドのオプションとして扱うよう に す る。 典型的にはコマンドライン上で `-',`--',`+' に続けて書くものとして,それらの文字が入力されな い 限 り 一 覧 や説明文字列が出ない(□)。厳密には pre- fix-hidden, prefix-needed, verbose スタイルすべてを 参 照して,その補完候補を一覧に含めるか決める(□)。 `-o' の代わりに(□訳注: 原文にtypo) `-O' オプション にすると,prefix-needed スタイルは無視する。 `-t' オプションは tag を指定する。指定しないときの デフォルトのタグは,-o オプションを指定したときには `options' で,そうでないときは `values' である。 If selected by the list-grouped style, strings with the same description will appear together in the list. _describe uses the _all_labels function to generate the matches, so it does not need to appear inside a loop over tag labels. _description [ -x ] [ -12VJ ] tag name descr [ spec ... ] kokomade This function is not to be confused with the previous one; it is used as a helper function for creating options to compadd. It is buried inside many of the higher level completion func- tions and so often does not need to be called directly. The styles listed below are tested in the current context using the given tag. The resulting options for compadd are put into the array named name (this is traditionally `expl', but this convention is not enforced). The description for the corresponding set of matches is passed to the function in descr. The styles tested are: format, hidden, matcher, ignored-patterns and group-name. The format style is first tested for the given tag and then for the descriptions tag if no value was found, while the remainder are only tested for the tag given as the zsh 4.3.2 March 2, 2006 78 ZSHCOMPSYS(1) ZSHCOMPSYS(1) first argument. The function also calls _setup which tests some more styles. The string returned by the format style (if any) will be modified so that the sequence `%d' is replaced by the descr given as the third argument without any leading or trailing white space. If, after removing the white space, the descr is the empty string, the format style will not be used and the options put into the name array will not con- tain an explanation string to be displayed above the matches. If _description is called with more than three arguments, the additional specs should be of the form `char:str'. These supply escape sequence replacements for the format style: every appearance of `%char' will be replaced by string. If the -x option is given, the description will be passed to compadd using the -x option instead of the default -X. This means that the description will be displayed even if there are no correspond- ing matches. The options placed in the array name take account of the group-name style, so matches are placed in a separate group where necessary. The group normally has its elements sorted (by passing the option -J to compadd), but if an option starting with `-V', `-J', `-1', or `-2' is passed to _description, that option will be included in the array. Hence it is possible for the completion group to be unsorted by giving the option `-V', `-1V', or `-2V'. In most cases, the function will be used like this: local expl _description files expl file compadd "$expl[@]" - "$files[@]" Note the use of the parameter expl, the hyphen, and the list of matches. Almost all calls to compadd within the completion system use a similar format; this ensures that user-specified styles are cor- rectly passed down to the builtins which implement the internals of completion. _dispatch context string ... This sets the current context to context and looks for completion functions to handle this context by hunting through the list of command names or spe- cial contexts (as described above for compdef) given as string .... The first completion function zsh 4.3.2 March 2, 2006 79 ZSHCOMPSYS(1) ZSHCOMPSYS(1) to be defined for one of the contexts in the list is used to generate matches. Typically, the last string is -default- to cause the function for default completion to be used as a fallback. The function sets the parameter $service to the string being tried, and sets the context/command field (the fourth) of the $curcontext parameter to the context given as the first argument. _files The function _files calls _path_files with all the arguments it was passed except for -g and -/. The use of these two options depends on the setting of the file-patterns style. This function accepts the full set of options allowed by _path_files, described below. _gnu_generic This function is a simple wrapper around the _argu- ments function described above. It can be used to determine automatically the long options understood by commands that produce a list when passed the option `--help'. It is intended to be used as a top-level completion function in its own right. For example, to enable option completion for the commands foo and bar, use compdef _gnu_generic foo bar after the call to compinit. The completion system as supplied is conservative in its use of this function, since it is important to be sure the command understands the option `--help'. _guard [ options ] pattern descr This function is intended to be used in the action for the specifications passed to _arguments and similar functions. It returns immediately with a non-zero return status if the string to be com- pleted does not match the pattern. If the pattern matches, the descr is displayed; the function then returns status zero if the word to complete is not empty, non-zero otherwise. The pattern may be preceded by any of the options understood by compadd that are passed down from _description, namely -M, -J, -V, -1, -2, -n, -F and -X. All of these options will be ignored. This fits in conveniently with the argument-passing con- ventions of actions for _arguments. zsh 4.3.2 March 2, 2006 80 ZSHCOMPSYS(1) ZSHCOMPSYS(1) As an example, consider a command taking the options -n and -none, where -n must be followed by a numeric value in the same word. By using: _arguments '-n-: :_guard "[0-9]#" "numeric value"' '-none' _arguments can be made to both display the message `numeric value' and complete options after `-n'. If the `-n' is already followed by one or more digits (the pattern passed to _guard) only the message will be displayed; if the `-n' is fol- lowed by another character, only options are com- pleted. _message [ -r12 ] [ -VJ group ] descr _message -e [ tag ] descr _description 関数の第3引数と同様に descr を説明文字 列として使用する。ただしこちらは,マッチするもの が あっ てもなくても表示される。補完すべきものがないと きのヘルプメッセージを出すときに有用。 The format style is examined with the messages tag to find a message; the usual tag, descriptions, is used only if the style is not set with the former. If the -r option is given, no style is used; the descr is taken literally as the string to display. This is most useful when the descr comes from a pre-processed argument list which already contains an expanded description. The -12VJ options and the group are passed to com- padd and hence determine the group the message string is added to. The second form gives a description for completions with the tag tag to be shown even if there are no matches for that tag. The tag can be omitted and if so the tag is taken from the parameter $curtag; this is maintained by the completion system and so is usually correct. _multi_parts sep array The argument sep is a separator character. The array may be either the name of an array parameter or a literal array in the form `(foo bar)', a parenthesised list of words separated by whites- pace. The possible completions are the strings from the array. However, each chunk delimited by sep will be completed separately. For example, the _tar function uses `_multi_parts / patharray' to complete partial file paths from the given array of complete file paths. zsh 4.3.2 March 2, 2006 81 ZSHCOMPSYS(1) ZSHCOMPSYS(1) The -i option causes _multi_parts to insert a unique match even if that requires multiple separa- tors to be inserted. This is not usually the expected behaviour with filenames, but certain other types of completion, for example those with a fixed set of possibilities, may be more suited to this form. Like other utility functions, this function accepts the `-V', `-J', `-1', `-2', `-n', `-f', `-X', `-M', `-P', `-S', `-r', `-R', and `-q' options and passes them to the compadd builtin. _next_label [ -x ] [ -12VJ ] tag name descr [ options ... ] This function is used to implement the loop over different tag labels for a particular tag as described above for the tag-order style. On each call it checks to see if there are any more tag labels; if there is it returns status zero, other- wise non-zero. As this function requires a current tag to be set, it must always follow a call to _tags or _requested. The -x12VJ options and the first three arguments are passed to the _description function. Where appropriate the tag will be replaced by a tag label in this call. Any description given in the tag-order style is preferred to the descr passed to _next_label. The options given after the descr are set in the parameter given by name, and hence are to be passed to compadd or whatever function is called to add the matches. Here is a typical use of this function for the tag foo. The call to _requested determines if tag foo is required at all; the loop over _next_label han- dles any labels defined for the tag in the tag-order style. local expl ret=1 ... if _requested foo; then ... while _next_label foo expl '...'; do compadd "$expl[@]" ... && ret=0 done ... fi return ret zsh 4.3.2 March 2, 2006 82 ZSHCOMPSYS(1) ZSHCOMPSYS(1) _normal This is the standard function called to handle com- pletion outside any special -context-. It is called both to complete the command word and also the arguments for a command. In the second case, _normal looks for a special completion for that command, and if there is none it uses the comple- tion for the -default- context. A second use is to reexamine the command line spec- ified by the $words array and the $CURRENT parame- ter after those have been modified. For example, the function _precommand, which completes after pre-command specifiers such as nohup, removes the first word from the words array, decrements the CURRENT parameter, then calls _normal again. The effect is that `nohup cmd ...' is treated in the same way as `cmd ...'. If the command name matches one of the patterns given by one of the options -p or -P to compdef, the corresponding completion function is called and then the parameter _compskip is checked. If it is set completion is terminated at that point even if no matches have been found. This is the same effect as in the -first- context. _options This can be used to complete the names of shell options. It provides a matcher specification that ignores a leading `no', ignores underscores and allows upper-case letters to match their lower-case counterparts (for example, `glob', `noglob', `NO_GLOB' are all completed). Any arguments are propagated to the compadd builtin. _options_set and _options_unset These functions complete only set or unset options, with the same matching specification used in the _options function. Note that you need to uncomment a few lines in the _main_complete function for these functions to work properly. The lines in question are used to store the option settings in effect before the completion widget locally sets the options it needs. Hence these functions are not generally used by the com- pletion system. _parameters This is used to complete the names of shell parame- ters. The option `-g pattern' limits the completion to zsh 4.3.2 March 2, 2006 83 ZSHCOMPSYS(1) ZSHCOMPSYS(1) parameters whose type matches the pattern. The type of a parameter is that shown by `print ${(t)param}', hence judicious use of `*' in pattern is probably necessary. All other arguments are passed to the compadd builtin. _path_files This function is used throughout the completion system to complete filenames. It allows completion of partial paths. For example, the string `/u/i/s/sig' may be completed to `/usr/include/sys/signal.h'. The options accepted by both _path_files and _files are: -f Complete all filenames. This is the default. -/ Specifies that only directories should be completed. -g pattern Specifies that only files matching the pat- tern should be completed. -W paths Specifies path prefixes that are to be prepended to the string from the command line to generate the filenames but that should not be inserted as completions nor shown in completion listings. Here, paths may be the name of an array parameter, a literal list of paths enclosed in parenthe- ses or an absolute pathname. -F ignored-files This behaves as for the corresponding option to the compadd builtin. It gives direct control over which filenames should be ignored. If the option is not present, the ignored-patterns style is used. Both _path_files and _files also accept the follow- ing options which are passed to compadd: `-J', `-V', `-1', `-2', `-n', `-X', `-M', `-P', `-S', `-q', `-r', and `-R'. Finally, the _path_files function uses the styles expand, ambiguous, special-dirs, list-suffixes and file-sort described above. zsh 4.3.2 March 2, 2006 84 ZSHCOMPSYS(1) ZSHCOMPSYS(1) _pick_variant [ -c command ] [ -r name ] label=pattern ... label [ args ... ] compdef 関数中で 1つのコマンド名で複数の補完バリ エ ー ションを持たせるときに使う。現在補完中のコマンド 名に,引数の最後に指定した args を与えて起動し て, その出力に pattern にマッチするものがあればそれに対 応する label を選ぶ。 -r で変数を指定した場合には, そ れに選ばれたラベルが代入される。起動コマンド名を 変える場合は -c オプションを使う。指定したパター ン に マッチしなければ,最後に指定したデフォルトのラベ ル label が選ばれて,終了コードが1となる。 この結果は _cmd_variant 連想配列変数にキャッシュ さ れる。訳注: 原文面影なし。 _regex_arguments name spec ... This function generates a completion function name which matches the specifications spec ..., a set of regular expressions as described below. After run- ning _regex_arguments, the function name should be called as a normal completion function. The pat- tern to be matched is given by the contents of the words array up to the current cursor position joined together with null characters; no quotation is applied. The arguments are grouped as sets of alternatives separated by `|', which are tried one after the other until one matches. Each alternative consists of a one or more specifications which are tried left to right, with each pattern matched being stripped in turn from the command line being tested, until all of the group succeeds or until one fails; in the latter case, the next alternative is tried. This structure can be repeated to arbi- trary depth by using parentheses; matching proceeds from inside to outside. A special procedure is applied if no test succeeds but the remaining command line string contains no null character (implying the remaining word is the one for which completions are to be generated). The completion target is restricted to the remain- ing word and any actions for the corresponding pat- terns are executed. In this case, nothing is stripped from the command line string. The order of evaluation of the actions can be determined by the tag-order style; the various formats supported by _alternative can be used in action. The descr is used for setting up the array parameter expl. Specification arguments take one of following forms, in which metacharacters such as `(', `)', `#' and `|' should be quoted. zsh 4.3.2 March 2, 2006 85 ZSHCOMPSYS(1) ZSHCOMPSYS(1) /pattern/ [%lookahead%] [-guard] [:tag:descr:action] This is a single primitive component. The function tests whether the combined pattern `(#b)((#B)pattern)lookahead*' matches the command line string. If so, `guard' is evaluated and its return status is examined to determine if the test has succeeded. The pattern string `[]' is guaranteed never to match. The lookahead is not stripped from the command line before the next pattern is examined. The argument starting with : is used in the same manner as an argument to _alternative. A component is used as follows: pattern is tested to see if the component already exists on the command line. If it does, any following specifications are examined to find something to complete. If a component is reached but no such pattern exists yet on the command line, the string containing the action is used to generate matches to insert at that point. /pattern/+ [%lookahead%] [-guard] [:tag:descr:action] This is similar to `/pattern/ ...' but the left part of the command line string (i.e. the part already matched by previous pat- terns) is also considered part of the com- pletion target. /pattern/- [%lookahead%] [-guard] [:tag:descr:action] This is similar to `/pattern/ ...' but the actions of the current and previously matched patterns are ignored even if the following `pattern' matches the empty string. ( spec ) Parentheses may be used to groups specs; note each parenthesis is a single argument to _regex_arguments. spec # This allows any number of repetitions of spec. spec spec The two specs are to be matched one after the other as described above. zsh 4.3.2 March 2, 2006 86 ZSHCOMPSYS(1) ZSHCOMPSYS(1) spec | spec Either of the two specs can be matched. The function _regex_words can be used as a helper function to generate matches for a set of alterna- tive words possibly with their own arguments as a command line argument. Examples: _regex_arguments _tst /$'[^\0]#\0'/ \ /$'[^\0]#\0'/ :'compadd aaa' This generates a function _tst that completes aaa as its only argument. The tag and description for the action have been omitted for brevity (this works but is not recommended in normal use). The first component matches the command word, which is arbitrary; the second matches any argument. As the argument is also arbitrary, any following com- ponent would not depend on aaa being present. _regex_arguments _tst /$'[^\0]#\0'/ \ /$'aaa\0'/ :'compadd aaa' This is a more typical use; it is similar, but any following patterns would only match if aaa was pre- sent as the first argument. _regex_arguments _tst /$'[^\0]#\0'/ \( \ /$'aaa\0'/ :'compadd aaa' \ /$'bbb\0'/ :'compadd bbb' \) \# In this example, an indefinite number of command arguments may be completed. Odd arguments are com- pleted as aaa and even arguments as bbb. Comple- tion fails unless the set of aaa and bbb arguments before the current one is matched correctly. _regex_arguments _tst /$'[^\0]#\0'/ \ \( /$'aaa\0'/ :'compadd aaa' \| \ /$'bbb\0'/ :'compadd bbb' \) \# This is similar, but either aaa or bbb may be com- pleted for any argument. In this case _regex_words could be used to generate a suitable expression for the arguments. _regex_words tag description spec ... This function can be used to generate arguments for the _regex_arguments command which may be inserted at any point where a set of rules is expected. The tag and description give a standard tag and zsh 4.3.2 March 2, 2006 87 ZSHCOMPSYS(1) ZSHCOMPSYS(1) description pertaining to the current context. Each spec contains two or three arguments separated by a colon: note that there is no leading colon in this case. Each spec gives one of a set of words that may be completed at this point, together with arguments. It is thus roughly equivalent to the _arguments function when used in normal (non-regex) comple- tion. The part of the spec before the first colon is the word to be completed. This may contain a *; the entire word, before and after the * is completed, but only the text before the * is required for the context to be matched, so that further arguments may be completed after the abbreviated form. The second part of spec is a description for the word being completed. The optional third part of the spec describes how words following the one being completed are them- selves to be completed. It will be evaluated in order to avoid problems with quoting. This means that typically it contains a reference to an array containing previously generated regex arguments. The option -t term specifies a terminator for the word instead of the usual space. This is handled as an auto-removable suffix in the manner of the option -s sep to _values. The result of the processing by _regex_words is placed in the array reply, which should be made local to the calling function. If the set of words and arguments may be matched repeatedly, a # should be appended to the generated array at that point. For example: local -a reply _regex_words mydb-commands 'mydb commands' \ 'add:add an entry to mydb:$mydb_add_cmds' \ 'show:show entries in mydb' _regex_arguments _mydb "$reply[@]" _mydb "$@" This shows a completion function for a command mydb which takes two command arguments, add and show. show takes no arguments, while the arguments for add have already been prepared in an array mydb_add_cmds, quite possibly by a previous call to _regex_words. zsh 4.3.2 March 2, 2006 88 ZSHCOMPSYS(1) ZSHCOMPSYS(1) _requested [ -x ] [ -12VJ ] tag [ name descr [ command args ... ] ] This function is called to decide whether a tag already registered by a call to _tags (see below) has been requested by the user and hence completion should be performed for it. It returns status zero if the tag is requested and non-zero otherwise. The function is typically used as part of a loop over different tags as follows: _tags foo bar baz while _tags; do if _requested foo; then ... # perform completion for foo fi ... # test the tags bar and baz in the same way ... # exit loop if matches were generated done Note that the test for whether matches were gener- ated is not performed until the end of the _tags loop. This is so that the user can set the tag-order style to specify a set of tags to be com- pleted at the same time. If name and descr are given, _requested calls the _description function with these arguments together with the options passed to _requested. If command is given, the _all_labels function will be called immediately with the same arguments. In simple cases this makes it possible to perform the test for the tag and the matching in one go. For example: local expl ret=1 _tags foo bar baz while _tags; do _requested foo expl 'description' \ compadd foobar foobaz && ret=0 ... (( ret )) || break done If the command is not compadd, it must nevertheless be prepared to handle the same options. _retrieve_cache cache_identifier This function retrieves completion information from the file given by cache_identifier, stored in a directory specified by the cache-path style which defaults to ~/.zcompcache. The return status is zero if retrieval was successful. It will only attempt retrieval if the use-cache style is set, so zsh 4.3.2 March 2, 2006 89 ZSHCOMPSYS(1) ZSHCOMPSYS(1) you can call this function without worrying about whether the user wanted to use the caching layer. See _store_cache below for more details. _sep_parts (□)foo:bar のように、区切り文字で区切られた複数の 補完対象語を補完する。 This function is passed alternating arrays and sep- arators as arguments. The arrays specify comple- tions for parts of strings to be separated by the separators. The arrays may be the names of array parameters or a quoted list of words in parenthe- ses. For example, with the array `hosts=(ftp news)' the call `_sep_parts '(foo bar)' @ hosts' will complete the string `f' to `foo' and the string `b@n' to `bar@news'. This function accepts the compadd options `-V', `-J', `-1', `-2', `-n', `-X', `-M', `-P', `-S', `-r', `-R', and `-q' and passes them on to the com- padd builtin used to add the matches. _setup tag [ group ] This function sets up the special parameters used by the completion system appropriately for the tag given as the first argument. It uses the styles list-colors, list-packed, list-rows-first, last-prompt, accept-exact, menu and force-list. The optional group supplies the name of the group in which the matches will be placed. If it is not given, the tag is used as the group name. This function is called automatically from _description and hence is not normally called explicitly. _store_cache cache_identifier params ... This function, together with _retrieve_cache and _cache_invalid, implements a caching layer which can be used in any completion function. Data obtained by costly operations are stored in parame- ters; this function then dumps the values of those parameters to a file. The data can then be retrieved quickly from that file via _retrieve_cache, even in different instances of the shell. The cache_identifier specifies the file which the data should be dumped to. The file is stored in a directory specified by the cache-path style which defaults to ~/.zcompcache. The remaining params zsh 4.3.2 March 2, 2006 90 ZSHCOMPSYS(1) ZSHCOMPSYS(1) arguments are the parameters to dump to the file. The return status is zero if storage was success- ful. The function will only attempt storage if the use-cache style is set, so you can call this func- tion without worrying about whether the user wanted to use the caching layer. The completion function may avoid calling _retrieve_cache when it already has the completion data available as parameters. However, in that case it should call _cache_invalid to check whether the data in the parameters and in the cache are still valid. See the _perl_modules completion function for a simple example of the usage of the caching layer. _tags [ [ -C name ] tags ... ] If called with arguments, these are taken to be the names of tags valid for completions in the current context. These tags are stored internally and sorted by using the tag-order style. Next, _tags is called repeatedly without arguments from the same completion function. This succes- sively selects the first, second, etc. set of tags requested by the user. The return status is zero if at least one of the tags is requested and non-zero otherwise. To test if a particular tag is to be tried, the _requested function should be called (see above). If `-C name' is given, name is temporarily stored in the argument field (the fifth) of the context in the curcontext parameter during the call to _tags; the field is restored on exit. This allows _tags to use a more specific context without having to change and reset the curcontext parameter (which has the same effect). _values [ -O name ] [ -s sep ] [ -S sep ] [ -wC ] desc spec ... 「パラメータ=値」という形式の任意の並びを補完する。 `-O name' は If the first argument is the option `-O name', it will be used in the same way as by the _arguments function. In other words, the ele- ments of the name array will be passed to compadd when executing an action. If the first argument (or the first argument after `-O name') is `-s', the next argument is used as the character that separates multiple values. This zsh 4.3.2 March 2, 2006 91 ZSHCOMPSYS(1) ZSHCOMPSYS(1) character is automatically added after each value in an auto-removable fashion (see below); all val- ues completed by `_values -s' appear in the same word on the command line, unlike completion using _arguments. If this option is not present, only a single value will be completed per word. Normally, _values will only use the current word to determine which values are already present on the command line and hence are not to be completed again. If the -w option is given, other arguments are examined as well. The first non-option argument is used as a string to print as a description before listing the val- ues. All other arguments describe the possible values and their arguments in the same format used for the description of options by the _arguments function (see above). The only differences are that no minus or plus sign is required at the beginning, values can have only one argument, and the forms of action beginning with an equal sign are not sup- ported. The character separating a value from its argument can be set using the option -S (like -s, followed by the character to use as the separator in the next argument). By default the equals sign will be used as the separator between values and arguments. Example: _values -s , 'description' \ '*foo[bar]' \ '(two)*one[number]:first count:' \ 'two[another number]::second count:(1 2 3)' This describes three possible values: `foo', `one', and `two'. The first is described as `bar', takes no argument and may appear more than once. The second is described as `number', may appear more than once, and takes one mandatory argument described as `first count'; no action is specified, so it will not be completed. The `(two)' at the beginning says that if the value `one' is on the line, the value `two' will no longer be considered a possible completion. Finally, the last value (`two') is described as `another number' and takes an optional argument described as `second count' for which the completions (to appear after an `=') are `1', `2', and `3'. The _values function will complete lists of these values separated by commas. zsh 4.3.2 March 2, 2006 92 ZSHCOMPSYS(1) ZSHCOMPSYS(1) Like _arguments, this function temporarily adds another context name component to the arguments element (the fifth) of the current context while executing the action. Here this name is just the name of the value for which the argument is com- pleted. The style verbose is used to decide if the descrip- tions for the values (but not those for the argu- ments) should be printed. The associative array val_args is used to report values and their arguments; this works similarly to the opt_args associative array used by _arguments. Hence the function calling _values should declare the local parameters state, line, context and val_args: local context state line typeset -A val_args when using an action of the form `->string'. With this function the context parameter will be set to the name of the value whose argument is to be com- pleted. Note also that _values normally adds the character used as the separator between values as an auto-removable suffix (similar to a `/' after a directory). However, this is not possible for a `->string' action as the matches for the argument are generated by the calling function. To get the usual behaviour, the the calling function can add the separator x as a suffix by passing the options `-qS x' either directly or indirectly to compadd. The option -C is treated in the same way as it is by _arguments. In that case the parameter curcon- text should be made local instead of context (as described above). _wanted [ -x ] [ -C name ] [ -12VJ ] tag name descr command args ... In many contexts, completion can only generate one particular set of matches, usually corresponding to a single tag. However, it is still necessary to decide whether the user requires matches of this type. This function is useful in such a case. The arguments to _wanted are the same as those to _requested, i.e. arguments to be passed to _description. However, in this case the command is not optional; all the processing of tags, includ- ing the loop over both tags and tag labels and the zsh 4.3.2 March 2, 2006 93 ZSHCOMPSYS(1) ZSHCOMPSYS(1) generation of matches, is carried out automatically by _wanted. Hence to offer only one tag and immediately add the corresponding matches with the given description: local expl _wanted tag expl 'description' \ compadd matches... Note that, as for _requested, the command must be able to accept options to be passed down to com- padd. Like _tags this function supports the -C option to give a different name for the argument context field. The -x option has the same meaning as for _description. COMPLETION DIRECTORIES In the source distribution, the files are contained in various subdirectories of the Completion directory. They may have been installed in the same structure, or into one single function directory. The following is a description of the files found in the original directory structure. If you wish to alter an installed file, you will need to copy it to some directory which appears earlier in your fpath than the standard directory where it appears. Base The core functions and special completion widgets automatically bound to keys. You will certainly need most of these, though will probably not need to alter them. Many of these are documented above. Zsh Functions for completing arguments of shell builtin commands and utility functions for this. Some of these are also used by functions from the Unix directory. Unix Functions for completing arguments of external com- mands and suites of commands. They may need modi- fying for your system, although in many cases some attempt is made to decide which version of a com- mand is present. For example, completion for the mount command tries to determine the system it is running on, while completion for many other utili- ties try to decide whether the GNU version of the command is in use, and hence whether the --help option is supported. X, AIX, BSD, ... Completion and utility function for commands avail- able only on some systems. These are not arranged zsh 4.3.2 March 2, 2006 94 ZSHCOMPSYS(1) ZSHCOMPSYS(1) hierarchically, so, for example, both the Linux and Debian directories, as well as the X directory, may be useful on your system. zsh 4.3.2 March 2, 2006 95