ZSHCOMPSYS(1) ZSHCOMPSYS(1) NNAAMMEE zshcompsys - zsh 補完システム DDEESSCCRRIIPPTTIIOONN 訳注: ○は独自追加。△は怪しい意訳。□は原文からばっさり改 変。日本語追加部分は文責広瀬雄二(yuuji(@)gentei.org)。 ここではzshの「新しい」補完システム ccoommppssyyss について 述 べ る。 この補完システムは _z_s_h_c_o_m_p_w_i_d(1) で述べたシェル関数の 集合体で構築されている。 この補完システムは,コンテクストやカーソル位置によってうま く処理を切り替えるようにできている。最初から多くのコマンド に対する補完プログラムが用意されているのでユーザは初 期 設 定(次 のINITIALIZATION節) 以上のことは知らなくても随分楽が できるようになっている(□)。 コンテクストとは,どんな補完を施すのかを決めるコマンドライ ン上の文脈のことで, The context that decides what comple- tion is to be performed may be +o 引数位置かオプション位置の場合: そのコマンドライ ン 位 置がどんな補完が要求されるべき場所なのか。たとえ ば,「rmdir の第1引数位置」ならディレクトリ名。 +o 特別なコンテクスト: シェルの文法固有のルールが適 用 さ れる場所か。たとえば,「コマンド位置の単語」だと か,「配列の添字」だとか。 コンテクストそのものの詳細は追って述べる。 コマンド名やコンテクストだけでなく,この補完システムではス タ イル と タグ という概念を使用する。これらは,ユーザが補 完システムの挙動を調整するためのものである。 「タグ」は,ユーザが補完させたいであろう様々な単語群をいく つかの種別に分類するためのものである。たとえば, lleessss (□) と打ったら,そのあとに入れ て 欲 し い の は ディ レ ク ト リ(ddiirreeccttoorriieess)よ り も ファ イル(ffiilleess)のほうだろう。この ffiilleess と ddiirreeccttoorriieess がタグである(□ 訳注: 原文が冒頭と 言 う流れを全く無視しているので根本的に変えた) (読まんでええ ここから) 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 llss command the user may prefer to try ffiilleess before ddiirreeccttoorriieess, 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 zzssttyyllee command described in see _z_s_h_m_o_d_u_l_e_s(1). (ここまで) 大雑把に言えば,タグは補完すべきものが何なのか,スタイルは それらをどう補完するかを決めるものである(□)。 (読 まんでええ) In summary, tags describe _w_h_a_t the comple- tion objects are, and style hhooww 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 __mmaaiinn__ccoommpplleettee 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 _c_o_m_p_l_e_t_e_r_s, functions that implement individual completion strategies: simple completion, error correction, completion with error correction, menu selection, etc. (ここまで) 多くのシェル関数があるが, `ccoommpp' で始まるものは直接呼ばれ るもの,`__' で始まるものは補完プログラムから呼ばれるもので ある。後者のシェル関数は補完の挙動を決定するもので,たいて いは「ウィジェット」としてキーストロークに割り当てられる。 IINNIITTIIAALLIIZZAATTIIOONN zshが完全な形でインストールさ れ て い れ ば, ユ ー ザ は ccoommppiinniittを 呼 ぶ だ けで初期化が終わる(次節参照)。ただし, ccoommppiinnssttaallllを実行して補完システムのさらなる機能を設定す る こともできる。 通 常 ccoommppiinnssttaallll は ..zzsshhrrcc ファイルにコードを追加する。そ れに書けなければ別のファイルに書いてそのことを通知する。た zsh 4.3.2 March 2, 2006 2 ZSHCOMPSYS(1) ZSHCOMPSYS(1) だし追加したコードが実際に動くかどうかは自己責任で確認すべ きで,たとえば ..zzsshhrrcc の途中で return する可能性があるとき は足されたコードをもっと前の位置に動かす必要がある。足され たコードを(コメント行を含めて)まるごといじらないようにして お けば,どこに移動しても将来 ccoommppiinnssttaallll を再実行したとき に正しく場所を検出して修正してくれるが,もしそのコード群に 手 動で何か足したときは次の ccoommppiinnssttaallll でそれは消されるの で注意されたい(zzssttyylleeで始まる行はやんわりと処理される)。 新しく足されたコー ド は 次 にzshを 起 動 し た と き か, ..zzsshhrrccをsourceすれば有効になる。ただし, ccoommppiinnssttaallllによっ て削られた定義があるときは,その違いはシェルを再起動しない 限りわからない。 最初に ccoommppiinnssttaallll を実行する前に, ffppaatthh 変数に登録された ディレクトリ群のどれかに ccoommppiinnssttaallll があることを確認す る 必 要があるかもしれないが,正常にzshがインストールされた状 態で ffppaatthh の値を勝手に削ったりしていなければ問題ないは ず で ある(△)。 `aauuttoollooaadd --UU ccoommppiinnssttaallll' でautoloadできるは ずである。 ccoommppiinnssttaallll を起動すると ..zzsshhrrcc 情報表示とと も にプロンプトが出るのでいつでも中止できる。最後の最後に確認 が出るところまで一切 ..zzsshhrrcc は上書きされない。 ccoommppiinniittのの起起動動 ここでは,使用中のシェル環境で直接 ccoommppiinniitt を呼んで補完を 初 期化する方法について述べる。もし ccoommppiinnssttaallll が完了して いれば ..zzsshhrrcc の中で自動的に呼ばれることになる。 ccoommppiinniitt コマンドもやはり ffppaatthh 変数に登録されているディレ ク ト リ 群 のどれかに存在する必要がある。登録されていれば `aauuttoollooaadd --UU ccoommppiinniitt;; ccoommppiinniitt' で実行できるはずであ る。 ccoommppiinniittは い く つ かのシェル関数定義と必要なシェル関数の autoload定義処理と新しい補完システムで使うウィジェットを定 義 し なおす。もし mmeennuu--sseelleecctt ウィジェット(zzsshh//ccoommpplliissttモ ジュール)を使うのであれば, ccoommppiinniitt より先にそのモジュ ー ルをロードしておくようにする。補完スタイル(後述)が補完とと もに展開も行なうように 設 定 さ れ て い て, TABキ ー に eexxppaanndd--oorr--ccoommpplleettee を割り当てているときは ccoommppiinniitt はそれ を ccoommpplleettee--wwoorrdd に変えて展開が正しく行なわれるよ う に す る。 な お, 古い補完ウィジェットをそのまま使いたいときは,ウィ ジェットの名前にピリオド `..' を付けた名前をどれかのキー に 割 り 当 てればよい。たとえば, `..eexxaappnndd--oorr--ccoommpplleettee' とす る。 デフォルトで ccoommppiinniitt は読み込んだ設定をダンプしたも の を ファイルに書き出し 2回目以降の処理が高速に済むようにしてい る。これを無効化するには ccoommppiinniitt に --DD オプションを付けて 呼べばよい。ダンプファイルは ..zzccoommppdduummpp という名前で,各種 初期化ファイル群と同じディレクトリ($$ZZDDOOTTDDIIRRか $$HHOOMMEE)に置か れ る。 こ の ファイル名は --dd オプションで変更できる。次回 ccoommppiinniitt はダンプファイルをロードし,完全な初期化 は し な zsh 4.3.2 March 2, 2006 3 ZSHCOMPSYS(1) ZSHCOMPSYS(1) い。 補 完 定義ファイルが更新されたときは ccoommppiinniitt がそれを認識 し,ダンプファイルを作り直す。ただし,関数名や補完定義ファ イ ルの1行目にある ##ccoommppddeeff の引数を変えたときは,手動でダ ンプファイルを消して,次の ccoommppiinniitt に新規に作り直させてし まうのが一番面倒がない。この更新チェック機能は --CC オプショ ンで無効化され,その場合ダンプファイルがない場合のみ作り直 す。 実際のダンプ処理は下請けで呼ばれる ccoommppdduummpp 関数が行なって いる。手動で明示的にダンプファイルを作りたい場合以外は呼ぶ 必要はないだろう(□)。 変 数 __ccoommppddiirr にディレクトリ名を代入しておくと, ccoommppiinniitt はそのディレクトリを補完定義関数のある場所と見なす。 セキュリティ確保のため, ccoommppiinniitt はスーパーユーザ,または ユ ー ザ自身の所有でないファイル,所有者以外にも書き込める ディレクトリかどうかを調べる。該当する場合は ccoommppiinniitt が本 当に使うか確認する。こうした検査をやめ,みつかったファイル を確認なし使わせたい場合は --uu オプション,危険なファイルを 黙って無視させたい場合は --ii オプション,セキュリティチェッ クを完全にスキップさせたい場合は --CC オプションを指定すれば よい。 セ キュリティチェックは ccoommppaauuddiitt 関数を起動すればいつでも 行なえる。起動時にディレクトリを指定すればそのディレクトリ を,指定しなければ ffppaatthh と __ccoommppddiirr が検査される(□大分省 略)。 ccoommppiinniitt のときと厳密に同じ場所を調べ さ せ る に は __ccoommppddiirr 変数に空文字列を代入してから呼ぶこと。 オオーートトロローードドフファァイイルル 先述のとおり,補完で使用するオートロード関数はアンダースコ アで始める約束とし,それらのファイルが ffppaatthh//FFPPAATTHH 変数 の 指 し 示 す ディ レクトリに存在しなければならない(繰り返す がzshが正常にインストールされていればそうなっているはず で ある)。 インストールが不完全で, ccoommppiinniitt がアンダースコアで始まる ファイルを20個以上探せなかった場合は, __ccoommppddiirr 変数の値を 追加して探す。もしそこに BBaassee というサブディレクトリがみつ かれば,同じ階層のすべてのサブディレクトリを,さらに BBaassee の下に CCoorree というサブディレクトリがみつかれば,そこにある すべてのサブディレクトリを追加する。これは,zshのソース 配 布に含まれるディレクトリを想定した挙動で,これを活かすには _compinit にソースを展開したディレクト リ の ..//CCoommpplleettiioonn ディレクトリを代入しておけばよいことになる(○)。 ccoommppiinniitt は, ffppaatthh//FFPPAATTHHにあるすべてのファイルの1行目を調 べ,特定のタグがあれば処理し,なければ無視する。 タグの書式は以下のどれか: zsh 4.3.2 March 2, 2006 4 ZSHCOMPSYS(1) ZSHCOMPSYS(1) ##ccoommppddeeff _n_a_m_e_s_._._. [ --[[ppPP]] _p_a_t_t_e_r_n_s_._._. [ --NN _n_a_m_e_s_._._. ] ] そのファイルをautoload登録し,_n_a_m_e_s を補完すると き に そ こ に定義されている関数が呼ばれるように設定す る。 _n_a_m_e_sは引数入力を補完して欲しいコマンドの名 前 か, --_c_o_n_t_e_x_t-- という書式で指定する特別なコンテクス ト(文脈) 指定のどれかを書く。 (or one of a number of special contexts in the form --_c_o_n_t_e_x_t-- described below.) _n_a_m_eの部分には `_c_m_d==_s_e_r_v_i_c_e' という記述も書け,その 場合 _c_m_d を補完するときに,_s_e_r_v_i_c_e を補完するときと 同じ挙動をするようになる。これは,そこで定義して い る 補完用関数の挙動を変えるために利用できる。実際に はその関数が呼ばれるときに,どのコマンドの補完を す る ために呼ばれたのかを変数 $$sseerrvviiccee に代入してくれ るので,関数作成時にはその値で処理を切り替えると よ い。もちろんその値を使わなくても構わない(□)。 ##ccoommppddeeff の行に --pp か --PP オプションがある場合は,後 続する引数(群)がパターンとして解釈され,そのパタ ー ン(の どれか)にマッチするコマンド(または文脈)に対す る補完をするときに関数が呼ばれるようになる。 --pp は 他 の補完を試す前, --PP は試したあとに呼ばれるパター ンを指定する。よって, --PP はデフォルトの挙動を指 定 するときに使える。 --NN オプションは, --pp や --PP オプションに続けて書いた パターンのあとに指定して,以後の引数はパターン指 定 でないことを指示する。 ##ccoommppddeeff --kk _s_t_y_l_e _k_e_y_-_s_e_q_u_e_n_c_e_s_._._. 内部ウィジェット _s_t_y_l_e と同様に振る舞うウィジェット を作り _k_e_y_-_s_e_q_u_e_n_c_e_s に割り当てる。 _s_t_y_l_e には, 補 完機能を持つ内部ウィジェットのどれか,すなわち ccoomm-- pplleettee--wwoorrdd, ddeelleettee--cchhaarr--oorr--lliisstt, eexxppaanndd--oorr--ccoomm-- pplleettee, eexxppaanndd--oorr--ccoommpplleettee--pprreeffiixx, lliisstt--cchhooiicceess, mmeennuu--ccoommpplleettee, mmeennuu--eexxppaanndd--oorr--ccoommpplleettee, rreevveerrssee--mmeennuu--ccoommpplleettee の ど れかを指定する。もし, zzsshh//ccoommpplliisstt モジュール( _z_s_h_m_o_d_u_l_e_s(1)参照) がロ ー ドされている場合は mmeennuu--sseelleecctt も指定可能。 _k_e_y_-_s_e_q_u_e_n_c_e_s で指定したどれかのキーがタイプされる とそのファイルで定義されている関数がマッチ単語を 生 成 するために呼ばれる。ただし,指定したキーストロー クに既に別の機能が割り当ててある場合はそのキーへ の 割 り 当 ては行なわれない。作成されるウィジェットは ファイル名と同じ名前で, bbiinnddkkeeyyコマンドで普通に 割 り当てできるものとなる。 ##ccoommppddeeff --KK _w_i_d_g_e_t_-_n_a_m_e _s_t_y_l_e _k_e_y_-_s_e_q_u_e_n_c_e_s ... --kkと 同様だが,ひとつの _w_i_d_g_e_t_-_n_a_m_e と _s_t_y_l_e の組み 合わせに対し,ひとつの _k_e_y_-_s_e_q_u_e_n_c_e_s だけが指定でき る。この3つの引数の組み合わせを何個でも書ける。その 場合 _w_i_d_g_e_t_-_n_a_m_e が重複しないようにする。最初の文字 zsh 4.3.2 March 2, 2006 5 ZSHCOMPSYS(1) ZSHCOMPSYS(1) が `__' で始まっていない場合は補われる。 _w_i_d_g_e_t_-_n_a_m_e の名前は,他のウィジェットと衝突しないようにしな け れ ばならないので,関数名に由来した名前を付けるとよ い。たとえば, ##ccoommppddeeff --KK __ffoooo__ccoommpplleettee ccoommpplleettee--wwoorrdd ""^^XX^^CC"" \\ __ffoooo__lliisstt lliisstt--cchhooiicceess ""^^XX^^DD"" (実際には1行で記述する) のような名前付けをする。 こ の例の場合, __ffoooo__ccoommpplleettee ウィジェットを補完用と定 義して, `^^XX^^CC'に割り当て, __ffoooo__lliisstt ウィジェッ ト を一覧出力用に定義して `^^XX^^DD' に割り当てている。 ##aauuttoollooaadd [ _o_p_t_i_o_n_s ] ##aauuttoollooaadd タグはその関数をautoload登録するのみで, 他の処理は行なわないことを指示する。典型的には, 補 完 関数の下請け関数をautoload化したりするために用い る。 _o_p_t_i_o_n_s を続けて 書 く と そ れ を そ の ま ま aauuttoollooaaddコ マンドに渡す。たとえば, ++XX を書いて,そ の関数を直ちにロードさせたりできる。オートロード の 際 には常に --UU,--zz オプションが暗黙のうちに有効化さ れる。 タグに書く ## 文字もタグ名に含まれるため,その後に空白を 書 い てはいけない。 ##ccoommppddeeff タグは後述する ccoommppddeeff 関数で処 理される。 ccoommppddeeff関数は補完用関数名を明示的に指定する必要 があるが,タグの方は暗黙のうちに決められるという点が異って いる。 どのような文脈で呼ばれる関数が定義されるかのコンテクスト指 定 は 下記のいずれか: (The special contexts for which com- pletion functions can be defined are:) --aarrrraayy--vvaalluuee-- 配列への代入時の右辺の位置 (`ffoooo==((......))') --bbrraaccee--ppaarraammeetteerr-- 中括弧内での変数名の展開 (`$${{......}}') --aassssiiggnn--ppaarraammeetteerr-- 変数代入時の変数名(`=='の左側) --ccoommmmaanndd-- コマンド位置での単語 --ccoonnddiittiioonn-- 条件式 (`[[[[......]]]]') 内の単語 --ddeeffaauulltt-- 他の補完が定義されていないときのデフォルトの補完 --eeqquuaall-- イコール記号で始まる単語 zsh 4.3.2 March 2, 2006 6 ZSHCOMPSYS(1) ZSHCOMPSYS(1) --ffiirrsstt-- すべての補完に先だって呼ばれる。呼ばれる関数では そ の 後本来呼ばれる補完機能をキャンセルするための変数 __ccoommppsskkiipp に値を設定できる。意味ある値は,aallll: その 後 の補完機能は一切呼ばない, ppaatttteerrnnss という文字列 を含む文字列: パターン補完関数(訳注: なに そ れ???) を 呼 ば な い,ddeeffaauulltt と いう文字列を含む文字列: `--ddeeffaauulltt--' コンテクスト用の補完関数を呼ばない(その コマンド用の補完関数は呼ぶ),のいずれかである。 --mmaatthh-- `((((...))))' の内部のような数式コンテクスト --ppaarraammeetteerr-- 変数名展開(`$$......') --rreeddiirreecctt-- リダイレクション記号の後の単語 --ssuubbssccrriipptt-- 変数の添字の中味. --ttiillddee-- `~~' 記号の後でスラッシュより前の単語 --vvaalluuee-- 代入の右側 上記のどのコンテクストにもデフォルトの補完関数が用意されて いて,それらはコンテクスト名の前に __ を付けた名前になっ て い る。 たとえば, `--ttiillddee--' 用のデフォルト関数は `__ttiillddee' である(□)。 --rreeddiirreecctt-- と --vvaalluuee-- コンテクストには追加で,コンテクスト 依存の情報を指定できる(内部的には __ddiissppaattcchh 関数で処理され る)。追加情報はカンマで区切って指定する。 --rreeddiirreecctt-- コンテ ク ス ト で は, 追 加 情 報 は `--rreeddii-- rreecctt--,,_o_p,,_c_o_m_m_a_n_d' の形式で指定する。ここで _o_p はリダイレク ション記号,_c_o_m_m_a_n_d はそのコマンドラインに書かれたコマンド である。コマンドラインにコマンドが書かれていない状態の指定 は _c_o_m_m_a_n_d 欄は空となる。訳 注: _c_o_m_m_a_n_d の 部 分 に は, `_c_m_d==_s_e_r_v_i_c_e' という記述も書ける。 --vvaalluuee-- コンテクストの追加情報は `--vvaalluuee--,,_n_a_m_e,,_c_o_m_m_a_n_d' と いう形式で指定する。ここで _n_a_m_e は変数名である。もし連想配 列の要素で補完を行なう場合,例えば `aassssoocc==((kkeeyy <>' のと き, _n_a_m_e は `_n_a_m_e--_k_e_y' に展開される。また,`mmaakkee CCFFLLAAGGSS==' ま でタイプして補完した場合などは, _c_o_m_m_a_n_d の部分がそのコ マンド(つまり mmaakkee)になり,それ以外の場合は空になる(□)。 このコンテクスト追加情報は,すべて厳密に決めたものからだん だん緩いコンテクストへと順次試されるので,必ずしもすべて厳 密に決めたコンテクスト追加情報を与えておく必要はない。要す る にたとえば, `ffoooo==<>' という補完を行なうとき,その補 zsh 4.3.2 March 2, 2006 7 ZSHCOMPSYS(1) ZSHCOMPSYS(1) 完を受け持つ __vvaalluuee という関数はまず `--vvaalluuee--,,ffoooo,,' という コンテクストを調べる(最後のカンマの右側は _c_o_m_m_a_n_d が空とい う こ と を 意 味 し て い る)。 続 い て `--vvaalluuee--,,ffoooo,,--ddeeffaauulltt--',`--vvaalluuee--,,--ddeeffaauulltt--,,--ddeeffaauulltt--' と いう順番にそのコンテクストでの補完が定義されているかを調べ て行く。 例(1): ccoommppddeeff ''__ffiilleess --gg ""**..lloogg""'' ''--rreeddiirreecctt--,,22>>,,--ddeeffaauulltt--'' `22>> <>' という文字列の後では,とくにそのコマンド用の補 完が定義されていないコマンドのときには `**..lloogg' にマッチ す るファイル名を補う。 例(2): ccoommppddeeff __ffoooo --vvaalluuee--,,--ddeeffaauulltt--,,--ddeeffaauulltt-- 変 数 への代入で,とくに指定のない場合は __ffoooo 関数が補完す る。通常は __vvaalluuee 関数がその処理をしている。 上記例(1)と同じルールはスタイル(後述)を用いて以下のよう に も指定できる。 zzssttyyllee ''::ccoommpplleettiioonn::**::**::--rreeddiirreecctt--,,22>>,,**::**'' ffiillee--ppaatttteerrnnss ''**..lloogg'' zzssttyyllee コマンドがスタイルを定義するものである(□)。 FFuunnccttiioonnss 以下の関数群は ccoommppiinniitt 呼出しにより定義される。 ccoommppddeeff [ --aann ] _f_u_n_c_t_i_o_n _n_a_m_e_s_._._. [ --[[ppPP]] _p_a_t_t_e_r_n_s_._._. [ --NN _n_a_m_e_s_._._. ] ] ccoommppddeeff --dd _n_a_m_e_s_._._. ccoommppddeeff --kk [ --aann ] _f_u_n_c_t_i_o_n _s_t_y_l_e _k_e_y_-_s_e_q_u_e_n_c_e_s_._._. ccoommppddeeff --KK [ --aann ] _f_u_n_c_t_i_o_n _n_a_m_e _s_t_y_l_e _k_e_y_-_s_e_q_u_e_n_c_e_s _._._. 第1の 書式は,指定したコンテクスト(##ccoommppddeeff記法のと きと同様の指定)のときの補完に _f_u_n_c_t_i_o_n 関数を呼ぶこ とを定義する。 や はり ##ccoommppddeeff 記法のときと同様引数は, `_c_m_d==_s_e_r_- _v_i_c_e' のようにも書ける。ただしその場合既に ##ccoommppddeeff で 別の `_c_m_d_1==_s_e_r_v_i_c_e' が定義されていなければならな い(訳注: $serviceで挙動を変えるような関数になってい ないといきなり `_c_m_d==_s_e_r_v_i_c_e' で別名定義しても挙動が 怪しいから)。 引数の _f_u_n_c_t_i_o_n には関数でなく,シェルの文を含む 文 字 列を書くこともできる。その文字列は補完単語群を生 成するため内部コマンド eevvaall で評価される。これ は, 単 純 が ゆえいちいち関数を定義したくない場合に便利 で,たとえば ffoooo コマンドの引数として単に `..hh' ファ zsh 4.3.2 March 2, 2006 8 ZSHCOMPSYS(1) ZSHCOMPSYS(1) イルだけを補完させたいのであれば, ccoommppddeeff ''__ffiilleess --gg ""**..hh""'' ffoooo とすればよい(訳注: __ffiilleess関数はファイルの補完単語を 生成する既定の関数)。 --nn オプションは,そのコマンドやコンテクスト用に既に 補 完が定義されている場合に上書き設定しないことを指 示する。 --dd オプションはコマンドやコンテクスト用の補完定義を 削除する。 ##ccoommppddeeff のときと同様,_n_a_m_e_s の部分には --pp, --PP and --NN オプションを指定できる(意味も ##ccoommppddeeff のとき と 同じ(パターン指定の切り替え)□)。 パ タ ー ン コ ン テ クストで呼ばれる関数では,変数 $$__ccoommppsskkiipp に値を設定してその他の補完関数が呼ばれる か を制御できる。 `ppaatttteerrnnss' という文字列を含む文字 列を指定するとパターン関数(訳注: って何???)が呼ばれ なくなり, `aallll' という文字列を含む文字列を指定する と他の関数が全く呼ばれなくなる。 --kk と --KK オプションの書式は ##ccoommppddeeff のときと同じ。 明 示 的 に 関数を指定するかどうかの違い(訳注: 要実 験)。 どの書式でも適用可能なオプション --aa は _f_u_n_c_t_i_o_n を オートロード化する。 aauuttoollooaadd --UU _f_u_n_c_t_i_o_n と等価。 ccoommppddeeff 関数を用いて,既存の補完関数を新しいコマンドに適用 させることもできる。たとえは, ccoommppddeeff __ppiiddss ffoooo とすると,ffoooo というコマンドの引数補完で __ppiiddss 関数を呼 び プロセスIDを補完させられるようになる。 ちなみに,後述する __ggnnuu__ggeenneerriicc 関数は `----hheellpp' オプション を受け付けるコマンドの補完をある程度自動的に行なう(□)。 CCOONNFFIIGGUURRAATTIIOONN この節ではまず補完システムの動き方の概要を述べ,続いてどの タイミングでどう補完単語を生成させるかをユーザが設定する方 法について詳しく説明していく。 概概要要 コマンドラインのどこかで呼び出された補完機能は,最初にコン テ ク ス ト を 調べる。コマンドの単語(たとえば `ggrreepp' なの か,`zzsshh なのか),カーソル位置の単語が引数に見なされるよう zsh 4.3.2 March 2, 2006 9 ZSHCOMPSYS(1) ZSHCOMPSYS(1) な オ プション(たとえば zzsshh の `--oo' オプションはシェルオプ ションを引数に取る) などなど。 こうしたコンテクスト情報はコロンで区切られた複数のフィール ドを持つ文字列に圧縮される。以後コンテクストと言ったらその 文字列で表現する。コンテクストはem(スタイル)というコンテク ス ト に影響を受けるオプションを探すために用いられ,それに よって補完システムを設定する(訳注: うーん漠然としすぎ じゃ ん)。 検索に使われるコンテクストは,同じ補完システムを呼ぶ 場合でも様々な値に変わる(△)。 コンテクストを表す文字列は,先頭にあるコロン文字に続けて常 に決まったフィールドを持つ以下のようなものである。 ::ccoommpplleettiioonn::_f_u_n_c_t_i_o_n::_c_o_m_p_l_e_t_e_r::_c_o_m_m_a_n_d::_a_r_g_u_m _e_n_t::ttaagg. 各フィールドの意味は以下のとおり。 +o ccoommpplleettiioonn という文字列そのもの(□): +o _f_u_n_c_t_i_o_n: 通 常 の補完システム経由でなく,名前つき ウィジェットから補完が呼ばれた場合の関数名。たい て い は 空 だ が,pprreeddiicctt--oonn のような特殊ウィジェット や,zshのソースディレクトリの WWiiddggeett ディレクトリに ある関数によってなんらかの値がセットされる。 +o _c_o_m_p_l_e_t_e_r: 稼動中のコンプリータで,関数名の先頭のア ンダースコアをとり,途中にあるアンダースコアをハ イ フ ンに変えた名前。コンプリータはどのように補完する かを統轄するもので,もっとも単純な `ccoommpplleettee' を 始 め, 綴り修正,その後のコンプリータの挙動を変えるた めのものなどいくつかある。「Control Functions」の節 参照。 +o _c_o_m_m_a_n_d ま たは --_c_o_n_t_e_x_t--: ##ccoommppddeeff タグや ccoommppddeeff のところで登場したもの。サブコマンドを持つコマン ド の 補完のときには,このフィールドにコマンド名とサブ コマンド名をハイフンで繋いだものがセットされる。 た とえば,ccvvss の aadddd サブコマンドの補完を行なうときに は,このフィールドが ccvvss--aadddd になる。 +o _a_r_g_u_m_e_n_t: どのコマンドライン,オプション引数の補 完 をしているのかを示す文字列。コマンドの(オプション引 数でない) _n番目の引数ならば, aarrgguummeenntt--_n に,_o_p_tと い うオプションの _n 番目の引数ならば, ooppttiioonn--_o_p_t--_n となる。ただし,コマンドラインが標準的なUnix流オ プ ショ ン・引数表記ルールで解析される場合のみ有効で, これがセットされない場合も少なくない(□)。 zsh 4.3.2 March 2, 2006 10 ZSHCOMPSYS(1) ZSHCOMPSYS(1) +o _t_a_g: マッチさせる対象物の種別を区別させるために使う もので,詳細は次に挙げる例で説明する(□□)。 コ ンテクストは,補完機能が働く入口のところで ::ccoommpplleettiioonn:: (と必要なら関数名var(function))だけが足された状態 か ら 始 まって,各種関数が呼ばれる毎にどんどん構築されていく。そう してコンプリータが _c_o_m_p_l_e_t_e_r 要素を足し,コンテクスト補 完 が _a_d_d と _a_r_g_u_m_e_n_t オプションを足し,最後に,どういう種類 の単語を補完したいのかが判明した時点で _t_a_g が足される。 一例を挙げる。 ::ccoommpplleettiioonn::::ccoommpplleettee::ddvviippss::ooppttiioonn--oo--11::ffiilleess というコンテクストは,ddvviippss コマンドの --oo オ プ ショ ン の 第1引 数 で は通常(ファイル)補完を試みることを示している。 よって, ddvviippss --oo ...... というコマンドラインでの補完関数はファイル名を生成する。 与えられたコンテクストにおいてどんな種類の補完を実行できる か は,上の例で出てきた ffiilleess を始めとする「タグ」という文 字列で表現される。どの補完関数も任意のタグ名を使って構わな いが,一般的なものはあらかじめ決められている(一覧を後述)。 ?????????????????????????????ここは削ってよい箇所 通常補完機能は,補完関数から渡された順番ですべてのタグに対 し て試される。この順番は ttaagg--oorrddeerr スタイルで変更できる。 補完は渡されたタグを渡された順番に行なうだけに 限 定 で き る(△)。 実際に,どういうコンテクストでどういうタグの補完をさせるか を知るためのキー割り当て可能な内部コマンド __ccoommpplleettee__hheellpp を使って見ることができる。(訳注: __ccoommpplleettee__hheellpp はデフォル トで ^^XXhh に割り当てられているので,これを `ddvviippss --oo ' まで 入 力 し た ところでタイプしてみるとよい。) これを用いると ttaagg--oorrddeerr やその他のスタイルの詳細が分かる。後述する`Bind- able Command'の節参照。 「スタイル」とはどのようにマッチするものを生成するかを決定 する,シェルオプションをより一層強力にしたようなもので,文 字列で表される値を何個でも持たせられる。スタイルは内部コマ ンドの zzssttyyllee (_z_s_h_m_o_d_u_l_e_s(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. たとえば,多くの補完関数はマッチす る 単 語 群 を 一 覧 表 示(lliisstt--cchhooiicceess□)する方法として,簡素バージョン,お節介バ ージョンの2つを持っていて,どちらを選ぶかは vveerrbboossee スタイ ルの値で変更できるようになっている。そういう風に作ってある 補完関数すべてでお節介バージョンを選びたければ, zzssttyyllee ''::ccoommpplleettiioonn::**'' vveerrbboossee yyeess を初期化ファイル(おそらく ..zzsshhrrcc) に入れるとよい。この文は 補完システム(ccoommpplleettiioonn)内のすべて(**)のコンテクストの vveerr-- bboossee スタイルに yyeess をセットしている。実際にはすべて で な く,** よりも限定的に設定しているスタイル指定にマッチするコ ンテクストであればそちらが使用される。補完システム以外に影 響 を与えるといけないので,パターンとしては `**' だけでなく `::ccoommpplleettiioonn::**' を与えるべきである(□)。 ちなみに,ccoommppiinnssttaallll を使って多くの汎用スタイルを設定する ことができる。 ssttyyllee の 使用をより限定的に指定する例として,内部コマンド kkiillll の補完を示す。この補完では vveerrbboossee スタイルがセットさ れ ていると (マッチする単語の一覧表示のときに□),ジョブの テキストとプロセスのコマンドラインをすべて出力し,スタイル が オフのときはジョブ番号とPIDのみを出力する。スタイルをオ フにしたい場合は, zzssttyyllee ''::ccoommpplleettiioonn::**::**::kkiillll::**'' vveerrbboossee nnoo とする。もし,もっと限定的にしたいのであ れ ば `jjoobbss' か `pprroocceesssseess' タ グ を 明示的に指定する。ジョブに関してだけ vveerrbboossee スタイルをオフにしたければ次のようにすればよい。 zzssttyyllee ''::ccoommpplleettiioonn::**::**::kkiillll::**::jjoobbss'' vveerrbboossee nnoo zzssttyyllee の --ee オプションを用いると,補完関数に関数的な文 を 直接指定できる(□)。 zzssttyyllee --ee ''::ccoommpplleettiioonn::**'' hhoossttss ''rreeppllyy==(($$mmyyhhoossttss))'' こ れは,ホスト名補完が必要なときに hhoossttss スタイルの値を変 数 mmyyhhoossttss から取得させる。もし mmyyhhoossttss の値が変動するなら 有用かもしれない。他の有用な例については後述する ffiillee--lliisstt スタイルを参照。ただし,--eeオプションは速度低下の恐れがある の で mmeennuu や lliisstt--rroowwss--ffiirrsstt スタイルと組み合わせない方が よい。 マッチするスタイル定義が複数あるような場合どれが選ばれるか は, zzssttyylleeでそれらを定義した順番ではなく,どちらがより限 定的なルールで書かれているかによって決まる。たとえば,リテ ラ ル 文 字 列はパターンを使用したものより優先されるので, `::ccoommpplleettiioonn::::ccoommpplleettee::ffoooo' は, `::ccoommpplleettiioonn::::ccoommpplleettee::**'' zsh 4.3.2 March 2, 2006 12 ZSHCOMPSYS(1) ZSHCOMPSYS(1) よりも限定的と見なされる。また,パターンを用いているものど うしでは,より長い(詳細な)パターンを使っているもののほうが 短い(大雑把な)パターンよりも優先される(□)。 スタイル名は,タグ名と同様各補完関数で任意に決められるが, これもまた既定のものがあるので次とその次の節で一覧を示す。 標標準準タタググ 下記一覧のうちいくつかは,特殊なスタイルを探すときに使われ るだけで,マッチする単語の種別を示すものではない。 aaccccoouunnttss uusseerrss--hhoossttss スタイルを探すために用いられる(△???) aallll--eexxppaannssiioonnss __eexxppaanndd コンプリータが,1つの文字列にマッチするもの すべてを挿入するときに用いられる aallll--ffiilleess すべてのファイル名(△???)(下記 gglloobbbbeedd--ffiilleess タグも 参照) aarrgguummeennttss コマンドに対する引数 aarrrraayyss 配列変数名 aassssoocciiaattiioonn--kkeeyyss 連想配列のキー(連想配列変数の添字を補完する場合に使 われる) bbooookkmmaarrkkss ブッ ク マークを補完するときに使われる (e.g. URL や (zftp) モジュール) bbuuiillttiinnss 内部コマンドの名前 cchhaarraacctteerrss 1文字 (ssttttyy コマンドで制御文字を入力する部分や, 開 き大括弧の後でキャラクタクラスを書く場合など) ccoolloorrmmaappiiddss XのカラーマップID ccoolloorrss 色の名前 ccoommmmaannddss 外部コマンドの名前で,ccvvssのような複雑なコマンドの補 完でサブコマンド一覧を得るためなどに用いる ccoonntteexxttss 内部コマンド zzssttyyllee に与えるコンテクスト文字列 zsh 4.3.2 March 2, 2006 13 ZSHCOMPSYS(1) ZSHCOMPSYS(1) ccoorrrreeccttiioonnss __aapppprrooxxiimmaattee と __ccoorrrreecctt コンプリータが,適当な修正 のために使う。 ccuurrssoorrss Xプログラムのカーソル名 ddeeffaauulltt デ フォルトのタグ: 別のより限定的なタグが有効な場合 のデフォルトを与えるために使われる(△???)。このタグ は コンテクスト文字列の _f_u_n_c_t_i_o_n フィールドがセット されている場合のみ有効。 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 _f_u_n_c_t_i_o_n field of the context name is set ddeessccrriippttiioonnss マッチの種別を記述するため ffoorrmmaatt スタイルの値を 調 べるときに使う ddeevviicceess デバイスファイルの名前 ddiirreeccttoorriieess ディレクトリ名 ddiirreeccttoorryy--ssttaacckk ディレクトリスタックのエントリ ddiissppllaayyss Xのディスプレイ名 ddoommaaiinnss ネットワークドメイン名 eexxppaannssiioonnss コ マンドライン上の1語を展開した結果生ずる語を1個ず つ順番に出すためのタグで,__eexxppaannddコンプリータによっ て使われる。 eexxtteennssiioonnss Xサーバのエクステンション ffiillee--ddeessccrriippttoorrss ファイルディスクリプタ ffiilleess ファ イル名補完で用いられる汎用ファイル名マッチのタ グ ffoonnttss Xのフォント名 ffssttyyppeess mmoouunnttコマンドなどで用いるファイルシステムタイプの名 zsh 4.3.2 March 2, 2006 14 ZSHCOMPSYS(1) ZSHCOMPSYS(1) 前 ffuunnccttiioonnss 関 数名 -- 通常はシェル関数だが特定のコマンドは別の 種類の関数を把握する gglloobbbbeedd--ffiilleess パターンマッチで生成されるファイル名 ggrroouuppss グループ名 hhiissttoorryy--wwoorrddss ヒストリリストにある単語 hhoossttss ホスト名 iinnddeexxeess 配列の添字 jjoobbss ジョブ名(内部コマンド`jjoobbssで得られるもの) iinntteerrffaacceess ネットワークインタフェース名 kkeeyymmaappss zshのキーマップ名 kkeeyyssyymmss Xのkeysyms lliibbrraarriieess システムライブラリ名 lliimmiittss リソースリミット llooccaall--ddiirreeccttoorriieess ccdd コマンド等の引数補完時の,カレントディレクトリに あるサブディレクトリ (ppaatthh--ddiirreeccttoorriieessも参照) mmaannuuaallss manにあるマニュアル名 mmaaiillbbooxxeess メイルフォルダ名 mmaappss マップ名(NISマップなど) mmeessssaaggeess メッ セージ用の ffoorrmmaatt スタイルを調べるときに使われ る mmooddiiffiieerrss Xのモディファイア名(訳 注: Shift, Control, Mod1, Mod2, ...) zsh 4.3.2 March 2, 2006 15 ZSHCOMPSYS(1) ZSHCOMPSYS(1) mmoodduulleess モジュール名 (zzsshh モジュール) mmyy--aaccccoouunnttss uusseerrss--hhoossttss スタイルを調べるときに使われる nnaammeedd--ddiirreeccttoorriieess 名前つきディレクトリ nnaammeess すべての種類の名前 nneewwssggrroouuppss USENET のニュースグループ nniicckknnaammeess NISマッ プのニックネーム(訳注: マップ名tt(passwd)は ニックネーム) ooppttiioonnss コマンドオプション oorriiggiinnaall __aapppprrooxxiimmaattee,__ccoorrrreecctt,__eexxppaanndd コンプリータが最 初 の文字列をマッチとして提示するときに使われる ootthheerr--aaccccoouunnttss uusseerrss--hhoossttss スタイルを調べるときに使われる ppaacckkaaggeess でびあんのぱっけーじ ppaarraammeetteerrss 変数名 ppaatthh--ddiirreeccttoorriieess ccddな どのディレクトリ移動系内部コマンドの引数を補完 するときに, ccddppaatthh変数に登録されたディレクトリ群か らみつかるサブディレクトリ (llooccaall--ddiirreeccttoorriieessと比較 せよ) ppaatthhss eexxppaanndd,aammbbiigguuoouuss,ssppeecciiaall--ddiirrss スタイルの値を調 べ るときに使われる(△???) ppooddss Perl pods(ドキュメントファイル) ppoorrttss ネットワークポート pprreeffiixxeess プレフィクス(URLのものなど) pprriinntteerrss プリントキューの名前 zsh 4.3.2 March 2, 2006 16 ZSHCOMPSYS(1) ZSHCOMPSYS(1) pprroocceesssseess プロセスID pprroocceesssseess--nnaammeess kkiillllaallllコマンドで指定するプロセス名を生成するときに ccoommmmaanndd スタイルを調べるときに使われる sseeqquueenncceess シーケンス(mmhhのシーケンス(連番)) sseessssiioonnss zzffttpp モジュールの「セッション」 ssiiggnnaallss シグナル名 ssttrriinnggss 文字列(ccddコマンドでカレントディレクトリの一部置換を 行なうときなど) ssttyylleess 内部コマンドtt(zstyle)用のスタイル名 ssuuffffiixxeess ファイル名の拡張子 ttaaggss タグ名 (e.g. rrppmm タグ) ttaarrggeettss Makefileのターゲット名 ttiimmee--zzoonneess タイムゾーン ttyyppeess 種 別を表すもの何でも(たとえば xxhhoosstt コマンドで指定 するアドレスタイプなど) uurrllss URL補完時に uurrllss と llooccaall スタイルを参照するのに 使 われる uusseerrss ユーザ名 vvaalluueess 指 定したリストにある複数の値の候補から必ずひとつだ けが補完されるような補完候補の集合 vvaarriiaanntt __ppiicckk__vvaarriiaanntt 関数が,インストールされているコマ ン ド の種類を決めるときに実際に起動するコマンドを決め るときに参照される。訳注: このタグに対する ccoommmmaanndd ス タイルの値にコマンド名が設定されていたらそれを起 動する(__ccaallll__pprrooggrraamm関数の役目)。 vviissuuaallss X visuals(訳注: ってなに???) zsh 4.3.2 March 2, 2006 17 ZSHCOMPSYS(1) ZSHCOMPSYS(1) wwaarrnniinnggss ffoorrmmaatt スタイルから警告を探すために使われる wwiiddggeettss zshのウィジェット名 wwiinnddoowwss X のウィンドウID zzsshh--ooppttiioonnss zshのシェルオプション 標標準準ススタタイイルル これから説明する「スタイル」のうちいくつかは,設定すべき値 が真偽値となっている。 `ttrruuee',`oonn',`yyeess',`11' という文字 列はどれも `true'(真)を 意 味 す る も の と し て 使 え, `ffaallssee',`ooffff',`nnoo',`00' と い う 文 字 列 は ど れ も `false'(偽)を意味するものとして使える。それ以外の値を設 定 したときの挙動は,とくにことわりのない限り未定義となってい る。値がセットされていないときの値は true か false のい ず れかである。 また以下のスタイルのうちいくつかは,マッチの種別に応じて決 まっているタグ群にたいして照合され,それでみつからなければ デフォルトタグに対するそのスタイルが参照される。 もっ と も 身 近 な ス タ イ ル に mmeennuu, lliisstt--ccoolloorrss, lliisstt--ppaacckkeedd, llaasstt--pprroommooppttがある(□)。 ddeeffaauullttタグをテストするとき,コンテクストの _f_u_n_c_t_i_o_n フィ ールドだけがセットされる。それによってデフォルトタグを使う ようなスタイルは次のようなコンテクスト定義で書くこと に な る。 zzssttyyllee ''::ccoommpplleettiioonn::**::ddeeffaauulltt'' mmeennuu ...... aacccceepptt--eexxaacctt 現 在のコンテキスト用のタグにくわえてデフォルトタグ に対しても調べられる。この値が `true' なら,コマ ン ド ライン上の単語が補完候補のどれかに完全一致してい たらそれを確定したものと見なす(たとえ,その単語で補 完 さ れ る可能性を持つ候補がものが他にあったとして も)。 パス名補完のとき(そのときのタグは `ppaatthhss'),この ス タ イルには真偽値に加えて任意個のパターンを持たせて よく,その場合与えたパターンのどれかにマッチする パ ス がコマンドライン上にタイプされていたらそれを即確 定する。その場合,確定されるパス名の後ろにさらに 多 く の パ スを入力していて,確定したあとにマッチする ファイルがないとしても確定する。 訳注: わからんね。実例で示す。 lleessss //uu//llii// で補完す zsh 4.3.2 March 2, 2006 18 ZSHCOMPSYS(1) ZSHCOMPSYS(1) ると //uu**//llii**// で探すので,//uussrr//lliibb,//uussrr//lliibbeexxeecc が 両方候補に入る。しかし //uussrr//lliibb// としっかり打ってか ら 補完したなら lliibbeexxeecc の方は入れずに //uussrr//lliibb// で 確定させたいなら zzssttyyllee ''::ccoommpplleettiioonn::**::**::lleessss::**'' \\ aacccceepptt--eexxaacctt //uussrr//lliibb としておく。ただしこうすると,lliibbeexxeecc のほうにあ る ファ イルを補完させたくて //uussrr//lliibb//ppoossttff と打ったと しても //uussrr//lliibb の部分が確定されてしまっているの で アウト。訳注終わり。 このスタイルは __eexxppaanndd コンプリータにもつかえ,その 場合チルダか変数名で始まるものを展開するかどうか を 決める。たとえば,変数 ffoooo と ffoooobbaarr が定義されてい たとして, `$$ffoooo' という単語が(その値に)展開され る の は aacccceepptt--eexxaacctt が true の場合だけで,そうでない ときは $$ffoooo を $$ffoooobbaarr に展開する可能性が残される。 また,もし値を `continue' にしておけば, __eexxppaanndd は 展開結果をマッチとして追加し,補完システムに継続 を 許可する。 訳注: __eexxppaanndd を呼ぶようにしてから実験。 zzssttyyllee ''::ccoommpplleettiioonn::**'' ccoommpplleetteerr __eexxppaanndd __ccoommpplleettee zzssttyyllee ''::ccoommpplleettiioonn::::eexxppaanndd::**'' ssuubbssttiittuuttee ttrruuee ffoooo==''TThhiiss iiss ffoooo'' ffoooobbaarr==''FFOOOOBBAARR'' eecchhoo $$ffoooo[[TTaabb]] zzssttyyllee ''::ccoommpplleettiioonn::::eexxppaanndd::**'' aacccceepptt--eexxaacctt ccoonnttiinnuuee これは `$$ffoooo' と `$$ffoooobbaarr' を選ばせる。 zzssttyyllee ''::ccoommpplleettiioonn::::eexxppaanndd::**'' aacccceepptt--eexxaacctt ttrruuee これは `$$ffoooo' を即確定して展開して完了。 zzssttyyllee ''::ccoommpplleettiioonn::::eexxppaanndd::**'' aacccceepptt--eexxaacctt ccoonnttiinnuuee これは `$$ffoooo' を展開したものに加え, `$$ffoooobbaarr' と最 初の `$$ffoooo' を候補としてメニュー補完する。 訳注終わり。 aadddd--ssppaaccee __eexxppaanndd コンプリータによって 使 わ れ る。 こ れ が true(デ フォルト) のとき,展開の直後にスペース(語が ディレクトリ名ならスラッシュ)が挿入される。また,値 と して `ffiillee' を代入しておくとコンプリータは実在す るファイルにのみスペースを追加する。 true, `ffiillee' い ずれかを持たせる場合,`ssuubbsstt' を組み合わせること ができ,その場合コン プ リ ー タ は, `$$((......))' や `$${{......}}' 置換の展開結果には空白を足さない。 (訳注: 理屈は分かるがこれもそうならんぞ??? zsh 4.3.2 March 2, 2006 19 ZSHCOMPSYS(1) ZSHCOMPSYS(1) zzssttyyllee ''::ccoommpplleettiioonn::**'' aadddd--ssppaaccee ffaallssee しても,必ず空白が入るのは何故だ。) __pprreeffiixx コ ン プリータはこの値を真偽値としてのみ使 い,サフィクスの前に空白をいれるかどうかだ け 決 め る。 aammbbiigguuoouuss 補完後の後に / などを補うものがある場合,メニュー補 完では,複数マッチがあったとしてもとりあえず 1つ 目 のマッチに / を付けて提示するが,このスタイルをセッ トすると複数マッチがある場合は一意に決まらない部 分 に カ ー ソ ル を戻して提示する(□)。このスタイルは ppaatthhss タグで常に参照される。 aassssiiggnn--lliisstt イコール記号の後の値代入の部分で,通常は1つのファイ ル 名だけ補完するが,このスタイルがセットされている 場合はPATH変数のようにコロン区切りの後を別のファ イ ル 名とみなして補完する。スタイルの値はそう補完すべ き変数にマッチするパターンのリスト。 デフォルトでは値にコロンが既に含まれていればONに な る。 ということで,これを明示的に指定しなくても快適 じゃん。 aauuttoo--ddeessccrriippttiioonn 1つの引数を取るオプション自身の説明文字列が補完定義 に 与えられていないとき,そのオプションの引数の方に 説明文字列があればそれオプション自身の説明として 使 う。 スタイルの値に含ませる %%dd がその文字列に置き換 えられる(□)。 aavvooiidd--ccoommpplleetteerr __aallll__mmaattcchheess コンプリータが使用する。現在挿入すべき 単 語を生成するときに,使わないコンプリータのリスト を列挙する(□)。 デフォルト値は `__eexxppaanndd __oolldd__lliisstt __ccoorrrreecctt __aapppprrooxx-- iimmaattee' で全マッチ単語挿入で要らなさそうなものを生成 するコンプリータを入れておく(□)。 ccaacchhee--ppaatthh 補完単語のキャッシュを保存するパス名を指定する。 デ フォ ル トは $$ZZDDOOTTDDIIRRが定義されている場合は `$$ZZDDOOTT-- DDIIRR//..zzccoommppccaacchhee', そ う で な い 場 合 は `$$HHOOMMEE//..zzccoommppccaacchhee'。 ただし, uussee--ccaacchhee スタイルが セットされていないときは使われない。 ccaacchhee--ppoolliiccyy キャッシュの再構築をいつするかを決める関数 を 決 め る。後述する __ccaacchhee__iinnvvaalliidd の項を参照。 zsh 4.3.2 March 2, 2006 20 ZSHCOMPSYS(1) ZSHCOMPSYS(1) ccaallll--ccoommmmaanndd mmaakkee,aanntt といった,マッチ単語生成に該当コマンドを 直接呼ぶようなもののときに,遅くなったり,mmaakkeeが 実 際 に仕事を始めちゃったりする問題を避けるために使わ れる。trueであれば,実際のコマンドを呼んでマッチ 単 語を生成する(場合もある□)。デフォルトは false。 ccoommmmaanndd 外 部コマンドを呼んでマッチ単語を生成するような多く の補完で使われ,呼ぶコマンドを変えるために 使 わ れ る。値を `--' で始めるとデフォルトのコマンドラインの 前に補われる(bbuuiillttiinnや ccoommmmaanndd を明示的に前置させた いときに便利)。 た とえば,kkiillll でPIDを補うときの一覧はpsを呼んで得 ているがこのスタイルの値に ppss tt$$TTTTYY などを入れて お け ば, 現在のTTYの PIDだけに限定できたりする(□)。 PIDの補完で言えば,実際の補完関数がPID部分を抽出 で き るよう出力が関数の期待どおりに得られるよう注意が 必要(□)。 コマンドを呼ぶのでそれが短い時間で確実に終わるよ う にすることにも注意が必要。訳注: ものすごく変えた。 ccoommmmaanndd--ppaatthh 補 完 の ときに用いるコマンド検索の値。デフォルトは ppaatthh 変数の値。 ccoommmmaannddss OSの初期化スクリプト(//eettcc//iinniitt..dd や //eettcc//rrcc..dd な ど に あるもの) のサブコマンドを補完する関数が使う。そ れらのスクリプトに与えるサブコマンドの一覧を指定 す る。デフォルトは `ssttaarrtt' と `ssttoopp'(□)。 ccoommpplleettee __eexxppaanndd__aalliiaass 関数を割り当て可能コマンド(デフォルト で ^^XXaa) として呼び出したときに使われる。入力した 単 語に完全にマッチするエイリアスがなかったときに,(続 けてタイプすると)マッチするもの一覧を出す(□)。 ccoommpplleetteerr コンプリータとして用いる関数を(文字列で)列挙す る。 指 定 で き るコンプリータは後述する `Control Func- tions' 節参照。 各文字列は,コンプリ ー タ 関 数, ま た は `_f_u_n_c_- _t_i_o_n::_n_a_m_e' という書式が許されている。前者の場合は, コンテクストの _c_o_m_p_l_e_t_e_r フィールドは,その関数の先 頭のアンダースコアを取り,残りのアンダースコア(もし あれば)をすべてハイフンに変えた文字列に変えた名前に なる。後者の場合,_f_u_n_c_t_i_o_n は呼ぶべきコンプリータの 名前となるが,呼ばれるときのコンテク ス ト の _c_o_m_- _p_l_e_t_e_r フィールドは _n_a_m_eとなる。ただし,_n_a_m_e がハイ フンで始まるときはその前にコンプリータ関数本来の コ zsh 4.3.2 March 2, 2006 21 ZSHCOMPSYS(1) ZSHCOMPSYS(1) ンテクスト名が追加される(□)。つまり, zzssttyyllee ''::ccoommpplleettiioonn::**'' ccoommpplleetteerr __ccoommpplleettee __ccoommpplleettee::--ffoooo と いうコンプリータ登録の場合,補完システムは __ccoomm-- pplleettee コンプリータを2回呼ぶことになり,1回目はコ ン テクストの _c_o_m_p_l_e_t_e_r フィールド名 ccoommpplleettee で, 2回 目はフィールド名 ccoommpplleettee--ffoooo で呼ばれる。 同じコンプリータを2度以上使うなら `_f_u_n_c_t_i_o_n_s::_n_a_m_e' の 書式を使って回毎に違うコンテクスト名で呼ばせなけ れば意味がない(__iiggnnoorreedd と __pprreeffiixx コンプリータに関 してはこの限りでない)。 こ の スタイルのデフォルト値は `__ccoommpplleettee __iiggnnoorreedd' で,「補完」のみを,1回目は iiggnnoorreedd--ppaatttteerrnnss スタイ ルと $$ffiiggnnoorree 変数の値を考慮して,2回目はそれなしで 行なう。 ccoonnddiittiioonn __lliisstt コンプリータがマッチするものの挿入を無条件 で 遅 れ さ せ る か 決 め る ために使う。デフォルトは `true'(???)。 ddiissaabblleedd __eexxppaanndd__aalliiaass コンプリータとそのキー割り当て可能 コ マンドが使い,`true' の場合は無効化されたエイリアス も補完する。デフォルトは `false'。 ddiissaabbllee--ssttaatt __ccvvss 関数がタグなしでこの値を用いて,相応の場所にあ る 修正ファイルを生成するために zzsshh//ssttaatt モジュール を使うかどうかを決める。`trule' ならモジュールを 使 わず llss コマンドを使う。 ddoommaaiinnss 補 完に使うネットワークドメイン名のリスト。セットさ れていない場合は //eettcc//rreessoollvv..ccoonnff ファイルから取 得 される。 eexxppaanndd こ のスタイルは,パス名のように複数の部分から成って いる文字列を補完するときに使われる。 この値のうち1つが `pprreeffiixx' という文字列であれ ば(完 全一致),後半部分が補完できなくても前半部分が補完で きるならできるだけ展 開 さ れ る。 訳 注: た と え ば,//uu//ii//hhooggee を補完するとき //uu**//ii**//hhooggee** がなくて も //uu**//ii** で補完できるなら //uussrr//iinncclluuddee//hhooggee に展開 する。 こ の値のうち1つが `ssuuffffiixx' という文字列であれば(完 全一致),途中に一意に定まらない部分があったと し て も, その後ろにある部分にマッチする名前が足される。 これにより結果の文字列は,一意に定まる前の最長の 文 zsh 4.3.2 March 2, 2006 22 ZSHCOMPSYS(1) ZSHCOMPSYS(1) 字 列となる。このとき,メニュー補完を用いてマッチす るものすべてを循環させることもできる。訳 注: //hhoommee 以下に yyuukkaa,yyuukkiittaa,yyuuuujjii ディレクトリがあり,それ ぞれに ..zz で始まるファイルとして ..zzsshheennvv,..zzsshhrrcc が あ るとする。このときに //hh//yy//..zz で ccoommpplleettee--wwoorrdd す ると, suffix でないときは //hhoommee//yyuu までが補完さ れ る が, suffix の と き は ..zz の 部分も頑張って //hhoommee//yyuu//..zzsshh に展開される。 ffaakkee どのコンテクストでも使えるスタイル。指定したコン テ ク ストで必ず追加で補完対象に含まれるような文字列を 指定する。指定する値は `_v_a_l_u_e::_d_e_s_c_r_i_p_t_i_o_n' の形式で 記述し,コロンの後ろに説明文字列を書く(コロンを含め て省略可能)。説明文字列にコロンを入れたいときはバッ ク スラッシュでクォートする。説明文字列は補完リスト 表示のときに出される。 どこでも呼ばれる可能性があるので,コンテクスト指 定 を 十分に限定的にすることが大切。ファイル名や変数名 で似たような追加候補を入れたい と き に つ い て は ffaakkee--ffiilleess や ffaakkee--ppaarraammeetteerrss 参照のこと。訳注: と にかく決まった単語を決まったコマンドの補完で使い た いときに便利なスタイル。 ffaakkee--aallwwaayyss ffaakkee スタイルと同じ働きだが,iiggnnoorreedd--ppaatttteerrnnss スタ イルを適用しない点だけ異なる。無視するパタ ー ン を `**' にセットすることでマッチ単語群を完全にオーバー ライドすることができる。 This works identically to the ffaakkee style except that the iiggnnoorreedd--ppaatttteerrnnss style is not applied to it. This makes it possible to override a set of matches completely by setting the ignored patterns to `**'. 以下に,単に分割タグのように表示のためだけに用い る 勝 手なデータをもつ任意のタグを補わせる方法を示す。 この例では,ttaagg--oorrddeerr スタイルを使って,標準コン プ リ ータの ccoommpplleettee が ccdd コマンドの引数を補完すると きに nnaammeedd--ddiirreeccttoorriieess タグを2回に分けて呼 ん で い る。 nnaammeedd--ddiirreeccttoorriieess--nnoorrmmaall タ グは普通に候補を持つが nnaammeedd--ddiirreeccttoorriieess--mmiinnee タグは自分のおきまりのディレ クトリ群だけを候補に持つようにしている。 nnaammeedd--ddiirreeccttoorriieess--mmiinnee contains a fixed set of directories. This has the effect of adding the match group `eexxttrraa ddiirreeccttoorriieess' with the given com- pletions. zzssttyyllee ''::ccoommpplleettiioonn::::ccoommpplleettee::ccdd::**'' ttaagg--oorrddeerr \\ ''nnaammeedd--ddiirreeccttoorriieess::--mmiinnee::eexxttrraa\\ ddiirreeccttoorriieess nnaammeedd--ddiirreeccttoorriieess::--nnoorrmmaall::nnaammeedd\\ ddiirreeccttoorriieess **'' zzssttyyllee ''::ccoommpplleettiioonn::::ccoommpplleettee::ccdd::**::nnaammeedd--ddiirreeccttoorriieess--mmiinnee'' \\ zsh 4.3.2 March 2, 2006 23 ZSHCOMPSYS(1) ZSHCOMPSYS(1) ffaakkee--aallwwaayyss mmyyddiirr11 mmyyddiirr22 zzssttyyllee ''::ccoommpplleettiioonn::::ccoommpplleettee::ccdd::**::nnaammeedd--ddiirreeccttoorriieess--mmiinnee'' \\ iiggnnoorreedd--ppaatttteerrnnss ''**'' 訳注: んでもこれを fake-always から fake にしても違 いが分からないのだが…… ffaakkee--ffiilleess こ のスタイルはファイルの補完に使われ,タグなしで参 照される(△)。値は `_d_i_r::_n_a_m_e_s_._._.' の形式で指定 し, _n_a_m_e_s(複数ある場合は空白で区切る)という名前のファイ ル(群)が _d_i_r に(実在しなくても)あるものして候補に含 める。 こ れはたとえばオートマウントディレクトリ(□)のよう にアクセスするまで一覧に出てこないパ ス 名 の 補 完 や,xビッ トだけあってrビットがないディレクトリにあ る読みだし可能ファイルの名前を補完したいと き に 便 利。 訳 注: たとえば,a2ps や psnup の結果をほとんどの場 合 //ttmmpp//hhooggee..ppss,//ttmmpp//hhooggee22..ppss,//ttmmpp//hhooggee33..ppss, … に リ ダ イレクトで書き出しているような場合,既存の ファイルがなくても >> のあとに //ttmmpp//hhooggee..ppss を補完さ せたい。そのようなときは, zzssttyyllee ''::ccoommpplleettiioonn::::**::--rreeddiirreecctt--,,>>,,((aa22ppss||ppssnnuupp))::**'' \\ ffaakkee--ffiilleess ""//ttmmpp::hhooggee..ppss ``eecchhoo hhooggee{{22....99}}..ppss``"" と設定しておくと,aa22ppss ffoooo >> の後ろで //ttmmpp//hhooggee..ppss などが補完候補となる。 ffaakkee--ppaarraammeetteerrss 変数名を補完する関数で使われる。値には,まだ未定 義 で も補完候補に入れる変数名を列挙する。指定する名前 にはコロンに続け て 変 数 の 型(`ssccaallaarr',`aarrrraayy', `iinntteeggeerr'等)を 補助的に追記できる。型を与えておくと その型が要求されているコンテクストでのみその変数 が 補完される。型指定のない変数は常に補完される。 ffiillee--lliisstt こ のスタイルは,標準の機構を用いて得られた補完候補 ファイル群を一覧表示するときに,llss --llに似たロングリ ス ト出力とするかどうかを決める。この機能はファイル の情報を得るためにシェルモジュール zzsshh//ssttaatt を使 用 す る。このモジュールは外部コマンドの ssttaatt より優先 されることになるが,それを避けたい場合は zzmmooddllooaadd --ii zzsshh//ssttaatt ddiissaabbllee ssttaatt と初期化ファイルに書いておくとよい。 このスタイルに設定できる値は,true(また は `aallll'): zsh 4.3.2 March 2, 2006 24 ZSHCOMPSYS(1) ZSHCOMPSYS(1) あ らゆる状況でロングフォーマットで出す, `iinnsseerrtt': ファイル名を挿入するとき, `lliisstt': ファイル名を挿入 せずに一覧を出すとき,のいずれか(△どう使いわけるの かいまいち)。 厳密には(□),この値は上記の値のどれかに,オプ ショ ン で ==_n_u_m を付けたもの,を配列にしたものにしてよ い。 _n_u_m は,ロングフォーマット表示にする場合の最大 マッチ数を表す。たとえば, zzssttyyllee ''::ccoommpplleettiioonn::**'' ffiillee--lliisstt lliisstt==2200 iinnsseerrtt==1100 と すると,マッチするものが20個までなら一覧出力をロ ングフォーマットにし, 10個までなら挿入する(あい ま い補完の例のように一覧がallで出るようになってるもの と見なす(△何???))。また, zzssttyyllee --ee ''::ccoommpplleettiioonn::**'' ffiillee--lliisstt ''(((( $${{++NNUUMMEERRIICC}} )))) &&&& rreeppllyy==((ttrruuee))'' とすると,数引数を付けて呼び出した場合に常にロン グ フォ ーマット,そうでないときショートフォーマットが 使われる。 (訳注: △△ほんにわからん) ffiillee--ppaatttteerrnnss 標準ファイル名補完関数である __ffiilleess が使用する。 こ のスタイルがセットされていない場合は,最大で3つのタ グ,`gglloobbbbeedd--ffiilleess',`ddiirreeccttoorriieess',`aallll--ffiilleess' が, __ffiilleess の呼び主の求めているファイル種別に応じ て渡される。最 初 の2つ,`gglloobbbbeedd--ffiilleess',`ddiirreeccttoo-- rriieess' は,通常いっしょに渡されて,サブディレクトリ 内のファイルを簡単に補完できるようにしている。 ffiillee--ppaatttteerrnnss スタイルは,デフォルトタグ(通常は使わ れない)の代わりのものを生み出すために使える(△□)。 このスタイル値は,`_p_a_t_t_e_r_n::_t_a_g' という要素 の 集 合 で, 各要素は同じ形式の要素をスペースで区切って列挙 したものでも構わない(□)。 _p_a_t_t_e_r_n はファイル名生成を行なうために使 わ れ る。 `%%pp' と書くとその部分が __ffiilleess 関数に渡されたパター ン(群) に置き換えられる。パターンにコロン自身が含ま れ るときはバックスラッシュでエスケープする必要があ る。複数のパターンを書く必要があるときはそれらの パ タ ーン全体を確固で括って,その中にパターンをカンマ で区切って書けばよい。 _t_a_gの部分で指定されたタグ群は,__ffiilleessによって別のス タ イルを照合するときに渡される。別のパターンに同じ タグ値を指定したとき,そ れ ら は 同 時 に 渡 さ れ る(△)。`::_t_a_g' を省略したときは `ffiilleess' タグが使わ れる。 _t_a_g 指定のさらに後ろにさらにコロンを付けて説明文 字 列 を追記することもできる。説明文字列を定義しておく zsh 4.3.2 March 2, 2006 25 ZSHCOMPSYS(1) ZSHCOMPSYS(1) と,補完関数のデフォルトの説明の代わり に, ffoorrmmaatt ス タイルの `%%dd' に置き換えられる。説明文字列自身に `%%dd' を入れておくと,それは補完関数のデフォルトの説 明文字列に置き換えられる。 たとえば,rrmm コマンドの引数の補完で,最初はオブジェ クトファイルだけ補完を試み,マッチしない場合のみ す べてのファイルを補完したい場合は以下のようにする。 zzssttyyllee ''::ccoommpplleettiioonn::**::**::rrmm::**'' ffiillee--ppaatttteerrnnss \\ ''**..oo::oobbjjeecctt--ffiilleess'' ''%%pp::aallll--ffiilleess'' デ フォルトの補完機能の挙動,すなわち,パターンに位 置するものと, (パターンとは無関係の)ディレクトリを 最 初に,その後ですべてのファイルを提示する,という 挙動を,「最初にパターンにマッチするものだ け 提 示 し, そのあとでディレクトリとすべてのファイルを…」 と変えたい場合は zzssttyyllee ''::ccoommpplleettiioonn::**'' ffiillee--ppaatttteerrnnss \\ ''%%pp::gglloobbbbeedd--ffiilleess'' ''**((--//))::ddiirreeccttoorriieess'' ''**::aallll--ffiilleess'' と指定すればよい。 This works even where there is no special pattern: __ffiilleess 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. 補完関数実行時には,EEXXTTEENNDDEEDD__GGLLOOBB オプションが セッ ト されるので,パターン中に`##',`~~' や `^^' などがあ れば,それらは特別な働きをする。 ffiillee--ssoorrtt 標準ファイル補完関数が,候補一覧表示の出力順を決 め る ためにこのスタイルをタグなしで使用する。メニュー 補完も同じ順番となる。設定できる値は, `ssiizzee': ファ イ ルサイズでソート, `lliinnkkss': リンクカウントでソー ト, `mmooddiiffiiccaattiioonn'(`ttiimmee' または `ddaattee'): 修正時刻 で ソ ー ト, `aacccceessss': 最終アクセス時刻でソート, `iinnooddee'(`cchhaannggee'): inode情報更新時刻でソート,の ど れか。 上 記の値以外,またはセットされていないときはファイ ル名でソートし,値に `rreevveerrssee' という文字列を含む場 合は逆順でソートする。 ffiilltteerr 訳注: 急いでるので飛ばします。 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 `ssnn', 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 ccoommmmaanndd style to specify how to connect to your LDAP server. ffoorrccee--lliisstt 一 覧出力が普通なら抑制されるようなときでも,必ず一 覧出力を強制実行する。 たとえば,通常一覧出力はマッチするものが2個以上ある 場 合に出てくる (訳注: AAUUTTOOLLIISSTT オプションが有効(デ フォルト)の状態で ccoommpplleettee--wwoorrdd した場合など)。この ス タイルを `aallwwaayyss' にセットすると,たとえマッチす るものが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. このスタイルはデフォルトタグだけでなく,現在の補 完 で有効な各タグで確かめられる。 ffoorrmmaatt ddeessccrriippttiioonnss タグに対してこのスタイルが設定されてい るとき,その値は一覧出力の上に表示される。値の文 字 列 中の `%%dd' は,マッチ対象に対する短い説明文に置き 換えられる。他に,`%%BB',`%%SS',`%%{{...%%}}' も使える。 現在の補完で有効なすべてのタグで確かめられ,その あ と で ddeessccrriippttiioonnss タグに対して確かめられる。これに より違う種類の補完対象には違う書式文字列を定義で き る。 また,もっと多くの `%%' 記法が使えるコンプリータもあ り,その場合はそのコンプリータ関数の Note also that some completer functions define additional `%%'-sequences. These are described for the com- pleter functions that make use of them. いくつかの補完関数では,mmeessssaaggeess タグに対するこのス タイル値を設定することで表示メッセージを変 更 で き る(その場合 `%%dd' は補完関数により出されるメッセージ に置換される)。 wwaarrnniinnggss タグに対するこのスタイル値は,マッチするも のがなかった場合に参照される。その場合,`%%dd' はマッ チが期待されたものに対する説明をスペースで区切っ て 並べたものに置き換えられる(△どういうとき??)。 `%%DD' は同じ説明をスペースではなく改行で区切って並べた も のに置き換えられる。 `%%dd' にprintf風の桁幅指定や,エスケープシーケンスが zsh 4.3.2 March 2, 2006 27 ZSHCOMPSYS(1) ZSHCOMPSYS(1) 使うこともできる。 zzsshh//zzuuttiill モジュールで定義されて い る 内 部 コマンドの zzffoorrmmaatt によって処理される。 _z_s_h_m_o_d_u_l_e_s(1)参照. gglloobb __eexxppaanndd コンプリータで使われる。この値が `true'(デ フォ ルト値) のときは直前の置換の結果に対してさらに グロッビングを試みる(ssuubbssttiittuutteeスタイルも 参 照)(△ □)。 gglloobbaall __eexxppaanndd__aalliiaass コンプリータとそのキー割り当て可能コ マンドが,グローバルエイリアスを展開するかどうか を 決める。デフォルトは `true'。 ggrroouupp--nnaammee 補 完システムでは別の種類のマッチ対象をグループごと に分けて一覧出力することができる。このスタイルを 用 い てタグごとに別々のグループ名を付けられる。たとえ ば,コマンドラインのコマンド位置で補完さ せ る と, シェ ル内部コマンド,外部コマンド,エイリアス,シェ ル関数, (代入のための)変数名,が有効な補完対象とし て 生成される。ここで,外部コマンドとシェル関数を候 補一覧表示で分けたい場合にはこうする: zzssttyyllee ''::ccoommpplleettiioonn::**::**::--ccoommmmaanndd--::**::ccoommmmaannddss'' ggrroouupp--nnaammee ccoommmmaannddss zzssttyyllee ''::ccoommpplleettiioonn::**::**::--ccoommmmaanndd--::**::ffuunnccttiioonnss'' ggrroouupp--nnaammee ffuunnccttiioonnss これで,同じタグを持つものが同じグループ内に表示 さ れる。 グ ループ名を持たないすべてのマッチ対象は --ddeeffaauulltt-- という名前のグループに入れられる(訳注: 次の文の下に あったがここに移動した)。 グ ループ名に空文字列を指定すると,マッチ対象のタグ 名がグループ名に使われる。したがって,すべての マッ チ種別を別々に表示させたいなら zzssttyyllee ''::ccoommpplleettiioonn::**'' ggrroouupp--nnaammee '''' としておくとよい。 訳注: これを試すときには, zzssttyyllee ''::ccoommpplleettiioonn::**::ddeessccrriippttiioonnss'' ffoorrmmaatt ''%%BBCCoommpplleettiinngg%%bb %%UU%%dd%%uu'' などとしておくと効果が分かりやすい。 ggrroouupp--oorrddeerr ggrroouupp--nnaammee スタイルと併せて使い,分類されたグループ の一覧出力での順番を指定する(補完そのものを決 め る ttaagg--oorrddeerr と比較せよ□)。名前を持つグループは指定し た順番で表示され,その他のものは補完関数で定義さ れ た順番で表示される。 zsh 4.3.2 March 2, 2006 28 ZSHCOMPSYS(1) ZSHCOMPSYS(1) た と え ば,コマンド位置で補完したときに内部コマン ド,シェル関数,外部コマンドをその順番で一覧に出 し たいなら下記のようにする。 zzssttyyllee ''::ccoommpplleettiioonn::**::**::--ccoommmmaanndd--::**'' ggrroouupp--oorrddeerr \\ bbuuiillttiinnss ffuunnccttiioonnss ccoommmmaannddss ggrroouuppss UNIXの グ ル ープ名のリスト。セットされていなければ YPデータベース,または `//eettcc//ggrroouupp' から取 得 さ れ る。 hhiiddddeenn こ の 値 が `true' のときは,指定したコンテクストで マッチしたものは一覧表示されなくなる。ただし,そ の マッ チに対して ffoorrmmaatt スタイルでセットされた説明文 は表示される。説明文も出さないようにするにはこの ス タイル値を `aallll' に設定する。 た だし,一覧表示が出されないだけで補完はされる。補 完対象からも外したいときは後述の ttaagg--oorrddeerr スタイル をいじることで調整できる(□)。 hhoossttss 補 完に現れるべきホスト名のリスト。この値をセットし ていない場合,ホスト名は `//eettcc//hhoossttss' から取得さ れ る hhoossttss--ppoorrttss ホ スト名とネットワークポート番号を受け取るコマンド の引数補完で使用される。値は `_h_o_s_t::_p_o_r_t' の形式で指 定 する。有効なポートはホスト名の有無によって決めら れる。同じホストに複数のポートが現れてよい(△訳 注: どこで使われるか分からん。telnetは違うみたいだ)。 iiggnnoorree--lliinnee こ のスタイルは現在の補完で有効なすべてのタグについ て調べられる。もし設定値が `ttrruuee' の場合は,候補 対 象 のうち既にコマンドラインに入力されているものは除 外される。`ccuurrrreenntt' の場合は現在入力中の単語に完 全 一致するものは補完候補から除外する (訳注: ffoooo,ffoooo-- bbaarr,ffoooobbaazz があるとして, ffoooo まで打ってか らTAB押 すなら,もう全部打っちゃった ffoooo は補完されてもうれ しくない)。 `ccuurrrreenntt--sshhoowwnn' は `ccuurrrreenntt' とほぼ同じ だ が,入力中の単語にマッチするもの一覧が表示されて いる場合のみ完全一致する候補を除外する。 `ootthheerr' は コ マンドラインにあるカーソル位置以外の単語を補完候 補から除外する。 ちなみに,aacccceepptt--eexxaacctt スタイルは,既に打ったものに 完 全 一 致するパスコンポーネントは確定,という意味 で,既に打ったものに完全一致するのは除外する `ccuurr-- rreenntt' と `ccuurrrreenntt--sshhoowwnn' はちょうどこれの逆みたいな 感じになっている(□)。 便利な局面が多いこのスタイル だ が,`::ccoommpplleettiioonn::**' の よ う な 広 範 囲 に及ぶコンテクストで `ttrruuee' や zsh 4.3.2 March 2, 2006 29 ZSHCOMPSYS(1) ZSHCOMPSYS(1) `ootthheerr' を設定するのはうれしくないだろう。 な ぜ な ら, たとえばあるコマンドに対して同じオプションを複 数回指定したいときに,2回以降が補完できなくなってし まうからである。 iiggnnoorree--ppaarreennttss こ のスタイルはパス名補完を行なう関数からタグなしで 照合され,ディレクトリ名を補うときに,現在の単語 に 含 まれている場所やカレントディレクトリを除外するか を決める。設定できる値は下記の1つ,または2つ両方。 ppaarreenntt 入力中の単語に含まれるディレクトリは無 視 す る。 たとえば, ffoooo//....// で補完するなら,すで に ffoooo が含まれているのでこれを除外する。 ppwwdd カレントディレクトリを除外する。たと え ば, ....// で補完するとき,カレントディレクトリ以外 のものを候補とする。 上記の値に加えて,さらに以下のどちらか,または両 方 を含めることもできる。 .... 補 完中の単語が `....//' を含む場合のみ該当する ディレクトリを無視する。 ddiirreeccttoorryy 対象をディレクトリに限定して補完しているとき だけ該当ディレクトリを無視する。ディレクトリ に限定していないときは無視 し な い。 訳 注: zzssttyylleeや 補 完システムで,その引数を ""**((--//))"" で検索している場合のみ該当ディレクトリを無視 させる。例: zzssttyyllee ''::ccoommpplleettiioonn::**::**::ffoooo::**'' \\ iiggnnoorree--ppaarreennttss ppwwdd ddiirreeccttoorryy zzssttyyllee ''::ccoommpplleettiioonn::**::**::ffoooo::**'' \\ ffiillee--ppaatttteerrnnss ''**((--//))'' 2行目のあるなしで挙動が変わる。訳注終わり。 除 外 指 定 された値は,下記 iiggnnoorreedd--ppaatttteerrnnss スタイルと同 様,__iiggnnoorreedd コンプリータで候補として復活する(訳注: つまり 除外指定したものしかマッチするものがなければ復活して選ばれ る)。 iiggnnoorreedd--ppaatttteerrnnss 補完対象から除外したいパターンのリスト。とはい え, こ れで指定したパターンにマッチする候補が完全に捨て られるわけではなく,それらを復 活 さ せ る た め に __iiggnnoorreedd コンプリータを ccoommpplleetteerr スタイルに追加し ておくこともできる。このスタイル は, シェ ル 変 数 $$ffiiggnnoorree の柔軟バージョンといえる。 補 完関数実行時には,EEXXTTEENNDDEEDD__GGLLOOBB オプションがセッ zsh 4.3.2 March 2, 2006 30 ZSHCOMPSYS(1) ZSHCOMPSYS(1) トされるので,パターン中に`##',`~~' や `^^' などが あ れば,それらは特別な働きをする。 iinnsseerrtt __aallll__mmaattcchheess コンプリータが,たんに別のマッチに一覧 を足すのではなく,マッチする単語すべてを挿入する か を決める。 訳注: 以下の例で。 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 訳注終わり。 iinnsseerrtt--iiddss kkiillll や wwaaiitt 内部コマンドの引数などでプロセスIDを補 完するときに,コマンドの名前は適切なプロセスIDに 変 換 されうる。このとき,プロセス名が一意に定まらない と問題が起きる。 訳注: kkiillll などの後ろにコマンド名を打ってTABを押 す と 補完関数は ppss コマンドなどの出力からそのコマンド 名にマッチする PIDを引いて来て,一意に定まる前に す ぐ コ マンドライン上の単語をPID数値に書き換えてしま い,メニュー補完を始めて次 のTABキ ー で マッ チ す るPIDを循環させる。普段メニュー補完を使っていない人 は,マッチするものが最初に出てくると一意に決まっ た の かと思ってすぐリターンを押してしまいやすく,危険 である。この挙動はこのスタイル値が未定義 か,`mmeennuu' にセットされているものである。訳注終わり。 こ のスタイル値を `ssiinnggllee' にすると,一意に定まるま ではコマンドライン上のコマンド名をPIDに書き換 え な い(□)。 それ以外の単語にしておくと,ユーザの入力が 対応するIDに共通なプレフィクスより長くなってから メ ニュー補完が始まる(訳注: どうもそうはならない感じだ なあ???)。 iinnsseerrtt--ttaabb この値が `true' のとき,カーソルの左側に非空白文 字 が な い 状態で TABキーを押すと,補完を始める代わり にTAB文字を挿入する。 `false' ならそのような場所 で も補完を行なう。 値 として `ppeennddiinngg' または `ppeennddiinngg==_v_a_l' を設定する こともでき,その場合処理待ちの入力がある場合には 補 完でなくTAB文字を挿入する。 _v_a_lを指定した場合は,入 力待ちの文字数の閾値を設定できる(□)。これはTAB文字 を 含むものを端末にペーストするときに便利である。た だしこれは zzsshh//zzllee モジュールで定義され る PPEENNDDIINNGG 変 数の値を頼りにしているが,これはすべてのプラット zsh 4.3.2 March 2, 2006 31 ZSHCOMPSYS(1) ZSHCOMPSYS(1) フォームで正確に設定されるとは限らない点に注意さ れ たい。 デフォルトは `true' だが,内部コマンド vvaarreedd の中で は `ffaallssee' である。 iinnsseerrtt--uunnaammbbiigguuoouuss __mmaattcchh と __aapppprrooxxiimmaattee コンプリータで使われる。これ ら のコンプリータは既入力文字列が補完結果と似通う部 分がほとんどなくなることもあるので,メニュー補完 に 移行することが多い。 し かし,このスタイルを `true' にするとコンプリータ は,最低限ユーザが入力したのと同じ文字数だけのあ い ま いでない初期文字列がみつからない限りメニュー補完 には移行しない。 (訳注: この項目末尾に詳細追記) __aapppprrooxxiimmaattee コンプリータの場合は,コンテクス ト の _c_o_m_p_l_e_t_e_r フィ ー ル ド は 既に ccoorrrreecctt--_n_u_m または aapppprrooxxiimmaattee--_n_u_m (_n_u_mは許容エラー数)のどちらかがセッ トされている。 __mmaattcchh コンプリータの場合は,このスタイル値を `ppaatt-- tteerrnn' にすることもでき,その場合コマンドライン上 の パ ターンはあいまいさなくマッチしなければ,そのまま にされる。 訳 注: zzssttyyllee ''::ccoommpplleettiioonn::**'' ccoommpplleetteerr __eexxppaanndd __ccoommpplleettee __mmaattcchh __aapppprrooxxiimmaattee な ど と し て __mmaattcchh,__aapppprrooxxiimmaattee が使われるようにしておく。カレ ン ト ディ レ ク ト リ に MMAACCHHIINNEESS,MMEETTAA--FFAAQQ,ccoonn-- ffiigg..ssuubb,ccoonnffiigguurree がある状態で MMAATT だ け 入 力 し てTABすると MMAACCHHIINNEESS と MMEETTAA--FFAAQQ で循環するメニュー 補完に突入する。 ま た,cciinnff ま で 打っ てTABす る と,ccoonnffiigg..ssuubb と ccoonnffiigguurree で循環するメニュー補完 に突入する。しかし, zzssttyyllee ''::ccoommpplleettiioonn::**'' \\ iinnsseerrtt--uunnaammbbiigguuoouuss ttrruuee すると,MMAATT のほうは3文字のままインクリメンタル補完 にはできないのでメニュー補完に突入するが,cciinnff のほ うは,ccoonnff に直せば ccoonnffiiggまで補完してインクリメ ン タ ル 補 完が続けられるのでメニュー補完には移行しな い。訳注終わり。 kkeeeepp--pprreeffiixx __eexxppaanndd コンプリータで使われる。`true' のときはチル ダ や変数展開を含むプレフィクスを保とうとする。ゆえ に,たとえば,`~~//ff**' は `//hhoommee//uusseerr//ffoooo' ではなく, `~~//ffoooo' に展開される。スタイル値を `cchhaannggeedd'(デフォ ルト値) にすると,プレフィクスは,展開結果とコマ ン ド ラインの元の文字列に別の変更があった場合だけ変更 されない。その他の値を設定するとプレフィクスを無 条 zsh 4.3.2 March 2, 2006 32 ZSHCOMPSYS(1) ZSHCOMPSYS(1) 件で展開する。 スタイル値が true のときの __eexxppaanndd の挙動によって, 1回展開したものがプレフィクスの復元で元と同じになっ てしまった場合には __eexxppaanndd を中止し,その結果残りの コンプリータが呼ばれることになる場合がある。 llaasstt--pprroommpptt シェルオプション AALLWWAAYYSS__LLAASSTT__PPRROOMMPPTT の,より柔軟 な バ ージョン。この値が `true' だと,補完システムは一 覧表示したのち,最初のコマンドライン位置に戻ろう と す る。このスタイルは現在の補完で有効なすべてのタグ について調べられ,そののちデフォルトタグで調べら れ る。 カ ーソルを戻すのはそのスタイルがすべて `true' だった場合。ただし,AALLWWAAYYSS__LLAASSTT__PPRROOMMPPTT と違い,数引 数の影響を受けない点が異なる点に注意。 kknnoowwnn--hhoossttss--ffiilleess sshの kknnoowwnn__hhoossttss ファイルと互換性のある書式で書か れたホスト名とIPアドレス(uussee--iippスタイルがセットされ て いる場合) を探すために使われるファイルのリスト。 セットされていない場合 は //eettcc//sssshh//sssshh__kknnoowwnn__hhoossttss と ~~//..sssshh//kknnoowwnn__hhoossttss が用いられる。 lliisstt キ ー割り当て可能コマンド __hhiissttoorryy__ccoommpplleettee__wwoorrdd に よって使われる。 `true' にセットされている場合は と くに効果がない。 `false' にセットされているとマッチ するものが一覧表示されなくなる。これは,一覧表示 機 能を制御するオプション,とくに AAUUTTOO__LLIISSTT をオーバー ライドする。コンテクストは 常 に `::ccoommpplleettiioonn::hhiiss-- ttoorryy--wwoorrddss' で始まる。 lliisstt--ccoolloorrss zzsshh//ccoommpplliisstt モジュールがロードされている場合に,こ のスタイルは色付け指定として使われる。 _z_s_h_m_o_d_u_l_e_s(1) の `The zsh/complist Module' 節で解説 されている ZZLLSS__CCOOLLOORRSS と ZZLLSS__CCOOLLOOUURRSS 変数の利用を置 き換えるがただし文法は同じである。 (訳注: 初 期 化 ファ イ ルに古い ZZLLSS__CCOOLLRROOSS や ZZLLSS__CCOOLLOOUURRSS の設定が あってもunsetされ,補完システムの lliisstt--ccoolloorrss が 優 先される。) このスタイルが ddeeffaauulltt タグに対してセットされている と,その値はすべての場所で使われるものと見 な さ れ る。 他のタグに対してセットされていれば,そのタグに よって決まる補完対象のみの設定になる。この使いわ け を うまく活用するには, ggrroouupp--nnaammee スタイルに空文字 列を設定しておく。 上述のタグごとの固有スタイル 設 定 だ け で な く, ggrroouupp--nnaammeeタ グで明示的に指定されたグループ名を使う こともできる。それには ZZLLSS__CCOOLLOORRSS や ZZLLSS__CCOOLLOOUURRSS 変 数 で許されている `((ggrroouupp))' 記法と ddeeffaauulltt タグの使 zsh 4.3.2 March 2, 2006 33 ZSHCOMPSYS(1) ZSHCOMPSYS(1) 用を組み合わせる(△訳注: 試したけどよう分からん)。 GNU llss 用に設定してある設定を使うこともできる。それ には以下のようにする。 zzssttyyllee ''::ccoommpplleettiioonn::**::ddeeffaauulltt'' lliisstt--ccoolloorrss $${{((ss..::..))LLSS__CCOOLLOORRSS}} (訳注: (s.:.) でコロン区切りをsplitしている) デ フォルトの彩色は GNU llss コマンドと同じで,それを 望む場合はスタイル値に空文字列を設定すればよい。 lliisstt--ggrroouuppeedd `true' (デフォルト) にセットすると補完システムは 一 覧 表示をグルーピングマッチを利用してよりコンパクト にしようと試みる。たとえば,コマンドに対す る オ プ ショ ンの説明文字列(vveerrbboosseeスタイルが `true' のとき に表示される)が同じものどうしは1つのエントリとし て 出現する。 (訳注: 導入以後 `false' に戻ることもなさ そうだからこのスタイルは気にしなくてよかろう) lliisstt--ppaacckkeedd ddeeffaauulltt タグに加えて,現在のコンテクストで有効な タ グ す べてで調べられる。`true' にセットされていると LLIISSTT__PPAACCKKEEDD オプションがセットされているかのよう に 一覧表示される。`false' は普通どおり。 lliisstt--pprroommpptt ddeeffaauulltt タグに対して設定されていると,候補一覧表示 のときに画面からあふれるときに1画面ごとにプロンプト を 出して止まる。スタイル値に空でない文字列が設定さ れているとその文字列がプロンプトとして用いられ る。 (zzsshh//ccoommpplliisstt モジュール(_z_s_h_m_o_d_u_l_e_s(1))も参照). 値 に は `%%' で始まるエスケープシーケンスも使える。 `%%ll' または `%%LL' は,表示されている最後の行数/全 行 数。 `%%mm' ま たは `%%MM' は,表示されている最後の項 番/全項目数。 `%%pp' または `%%PP' は,表示されている位 置 の パ ー セ ン テ ージ (先頭なら `TToopp',末尾なら `BBoottttoomm')に置き換えられる。いずれの場合も小文字の方 は プロンプト表示幅が変動するが,大文字の方は右側に スペースを詰めた固定幅になる。 `%%SS' と `%%ss' は 強 調, 強 調 解 除, `%%BB' と `%%bb' は太字,太字解除, `%%UU',と `%%uu' は下線,下線解除に使え る。 `%%{{...%%}}' はエスケープシーケンスを表示幅0と見なすために括る。 プロンプトを出すのをやめるには zzssttyyllee --dd してこの値 を 削除するだけではだめで,変数 LLIISSTTPPRROOMMPPTT を unset する必要がある。 lliisstt--rroowwss--ffiirrsstt lliisstt--ppaacckkeedd スタイルと 同 じ よ う に 調 べ ら れ, LLIISSTT__RROOWWSS__FFIIRRSSTT オプションと同様,補完一覧表示を横 zsh 4.3.2 March 2, 2006 34 ZSHCOMPSYS(1) ZSHCOMPSYS(1) 進みにする。 (訳注: デフォルトの一覧表示は llss と 同 じ縦進み) lliisstt--ssuuffffiixxeess ファ イ ル 名補完を行なう関数で使われる。 `true' に セットすると,補完を既に入力された複数のパスコン ポ ー ネントを含めた文字列に対して行なわれ,一意に定ま らないコンポーネントが表示される。セットしないと 補 完は最初のあいまいなパスコンポーネントで止まる。 lliisstt--sseeppaarraattoorr 訳 注: スタイルはいったんやめて次のセクション行きま す。 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). llooccaall 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: zzssttyyllee ''::ccoommpplleettiioonn::**'' llooccaall ttooaasstt \\ //vvaarr//hhttttpp//ppuubblliicc//ttooaasstt ppuubblliicc__hhttmmll Completion after `hhttttpp::////ttooaasstt//ssttuuffff//' will look for files in the directory //vvaarr//hhttttpp//ppuubb-- lliicc//ttooaasstt//ssttuuffff, while completion after `hhttttpp::////ttooaasstt//~~yyoouussiirr//' will look for files in the directory ~~yyoouussiirr//ppuubblliicc__hhttmmll. mmaaiill--ddiirreeccttoorryy If set, zsh will assume that mailbox files can be found in the directory specified. It defaults to `~~//MMaaiill'. mmaattcchh--oorriiggiinnaall This is used by the __mmaattcchh completer. If it is set to oonnllyy, __mmaattcchh 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. mmaattcchheerr こ のスタイルはカレントコンテクストでの正当なタグす zsh 4.3.2 March 2, 2006 35 ZSHCOMPSYS(1) ZSHCOMPSYS(1) べてで独立に参照される。この値は mmaattcchheerr--lliisstt で 設 定されているマッチ仕様に追加される。書式は _z_s_h_c_o_m_p_- _w_i_d(1) の `Matching Control' 節参照。 mmaattcchheerr--lliisstt このスタイルにはすべての場所で適用されるマッチ仕 様 を 設 定する。マッチ仕様については _z_s_h_c_o_m_p_w_i_d(1) の `Matching Control' 節参照。このスタイルには(シェ ル の)単語的に複数の値を設定でき,選択されたコンプリー タで順次この値を適用する。たとえば,もし, 普 通 の マッ チングを行なってそれで見つからなければ始めて大 文字小文字無視でマッチさせる補完をさせたければ, zzssttyyllee ''::ccoommpplleettiioonn::**'' mmaattcchheerr--lliisstt '''' ''mm::{{aa--zzAA--ZZ}}=={{AA--ZZaa--zz}}'' のようにする。デフォルトでは2つ目以降の仕様指定はそ れ以前のものを上書きするが,指定の先頭に ++ を付ける と追加する。これにより重複なしで徐々にマッチング 規 則を緩くしていくのが可能となっている。たとえば, zzssttyyllee ''::ccoommpplleettiioonn::**'' mmaattcchheerr--lliisstt '''' ''++mm{{aa--ZZ}}=={{AA--ZZ}}'' ''++mm{{AA--ZZ}}=={{aa--zz}}'' と すると,最初は,文字そのままでマッチさせ,それで だめなら小文字を大文字に変換してマッチ,それでも だ め なら小文字を大文字に変換することも追加で行なって マッチ,という風になる。特定のコンプリータ だ け に マッ チ仕様の指定を行なうこともでき,その場合はコン テクスト第3フィールド(つまりcompleterの位置)にそ の コンプリータを書けばよい。たとえば, __ccoommpplleettee コン プリータと __pprreeffiixx コンプリータを使っている場合で, __ccoommpplleettee コンプリータだけに大文字小文字無視マッチ を適用させたいなら, zzssttyyllee ''::ccoommpplleettiioonn::**'' ccoommpplleetteerr __ccoommpplleettee __pprreeffiixx zzssttyyllee ''::ccoommpplleettiioonn::**::ccoommpplleettee::**'' mmaattcchheerr--lliisstt \\ '''' ''mm::{{aa--zzAA--ZZ}}=={{AA--ZZaa--zz}}'' のようにする。 User-defined names, as explained for the ccoommpplleetteerr 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: zzssttyyllee ''::ccoommpplleettiioonn::**'' ccoommpplleetteerr __ccoommpplleettee __ccoorrrreecctt __ccoommpplleettee::ffoooo zzssttyyllee ''::ccoommpplleettiioonn::**::ccoommpplleettee::**'' mmaattcchheerr--lliisstt \\ '''' ''mm::{{aa--zzAA--ZZ}}=={{AA--ZZaa--zz}}'' zzssttyyllee ''::ccoommpplleettiioonn::**::ffoooo::**'' mmaattcchheerr--lliisstt \\ ''mm::{{aa--zzAA--ZZ}}=={{AA--ZZaa--zz}} rr::||[[--__..//]]==** rr::||==**'' 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 __ccoorrrreecctt and __aapppprrooxxiimmaattee do not use the match specifications at all, though these completers will only ever called once even if the mmaattcchheerr--lliisstt contains more than one element. Where multiple specifications are useful, note that the _e_n_t_i_r_e completion is done for each element of mmaattcchheerr--lliisstt, 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. mmaaxx--eerrrroorrss This is used by the __aapppprrooxxiimmaattee and __ccoorrrreecctt 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 `nnuummeerriicc', the completer function will take any numeric argument as the maximum number of errors allowed. For example, with zzssttyyllee ''::ccoommpplleettiioonn::**::aapppprrooxxiimmaattee::::::'' mmaaxx--eerrrroorrss 22 nnuummeerriicc two errors are allowed if no numeric argument is given, but with a numeric argument of six (as in `EESSCC--66 TTAABB'), up to six errors are accepted. Hence with a value of `00 nnuummeerriicc', no correcting comple- tion will be attempted unless a numeric argument is given. If the value contains the string `nnoott--nnuummeerriicc', the completer will _n_o_t 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, `22 nnoott--nnuummeerriicc' 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 `22 nnuummeerriicc'. mmaaxx--mmaattcchheess--wwiiddtthh 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 vveerrbboossee 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. mmeennuu 現在の補完で定義されているタグのコンテクストで, こ の 値が `true' のときはメニュー補完が用いられる。タ グつきで指定されている値は,`ddeeffaauulltt' タグのもの よ りも優先する。 If none of the values found in this way is true but at least one is set to `aauuttoo', the shell behaves as if the AAUUTTOO__MMEENNUU option is set. If one of the values is explicitly set to false, menu completion will be explicitly turned off, overriding the MMEENNUU__CCOOMMPPLLEETTEE option and other set- tings. In the form `yyeess==_n_u_m', where `yyeess' may be any of the true values (`yyeess', `ttrruuee', `oonn' and `11'), menu completion will be turned on if there are at least _n_u_m matches. In the form `yyeess==lloonngg', 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 `yyeess==lloonngg--lliisstt' (Typically, the value `sseelleecctt==lloonngg--lliisstt' described later is more useful as it provides control over scrolling.) Similarly, with any of the `false' values (as in `nnoo==1100'), menu completion will _n_o_t be used if there are _n_u_m or more matches. The value of this widget also controls menu selec- tion, as implemented by the zzsshh//ccoommpplliisstt module. The following values may appear either alongside or instead of the values above. If the value contains the string `sseelleecctt', menu selection will be started unconditionally. In the form `sseelleecctt==_n_u_m', menu selection will only be started if there are at least _n_u_m 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`nnoo--sseelleecctt'. 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 `sseelleecctt==lloonngg'. To start menu selection even if the current widget only performs listing, use the value `sseelleecctt==lloonngg--lliisstt'. To turn on menu completion or menu selection when a there are a certain number of matches _o_r the list of matches does not fit on the screen, both of `yyeess==' and `sseelleecctt==' may be given twice, once with a number and once with `lloonngg' or `lloonngg--lliisstt'. Finally, it is possible to activate two special modes of menu selection. The word `iinntteerraaccttiivvee' in the value causes interactive mode to be entered immediately when menu selection is started; see the description of the zzsshh//ccoommpplliisstt module in _z_s_h_m_o_d_- _u_l_e_s(1)for a description of interactive mode. Including the string `sseeaarrcchh' does the same for incremental search mode. To select backward incre- mental search, include the string `sseeaarrcchh--bbaacckk-- wwaarrdd'. mmuuttttrrcc If set, gives the location of the mutt configura- tion file. It defaults to `~~//..mmuuttttrrcc'. nnuummbbeerrss This is used with the jjoobbss 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 `11', strings will only be used if all jobs differ in the first word on their command lines. oolldd--lliisstt こ のスタイルは __oollddlliisstt コンプリータによって使われ る。値が `aallwwaayyss' のときは、一覧を出す標 準 的 ウィ ジェッ トが今回マッチしたもののリストを保持するよう になる。 This is used by the __oollddlliisstt completer. If it is set to `aallwwaayyss', 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 `nneevveerr', giving the behaviour without the __oollddlliisstt 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 __oollddlliisstt. 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. たとえば、カーソルの下に修正案一 覧 を 出 す __ccoorr-- rreecctt__wwoorrdd ウィ ジェット(^^XXcc)を呼び出した場合を考え る。普通は次に ^^DD を押すとコマンドライン上の単語 で 普 通 の補完をする場合の候補一覧を出すが、 __oollddlliisstt と組み合わせると生成済みの修正案リストを表示する。 As another example consider the __mmaattcchh completer: with the iinnsseerrtt--uunnaammbbiigguuoouuss 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 __oollddlliisstt completer and setting this style to __mmaattcchh, the list of matches generated on the first attempt will be used again. oolldd--mmaattcchheess __aallll__mmaattcchheess コンプリータが使用する。 This is used by the __aallll__mmaattcchheess 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 `oonnllyy'. If the value is `oonnllyy', __aallll__mmaattcchheess 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 __aallll__mmaattcchheess completer unconditionally. One possible use is for either this style or the ccoomm-- pplleetteerr style to be defined with the --ee option to zzssttyyllee to make the style conditional. oolldd--mmeennuu This is used by the __oollddlliisstt 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 TTAABB. The default behaviour of __oollddlliisstt 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 __oollddlliisstt completer. For example, suppose you type ^^XXcc to generate a list of corrections, and menu completion is started in one of the usual ways. Usually, or with this style set to ffaallssee, typing TTAABB at this point would start trying to complete the line as it now appears. With __oollddlliisstt, it instead continues to zsh 4.3.2 March 2, 2006 40 ZSHCOMPSYS(1) ZSHCOMPSYS(1) cycle through the list of corrections. oorriiggiinnaall This is used by the __aapppprrooxxiimmaattee and __ccoorrrreecctt 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 ccoorrrreecctt--_n_u_m or aapppprrooxxiimmaattee--_n_u_m, where _n_u_m is the number of errors that were accepted. ppaacckkaaggeesseett This style is used when completing arguments of the Debian `ddppkkgg' program. It contains an override for the default package set for a given context. For example, zzssttyyllee ''::ccoommpplleettiioonn::**::ccoommpplleettee::ddppkkgg::ooppttiioonn----ssttaattuuss--11::**'' \\ ppaacckkaaggeesseett aavvaaiill causes available packages, rather than only installed packages, to be completed for `ddppkkgg ----ssttaattuuss'. ppaatthh The function that completes color names uses this style with the ccoolloorrss tag. The value should be the pathname of a file containing color names in the format of an X11 rrggbb..ttxxtt 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. ppiinnee--ddiirreeccttoorryy 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. ppoorrttss A list of Internet service names (network ports) to complete. If this is not set, service names are taken from the file `//eettcc//sseerrvviicceess'. pprreeffiixx--hhiiddddeenn 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'. pprreeffiixx--nneeeeddeedd 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'. pprreesseerrvvee--pprreeffiixx 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 `aa:://......' and so on. rraannggee This is used by the __hhiissttoorryy completer and the __hhiissttoorryy__ccoommpplleettee__wwoorrdd 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 `_m_a_x::_s_l_i_c_e', the last _s_l_i_c_e words will be completed; then if that yields no matches, the _s_l_i_c_e words before those will be tried and so on. This process stops either when at least one match was been found, or _m_a_x words have been tried. The default is to complete all words from the his- tory at once. rreegguullaarr This style is used by the __eexxppaanndd__aalliiaass completer and bindable command. If set to `ttrruuee' (the default), regular aliases will be expanded but only in command position. If it is set to `ffaallssee', reg- ular aliases will never be expanded. If it is set to `aallwwaayyss', regular aliases will be expanded even if not in command position. rreehhaasshh If this is set when completing external commands, the internal list (hash) of commands will be updated for each search by issuing the rreehhaasshh 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. rreemmoottee--aacccceessss If set to ffaallssee, 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 CCVVSS command. It is not always possible to know if connections are in fact to a remote site, so some may be pre- vented unnecessarily. rreemmoovvee--aallll--dduuppss The __hhiissttoorryy__ccoommpplleettee__wwoorrdd bindable command and the __hhiissttoorryy completer use this to decide if all dupli- cate matches should be removed, rather than just consecutive duplicates. sseelleecctt--pprroommpptt If this is set for the ddeeffaauulltt tag, its value will be displayed during menu selection (see the mmeennuu style above) when the completion list does not fit on the screen as a whole. The same escapes as for the lliisstt--pprroommpptt 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. sseelleecctt--ssccrroollll This style is tested for the ddeeffaauulltt tag and deter- mines how a completion list is scrolled during a menu selection (see the mmeennuu style above) when the completion list does not fit on the screen as a whole. If the value is `00' (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. sseeppaarraattee--sseeccttiioonnss This style is used with the mmaannuuaallss 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 `mmaannuuaall.._X', where _X is the section number. When the ggrroouupp--nnaammee style is also in effect, pages from different sections will appear separately. This style is also used simi- larly with the wwoorrddss 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'. sshhooww--ccoommpplleetteerr 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. ssiinnggllee--iiggnnoorreedd 1つしかマッチがないときに __iiggnnoorreedd コンプリー タ に よっ て使われる。このスタイル値を `sshhooww' にしておく と,唯一のマッチは挿入されず表示される。 `mmeennuu' に し ておくと,唯一のマッチと元の文字列がマッチとして 加えられ,メニュー補完を開始する。 ssoorrtt Many completion widgets call __ddeessccrriippttiioonn at some point which decides whether the matches are added sorted or unsorted (often indirectly via __wwaanntteedd or __rreeqquueesstteedd). 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 ttrruuee. __eexxppaanndd コンプリータの場合,`true' にセットされてい るとつねにソートする。`mmeennuu' の場合は展開結果を一個 ずつメニュー補完で提示する場合のみソートし,全て の 展開結果を一括で挿入する場合にはソートしない。 訳 注: 複数の語を含む配列変数の展開結果中,実在する ファイル名と同じものがあると,それらだけ先頭に寄 せ られる。 ssppeecciiaall--ddiirrss 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 ssppeecciiaall--ddiirrss to `....' when the current prefix is empty, is a single `..', or consists only of a path beginning with `....//'. Otherwise the value is `false'. zzssttyyllee --ee ''::ccoommpplleettiioonn::**'' ssppeecciiaall--ddiirrss \\ ''[[[[ $$PPRREEFFIIXX == ((....//))##((||..||....)) ]]]] &&&& rreeppllyy==((....))'' ssqquueeeezzee--ssllaasshheess 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 `ffoooo////bbaarr') 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. ssttoopp If set to `true', the __hhiissttoorryy__ccoommpplleettee__wwoorrdd bind- able command will stop once when reaching the beginning or end of the history. Invoking __hhiiss-- ttoorryy__ccoommpplleettee__wwoorrdd will then wrap around to the opposite end of the history. If this style is set to `false' (the default), __hhiissttoorryy__ccoommpplleettee__wwoorrdd will loop immediately as in a menu completion. ssttrriipp--ccoommmmeennttss 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 _u_s_e_r_@_h_o_s_t form. ssuubbsstt--gglloobbss--oonnllyy __eexxppaanndd コンプリータが使う。`true' の場合,グロッビ ン グと置換両方がコマンドラインにあるときに,置換だ けうまくいってもグロッビングがうまく行かない場合 に は 置 換 も し なかったことにする(□)。訳注: たとえ ば,`ffiillee==ffoooo' のときに, $${{ffiillee}}..** で __eexxppaanndd した とする。このとき, ffoooo..** にマッチするものがあれば, 通常通り展開結果をコマンドラインに挿入するが, マッ チするものがなければ $${{ffiillee}} 自体も展開しないことに する。 デフォルト値は `true'。 ssuuffffiixx __eexxppaanndd コンプリータで使われる。チルダまたは変数 展 開 のとき, `true' の場合はサフィクスを持たない場合 のみ展開される。 i.e. if it is something like `~~ffoooo' or `$$ffoooo' rather than `~~ffoooo//' or `$$ffoooo//bbaarr', unless that suffix itself contains characters eli- gible for expansion. デフォルト値は `true'。 ttaagg--oorrddeerr 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 ffiillee--ppaatttteerrnnss style for an exception to this behavior.) For example: zsh 4.3.2 March 2, 2006 45 ZSHCOMPSYS(1) ZSHCOMPSYS(1) zzssttyyllee ''::ccoommpplleettiioonn::**::ccoommpplleettee::--ccoommmmaanndd--::**'' ttaagg--oorrddeerr \\ ''ccoommmmaannddss ffuunnccttiioonnss'' 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 _o_n_l_y 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. !! _t_a_g_s... A string starting with an exclamation mark specifies names of tags that are _n_o_t to be used. The effect is the same as if all other possible tags for the context had been listed. _t_a_g::_l_a_b_e_l ... Here, _t_a_g is one of the standard tags and _l_a_b_e_l is an arbitrary name. Matches are generated as normal but the name _l_a_b_e_l is used in contexts instead of _t_a_g. This is not useful in words starting with !!. If the _l_a_b_e_l starts with a hyphen, the _t_a_g is prepended to the _l_a_b_e_l 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. _t_a_g::_l_a_b_e_l::_d_e_s_c_r_i_p_t_i_o_n As before, but ddeessccrriippttiioonn will replace the `%%dd' in the value of the ffoorrmmaatt style instead of the default description supplied by the completion function. Spaces in the description must be quoted with a backslash. A `%%dd' appearing in _d_e_s_c_r_i_p_t_i_o_n 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 `{{_p_a_t_1,,_p_a_t_2_._._.}}'. 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: zzssttyyllee ''::ccoommpplleettiioonn::**::**::--ccoommmmaanndd--::**'' ttaagg--oorrddeerr \\ ''ffuunnccttiioonnss::--nnoonn--ccoommpp **'' ffuunnccttiioonnss zzssttyyllee ''::ccoommpplleettiioonn::**::ffuunnccttiioonnss--nnoonn--ccoommpp'' iiggnnoorreedd--ppaatttteerrnnss ''__**'' On the first attempt, all tags will be offered but the ffuunnccttiioonnss tag will be replaced by ffuunncc-- ttiioonnss--nnoonn--ccoommpp. The iiggnnoorreedd--ppaatttteerrnnss style is set for this tag to exclude functions starting with an underscore. If there are no matches, the second value of the ttaagg--oorrddeerr 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: zzssttyyllee ''::ccoommpplleettiioonn::**'' ttaagg--oorrddeerr \\ ''ooppttiioonnss::--lloonngg::lloonngg\\ ooppttiioonnss ooppttiioonnss::--sshhoorrtt::sshhoorrtt\\ ooppttiioonnss ooppttiioonnss::--ssiinnggllee--lleetttteerr::ssiinnggllee\\ lleetttteerr\\ ooppttiioonnss'' zstyle ':completion:*:options-long' ignored-patterns '[-+](|-|[^-]*)' zstyle ':completion:*:options-short' ignored-patterns '--*' '[-+]?' zstyle ':completion:*:options-single-letter' ignored-patterns '???*' With the ggrroouupp--nnaammeess 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 mmaattcchheerr--lliisstt 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 ffoooo: zsh 4.3.2 March 2, 2006 47 ZSHCOMPSYS(1) ZSHCOMPSYS(1) zzssttyyllee ''::ccoommpplleettiioonn::**::**::ffoooo::**'' ttaagg--oorrddeerr ''**'' ''**::--ccaassee'' zzssttyyllee ''::ccoommpplleettiioonn::**--ccaassee'' mmaattcchheerr ''mm::{{aa--zz}}=={{AA--ZZ}}'' First, all the tags offered when completing after ffoooo are tried using the normal tag name. If that generates no matches, the second value of ttaagg--oorrddeerr is used, which tries all tags again except that this time each has --ccaassee appended to its name for lookup of styles. Hence this time the value for the mmaattcchheerr style from the second call to zzssttyyllee in the example is used to make completion case-insen- sitive. It is possible to use the --ee option of the zzssttyyllee builtin command to specify conditions for the use of particular tags. For example: zzssttyyllee --ee ''**::--ccoommmmaanndd--::**'' ttaagg--oorrddeerr '' iiff [[[[ --nn $$PPRREEFFIIXX$$SSUUFFFFIIXX ]]]];; tthheenn rreeppllyy==(( )) eellssee rreeppllyy==(( -- )) ffii'' Completion in command position will be attempted only if the string typed so far is not empty. This is tested using the PPRREEFFIIXX special parameter; see zshcompwid for a description of parameters which are special inside completion widgets. Setting rreeppllyy 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 ttaagg--oorrddeerr style has been defined for a con- text, the strings `((||**--))aarrgguummeenntt--** ((||**--))ooppttiioonn--** vvaalluueess' and `ooppttiioonnss' 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. uurrllss This is used together with the the uurrllss 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 `hhttttpp', `ffttpp', `bbooookkmmaarrkk' 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, zzssttyyllee ''::ccoommpplleettiioonn::**'' uurrllss ~~//..uurrllss mmkkddiirr --pp ~~//..uurrllss//ffttpp//ffttpp..zzsshh..oorrgg//ppuubb//ddeevveellooppmmeenntt allows completion of all the components of the URL ffttpp::////ffttpp..zzsshh..oorrgg//ppuubb//ddeevveellooppmmeenntt after suitable commands such as `nneettssccaappee' or `llyynnxx'. Note, how- ever, that access methods and files are completed separately, so if the hhoossttss style is set hosts can be completed without reference to the uurrllss style. See the description in the function __uurrllss itself for more information (e.g. `mmoorree $$^^ffppaatthh//__uurrllss((NN))'). uussee--ccaacchhee If this is set, the completion caching layer is activated for any completions which use it (via the __ssttoorree__ccaacchhee, __rreettrriieevvee__ccaacchhee, and __ccaacchhee__iinnvvaalliidd functions). The directory containing the cache files can be changed with the ccaacchhee--ppaatthh style. uussee--ccoommppccttll If this style is set to a string _n_o_t equal to ffaallssee, 00, nnoo, and ooffff, the completion system may use any completion specifications defined with the ccoommppccttll builtin command. If the style is unset, this is done only if the zzsshh//ccoommppccttll module is loaded. The string may also contain the substring `ffiirrsstt' to use completions defined with `ccoommppccttll --TT', and the substring `ddeeffaauulltt' to use the comple- tion defined with `ccoommppccttll --DD'. Note that this is only intended to smooth the tran- sition from ccoommppccttll to the new completion system and may disappear in the future. Note also that the definitions from ccoommppccttll will only be used if there is no specific completion function for the command in question. For example, if there is a function __ffoooo to complete arguments to the command ffoooo, ccoommppccttll will never be invoked for ffoooo. However, the ccoommppccttll version will be zsh 4.3.2 March 2, 2006 49 ZSHCOMPSYS(1) ZSHCOMPSYS(1) tried if ffoooo only uses default completion. uussee--iipp By default, the function __hhoossttss 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 hhoossttss style is set; note also it must be set before the cache of host names is gen- erated (typically the first completion attempt). uussee--ppeerrll 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. uusseerrss 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. uusseerrss--hhoossttss The values of this style should be of the form `_u_s_e_r@@_h_o_s_t' or `_u_s_e_r::_h_o_s_t'. 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 rrllooggiinn and sssshh, by using the mmyy--aaccccoouunnttss tag. Similarly, values for sets of commands which usually refer to the accounts of other people, such as ttaallkk and ffiinnggeerr, can be grouped by using the ootthheerr--aaccccoouunnttss tag. More ambivalent commands may use the aaccccoouunnttss tag. uusseerrss--hhoossttss--ppoorrttss Like uusseerrss--hhoossttss but used for commands like tteellnneett and containing strings of the form `_u_s_e_r@@_h_o_s_t::_p_o_r_t'. zsh 4.3.2 March 2, 2006 50 ZSHCOMPSYS(1) ZSHCOMPSYS(1) vveerrbboossee 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'. wwoorrdd This is used by the __lliisstt 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. CCOONNTTRROOLL FFUUNNCCTTIIOONNSS ccoommppiinniitt は,補完を行なう関数すべてのウィジェットを再定義 して,与えられたウィジェット関数 __mmaaiinn__ccoommpplleettee を呼ぶよう に す る。この関数は,マッチするものを生成する「コンプリー タ」と呼ばれる関数を呼 ぶ ラッ パ ー と なっ て い る。 も し,`__mmaaiinn__ccoommpplleettee' が引数つきで呼ばれたときには,それら は補完関数と見なされ,その順番で呼ばれることになる。引数な し なら,補完を試みる関数は ccoommpplleetteerr スタイルから取得され る。たとえば,通常の補完関数をまず呼んで,それでマッチする も のがなければ綴違い修正関数を呼ばせたければ,ccoommppiinniitt し たあとで zzssttyyllee ''::ccoommpplleettiioonn::**'' ccoommpplleetteerr __ccoommpplleettee __ccoorrrreecctt とする。このスタイルのデフォルト値は `__ccoommpplleettee __iiggnnoorreedd' で,通常の補完を,まず iiggnnoorreedd--ppaatttteerrnnss スタイルの効果あり で,続いて効果なしで,という順番で試みる。 __mmaaiinn__ccoommpplleettee 関数は各コンプリータ関数のリターンコードを見て,次のコンプ リータを呼ぶかどうか決める。リターンコード0なら,残りの コ ンプリータは呼ばずに __mmaaiinn__ccoommpplleettee 関数自体から抜ける。 も し __mmaaiinn__ccoommpplleettee の最初の引数がハイフン1字なら,引数は コンプリータの名前とは見なされず, 2つ目の引数はコンテクス ト の ccoommpplleetteerr フィールドの値に,残りの引数はマッチするも のを生成する関数名とその引数と見なされる。 以下のコンプリータ関数は配布物に含まれているものだが,ユー ザは自分専用のものを書くことができる。関数名はアンダースコ アで始まるが,コンテクストでは先頭のアンダースコアは取り除 か れ る こ とに注意せよ。たとえば,基本の補完は `::ccoommppllee-- ttiioonn::::ccoommpplleettee::_._._.' というコンテクストで実行される。 __aallll__mmaattcchheess このコンプリータは,「それ以外のマッチすべて」か ら な る文字列を追加するために使われる。これは以後呼ば れるコンプリータに影響を与えるためのものなので, 一 連 のコンプリータの先頭に登場する必要がある。マッチ zsh 4.3.2 March 2, 2006 51 ZSHCOMPSYS(1) ZSHCOMPSYS(1) するものすべ て の リ ス ト は aavvooiidd--ccoommpplleetteerr と oolldd--mmaattcchheess スタイルの影響を受ける。 後 述する __ggeenneerriicc 関数を利用して __aallll__mmaattcchheess 自身 にキーを割り当てるとよい。たとえば以下のよ う に す る。 zzllee --CC aallll--mmaattcchheess ccoommpplleettee--wwoorrdd __ggeenneerriicc bbiinnddkkeeyy ''^^XXaa'' aallll--mmaattcchheess zzssttyyllee ''::ccoommpplleettiioonn::aallll--mmaattcchheess::**'' oolldd--mmaattcchheess oonnllyy zzssttyyllee ''::ccoommpplleettiioonn::aallll--mmaattcchheess::::::::'' ccoommpplleetteerr __aallll__mmaattcchheess 註: これだけでは補完はされない。最初に候補一覧を出 してから ^^XXaa を押してマッチするものすべてを出す。 __aapppprrooxxiimmaattee 基本コンプリータの __ccoommpplleettee に似ているが,補完に綴 り 修正を受けることを許可する。許される間違いの上限 の個数は mmaaxx--eerrrroorrss スタイルで指定する。個数の数 え 方 については _z_s_h_e_x_p_n(1) 参照。通常このコンプリータ は,普通の __ccoommpplleettee コンプリータのあとでだけ試行さ れる。 zzssttyyllee ''::ccoommpplleettiioonn::**'' ccoommpplleetteerr __ccoommpplleettee __aapppprrooxxiimmaattee と すると普通の補完で補完候補を得られなかった場合に 限り修正補完をする。もし,修正により補完候補がみ つ かっ た場合はコンプリータはそれらを巡回できるようメ ニュー補完を開始する。 このコンプリータは,修正候補と元の文字列を生成す る ときに ccoorrrreeccttiioonnss と oorriiggiinnaall タグを利用する。前者 用の ffoorrmmaatt スタイルには `%%ee' と `%%oo' を含ませる こ と ができ,それぞれ修正に要したエラー数および,元の 文字列,に置き換えられる。 訳注: こんな感じ。 zzssttyyllee ''::ccoommpplleettiioonn::**::aapppprrooxxiimmaattee**::**::**::ccoorrrreeccttiioonnss'' \\ ffoorrmmaatt ''%%BB%%dd ((eerrrroorrss==%%ee)) ((oorriiggiinnaall==%%oo))%%bb'' zzssttyyllee ''::ccoommpplleettiioonn::**'' ccoommpplleetteerr __ccoommpplleettee __aapppprrooxxiimmaattee 訳注終わり。 このコンプリータは mmaaxx--eerrrroorrss スタイルで指定され た 最 大エラー数を徐々に増やして行くので,もし「エラー 修正数1」でみつかったら,修正数2以上のものは出て こ な い。修正数2でみつかった場合は3以上が出ない…,以 下同様。またコンテクストのコンプリータ名のところ に は,現在試行されているエラー修正数が,修正数1のとき は `aapppprrooxxiimmaattee--11',修正数2のときは `aapppprrooxxiimmaattee--22'…,と変わるようになっている。 __aapppprrooxxiimmaattee を別の関数から呼ぶときは --aa オプション zsh 4.3.2 March 2, 2006 52 ZSHCOMPSYS(1) ZSHCOMPSYS(1) に 続 け て 許 容エラー数を渡すことができる。引数は mmaaxx--eerrrroorrss スタイルと同じ書式で,1つの文字 列 に す る。 こ の コ ン プ リ ータ(と後述の __ccoorrrreecctt コンプリー タ)は,とくに大きな許容エラー数を指定して呼んだとき に 厖 大なコストがかかる可能性を持つ。そこで, ccoomm-- pplleetteerr スタイルを定義するときに, zzssttyyllee の --ee オプ ションを使って,全く同じ文字列に対して2回連続で補完 しようとしたときにそうしたコンプリータが呼ばれる よ うにすることもできる。例: zzssttyyllee --ee ''::ccoommpplleettiioonn::**'' ccoommpplleetteerr '' iiff [[[[ $$__llaasstt__ttrryy !!== ""$$HHIISSTTNNOO$$BBUUFFFFEERR$$CCUURRSSOORR"" ]]]];; tthheenn __llaasstt__ttrryy==""$$HHIISSTTNNOO$$BBUUFFFFEERR$$CCUURRSSOORR"" rreeppllyy==((__ccoommpplleettee __mmaattcchh __pprreeffiixx)) eellssee rreeppllyy==((__iiggnnoorreedd __ccoorrrreecctt __aapppprrooxxiimmaattee)) ffii'' ここではzleと補完ウィジェット内部で使える HHIISSTTNNOO 変 数と,BBUUFFFFEERR,CCUURRSSOORR 特殊変数を使い,直前に補完した と きとコマンドラインが同じかどうか調べ,そのときだ け __iiggnnoorreedd,__ccoorrrreecctt,__aapppprrooxxiimmaattee コンプリータ が 呼ばれるようにしている。 __ccoommpplleettee コ ンテクストに即した方法で,すべての補完候補を生成 するコンプリータ。つまり,ccoommppddeeff 関数(解説済 み)で 定 義 した設定とすべての特殊変数の現在の値を使う(訳 注: 分からない人にとっては「つまり…」になってな い やん乱暴だなあ)。通常の補完動作を与えているのがこの コンプリータである。 コマンドの引数を補完するために __ccoommpplleettee はユーティ リ ティ 関数の __nnoorrmmaall を呼び,今度はそれが特別な関 数(後述)を探し出 す 役 割 を 受 け 持 つ。 こ の と き(□),`--_c_o_n_t_e_x_t--' という形式の様々なコンテクスト がはっきりと区別される。これらコンテクストなどに つ い ては文書前半の ##ccoommppddeeff タグの引数の説明に書かれ ている。 固有のコンテクスト用の関数を探す前に, __ccoommpplleettee は 変数 `ccoommppccoonntteexxtt' がセットされているか調べる。たと えば自作関数で入力に vvaarreedd を使ったりする局面などで は 通常の補完関数の振り分け(dispatch)をオーバーライ ドできると便利でそのようなときに `ccoommppccoonntteexxtt' 変数 が 使える。もし値に配列を入れておけば,各要素は補完 候補となり, `vvaalluueess' タグと `vvaalluuee' デスクリプショ ン(△)を 用いて補完されるようになる(△ 訳注: 分かん ないけど飛ばす)。 また,連想配列の値を入れておけば,各キーが 補 完 候 zsh 4.3.2 March 2, 2006 53 ZSHCOMPSYS(1) ZSHCOMPSYS(1) 補,値(value)がそれに対応する説明文字列として使われ る。また,コロンを含んだ文字列を `_t_a_g::_d_e_s_c_r::_a_c_t_i_o_n' のような形式で入れておくとそれは, 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 `ccoommppccoonntteexxtt' is set to a string con- taining colons, it should be of the form `_t_a_g::_d_e_s_c_r::_a_c_t_i_o_n'. In this case the _t_a_g and _d_e_s_c_r give the tag and description to use and the _a_c_t_i_o_n indicates what should be completed in one of the forms accepted by the __aarrgguummeennttss utility function described below. 最後に,コロンなしの文字列を入れておくと,その値 が コ ンテクストとして使われ,それ用の関数が呼ばれるこ とになる。この目的のために,--ccoommmmaanndd--lliinnee-- という名 前 の特別なコンテクストがあり,それはコマンドライン 全体(コマンドとその引数)を補完する(△???)。これは補 完 システム自体は使用していないが,明示的に呼ばれる と処理される。 訳注: あら,__ccoommpplleettee の説明終わっちゃっ た。 こ れ じゃ 分からんよなあ。わからんけど,分かるような説明 も書けんか。訳注終わり。 __ccoorrrreecctt 現在の語に対する補完ではなく,綴り「修正」のみを 生 成 する。 __aapppprrooxxiimmaattee に似ているが,カーソル位置以 降に文字を補うことはせず,既に入力し終えた単語の ス ペ ルチェック(&修正)のように機能する。 __aapppprrooxxiimmaattee に基づくコンプリータだが,コンテクストのコンプリ ー タフィールドは ccoorrrreecctt となる。 For example, with: zzssttyyllee ''::ccoommpplleettiioonn::::::::::'' ccoommpplleetteerr __ccoommpplleettee __ccoorrrreecctt __aapppprrooxxiimmaattee zzssttyyllee ''::ccoommpplleettiioonn::**::ccoorrrreecctt::::::'' mmaaxx--eerrrroorrss 22 nnoott--nnuummeerriicc zzssttyyllee ''::ccoommpplleettiioonn::**::aapppprrooxxiimmaattee::::::'' mmaaxx--eerrrroorrss 33 nnuummeerriicc 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 __ccoorrrreecctt is called as a function, the number of errors to accept may be given following the --aa option. The argument is in the same form a values to the aacccceepptt 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 __aapppprrooxxiimmaattee completer or, as in the example, just before it. Using it after the __aapppprrooxxiimmaattee completer is useless since __aapppprrooxxii-- mmaattee will at least generate the corrected strings generated by the __ccoorrrreecctt completer -- and probably more. __eexxppaanndd 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 ccoommpplleettee--wwoorrdd, not eexxppaanndd--oorr--ccoommpplleettee (the default binding for TTAABB), 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 __ccoommpplleettee completer function. The tags used when generating expansions are aallll--eexxppaannssiioonnss for the string containing all possi- ble expansions, eexxppaannssiioonnss when adding the possible expansions as single matches and oorriiggiinnaall when adding the original string from the line. The order in which these strings are generated, if at all, can be controlled by the ggrroouupp--oorrddeerr and ttaagg--oorrddeerr styles, as usual. The format string for aallll--eexxppaannssiioonnss and for eexxppaann-- ssiioonnss may contain the sequence `%%oo' which will be replaced by the original string from the line. The kind of expansion to be tried is controlled by the ssuubbssttiittuuttee, gglloobb and ssuubbsstt--gglloobbss--oonnllyy styles. It is also possible to call __eexxppaanndd as a function, in which case the different modes may be selected with options: --ss for ssuubbssttiittuuttee, --gg for gglloobb and --oo for ssuubbsstt--gglloobbss--oonnllyy. __eexxppaanndd__aalliiaass 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 rreegguullaarr, gglloobbaall and ddiiss-- aabblleedd. This function is also a bindable command, see the section `Bindable Commands' below. __hhiissttoorryy 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 rreemmoovvee--aallll--dduuppss, and ssoorrtt styles as for the __hhiiss-- ttoorryy__ccoommpplleettee__wwoorrdd bindable command, see the sec- tion `Bindable Commands' below and the section `Completion System Configuration' above. __iiggnnoorreedd The iiggnnoorreedd--ppaatttteerrnnss 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 iiggnnoorreedd--ppaatttteerrnnss 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 __pprreeffiixx completer. The ssiinn-- ggllee--iiggnnoorreedd style is also available as described above. __lliisstt 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 ccoonnddiittiioonn and wwoorrdd, see the section `Completion System Con- figuration' above. __mmaattcchh This completer is intended to be used after the __ccoommpplleettee 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 GGLLOOBB__CCOOMMPPLLEETTEE 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 mmaattcchh--oorriiggiinnaall style described above. The generated matches will be offered in a menu completion unless the iinnsseerrtt--uunnaammbbiigguuoouuss 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 mmaattcchheerr--lliisstt and mmaattcchheerr) will not be used. __mmeennuu 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 __ggeenneerriicc 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 MMEENNUU__CCOOMMPPLLEETTEE option and does not work with the other menu com- pletion widgets such as rreevveerrssee--mmeennuu--ccoommpplleettee, or aacccceepptt--aanndd--mmeennuu--ccoommpplleettee. __oollddlliisstt 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: oolldd--lliisstt and oolldd--mmeennuu, see the section `Completion System Configuration' above. __pprreeffiixx 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 eexxppaanndd--oorr--ccoommpplleettee--pprreeffiixx command. The ccoommpplleetteerr 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 __pprreeffiixx 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 __pprreeffiixx will be called. For example, consider this global ccoommpplleetteerr style: zzssttyyllee ''::ccoommpplleettiioonn::**'' ccoommpplleetteerr \\ __ccoommpplleettee __pprreeffiixx __ccoorrrreecctt __pprreeffiixx::ffoooo Here, the __pprreeffiixx completer tries normal completion but ignoring the suffix. If that doesn't generate any matches, and neither does the call to the __ccoorr-- rreecctt completer after it, __pprreeffiixx 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 `ffoooo'. To use __pprreeffiixx as the last resort and try only nor- mal completion when it is invoked: zzssttyyllee ''::ccoommpplleettiioonn::**'' ccoommpplleetteerr __ccoommpplleettee ...... __pprreeffiixx zzssttyyllee ''::ccoommpplleettiioonn::::pprreeffiixx::**'' ccoommpplleetteerr __ccoommpplleettee zsh 4.3.2 March 2, 2006 57 ZSHCOMPSYS(1) ZSHCOMPSYS(1) The aadddd--ssppaaccee style is also respected. If it is set to `true' then __pprreeffiixx will insert a space between the matches generated (if any) and the suf- fix. Note that this completer is only useful if the CCOOMM-- PPLLEETTEE__IINN__WWOORRDD 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. bbaasshhccoommppiinniitt This function provides compatibility with bash's programmable completion system. When run it will define the functions, ccoommppggeenn and ccoommpplleettee which correspond to the bash builtins with the same names. It will then be possible to use completion specifications and functions written for bash. BBIINNDDAABBLLEE CCOOMMMMAANNDDSS できるだけ直感に添えるよう作られたコンテクスト依存の補完だ けでなく,他の特殊なウィジェットがあり,キーに割り当てるこ とができる。以下にそれら一覧を示す。 __bbaasshh__ccoommpplleettiioonnss __bbaasshh__ccoommpplleettee--wwoorrdd と __bbaasshh__lliisstt--cchhooiicceess の2つの ウィジェットによって使われる関数で,bashの補完コ マ ン ドと互換のある機能を提供している。呼び出しキーの 最後のストロークで補完対象を切り替える。 `!!' ならコ マ ン ド 名,`$$' な ら 環境変数名, `@@' ならホスト 名,`//' ならファイル名, `~~' ならユーザ名を補 完 す る。 bashで は `\\ee' のあとにそれらのキーを押せば補 完, `\\^^XX' のあとに押せば一覧表示となるが,これらの うちいくつかはzshの標準キーバインドとかち合うのでデ フォルトでは `\\ee~~' と `^^XX~~' だけキーに割り当てて あ る。 残りのキーをbashと同じバインドで足すには以下の ようにする。 ffoorr kkeeyy iinn ''!!'' ''$$'' ''@@'' ''//'' ''~~'';; ddoo bbiinnddkkeeyy ""\\ee$$kkeeyy"" __bbaasshh__ccoommpplleettee--wwoorrdd bbiinnddkkeeyy ""^^XX$$kkeeyy"" __bbaasshh__lliisstt--cchhooiicceess ddoonnee This includes the bindings for `~~' in case they were already bound to something else; the comple- tion code does not override user bindings. __ccoorrrreecctt__ffiilleennaammee ((^^XXCC)) 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) __ccoorrrreecctt__wwoorrdd (^Xc) Performs correction of the current argument using the usual contextual completions as possible choices. This stores the string `ccoorrrreecctt--wwoorrdd' in the _f_u_n_c_t_i_o_n field of the context name and then calls the __ccoorrrreecctt completer. __eexxppaanndd__aalliiaass ((^^XXaa)) 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 rreegguullaarr, gglloobbaall and ddiissaabblleedd. When used as a bindable command there is one addi- tional feature that can be selected by setting the ccoommpplleettee style to `true'. In this case, if the word is not the name of an alias, __eexxppaanndd__aalliiaass 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 __eexxppaanndd__aalliiaass once more will expand the now-com- plete alias name. __eexxppaanndd__wwoorrdd ((^^XXee)) Performs expansion on the current word: equivalent to the standard eexxppaanndd--wwoorrdd command, but using the __eexxppaanndd completer. Before calling it, the _f_u_n_c_t_i_o_n field of the context is set to `eexxppaanndd--wwoorrdd'. __ggeenneerriicc 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 _f_u_n_c_t_i_o_n 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: zzllee --CC ffoooo ccoommpplleettee--wwoorrdd __ggeenneerriicc bbiinnddkkeeyy ''......'' ffoooo zzssttyyllee ''::ccoommpplleettiioonn::ffoooo::**'' mmeennuu yyeess sseelleecctt==11 Note in particular that the ccoommpplleetteerr style may be set for the context in order to change the set of functions used to generate possible matches. If __ggeenneerriicc is called with arguments, those are passed through to __mmaaiinn__ccoommpplleettee as the list of completers in place of those defined by the ccoommpplleetteerr style. __hhiissttoorryy__ccoommpplleettee__wwoorrdd (\e/) Complete words from the shell's command history. zsh 4.3.2 March 2, 2006 59 ZSHCOMPSYS(1) ZSHCOMPSYS(1) This uses the lliisstt, rreemmoovvee--aallll--dduuppss, ssoorrtt, and ssttoopp styles. __mmoosstt__rreecceenntt__ffiillee ((^^XXmm)) 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. __nneexxtt__ttaaggss (^Xn) This command alters the set of matches used to that for the next tag, or set of tags, either as given by the ttaagg--oorrddeerr 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. __rreeaadd__ccoommpp ((^^XX^^RR)) 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 `__ffiilleess --//', 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 ccoommppaadddd 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: `DDEELL' and `^^HH' delete the last character; `^^UU' deletes the line, and `^^CC' and `^^GG' abort the function, while `RREETT' 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 __rreeaadd__ccoommpp will use the existing string instead of reading a new one. To force a new string to be read, call __rreeaadd__ccoommpp with a numeric argument. __ccoommpplleettee__ddeebbuugg ((^^XX??)) 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) __ccoommpplleettee__hheellpp ((^^XXhh)) 現 在のカーソル位置でのコンテクストの各フィールド情 報を表示する。 1より大きな数引数をつけ る と(`EESSCC--22 ^^XXhh' など) そこで参照されるスタイルとそのときのコン テクストもすべて表示される。 ただし,スタイルに関する情報はユーザが独自に設定 し た スタイルなどで変わりうるので不完全であることに注 意。 __ccoommpplleettee__ttaagg ((^^XXtt)) This widget completes symbol tags created by the eettaaggss or ccttaaggss programmes (note there is no connec- tion with the completion system's tags) stored in a file TTAAGGSS, in the format used by eettaaggss, or ttaaggss, in the format created by ccttaaggss. It will look back up the path hierarchy for the first occurrence of either file; if both exist, the file TTAAGGSS is pre- ferred. You can specify the full path to a TTAAGGSS or ttaaggss file by setting the parameter $$TTAAGGSSFFIILLEE or $$ttaaggssffiillee respectively. The corresponding comple- tion tags used are eettaaggss and vvttaaggss, after emacs and vi respectively. UUTTIILLIITTYY FFUUNNCCTTIIOONNSS ここでは補完関数を書くときに有用なユーティリティ関数につい て述べる。 If functions are installed in subdirectories, most of these reside in the BBaassee subdirectory. 配布に含ま れるコマンド用の補完関数例のように,候補一覧を生成するユー ティリティ関数はすべて,候補を生成したならゼロ,しなかった なら非ゼロを返すという決まりに従っている。 また,__mmaaiinn__ccoommpplleettee 関数は補完を行なう直前と直後にそれ ぞ れ配列 ccoommpppprreeffuunnccss,配列 ccoommppppoossttffuunnccss に列挙された関数を 呼ぶ。各関数は明示的に自分自身を配列に再代入しない限り 1度 だ け呼ばれる(訳注: それがユーティリティ関数とどう関連する か書いてクレー???)。 __aallll__llaabbeellss [ --xx ] [ --1122VVJJ ] _t_a_g _n_a_m_e _d_e_s_c_r [ _c_o_m_m_a_n_d _a_r_g_s ... ] 下 記 __nneexxtt__llaabbeell 関数(該当箇所の説明にループを構築 する例がある) への手軽なインタフェース関 数。 _c_o_m_- _m_a_n_d とその引数が補完候補を生成するために呼ばれる。 _n_a_m_e に保存されたオプションは自動的に,_a_r_g_s に追 加 さ れ(_c_o_m_m_a_n_dにも渡され)る。通常それらは _c_o_m_m_a_n_d 直 後に挿入されるが,_a_r_g_s のどれかがハイフンのみの場合 は その直前に入れられる。ハイフンが最後の引数のとき は,最後のハイフンを削除する(△なじぇ)。こ れ に よ り,ccoommppaadddd や他のユーティリティ関数を1回だけ呼んで 補完候補を生成する よ う な ほ と ん ど の 場 所 で __aallll__llaabbeellss を使えるようになる(△???: はにゃ)。 zsh 4.3.2 March 2, 2006 61 ZSHCOMPSYS(1) ZSHCOMPSYS(1) たとえば, llooccaall eexxppll ...... iiff __rreeqquueesstteedd ffoooo;; tthheenn ...... __aallll__llaabbeellss ffoooo eexxppll ''......'' ccoommppaadddd ...... -- $$mmaattcchheess ffii と すると, __aallll__llaabbeellssが生成したものより優先される ような追加オプションを ccoommppaaddddにつけて, mmaattcchheess 変 数にある値を補完するようになる(△んむ???)。 __aalltteerrnnaattiivvee [ --CC _n_a_m_e ] _s_p_e_c ... 複 数のタグが利用可能な単純なケースで有用。本質的に これは __ttaaggss 関数(後述)で説明するループのようなもの を実装している。 使用するタグとそのとき遂行する処理は _s_p_e_c で `_t_a_g::_d_e_s_c_r::_a_c_t_i_o_n' という書式で指定する。 _t_a_g は __ttaaggss を使って与えられ,もしタグが要求された ら _a_c_t_i_o_n が _d_e_s_c_r を説明文字列として伴って実行され る。 _a_c_t_i_o_n は,下記 __aarrgguummeennttss 関数が受け付けるも のと同じ (ただし `-->>_s_t_a_t_e' と `==_._._.' を除く)。 たとえば,_a_c_t_i_o_n は単純な関数呼び出しでよく, __aalltteerrnnaattiivvee \\ ''uusseerrss::uusseerr::__uusseerrss'' \\ ''hhoossttss::hhoosstt::__hhoossttss'' とすると,ユーザ名とホスト名を補完候補とし て 提 示 し, そ れ らはそれぞれ __uusseerrss,__hhoossttss 関数が生成す る。 __aarrgguummeennttss 関数のように,この関数は __aallll__llaabbeellss を す べてのタグセットに関して繰り返してアクションを実 行するために使う。特別な処理は付加的な有効タグが あ る 場 合のみ(たとえば, __aalltteerrnnaattiivvee から呼ばれた関 数)される(△なんのこっちゃ???)。 __ttaaggss 関数と同様,--CC オプションで aarrgguummeenntt コンテク ストフィールドに別のものを与えられる。 訳 注: __ttaaggss 関数が分からないとこれを理解するのは困 難。上記の users, hosts の例を __ttaaggss のループで書く と,おそらくこのようになる。 llooccaall eexxppll rreett==11 zsh 4.3.2 March 2, 2006 62 ZSHCOMPSYS(1) ZSHCOMPSYS(1) __ttaaggss uusseerrss hhoossttss wwhhiillee __ttaaggss;; ddoo __rreeqquueesstteedd uusseerrss eexxppll ''uusseerr'' __uusseerrss &&&& rreett==00 __rreeqquueesstteedd hhoossttss eexxppll ''hhoosstt'' __hhoossttss &&&& rreett==00 (((( rreett )))) |||| rreettuurrnn rreett ddoonnee __aarrgguummeennttss [ --nnsswwWWAACCRRSS ] [ --OO _n_a_m_e ] [ --MM _m_a_t_c_h_s_p_e_c ] [ :: ] _s_p_e_c ... こ の関数は,標準的なUNIXのオプションと引数の流儀に 従うコマンドの完全な仕様を補完システムに教えるた め に 使う。以下に示す書式を使って個々のコマンドのオプ ション・引数のセットを指定して行くわけだが, __aarrgguu-- mmeenntt 自身へのオプションなのか対象となるコマンドのオ プション指定なのか紛らわしくなるので,区別しやす く す るためにそれらの間にコロンひとつを挟んでも構わな い(□訳注: ちゅーかこのマニュアル自身が __aarrgguummeennttss へ のオプションなのか,それによって補完されるコマン ドのオプションなのか判別しやすい工夫をしてないの が 痛い。気をつけて読んでくだされ。)。 __aarrgguummeennttss 自身 へのオプションは1字オプションだが必ず別の単語で指定 しなければならない(つまり --ss --ww をまとめて --ssww とす るのは不可(□))。 __aarrgguummeennttss に --nn オプションを指定すると,変数 NNOORR-- MMAARRGG に配列変数 wwoorrddss 中の最初の普通の引数の位置, つまりオプション指定が終わった最初の引数の位置, を 代 入するようになる。普通の引数まで辿り着かない場合 NNOORRMMAARRGG は --11 になる。呼び主となる関数では,--nn オプ ションが渡されたら必ず `iinntteeggeerr NNOORRMMAARRGG' する必要が ある。そうしておかないと変数が使われない(△???)。 訳注: 以下で登場する _m_e_s_s_a_g_e_s は,補完寺に補完対 象 を 説明する文として使われるが,デフォルトでは出てこ ない(と思う)。 zzssttyyllee ''::ccoommpplleettiioonn::**::ddeessccrriippttiioonnss'' \\ ffoorrmmaatt ''[[[[CCoommpplleettiinngg %%BB%%dd%%bb]]]]'' などとして説明文字列が出てくるようにしておこう。 訳 注終わり。 _n::_m_e_s_s_a_g_e::_a_c_t_i_o_n _n::::_m_e_s_s_a_g_e::_a_c_t_i_o_n 第var(n)番目の普通の引数(の情報)を記述する。 _m_e_s_s_a_g_e は,補完候補一覧の上に 表 示 さ れ, _a_c_t_i_o_n はこの位置で補完されるべきものを指示 する(方法については後述)。 ::::とコロ ン2つ を _m_e_s_s_a_g_e の 前 に 付けた場合は,その引数が任 意(optional)であることを指示する。また,_m_e_s_- _s_a_g_e が空白文字だけを含むときには補完候補一 覧の上には何も表示されない。た だ し,_a_c_t_i_o_n で何か説明の文字列を足している場合はそれが表 示される。 zsh 4.3.2 March 2, 2006 63 ZSHCOMPSYS(1) ZSHCOMPSYS(1) ::_m_e_s_s_a_g_e::_a_c_t_i_o_n ::::_m_e_s_s_a_g_e::_a_c_t_i_o_n 上記と同様。ただし,何番目 か に か か わ ら ずem(次の)引数についての記述となる。もしすべ ての引数を正しい順番で書くならば, _nを省略し たこの書き方だけ並べればよい(□)。 **::_m_e_s_s_a_g_e::_a_c_t_i_o_n **::::_m_e_s_s_a_g_e::_a_c_t_i_o_n **::::::_m_e_s_s_a_g_e::_a_c_t_i_o_n 上 記2つの記法による(オプションでない)引数に ついての記述がない引数は,ここで書いた記述に 従う。何番目の引数かの指定をとくに行なわない 書き方。 :::: とコロン2つを _m_e_s_s_a_g_e の前に書くと,特 殊 配 列変数 wwoorrddss と特殊変数 CCUURRRREENNTT は,(オプ ションでない)普通の引数を指すよう _a_c_t_i_o_n実行 時(評 価 時)に修正される。 :::::: とコロン3つを _m_e_s_s_a_g_e の前に書くと,この記法でカバーされる 普通の引数だけを指すように修正される。 (△訳 注???: どういうときに役立つか分からん) _o_p_t_s_p_e_c _o_p_t_s_p_e_c:_._._. 補完対象のコマンドのオプションを記述する。コ ロ ンを付けた場合,そのオプションは1つ以上の 引数を取ることを意味する。コロンなしの場合, そのオプションには引数がないことを意味する。 デフォルトではオプション名は2文字以上でも よ い ものとみなすが, __aarrgguummeennttss自身の --ss を指 定すると,補完対象のコマンドのオプショ ン は 1字だけと見なす。ただし,たとえば `----pprreeffiixx' のように, ---- で始まるオプションはやは り1つ の 完全なオプション名と見なす。これはGNU標準 に適っている。 --ss と --ww を両方指定すると,引数を取る1字オプ ショ ンが交ざっていたとしても,1字オプション どうしをまとめて指定できるものと見なす。たと え ば, あ る コマンドの --aa オプションが引数 を1つ取るものだとして, --ssなしのとき: `--aabb' はそれで1つのオプション(処理されない), --ssあ りのとき: `--aabb' は1つのオプ ショ ン と 引 数 `bb', --ss と --ww のとき: `--aabb' は --aa オプショ ンと --bb オプションの指定で,さらにその後引数 が来るものと期待される…,のように補完時の解 釈が変わる。 これらのルール解釈は,--WW を指定するともっ と 深 遠な領域へ: --WW をつけると,同じ単語内に現 れる引数のあとでも1字オプションを補完でき る ようになる。しかしその位置で実際に補完が行な zsh 4.3.2 March 2, 2006 64 ZSHCOMPSYS(1) ZSHCOMPSYS(1) われるかどうかは,遂行される _a_c_t_i_o_n に依存す る。より深く制御したい場合は __gguuaarrdd のような ユーティリティ関数をアクションの一部に使うと よい。 (訳注: -W の違いが分からない…。) さ て,最初の _o_p_t_s_p_e_c で利用できる書き方を以 下に示す。オプションに引数があってもなくても 構わない。 **_o_p_t_s_p_e_c こ の _o_p_t_s_p_e_c は下記のいずれかであ る。これは,_o_p_t_s_p_e_c が繰り返してもよ い ことを意味する。通常は(繰り返しは 自動的に避けられるので□),コマン ド ラインのカーソルより左側に入力済みの オプションは候補一覧から外れる。 (訳 注: 複 数回指定する可能性のあるオプ ションにはハイフンの直前に ** を指 定 しておく) --_o_p_t_n_a_m_e ++_o_p_t_n_a_m_e オ プ ショ ン 指 定 の最も単純な形式 で,_o_p_t_s_p_e_c にマイナスかプラスで始ま る オ プ ショ ン そ のものを書く(例: `--ffoooo')。オプションの最初の引数(がも し あるならそれ)はem(別の)単語として そのオプションの直後に来る必要 が あ る(△訳注: コロン要らないの?)。 `--++_o_p_t_n_a_m_e' または `++--_o_p_t_n_a_m_e' とい う形式で書けば,--_o_p_t_n_a_m_e と ++_o_p_t_n_a_m_e 両方のオプション指定が有効だと指定で きる。 下記のいずれの書式も,先頭の `--' は `++' に置き換えたり組み合わせたりでき る。 --_o_p_t_n_a_m_e-- そのオプションの第1引数が同じ単語 内 でそのオプションの直後に書くべきであ ることを示す。たとえ ば,`--ffoooo--::_._._.' と書くと,補完されたオプションとその 引数は,`--ffoooo_a_r_g' のようになる。 --_o_p_t_n_a_m_e++ 上記と似ているが,そのオプショ ン の 第1引 数は,同じ単語内のオプション直 後に来ても,次の単語に来てもよいこと を 示す。たとえば, `--ffoooo++::_._._.' の場 合,補完されたオプション と 引 数 は `--ffoooo_a_r_g' または `--ffoooo _a_r_g' のどちら ででも指定されうることを示す。 zsh 4.3.2 March 2, 2006 65 ZSHCOMPSYS(1) ZSHCOMPSYS(1) --_o_p_t_n_a_m_e== そのオプションの第1引数は,次の単 語 として指定するか,同じ単語内でイコー ルで区切って指定するかどちらかである ことを示す。たとえば, `--ffoooo==_a_r_g' ま たは `--ffoooo _a_r_g' のどちらででも指定さ れうる。 --_o_p_t_n_a_m_e==-- そのオプションへの引数が必ず同一単語 内でイコールを使って与えられるべきこ と を示す(訳注: 上と同じだが次の単語 では不可という場合)。 _o_p_t_s_p_e_c[[_e_x_p_l_a_n_a_t_i_o_n]] これまで説明した上記すべての _o_p_t_s_p_e_c には,そのオプションの説明文字列を大 括弧で括って `--qq[[qquueerryy ooppeerraattiioonn]]' のように追加指定することができる。 オプション一覧表示のときに,この説明 文字列をいっしょに表示するかどうかは vveerrbboossee スタイルで決定する。 説 明 文 字 列 の 指 定 が な い が,aauuttoo--ddeessccrriippttiioonn スタイルが セッ ト されていて _o_p_t_s_p_e_c にひとつだけ引 数の指定がある場合は,そのスタイルの 値 が 表示される。その文字列中にある `%%dd' は _o_p_t_s_p_e_c の後ろにある _o_p_t_a_r_g の最初の _m_e_s_s_a_g_e に置き換えられる(下 記参照)。 オプションとして `+' や `==' 自身そのものを書きた い 場合はたとえば `--\\++' のようにクォートする。 _o_p_t_s_p_e_c の後ろに続く _o_p_t_a_r_g は,以下のいずれかの形 式で記述する。 ::_m_e_s_s_a_g_e::_a_c_t_i_o_n ::::_m_e_s_s_a_g_e::_a_c_t_i_o_n そのオプションに対する引数に関する指定: _m_e_s_- _s_a_g_e と _a_c_t_i_o_n は普通の引数に対する記述と同 じように処理される。コロン1つで始まるほう は 必 ず 引 数を要求し,コロン2つのほうは引数が あってもなくてもよいことを意味する。 訳注: 「オプションに対する引数があってもなく て も いい?」というのはたとえば,configureの ----eennaabbllee--hhooggee==yyeess が ----eennaabbllee--hhooggee だけで も いいような場合がある。そういう場合は ----eennaabbllee--hhooggee==''[[QQuuiieett]]::::QQuuiieett MMooddee::((yyeess nnoo))'' zsh 4.3.2 March 2, 2006 66 ZSHCOMPSYS(1) ZSHCOMPSYS(1) などとするとよい。訳注終わり。 そのオプションが複数の引数を必要とするなら, この記法を引数の数だけ繰り返してよい。 つ ま り, ::_m_e_s_s_a_g_e_1::_a_c_t_i_o_n_1::_m_e_s_s_a_g_e_2::_a_c_t_i_o_n_2 とす ると2引数を取るオプションの指定となる。 ::**_p_a_t_t_e_r_n::_m_e_s_s_a_g_e::_a_c_t_i_o_n ::**_p_a_t_t_e_r_n::::_m_e_s_s_a_g_e::_a_c_t_i_o_n ::**_p_a_t_t_e_r_n::::::_m_e_s_s_a_g_e::_a_c_t_i_o_n 複数の引数の記述: 複数の引数を取るようなオプ ションに対するこの形式の _o_p_t_a_r_g は最後にだけ 書くことができる(訳注: そうでないとどこか ら 次のオプションや残りの引数を取っていいか分か らない)。もし _p_a_t_t_e_r_n が空(つまり ::**::)の場合 は,コマンドラインの残りのすべての引数をここ に書いた _a_c_t_i_o_n の方法で補完することを指定す る。 _p_a_t_t_e_r_n を指定した場合は,そのパターン にマッチする語を含む引数までは _a_c_t_i_o_n で補完 する。 訳注: たとえば,ffiinndd の --eexxeecc オプションのよ うに, \\;; までをコマンドと見なす,のようなも のはこれで指定する。訳注終わり。 複 数のコロンは普通の引数に対する `**::_._._.' と 同じように処理される -- コロン2つなら特殊 配 列 変 数 wwoorrddss と特殊変数 CCUURRRREENNTT は,(オプ ションでない)普通の引数を指すよう _a_c_t_i_o_n実行 時(評 価時)に修正される。コロン3つならそれら 変数が,この記法でカバーされる普通の引数だけ を指すように修正される。 以上でコロンそのものを値に含ませたい場合はバックスラッシュ でクォートして `\\::' のように書く。 上記いずれの書式でも,その前に括弧内に列挙したオプションや 引数の番号を置くことができる。そのオプションをコマンドライ ンで書いたときに括弧内に列挙したオプションや引数を候補から 外すことを意味する。たとえば,`((--ttwwoo --tthhrreeee 11))--oonnee::......' と 書くと `--oonnee' というオプションを補完候補に含めると同時に, コマンドラインにそれを書いたらそれより後ろの方では --ttwwoo オ プションも,`--tthhrreeee オプションも第1引数で補完すべきも の, い ずれも補完しないようにする。また,`((--ffoooo))::_._._.' は普通の 引数の補完指定の前に `--ffoooo' を置いたもので,もし普通の引数 を入力したあとには --ffoooo は補完しないことを意味する。 除外されるオプションリストには他の項目も書くことができ,そ の場の指定がマッチするときには該当項目が除外されるようにで き る。 ア ス タ リ ス ク1つ (**) は,残りの引数すべて(つま り`**::......' のような形),コロン1つ (::) は,普通の(オプション で ない)引数すべて,ハイフン1つ (--) は,すべてのオプション に対する指定となる。たとえば,`((**))' をオプションの前に書い た場合,そのオプションがコマンドライン中に挿入されたら,そ zsh 4.3.2 March 2, 2006 67 ZSHCOMPSYS(1) ZSHCOMPSYS(1) れより後ろには「残りの引数」 (上記の `::**' で始ま る _s_p_e_c) を補完しないことを意味する。 (訳注: 候補から外す目的で括弧 内に列挙する指定を「除外リスト」と呼ぶことにする。) こうした指定の再利用を助ける目的で上記記法の前に `!!' を 付 け る記法が用意されている。 `!!' を前置したオプションは補完 されなくなる。これが有用なケースは,引数が配列で与えられ, かつ __aarrgguummeennttss 関数が何度も,次第により限定的なコンテクス ト用に呼ばれるようなときである。たとえば最初の呼び出 し が `__aarrgguummeennttss $$gglloobbaall__ooppttiioonnss' で, そ の 後 の 呼び出しが `__aarrgguummeennttss !!$$^^gglloobbaall__ooppttiioonnss' という形式で呼んだりする 場 合である(訳注: 降って涌いたようなこの段落何?)。 上記の一連の記法で出てきた _a_c_t_i_o_n は,補完候補をどのように 生成するかを記述する。いずれも _a_c_t_i_o_n の部分が,すべてのラ ベルを処理するために __aallll__llaabbeellss 関数を呼んで実行される(た だし `-->>_s_t_r_i_n_g' の場合を除く)。関数呼び出しが新しいもの を 導入しない限りタグの特別な処理は必要とされない(△ ???)。 _a_c_t_i_o_n の部分の書式は以下の通り。 ` ' (クォートなしの空白1つ) そ の引数は必須だが,マッチを生成できないまたは生成 しない方がよいものであることを指定 す る。 こ の 場 合,_m_e_s_s_a_g_e は表示されるものの候補一覧は表示されな い。ただし,この場合でも _m_e_s_s_a_g_e の終端を示すコロン は必要で,省略してよいのは _m_e_s_s_a_g_e,_a_c_t_i_o_n 両方とも 省略する場合である。 訳注: `----nnaammee::YYoouurr NNaammee:: ::' とすると ----nnaammee の後 ろ では補完しない。 ((_i_t_e_m_1 _i_t_e_m_2 _._._.)) 補完候補となる単語そのものの列挙。例: ::ffoooo::((ffoooo bbaarr bbaazz)) ((((_i_t_e_m_1\\::_d_e_s_c_1 _._._.)))) 上 記と同様だが,補完候補の各単語に対する注釈を付加 する。コロンを必ずバックスラッシュでクォートする こ とに注意。たとえば, ::ffoooo::((((aa\\::bbaarr bb\\::bbaazz)))) と す る と, コ ン テ ク ストで vvaalluuee タグとともに ddeessccrriippttiioonn スタイルがセットされている場合にこれ ら の注釈が表示される。 -->>_s_t_r_i_n_g この形式では,__aarrgguummeennttss は引数とオプションの処理を して呼出し側の関数に return するときに,状態変数 を セッ トするようになる。呼出し側の関数では,変数値を 使って補完生成を調節できる。これはたとえば,ステ ー トマシンを実装する関数などで使うことができる。 zsh 4.3.2 March 2, 2006 68 ZSHCOMPSYS(1) ZSHCOMPSYS(1) `-->>_s_t_r_i_n_g' に 遭遇すると __aarrgguummeennttss 関数は,_s_t_r_i_n_g の先頭末尾の空白をすべて除去し,配列 ssttaattee にすべて の _s_t_r_i_n_g の値を入れてどんなアクションが取られるべ きか分かるようにする。 ちゃんと振る舞う他の補完関数もそうだ が,__aarrgguummeennttss 関 数はデフォルトでは補完候補を追加できればゼロを, そうでなければ非ゼロを返す。しかし,もし --RR オ プ ショ ンを指定した場合 __aarrgguummeennttss 関数は,リターンコ ード300を返し,$$ssttaattee の値を見て処理を切り替える よ う呼び側関数に伝える。 $$ssttaattee だけでなく,__aarrgguummeennttss 関数はグローバル変数 `ccoonntteexxtt', `lliinnee',`oopptt__aarrggss' をセットする(後述)。 また, PPRREEFFIIXX や wwoorrddss のような特殊変数は変更せず, 呼び側の関数にそれらの変数の処 理 を 完 全 に 任 せ る(□)。 それゆえ,少なくとも1つ `-->>_s_t_r_i_n_g' を含んだアクショ ンをつけて __aarrgguummeennttss 関数を呼ぶ関数では,適切な ロ ーカル変数宣言をしておく必要がある。つまり, llooccaall ccoonntteexxtt ssttaattee lliinnee ttyyppeesseett --AA oopptt__aarrggss として,__aarrgguummeennttss 関数がグローバル変数を変えてしま うのを防ぐ(△使い方は???)。 {{_e_v_a_l_-_s_t_r_i_n_g}} 中括弧内に書かれた文字列は候補単語を生成するシェ ル コードとしてevalされる。 _e_v_a_l_-_s_t_r_i_n_g 自身が開括弧で も開中括弧でも始まっていない場合それは,実行前に 別 の単語に分割される。 訳 注: 補完候補を生成する方法載ってないじゃん。ここ では別の補完候補生成関数を使うか,候補を追加する た め の ccoommppaadddd 関数を直接使う。次の例は,--time オプ ション(仮)に与える引数に現在の時刻文字列を補完候 補 にする。 ''----ttiimmee::現現在在時時刻刻::{{ccoommppaadddd ``ddaattee ++""%%HH\\::%%MM\\::%%SS""``}}'' 訳注終わり。 == _a_c_t_i_o_n _a_c_t_i_o_n の前に `== ' (イコール記号と1つのスペース) が あると, __aarrgguummeennttss 関数は現在のコン テ ク ス ト の _a_r_g_u_m_e_n_t フィールドの中味を特殊配列変数 wwoorrddss の先 頭要素の位置に挿入し,特殊変数 CCUURRRREENNTT の値をインク リ メントする。こうすることで補完コマンドラインにダ ミーの単語を挿入しつつも,実際に補完が起きている 場 所は変えないという効果が得られる。 この手法が役立つのは,上記引数指定記述のコロン2つと zsh 4.3.2 March 2, 2006 69 ZSHCOMPSYS(1) ZSHCOMPSYS(1) コロン3つを続けて書いたもの,つまり _a_c_t_i_o_n の操作す るコマンドライン上の単語(wwoorrddss)を制限するものと組み 合わせる場合である。たとえば, _a_c_t_i_o_n 自身が,限 ら れ た範囲の引数に対して __aarrgguummeennttss を呼ぶ場合,この 手法で,二回目に __aarrgguummeennttss が呼ばれるときの範囲 に 適 切なコマンド名をもぐりこませて行解析がうまくいく ようにする。 _w_o_r_d_._._. _w_o_r_d_._._. 上記の _a_c_t_i_o_n 記法に当てはまらないものすべて。 _a_c_t_i_o_n が空白で始まる場合は残りの単語群が修正さ れ ずに実行される。 空 白で始まらない場合は,最初の単語の後ろにいくつか の文字列( のちに ccoommppaadddd のオプションとして渡 さ れ る)を追加して実行される。これらは __aarrgguummeennttss によっ て指定された $state が補完コマンドに正しく伝わる こ とを保証する(△???)。 こ れ らの付加的な引数は配列変数 `eexxppll から取得され る。この変数は _a_c_t_i_o_n を実行する前に設定され,そ の 中で参照されうる。 訳 注: よ ーわからん。飛ばす。でも便利そうだ。あと で。 They ensure that the state specified by __aarrgguummeennttss, 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 `eexxppll'; this will be set up before executing the _a_c_t_i_o_n and hence may be referred to inside it, typically in an expansion of the form `$$eexxppll[[@@]]' which preserves empty elements of the array. _a_c_t_i_o_n 実行時に設定される変数について示す。 配列 `lliinnee' は,コマンドライン中にあるコマンド名とその普通 の引数を集めたもの,つまりすべてのオプションとオプションの 引数を取り除いたものとなる。 連想配列 `oopptt__aarrggss' にはオプションが代入される。このとき, オプション名はキー,その引数は値(バリュー)として入る。引数 を2つ以上取るオプションの引数は1つの文字列にコロン区切りで 格 納 される。引数の値にコロンが含まれていたときはバックス ラッシュでエスケープされる。 変数 `ccoonntteexxtt' は,`-->>_s_t_r_i_n_g' の形式の aaccttiioonn を実行するた め に呼び側の関数に戻るときにセットされる。それには $$ssttaattee に対応した配列がセットされる。各要素はコンテクストの _a_r_g_u_- _m_e_n_t フィールドに適した名前,つまり,`ooppttiioonn_-_o_p_t--_n' という 値であればそれは _-_o_p_t というオプションの _n番 目 の 引 数, zsh 4.3.2 March 2, 2006 70 ZSHCOMPSYS(1) ZSHCOMPSYS(1) `aarrgguummeenntt--_n' という値であればそれは _n番目の引数,という風 になる。「残りの」引数,つまりリストの最後で位置指定なしで 定義されているものに関しては,_n は文字列 `rreesstt' になる。 たとえば,あるコマンドの --oo オプションに対する引数の補完中 なら `ooppttiioonn--oo--11',普通の(オプションでな い)第2引 数 な ら `aarrgguummeenntt--22' という具合にセットされる。 さ らに,_a_c_t_i_o_n の評価中は ccuurrccoonntteexxtt 変数のコンテクスト名 には, ccoonntteexxtt 変数に入れられるのと同じ文字列が足される(△ 未確認)。 (訳 注: さて,コマンドにはつけるオプションによって文法がか なり変わるものがある。そのような場合,オプションと引数の組 み合わせをグループ化して別々に管理することができる。) オプ ションと引数の組み合わせのセットを,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. 例を示す。 __aarrgguummeennttss \\ --aa \\ -- sseett11 \\ --cc \\ -- sseett22 \\ --dd \\ ''::aarrgg::((xx22 yy22))'' は,2つのセットを定義している。コマンドラインが `--cc' を 含 む ときは,`--dd' オプションと `':arg:(x2 y2)'' により期待さ れる引数は補完候補にはならない。逆に,`--dd' オプションや 引 数が入力された場合は `--cc' オプションが候補から外れる。しか し,`--aa' の後ろではいずれの場合も有効なオプションと見な さ れる。 ハイフンで分割したセットは互いに排他的な補完関係となるが, セット間の排他だけでなくセット内の排他も同時に指定できる。 zsh 4.3.2 March 2, 2006 71 ZSHCOMPSYS(1) ZSHCOMPSYS(1) セット名を `((_n_a_m_e))' のように括弧で括って書くと,そのセット の中の補完候補は,そのセット内の他の候補に対しても別のセッ トの候補に対しても排他的となる。つまり,複数のセットの中か ら,選ばれるものはただひとつという関係を書ける。これは,排 他的なオプションにエイリアスがある場合などに有用で, __aarrgguummeennttss \\ --aa --bb \\ -- ''((ccoommpprreessss))'' \\ {{--cc,,----ccoommpprreessss}}''[[ccoommpprreessss]]'' \\ -- ''((uunnccoommpprreessss))'' \\ {{--dd,,----ddeeccoommpprreessss}}''[[ddeeccoommpprreessss]]'' と 書くと,compress セットと uncompress セットは同時には補 完されず,なおかつ compress セットで補完する場合も `--cc' と `----ccoommpprreessss' は同時には補完されなくなる(□この段落原文から 相当変えた)。 もっとも,複数のセットを持たせると補完のためのコードがそれ ぞれ別々に解析しなければならないので遅くなることからどうし ても必要な場合以外は使用を控えるのが望ましい(□)。別解とし ては,排他的な関係を持つオプションの指定を `--ffoooo::**::......' の ように書いて,残りの引数をすべて rest-arguments として読み 切ってもらう方法がある(□)。 __aarrgguummeennttss 関数のオプションについて列挙する(□)。 --SS オプション: `----' をオプションの終わりと自動判定する。た とえば, ffoooobbaarr --aa ---- --bb にある `--bb' は引数と見なされる。`----' 自身は引数と も オ プ ションとも見なされない。 --AAオプション: オプションでない引数の後ろではオプションの補 完をやめる。与えた単語が普通の引数でないと判断するためのパ ターンを --AA オプションの引数として指定する。たとえば,_o_p_t_- _s_p_e_c にオプションとして登録していないものでも「ハイフン で 始 ま る も の は なんでも普通の引数と見なさない」のであれ ば,`--AA ""--**""' と指定する。 --OO オプション: `--OO _n_a_m_e' のように指定し, _a_c_t_i_o_n を実行 す るために呼ばれる関数群に,_n_a_m_eという名の配列変数に含まれる 要素を引数として渡す。これはたとえば,すべての _a_c_t_i_o_n に対 し て共通の「tt(compadd)用オプション」を渡したいときなどに 有用(△??? 例をクレー)。 --MM オプション: '--MM _s_p_e_c' のように指定し,オプション名と 値 の 補完時の「マッチ仕様」を決める。(訳注: 「マッチ仕様」は zshcompwid(1) に) この指定は最初のオプション仕様記述の前に来なければな ら な い。デフォルト値は `rr::||[[__--]]==** rr::||==**' で,これは `__' と `--' zsh 4.3.2 March 2, 2006 72 ZSHCOMPSYS(1) ZSHCOMPSYS(1) の後ろでは「部分マッチ」を許可することを意味する。た と え ば, `-f-b' を補完したときは `-f*-b*' というパターンにマッ チするもので補完するので `--ffoooo--bbaarr' など に 補 完 さ れ う る(□)。 --CC オプション: `-->>_s_t_a_t_e' のアクションを使う場合に ccuurrccoonn-- tteexxtt 変数の値をその場に応じた値に変えるよう __aarrgguummeennttss に 指示する。この変数は現在のコンテクストに追随するための変数 で,これを使用する関数では修正した値を返してしまったりする ことのないようローカル変数化し,以下のようにして正しく初期 値設定する必要がある。 llooccaall ccuurrccoonntteexxtt==""$$ccuurrccoonntteexxtt"" 複数の state を同時に当てはめることができないときなどに 有 用(△???実 例 を ク レー)。 This is useful where it is not possible for multiple states to be valid together. 訳注: 例えば ccmmdd というコマンド引数での補完 で __aarrgguummeennttss を 使い,その中に ''--ffoooo::ffoooo ooppttiioonn::-->>ffoooo'' があったとする。 --ffoooo オプションを入力し終えその引数位置で呼ばれた と き の $$ccuurrccoonntteexxtt が ::ccoommpplleettee::ccmmdd::ooppttiioonn--ffoooo--11 となる。 --CC なし だと ::ccoommpplleettee::ccmmdd:: のまま変わらない。訳注終わり。 `----' オプション: (□)GNUのコマンドのオプション流儀のおまか せオプション。 `----hheellpp' というオプションでヘルプ出力が出て くるようなものに対しその出力を取り込んでオプション解析を自 動で行なう。もちろん,ヘルプ出力にちゃんと対応していないコ マンドにこれを使うと危険。 対象コマンドのオプションそのものだけでな く, `----_o_p_t=_v_a_l' という書き方が正当と見なされるオプションならそのオプション の引数の種別の推測も試みる。完全自動での推測がうまくいかな い場合はヒントを与えて,ヘルプ出力から,あるオプションの引 数の種別を推測しやすくすることもできる。ヒ ン ト は `_p_a_t_- _t_e_r_n::_m_e_s_s_a_g_e::_a_c_t_i_o_n' という形式で与える(通常の引数使用指定 は使われない点に注意)。 _p_a_t_t_e_r_n のマッチングはヘルプ出力中の,あるオプションに対す る説明文に対して適用され,マッチした場合はそのオプションの 引数補完時には,指定した _m_e_s_s_a_g_e と _a_c_t_i_o_n が利用される。 たとえば, __aarrgguummeennttss ---- ''**\\**::ttooggggllee::((yyeess nnoo))'' \\ ''**==FFIILLEE**::ffiillee::__ffiilleess'' \\ ''**==DDIIRR**::ddiirreeccttoorryy::__ffiilleess --//'' \\ ''**==PPAATTHH**::ddiirreeccttoorryy::__ffiilleess --//'' とすると,ヘルプ行の説明文がアスタリスクで終わってるものの 引数は `yyeess' と `nnoo' で, `==FFIILLEE' という文字列が含まれてい るものの引数はファイルで, `==DDIIRR' や `==PPAATTHH' が含まれて い る も の の引数はディレクトリで補完する。実は最後の3つはデ フォルトで組み込まれているので明示的に与える必要はない。よ zsh 4.3.2 March 2, 2006 73 ZSHCOMPSYS(1) ZSHCOMPSYS(1) くあるヘルプ行の例として --CC,, ----ddiirreeccttoorryy==DDIIRR cchhaannggee ttoo ddiirreeccttoorryy DDIIRR の ようなものがあるが,これだと `----ddiirreeccttoorryy' の引数はディ レクトリを補完するが `--CC' の後ろではうまくいかない。 また,__aarrgguummeennttss はオプションの引数が任意かどうかも推測 す る が明示的に指定したい場合はヒントのところで _m_e_s_s_a_g_e の前 のコロンを 2個にすればよい。 _p_a_t_t_e_r_n が `((--))' で終わっている場合は………パス, If the _p_a_t_t_e_r_n ends in `((--))', this will removed from the pattern and the _a_c_t_i_o_n will be used only directly after the `==', not in the next word. This is the behaviour of a normal specification defined with the form `==--'. `__aarrgguummeennttss ----' には,それ専用の追加オプションがある(こ こ から□)。 ---- --ii オプション: 解析に使うヘルプ出力中で無視すべきパター ンを指定する。たとえば,configure オプションなどで一般的な 記法の説明として ----eennaabbllee--FFEEAATTUURREE nnoott iinncclluuddee FFEEAATTUURREE...... の よ うな行があったりする。これは抽象例であって実際のオプ ションではないので無視したい。このようなときは,無視したい パターンを与える。たとえば, __aarrgguummeennttss ---- --ii \\ ""((----((eenn||ddiiss))aabbllee--FFEEAATTUURREE**))"" とすると,`----eennaabbllee--FFEEAATTUURREE' と `----ddiissaabbllee--FFEEAATTUURREE' という オプションは無視する。 ---- --ss オプション: `--ss _p_a_i_r' の形で指定して,オプションエイ リアスを定義する。 _p_a_i_r の部分にはパターンとその置き換え語 を指定する。たと え ば,ccoonnffiigguurree の ヘ ル プ 出 力 に は `----eennaabbllee--ffoooo' の 説 明 し か な いにもかかわらず実際には `----ddiissaabbllee--ffoooo' も容認される。このような場合は, __aarrgguummeennttss ---- --ss ""((##----eennaabbllee-- ----ddiissaabbllee--))"" とするることで,`----ddiissaabbllee--**' のほうも補完されるよう に な る。 (ここまで□) ここで __aarrgguummeennttss 関数の一般的な使用例を示す。 __aarrgguummeennttss ''--ll++::lleefftt bboorrddeerr::'' \\ ''--ffoorrmmaatt::ppaappeerr ssiizzee::((lleetttteerr AA44))'' \\ ''**--ccooppyy::oouuttppuutt ffiillee::__ffiilleess::::rreessoolluuttiioonn::((330000 660000))'' \\ ''::ppoossttssccrriipptt ffiillee::__ffiilleess --gg \\**..\\((ppss\\||eeppss\\))'' \\ ''**::ppaaggee nnuummbbeerr::'' zsh 4.3.2 March 2, 2006 74 ZSHCOMPSYS(1) ZSHCOMPSYS(1) こ の 例は,ここで定義している関数が補完するコマンドのオプ ションにある, `--ll',`--ffoorrmmaatt',`--ccooppyy' の3つのオプショ ン について記述している。最初のものは引数をひとつ取り,引数補 完時に使う説明として `_l_e_f_t _b_o_r_d_e_r' を使い,補完候補は何 も 提 示 し な い よ う 指定している。また `++' の指定があるの で,`--ll' オプションの引数は `--ll' にくっつけて書いても, 次 の引数に書いてもよいことを意味している。 次 の `--ffoorrmmaatt' は,説明文字列を `_p_a_p_e_r _s_i_z_e' にし,補完候 補を `lleetttteerr' と `AA44' にしている。 `--ccooppyy' オプションは `**' によって,そのオプションがコマ ン ド ラ インに何回現れても補完することを意味し,また `output file' と `ressolution' に相当する2つの引数を取ることを意味 し て い る。 た だし, 2つ目の引数は省略可能である(コロン が2つ)。 最後の2つは,そのコマンドの普通の(オプションでない)引数 と し て補完されることを意味している。第1引数では説明文字列を `postscript files' として,ファイル名が `ppss か `eeppss' で 終 わるものを補完する。最後の記述は,残りすべての引数で,説明 文字列を `page numbers' として補完せずに入力させることを意 味している。 __ccaacchhee__iinnvvaalliidd _c_a_c_h_e___i_d_e_n_t_i_f_i_e_r 補 完キャッシュの再構築が必要なときにゼロを返す。現 在のコンテクストの ccaacchhee--ppoolliiccyy スタイルを参照し て 判定を下す。 This should provide a function name which is run with the full path to the relevant cache file as the only argument. Example: __eexxaammppllee__ccaacchhiinngg__ppoolliiccyy (()) {{ ## rreebbuuiilldd iiff ccaacchhee iiss mmoorree tthhaann aa wweeeekk oolldd oollddpp==(( ""$$11""((NNmmww++11)) )) (((( $$##oollddpp )))) }} __ccaallll__ffuunnccttiioonn _r_e_t_u_r_n _n_a_m_e [ _a_r_g_s ... ] 関 数 _n_a_m_e が定義されていれば,引数 _a_r_g_s を付けて呼 び,終了コードを変数 _r_e_t_u_r_n に格納する。 _r_e_t_u_r_n を 空にするかハイフンにすると無視される。 __ccaallll__ffuunnccttiioonn 関数自身の終了コードは,関数 _n_a_m_e が 存在して呼べたらゼロ,そうでなければ非ゼロとなる。 __ccaallll__pprrooggrraamm _t_a_g _s_t_r_i_n_g ... 訳注: ★これ結構重要なのになー★。 外部コマンドを呼ぶ。ただ呼ぶだけでなく,ユーザが 呼 び 出すべき外部コマンドをオーバーライドしやすいよう zsh 4.3.2 March 2, 2006 75 ZSHCOMPSYS(1) ZSHCOMPSYS(1) な機構を備えている。とくに指定がなければ _s_t_r_i_n_g を 外 部コマンドとして呼び出し,その終了コードを返す。 ただし,_t_a_g に対する ccoommmmaanndd スタイルが定義されてい る 場 合 はその値(文字列)を外部コマンドとして呼び出 す。呼び出したコマンドからの出力は,スペース区切 り で連結される。 訳 注: 例: cvs の サ ブ コ マ ン ド名一覧は `ccvvss ----hheellpp--ccoommmmaannddss' として得ている。でも「commit じゃ なくて ci がいい!」と思っているなら外部コマンド呼び 出しを変えてしまえばよい。 __ccvvss 関数定義には, $$((__ccaallll__pprrooggrraamm ccoommmmaannddss ccvvss ----hheellpp--ccoommmmaannddss 22>>&&11)) と い う 部 分 が あ る が, こ れ は,''::ccoommppllee-- ttiioonn::**::ccvvss::**::ccoommmmaannddss'' コンテクストの ccoommmmaanndd タグ で上書きできるので, cvs 本来のヘルプ画面 の `com- mit' を `ci' に置換したヘルプ画面を出すような偽コマ ンド(仮に cvshelpfake とする)を作っておいて, zzssttyyllee ''::ccoommpplleettiioonn::**::ccvvss::**::ccoommmmaannddss'' \\ ccoommmmaanndd ccvvsshheellppffaakkee などとしておく。 __ccvvss の場合,cvs のサブコマンド を 初 めて補完するときにこのコマンドを呼ぶのでコンテク ストのコマンド名のところがちゃんと `ccvvss' になってい る が,補完定義によっては空だったり,別のコマンド名 だったりする場合があるので注意が必要。訳注終わり。 __ccoommbbiinnaattiioonn [ --ss _p_a_t_t_e_r_n ] _t_a_g _s_t_y_l_e _s_p_e_c ... _f_i_e_l_d _o_p_t_s ... 「ホ スト名とユーザ名」などのように,複数の値の組み 合わせの補完を行なうときに使う。 _s_t_y_l_e の部分には構 成 す べ きペアのスタイルを指定する。このスタイルは _t_a_g が指定されたコンテクストで照合される。 スタイル名はたとえば, `uusseerrss--hhoossttss--ppoorrttss' の よ う に, フィールド名をハイフンで区切ったもので構成され る。 値が既に確定しているものに対するフィ ー ル ド に は `_f_i_e_l_d==_p_a_t_t_e_r_n' という書式の _s_p_e_c が与えられる。た とえば,もしそれまで入力したコマンドラインでユー ザ `ppwwss' を指定したならば,`uusseerrss==ppwwss' という引数が現 れるべきである。 訳注: ようするに _s_p_e_c 引数は(普通は)補完時に動的 に 生 成されるもので, __ccoommbbiinnaattiioonn を呼び出すときには コマンドライン上に入力したユーザ名やホスト名を自 動 的 に 取 得 して,それを使って `uusseerrss==ppwwss' のような _s_p_e_c をそこに生成すると,ユーザが `ppwwss' に合致す る よ うなホスト(とそのポート)だけを補完候補に選んでく れる。 zsh 4.3.2 March 2, 2006 76 ZSHCOMPSYS(1) ZSHCOMPSYS(1) この関数の使い方については __ccoommbbiinnaattiioonn 関数を定 義 し ているファイルの使用例を見るのがいちばん速い。こ こは読んでも分からん。てことで,飛ばす。訳 注 終 わ り。 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 --ss to __ccoommbbiinnaattiioonn which specifies a pattern. Typically this is a character class, as for example `--ss ""[[::@@]]""' in the case of the uusseerrss--hhoossttss style. Each `_f_i_e_l_d==_p_a_t_t_e_r_n' 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 `uusseerrss--hhoossttss--ppoorrttss' or no matching hostname when a host is required, the function `__hhoossttss' will automatically be called. If the same name is used for more than one field, in both the `_f_i_e_l_d==_p_a_t_t_e_r_n' 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 ccoommppaadddd when generating matches from the style value, or to the functions for the fields if they are called. __ddeessccrriibbee [ --ooOO | --tt _t_a_g ] _d_e_s_c_r _n_a_m_e_1 [ _n_a_m_e_2 ] _o_p_t_s ... ---- ... この関数は補完候補と説明文字列を関連付ける。 This function associates completions with descrip- tions. Multiple groups separated by ---- can be sup- plied, potentially with different completion options _o_p_t_s. _d_e_s_c_r は 候 補 一 覧の上に出る説明文字列で,これは ddeessccrriippttiioonnss タグに対する ffoorrmmaatt スタイルが定義され ているときに表示される。 _d_e_s_c_r の後ろには,1個か2個 の配列変数の名前が続き,さらに後ろに ccoommppaadddd に渡す オ プションが続く。 1個目の配列は,補完候補の単語と zsh 4.3.2 March 2, 2006 77 ZSHCOMPSYS(1) ZSHCOMPSYS(1) それに対する説明文字列 を `_c_o_m_p_l_e_t_i_o_n::_d_e_s_c_r_i_p_t_i_o_n' の 書 式 で書いた要素を含むものである。 2個目の配列 は,1個目の配列と要素数が同じもので, 1個目配列に対 応 する補完候補単語として _c_o_m_p_l_e_t_i_o_n の代わりに 2個 目配列の対応する要素を追加する(△どういうときに役立 つの???)。説明文字列は1個目の配列にあったものがその まま残る。 配列の後ろにはいくつかのオプション を 指 定 す る。 Finally, a set of completion options can appear. 最 初の引数の前に `--oo' オプションを指定すると,追加 する候補をそのコマンドのオプションとして扱うよう に す る。 典型的にはコマンドライン上で `--',`----',`++' に続けて書くものとして,それらの文字が入力されな い 限 り 一 覧 や説明文字列が出ない(□)。厳密には pprree-- ffiixx--hhiiddddeenn, pprreeffiixx--nneeeeddeedd, vveerrbboossee スタイルすべてを 参 照して,その補完候補を一覧に含めるか決める(□)。 `--oo' の代わりに(□訳注: 原文にtypo) `--OO' オプション にすると,pprreeffiixx--nneeeeddeedd スタイルは無視する。 `--tt' オプションは _t_a_g を指定する。指定しないときの デフォルトのタグは,--oo オプションを指定したときには `ooppttiioonnss' で,そうでないときは `vvaalluueess' である。 If selected by the lliisstt--ggrroouuppeedd style, strings with the same description will appear together in the list. __ddeessccrriibbee uses the __aallll__llaabbeellss function to generate the matches, so it does not need to appear inside a loop over tag labels. __ddeessccrriippttiioonn [ --xx ] [ --1122VVJJ ] _t_a_g _n_a_m_e _d_e_s_c_r [ _s_p_e_c ... ] kokomade This function is not to be confused with the previous one; it is used as a helper function for creating options to ccoommppaadddd. 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 _t_a_g. The resulting options for ccoommppaadddd are put into the array named _n_a_m_e (this is traditionally `eexxppll', but this convention is not enforced). The description for the corresponding set of matches is passed to the function in _d_e_s_c_r. The styles tested are: ffoorrmmaatt, hhiiddddeenn, mmaattcchheerr, iiggnnoorreedd--ppaatttteerrnnss and ggrroouupp--nnaammee. The ffoorrmmaatt style is first tested for the given _t_a_g and then for the ddeessccrriippttiioonnss 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 __sseettuupp which tests some more styles. The string returned by the ffoorrmmaatt style (if any) will be modified so that the sequence `%%dd' is replaced by the _d_e_s_c_r given as the third argument without any leading or trailing white space. If, after removing the white space, the _d_e_s_c_r is the empty string, the format style will not be used and the options put into the _n_a_m_e array will not con- tain an explanation string to be displayed above the matches. If __ddeessccrriippttiioonn is called with more than three arguments, the additional _s_p_e_cs should be of the form `_c_h_a_r::_s_t_r'. These supply escape sequence replacements for the ffoorrmmaatt style: every appearance of `%%_c_h_a_r' will be replaced by _s_t_r_i_n_g. If the --xx option is given, the description will be passed to ccoommppaadddd using the --xx option instead of the default --XX. This means that the description will be displayed even if there are no correspond- ing matches. The options placed in the array _n_a_m_e take account of the ggrroouupp--nnaammee style, so matches are placed in a separate group where necessary. The group normally has its elements sorted (by passing the option --JJ to ccoommppaadddd), but if an option starting with `--VV', `--JJ', `--11', or `--22' is passed to __ddeessccrriippttiioonn, that option will be included in the array. Hence it is possible for the completion group to be unsorted by giving the option `--VV', `--11VV', or `--22VV'. In most cases, the function will be used like this: llooccaall eexxppll __ddeessccrriippttiioonn ffiilleess eexxppll ffiillee ccoommppaadddd ""$$eexxppll[[@@]]"" -- ""$$ffiilleess[[@@]]"" Note the use of the parameter eexxppll, the hyphen, and the list of matches. Almost all calls to ccoommppaadddd 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. __ddiissppaattcchh _c_o_n_t_e_x_t _s_t_r_i_n_g _._._. This sets the current context to _c_o_n_t_e_x_t 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 ccoommppddeeff) given as _s_t_r_i_n_g _._._.. 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 _s_t_r_i_n_g is --ddeeffaauulltt-- to cause the function for default completion to be used as a fallback. The function sets the parameter $$sseerrvviiccee to the _s_t_r_i_n_g being tried, and sets the _c_o_n_t_e_x_t_/_c_o_m_m_a_n_d field (the fourth) of the $$ccuurrccoonntteexxtt parameter to the _c_o_n_t_e_x_t given as the first argument. __ffiilleess The function __ffiilleess calls __ppaatthh__ffiilleess with all the arguments it was passed except for --gg and --//. The use of these two options depends on the setting of the ffiillee--ppaatttteerrnnss style. This function accepts the full set of options allowed by __ppaatthh__ffiilleess, described below. __ggnnuu__ggeenneerriicc This function is a simple wrapper around the __aarrgguu-- mmeennttss function described above. It can be used to determine automatically the long options understood by commands that produce a list when passed the option `----hheellpp'. 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 ffoooo and bbaarr, use ccoommppddeeff __ggnnuu__ggeenneerriicc ffoooo bbaarr after the call to ccoommppiinniitt. 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 `----hheellpp'. __gguuaarrdd [ _o_p_t_i_o_n_s ] _p_a_t_t_e_r_n _d_e_s_c_r This function is intended to be used in the _a_c_t_i_o_n for the specifications passed to __aarrgguummeennttss and similar functions. It returns immediately with a non-zero return status if the string to be com- pleted does not match the _p_a_t_t_e_r_n. If the pattern matches, the _d_e_s_c_r is displayed; the function then returns status zero if the word to complete is not empty, non-zero otherwise. The _p_a_t_t_e_r_n may be preceded by any of the options understood by ccoommppaadddd that are passed down from __ddeessccrriippttiioonn, namely --MM, --JJ, --VV, --11, --22, --nn, --FF and --XX. All of these options will be ignored. This fits in conveniently with the argument-passing con- ventions of actions for __aarrgguummeennttss. zsh 4.3.2 March 2, 2006 80 ZSHCOMPSYS(1) ZSHCOMPSYS(1) As an example, consider a command taking the options --nn and --nnoonnee, where --nn must be followed by a numeric value in the same word. By using: __aarrgguummeennttss ''--nn--:: ::__gguuaarrdd ""[[00--99]]##"" ""nnuummeerriicc vvaalluuee""'' ''--nnoonnee'' __aarrgguummeennttss can be made to both display the message `nnuummeerriicc vvaalluuee' and complete options after `--nn<>'. If the `--nn' is already followed by one or more digits (the pattern passed to __gguuaarrdd) only the message will be displayed; if the `--nn' is fol- lowed by another character, only options are com- pleted. __mmeessssaaggee [ --rr1122 ] [ --VVJJ _g_r_o_u_p ] _d_e_s_c_r __mmeessssaaggee --ee [ _t_a_g ] _d_e_s_c_r __ddeessccrriippttiioonn 関数の第3引数と同様に _d_e_s_c_r を説明文字 列として使用する。ただしこちらは,マッチするもの が あっ てもなくても表示される。補完すべきものがないと きのヘルプメッセージを出すときに有用。 The ffoorrmmaatt style is examined with the mmeessssaaggeess tag to find a message; the usual tag, ddeessccrriippttiioonnss, is used only if the style is not set with the former. If the --rr option is given, no style is used; the _d_e_s_c_r is taken literally as the string to display. This is most useful when the _d_e_s_c_r comes from a pre-processed argument list which already contains an expanded description. The --1122VVJJ options and the _g_r_o_u_p are passed to ccoomm-- ppaadddd and hence determine the group the message string is added to. The second form gives a description for completions with the tag _t_a_g 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 $$ccuurrttaagg; this is maintained by the completion system and so is usually correct. __mmuullttii__ppaarrttss _s_e_p _a_r_r_a_y The argument _s_e_p is a separator character. The _a_r_r_a_y may be either the name of an array parameter or a literal array in the form `((ffoooo bbaarr))', a parenthesised list of words separated by whites- pace. The possible completions are the strings from the array. However, each chunk delimited by _s_e_p will be completed separately. For example, the __ttaarr function uses `__mmuullttii__ppaarrttss // _p_a_t_h_a_r_r_a_y' 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 --ii option causes __mmuullttii__ppaarrttss 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 `--VV', `--JJ', `--11', `--22', `--nn', `--ff', `--XX', `--MM', `--PP', `--SS', `--rr', `--RR', and `--qq' options and passes them to the ccoommppaadddd builtin. __nneexxtt__llaabbeell [ --xx ] [ --1122VVJJ ] _t_a_g _n_a_m_e _d_e_s_c_r [ _o_p_t_i_o_n_s ... ] This function is used to implement the loop over different tag labels for a particular tag as described above for the ttaagg--oorrddeerr 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 __ttaaggss or __rreeqquueesstteedd. The --xx1122VVJJ options and the first three arguments are passed to the __ddeessccrriippttiioonn function. Where appropriate the _t_a_g will be replaced by a tag label in this call. Any description given in the ttaagg--oorrddeerr style is preferred to the _d_e_s_c_r passed to __nneexxtt__llaabbeell. The _o_p_t_i_o_n_s given after the _d_e_s_c_r are set in the parameter given by _n_a_m_e, and hence are to be passed to ccoommppaadddd or whatever function is called to add the matches. Here is a typical use of this function for the tag ffoooo. The call to __rreeqquueesstteedd determines if tag ffoooo is required at all; the loop over __nneexxtt__llaabbeell han- dles any labels defined for the tag in the ttaagg--oorrddeerr style. llooccaall eexxppll rreett==11 ...... iiff __rreeqquueesstteedd ffoooo;; tthheenn ...... wwhhiillee __nneexxtt__llaabbeell ffoooo eexxppll ''......'';; ddoo ccoommppaadddd ""$$eexxppll[[@@]]"" ...... &&&& rreett==00 ddoonnee ...... ffii rreettuurrnn rreett zsh 4.3.2 March 2, 2006 82 ZSHCOMPSYS(1) ZSHCOMPSYS(1) __nnoorrmmaall This is the standard function called to handle com- pletion outside any special _-_c_o_n_t_e_x_t_-. It is called both to complete the command word and also the arguments for a command. In the second case, __nnoorrmmaall looks for a special completion for that command, and if there is none it uses the comple- tion for the --ddeeffaauulltt-- context. A second use is to reexamine the command line spec- ified by the $$wwoorrddss array and the $$CCUURRRREENNTT parame- ter after those have been modified. For example, the function __pprreeccoommmmaanndd, which completes after pre-command specifiers such as nnoohhuupp, removes the first word from the wwoorrddss array, decrements the CCUURRRREENNTT parameter, then calls __nnoorrmmaall again. The effect is that `nnoohhuupp _c_m_d _._._.' is treated in the same way as `_c_m_d _._._.'. If the command name matches one of the patterns given by one of the options --pp or --PP to ccoommppddeeff, the corresponding completion function is called and then the parameter __ccoommppsskkiipp 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 --ffiirrsstt-- context. __ooppttiioonnss This can be used to complete the names of shell options. It provides a matcher specification that ignores a leading `nnoo', ignores underscores and allows upper-case letters to match their lower-case counterparts (for example, `gglloobb', `nnoogglloobb', `NNOO__GGLLOOBB' are all completed). Any arguments are propagated to the ccoommppaadddd builtin. __ooppttiioonnss__sseett and __ooppttiioonnss__uunnsseett These functions complete only set or unset options, with the same matching specification used in the __ooppttiioonnss function. Note that you need to uncomment a few lines in the __mmaaiinn__ccoommpplleettee 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. __ppaarraammeetteerrss This is used to complete the names of shell parame- ters. The option `--gg _p_a_t_t_e_r_n_' _l_i_m_i_t_s _t_h_e _c_o_m_p_l_e_t_i_o_n _t_o zsh 4.3.2 March 2, 2006 83 ZSHCOMPSYS(1) ZSHCOMPSYS(1) _p_a_r_a_m_e_t_e_r_s _w_h_o_s_e _t_y_p_e _m_a_t_c_h_e_s _t_h_e _p_a_t_t_e_r_n_. _T_h_e _t_y_p_e _o_f _a _p_a_r_a_m_e_t_e_r _i_s _t_h_a_t _s_h_o_w_n _b_y _`pprriinntt $${{((tt))_p_a_r_a_m}}_'_, _h_e_n_c_e _j_u_d_i_c_i_o_u_s _u_s_e _o_f _`**_' _i_n _p_a_t_t_e_r_n _i_s _p_r_o_b_a_b_l_y _n_e_c_e_s_s_a_r_y_. All other arguments are passed to the ccoommppaadddd builtin. __ppaatthh__ffiilleess This function is used throughout the completion system to complete filenames. It allows completion of partial paths. For example, the string `//uu//ii//ss//ssiigg' may be completed to `//uussrr//iinncclluuddee//ssyyss//ssiiggnnaall..hh'. The options accepted by both __ppaatthh__ffiilleess and __ffiilleess are: --ff Complete all filenames. This is the default. --// Specifies that only directories should be completed. --gg _p_a_t_t_e_r_n Specifies that only files matching the _p_a_t_- _t_e_r_n should be completed. --WW _p_a_t_h_s 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, _p_a_t_h_s may be the name of an array parameter, a literal list of paths enclosed in parenthe- ses or an absolute pathname. --FF _i_g_n_o_r_e_d_-_f_i_l_e_s This behaves as for the corresponding option to the ccoommppaadddd builtin. It gives direct control over which filenames should be ignored. If the option is not present, the iiggnnoorreedd--ppaatttteerrnnss style is used. Both __ppaatthh__ffiilleess and __ffiilleess also accept the follow- ing options which are passed to ccoommppaadddd: `--JJ', `--VV', `--11', `--22', `--nn', `--XX', `--MM', `--PP', `--SS', `--qq', `--rr', and `--RR'. Finally, the __ppaatthh__ffiilleess function uses the styles eexxppaanndd, aammbbiigguuoouuss, ssppeecciiaall--ddiirrss, lliisstt--ssuuffffiixxeess and ffiillee--ssoorrtt described above. zsh 4.3.2 March 2, 2006 84 ZSHCOMPSYS(1) ZSHCOMPSYS(1) __ppiicckk__vvaarriiaanntt [[ --cc _c_o_m_m_a_n_d ]] [[ --rr _n_a_m_e ]] _l_a_b_e_l==_p_a_t_t_e_r_n ...... _l_a_b_e_l [[ _a_r_g_s ...... ]] ccoommppddeeff 関数中で 1つのコマンド名で複数の補完バリ エ ー ションを持たせるときに使う。現在補完中のコマンド 名に,引数の最後に指定した _a_r_g_s を与えて起動し て, その出力に _p_a_t_t_e_r_n にマッチするものがあればそれに対 応する _l_a_b_e_l を選ぶ。 --rr で変数を指定した場合には, そ れに選ばれたラベルが代入される。起動コマンド名を 変える場合は --cc オプションを使う。指定したパター ン に マッチしなければ,最後に指定したデフォルトのラベ ル _l_a_b_e_l が選ばれて,終了コードが1となる。 この結果は ___c_m_d___v_a_r_i_a_n_t 連想配列変数にキャッシュ さ れる。訳注: 原文面影なし。 __rreeggeexx__aarrgguummeennttss _n_a_m_e _s_p_e_c ... This function generates a completion function _n_a_m_e which matches the specifications _s_p_e_c ......, a set of regular expressions as described below. After run- ning __rreeggeexx__aarrgguummeennttss, the function _n_a_m_e should be called as a normal completion function. The pat- tern to be matched is given by the contents of the wwoorrddss 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 _a_c_t_i_o_ns for the corresponding pat- terns are executed. In this case, nothing is stripped from the command line string. The order of evaluation of the _a_c_t_i_o_ns can be determined by the ttaagg--oorrddeerr style; the various formats supported by __aalltteerrnnaattiivvee can be used in _a_c_t_i_o_n. The _d_e_s_c_r is used for setting up the array parameter eexxppll. 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) //_p_a_t_t_e_r_n// [%%_l_o_o_k_a_h_e_a_d%%] [--_g_u_a_r_d] [::_t_a_g::_d_e_s_c_r::_a_c_t_i_o_n] This is a single primitive component. The function tests whether the combined pattern `((##bb))((((##BB))_p_a_t_t_e_r_n))_l_o_o_k_a_h_e_a_d**' matches the command line string. If so, `_g_u_a_r_d' is evaluated and its return status is examined to determine if the test has succeeded. The _p_a_t_t_e_r_n string `[[]]' is guaranteed never to match. The _l_o_o_k_a_h_e_a_d 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 __aalltteerrnnaattiivvee. A component is used as follows: _p_a_t_t_e_r_n 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 _a_c_t_i_o_n is used to generate matches to insert at that point. //_p_a_t_t_e_r_n//++ [%%_l_o_o_k_a_h_e_a_d%%] [--_g_u_a_r_d] [::_t_a_g::_d_e_s_c_r::_a_c_t_i_o_n] This is similar to `//_p_a_t_t_e_r_n// ...' 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. //_p_a_t_t_e_r_n//-- [%%_l_o_o_k_a_h_e_a_d%%] [--_g_u_a_r_d] [::_t_a_g::_d_e_s_c_r::_a_c_t_i_o_n] This is similar to `//_p_a_t_t_e_r_n// ...' but the _a_c_t_i_o_ns of the current and previously matched patterns are ignored even if the following `_p_a_t_t_e_r_n' matches the empty string. (( _s_p_e_c )) Parentheses may be used to groups _s_p_e_cs; note each parenthesis is a single argument to __rreeggeexx__aarrgguummeennttss. _s_p_e_c ## This allows any number of repetitions of _s_p_e_c. _s_p_e_c _s_p_e_c The two _s_p_e_cs are to be matched one after the other as described above. zsh 4.3.2 March 2, 2006 86 ZSHCOMPSYS(1) ZSHCOMPSYS(1) _s_p_e_c || _s_p_e_c Either of the two _s_p_e_cs can be matched. The function __rreeggeexx__wwoorrddss 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: __rreeggeexx__aarrgguummeennttss __ttsstt //$$''[[^^\\00]]##\\00''// \\ //$$''[[^^\\00]]##\\00''// ::''ccoommppaadddd aaaaaa'' This generates a function __ttsstt that completes aaaaaa as its only argument. The _t_a_g and _d_e_s_c_r_i_p_t_i_o_n 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 aaaaaa being present. __rreeggeexx__aarrgguummeennttss __ttsstt //$$''[[^^\\00]]##\\00''// \\ //$$''aaaaaa\\00''// ::''ccoommppaadddd aaaaaa'' This is a more typical use; it is similar, but any following patterns would only match if aaaaaa was pre- sent as the first argument. __rreeggeexx__aarrgguummeennttss __ttsstt //$$''[[^^\\00]]##\\00''// \\(( \\ //$$''aaaaaa\\00''// ::''ccoommppaadddd aaaaaa'' \\ //$$''bbbbbb\\00''// ::''ccoommppaadddd bbbbbb'' \\)) \\## In this example, an indefinite number of command arguments may be completed. Odd arguments are com- pleted as aaaaaa and even arguments as bbbbbb. Comple- tion fails unless the set of aaaaaa and bbbbbb arguments before the current one is matched correctly. __rreeggeexx__aarrgguummeennttss __ttsstt //$$''[[^^\\00]]##\\00''// \\ \\(( //$$''aaaaaa\\00''// ::''ccoommppaadddd aaaaaa'' \\|| \\ //$$''bbbbbb\\00''// ::''ccoommppaadddd bbbbbb'' \\)) \\## This is similar, but either aaaaaa or bbbbbb may be com- pleted for any argument. In this case __rreeggeexx__wwoorrddss could be used to generate a suitable expression for the arguments. __rreeggeexx__wwoorrddss _t_a_g _d_e_s_c_r_i_p_t_i_o_n _s_p_e_c ... This function can be used to generate arguments for the __rreeggeexx__aarrgguummeennttss command which may be inserted at any point where a set of rules is expected. The _t_a_g and _d_e_s_c_r_i_p_t_i_o_n give a standard tag and zsh 4.3.2 March 2, 2006 87 ZSHCOMPSYS(1) ZSHCOMPSYS(1) description pertaining to the current context. Each _s_p_e_c contains two or three arguments separated by a colon: note that there is no leading colon in this case. Each _s_p_e_c gives one of a set of words that may be completed at this point, together with arguments. It is thus roughly equivalent to the __aarrgguummeennttss function when used in normal (non-regex) comple- tion. The part of the _s_p_e_c 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 _s_p_e_c is a description for the word being completed. The optional third part of the _s_p_e_c 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 --tt _t_e_r_m 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 --ss _s_e_p to __vvaalluueess. The result of the processing by __rreeggeexx__wwoorrddss is placed in the array rreeppllyy, 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: llooccaall --aa rreeppllyy __rreeggeexx__wwoorrddss mmyyddbb--ccoommmmaannddss ''mmyyddbb ccoommmmaannddss'' \\ ''aadddd::aadddd aann eennttrryy ttoo mmyyddbb::$$mmyyddbb__aadddd__ccmmddss'' \\ ''sshhooww::sshhooww eennttrriieess iinn mmyyddbb'' __rreeggeexx__aarrgguummeennttss __mmyyddbb ""$$rreeppllyy[[@@]]"" __mmyyddbb ""$$@@"" This shows a completion function for a command mmyyddbb which takes two command arguments, aadddd and sshhooww. sshhooww takes no arguments, while the arguments for aadddd have already been prepared in an array mmyyddbb__aadddd__ccmmddss, quite possibly by a previous call to __rreeggeexx__wwoorrddss. zsh 4.3.2 March 2, 2006 88 ZSHCOMPSYS(1) ZSHCOMPSYS(1) __rreeqquueesstteedd [ --xx ] [ --1122VVJJ ] _t_a_g [ _n_a_m_e _d_e_s_c_r [ _c_o_m_m_a_n_d _a_r_g_s ... ] ] This function is called to decide whether a tag already registered by a call to __ttaaggss (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: __ttaaggss ffoooo bbaarr bbaazz wwhhiillee __ttaaggss;; ddoo iiff __rreeqquueesstteedd ffoooo;; tthheenn ...... ## ppeerrffoorrmm ccoommpplleettiioonn ffoorr ffoooo ffii ...... ## tteesstt tthhee ttaaggss bbaarr aanndd bbaazz iinn tthhee ssaammee wwaayy ...... ## eexxiitt lloooopp iiff mmaattcchheess wweerree ggeenneerraatteedd ddoonnee Note that the test for whether matches were gener- ated is not performed until the end of the __ttaaggss loop. This is so that the user can set the ttaagg--oorrddeerr style to specify a set of tags to be com- pleted at the same time. If _n_a_m_e and _d_e_s_c_r are given, __rreeqquueesstteedd calls the __ddeessccrriippttiioonn function with these arguments together with the options passed to __rreeqquueesstteedd. If _c_o_m_m_a_n_d is given, the __aallll__llaabbeellss 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: llooccaall eexxppll rreett==11 __ttaaggss ffoooo bbaarr bbaazz wwhhiillee __ttaaggss;; ddoo __rreeqquueesstteedd ffoooo eexxppll ''ddeessccrriippttiioonn'' \\ ccoommppaadddd ffoooobbaarr ffoooobbaazz &&&& rreett==00 ...... (((( rreett )))) |||| bbrreeaakk ddoonnee If the _c_o_m_m_a_n_d is not ccoommppaadddd, it must nevertheless be prepared to handle the same options. __rreettrriieevvee__ccaacchhee _c_a_c_h_e___i_d_e_n_t_i_f_i_e_r This function retrieves completion information from the file given by _c_a_c_h_e___i_d_e_n_t_i_f_i_e_r, stored in a directory specified by the ccaacchhee--ppaatthh style which defaults to ~~//..zzccoommppccaacchhee. The return status is zero if retrieval was successful. It will only attempt retrieval if the uussee--ccaacchhee 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 __ssttoorree__ccaacchhee below for more details. __sseepp__ppaarrttss (□)ffoooo::bbaarr のように、区切り文字で区切られた複数の 補完対象語を補完する。 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 `hhoossttss==((ffttpp nneewwss))' the call `__sseepp__ppaarrttss ''((ffoooo bbaarr))'' @@ hhoossttss' will complete the string `ff' to `ffoooo' and the string `bb@@nn' to `bbaarr@@nneewwss'. This function accepts the ccoommppaadddd options `--VV', `--JJ', `--11', `--22', `--nn', `--XX', `--MM', `--PP', `--SS', `--rr', `--RR', and `--qq' and passes them on to the ccoomm-- ppaadddd builtin used to add the matches. __sseettuupp _t_a_g [ _g_r_o_u_p ] This function sets up the special parameters used by the completion system appropriately for the _t_a_g given as the first argument. It uses the styles lliisstt--ccoolloorrss, lliisstt--ppaacckkeedd, lliisstt--rroowwss--ffiirrsstt, llaasstt--pprroommpptt, aacccceepptt--eexxaacctt, mmeennuu and ffoorrccee--lliisstt. The optional _g_r_o_u_p supplies the name of the group in which the matches will be placed. If it is not given, the _t_a_g is used as the group name. This function is called automatically from __ddeessccrriippttiioonn and hence is not normally called explicitly. __ssttoorree__ccaacchhee _c_a_c_h_e___i_d_e_n_t_i_f_i_e_r _p_a_r_a_m_s ... This function, together with __rreettrriieevvee__ccaacchhee and __ccaacchhee__iinnvvaalliidd, 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 __rreettrriieevvee__ccaacchhee, even in different instances of the shell. The _c_a_c_h_e___i_d_e_n_t_i_f_i_e_r specifies the file which the data should be dumped to. The file is stored in a directory specified by the ccaacchhee--ppaatthh style which defaults to ~~//..zzccoommppccaacchhee. The remaining _p_a_r_a_m_s 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 uussee--ccaacchhee 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 __rreettrriieevvee__ccaacchhee when it already has the completion data available as parameters. However, in that case it should call __ccaacchhee__iinnvvaalliidd 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. __ttaaggss [ [ --CC _n_a_m_e ] _t_a_g_s ... ] 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 ttaagg--oorrddeerr style. Next, __ttaaggss 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 __rreeqquueesstteedd function should be called (see above). If `--CC _n_a_m_e' is given, _n_a_m_e is temporarily stored in the argument field (the fifth) of the context in the ccuurrccoonntteexxtt parameter during the call to __ttaaggss; the field is restored on exit. This allows __ttaaggss to use a more specific context without having to change and reset the ccuurrccoonntteexxtt parameter (which has the same effect). __vvaalluueess [ --OO _n_a_m_e ] [ --ss _s_e_p ] [ --SS _s_e_p ] [ --wwCC ] _d_e_s_c _s_p_e_c ... 「パラメータ=値」という形式の任意の並びを補完する。 `--OO _n_a_m_e' は If the first argument is the option `--OO _n_a_m_e', it will be used in the same way as by the __aarrgguummeennttss function. In other words, the ele- ments of the _n_a_m_e array will be passed to ccoommppaadddd when executing an action. If the first argument (or the first argument after `--OO _n_a_m_e') is `--ss', 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 `__vvaalluueess --ss' appear in the same word on the command line, unlike completion using __aarrgguummeennttss. If this option is not present, only a single value will be completed per word. Normally, __vvaalluueess 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 --ww 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 __aarrgguummeennttss 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 --SS (like --ss, 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: __vvaalluueess --ss ,, ''ddeessccrriippttiioonn'' \\ ''**ffoooo[[bbaarr]]'' \\ ''((ttwwoo))**oonnee[[nnuummbbeerr]]::ffiirrsstt ccoouunntt::'' \\ ''ttwwoo[[aannootthheerr nnuummbbeerr]]::::sseeccoonndd ccoouunntt::((11 22 33))'' This describes three possible values: `ffoooo', `oonnee', and `ttwwoo'. The first is described as `bbaarr', takes no argument and may appear more than once. The second is described as `nnuummbbeerr', may appear more than once, and takes one mandatory argument described as `ffiirrsstt ccoouunntt'; no action is specified, so it will not be completed. The `((ttwwoo))' at the beginning says that if the value `oonnee' is on the line, the value `ttwwoo' will no longer be considered a possible completion. Finally, the last value (`ttwwoo') is described as `aannootthheerr nnuummbbeerr' and takes an optional argument described as `sseeccoonndd ccoouunntt' for which the completions (to appear after an `==') are `11', `22', and `33'. The __vvaalluueess function will complete lists of these values separated by commas. zsh 4.3.2 March 2, 2006 92 ZSHCOMPSYS(1) ZSHCOMPSYS(1) Like __aarrgguummeennttss, this function temporarily adds another context name component to the arguments element (the fifth) of the current context while executing the _a_c_t_i_o_n. Here this name is just the name of the value for which the argument is com- pleted. The style vveerrbboossee is used to decide if the descrip- tions for the values (but not those for the argu- ments) should be printed. The associative array vvaall__aarrggss is used to report values and their arguments; this works similarly to the oopptt__aarrggss associative array used by __aarrgguummeennttss. Hence the function calling __vvaalluueess should declare the local parameters ssttaattee, lliinnee, ccoonntteexxtt and vvaall__aarrggss: llooccaall ccoonntteexxtt ssttaattee lliinnee ttyyppeesseett --AA vvaall__aarrggss when using an action of the form `-->>_s_t_r_i_n_g'. With this function the ccoonntteexxtt parameter will be set to the name of the value whose argument is to be com- pleted. Note also that __vvaalluueess 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 `-->>_s_t_r_i_n_g' 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 `--qqSS _x' either directly or indirectly to ccoommppaadddd. The option --CC is treated in the same way as it is by __aarrgguummeennttss. In that case the parameter ccuurrccoonn-- tteexxtt should be made local instead of ccoonntteexxtt (as described above). __wwaanntteedd [ --xx ] [ --CC _n_a_m_e ] [ --1122VVJJ ] _t_a_g _n_a_m_e _d_e_s_c_r _c_o_m_m_a_n_d _a_r_g_s ... 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 __wwaanntteedd are the same as those to __rreeqquueesstteedd, i.e. arguments to be passed to __ddeessccrriippttiioonn. However, in this case the _c_o_m_m_a_n_d 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 __wwaanntteedd. Hence to offer only one tag and immediately add the corresponding matches with the given description: llooccaall eexxppll __wwaanntteedd ttaagg eexxppll ''ddeessccrriippttiioonn'' \\ ccoommppaadddd mmaattcchheess...... Note that, as for __rreeqquueesstteedd, the _c_o_m_m_a_n_d must be able to accept options to be passed down to ccoomm-- ppaadddd. Like __ttaaggss this function supports the --CC option to give a different name for the argument context field. The --xx option has the same meaning as for __ddeessccrriippttiioonn. CCOOMMPPLLEETTIIOONN DDIIRREECCTTOORRIIEESS In the source distribution, the files are contained in various subdirectories of the CCoommpplleettiioonn 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 ffppaatthh than the standard directory where it appears. BBaassee 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. ZZsshh Functions for completing arguments of shell builtin commands and utility functions for this. Some of these are also used by functions from the UUnniixx directory. UUnniixx 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 mmoouunntt 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 ----hheellpp option is supported. XX, AAIIXX, BBSSDD, ... 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 LLiinnuuxx and DDeebbiiaann directories, as well as the XX directory, may be useful on your system. zsh 4.3.2 March 2, 2006 95