texinode(Completion System)(Completion Using compctl)(Completion Widgets)(Top)
chapter(Completion System)
cindex(completion system)
cindex(completion, programmable)
cindex(completion, controlling)
sect(Description)

訳注: ○は独自追加。△は怪しい意訳。□は原文からばっさり改変。

ここではzshの「新しい」補完システム tt(compsys) について述べる。
この補完システムは
ifzman(zmanref(zshcompwid))\
ifnzman(the previous chapter, noderef(補完ウィジェット))
で述べたシェル関数の集合体で構築されている。

この補完システムは，コンテクストやカーソル位置によって
うまく処理を切り替えるようにできている。
最初から多くのコマンドに対する補完プログラムが用意されているので
ユーザは初期設定(\
ifzman(次のINITIALIZATION節)\
ifnzman(in noderef(Initialization)))
以上のことは知らなくても随分楽ができるようになっている(□)。

コンテクストとは，どんな補完を施すのかを決めるコマンドライン上の文脈
のことで，
The context that decides what completion is to be performed may be
startitemize()
itemiz(\
引数位置かオプション位置の場合: 
そのコマンドライン位置がどんな補完が要求されるべき場所なのか。
たとえば，「rmdir の第1引数位置」ならディレクトリ名。
)
itemiz(\
特別なコンテクスト: シェルの文法固有のルールが適用される場所か。
たとえば，「コマンド位置の単語」だとか，「配列の添字」だとか。
)
enditemize()

コンテクストそのものの詳細は追って述べる。

コマンド名やコンテクストだけでなく，この補完システムでは
em(スタイル) と em(タグ) という概念を使用する。これらは，
ユーザが補完システムの挙動を調整するためのものである。

「タグ」は，ユーザが補完させたいであろう
様々な単語群をいくつかの種別に分類するためのものである。たとえば，
tt(less) (□) と打ったら，そのあとに入れて欲しいのは
ディレクトリ(tt(directories))よりもファイル(tt(files))のほうだろう。
この tt(files) と tt(directories) がタグである(□ 訳注: 原文が
冒頭と言う流れを全く無視しているので根本的に変えた)

(読まんでええ ここから)
Tags play a dual role.  They serve as a classification system for
the matches, typically indicating a class of object that the user
may need to distinguish.  For example, when completing arguments of the
tt(ls) command the user may prefer to try tt(files) before tt(directories),
so both of these are tags.  They also appear as the rightmost
element in a context specification.
(ここまで)

「スタイル」はユーザがその値を自分で変えて，
補完システムの様々な動き，たとえばマッチする単語の出力
を変えたりするなど，様々な挙動をコントロールすることができる。
(訳注: ここも原文が冗長。冒頭なのでさらっと)

(読まんでええ)
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 tt(zstyle) command described in
ifzman(see zmanref(zshmodules))\
ifnzman(noderef(The zsh/zutil Module)).
(ここまで)


大雑把に言えば，タグは補完すべきものがem(何)なのか，スタイルはそれらを
em(どう)補完するかを決めるものである(□)。

(読まんでええ)
In summary, tags describe em(what) the completion objects are, and style
tt(how) they are to be completed.  At various points of execution, the
completion system checks what styles and/or tags are defined for the
current context, and uses that to modify its behavior.  The full
description of context handling, which determines how tags and other
elements of the context influence the behaviour of styles, is described
ifzman(below in COMPLETION SYSTEM CONFIGURATION)\
ifnzman(in noderef(Completion System Configuration)).
(ここまで)

補完要求が発生すると，まず振り分け関数(ディスパッチャ)が呼ばれ……
(訳注: というこの段落もここにあってもちっとも分かりやすくないので飛ばす)

When a completion is requested, a dispatcher function is called;
see the description of tt(_main_complete) in the list of control functions
below. This dispatcher decides which function should
be called to produce the completions, and calls it. The result is
passed to one or more em(completers), functions that implement
individual completion strategies: simple completion, error correction,
completion with error correction, menu selection, etc.

(ここまで)

多くのシェル関数があるが，
`tt(comp)' で始まるものは直接呼ばれるもの，`tt(_)' で始まるものは
補完プログラムから呼ばれるものである。後者のシェル関数は補完の挙動を
決定するもので，たいていは「ウィジェット」としてキーストロークに割り当てられる。

comment(
More generally, the shell functions contained in the completion system are
of two types:
startitemize()
itemiz(\
those beginning `tt(comp)' are to be called directly; there are only
a few of these;
)
itemiz(\
those beginning `tt(_)' are called by the
completion code.  The shell functions of this set, which implement
completion behaviour and may be bound to keystrokes, are referred to
as `widgets'.  These proliferate as new completions are required.
)
enditemize()

)


startmenu()
menu(初期化)
menu(Completion System Configuration)
menu(Control Functions)
menu(割り当て可能コマンド)
menu(補完関数)
menu(Completion Directories)
endmenu()

texinode(初期化)(Completion System Configuration)()(Completion System)
sect(INITIALIZATION)
findex(compinstall)
cindex(補完システム, 導入)

zshが完全な形でインストールされていれば，ユーザは
tt(compinit)を呼ぶだけで初期化が終わる(次節参照)。ただし，
tt(compinstall)を実行して補完システムのさらなる機能を
設定することもできる。

通常 tt(compinstall) は tt(.zshrc) ファイルにコードを追加する。
それに書けなければ別のファイルに書いてそのことを通知する。
ただし追加したコードが実際に動くかどうかは自己責任で確認すべきで，
たとえば tt(.zshrc) の途中で return する可能性があるときは
足されたコードをもっと前の位置に動かす必要がある。
足されたコードを(コメント行を含めて)まるごといじらないようにしておけば，
どこに移動しても将来 tt(compinstall) を再実行したときに正しく場所を
検出して修正してくれるが，もしそのコード群に手動で何か足したときは
次の tt(compinstall) でそれは消されるので注意されたい(tt(zstyle)で始まる
行はやんわりと処理される)。

新しく足されたコードは次にzshを起動したときか，
tt(.zshrc)をsourceすれば有効になる。ただし，
tt(compinstall)によって削られた定義があるときは，
その違いはシェルを再起動しない限りわからない。

最初に tt(compinstall) を実行する前に， tt(fpath) 変数に登録された
ディレクトリ群のどれかに tt(compinstall) があることを確認する必要が
あるかもしれないが，正常にzshがインストールされた状態で tt(fpath) の値を
勝手に削ったりしていなければ問題ないはずである(△)。
`tt(autoload -U compinstall)' でautoloadできるはずである。
tt(compinstall) を起動すると tt(.zshrc) 情報表示とともに
プロンプトが出るのでいつでも中止できる。最後の最後に確認が出る
ところまで一切 tt(.zshrc) は上書きされない。

subsect(compinitの起動)
findex(compinit)
cindex(補完システム, 初期化)

ここでは，使用中のシェル環境で直接 tt(compinit) を呼んで補完を初期化
する方法について述べる。もし tt(compinstall) が完了していれば
tt(.zshrc) の中で自動的に呼ばれることになる。

tt(compinit) コマンドもやはり tt(fpath) 変数に登録されている
ディレクトリ群のどれかに存在する必要がある。登録されていれば
`tt(autoload -U compinit; compinit)' で実行できるはずである。
tt(compinit)はいくつかのシェル関数定義と必要なシェル関数の
autoload定義処理と新しい補完システムで使うウィジェットを定義しなおす。
もし tt(menu-select) ウィジェット(tt(zsh/complist)モジュール)を使うのであれば，
tt(compinit) より先にそのモジュールをロードしておくようにする。
補完スタイル(後述)が補完とともに展開も行なうように設定されていて，
TABキーに tt(expand-or-complete) を割り当てているときは
tt(compinit) はそれを tt(complete-word) に変えて展開が正しく行なわれる
ようにする。

なお，古い補完ウィジェットをそのまま使いたいときは，ウィジェットの名前に
ピリオド `tt(.)' を付けた名前をどれかのキーに割り当てればよい。たとえば，
`tt(.exapnd-or-complete)' とする。


デフォルトで tt(compinit) は読み込んだ設定をダンプしたものをファイルに書き出し
2回目以降の処理が高速に済むようにしている。
これを無効化するには tt(compinit) に tt(-D) オプションを付けて呼べばよい。
ダンプファイルは tt(.zcompdump) という名前で，各種初期化ファイル群と
同じディレクトリ(tt($ZDOTDIR)か tt($HOME))に置かれる。
このファイル名は tt(-d) オプションで変更できる。
次回 tt(compinit) はダンプファイルをロードし，完全な初期化はしない。

補完定義ファイルが更新されたときは tt(compinit) がそれを認識し，
ダンプファイルを作り直す。ただし，関数名や補完定義ファイルの1行目にある
tt(#compdef) の引数を変えたときは，手動でダンプファイルを消して，
次の tt(compinit) に新規に作り直させてしまうのが一番面倒がない。
この更新チェック機能は tt(-C) オプションで無効化され，その場合
ダンプファイルがない場合のみ作り直す。

実際のダンプ処理は下請けで呼ばれる tt(compdump) 関数が行なっている。
手動で明示的にダンプファイルを作りたい場合以外は呼ぶ必要はないだろう(□)。

変数 tt(_compdir) にディレクトリ名を代入しておくと，
tt(compinit) はそのディレクトリを補完定義関数のある場所と見なす。

セキュリティ確保のため，
tt(compinit) はスーパーユーザ，またはユーザ自身
の所有でないファイル，所有者以外にも書き込めるディレクトリかどうかを
調べる。
該当する場合は tt(compinit) が本当に使うか確認する。
こうした検査をやめ，みつかったファイルを確認なし使わせたい場合は
tt(-u) オプション，危険なファイルを黙って無視させたい場合は
tt(-i) オプション，セキュリティチェックを完全にスキップさせたい場合は
tt(-C) オプションを指定すればよい。

findex(compaudit)
セキュリティチェックは tt(compaudit) 関数を起動すればいつでも行なえる。
起動時にディレクトリを指定すればそのディレクトリを，
指定しなければ tt(fpath) と tt(_compdir) が検査される(□大分省略)。
tt(compinit) のときと厳密に同じ場所を調べさせるには
tt(_compdir) 変数に空文字列を代入してから呼ぶこと。

subsect(オートロードファイル)
cindex(補完システム, オートロード関数)

先述のとおり，補完で使用するオートロード関数はアンダースコアで始める
約束とし，それらのファイルが tt(fpath/FPATH) 変数の指し示すディレクトリ
に存在しなければならない(繰り返すがzshが正常にインストールされていれば
そうなっているはずである)。

インストールが不完全で，
tt(compinit) がアンダースコアで始まるファイルを20個以上探せなかった場合は，
tt(_compdir) 変数の値を追加して探す。
もしそこに tt(Base) というサブディレクトリがみつかれば，同じ階層の
すべてのサブディレクトリを，さらに tt(Base) の下に tt(Core) という
サブディレクトリがみつかれば，そこにあるすべてのサブディレクトリを
追加する。これは，zshのソース配布に含まれるディレクトリを想定した
挙動で，これを活かすには _compinit にソースを展開したディレクトリの
tt(./Completion) ディレクトリを代入しておけばよいことになる(○)。

cindex(compdef, compinitの起動)
tt(compinit) は，
tt(fpath/FPATH)にあるすべてのファイルの1行目を調べ，
特定のタグがあれば処理し，なければ無視する。

タグの書式は以下のどれか:

startitem()
item(tt(#compdef) var(names...) [ tt(-[pP]) var(patterns...) [ tt(-N) var(names...) ] ])(
そのファイルをautoload登録し，var(names) を補完するときに
そこに定義されている関数が呼ばれるように設定する。
var(names)は引数入力を補完して欲しいコマンドの名前か，
tt(-)var(context)tt(-) という書式で指定する特別なコンテクスト(文脈)
指定のどれかを書く。
(or one of
a number of special contexts in the form tt(-)var(context)tt(-) described
below.)

var(name)の部分には `var(cmd)tt(=)var(service)' という記述も書け，
その場合 var(cmd) を補完するときに，var(service) を補完するときと
同じ挙動をするようになる。
これは，そこで定義している補完用関数の挙動を変えるために利用できる。
実際にはその関数が呼ばれるときに，どのコマンドの補完をするために呼ばれたのかを
変数 tt($service) に代入してくれるので，関数作成時にはその値で
処理を切り替えるとよい。もちろんその値を使わなくても構わない(□)。

tt(#compdef) の行に tt(-p) か tt(-P) オプションがある場合は，
後続する引数(群)がパターンとして解釈され，そのパターン(のどれか)にマッチする
コマンド(または文脈)に対する補完をするときに関数が呼ばれるようになる。
tt(-p) は他の補完を試す前， tt(-P) は試したあとに呼ばれるパターンを
指定する。よって， tt(-P) はデフォルトの挙動を指定するときに使える。

tt(-N) オプションは， tt(-p) や tt(-P) オプションに続けて書いたパターンの
あとに指定して，以後の引数はパターン指定でないことを指示する。
)
item(tt(#compdef -k) var(style key-sequences...))(
内部ウィジェット var(style) と同様に振る舞うウィジェットを作り
var(key-sequences) に割り当てる。
var(style) には，補完機能を持つ
内部ウィジェットのどれか，すなわち
tt(complete-word), tt(delete-char-or-list),
tt(expand-or-complete), tt(expand-or-complete-prefix), tt(list-choices),
tt(menu-complete), tt(menu-expand-or-complete),
tt(reverse-menu-complete)
のどれかを指定する。もし，
tt(zsh/complist) モジュール(
ifzman(zmanref(zshmodules))\
ifnzman(noderef(The zsh/complist Module))\
参照)
がロードされている場合は tt(menu-select) も指定可能。

var(key-sequences) で指定したどれかのキーがタイプされると
そのファイルで定義されている関数がマッチ単語を生成するために呼ばれる。
ただし，指定したキーストロークに既に別の機能が割り当ててある場合は
そのキーへの割り当ては行なわれない。作成されるウィジェットはファイル名と
同じ名前で，
tt(bindkey)コマンドで普通に割り当てできるものとなる。
)
item(tt(#compdef -K) var(widget-name) var(style) var(key-sequences) ...)(
tt(-k)と同様だが，ひとつの var(widget-name) と var(style) の組み合わせに
対し，ひとつの var(key-sequences) だけが指定できる。この3つの引数の
組み合わせを何個でも書ける。その場合 var(widget-name) が重複しないようにする。
最初の文字が `tt(_)' で始まっていない場合は補われる。
var(widget-name)
の名前は，他のウィジェットと衝突しないようにしなければならないので，
関数名に由来した名前を付けるとよい。たとえば，

example(#compdef -K _foo_complete complete-word "^X^C" \ 
  _foo_list list-choices "^X^D")

(実際には1行で記述する) のような名前付けをする。この例の場合，
tt(_foo_complete) ウィジェットを補完用と定義して，
`tt(^X^C)'に割り当て， tt(_foo_list) ウィジェットを一覧出力用に
定義して `tt(^X^D)' に割り当てている。
)
item(tt(#autoload) [ var(options) ])(
tt(#autoload) タグはその関数をautoload登録するのみで，他の処理は
行なわないことを指示する。典型的には，補完関数の下請け
関数をautoload化したりするために用いる。
var(options) を続けて書くと
それをそのまま tt(autoload)コマンドに渡す。たとえば，
tt(+X) を書いて，
その関数を直ちにロードさせたりできる。オートロードの際には常に
tt(-U)，tt(-z) オプションが暗黙のうちに有効化される。
)
enditem()

タグに書く tt(#) 文字もタグ名に含まれるため，その後に空白を書いてはいけない。
tt(#compdef) タグは後述する tt(compdef) 関数で処理される。
tt(compdef)関数は補完用関数名を明示的に指定する必要があるが，
タグの方は暗黙のうちに決められるという点が異っている。

どのような文脈で呼ばれる関数が定義されるかのコンテクスト指定は
下記のいずれか:
(The special contexts for which completion functions can be defined are:)

startitem()
kindex(-array-value-, completion context)
item(tt(-array-value-))(
配列への代入時の右辺の位置
(`tt(foo=LPAR()...RPAR())')
)
kindex(-brace-parameter-, completion context)
item(tt(-brace-parameter-))(
中括弧内での変数名の展開 (`tt(${...})')
)
kindex(-assign-parameter-, completion context)
item(tt(-assign-parameter-))(
変数代入時の変数名(`tt(=)'の左側)
)
kindex(-command-, completion context)
item(tt(-command-))(
コマンド位置での単語
)
kindex(-condition-, completion context)
item(tt(-condition-))(
条件式 (`tt([[...]])') 内の単語
)
kindex(-default-, completion context)
item(tt(-default-))(
他の補完が定義されていないときのデフォルトの補完
)
kindex(-equal-, completion context)
item(tt(-equal-))(
イコール記号で始まる単語
)
kindex(-first-, completion context)
item(tt(-first-))(
すべての補完に先だって呼ばれる。呼ばれる関数ではその後本来呼ばれる補完機能
をキャンセルするための変数 tt(_compskip) に値を設定できる。
意味ある値は，tt(all): その後の補完機能は一切呼ばない，
tt(patterns) という文字列を含む文字列: パターン補完関数(訳注: なにそれ???)
を呼ばない，tt(default) という文字列を含む文字列: `tt(-default-)'
コンテクスト用の補完関数を呼ばない(そのコマンド用の補完関数は呼ぶ)，
のいずれかである。
)
kindex(-math-, completion context)
item(tt(-math-))(
`tt(LPAR()LPAR())...tt(RPAR()RPAR())' の内部のような
数式コンテクスト
)
kindex(-parameter-, completion context)
item(tt(-parameter-))(
変数名展開(`tt($...)')
)
kindex(-redirect-, completion context)
item(tt(-redirect-))(
リダイレクション記号の後の単語
)
kindex(-subscript-, completion context)
item(tt(-subscript-))(
変数の添字の中味.
)
kindex(-tilde-, completion context)
item(tt(-tilde-))(
`tt(~)' 記号の後でスラッシュより前の単語
)
kindex(-value-, completion context)
item(tt(-value-))(
代入の右側
)
enditem()

上記のどのコンテクストにもデフォルトの補完関数が用意されていて，
それらはコンテクスト名の前に tt(_) を付けた名前になっている。たとえば，
`tt(-tilde-)' 用のデフォルト関数は `tt(_tilde)' である(□)。

tt(-redirect-) と tt(-value-) コンテクストには追加で，コンテクスト依存の
情報を指定できる(内部的には tt(_dispatch) 関数で処理される)。
追加情報はカンマで区切って指定する。

tt(-redirect-) コンテクストでは，追加情報は
`tt(-redirect-,)var(op)tt(,)var(command)' の形式で指定する。
ここで var(op) はリダイレクション記号，var(command) はそのコマンドラインに
書かれたコマンドである。コマンドラインにコマンドが書かれていない状態の
指定は var(command) 欄は空となる。訳注: var(command) の部分には，
`var(cmd)tt(=)var(service)' という記述も書ける。

tt(-value-) コンテクストの追加情報は
`tt(-value-,)var(name)tt(,)var(command)' という形式で指定する。
ここで var(name) は変数名である。もし連想配列の要素で補完を
行なう場合，例えば `tt(assoc=LPAR()key <TAB>)' のとき，
var(name) は `var(name)tt(-)var(key)' に展開される。
また，`tt(make CFLAGS=)' までタイプして補完した場合などは，
var(command) の部分がそのコマンド(つまり tt(make))になり，
それ以外の場合は空になる(□)。

このコンテクスト追加情報は，すべて厳密に決めたものからだんだん緩い
コンテクストへと順次試されるので，必ずしもすべて厳密に決めたコンテクスト
追加情報を与えておく必要はない。要するにたとえば，
`tt(foo=<TAB>)' という補完を行なうとき，その補完を受け持つ tt(_value)
という関数はまず `tt(-value-,foo,)' というコンテクストを
調べる(最後のカンマの右側は var(command) が空ということを意味している)。
続いて `tt(-value-,foo,-default-)'，`tt(-value-,-default-,-default-)'
という順番にそのコンテクストでの補完が定義されているかを調べて行く。

例(1):

example(compdef '_files -g "*.log"' '-redirect-,2>,-default-')

`tt(2> <TAB>)' という文字列の後では，とくにそのコマンド用の補完が
定義されていないコマンドのときには `tt(*.log)' にマッチするファイル名を
補う。

例(2):

example(compdef _foo -value-,-default-,-default-)

変数への代入で，とくに指定のない場合は tt(_foo) 関数が補完する。
通常は tt(_value) 関数がその処理をしている。

上記例(1)と同じルールはスタイル(後述)を用いて以下のようにも指定できる。

example(zstyle ':completion:*:*:-redirect-,2>,*:*' file-patterns '*.log')

tt(zstyle) コマンドがスタイルを定義するものである(□)。

subsect(Functions)

以下の関数群は tt(compinit) 呼出しにより定義される。

findex(compdef)
cindex(補完システム, 定義の追加)
startitem()
xitem(tt(compdef) [ tt(-an) ] var(function names...) [ tt(-[pP]) var(patterns...) [ tt(-N) var(names...) ] ])
xitem(tt(compdef -d) var(names...))
xitem(tt(compdef -k) [ tt(-an) ] var(function style key-sequences...))
item(tt(compdef -K) [ tt(-an) ] var(function name style key-sequences ...))(
第1の書式は，指定したコンテクスト(tt(#compdef)記法のときと同様の指定)の
ときの補完に var(function) 関数を呼ぶことを定義する。

やはり tt(#compdef) 記法のときと同様引数は，
`var(cmd)tt(=)var(service)' のようにも書ける。ただしその場合
既に tt(#compdef) で別の `var(cmd1)tt(=)var(service)' が定義されて
いなければならない(訳注: $serviceで挙動を変えるような関数になっていないと
いきなり `var(cmd)tt(=)var(service)' で別名定義しても挙動が怪しいから)。

引数の var(function) には関数でなく，シェルの文を含む文字列を書くこともできる。
その文字列は補完単語群を生成するため内部コマンド tt(eval) で評価される。
これは，単純がゆえいちいち関数を定義したくない場合に便利で，
たとえば tt(foo) コマンドの引数として単に `tt(.h)' ファイルだけを補完させたい
のであれば，

example(compdef '_files -g "*.h"' foo)

とすればよい(訳注: tt(_files)関数はファイルの補完単語を生成する既定の関数)。

tt(-n) オプションは，そのコマンドやコンテクスト用に既に補完が定義されている
場合に上書き設定しないことを指示する。

tt(-d) オプションはコマンドやコンテクスト用の補完定義を削除する。

tt(#compdef) のときと同様，var(names) の部分には
tt(-p), tt(-P) and tt(-N) オプションを指定できる(意味も tt(#compdef) 
のときと同じ(パターン指定の切り替え)□)。

パターンコンテクストで呼ばれる関数では，変数 tt($_compskip) 
に値を設定してその他の補完関数が呼ばれるかを制御できる。
`tt(patterns)' という文字列を含む文字列を指定すると
パターン関数(訳注: って何???)が呼ばれなくなり，
`tt(all)' という文字列を含む文字列を指定すると他の関数が
全く呼ばれなくなる。

tt(-k) と tt(-K) オプションの書式は tt(#compdef) のときと同じ。
明示的に関数を指定するかどうかの違い(訳注: 要実験)。
comment(
The form with tt(-k) defines a widget with the same name as the var(function)
that will be called for each of the var(key-sequences); this is like the
tt(#compdef -k) tag.  The function should generate the completions needed
and will otherwise behave like the builtin widget whose name is given as
the var(style) argument.  The widgets usable for this are:
tt(complete-word), tt(delete-char-or-list), tt(expand-or-complete),
tt(expand-or-complete-prefix), tt(list-choices), tt(menu-complete),
tt(menu-expand-or-complete), and tt(reverse-menu-complete), as well as
tt(menu-select) if the tt(zsh/complist) module is loaded.  The option tt(-n)
prevents the key being bound if it is already to bound to something other
than tt(undefined-key).

The form with tt(-K) is similar and defines multiple widgets based on the
same var(function), each of which requires the set of three arguments
var(name), var(style) and var(key-sequences), where the latter two are as
for tt(-k) and the first must be a unique widget name beginning with an
underscore.
)

どの書式でも適用可能なオプション tt(-a) は var(function) を
オートロード化する。
tt(autoload -U )var(function) と等価。
)
enditem()

tt(compdef) 関数を用いて，既存の補完関数を新しいコマンドに適用
させることもできる。たとえは，

example(compdef _pids foo)

とすると，tt(foo) というコマンドの引数補完で tt(_pids) 関数を呼び
プロセスIDを補完させられるようになる。

ちなみに，後述する tt(_gnu_generic) 関数は
`tt(-)tt(-help)' オプションを受け付けるコマンドの補完をある程度
自動的に行なう(□)。

texinode(補完システム Configuration)(Control Functions)(初期化)(補完システム)
sect(Configuration)
cindex(補完システム, configuration)

この節ではまず補完システムの動き方の概要を述べ，続いて
どのタイミングでどう補完単語を生成させるかをユーザが設定する
方法について詳しく説明していく。

subsect(概要)

コマンドラインのどこかで呼び出された補完機能は，最初にコンテクストを
調べる。コマンドの単語(たとえば `tt(grep)' なのか，`tt(zsh) なのか)，
カーソル位置の単語が引数に見なされるようなオプション(たとえば
tt(zsh) の `tt(-o)' オプションはシェルオプションを引数に取る)
などなど。

こうしたコンテクスト情報はコロンで区切られた複数のフィールドを持つ
文字列に圧縮される。以後コンテクストと言ったらその文字列で表現する。
コンテクストはem(スタイル)というコンテクストに影響を受けるオプションを
探すために用いられ，それによって補完システムを設定する(訳注: うーん
漠然としすぎじゃん)。検索に使われるコンテクストは，
同じ補完システムを呼ぶ場合でも様々な値に変わる(△)。

コンテクストを表す文字列は，先頭にあるコロン文字に続けて
常に決まったフィールドを持つ以下のようなものである。

tt(:completion:)var(function)tt(:)var(completer)tt(:)var(command)tt(:)var(argum
ent)tt(:)tt(tag).

各フィールドの意味は以下のとおり。

startitemize()
itemiz(\
tt(completion) という文字列そのもの(□):
comment(
The literal string tt(completion), saying that this style is used by
the 補完システム.  This distinguishes the context from those used
by, for example, zle widgets and ZFTP functions.)
)
itemiz(\
var(function): 通常の補完システム経由でなく，名前つきウィジェット
から補完が呼ばれた場合の関数名。たいていは空だが，tt(predict-on)
のような特殊ウィジェットや，zshのソースディレクトリの
tt(Widget) ディレクトリにある関数によってなんらかの値がセットされる。
)
itemiz(\
var(completer): 稼動中のコンプリータで，関数名の先頭のアンダースコアを
とり，途中にあるアンダースコアをハイフンに変えた名前。コンプリータは
どのように補完するかを統轄するもので，もっとも単純な `tt(complete)' 
を始め，綴り修正，その後のコンプリータの挙動を変えるためのものなど
いくつかある。
ifzman(「Control Functions」の節)\
ifnzman(noderef(Control Functions)) 
参照。
)
itemiz(\
var(command) または tt(-)var(context)tt(-):
tt(#compdef) タグや tt(compdef) のところで登場したもの。
サブコマンドを持つコマンドの補完のときには，このフィールドに
コマンド名とサブコマンド名をハイフンで繋いだものがセットされる。
たとえば，tt(cvs) の tt(add) サブコマンドの補完を行なうときには，
このフィールドが tt(cvs-add) になる。
)
itemiz(\
var(argument): どのコマンドライン，オプション引数の補完をしている
のかを示す文字列。コマンドの(オプション引数でない) var(n)番目の引数ならば，
tt(argument-)var(n) に，var(opt)というオプションの var(n) 番目の引数ならば，
tt(option-)var(opt)tt(-)var(n) となる。
ただし，コマンドラインが標準的なUnix流オプション・引数表記ルールで
解析される場合のみ有効で，これがセットされない場合も少なくない(□)。
)
itemiz(\
var(tag): マッチさせる対象物の種別を区別させるために使うもので，
詳細は次に挙げる例で説明する(□□)。
comment(
The var(tag).  Tags are used to discriminate between the types
of matches a completion function can generate in a certain context and
are described further below.)
)
enditemize()

コンテクストは，補完機能が働く入口のところで tt(:completion:) (と
必要なら関数名var(function))だけが足された状態から始まって，各種関数が
呼ばれる毎にどんどん構築されていく。そうしてコンプリータが var(completer)
要素を足し，コンテクスト補完が var(add) と var(argument) オプションを足し，
最後に，どういう種類の単語を補完したいのかが判明した時点で
var(tag) が足される。

一例を挙げる。

example(tt(:completion::complete:dvips:option-o-1:files))

というコンテクストは，tt(dvips) コマンドの tt(-o) オプションの第1引数では
通常(ファイル)補完を試みることを示している。よって，

example(tt(dvips -o ...))

というコマンドラインでの補完関数はファイル名を生成する。

与えられたコンテクストにおいてどんな種類の補完を実行できるかは，
上の例で出てきた tt(files) を始めとする「タグ」という文字列で表現される。
どの補完関数も任意のタグ名を使って構わないが，一般的なものは
あらかじめ決められている(一覧を後述)。
?????????????????????????????ここは削ってよい箇所

通常補完機能は，補完関数から渡された順番ですべてのタグに対して試される。
この順番は tt(tag-order) スタイルで変更できる。補完は渡された
タグを渡された順番に行なうだけに限定できる(△)。

実際に，どういうコンテクストでどういうタグの補完をさせるかを
知るためのキー割り当て可能な内部コマンド tt(_complete_help) を
使って見ることができる。(訳注:
tt(_complete_help) はデフォルトで tt(^Xh) に割り当てられているので，
これを `tt(dvips -o )' まで入力したところでタイプしてみるとよい。)
これを用いると tt(tag-order) やその他のスタイルの詳細が分かる。
ifzman(後述する`Bindable Command'の節)\
ifnzman(noderef(Bindable Command))参照。

「スタイル」とはどのようにマッチするものを生成するかを決定する，
シェルオプションをより一層強力にしたようなもので，文字列で表される
値を何個でも持たせられる。スタイルは内部コマンドの tt(zstyle) 
(\
ifzman(zmanref(zshmodules) 参照)\
ifnzman(noderef(The zsh/zutil Module))) で変更できる。

適合するスタイルを探すとき，補完システムはタグ名を含んだ
完全なコンテクスト名を利用する。
従って，スタイルの値を探す手順は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, which may be matched as a pattern, and the
name of the style itself, which must be given exactly.

たとえば，多くの補完関数はマッチする単語群を
一覧表示(tt(list-choices)□)する方法として，
簡素バージョン，お節介バージョンの2つを持っていて，どちらを選ぶかは
tt(verbose) スタイルの値で変更できるようになっている。
そういう風に作ってある補完関数すべてでお節介バージョンを選びたければ，

example(zstyle ':completion:*' verbose yes)

を初期化ファイル(おそらく tt(.zshrc)) に入れるとよい。
この文は補完システム(tt(completion))内のすべて(tt(*))のコンテクスト
の tt(verbose) スタイルに tt(yes) をセットしている。
実際にはすべてでなく，tt(*) よりも限定的に設定しているスタイル指定に
マッチするコンテクストであればそちらが使用される。
補完システム以外に影響を与えるといけないので，
パターンとしては `tt(*)' だけでなく `tt(:completion:*)' を
与えるべきである(□)。

ちなみに，tt(compinstall) を使って多くの汎用スタイルを設定することができる。

tt(style) の使用をより限定的に指定する例として，内部コマンド tt(kill) 
の補完を示す。この補完では tt(verbose) スタイルがセットされていると
(マッチする単語の一覧表示のときに□)，ジョブのテキストと
プロセスのコマンドラインをすべて出力し，スタイルがオフのときは
ジョブ番号とPIDのみを出力する。スタイルをオフにしたい場合は，

example(zstyle ':completion:*:*:kill:*' verbose no)

とする。もし，もっと限定的にしたいのであれば `tt(jobs)' か
`tt(processes)' タグを明示的に指定する。ジョブに関してだけ
tt(verbose) スタイルをオフにしたければ次のようにすればよい。

example(zstyle ':completion:*:*:kill:*:jobs' verbose no)

tt(zstyle) の tt(-e) オプションを用いると，補完関数に関数的な文を
直接指定できる(□)。

example(tt(zstyle -e ':completion:*' hosts 'reply=($myhosts)'))

これは，ホスト名補完が必要なときに tt(hosts) スタイルの値を
変数 tt(myhosts) から取得させる。もし tt(myhosts) の値が
変動するなら有用かもしれない。他の有用な例については
後述する tt(file-list) スタイルを参照。ただし，tt(-e)オプション
は速度低下の恐れがあるので tt(menu) や tt(list-rows-first) スタイルと
組み合わせない方がよい。

マッチするスタイル定義が複数あるような場合どれが選ばれるかは，
tt(zstyle)でそれらを定義した順番ではなく，どちらがより限定的な
ルールで書かれているかによって決まる。たとえば，リテラル文字列は
パターンを使用したものより優先されるので，
`tt(:completion::complete:foo)' は，
`tt(:completion::complete:*') よりも限定的と見なされる。また，
パターンを用いているものどうしでは，より長い(詳細な)パターンを使っている
もののほうが短い(大雑把な)パターンよりも優先される(□)。

スタイル名は，タグ名と同様各補完関数で任意に決められるが，
これもまた既定のものがあるので次とその次の節で一覧を示す。

subsect(標準タグ)
cindex(補完システム, タグ)

下記一覧のうちいくつかは，特殊なスタイルを探すときに使われるだけで，
マッチする単語の種別を示すものではない。

startitem()
kindex(accounts, 補完タグ)
item(tt(accounts))(
tt(users-hosts) スタイルを探すために用いられる(△???)
)
kindex(all-expansions, 補完タグ)
item(tt(all-expansions))(
tt(_expand) コンプリータが，1つの文字列にマッチするものすべてを
挿入するときに用いられる
)
kindex(all-files, 補完タグ)
item(tt(all-files))(
すべてのファイル名(△???)(下記 tt(globbed-files) タグも参照)
)
kindex(arguments, 補完タグ)
item(tt(arguments))(
コマンドに対する引数
)
kindex(arrays, 補完タグ)
item(tt(arrays))(
配列変数名
)
kindex(association-keys, 補完タグ)
item(tt(association-keys))(
連想配列のキー(連想配列変数の添字を補完する場合に使われる)
)
kindex(bookmarks, 補完タグ)
item(tt(bookmarks))(
ブックマークを補完するときに使われる
(e.g. URL や (zftp) モジュール)
)
kindex(builtins, 補完タグ)
item(tt(builtins))(
内部コマンドの名前
)
kindex(characters, 補完タグ)
item(tt(characters))(
1文字 (tt(stty) コマンドで制御文字を入力する部分や，
開き大括弧の後でキャラクタクラスを書く場合など)
)
kindex(colormapids, 補完タグ)
item(tt(colormapids))(
XのカラーマップID
)
kindex(colors, 補完タグ)
item(tt(colors))(
色の名前
)
kindex(commands, 補完タグ)
item(tt(commands))(
外部コマンドの名前で，tt(cvs)のような複雑なコマンドの補完で
サブコマンド一覧を得るためなどに用いる
)
kindex(contexts, 補完タグ)
item(tt(contexts))(
内部コマンド tt(zstyle) に与えるコンテクスト文字列
)
kindex(corrections, 補完タグ)
item(tt(corrections))(
tt(_approximate) と tt(_correct) コンプリータが，適当な修正の
ために使う。
)
kindex(cursors, 補完タグ)
item(tt(cursors))(
Xプログラムのカーソル名
)
kindex(default, 補完タグ)
item(tt(default))(
デフォルトのタグ: 別のより限定的なタグが有効な場合のデフォルトを
与えるために使われる(△???)。このタグはコンテクスト文字列の
var(function) フィールドがセットされている場合のみ有効。
used in some contexts to provide a way of supplying a default when more
specific tags are also valid.  Note that this tag is
used when only the var(function) field of the context name is set
)
kindex(descriptions, 補完タグ)
item(tt(descriptions))(
マッチの種別を記述するため tt(format) スタイルの値を調べるときに使う
)
kindex(devices, 補完タグ)
item(tt(devices))(
デバイスファイルの名前
)
kindex(directories, 補完タグ)
item(tt(directories))(
ディレクトリ名
)
kindex(directory-stack, 補完タグ)
item(tt(directory-stack))(
ディレクトリスタックのエントリ
)
kindex(displays, 補完タグ)
item(tt(displays))(
Xのディスプレイ名
)
kindex(domains, 補完タグ)
item(tt(domains))(
ネットワークドメイン名
)
kindex(expansions, 補完タグ)
item(tt(expansions))(
コマンドライン上の1語を展開した結果生ずる語を1個ずつ順番に出すための
タグで，tt(_expand)コンプリータによって使われる。
)
kindex(extensions, 補完タグ)
item(tt(extensions))(
Xサーバのエクステンション
)
kindex(file-descriptors, 補完タグ)
item(tt(file-descriptors))(
ファイルディスクリプタ
)
kindex(files, 補完タグ)
item(tt(files))(
ファイル名補完で用いられる汎用ファイル名マッチのタグ
)
kindex(fonts, 補完タグ)
item(tt(fonts))(
Xのフォント名
)
kindex(fstypes, 補完タグ)
item(tt(fstypes))(
tt(mount)コマンドなどで用いるファイルシステムタイプの名前
)
kindex(functions, 補完タグ)
item(tt(functions))(
関数名 DASH()- 通常はシェル関数だが特定のコマンドは別の種類の関数を把握する
)
kindex(globbed-files, 補完タグ)
item(tt(globbed-files))(
パターンマッチで生成されるファイル名
)
kindex(groups, 補完タグ)
item(tt(groups))(
グループ名
)
kindex(history-words, 補完タグ)
item(tt(history-words))(
ヒストリリストにある単語
)
kindex(hosts, 補完タグ)
item(tt(hosts))(
ホスト名
)
kindex(indexes, 補完タグ)
item(tt(indexes))(
配列の添字
)
kindex(jobs, 補完タグ)
item(tt(jobs))(
ジョブ名(内部コマンド`tt(jobs)で得られるもの)
)
kindex(interfaces, 補完タグ)
item(tt(interfaces))(
ネットワークインタフェース名
)
kindex(keymaps, 補完タグ)
item(tt(keymaps))(
zshのキーマップ名
)
kindex(keysyms, 補完タグ)
item(tt(keysyms))(
Xのkeysyms
)
kindex(libraries, 補完タグ)
item(tt(libraries))(
システムライブラリ名
)
kindex(limits, 補完タグ)
item(tt(limits))(
リソースリミット
)
kindex(local-directories, 補完タグ)
item(tt(local-directories))(
tt(cd) コマンド等の引数補完時の，カレントディレクトリにあるサブディレクトリ
(tt(path-directories)も参照)
)
kindex(manuals, 補完タグ)
item(tt(manuals))(
manにあるマニュアル名
)
kindex(mailboxes, 補完タグ)
item(tt(mailboxes))(
メイルフォルダ名
)
kindex(maps, 補完タグ)
item(tt(maps))(
マップ名(NISマップなど)
)
kindex(messages, 補完タグ)
item(tt(messages))(
メッセージ用の tt(format) スタイルを調べるときに使われる
)
kindex(modifiers, 補完タグ)
item(tt(modifiers))(
Xのモディファイア名(訳注: Shift, Control, Mod1, Mod2, ...)
)
kindex(modules, 補完タグ)
item(tt(modules))(
モジュール名 (tt(zsh) モジュール)
)
kindex(my-accounts, 補完タグ)
item(tt(my-accounts))(
tt(users-hosts) スタイルを調べるときに使われる
)
kindex(named-directories, 補完タグ)
item(tt(named-directories))(
名前つきディレクトリ
)
kindex(names, 補完タグ)
item(tt(names))(
すべての種類の名前
)
kindex(newsgroups, 補完タグ)
item(tt(newsgroups))(
USENET のニュースグループ
)
kindex(nicknames, 補完タグ)
item(tt(nicknames))(
NISマップのニックネーム(訳注: マップ名tt(passwd)はニックネーム)
)
kindex(options, 補完タグ)
item(tt(options))(
コマンドオプション
)
kindex(original, 補完タグ)
item(tt(original))(
tt(_approximate)，tt(_correct)，tt(_expand) コンプリータが
最初の文字列をマッチとして提示するときに使われる
)
kindex(other-accounts, 補完タグ)
item(tt(other-accounts))(
tt(users-hosts) スタイルを調べるときに使われる
)
kindex(packages, 補完タグ)
item(tt(packages))(
でびあんのぱっけーじ
)
kindex(parameters, 補完タグ)
item(tt(parameters))(
変数名
)
kindex(path-directories, 補完タグ)
item(tt(path-directories))(
tt(cd)などのディレクトリ移動系内部コマンドの引数を補完するときに，
tt(cdpath)変数に登録されたディレクトリ群からみつかるサブディレクトリ
(tt(local-directories)と比較せよ)
)
kindex(paths, 補完タグ)
item(tt(paths))(
tt(expand)，tt(ambiguous)，tt(special-dirs) スタイルの
値を調べるときに使われる(△???)
)
kindex(pods, 補完タグ)
item(tt(pods))(
Perl pods(ドキュメントファイル)
)
kindex(ports, 補完タグ)
item(tt(ports))(
ネットワークポート
)
kindex(prefixes, 補完タグ)
item(tt(prefixes))(
プレフィクス(URLのものなど)
)
kindex(printers, 補完タグ)
item(tt(printers))(
プリントキューの名前
)
kindex(processes, 補完タグ)
item(tt(processes))(
プロセスID
)
kindex(processes-names, 補完タグ)
item(tt(processes-names))(
tt(killall)コマンドで指定するプロセス名を生成するときに
tt(command) スタイルを調べるときに使われる
)
kindex(sequences, 補完タグ)
item(tt(sequences))(
シーケンス(tt(mh)のシーケンス(連番))
)
kindex(sessions, 補完タグ)
item(tt(sessions))(
tt(zftp) モジュールの「セッション」
)
kindex(signals, 補完タグ)
item(tt(signals))(
シグナル名
)
kindex(strings, 補完タグ)
item(tt(strings))(
文字列(tt(cd)コマンドでカレントディレクトリの一部置換を行なうときなど)
)
kindex(styles, 補完タグ)
item(tt(styles))(
内部コマンドtt(zstyle)用のスタイル名
)
kindex(suffixes, 補完タグ)
item(tt(suffixes))(
ファイル名の拡張子
)
kindex(tags, 補完タグ)
item(tt(tags))(
タグ名 (e.g. tt(rpm) タグ)
)
kindex(targets, 補完タグ)
item(tt(targets))(
Makefileのターゲット名
)
kindex(time-zones, 補完タグ)
item(tt(time-zones))(
タイムゾーン
)
kindex(types, 補完タグ)
item(tt(types))(
種別を表すもの何でも(たとえば tt(xhost) コマンドで指定するアドレスタイプなど)
)
kindex(urls, 補完タグ)
item(tt(urls))(
URL補完時に tt(urls) と tt(local) スタイルを参照するのに使われる
)
kindex(users, 補完タグ)
item(tt(users))(
ユーザ名
)
kindex(values, 補完タグ)
item(tt(values))(
指定したリストにある複数の値の候補から必ずひとつだけが補完されるような
補完候補の集合
)
kindex(variant, 補完タグ)
item(tt(variant))(
tt(_pick_variant) 関数が，インストールされているコマンドの種類を
決めるときに実際に起動するコマンドを決めるときに参照される。
訳注: このタグに対する tt(command) スタイルの値にコマンド名が
設定されていたらそれを起動する(tt(_call_program)関数の役目)。
)
kindex(visuals, 補完タグ)
item(tt(visuals))(
X visuals(訳注: ってなに???)
)
kindex(warnings, 補完タグ)
item(tt(warnings))(
tt(format) スタイルから警告を探すために使われる
)
kindex(widgets, 補完タグ)
item(tt(widgets))(
zshのウィジェット名
)
kindex(windows, 補完タグ)
item(tt(windows))(
X のウィンドウID
)
kindex(zsh-options, 補完タグ)
item(tt(zsh-options))(
zshのシェルオプション
)
enditem()

subsect(標準スタイル)
cindex(補完システム, styles)

これから説明する「スタイル」のうちいくつかは，設定すべき値が
真偽値となっている。
`tt(true)'，`tt(on)'，`tt(yes)'，`tt(1)' という文字列はどれも
`true'(真)を意味するものとして使え，
`tt(false)'，`tt(off)'，`tt(no)'，`tt(0)' という文字列はどれも
`false'(偽)を意味するものとして使える。
それ以外の値を設定したときの挙動は，とくにことわりのない限り未定義と
なっている。値がセットされていないときの値は true か false の
いずれかである。

また以下のスタイルのうちいくつかは，マッチの種別に応じて決まっている
タグ群にたいして照合され，
それでみつからなければデフォルトタグに対するそのスタイルが参照される。

もっとも身近なスタイルに
tt(menu)，
tt(list-colors)，
tt(list-packed)，
tt(last-promopt)がある(□)。

comment(
The most notable styles of this type are tt(menu), 
tt(list-colors) and styles controlling completion listing such as 
tt(list-packed) and tt(last-prompt). 
)
tt(default)タグをテストするとき，コンテクストの var(function) フィールド
だけがセットされる。それによってデフォルトタグを使うようなスタイルは次の
ようなコンテクスト定義で書くことになる。

example(zstyle ':completion:*:default' menu ...)

startitem()
kindex(accept-exact, completion style)
item(tt(accept-exact))(
現在のコンテキスト用のタグにくわえてデフォルトタグに対しても調べられる。
この値が `true' なら，コマンドライン上の単語が補完候補のどれかに
完全一致していたらそれを確定したものと見なす(たとえ，その単語で
補完される可能性を持つ候補がものが他にあったとしても)。

パス名補完のとき(そのときのタグは `tt(paths)')，
このスタイルには真偽値に加えて任意個のパターンを持たせてよく，
その場合与えたパターンのどれかにマッチするパスがコマンドライン上に
タイプされていたらそれを即確定する。その場合，確定されるパス名の
後ろにさらに多くのパスを入力していて，確定したあとにマッチするファイルが
ないとしても確定する。

訳注: わからんね。実例で示す。
tt(less /u/li/) で補完すると
tt(/u*/li*/) で探すので，tt(/usr/lib)，tt(/usr/libexec) が両方候補に入る。
しかし tt(/usr/lib/) としっかり打ってから補完したなら tt(libexec) の方は
入れずに tt(/usr/lib/) で確定させたいなら

example(zstyle ':completion:*:*:less:*' \ 
    accept-exact /usr/lib)

としておく。ただしこうすると，tt(libexec) のほうにあるファイルを
補完させたくて tt(/usr/lib/postf) と打ったとしても tt(/usr/lib) の
部分が確定されてしまっているのでアウト。訳注終わり。

このスタイルは tt(_expand) コンプリータにもつかえ，
その場合チルダか変数名で始まるものを展開するかどうかを決める。
たとえば，変数 tt(foo) と tt(foobar) が定義されていたとして，
`tt($foo)' という単語が(その値に)展開されるのは tt(accept-exact) が
true の場合だけで，そうでないときは tt($foo) を tt($foobar) に
展開する可能性が残される。


また，もし値を `continue' にしておけば，
tt(_expand) は展開結果をマッチとして追加し，補完システムに
継続を許可する。

訳注: tt(_expand) を呼ぶようにしてから実験。
example(zstyle ':completion:*' completer _expand _complete
zstyle ':completion::expand:*' substitute true
foo='This is foo'
foobar='FOOBAR'
echo $foo[Tab]
zstyle ':completion::expand:*' accept-exact continue
)
これは `tt($foo)' と `tt($foobar)' を選ばせる。

example(zstyle ':completion::expand:*' accept-exact true)
これは `tt($foo)' を即確定して展開して完了。

example(zstyle ':completion::expand:*' accept-exact continue)
これは `tt($foo)' を展開したものに加え，
`tt($foobar)' と最初の `tt($foo)' を候補としてメニュー補完する。

訳注終わり。
)
kindex(add-space, completion style)
item(tt(add-space))(
tt(_expand) コンプリータによって使われる。これが true(デフォルト)
のとき，展開の直後にスペース(語がディレクトリ名ならスラッシュ)が
挿入される。また，値として `tt(file)' を代入しておくと
コンプリータは実在するファイルにのみスペースを追加する。
true， `tt(file)' いずれかを持たせる場合，`tt(subst)' を
組み合わせることができ，その場合コンプリータは，
`tt($LPAR()...RPAR())' や `tt(${...})' 置換の展開結果には
空白を足さない。

(訳注: 理屈は分かるがこれもそうならんぞ???

example(zstyle ':completion:*' add-space false)

しても，必ず空白が入るのは何故だ。)

tt(_prefix) コンプリータはこの値を真偽値としてのみ使い，
サフィクスの前に空白をいれるかどうかだけ決める。
)
kindex(ambiguous, completion style)
item(tt(ambiguous))(
補完後の後に / などを補うものがある場合，
メニュー補完では，複数マッチがあったとしてもとりあえず
1つ目のマッチに / を付けて提示するが，このスタイルをセットすると
複数マッチがある場合は一意に決まらない部分にカーソルを戻して提示する(□)。
このスタイルは tt(paths) タグで常に参照される。
)
kindex(assign-list, completion style)
item(tt(assign-list))(
イコール記号の後の値代入の部分で，通常は1つのファイル名だけ補完するが，
このスタイルがセットされている場合はPATH変数のようにコロン区切りの後を
別のファイル名とみなして補完する。スタイルの値はそう補完すべき変数に
マッチするパターンのリスト。

デフォルトでは値にコロンが既に含まれていればONになる。ということで，
これを明示的に指定しなくても快適じゃん。
)
kindex(auto-description, completion style)
item(tt(auto-description))(
1つの引数を取るオプション自身の説明文字列が補完定義に与えられていない
とき，そのオプションの引数の方に説明文字列があればそれオプション自身の
説明として使う。スタイルの値に含ませる tt(%d) がその文字列に
置き換えられる(□)。
)
kindex(avoid-completer, completion style)
item(tt(avoid-completer))(
tt(_all_matches) コンプリータが使用する。
現在挿入すべき単語を生成するときに，使わないコンプリータの
リストを列挙する(□)。

デフォルト値は `tt(_expand _old_list _correct _approximate)' で
全マッチ単語挿入で要らなさそうなものを生成するコンプリータを入れておく(□)。
)
kindex(cache-path, completion style)
item(tt(cache-path))(
補完単語のキャッシュを保存するパス名を指定する。デフォルトは
tt($ZDOTDIR)が定義されている場合は `tt($ZDOTDIR/.zcompcache)'，
そうでない場合は `tt($HOME/.zcompcache)'。ただし，
tt(use-cache) スタイルがセットされていないときは使われない。
)
kindex(cache-policy, completion style)
item(tt(cache-policy))(
キャッシュの再構築をいつするかを決める関数を決める。
後述する tt(_cache_invalid) の項を参照。
)
kindex(call-command, completion style)
item(tt(call-command))(
tt(make)，tt(ant) といった，マッチ単語生成に該当コマンドを直接呼ぶような
もののときに，遅くなったり，tt(make)が実際に仕事を始めちゃったりする
問題を避けるために使われる。trueであれば，実際のコマンドを呼んで
マッチ単語を生成する(場合もある□)。デフォルトは false。
)
kindex(command, completion style)
item(tt(command))(
外部コマンドを呼んでマッチ単語を生成するような多くの補完で使われ，
呼ぶコマンドを変えるために使われる。値を `tt(-)' で始めると
デフォルトのコマンドラインの前に補われる(tt(builtin)や
tt(command) を明示的に前置させたいときに便利)。

たとえば，tt(kill) でPIDを補うときの一覧はpsを呼んで得ているが
このスタイルの値に tt(ps t$TTY) などを入れておけば，現在のTTYの
PIDだけに限定できたりする(□)。
PIDの補完で言えば，実際の補完関数がPID部分を抽出できるよう出力が
関数の期待どおりに得られるよう注意が必要(□)。

コマンドを呼ぶのでそれが短い時間で確実に終わるようにすることにも注意が必要。
訳注: ものすごく変えた。
)
kindex(command-path, completion style)
item(tt(command-path))(
補完のときに用いるコマンド検索の値。デフォルトは tt(path) 変数の値。
)
kindex(commands, completion style)
item(tt(commands))(
OSの初期化スクリプト(\
tt(/etc/init.d) や tt(/etc/rc.d) などにあるもの)
のサブコマンドを補完する関数が使う。それらのスクリプトに与える
サブコマンドの一覧を指定する。デフォルトは `tt(start)' と `tt(stop)'(□)。
)
kindex(complete, completion style)
item(tt(complete))(
tt(_expand_alias) 関数を割り当て可能コマンド(デフォルトで tt(^Xa))
として呼び出したときに使われる。入力した単語に完全にマッチする
エイリアスがなかったときに，(続けてタイプすると)マッチするもの一覧を
出す(□)。
)
kindex(completer, completion style)
item(tt(completer))(
コンプリータとして用いる関数を(文字列で)列挙する。
指定できるコンプリータは
ifzman(後述する `Control Functions' 節)\
ifnzman(noderef(Control Functions))\
参照。

各文字列は，コンプリータ関数，または `var(function)tt(:)var(name)'
という書式が許されている。前者の場合は，コンテクストの
var(completer) フィールドは，その関数の先頭のアンダースコアを取り，
残りのアンダースコア(もしあれば)をすべてハイフンに変えた文字列に
変えた名前になる。後者の場合，var(function) は呼ぶべきコンプリータの
名前となるが，呼ばれるときのコンテクストの var(completer) フィールドは
var(name)となる。ただし，var(name) がハイフンで始まるときは
その前にコンプリータ関数本来のコンテクスト名が追加される(□)。
つまり，

example(zstyle ':completion:*' completer _complete _complete:-foo)

というコンプリータ登録の場合，補完システムは tt(_complete)
コンプリータを2回呼ぶことになり，1回目は
コンテクストの var(completer) フィールド名 tt(complete) で，
2回目はフィールド名 tt(complete-foo) で呼ばれる。

同じコンプリータを2度以上使うなら `var(functions)tt(:)var(name)' の
書式を使って回毎に違うコンテクスト名で呼ばせなければ
意味がない(tt(_ignored) と tt(_prefix) コンプリータに関しては
この限りでない)。

このスタイルのデフォルト値は `tt(_complete _ignored)' で，
「補完」のみを，1回目は tt(ignored-patterns) スタイルと
tt($fignore) 変数の値を考慮して，2回目はそれなしで行なう。
)
kindex(condition, completion style)
item(tt(condition))(
tt(_list) コンプリータがマッチするものの挿入を無条件で遅れさせるか
決めるために使う。デフォルトは `true'(???)。
)
kindex(disabled, completion style)
item(tt(disabled))(
tt(_expand_alias) コンプリータとそのキー割り当て可能コマンド
が使い，`true' の場合は無効化されたエイリアスも補完する。デフォルトは
`false'。
)
kindex(disable-stat, completion style)
item(tt(disable-stat))(
tt(_cvs) 関数がタグなしでこの値を用いて，
相応の場所にある修正ファイルを生成するために tt(zsh/stat) モジュールを
使うかどうかを決める。`trule' ならモジュールを使わず
tt(ls) コマンドを使う。
)
kindex(domains, completion style)
item(tt(domains))(
補完に使うネットワークドメイン名のリスト。セットされていない場合は
tt(/etc/resolv.conf) ファイルから取得される。
)
kindex(expand, completion style)
item(tt(expand))(
このスタイルは，パス名のように複数の部分から成っている文字列を
補完するときに使われる。

この値のうち1つが `tt(prefix)' という文字列であれば(完全一致)，
後半部分が補完できなくても前半部分が補完できるならできるだけ
展開される。訳注: たとえば，tt(/u/i/hoge) を補完するとき tt(/u*/i*/hoge*)
がなくても tt(/u*/i*) で補完できるなら tt(/usr/include/hoge) に
展開する。

この値のうち1つが `tt(suffix)' という文字列であれば(完全一致)，
途中に一意に定まらない部分があったとしても，その後ろにある
部分にマッチする名前が足される。これにより結果の文字列は，
一意に定まる前の最長の文字列となる。このとき，メニュー補完を
用いてマッチするものすべてを循環させることもできる。訳注: 
tt(/home) 以下に tt(yuka)，tt(yukita)，tt(yuuji) ディレクトリがあり，
それぞれに tt(.z) で始まるファイルとして tt(.zshenv)，tt(.zshrc) がある
とする。このときに tt(/h/y/.z) で tt(complete-word) すると，
suffix でないときは tt(/home/yu) までが補完されるが，
suffix のときは tt(.z) の部分も頑張って tt(/home/yu/.zsh) に
展開される。
)
kindex(fake, completion style)
item(tt(fake))(
どのコンテクストでも使えるスタイル。指定したコンテクストで
必ず追加で補完対象に含まれるような文字列を指定する。
指定する値は `var(value)tt(:)var(description)' の形式で記述し，
コロンの後ろに説明文字列を書く(コロンを含めて省略可能)。
説明文字列にコロンを入れたいときはバックスラッシュでクォートする。
説明文字列は補完リスト表示のときに出される。

どこでも呼ばれる可能性があるので，コンテクスト指定を十分に限定的に
することが大切。ファイル名や変数名で似たような追加候補を入れたいときに
ついては tt(fake-files) や tt(fake-parameters) 参照のこと。
訳注: とにかく決まった単語を決まったコマンドの補完で
使いたいときに便利なスタイル。
)
kindex(fake-always, completion style)
item(tt(fake-always))(
tt(fake) スタイルと同じ働きだが，tt(ignored-patterns) スタイルを
適用しない点だけ異なる。無視するパターンを `tt(*)' に
セットすることでマッチ単語群を完全にオーバーライドすることができる。
This works identically to the tt(fake) style except that
the tt(ignored-patterns) style is not applied to it.  This makes it
possible to override a set of matches completely by setting the
ignored patterns to `tt(*)'.

以下に，単に分割タグのように表示のためだけに用いる勝手なデータをもつ
任意のタグを補わせる方法を示す。この例では，tt(tag-order) スタイルを
使って，標準コンプリータの tt(complete) が tt(cd) コマンドの引数を
補完するときに tt(named-directories) タグを2回に分けて呼んでいる。

tt(named-directories-normal) タグは普通に候補を持つが
tt(named-directories-mine) タグは自分のおきまりのディレクトリ群だけを
候補に持つようにしている。

tt(named-directories-mine) contains a fixed set of directories.
This has the effect of adding the match group `tt(extra directories)' with
the given completions.

example(zstyle ':completion::complete:cd:*' tag-order \ 
  'named-directories:-mine:extra\ directories
  named-directories:-normal:named\ directories *'
zstyle ':completion::complete:cd:*:named-directories-mine' \ 
  fake-always mydir1 mydir2
zstyle ':completion::complete:cd:*:named-directories-mine' \ 
  ignored-patterns '*')

訳注: んでもこれを fake-always から fake にしても違いが分からないのだが……
)
kindex(fake-files, completion style)
item(tt(fake-files))(
このスタイルはファイルの補完に使われ，タグなしで参照される(△)。
値は `var(dir)tt(:)var(names...)' の形式で指定し，
var(names)(複数ある場合は空白で区切る)という名前のファイル(群)が
var(dir) に(実在しなくても)あるものして候補に含める。

これはたとえばオートマウントディレクトリ(□)のようにアクセスするまで
一覧に出てこないパス名の補完や，xビットだけあってrビットがない
ディレクトリにある読みだし可能ファイルの名前を補完したいときに便利。

訳注: たとえば，a2ps や psnup の結果をほとんどの場合
tt(/tmp/hoge.ps)，tt(/tmp/hoge2.ps)，tt(/tmp/hoge3.ps)，… に
リダイレクトで書き出しているような場合，既存のファイルがなくても
tt(>) のあとに tt(/tmp/hoge.ps) を補完させたい。そのようなときは，

example(zstyle ':completion::*:-redirect-,>,(a2ps|psnup):*' \ 
  fake-files "/tmp:hoge.ps `echo hoge{2..9}.ps`")

と設定しておくと，tt(a2ps foo > ) の後ろで tt(/tmp/hoge.ps) などが
補完候補となる。
)
kindex(fake-parameters, completion style)
item(tt(fake-parameters))(
変数名を補完する関数で使われる。
値には，まだ未定義でも補完候補に入れる変数名を列挙する。
指定する名前にはコロンに続けて変数の型(`tt(scalar)'，`tt(array)'，
`tt(integer)'等)を補助的に追記できる。型を与えておくと
その型が要求されているコンテクストでのみその変数が補完される。
型指定のない変数は常に補完される。
)
kindex(file-list, completion style)
item(tt(file-list))(
このスタイルは，標準の機構を用いて得られた補完候補ファイル群を
一覧表示するときに，tt(ls -l)に似たロングリスト出力とするかどうかを
決める。この機能はファイルの情報を得るために
シェルモジュール tt(zsh/stat) を使用する。このモジュールは
外部コマンドの tt(stat) より優先されることになるが，
それを避けたい場合は

example(zmodload -i zsh/stat
disable stat)

と初期化ファイルに書いておくとよい。

このスタイルに設定できる値は，true(または `tt(all)'):
あらゆる状況でロングフォーマットで出す，
`tt(insert)': ファイル名を挿入するとき，
`tt(list)': ファイル名を挿入せずに一覧を出すとき，
のいずれか(△どう使いわけるのかいまいち)。

厳密には(□)，この値は上記の値のどれかに，オプションで
tt(=)var(num) を付けたもの，を配列にしたものにしてよい。
var(num) は，ロングフォーマット表示にする場合の最大マッチ数を表す。
たとえば，

example(zstyle ':completion:*' file-list list=20 insert=10)

とすると，マッチするものが20個までなら一覧出力をロングフォーマットにし，
10個までなら挿入する(あいまい補完の例のように一覧がallで
出るようになってるものと見なす(△何???))。
また，

example(zstyle -e ':completion:*' file-list '(( ${+NUMERIC} )) && reply=(true)')

とすると，数引数を付けて呼び出した場合に常にロングフォーマット，
そうでないときショートフォーマットが使われる。
(訳注: △△ほんにわからん)
)
kindex(file-patterns, completion style)
item(tt(file-patterns))(
標準ファイル名補完関数である tt(_files) が使用する。
このスタイルがセットされていない場合は，最大で3つの
タグ，`tt(globbed-files)'，`tt(directories)'，`tt(all-files)'
が， tt(_files) の呼び主の求めているファイル種別に応じて渡される。
最初の2つ，`tt(globbed-files)'，`tt(directories)' は，
通常いっしょに渡されて，サブディレクトリ内のファイルを簡単に
補完できるようにしている。

tt(file-patterns) スタイルは，デフォルトタグ(通常は使われない)の
代わりのものを生み出すために使える(△□)。
このスタイル値は，`var(pattern)tt(:)var(tag)' という要素の集合で，
各要素は同じ形式の要素をスペースで区切って列挙したものでも構わない(□)。

var(pattern) はファイル名生成を行なうために使われる。
`tt(%p)' と書くとその部分が tt(_files) 関数に渡された
パターン+LPAR()群+RPAR() に置き換えられる。パターンにコロン自身が含まれる
ときはバックスラッシュでエスケープする必要がある。複数のパターンを
書く必要があるときはそれらのパターン全体を確固で括って，その中に
パターンをカンマで区切って書けばよい。


var(tag)の部分で指定されたタグ群は，tt(_files)によって別のスタイルを
照合するときに渡される。別のパターンに同じタグ値を指定したとき，
それらは同時に渡される(△)。`tt(:)var(tag)' を省略したときは
`tt(files)' タグが使われる。

var(tag) 指定のさらに後ろにさらにコロンを付けて説明文字列を追記する
こともできる。説明文字列を定義しておくと，補完関数のデフォルトの
説明の代わりに， tt(format) スタイルの `tt(%d)' に置き換えられる。
説明文字列自身に `tt(%d)' を入れておくと，それは補完関数のデフォルトの
説明文字列に置き換えられる。

たとえば，tt(rm) コマンドの引数の補完で，最初はオブジェクトファイルだけ
補完を試み，マッチしない場合のみすべてのファイルを補完したい場合は
以下のようにする。

example(zstyle ':completion:*:*:rm:*' file-patterns \ 
    '*.o:object-files' '%p:all-files')

デフォルトの補完機能の挙動，すなわち，
パターンに位置するものと，
(パターンとは無関係の)ディレクトリを最初に，その後ですべてのファイルを
提示する，という挙動を，
「最初にパターンにマッチするものだけ提示し，そのあとで
ディレクトリとすべてのファイルを…」と変えたい場合は

example(zstyle ':completion:*' file-patterns \ 
    '%p:globbed-files' '*(-/):directories' '*:all-files')

と指定すればよい。

This works even where there is no special pattern: tt(_files) matches
all files using the pattern `tt(*)' 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.

補完関数実行時には，tt(EXTENDED_GLOB) オプションがセットされるので，
パターン中に`tt(#)'，`tt(~)' や `tt(^)' などがあれば，それらは特別な
働きをする。
)
kindex(file-sort, completion style)
item(tt(file-sort))(
標準ファイル補完関数が，候補一覧表示の出力順を決めるためにこのスタイルを
タグなしで使用する。メニュー補完も同じ順番となる。
設定できる値は，
`tt(size)': ファイルサイズでソート，
`tt(links)': リンクカウントでソート，
`tt(modification)'(`tt(time)' または `tt(date)'): 修正時刻でソート，
`tt(access)': 最終アクセス時刻でソート，
`tt(inode)'(`tt(change)'): inode情報更新時刻でソート，のどれか。

上記の値以外，またはセットされていないときはファイル名でソートし，
値に `tt(reverse)' という文字列を含む場合は逆順でソートする。
)
kindex(filter, completion style)
item(tt(filter))(
訳注: 急いでるので飛ばします。

This is used by the LDAP plugin for e-mail address completion to specify
the attributes to match against when filtering entries.  So for example, if
the style is set to `tt(sn)', matching is done against surnames.  Standard
LDAP filtering is used so normal completion matching is bypassed.  If this
style is not set, the LDAP plugin is skipped.  You may also need to set the
tt(command) style to specify how to connect to your LDAP server.
)
kindex(force-list, completion style)
item(tt(force-list))(
一覧出力が普通なら抑制されるようなときでも，必ず一覧出力を強制実行する。

たとえば，通常一覧出力はマッチするものが2個以上ある場合に出てくる
(訳注: tt(AUTOLIST) オプションが有効(デフォルト)の状態で
tt(complete-word) した場合など)。このスタイルを
`tt(always)' にセットすると，たとえマッチするものが1個であっても
一覧出力する。スタイル値に整数を指定すると，マッチするものの
個数がその数以上になったときに，たとえそれらが同じ文字列を挿入する
場合でも一覧出力される(△訳注:それってどういうときなの???)
In this case the list will be shown if there are
at least that many matches, even if they would all insert the same
string.

このスタイルはデフォルトタグだけでなく，現在の補完で有効な各タグで
確かめられる。
)
kindex(format, completion style)
item(tt(format))(
tt(descriptions) タグに対してこのスタイルが設定されているとき，
その値は一覧出力の上に表示される。
値の文字列中の `tt(%d)' は，マッチ対象に対する短い説明文に置き換えられる。
他に，`tt(%B)'，`tt(%S)'，`tt(%{)...tt(%})' も使える。

現在の補完で有効なすべてのタグで確かめられ，そのあとで
tt(descriptions) タグに対して確かめられる。これにより
違う種類の補完対象には違う書式文字列を定義できる。

また，もっと多くの `tt(%)' 記法が使えるコンプリータもあり，
その場合はそのコンプリータ関数の
Note also that some completer functions define additional
`tt(%)'-sequences.  These are described for the completer functions that 
make use of them.

いくつかの補完関数では，tt(messages) タグに対するこのスタイル値を
設定することで表示メッセージを変更できる(その場合 `tt(%d)' は
補完関数により出されるメッセージに置換される)。

tt(warnings) タグに対するこのスタイル値は，マッチするものがなかった場合に
参照される。その場合，`tt(%d)' はマッチが期待されたものに対する
説明をスペースで区切って並べたものに置き換えられる(△どういうとき??)。
`tt(%D)' は同じ説明をスペースではなく改行で区切って並べたものに
置き換えられる。

`tt(%d)' にprintf風の桁幅指定や，エスケープシーケンスが使うこともできる。
tt(zsh/zutil) モジュールで定義されている内部コマンドの tt(zformat) によって
処理される。
ifzman(zmanref(zshmodules))\
ifnzman(noderef(The zsh/zutil Module))\
参照.
)
kindex(glob, completion style)
item(tt(glob))(
tt(_expand) コンプリータで使われる。
この値が `true'(デフォルト値) のときは直前の置換の結果に対して
さらにグロッビングを試みる(tt(substitute)スタイルも参照)(△□)。
)
kindex(global, completion style)
item(tt(global))(
tt(_expand_alias) コンプリータとそのキー割り当て可能コマンドが，
グローバルエイリアスを展開するかどうかを決める。デフォルトは
`true'。
)
kindex(group-name, completion style)
item(tt(group-name))(
補完システムでは別の種類のマッチ対象をグループごとに分けて一覧出力
することができる。このスタイルを用いてタグごとに別々のグループ名を
付けられる。たとえば，コマンドラインのコマンド位置で補完させると，
シェル内部コマンド，外部コマンド，エイリアス，シェル関数，
(代入のための)変数名，が有効な補完対象として生成される。ここで，
外部コマンドとシェル関数を候補一覧表示で分けたい場合にはこうする:

example(zstyle ':completion:*:*:-command-:*:commands' group-name commands
zstyle ':completion:*:*:-command-:*:functions' group-name functions)

これで，同じタグを持つものが同じグループ内に表示される。

グループ名を持たないすべてのマッチ対象は tt(-default-) という名前の
グループに入れられる(訳注: 次の文の下にあったがここに移動した)。

グループ名に空文字列を指定すると，マッチ対象のタグ名がグループ名に
使われる。したがって，すべてのマッチ種別を別々に表示させたいなら

example(zstyle ':completion:*' group-name '')

としておくとよい。

訳注: これを試すときには，

example(zstyle ':completion:*:descriptions' format '%BCompleting%b %U%d%u')

などとしておくと効果が分かりやすい。
)
kindex(group-order, completion style)
item(tt(group-order))(
tt(group-name) スタイルと併せて使い，分類されたグループの一覧出力での
順番を指定する(補完そのものを決める tt(tag-order) と比較せよ□)。
名前を持つグループは指定した順番で表示され，
その他のものは補完関数で定義された順番で表示される。

たとえば，コマンド位置で補完したときに内部コマンド，シェル関数，
外部コマンドをその順番で一覧に出したいなら下記のようにする。

example(zstyle ':completion:*:*:-command-:*' group-order \ 
       builtins functions commands)
)
kindex(groups, completion style)
item(tt(groups))(
UNIXのグループ名のリスト。セットされていなければ
YPデータベース，または `tt(/etc/group)' から取得される。
)
kindex(hidden, completion style)
item(tt(hidden))(
この値が `true' のときは，指定したコンテクストで
マッチしたものは一覧表示されなくなる。ただし，
そのマッチに対して tt(format) スタイルでセットされた説明文は表示される。
説明文も出さないようにするにはこのスタイル値を `tt(all)' に設定する。

ただし，一覧表示が出されないだけで補完はされる。
補完対象からも外したいときは後述の tt(tag-order) スタイルを
いじることで調整できる(□)。
)
kindex(hosts, completion style)
item(tt(hosts))(
補完に現れるべきホスト名のリスト。この値をセットしていない場合，
ホスト名は `tt(/etc/hosts)' から取得される
)
kindex(hosts-ports, completion style)
item(tt(hosts-ports))(
ホスト名とネットワークポート番号を受け取るコマンドの
引数補完で使用される。値は
`var(host)tt(:)var(port)' の形式で指定する。
有効なポートはホスト名の有無によって決められる。同じホストに
複数のポートが現れてよい(△訳注: どこで使われるか分からん。telnetは
違うみたいだ)。
)
kindex(ignore-line, completion style)
item(tt(ignore-line))(
このスタイルは現在の補完で有効なすべてのタグについて調べられる。
もし設定値が `tt(true)' の場合は，候補対象のうち既にコマンドラインに
入力されているものは除外される。`tt(current)' の場合は現在入力中の単語
に完全一致するものは補完候補から除外する
(訳注: tt(foo)，tt(foobar)，tt(foobaz) があるとして，
tt(foo) まで打ってからTAB押すなら，もう全部打っちゃった
tt(foo) は補完されてもうれしくない)。
`tt(current-shown)' は `tt(current)' とほぼ同じだが，入力中の単語に
マッチするもの一覧が表示されている場合のみ完全一致する候補を除外する。
`tt(other)' はコマンドラインにあるカーソル位置以外の単語を
補完候補から除外する。

ちなみに，tt(accept-exact) スタイルは，既に打ったものに完全一致する
パスコンポーネントは確定，という意味で，既に打ったものに完全一致する
のは除外する `tt(current)' と `tt(current-shown)' はちょうどこれの
逆みたいな感じになっている(□)。

便利な局面が多いこのスタイルだが，`tt(:completion:*)' のような
広範囲に及ぶコンテクストで `tt(true)' や `tt(other)' を
設定するのはうれしくないだろう。なぜなら，たとえばあるコマンドに対して
同じオプションを複数回指定したいときに，2回以降が補完できなくなって
しまうからである。
)
kindex(ignore-parents, completion style)
item(tt(ignore-parents))(
このスタイルはパス名補完を行なう関数からタグなしで照合され，
ディレクトリ名を補うときに，現在の単語に含まれている場所や
カレントディレクトリを除外するかを決める。設定できる値は
下記の1つ，または2つ両方。

startitem()
item(tt(parent))(
入力中の単語に含まれるディレクトリは無視する。たとえば，
tt(foo/../) で補完するなら，すでに tt(foo) が含まれているのでこれを
除外する。
)
item(tt(pwd))(
カレントディレクトリを除外する。たとえば，
tt(../) で補完するとき，カレントディレクトリ以外のものを候補とする。
)
enditem()

上記の値に加えて，さらに以下のどちらか，または両方を含めることもできる。

startitem()
item(tt(..))(
補完中の単語が `tt(../)' を含む場合のみ該当するディレクトリを無視する。
)
item(tt(directory))(
対象をディレクトリに限定して補完しているときだけ該当ディレクトリを
無視する。ディレクトリに限定していないときは無視しない。訳注:
tt(zstyle)や補完システムで，その引数を tt("*(-/)") で検索している
場合のみ該当ディレクトリを無視させる。例:

example(zstyle ':completion:*:*:foo:*' \ 
  ignore-parents pwd directory
zstyle ':completion:*:*:foo:*' \ 
  file-patterns '*(-/)')

2行目のあるなしで挙動が変わる。訳注終わり。
)
enditem()

除外指定された値は，下記 tt(ignored-patterns) スタイルと
同様，tt(_ignored) コンプリータで候補として復活する(訳注:
つまり除外指定したものしかマッチするものがなければ復活して選ばれる)。
)
kindex(ignored-patterns, completion style)
item(tt(ignored-patterns))(
補完対象から除外したいパターンのリスト。
とはいえ，これで指定したパターンにマッチする候補が完全に捨てられるわけ
ではなく，それらを復活させるために tt(_ignored) コンプリータを
tt(completer) スタイルに追加しておくこともできる。
このスタイルは，シェル変数 tt($fignore) の柔軟バージョンといえる。

補完関数実行時には，tt(EXTENDED_GLOB) オプションがセットされるので，
パターン中に`tt(#)'，`tt(~)' や `tt(^)' などがあれば，それらは特別な
働きをする。
)
kindex(insert, completion style)
item(tt(insert))(
tt(_all_matches) コンプリータが，
たんに別のマッチに一覧を足すのではなく，
マッチする単語すべてを挿入するかを決める。

訳注: 以下の例で。

zle -C all-matches complete-word _generic
bindkey '^Xa' all-matches
zstyle ':completion:all-matches:*' completer _all_matches _complete
zstyle ':completion:all-matches:*' insert true

訳注終わり。
)
kindex(insert-ids, completion style)
item(tt(insert-ids))(
tt(kill) や tt(wait) 内部コマンドの引数などでプロセスIDを補完するときに，
コマンドの名前は適切なプロセスIDに変換されうる。
このとき，プロセス名が一意に定まらないと問題が起きる。

訳注: tt(kill) などの後ろにコマンド名を打ってTABを押すと
補完関数は tt(ps) コマンドなどの出力からそのコマンド名にマッチする
PIDを引いて来て，一意に定まる前にすぐコマンドライン上の単語をPID数値に
書き換えてしまい，メニュー補完を始めて次のTABキーでマッチするPIDを
循環させる。普段メニュー補完を使っていない人は，マッチするものが
最初に出てくると一意に決まったのかと思ってすぐリターンを押してしまい
やすく，危険である。この挙動はこのスタイル値が未定義か，`tt(menu)' に
セットされているものである。訳注終わり。


このスタイル値を `tt(single)' にすると，一意に定まるまでは
コマンドライン上のコマンド名をPIDに書き換えない(□)。それ以外の
単語にしておくと，ユーザの入力が対応するIDに共通なプレフィクスより長く
なってからメニュー補完が始まる(訳注: どうもそうはならない感じだなあ???)。
)
kindex(insert-tab, completion style)
item(tt(insert-tab))(
この値が `true' のとき，カーソルの左側に非空白文字がない状態で
TABキーを押すと，補完を始める代わりにTAB文字を挿入する。
`false' ならそのような場所でも補完を行なう。

値として `tt(pending)' または `tt(pending=)var(val)' を設定することもでき，
その場合処理待ちの入力がある場合には補完でなくTAB文字を挿入する。
var(val)を指定した場合は，入力待ちの文字数の閾値を設定できる(□)。
これはTAB文字を含むものを端末にペーストするときに便利である。
ただしこれは tt(zsh/zle) モジュールで定義される tt(PENDING) 変数
の値を頼りにしているが，これはすべてのプラットフォームで正確に
設定されるとは限らない点に注意されたい。

デフォルトは `true' だが，内部コマンド tt(vared) の中では `tt(false)' である。
)
kindex(insert-unambiguous, completion style)
item(tt(insert-unambiguous))(
tt(_match) と tt(_approximate) コンプリータで使われる。
これらのコンプリータは既入力文字列が補完結果と似通う部分がほとんど
なくなることもあるので，メニュー補完に移行することが多い。

しかし，このスタイルを `true' にするとコンプリータは，
最低限ユーザが入力したのと同じ文字数だけの
あいまいでない初期文字列がみつからない限りメニュー補完には移行しない。
(訳注: この項目末尾に詳細追記)

tt(_approximate) コンプリータの場合は，
コンテクストの var(completer) フィールドは
既に tt(correct-)var(num) または tt(approximate-)var(num)
(var(num)は許容エラー数)のどちらかがセットされている。

tt(_match) コンプリータの場合は，
このスタイル値を `tt(pattern)' にすることもでき，その場合
コマンドライン上のパターンはあいまいさなくマッチしなければ，
そのままにされる。

訳注: tt(zstyle ':completion:*' completer _expand 
_complete _match _approximate) などとして tt(_match)，tt(_approximate)
が使われるようにしておく。カレントディレクトリに 
tt(MACHINES)，tt(META-FAQ)，tt(config.sub)，tt(configure)
がある状態で tt(MAT) だけ入力してTABすると tt(MACHINES) と
tt(META-FAQ) で循環するメニュー補完に突入する。また，tt(cinf) まで
打ってTABすると，tt(config.sub) と tt(configure) で循環する
メニュー補完に突入する。しかし，

example(zstyle ':completion:*' \ 
    insert-unambiguous true)

すると，tt(MAT) のほうは3文字のままインクリメンタル補完にはできないので
メニュー補完に突入するが，tt(cinf) のほうは，tt(conf) に直せば
tt(config)まで補完してインクリメンタル補完が続けられるので
メニュー補完には移行しない。
訳注終わり。
)
kindex(keep-prefix, completion style)
item(tt(keep-prefix))(
tt(_expand) コンプリータで使われる。`true' のときは
チルダや変数展開を含むプレフィクスを保とうとする。
ゆえに，たとえば，`tt(~/f*)' は `tt(/home/user/foo)' ではなく，
`tt(~/foo)' に展開される。スタイル値を `tt(changed)'(デフォルト値) にすると，
プレフィクスは，展開結果とコマンドラインの元の文字列に別の変更があった場合
だけ変更されない。その他の値を設定するとプレフィクスを無条件で展開する。

スタイル値が true のときの tt(_expand) の挙動によって，
1回展開したものがプレフィクスの復元で元と同じになってしまった場合には
tt(_expand) を中止し，その結果残りのコンプリータが呼ばれることになる
場合がある。
)
kindex(last-prompt, completion style)
item(tt(last-prompt))(
シェルオプション tt(ALWAYS_LAST_PROMPT) の，より柔軟なバージョン。
この値が `true' だと，補完システムは一覧表示したのち，
最初のコマンドライン位置に戻ろうとする。
このスタイルは現在の補完で有効なすべてのタグについて調べられ，そののち
デフォルトタグで調べられる。カーソルを戻すのはそのスタイルがすべて
`true' だった場合。
ただし，tt(ALWAYS_LAST_PROMPT) と違い，数引数の影響を受けない点が異なる
点に注意。
)
kindex(known-hosts-files)
item(tt(known-hosts-files))(
sshの tt(known_hosts) ファイルと互換性のある書式で書かれた
ホスト名とIPアドレス(tt(use-ip)スタイルがセットされている場合)
を探すために使われるファイルのリスト。セットされていない場合は
tt(/etc/ssh/ssh_known_hosts) と tt(~/.ssh/known_hosts) が
用いられる。
)
kindex(list, completion style)
item(tt(list))(
キー割り当て可能コマンド tt(_history_complete_word) によって使われる。
`true' にセットされている場合はとくに効果がない。
`false' にセットされているとマッチするものが一覧表示されなくなる。
これは，一覧表示機能を制御するオプション，とくに tt(AUTO_LIST)
をオーバーライドする。コンテクストは常に
`tt(:completion:history-words)' で始まる。
)
kindex(list-colors, completion style)
item(tt(list-colors))(
tt(zsh/complist) モジュールがロードされている場合に，
このスタイルは色付け指定として使われる。

ifzman(zmanref(zshmodules) の `The zsh/complist Module' 節)\
ifnzman(noderef(The zsh/complist Module))\
で解説されている tt(ZLS_COLORS) と tt(ZLS_COLOURS) 変数の利用を置き換えるが
ただし文法は同じである。
(訳注: 初期化ファイルに古い tt(ZLS_COLROS) や tt(ZLS_COLOURS) の
設定があってもunsetされ，補完システムの tt(list-colors) が優先される。)


このスタイルが tt(default) タグに対してセットされていると，
その値はすべての場所で使われるものと見なされる。
他のタグに対してセットされていれば，そのタグによって決まる補完対象
のみの設定になる。この使いわけをうまく活用するには，
tt(group-name) スタイルに空文字列を設定しておく。

上述のタグごとの固有スタイル設定だけでなく，
tt(group-name)タグで明示的に指定されたグループ名を使うこともできる。
それには tt(ZLS_COLORS) や tt(ZLS_COLOURS) 変数で許されている
`tt((group))' 記法と tt(default) タグの使用を組み合わせる(△
訳注: 試したけどよう分からん)。

comment(
it is also possible to
use group names specified explicitly by the tt(group-name) tag together
with the `tt((group))' syntax allowed by the tt(ZLS_COLORS) and
tt(ZLS_COLOURS) parameters and simply using the tt(default) tag.
)

GNU tt(ls) 用に設定してある設定を使うこともできる。それには以下のようにする。

example(zstyle ':completion:*:default' list-colors ${(s.:.)LS_COLORS})

(訳注: (s.:.) でコロン区切りをsplitしている)

デフォルトの彩色は GNU tt(ls) コマンドと同じで，それを望む場合は
スタイル値に空文字列を設定すればよい。
)
kindex(list-grouped, completion style)
item(tt(list-grouped))(
`true' (デフォルト) にセットすると補完システムは一覧表示を
グルーピングマッチを利用してよりコンパクトにしようと試みる。
たとえば，コマンドに対するオプションの説明文字列(tt(verbose)スタイルが
`true' のときに表示される)が同じものどうしは1つのエントリとして出現する。
(訳注: 導入以後 `false' に戻ることもなさそうだからこのスタイルは
気にしなくてよかろう)
)
kindex(list-packed, completion style)
item(tt(list-packed))(
tt(default) タグに加えて，現在のコンテクストで有効なタグすべてで
調べられる。`true' にセットされていると tt(LIST_PACKED) オプションが
セットされているかのように一覧表示される。`false' は普通どおり。
)
kindex(list-prompt, completion style)
item(tt(list-prompt))(
tt(default) タグに対して設定されていると，候補一覧表示のときに
画面からあふれるときに1画面ごとにプロンプトを出して止まる。
スタイル値に空でない文字列が設定されているとその文字列が
プロンプトとして用いられる。
(\
ifzman(tt(zsh/complist) モジュール(zmanref(zshmodules)))\
ifnzman(noderef(The zsh/complist Module))\
も参照).

値には `tt(%)' で始まるエスケープシーケンスも使える。
`tt(%l)' または `tt(%L)' は，表示されている最後の行数/全行数。
`tt(%m)' または `tt(%M)' は，表示されている最後の項番/全項目数。
`tt(%p)' または `tt(%P)' は，表示されている位置のパーセンテージ
(先頭なら `tt(Top)'，末尾なら `tt(Bottom)')に置き換えられる。
いずれの場合も小文字の方はプロンプト表示幅が変動するが，
大文字の方は右側にスペースを詰めた固定幅になる。
`tt(%S)' と `tt(%s)' は強調，強調解除，
`tt(%B)' と `tt(%b)' は太字，太字解除,
`tt(%U)',と `tt(%u)' は下線，下線解除に使える。
`tt(%{)...tt(%})' はエスケープシーケンスを表示幅0と見なすために括る。

プロンプトを出すのをやめるには
tt(zstyle -d) してこの値を削除するだけではだめで，変数 tt(LISTPROMPT)
を unset する必要がある。
)
kindex(list-rows-first, completion style)
item(tt(list-rows-first))(
tt(list-packed) スタイルと同じように調べられ，
tt(LIST_ROWS_FIRST) オプションと同様，補完一覧表示を横進みにする。
(訳注: デフォルトの一覧表示は tt(ls) と同じ縦進み)
)
kindex(list-suffixes, completion style)
item(tt(list-suffixes))(
ファイル名補完を行なう関数で使われる。
`true' にセットすると，補完を既に入力された複数のパスコンポーネントを含めた
文字列に対して行なわれ，一意に定まらないコンポーネントが表示される。
セットしないと補完は最初のあいまいなパスコンポーネントで止まる。
)
kindex(list-separator, completion style)
item(tt(list-separator))(
訳注: スタイルはいったんやめて次のセクション行きます。
The value of this style is used in completion listing to separate the
string to complete from a description when possible (e.g. when
completing options).  It defaults to `tt(-)tt(-)' (two hyphens).
)
kindex(local, completion style)
item(tt(local))(
This is for use with functions that complete URLs for which the
corresponding files are available directly from the filing system.
Its value should consist of three strings: a
hostname, the path to the default web pages for the server, and the
directory name used by a user placing web pages within their home
area.

For example:

example(zstyle ':completion:*' local toast \ 
    /var/http/public/toast public_html)

Completion after `tt(http://toast/stuff/)' will look for files in the
directory tt(/var/http/public/toast/stuff),  while completion after
`tt(http://toast/~yousir/)' will look for files in the directory
tt(~yousir/public_html).
)
kindex(mail-directory, completion style)
item(tt(mail-directory))(
If set, zsh will assume that mailbox files can be found in
the directory specified.  It defaults to `tt(~/Mail)'.
)
kindex(match-original, completion style)
item(tt(match-original))(
This is used by the tt(_match) completer.  If it is set to
tt(only), tt(_match) will try to generate matches without inserting a
`tt(*)' at the cursor position.  If set to any other non-empty value,
it will first try to generate matches without inserting the `tt(*)'
and if that yields no matches, it will try again with the `tt(*)'
inserted.  If it is unset or set to the empty string, matching will
only be performed with the `tt(*)' inserted.
)
kindex(matcher, completion style)
item(tt(matcher))(
このスタイルはカレントコンテクストでの正当なタグすべてで
独立に参照される。この値は tt(matcher-list) で設定されているマッチ仕様に
追加される。書式は
ifzman(zmanref(zshcompwid) の `Matching Control' 節)\
ifnzman(noderef(Matching Control))\
参照。
)
kindex(matcher-list, completion style)
item(tt(matcher-list))(
このスタイルにはすべての場所で適用されるマッチ仕様を設定する。
マッチ仕様については
ifzman(zmanref(zshcompwid) の `Matching Control' 節)\
ifnzman(noderef(Matching Control))\
参照。
このスタイルには(シェルの)単語的に複数の値を設定でき，
選択されたコンプリータで順次この値を適用する。
たとえば，もし，普通のマッチングを行なってそれで見つからなければ
始めて大文字小文字無視でマッチさせる補完をさせたければ，

example(zstyle ':completion:*' matcher-list '' 'm:{a-zA-Z}={A-Za-z}')

のようにする。デフォルトでは2つ目以降の仕様指定はそれ以前のものを
上書きするが，指定の先頭に tt(+) を付けると追加する。これにより
重複なしで徐々にマッチング規則を緩くしていくのが可能となっている。
たとえば，

example(zstyle ':completion:*' matcher-list '' '+m{a-Z}={A-Z}' '+m{A-Z}={a-z}')

とすると，最初は，文字そのままでマッチさせ，
それでだめなら小文字を大文字に変換してマッチ，
それでもだめなら小文字を大文字に変換することも追加で行なってマッチ，
という風になる。
特定のコンプリータだけにマッチ仕様の指定を行なうこともでき，その場合は
コンテクスト第3フィールド(つまりcompleterの位置)にそのコンプリータを
書けばよい。たとえば，
tt(_complete) コンプリータと tt(_prefix) コンプリータを使っている場合で，
tt(_complete) コンプリータだけに大文字小文字無視マッチを適用させたいなら，

example(zstyle ':completion:*' completer _complete _prefix
zstyle ':completion:*:complete:*' matcher-list \ 
       '' 'm:{a-zA-Z}={A-Za-z}')

のようにする。
User-defined names, as explained for the tt(completer) style, are
available.  This makes it possible to try the same completer more than
once with different match specifications each time.  For example, to try
normal completion without a match specification, then normal completion
with case-insensitive matching, then correction, and finally
partial-word completion:

example(zstyle ':completion:*' completer _complete _correct _complete:foo
zstyle ':completion:*:complete:*' matcher-list \ 
    '' 'm:{a-zA-Z}={A-Za-z}'
zstyle ':completion:*:foo:*' matcher-list \ 
    'm:{a-zA-Z}={A-Za-z} r:|[-_./]=* r:|=*')

If the style is unset in any context no match specification is applied.
Note also that some completers such as tt(_correct) and tt(_approximate)
do not use the match specifications at all, though these completers will
only ever called once even if the tt(matcher-list) contains more than
one element.

Where multiple specifications are useful, note that the em(entire)
completion is done for each element of tt(matcher-list), which can
quickly reduce the shell's performance.  As a rough rule of thumb,
one to three strings will give acceptable performance.  On the other
hand, putting multiple space-separated values into the same string does
not have an appreciable impact on performance.
)
kindex(max-errors, completion style)
item(tt(max-errors))(
This is used by the tt(_approximate) and tt(_correct) completer functions
to determine the maximum number of errors to allow.  The completer will try
to generate 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 `tt(numeric)', the 
completer function will take any numeric argument as the
maximum number of errors allowed. For example, with

example(zstyle ':completion:*:approximate:::' max-errors 2 numeric)

two errors are allowed if no numeric argument is given, but with
a numeric argument of six (as in `tt(ESC-6 TAB)'), up to six
errors are accepted.  Hence with a value of `tt(0 numeric)', no correcting
completion will be attempted unless a numeric argument is given.

If the value contains the string `tt(not-numeric)', the completer
will em(not) try to generate corrected
completions when given a numeric argument, so in this case the number given
should be greater than zero.  For example, `tt(2 not-numeric)' specifies that
correcting completion with two errors will usually be performed, but if a
numeric argument is given, correcting completion will not be
performed.

The default value for this style is `tt(2 numeric)'.
)
kindex(max-matches-width, completion style)
item(tt(max-matches-width))(
This style is used to determine the trade off between the width of the
display used for matches and the width used for their descriptions when
the tt(verbose) style is in effect.  The value gives the number of
display columns to reserve for the 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.
)
kindex(menu, completion style)
item(tt(menu))(
現在の補完で定義されているタグのコンテクストで，この値が
`true' のときはメニュー補完が用いられる。タグつきで指定されている
値は，`tt(default)' タグのものよりも優先する。

If none of the values found in this way is true but at least
one is set to `tt(auto)', the shell behaves as if the tt(AUTO_MENU)
option is set.


If one of the values is explicitly set to false, menu
completion will be explicitly turned off, overriding the
tt(MENU_COMPLETE) option and other settings.

In the form `tt(yes=)var(num)', where `tt(yes)' may be any of the
true values (`tt(yes)', `tt(true)', `tt(on)' and `tt(1)'),
menu completion will be turned on if there are at least var(num) matches.
In the form `tt(yes=long)', menu completion 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 `tt(yes=long-list)'
(Typically, the value `tt(select=long-list)' described later is more
useful as it provides control over scrolling.)

Similarly, with any of the `false' values (as in `tt(no=10)'), menu
completion will em(not) be used if there are var(num) or more matches.  

The value of this widget also controls menu selection, as implemented by
the tt(zsh/complist) module.  The following values may appear either
alongside or instead of the values above.

If the value contains the string `tt(select)', menu selection
will be started unconditionally.

In the form `tt(select=)var(num)', menu selection will only be started if
there are at least var(num) matches.  If the values for more than one
tag provide a number, the smallest number is taken.

Menu selection can be turned off explicitly by defining a value
containing the string`tt(no-select)'.

It is also possible to start menu selection only if the list of
matches does not fit on the screen by using the value
`tt(select=long)'.  To start menu selection even if the current widget
only performs listing, use the value `tt(select=long-list)'.

To turn on menu completion or menu selection when a there are a certain
number of matches em(or) the list of matches does not fit on the
screen, both of `tt(yes=)' and `tt(select=)' may be given twice, once
with a number and once with `tt(long)' or `tt(long-list)'.

Finally, it is possible to activate two special modes of menu selection.
The word `tt(interactive)' in the value causes interactive mode
to be entered immediately when menu selection is started; see
ifzman(the description of the tt(zsh/complist) module in zmanref(zshmodules))\
ifnzman(noderef(The zsh/complist Module))\
 for a description of interactive mode.  Including the string
`tt(search)' does the same for incremental search mode.  To select backward
incremental search, include the string `tt(search-backward)'.
)
kindex(muttrc, completion style)
item(tt(muttrc))(
If set, gives the location of the mutt configuration file.  It defaults
to `tt(~/.muttrc)'.
)
kindex(numbers, completion style)
item(tt(numbers))(
This is used with the tt(jobs) tag.  If it is `true', the shell will
complete job numbers instead of the shortest unambiguous prefix
of the job command text.  If the value is a number, job numbers will
only be used if that many words from the job descriptions are required to
resolve ambiguities.  For example, if the value is `tt(1)', strings will
only be used if all jobs differ in the first word on their command lines.
)
kindex(old-list, completion style)
item(tt(old-list))(
このスタイルは tt(_oldlist) コンプリータによって使われる。
値が `tt(always)' のときは、一覧を出す標準的ウィジェットが
今回マッチしたもののリストを保持するようになる。
This is used by the tt(_oldlist) completer.  If it is set to `tt(always)',
then standard widgets which perform listing will retain the current list of
matches, however they were generated; this can be turned off explicitly
with the value `tt(never)', giving the behaviour without the tt(_oldlist)
completer.  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 completion list is generated; this is the default behaviour of
tt(_oldlist).  However, if there is an old list and this style contains
the name of the completer function that generated the list, then the
old list will be used even if it was generated by a widget which does
not do listing.

たとえば、カーソルの下に修正案一覧を出す
tt(_correct_word) ウィジェット(tt(^Xc))を呼び出した場合を考える。
普通は次に tt(^D) を押すとコマンドライン上の単語で普通の補完を
する場合の候補一覧を出すが、
tt(_oldlist) と組み合わせると生成済みの修正案リストを表示する。

As another example consider the tt(_match) completer: with the
tt(insert-unambiguous) style set to `true' it inserts only a common prefix
string, if there is any.  However, this may remove parts of the original
pattern, so that further completion could produce more matches than on the
first attempt.  By using the tt(_oldlist) completer and setting this style
to tt(_match), the list of matches generated on the first attempt will be
used again.
)
kindex(old-matches, completion style)
item(tt(old-matches))(
tt(_all_matches) コンプリータが使用する。

This is used by the tt(_all_matches) completer to decide if an old
list of matches should be used if one exists.  This is selected by one of
the `true' values or by the string `tt(only)'.  If
the value is `tt(only)', tt(_all_matches) will only use an old list
and won't have any effect on the list of matches currently being
generated.

If this style is set it is generally unwise to call the tt(_all_matches)
completer unconditionally.  One possible use is for either this style or
the tt(completer) style to be defined with the tt(-e) option to
tt(zstyle) to make the style conditional.
)
kindex(old-menu, completion style)
item(tt(old-menu))(
This is used by the tt(_oldlist) completer.  It controls how menu
completion behaves when a completion has already been inserted and the
user types a standard completion key such as tt(TAB).  The default
behaviour of tt(_oldlist) is that menu completion always continues
with the existing list of completions.  If this style is set to
`false', however, a new completion is started if the old list was
generated by a different completion command; this is the behaviour without
the tt(_oldlist) completer.

For example, suppose you type tt(^Xc) to generate a list of corrections,
and menu completion is started in one of the usual ways.  Usually, or with
this style set to tt(false), typing tt(TAB) at this point would start
trying to complete the line as it now appears.  With tt(_oldlist), it
instead continues to cycle through the list of corrections.
)
kindex(original, completion style)
item(tt(original))(
This is used by the tt(_approximate) and tt(_correct)
completers 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 corrections, 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 tt(correct-)var(num) or
tt(approximate-)var(num), where var(num) is the number of errors that
were accepted.
)
kindex(packageset, completion style)
item(tt(packageset))(
This style is used when completing arguments of the Debian `tt(dpkg)'
program.  It contains an override for the default package set
for a given context.  For example,

example(zstyle ':completion:*:complete:dpkg:option--status-1:*' \ 
               packageset avail)

causes available packages, rather than only installed packages,
to be completed for `tt(dpkg -)tt(-status)'.
)
kindex(path, completion style)
item(tt(path))(
The function that completes color names uses this style with the 
tt(colors) tag.  The value should be the pathname of a file
containing color names in the format of an X11 tt(rgb.txt) file.  If
the style is not set but this file is found in one of various standard
locations it will be used as the default.
)
kindex(pine-directory, completion style)
item(tt(pine-directory))(
If set, specifies the directory containing PINE mailbox files.  There
is no default, since recursively searching this directory is inconvenient
for anyone who doesn't use PINE.
)
kindex(ports, completion style)
item(tt(ports))(
A list of Internet service names (network ports) to complete.  If this is
not set, service names are taken from the file `tt(/etc/services)'.
)
kindex(prefix-hidden, completion style)
item(tt(prefix-hidden))(
This is used for certain completions which share a common prefix, for
example command options beginning 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'.
)
kindex(prefix-needed, completion style)
item(tt(prefix-needed))(
This, too, is used for matches with a common prefix.  If it is set to
`true' this common prefix must be typed by the user to generate the
matches.  In the case of command options, this means that the initial
`tt(-)', `tt(+)', or `tt(-)tt(-)' must be typed explicitly before option
names will be completed.

The default value for this style is `true'.
)
kindex(preserve-prefix, completion style)
item(tt(preserve-prefix))(
This style is used when completing path names.  Its value should be a
pattern matching an initial prefix of the word to complete that should
be left unchanged under all circumstances.  For example, on some Unices
an initial `tt(//)' (double slash) has a special meaning; setting
this style to the string `tt(//)' will preserve it.  As another example,
setting this style to `tt(?:/)' under Cygwin would allow completion
after `tt(a:/...)' and so on.
)
kindex(range, completion style)
item(tt(range))(
This is used by the tt(_history) completer and the
tt(_history_complete_word) bindable command to decide which words
should be completed.  

If it is a singe number, only the last var(N) words from the history
will be completed.

If it is a range of the form `var(max)tt(:)var(slice)',
the last var(slice) words will be completed; then if that
yields no matches, the var(slice) words before those will be tried and 
so on.  This process stops either when at least one match was been
found, or var(max) words have been tried.

The default is to complete all words from the history at once.
)
kindex(regular, completion style)
item(tt(regular))(
This style is used by the tt(_expand_alias) completer and bindable 
command.  If set to `tt(true)' (the default), regular aliases will be
expanded but only in command position.  If it is set to `tt(false)',
regular aliases will never be expanded.   If it is set to `tt(always)',
regular aliases will be expanded even if not in command position.
)
kindex(rehash, completion style)
item(tt(rehash))(
If this is set when completing external commands, the internal
list (hash) of commands will be updated for each search by issuing
the tt(rehash) command.  There is a speed penalty for this which
is only likely to be noticeable when directories in the path have
slow file access.
)
kindex(remote-access, completion style)
item(tt(remote-access))(
If set to tt(false), certain commands will be prevented from making
Internet connections to retrieve remote information.  This includes the
completion for the tt(CVS) command.

It is not always possible to know if connections are in fact to a remote
site, so some may be prevented unnecessarily.
)
kindex(remove-all-dups, completion style)
item(tt(remove-all-dups))(
The tt(_history_complete_word) bindable command and the tt(_history)
completer use this to decide if all duplicate matches should be
removed, rather than just consecutive duplicates.
)
kindex(select-prompt, completion style)
item(tt(select-prompt))(
If this is set for the tt(default) tag, its
value will be displayed during menu selection (see the tt(menu) style
above) when the completion list does not fit on the screen as a
whole.  The same escapes as for the tt(list-prompt) style are
understood, except that the numbers refer to the match or line the mark is
on.  A default prompt is used when the value is the empty string.
)
kindex(select-scroll, completion style)
item(tt(select-scroll))(
This style is tested for the tt(default) tag and determines how a
completion list is scrolled during a menu selection (see the tt(menu)
style above) when the completion list does not fit on the screen as a
whole.  If the value is `tt(0)' (zero), the list is scrolled by
half-screenfuls; if it is a positive integer, the list is scrolled by the
given number of lines; if it is a negative number, the list is scrolled by a
screenful minus the absolute value of the given number of lines.
The default is to scroll by single lines.
)
kindex(separate-sections, completion style)
item(tt(separate-sections))(
This style is used with the tt(manuals) tag when completing names of
manual pages.  If it is `true', entries for different sections are
added separately using tag names of the form `tt(manual.)var(X)',
where var(X) is the section number.  When the tt(group-name) style is
also in effect, pages from different sections will appear separately.
This style is also used similarly with the tt(words) style when
completing words for the dict command. It allows words from different
dictionary databases to be added separately.
The default for this style is `false'.
)
kindex(show-completer, completion style)
item(tt(show-completer))(
Tested whenever a new completer is tried.  If it is true, the completion
system outputs a progress message in the listing area showing what
completer is being tried.  The message will be overwritten by any output
when completions are found and is removed after completion is finished.
)
kindex(single-ignored, completion style)
item(tt(single-ignored))(
1つしかマッチがないときに tt(_ignored) コンプリータによって使われる。
このスタイル値を `tt(show)' にしておくと，唯一のマッチは
挿入されず表示される。
`tt(menu)' にしておくと，唯一のマッチと元の文字列がマッチとして加えられ，
メニュー補完を開始する。
)
kindex(sort, completion style)
item(tt(sort))(
Many completion widgets call tt(_description) at some point which
decides whether the matches are added sorted or unsorted (often
indirectly via tt(_wanted) or tt(_requested)).  This style can be set
explicitly to one of the usual true or false values as an override.
If it is not set for the context, the standard 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
tt(true).

tt(_expand) コンプリータの場合，`true' にセットされていると
つねにソートする。`tt(menu)' の場合は展開結果を一個ずつメニュー補完で
提示する場合のみソートし，全ての展開結果を一括で挿入する場合には
ソートしない。

訳注: 複数の語を含む配列変数の展開結果中，実在するファイル
名と同じものがあると，それらだけ先頭に寄せられる。
)
kindex(special-dirs, completion style)
item(tt(special-dirs))(
Normally, the completion code will not produce the directory names
`tt(.)' and `tt(..)' as possible completions.  If this style is set to
`true', it will add both `tt(.)' and `tt(..)' as possible completions;
if it is set to `tt(..)', only `tt(..)' will be added.

The following example sets tt(special-dirs) to `tt(..)' when the
current prefix is empty, is a single `tt(.)', or consists only of a path
beginning with `tt(../)'.  Otherwise the value is `false'.

example(zstyle -e ':completion:*' special-dirs \ 
   '[[ $PREFIX = LPAR()../RPAR()#LPAR()|.|..RPAR() ]] && reply=LPAR()..RPAR()')
)
kindex(squeeze-slashes, completion style)
item(tt(squeeze-slashes))(
If set to `true', sequences of slashes in filename paths (for example in
`tt(foo//bar)') will be treated as a single slash.  This is the usual
behaviour of UNIX paths.  However, by default the file completion
function behaves as if there were a `tt(*)' between the slashes.
)
kindex(stop, completion style)
item(tt(stop))(
If set to `true', the tt(_history_complete_word) bindable
command will stop once when reaching the beginning or end of the
history.  Invoking tt(_history_complete_word) will then wrap around to 
the opposite end of the history.  If this style is set to `false' (the 
default), tt(_history_complete_word) will loop immediately as in a
menu completion.
)
kindex(strip-comments, completion style)
item(tt(strip-comments))(
If set to `true', this style causes non-essential comment text to be
removed from completion matches.  Currently it is only used when
completing e-mail addresses where it removes any display name from the
addresses, cutting them down to plain var(user@host) form.
)
kindex(subst-globs-only, completion style)
item(tt(subst-globs-only))(
tt(_expand) コンプリータが使う。`true' の場合，
グロッビングと置換両方がコマンドラインにあるときに，
置換だけうまくいってもグロッビングがうまく行かない場合には
置換もしなかったことにする(□)。
訳注: たとえば，`tt(file=foo)' のときに，
tt(${file}.*) で tt(_expand) したとする。このとき，
tt(foo.*) にマッチするものがあれば，通常通り展開結果をコマンドラインに
挿入するが，マッチするものがなければ tt(${file}) 自体も展開しない
ことにする。

デフォルト値は `true'。
)
kindex(suffix, completion style)
item(tt(suffix))(
tt(_expand) コンプリータで使われる。チルダまたは変数展開のとき，
`true' の場合はサフィクスを持たない場合のみ展開される。
i.e. if it is
something like `tt(~foo)' or `tt($foo)' rather than `tt(~foo/)' or
`tt($foo/bar)', unless that suffix itself contains characters eligible
for expansion.
デフォルト値は `true'。
)
kindex(tag-order, completion style)
item(tt(tag-order))(
This provides a mechanism for sorting how the tags available in a
particular context will be used.

The values for the style are sets of space-separated 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 tt(file-patterns) style for
an exception to this behavior.)

For example:

example(zstyle ':completion:*:complete:-command-:*' tag-order \ 
    'commands functions')

specifies that completion in command position first offers
external commands and shell functions.  Remaining tags will be tried if
no completions are found.

In addition to tag names, each string in the value may take one of the
following forms:

startitem()
item(tt(-))(
If any value consists of only a hyphen,
then em(only) the tags specified in the other values are
generated.  Normally all tags not explicitly selected are tried last
if the specified tags fail to generate any matches.  This means 
that a single value consisting only of a single hyphen
turns off completion.
)
item(tt(!) var(tags)...)(
A string starting with an exclamation mark
specifies names of tags that are em(not) to be used.  The effect is
the same as if all other possible tags for the context had been
listed.
)
item(var(tag)tt(:)var(label) ...)(
Here, var(tag) is one of the standard tags and var(label) is an
arbitrary name.  Matches are generated as normal but the name var(label)
is used in contexts instead of var(tag).  This is not useful in words
starting with tt(!).

If the var(label) starts with a hyphen, the var(tag) is prepended to the
var(label) to form the name used for lookup.  This can be
used to make the completion system try a certain tag more than once,
supplying different style settings for each attempt; see below for an
example.
)
item(var(tag)tt(:)var(label)tt(:)var(description))(
As before, but tt(description) will replace the `tt(%d)' in
the value of the tt(format) style instead of the default description
supplied by the completion function.  Spaces in the description must
be quoted with a backslash.  A `tt(%d)' appearing
in var(description) is replaced with the description given by the
completion function.
)
enditem()

In any of the forms above the tag may be a pattern or several
patterns in the form `tt({)var(pat1)tt(,)var(pat2...)tt(})'.  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 without having to
repeat them all.  For example, to make completion of function names in
command position ignore all the completion functions starting with an
underscore the first time completion is tried:

example(zstyle ':completion:*:*:-command-:*' tag-order \ 
    'functions:-non-comp *' functions
zstyle ':completion:*:functions-non-comp' ignored-patterns '_*')

On the first attempt, all tags will be offered but the tt(functions) tag
will be replaced by tt(functions-non-comp).  The tt(ignored-patterns) style 
is set for this tag to exclude functions starting with an underscore.
If there are no matches, the second value of the
tt(tag-order) style is used which completes 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:

example(zstyle ':completion:*' tag-order \ 
    'options:-long:long\ options
     options:-short:short\ options
     options:-single-letter:single\ letter\ options'

zstyle ':completion:*:options-long' ignored-patterns '[-+](|-|[^-]*)'
zstyle ':completion:*:options-short' ignored-patterns '--*' '[-+]?'
zstyle ':completion:*:options-single-letter' ignored-patterns '???*')

With the tt(group-names) style set, options beginning with
`tt(-)tt(-)', options beginning with a single `tt(-)' or `tt(+)' but
containing multiple characters, and single-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
tt(matcher-list) style offers something similar, but it is tested very
early in the completion system and hence can't be set for single
commands nor for more specific contexts.  Here is how to
try normal completion without any match specification and, if that
generates no matches, try again with case-insensitive matching, restricting
the effect to arguments of the command tt(foo):

example(zstyle ':completion:*:*:foo:*' tag-order '*' '*:-case'
zstyle ':completion:*-case' matcher 'm:{a-z}={A-Z}')

First, all the tags offered when completing after tt(foo) are tried using
the normal tag name.  If that generates no matches, the second value of
tt(tag-order) is used, which tries all tags again except that this time
each has tt(-case) appended to its name for lookup of styles.  Hence this
time the value for the tt(matcher) style from the second call to tt(zstyle)
in the example is used to make completion case-insensitive.

It is possible to use the tt(-e) option of the tt(zstyle) builtin
command to specify conditions for the use of particular tags.  For
example:

example(zstyle -e '*:-command-:*' tag-order '
    if [[ -n $PREFIX$SUFFIX ]]; then
      reply=( )
    else
      reply=( - )
    fi')

Completion in command position will be attempted only if the string
typed so far is not empty.  This is tested using the tt(PREFIX)
special parameter; see
ifzman(zshcompwid)\
ifnzman(noderef(Completion Widgets))
for a description of parameters which are special inside completion widgets.
Setting tt(reply) to an empty array provides the default
behaviour of trying all tags at once; setting it to an
array containing only a hyphen disables the use of all tags and hence of
all completions.

If no tt(tag-order) style has been defined for a context, the strings
`tt((|*-)argument-* (|*-)option-* values)' and `tt(options)' plus all
tags offered by the completion function will be used to provide a
sensible default behavior that causes arguments (whether normal command
arguments or arguments of options) to be completed before option names for
most commands.
)
kindex(urls, completion style)
item(tt(urls))(
This is used together with the the tt(urls) tag by
functions completing URLs.

If the value consists of more than one string, or if the only string
does not name a file or directory, 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).

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
`tt(http)', `tt(ftp)', `tt(bookmark)' and so on.  In many cases the next
level of directories will be a filename.  The directory hierarchy can
descend as deep as necessary.

For example, 

example(zstyle ':completion:*' urls ~/.urls
mkdir -p ~/.urls/ftp/ftp.zsh.org/pub/development
)

allows completion of all the components of the URL
tt(ftp://ftp.zsh.org/pub/development) after suitable commands such as
`tt(netscape)' or `tt(lynx)'.  Note, however, that access methods and
files are completed separately, so if the tt(hosts) style is set hosts
can be completed without reference to the tt(urls) style.

See the description in the function tt(_urls) itself
for more information (e.g. `tt(more $^fpath/_urls+LPAR()N+RPAR())').
)
kindex(use-cache, completion style)
item(tt(use-cache))(
If this is set, the completion caching layer is activated for any completions
which use it (via the tt(_store_cache), tt(_retrieve_cache), and
tt(_cache_invalid) functions).  The directory containing the cache
files can be changed with the tt(cache-path) style.
)
kindex(use-compctl, completion style)
item(tt(use-compctl))(
If this style is set to a string em(not) equal to tt(false), tt(0),
tt(no), and tt(off), the completion system may use any completion
specifications defined with the tt(compctl) builtin command.  If the
style is unset, this is done only if the tt(zsh/compctl) module
is loaded.  The string may also contain the substring `tt(first)' to
use completions defined with `tt(compctl -T)', and the substring
`tt(default)' to use the completion defined with `tt(compctl -D)'.

Note that this is only intended to smooth the transition from
tt(compctl) to the new completion system and may disappear in the
future.

Note also that the definitions from tt(compctl) will only be used if
there is no specific completion function for the command in question.  For
example, if there is a function tt(_foo) to complete arguments to the
command tt(foo), tt(compctl) will never be invoked for tt(foo).
However, the tt(compctl) version will be tried if tt(foo) only uses
default completion.
)
kindex(use-ip, completion style)
item(tt(use-ip))(
By default, the function tt(_hosts) that completes host names strips
IP addresses from entries read from host databases such as NIS and
ssh files.  If this style is true, the corresponding IP addresses
can be completed as well.  This style is not use in any context
where the tt(hosts) style is set; note also it must be set before
the cache of host names is generated (typically the first completion
attempt).
)
kindex(use-perl, completion style)
item(tt(use-perl))(
Various parts of the function system use awk to extract words from
files or command output as this universally available.  However, many
versions of awk have arbitrary limits on the size of input.  If this
style is set, perl will be used instead.  This is almost always
preferable if perl is available on your system.

Currently this is only used in completions for `make', but it may be
extended depending on authorial frustration.
)
kindex(users, completion style)
item(tt(users))(
This may be set to a list of usernames to be completed.
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.
)
kindex(users-hosts, completion style)
item(tt(users-hosts))(
The values of this style should be of the form
`var(user)tt(@)var(host)' or `var(user)tt(:)var(host)'. It is used for
commands that need pairs of
user- and hostnames.  These commands will complete usernames from this
style (only), and will restrict subsequent hostname completion 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 tt(rlogin) and tt(ssh), by using the tt(my-accounts) tag.
Similarly, values for sets of commands which usually refer to the
accounts of other people, such as tt(talk) and tt(finger), can be
grouped by using the tt(other-accounts) tag.  More ambivalent commands
may use the tt(accounts) tag.
)
kindex(users-hosts-ports, completion style)
item(tt(users-hosts-ports))(
Like tt(users-hosts) but used for commands like tt(telnet) and
containing strings of the form `var(user)tt(@)var(host)tt(:)var(port)'.
)
kindex(verbose, completion style)
item(tt(verbose))(
If set, as it is by default, the completion listing is more verbose.
In particular many commands show descriptions for options if this
style is `true'.
)
kindex(word, completion style)
item(tt(word))(
This is used by the tt(_list) completer, which prevents the insertion of
completions until a second completion 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.
)
enditem()

texinode(Control Functions)(Bindable Commands)(Completion System Configuration)(Completion System)
sect(Control Functions)
cindex(completion system, choosing completers)

tt(compinit) は，
補完を行なう関数すべてのウィジェットを再定義して，
与えられたウィジェット関数 tt(_main_complete) を呼ぶようにする。
この関数は，マッチするものを生成する「コンプリータ」と呼ばれる
関数を呼ぶラッパーとなっている。
もし，`tt(_main_complete)' が引数つきで呼ばれたときには，
それらは補完関数と見なされ，その順番で呼ばれることになる。
引数なしなら，補完を試みる関数は tt(completer) スタイルから取得される。
たとえば，通常の補完関数をまず呼んで，それでマッチするものがなければ
綴違い修正関数を呼ばせたければ，tt(compinit) したあとで

example(zstyle ':completion:*' completer _complete _correct)

とする。このスタイルのデフォルト値は
`tt(_complete _ignored)' で，
通常の補完を，まず tt(ignored-patterns) スタイルの効果ありで，
続いて効果なしで，という順番で試みる。
tt(_main_complete) 関数は
各コンプリータ関数のリターンコードを見て，次のコンプリータを
呼ぶかどうか決める。リターンコード0なら，残りのコンプリータは呼ばずに
tt(_main_complete) 関数自体から抜ける。

もし tt(_main_complete) の最初の引数がハイフン1字なら，
引数はコンプリータの名前とは見なされず，
2つ目の引数はコンテクストの tt(completer) フィールドの値に，
残りの引数はマッチするものを生成する関数名とその引数と見なされる。

以下のコンプリータ関数は配布物に含まれているものだが，
ユーザは自分専用のものを書くことができる。
関数名はアンダースコアで始まるが，コンテクストでは
先頭のアンダースコアは取り除かれることに注意せよ。
たとえば，基本の補完は
`tt(:completion::complete:)var(...)' というコンテクストで実行される。

cindex(completion system, completers)
startitem()
findex(_all_matches)
item(tt(_all_matches))(
このコンプリータは，「それ以外のマッチすべて」からなる文字列を
追加するために使われる。
これは以後呼ばれるコンプリータに影響を与えるためのものなので，
一連のコンプリータの先頭に登場する必要がある。
マッチするものすべてのリストは tt(avoid-completer) と
tt(old-matches) スタイルの影響を受ける。

後述する tt(_generic) 関数を利用して tt(_all_matches) 自身に
キーを割り当てるとよい。たとえば以下のようにする。

example(zle -C all-matches complete-word _generic
bindkey '^Xa' all-matches
zstyle ':completion:all-matches:*' old-matches only
zstyle ':completion:all-matches::::' completer _all_matches)

註: これだけでは補完はされない。最初に候補一覧を出してから
tt(^Xa) を押してマッチするものすべてを出す。
)
findex(_approximate)
item(tt(_approximate))(
基本コンプリータの tt(_complete) に似ているが，
補完に綴り修正を受けることを許可する。
許される間違いの上限の個数は tt(max-errors) スタイルで指定する。
個数の数え方については
ifzman(\
zmanref(zshexpn)
)\
ifnzman(\
noderef(Filename Generation)
)\
参照。
通常このコンプリータは，普通の tt(_complete) コンプリータの
あとでだけ試行される。

example(zstyle ':completion:*' completer _complete _approximate)

とすると普通の補完で補完候補を得られなかった場合に限り
修正補完をする。もし，修正により補完候補がみつかった場合は
コンプリータはそれらを巡回できるようメニュー補完を開始する。

このコンプリータは，修正候補と元の文字列を生成するときに
tt(corrections) と tt(original) タグを利用する。
前者用の tt(format) スタイルには
`tt(%e)' と `tt(%o)' を含ませることができ，それぞれ
修正に要したエラー数および，元の文字列，に置き換えられる。

訳注: こんな感じ。

example(zstyle ':completion:*:approximate*:*:*:corrections' \ 
   format '%B%d (errors=%e) (original=%o)%b'
zstyle ':completion:*' completer _complete _approximate)

訳注終わり。

このコンプリータは tt(max-errors) スタイルで指定された最大エラー数を
徐々に増やして行くので，もし「エラー修正数1」でみつかったら，
修正数2以上のものは出てこない。
修正数2でみつかった場合は3以上が出ない…，以下同様。
またコンテクストのコンプリータ名のところには，
現在試行されているエラー修正数が，
修正数1のときは `tt(approximate-1)'，修正数2のときは
 `tt(approximate-2)'…，と変わるようになっている。

tt(_approximate) を別の関数から呼ぶときは
tt(-a) オプションに続けて許容エラー数を渡すことができる。
引数は tt(max-errors) スタイルと同じ書式で，1つの文字列にする。

このコンプリータ(と後述の tt(_correct) コンプリータ)は，
とくに大きな許容エラー数を指定して呼んだときに厖大なコストがかかる
可能性を持つ。そこで，
tt(completer) スタイルを定義するときに，
tt(zstyle) の tt(-e) オプションを使って，全く同じ文字列に
対して2回連続で補完しようとしたときにそうしたコンプリータが
呼ばれるようにすることもできる。例:

example(zstyle -e ':completion:*' completer '
  if [[ $_last_try != "$HISTNO$BUFFER$CURSOR" ]]; then
    _last_try="$HISTNO$BUFFER$CURSOR"
    reply=(_complete _match _prefix)
  else
    reply=(_ignored _correct _approximate)
  fi')

ここではzleと補完ウィジェット内部で使える
tt(HISTNO) 変数と，tt(BUFFER)，tt(CURSOR) 特殊変数を使い，
直前に補完したときとコマンドラインが同じかどうか調べ，
そのときだけ tt(_ignored)，tt(_correct)，tt(_approximate) 
コンプリータが呼ばれるようにしている。
)
findex(_complete)
item(tt(_complete))(
コンテクストに即した方法で，すべての補完候補を生成するコンプリータ。
つまり，tt(compdef) 関数(解説済み)で定義した設定とすべての特殊変数の
現在の値を使う(訳注: 分からない人にとっては「つまり…」になってないやん
乱暴だなあ)。
通常の補完動作を与えているのがこのコンプリータである。

コマンドの引数を補完するために tt(_complete) はユーティリティ関数の
tt(_normal) を呼び，今度はそれが特別な関数(後述)を探し出す役割を
受け持つ。
このとき(□)，`tt(-)var(context)tt(-)' という形式の様々な
コンテクストがはっきりと区別される。これらコンテクストなどについては
文書前半の tt(#compdef) タグの引数の説明に書かれている。

固有のコンテクスト用の関数を探す前に，
tt(_complete) は変数 `tt(compcontext)' がセットされているか調べる。
たとえば自作関数で入力に tt(vared) を使ったりする局面などでは
通常の補完関数の振り分け(dispatch)をオーバーライドできると便利で
そのようなときに `tt(compcontext)' 変数が使える。
もし値に配列を入れておけば，各要素は補完候補となり，
`tt(values)' タグと `tt(value)' デスクリプション(△)を
用いて補完されるようになる(△ 訳注: 分かんないけど飛ばす)。

comment(
If it is set to an array, the elements are taken
to be the possible matches which will be completed using the tag
`tt(values)' and the description `tt(value)'. 
)

また，連想配列の値を入れておけば，各キーが補完候補，
値(value)がそれに対応する説明文字列として使われる。
また，コロンを含んだ文字列を
`var(tag)tt(:)var(descr)tt(:)var(action)' のような形式で入れておくとそれは，


If it is set to an
associative array, the keys are used as the possible completions and
the values (if non-empty) are used as descriptions for the matches.  If
`tt(compcontext)' is set to a string containing colons, it should be of
the form `var(tag)tt(:)var(descr)tt(:)var(action)'.  In this case the
var(tag) and var(descr) give the tag and description to use and the
var(action) indicates what should be completed in one of the forms
accepted by the tt(_arguments) utility function described below.

最後に，コロンなしの文字列を入れておくと，
その値がコンテクストとして使われ，それ用の関数が呼ばれることになる。
この目的のために，tt(-command-line-) という名前の特別なコンテクスト
があり，それはコマンドライン全体(コマンドとその引数)を補完する(△???)。
これは補完システム自体は使用していないが，明示的に呼ばれると処理される。

訳注: あら，tt(_complete) の説明終わっちゃった。これじゃ分からんよなあ。
わからんけど，分かるような説明も書けんか。訳注終わり。
)
findex(_correct)
item(tt(_correct))(
現在の語に対する補完ではなく，綴り「修正」のみを生成する。
tt(_approximate) に似ているが，カーソル位置以降に文字を補うことはせず，
既に入力し終えた単語のスペルチェック(&修正)のように機能する。
tt(_approximate) に基づくコンプリータだが，コンテクストのコンプリータ
フィールドは tt(correct) となる。

For example, with:

example(zstyle ':completion:::::' completer _complete _correct _approximate
zstyle ':completion:*:correct:::' max-errors 2 not-numeric
zstyle ':completion:*:approximate:::' max-errors 3 numeric)

correction will accept up to two errors.  If a numeric argument is
given, correction will not be performed, but correcting completion
will be, and will accept as many errors as given by the numeric
argument.  Without a numeric argument, first correction and then
correcting completion will be tried, with the first one accepting two
errors and the second one accepting three errors.

When tt(_correct) is called as a function, the number of errors to accept
may be given following the tt(-a) option.  The argument is in the same
form a values to the tt(accept) style, all in one string.

This completer function is intended to be used without the
tt(_approximate) completer or, as in the example, just before
it.  Using it after the tt(_approximate) completer is useless since
tt(_approximate) will at least generate the corrected strings
generated by the tt(_correct) completer DASH()- and probably more.
)
findex(_expand)
item(tt(_expand))(
This completer function does not really perform completion, but instead
checks if the word on the command line is eligible for expansion and,
if it is, gives detailed control over how this expansion is done.  For
this to happen, the completion system needs to be invoked with
tt(complete-word), not tt(expand-or-complete) (the default binding for
tt(TAB)), as otherwise the string will be expanded by the shell's
internal mechanism before the completion system is started.
Note also this completer should be called before the tt(_complete) 
completer function.

The tags used when generating expansions are tt(all-expansions) for the
string containing all possible expansions, tt(expansions) when adding
the possible expansions as single matches and tt(original) when adding
the original string from the line.  The order in which these strings are
generated, if at all, can be controlled by the tt(group-order) and
tt(tag-order) styles, as usual.

The format string for tt(all-expansions) and for tt(expansions) may
contain the sequence `tt(%o)' which will be replaced by the original
string from the line.

The kind of expansion to be tried is controlled by the tt(substitute),
tt(glob) and tt(subst-globs-only) styles.

It is also possible to call tt(_expand) as a function, in which case the
different modes may be selected with options: tt(-s) for
tt(substitute), tt(-g) for tt(glob) and tt(-o) for tt(subst-globs-only).
)
findex(_expand_alias)
item(tt(_expand_alias))(
If the word the cursor is on is an alias, it is expanded and no other
completers are called.  The types of aliases which are to be expanded can
be controlled with the styles tt(regular), tt(global) and tt(disabled).

This function is also a bindable command, see
ifzman(the section `Bindable Commands' below)\
ifnzman(noderef(Bindable Commands)).
)
findex(_history)
item(tt(_history))(
Complete words from the shell's command  history.  This completer 
can be controlled by the tt(remove-all-dups), and tt(sort) styles as for the
tt(_history_complete_word) bindable command, see
ifzman(the section `Bindable Commands' below)\
ifnzman(noderef(Bindable Commands))
and
ifzman(the section `Completion System Configuration' above)\
ifnzman(noderef(Completion System Configuration)).
)
findex(_ignored)
item(tt(_ignored))(
The tt(ignored-patterns) style can be set to a list of patterns which are
compared against possible completions; matching ones are removed.
With this completer those matches can be reinstated, as
if no tt(ignored-patterns) style were set.  The completer actually
generates its own list of matches; which completers are invoked
is determined in the same way as for the tt(_prefix) completer.
The tt(single-ignored) style is also available as described above.
)
findex(_list)
item(tt(_list))(
This completer allows the insertion of matches to be delayed until
completion is attempted a second time without the word on the line
being changed.  On the first attempt, only the list of matches will be
shown.  It is affected by the styles tt(condition) and tt(word), see
ifzman(the section `Completion System Configuration' above)\
ifnzman(noderef(Completion System Configuration)).
)
findex(_match)
item(tt(_match))(
This completer is intended to be used after the tt(_complete)
completer.  It behaves similarly but the string on the command line may
be a pattern to match against trial completions.  This gives the effect
of the tt(GLOB_COMPLETE) option.

Normally completion will be performed by taking the pattern from the line,
inserting a `tt(*)' at the cursor position and comparing the resulting
pattern with the possible completions generated.  This can be modified
with the tt(match-original) style described above.

The generated matches will be offered in a menu completion unless the
tt(insert-unambiguous) style is set to `true'; see the description above
for other options for this style.

Note that matcher specifications defined globally or used by the
completion functions (the styles tt(matcher-list) and tt(matcher)) will
not be used.
)
findex(_menu)
item(tt(_menu))(
This completer was written as simple example function 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
tt(_generic) based widgets. It should be used as the first completer in
the list.  Note that this is independent of the setting of the
tt(MENU_COMPLETE) option and does not work with the other menu
completion widgets such as tt(reverse-menu-complete), or
tt(accept-and-menu-complete).
)
findex(_oldlist)
item(tt(_oldlist))(
This completer controls how the standard completion widgets behave
when there is an existing list of completions which may have been
generated by a special 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
ordinary contextual completions.
It should appear in the list of completers before any of
the widgets which generate matches.  It uses two styles: tt(old-list) and
tt(old-menu), see
ifzman(the section `Completion System Configuration' above)\
ifnzman(noderef(Completion System Configuration)).
)
findex(_prefix)
item(tt(_prefix))(
This completer can be used to try completion with the suffix (everything
after the cursor) ignored.  In other words, the suffix will not be
considered to be part of the word to complete.  The effect is similar
to the tt(expand-or-complete-prefix) command.

The tt(completer) style is used to decide which other completers are to
be called to generate matches.  If this style is unset, the list of
completers set for the current context is used DASH()- except, of course, the
tt(_prefix) completer itself.  Furthermore, if this completer appears
more than once in the list of completers only those completers not
already tried by the last invocation of tt(_prefix) will be called.

For example, consider this global tt(completer) style:

example(zstyle ':completion:*' completer \ 
    _complete _prefix _correct _prefix:foo)

Here, the tt(_prefix) completer tries normal completion but ignoring the
suffix.  If that doesn't generate any matches, and neither does
the call to the tt(_correct) completer after it, tt(_prefix) will 
be called a second time and, now only trying correction with the
suffix ignored.  On the second invocation the completer part of the
context appears as `tt(foo)'.

To use tt(_prefix) as the last resort and try only normal completion
when it is invoked:

example(zstyle ':completion:*' completer _complete ... _prefix
zstyle ':completion::prefix:*' completer _complete)

The tt(add-space) style is also respected.  If it is set to `true' then
tt(_prefix) will insert a space between the matches generated (if any) 
and the suffix.

Note that this completer is only useful if the
tt(COMPLETE_IN_WORD) option is set; otherwise, the cursor will
be moved to the end of the current word before the completion code is
called and hence there will be no suffix.
)
findex(bashcompinit)
item(tt(bashcompinit))(
This function provides compatibility with bash's programmable completion
system.  When run it will define the functions, tt(compgen) and
tt(complete) which correspond to the bash builtins with the same names.
It will then be possible to use completion specifications and functions
written for bash.
)
enditem()

texinode(Bindable Commands)(Completion Functions)(Control Functions)(Completion System)
sect(Bindable Commands)
cindex(completion system, bindable commands)

できるだけ直感に添えるよう作られたコンテクスト依存の補完だけでなく，
他の特殊なウィジェットがあり，キーに割り当てることができる。
以下にそれら一覧を示す。

startitem()
findex(_bash_completions)
item(tt(_bash_completions))(
tt(_bash_complete-word) と tt(_bash_list-choices) の2つのウィジェットに
よって使われる関数で，bashの補完コマンドと互換のある機能を提供している。
呼び出しキーの最後のストロークで補完対象を切り替える。
`tt(!)' ならコマンド名，`tt($)' なら環境変数名，
`tt(@)' ならホスト名，`tt(/)' ならファイル名，
`tt(~)' ならユーザ名を補完する。
bashでは `tt(\e)' のあとにそれらのキーを押せば補完，
`tt(\^X)' のあとに押せば一覧表示となるが，
これらのうちいくつかはzshの標準キーバインドとかち合うので
デフォルトでは `tt(\e~)' と `tt(^X~)' だけキーに割り当ててある。
残りのキーをbashと同じバインドで足すには以下のようにする。


example(for key in '!' '$' '@' '/' '~'; do
  bindkey "\e$key" _bash_complete-word
  bindkey "^X$key" _bash_list-choices
done)

This includes the bindings for `tt(~)' in case they were already bound to
something else; the completion code does not override user bindings.
)
findex(_correct_filename (^XC))
item(tt(_correct_filename (^XC)))(
Correct the filename path at the cursor position.  Allows up to six errors
in the name.  Can also be called with an argument to correct
a filename path, independently of zle; the correction is printed on
standard output.
)
findex(_correct_word) (^Xc)
item(tt(_correct_word) (^Xc))(
Performs correction of the current argument using the usual contextual
completions as possible choices. This stores the string
`tt(correct-word)' in the var(function) field of the context name and
then calls the tt(_correct) completer.
)
findex(_expand_alias (^Xa))
item(tt(_expand_alias (^Xa)))(
This function can be used as a completer and as a bindable command.
It expands the word the cursor is on if it is an alias.  The types of
alias expanded can be controlled with the styles tt(regular), tt(global)
and tt(disabled).

When used as a bindable command there is one additional feature that
can be selected by setting the tt(complete) style to `true'.  In this
case, if the word is not the name of an alias, tt(_expand_alias) tries
to complete the word to a full alias name without expanding it.  It
leaves the cursor directly after the completed word so that invoking
tt(_expand_alias) once more will expand the now-complete alias name.
)
findex(_expand_word (^Xe))
item(tt(_expand_word (^Xe)))(
Performs expansion on the current word:  equivalent to the standard
tt(expand-word) command, but using the tt(_expand) completer.  Before
calling it, the var(function) field of the context is set to
`tt(expand-word)'.
)
findex(_generic)
item(tt(_generic))(
This function is not defined as a widget and not bound by
default.  However, it can be used to define a widget and will then
store the name of the widget in the var(function) field of the context 
and call the completion system.  This allows custom completion widgets
with their own set of style settings to be defined easily.  For example, 
to define a widget that performs normal completion and starts
menu selection:

example(zle -C foo complete-word _generic
bindkey '...' foo
zstyle ':completion:foo:*' menu yes select=1)

Note in particular that the tt(completer) style may be set for the context
in order to change the set of functions used to generate possible matches.
If tt(_generic) is called with arguments, those are passed through to
tt(_main_complete) as the list of completers in place of those defined by
the tt(completer) style.
)
findex(_history_complete_word (\e/))
item(tt(_history_complete_word) (\e/))(
Complete words from the shell's command history. This uses the
tt(list), tt(remove-all-dups), tt(sort), and tt(stop) styles.
)
findex(_most_recent_file (^Xm))
item(tt(_most_recent_file (^Xm)))(
Complete the name of the most recently modified file matching the pattern
on the command line (which may be blank).  If given a numeric argument
var(N), complete the var(N)th most recently modified file.  Note the
completion, if any, is always unique.
)
findex(_next_tags (^Xn))
item(tt(_next_tags) (^Xn))(
This command alters the set of matches used to that for the next tag, or
set of tags, either as given by the tt(tag-order) style or as set by
default; these matches would otherwise not be available.
Successive invocations of the command cycle through all possible sets of
tags.
)
findex(_read_comp (^X^R))
item(tt(_read_comp (^X^R)))(
Prompt the user for a string, and use that to perform completion on the
current word.  There are two possibilities for the string.  First, it can
be a set of words beginning `tt(_)', for example `tt(_files -/)', in which
case the function with any arguments will be called to generate the
completions.  Unambiguous parts of the function name will be completed
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
tt(compadd) and should hence be an expression specifying what should
be completed.

A very restricted set of editing commands is available when reading the
string:  `tt(DEL)' and `tt(^H)' delete the last character; `tt(^U)' deletes
the line, and `tt(^C)' and `tt(^G)' abort the function, while `tt(RET)'
accepts the completion.  Note the string is used verbatim as a command
line, so arguments must be quoted in accordance with standard shell rules.

Once a string has been read, the next call to tt(_read_comp) will use the
existing string instead of reading a new one.  To force a new string to be
read, call tt(_read_comp) with a numeric argument.
)
findex(_complete_debug (^X?))
item(tt(_complete_debug (^X?)))(
This widget performs ordinary completion, but captures in a temporary file
a trace of the shell commands executed by the completion system.  Each
completion attempt gets its own file.  A command to view each of these
files is pushed onto the editor buffer stack.
)
findex(_complete_help (^Xh))
item(tt(  _complete_help (^Xh)))(
現在のカーソル位置でのコンテクストの各フィールド情報を表示する。
1より大きな数引数をつけると(`tt(ESC-2 ^Xh)' など)
そこで参照されるスタイルとそのときのコンテクストもすべて表示される。

ただし，スタイルに関する情報はユーザが独自に設定したスタイルなどで
変わりうるので不完全であることに注意。
)
findex(_complete_tag (^Xt))
item(tt(_complete_tag (^Xt)))(
This widget completes symbol tags created by the tt(etags) or tt(ctags)
programmes (note there is no connection with the completion system's tags)
stored in a file tt(TAGS), in the format used by tt(etags), or tt(tags), in the
format created by tt(ctags).  It will look back up the path hierarchy for
the first occurrence of either file; if both exist, the file tt(TAGS) is
preferred.  You can specify the full path to a tt(TAGS) or tt(tags) file by
setting the parameter tt($TAGSFILE) or tt($tagsfile) respectively.
The corresponding completion tags used are tt(etags) and tt(vtags), after
emacs and vi respectively.
)
enditem()

texinode(Completion Functions)(Completion Directories)(Bindable Commands)(Completion System)
sect(Utility Functions)
cindex(completion system, utility functions)

ここでは補完関数を書くときに有用なユーティリティ関数について述べる。
If functions are installed in
subdirectories, most of these reside in the tt(Base) subdirectory.  
配布に含まれるコマンド用の補完関数例のように，
候補一覧を生成するユーティリティ関数はすべて，
候補を生成したならゼロ，しなかったなら非ゼロを返すという決まりに従っている。

また，tt(_main_complete) 関数は補完を行なう直前と直後にそれぞれ
配列 tt(compprefuncs)，配列 tt(comppostfuncs) に列挙された関数を
呼ぶ。各関数は明示的に自分自身を配列に再代入しない限り
1度だけ呼ばれる(訳注: それがユーティリティ関数とどう関連するか
書いてクレー???)。

startitem()
findex(_all_labels)
item(tt(_all_labels) [ tt(-x) ] [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(command) var(args) ... ])(
下記 tt(_next_label) 関数(該当箇所の説明にループを構築する例がある)
への手軽なインタフェース関数。
var(command) とその引数が補完候補を生成するために呼ばれる。
var(name) に保存されたオプションは自動的に，var(args)
に追加され(var(command)にも渡され)る。
通常それらは var(command) 直後に挿入されるが，var(args) の
どれかがハイフンのみの場合はその直前に入れられる。
ハイフンが最後の引数のときは，最後のハイフンを削除する(△なじぇ)。
これにより，tt(compadd) や他のユーティリティ関数を1回だけ呼んで
補完候補を生成するようなほとんどの場所で tt(_all_labels) を
使えるようになる(△???: はにゃ)。

comment(
This allows tt(_all_labels) to be used in almost all
cases where the matches can be generated by a single call to the
tt(compadd) builtin command or by a call to one of the utility functions.
)

たとえば，

example(local expl
...
if _requested foo; then
  ...
  _all_labels foo expl '...' compadd ... - $matches
fi)

とすると，
tt(_all_labels)が生成したものより優先されるような追加オプションを
tt(compadd)につけて，
tt(matches) 変数にある値を補完するようになる(△んむ???)。

comment(
Will complete the strings from the tt(matches) parameter, using
tt(compadd) with additional options which will take precedence over
those generated by tt(_all_labels).
)
)
findex(_alternative)
item(tt(_alternative) [ tt(-C) var(name) ] var(spec) ...)(
複数のタグが利用可能な単純なケースで有用。
本質的にこれは tt(_tags) 関数(後述)で説明するループのようなものを
実装している。

使用するタグとそのとき遂行する処理は var(spec) で

`var(tag)tt(:)var(descr)tt(:)var(action)'

という書式で指定する。

var(tag) は tt(_tags) を使って与えられ，もしタグが要求されたら
var(action) が var(descr) を説明文字列として伴って実行される。
var(action) は，下記 tt(_arguments) 関数が受け付けるものと同じ
(ただし `tt(->)var(state)' と `tt(=)var(...)' を除く)。

たとえば，var(action) は単純な関数呼び出しでよく，

example(_alternative \ 
    'users:user:_users' \ 
    'hosts:host:_hosts')

とすると，ユーザ名とホスト名を補完候補として提示し，それらは
それぞれ tt(_users)，tt(_hosts) 関数が生成する。

tt(_arguments) 関数のように，この関数は tt(_all_labels) を
すべてのタグセットに関して繰り返してアクションを実行するために使う。
特別な処理は付加的な有効タグがある場合のみ(たとえば，
tt(_alternative) から呼ばれた関数)される(△なんのこっちゃ???)。
comment(
Like tt(_arguments), this functions uses tt(_all_labels) to execute 
the actions, which will loop over all sets of tags.  Special handling is
only required if there is an additional valid tag, for example inside a
function called from tt(_alternative).
)

tt(_tags) 関数と同様，tt(-C) オプションで tt(argument) コンテクスト
フィールドに別のものを与えられる。

訳注: tt(_tags) 関数が分からないとこれを理解するのは困難。
上記の users, hosts の例を tt(_tags) のループで書くと，おそらく
このようになる。

example(local expl ret=1
_tags users hosts
while _tags; do
   _requested users expl 'user' _users && ret=0
   _requested hosts expl 'host' _hosts && ret=0
  (( ret )) || return ret
done)
)
findex(_arguments)
item(tt(_arguments) [ tt(-nswWACRS) ] [ tt(-O) var(name) ] [ tt(-M) var(matchspec) ] [ tt(:) ] var(spec) ...)(
この関数は，標準的なUNIXのオプションと引数の流儀に従うコマンドの
完全な仕様を補完システムに教えるために使う。以下に示す書式を
使って個々のコマンドのオプション・引数のセットを指定して行くわけだが，
tt(_argument) 自身へのオプションなのか対象となるコマンドのオプション指定
なのか紛らわしくなるので，区別しやすくするためにそれらの間にコロンひとつを
挟んでも構わない(□訳注: ちゅーかこのマニュアル自身が tt(_arguments) への
オプションなのか，それによって補完されるコマンドのオプションなのか
判別しやすい工夫をしてないのが痛い。気をつけて読んでくだされ。)。
tt(_arguments) 自身へのオプションは1字オプションだが
必ず別の単語で指定しなければならない(つまり tt(-s -w) をまとめて
tt(-sw) とするのは不可(□))。

tt(_arguments) に tt(-n) オプションを指定すると，変数 tt(NORMARG) に
配列変数 tt(words) 中の最初の普通の引数の位置，
つまりオプション指定が終わった最初の引数の位置，を代入するようになる。
普通の引数まで辿り着かない場合 tt(NORMARG) は tt(-1) になる。
呼び主となる関数では，tt(-n) オプションが渡されたら
必ず `tt(integer NORMARG)' する必要がある。そうしておかないと
変数が使われない(△???)。

訳注: 以下で登場する var(messages) は，補完寺に補完対象を説明する文
として使われるが，デフォルトでは出てこない(と思う)。

example(zstyle ':completion:*:descriptions' \ 
  format '[[Completing %B%d%b]]')

などとして説明文字列が出てくるようにしておこう。
訳注終わり。

startitem()
xitem(var(n)tt(:)var(message)tt(:)var(action))
item(var(n)tt(::)var(message)tt(:)var(action))(
第var(n)番目の普通の引数(の情報)を記述する。
var(message) は，補完候補一覧の上に表示され，
var(action) はこの位置で補完されるべきものを指示する(方法については後述)。
tt(::)とコロン2つを var(message) の前に付けた場合は，その引数が
任意(optional)であることを指示する。
また，var(message) が空白文字だけを含むときには補完候補一覧の上には
何も表示されない。ただし，var(action) で何か説明の文字列を足している
場合はそれが表示される。
)
xitem(tt(:)var(message)tt(:)var(action))
item(tt(::)var(message)tt(:)var(action))(
上記と同様。ただし，何番目かにかかわらずem(次の)引数についての
記述となる。もしすべての引数を正しい順番で書くならば，
var(n)を省略したこの書き方だけ並べればよい(□)。
)
xitem(tt(*:)var(message)tt(:)var(action))
xitem(tt(*::)var(message)tt(:)var(action))
item(tt(*:::)var(message)tt(:)var(action))(
上記2つの記法による(オプションでない)引数についての記述が
ない引数は，ここで書いた記述に従う。何番目の引数かの指定を
とくに行なわない書き方。

tt(::) とコロン2つを var(message) の前に書くと，特殊配列変数 tt(words)
と特殊変数 tt(CURRENT) は，(オプションでない)普通の引数を指すよう
var(action)実行時(評価時)に修正される。
tt(:::) とコロン3つを var(message) の前に書くと，この記法で
カバーされる普通の引数だけを指すように修正される。
(△訳注???: どういうときに役立つか分からん)
)
xitem(var(optspec))
item(var(optspec):var(...))(
補完対象のコマンドのオプションを記述する。コロンを付けた場合，
そのオプションは1つ以上の引数を取ることを意味する。コロンなしの場合，
そのオプションには引数がないことを意味する。

デフォルトではオプション名は2文字以上でもよいものとみなすが，
tt(_arguments)自身の tt(-s) を指定すると，補完対象のコマンドのオプションは
1字だけと見なす。ただし，たとえば `tt(--prefix)' のように，
tt(--) で始まるオプションはやはり1つの完全なオプション名と見なす。
これはGNU標準に適っている。

tt(-s) と tt(-w) を両方指定すると，引数を取る1字オプションが交ざっていた
としても，1字オプションどうしをまとめて指定できるものと見なす。
たとえば，あるコマンドの tt(-a) オプションが引数を1つ取るものだとして，
tt(-s)なしのとき: `tt(-ab)' はそれで1つのオプション(処理されない)，
tt(-s)ありのとき: `tt(-ab)' は1つのオプションと引数 `tt(b)'，
tt(-s) と tt(-w) のとき: `tt(-ab)' は tt(-a) オプションと
tt(-b) オプションの指定で，さらにその後引数が来るものと期待される…，
のように補完時の解釈が変わる。

これらのルール解釈は，tt(-W) を指定するともっと深遠な領域へ:
tt(-W) をつけると，同じ単語内に現れる引数のあとでも1字オプションを
補完できるようになる。しかしその位置で実際に補完が行なわれるかどうかは，
遂行される var(action) に依存する。より深く制御したい場合は
tt(_guard) のようなユーティリティ関数をアクションの一部に使うとよい。
(訳注: -W の違いが分からない…。)

さて，最初の var(optspec) で利用できる書き方を以下に示す。
オプションに引数があってもなくても構わない。

startitem()
item(tt(*)var(optspec))(
この var(optspec) は下記のいずれかである。
これは，var(optspec) が繰り返してもよいことを意味する。
通常は(繰り返しは自動的に避けられるので□)，コマンドラインの
カーソルより左側に入力済みのオプションは候補一覧から外れる。
(訳注: 複数回指定する可能性のあるオプションにはハイフンの直前に tt(*) 
を指定しておく)
)
xitem(tt(-)var(optname))
item(tt(+)var(optname))(
オプション指定の最も単純な形式で，var(optspec) にマイナスかプラスで
始まるオプションそのものを書く(例: `tt(-foo)')。オプションの最初の
引数(がもしあるならそれ)はem(別の)単語としてそのオプションの直後に来る
必要がある(△訳注: コロン要らないの?)。

`tt(-+)var(optname)' または `tt(+-)var(optname)' という形式で
書けば，tt(-)var(optname) と tt(+)var(optname) 両方のオプション指定が
有効だと指定できる。

下記のいずれの書式も，先頭の `tt(-)' は `tt(+)' に置き換えたり組み合わせたり
できる。
)
item(tt(-)var(optname)tt(-))(
そのオプションの第1引数がem(同じ単語)内でそのオプションの直後に
書くべきであることを示す。たとえば，`tt(-foo-:)var(...)' と
書くと，補完されたオプションとその引数は，`tt(-foo)var(arg)' のように
なる。
)
item(tt(-)var(optname)tt(+))(
上記と似ているが，そのオプションの第1引数は，同じ単語内のオプション直後に
来ても，次の単語に来てもよいことを示す。たとえば，
`tt(-foo+:)var(...)' の場合，補完されたオプションと引数は
`tt(-foo)var(arg)' または `tt(-foo) var(arg)' のどちらででも
指定されうることを示す。
)
item(tt(-)var(optname)tt(=))(
そのオプションの第1引数は，次の単語として指定するか，同じ単語内で
イコールで区切って指定するかどちらかであることを示す。たとえば，
`tt(-foo=)var(arg)' または `tt(-foo) var(arg)' のどちらででも
指定されうる。
)
item(tt(-)var(optname)tt(=-))(
そのオプションへの引数が必ず同一単語内でイコールを使って与えられるべき
ことを示す(訳注: 上と同じだが次の単語では不可という場合)。
)
item(var(optspec)tt([)var(explanation)tt(]))(
これまで説明した上記すべての var(optspec) には，
そのオプションの説明文字列を大括弧で括って
`tt(-q[query operation])' のように追加指定することができる。

オプション一覧表示のときに，この説明文字列をいっしょに表示するかどうかは
tt(verbose) スタイルで決定する。

説明文字列の指定がないが，tt(auto-description) スタイルがセットされていて
var(optspec) にひとつだけ引数の指定がある場合は，そのスタイルの値が表示
される。その文字列中にある
`tt(%d)' は var(optspec) の後ろにある var(optarg) の最初の var(message) 
に置き換えられる(下記参照)。
)
enditem()

オプションとして `PLUS()' や `tt(=)' 自身そのものを書きたい場合は
たとえば `tt(-\+)' のようにクォートする。

var(optspec) の後ろに続く var(optarg) は，以下のいずれかの形式で
記述する。

startitem()
xitem(tt(:)var(message)tt(:)var(action))
item(tt(::)var(message)tt(:)var(action))(
そのオプションに対する引数に関する指定: 
var(message) と var(action) は普通の引数に対する記述と同じように
処理される。コロン1つで始まるほうは必ず引数を要求し，
コロン2つのほうは引数があってもなくてもよいことを意味する。

訳注: 「オプションに対する引数があってもなくてもいい?」というのは
たとえば，configureの tt(--enable-hoge=yes) が tt(--enable-hoge) だけでも
いいような場合がある。そういう場合は

example(--enable-hoge='[Quiet]::Quiet Mode:(yes no)')

などとするとよい。訳注終わり。

そのオプションが複数の引数を必要とするなら，この記法を引数の
数だけ繰り返してよい。つまり，
tt(:)var(message1)tt(:)var(action1)tt(:)var(message2)tt(:)var(action2)
とすると2引数を取るオプションの指定となる。
)
xitem(tt(:*)var(pattern)tt(:)var(message)tt(:)var(action))
xitem(tt(:*)var(pattern)tt(::)var(message)tt(:)var(action))
item(tt(:*)var(pattern)tt(:::)var(message)tt(:)var(action))(
複数の引数の記述: 複数の引数を取るようなオプションに対する
この形式の var(optarg) は最後にだけ書くことができる(訳注:
そうでないとどこから次のオプションや残りの引数を取っていいか分からない)。
もし var(pattern) が空(つまり tt(:*:))の場合は，
コマンドラインの残りのすべての引数をここに書いた var(action)
の方法で補完することを指定する。
var(pattern) を指定した場合は，そのパターンにマッチする語を含む引数までは
var(action) で補完する。

訳注: たとえば，tt(find) の tt(-exec) オプションのように，
tt(\;) までをコマンドと見なす，のようなものはこれで指定する。
訳注終わり。

複数のコロンは普通の引数に対する `tt(*:)var(...)' と
同じように処理される -- コロン2つなら
特殊配列変数 tt(words)
と特殊変数 tt(CURRENT) は，(オプションでない)普通の引数を指すよう
var(action)実行時(評価時)に修正される。
コロン3つならそれら変数が，この記法で
カバーされる普通の引数だけを指すように修正される。
)
enditem()
)
enditem()

以上でコロンそのものを値に含ませたい場合はバックスラッシュで
クォートして `tt(\:)' のように書く。

上記いずれの書式でも，その前に括弧内に列挙したオプションや引数の番号を
置くことができる。そのオプションをコマンドラインで書いたときに
括弧内に列挙したオプションや引数を候補から外すことを意味する。
たとえば，`tt((-two -three 1)-one:...)' と書くと `tt(-one)' という
オプションを補完候補に含めると同時に，コマンドラインにそれを
書いたらそれより後ろの方では tt(-two) オプションも，`tt(-three) オプションも
第1引数で補完すべきもの，いずれも補完しないようにする。
また，`tt((-foo):)var(...)' は普通の引数の補完指定の前に
`tt(-foo)' を置いたもので，もし普通の引数を入力したあとには
tt(-foo) は補完しないことを意味する。

除外されるオプションリストには他の項目も書くことができ，
その場の指定がマッチするときには該当項目が除外されるようにできる。
アスタリスク1つ (tt(*)) は，残りの引数すべて(つまり`tt(*:...)' のような形)，
コロン1つ (tt(:)) は，普通の(オプションでない)引数すべて，
ハイフン1つ (tt(-)) は，すべてのオプションに対する指定となる。
たとえば，`tt((*))' をオプションの前に書いた場合，そのオプションが
コマンドライン中に挿入されたら，それより後ろには「残りの引数」
(上記の `tt(:*)' で始まる var(spec)) を補完しないことを意味する。
(訳注: 候補から外す目的で括弧内に列挙する指定を「除外リスト」と
呼ぶことにする。)

こうした指定の再利用を助ける目的で
上記記法の前に `tt(!)' を付ける記法が用意されている。
`tt(!)' を前置したオプションは補完されなくなる。
これが有用なケースは，引数が配列で与えられ，かつ tt(_arguments)
関数が何度も，次第により限定的なコンテクスト用に呼ばれるようなときである。
たとえば最初の呼び出しが `tt(_arguments $global_options)' で，
その後の呼び出しが `tt(_arguments !$^global_options)' という形式で
呼んだりする場合である(訳注: 降って涌いたようなこの段落何?)。

上記の一連の記法で出てきた var(action) は，補完候補をどのように生成するかを
記述する。いずれも var(action) の部分が，すべてのラベルを処理するために
tt(_all_labels) 関数を呼んで実行される(ただし `tt(->)var(string)' の
場合を除く)。関数呼び出しが新しいものを導入しない限りタグの特別な処理は
必要とされない(△ ???)。

var(action) の部分の書式は以下の通り。

startitem()
item(`tt( )' (クォートなしの空白1つ))(
その引数は必須だが，マッチを生成できないまたは生成しない方がよいもので
あることを指定する。この場合，var(message) は表示されるものの
候補一覧は表示されない。ただし，この場合でも var(message) の
終端を示すコロンは必要で，省略してよいのは var(message)，var(action)
両方とも省略する場合である。

訳注: `tt(--name:Your Name: :)' とすると tt(--name) の後ろでは補完しない。
)
item(tt(LPAR())var(item1) var(item2) var(...)tt(RPAR()))(
補完候補となる単語そのものの列挙。例:

example(tt(:foo:LPAR()foo bar baz)tt(RPAR()))
)
item(tt(((var(item1)\:var(desc1) var(...)))))(
上記と同様だが，補完候補の各単語に対する注釈を付加する。
コロンを必ずバックスラッシュでクォートすることに注意。たとえば，

example(tt(:foo:LPAR()LPAR()a\:bar b\:baz)tt(RPAR()RPAR()))

とすると，コンテクストで tt(value) タグとともに tt(description)
スタイルがセットされている場合にこれらの注釈が表示される。
)
item(tt(->)var(string))(
vindex(context, use of)
vindex(line, use of)
vindex(opt_args, use of)
この形式では，tt(_arguments) は引数とオプションの処理をして
呼出し側の関数に return するときに，状態変数をセットするようになる。
呼出し側の関数では，変数値を使って補完生成を調節できる。
これはたとえば，ステートマシンを実装する関数などで使うことができる。

`tt(->)var(string)' に遭遇すると tt(_arguments) 関数は，var(string) 
の先頭末尾の空白をすべて除去し，配列 tt(state) にすべての var(string) 
の値を入れてどんなアクションが取られるべきか分かるようにする。

ちゃんと振る舞う他の補完関数もそうだが，tt(_arguments) 関数は
デフォルトでは補完候補を追加できればゼロを，そうでなければ非ゼロを返す。
しかし，もし tt(-R) オプションを指定した場合 tt(_arguments) 関数は，
リターンコード300を返し，tt($state) の値を見て処理を切り替えるよう
呼び側関数に伝える。

tt($state) だけでなく，tt(_arguments) 関数はグローバル変数 `tt(context)'，
`tt(line)'，`tt(opt_args)' をセットする(後述)。また，
tt(PREFIX) や tt(words) のような特殊変数は変更せず，
呼び側の関数にそれらの変数の処理を完全に任せる(□)。

それゆえ，少なくとも1つ `tt(->)var(string)' を含んだ
アクションをつけて tt(_arguments) 関数を呼ぶ関数では，
適切なローカル変数宣言をしておく必要がある。つまり，

example(local context state line
typeset -A opt_args)

として，tt(_arguments) 関数がグローバル変数を変えてしまうのを防ぐ(△
使い方は???)。
)
item(tt({)var(eval-string)tt(}))(
vindex(expl, use of)
中括弧内に書かれた文字列は候補単語を生成するシェルコードとしてevalされる。
var(eval-string) 自身が開括弧でも開中括弧でも始まっていない場合それは，
実行前に別の単語に分割される。

訳注: 補完候補を生成する方法載ってないじゃん。ここでは
別の補完候補生成関数を使うか，候補を追加するための tt(compadd) 関数を
直接使う。次の例は，--time オプション(仮)に与える引数に
現在の時刻文字列を補完候補にする。

example('--time:現在時刻:{compadd `date +"%H\:%M\:%S"`}')

訳注終わり。
)
item(tt(= )var(action))(
var(action) の前に `tt(= )' (イコール記号と1つのスペース) があると，
tt(_arguments) 関数は現在のコンテクストの var(argument) フィールドの中味を
特殊配列変数 tt(words) の先頭要素の位置に挿入し，特殊変数 tt(CURRENT) 
の値をインクリメントする。
こうすることで補完コマンドラインにダミーの単語を挿入しつつも，
実際に補完が起きている場所は変えないという効果が得られる。

この手法が役立つのは，上記引数指定記述のコロン2つとコロン3つを
続けて書いたもの，つまり var(action) の操作するコマンドライン上の
単語(tt(words))を制限するものと組み合わせる場合である。
たとえば，
var(action) 自身が，限られた範囲の引数に対して tt(_arguments) を呼ぶ場合，
この手法で，二回目に tt(_arguments) が呼ばれるときの範囲に
適切なコマンド名をもぐりこませて行解析がうまくいくようにする。
)
xitem( var(word...))
item(var(word...))(
上記の var(action) 記法に当てはまらないものすべて。
 var(action) が空白で始まる場合は残りの単語群が修正されずに実行される。

空白で始まらない場合は，最初の単語の後ろにいくつかの文字列(
のちに tt(compadd) のオプションとして渡される)を追加して実行される。
これらは tt(_arguments) によって指定された $state 
が補完コマンドに正しく伝わることを保証する(△???)。

これらの付加的な引数は配列変数 `tt(expl) から取得される。
この変数は var(action) を実行する前に設定され，
その中で参照されうる。

訳注: よーわからん。飛ばす。でも便利そうだ。あとで。

They ensure that the state specified by tt(_arguments), in
particular the descriptions of options and arguments, is correctly passed
to the completion command.  These additional arguments
are taken from the array parameter `tt(expl)'; this will be set up
before executing the var(action) and hence may be referred to inside it,
typically in an expansion of the form `tt($expl[@])' which preserves empty
elements of the array.
)
enditem()

var(action) 実行時に設定される変数について示す。

配列 `tt(line)' は，コマンドライン中にあるコマンド名とその普通の
引数を集めたもの，つまりすべてのオプションとオプションの引数を取り除いた
ものとなる。

連想配列 `tt(opt_args)' にはオプションが代入される。このとき，オプション名
はキー，その引数は値(バリュー)として入る。引数を2つ以上取るオプションの引
数は1つの文字列にコロン区切りで格納される。引数の値にコロンが含まれていた
ときはバックスラッシュでエスケープされる。

変数 `tt(context)' は，`tt(->)var(string)' の形式の tt(action) を
実行するために呼び側の関数に戻るときにセットされる。
それには tt($state) に対応した配列がセットされる。
各要素はコンテクストの var(argument) フィールドに適した名前，
つまり，`tt(option)var(-opt)tt(-)var(n)' という値であれば
それは var(-opt) というオプションの var(n)番目の引数，
`tt(argument-)var(n)' という値であればそれは var(n)番目の引数，
という風になる。
「残りの」引数，つまりリストの最後で位置指定なしで定義されているもの
に関しては，var(n) は文字列 `tt(rest)' になる。

たとえば，あるコマンドの tt(-o) オプションに対する引数の補完中なら
`tt(option-o-1)'，普通の(オプションでない)第2引数なら `tt(argument-2)'
という具合にセットされる。

さらに，var(action) の評価中は tt(curcontext) 変数のコンテクスト名には，
tt(context) 変数に入れられるのと同じ文字列が足される(△未確認)。

(訳注: さて，コマンドにはつけるオプションによって文法が
かなり変わるものがある。そのような場合，オプションと引数の組み合わせを
グループ化して別々に管理することができる。)
オプションと引数の組み合わせのセットを，1つのハイフンで区切って
複数持たせることも可能である。その場合，最初のハイフンまでに
書いたセットは，残りのセットすべてで共有される。
2つ目以降のセットの記述の単語はそのセットの名前を意味し，
それを上述の「除外リスト」に書くことができる(□)。名前は
単独で書いてもよいし，上で述べられている possible values の
どれか1つの前でもよい(△訳注: described aboveってどれだよ。
aboveとbelowばっかでまったくわからんぞ)。
後者の場合は `tt(-)' をその名前と残りの名前の間に書く必要がある。

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 exclusion lists in specifications,
either alone or before one of the possible values described above.
In the second case a `tt(-)' should appear between this name and the
remainder.

例を示す。

example(_arguments \ 
    -a \ 
  - set1 \ 
    -c \ 
  - set2 \ 
    -d \ 
    ':arg:(x2 y2)')

は，2つのセットを定義している。コマンドラインが `tt(-c)' を
含むときは，`tt(-d)' オプションと `':arg:(x2 y2)'' により期待される引数
は補完候補にはならない。逆に，`tt(-d)' オプションや引数が入力された
場合は `tt(-c)' オプションが候補から外れる。しかし，`tt(-a)' の後ろでは
いずれの場合も有効なオプションと見なされる。

ハイフンで分割したセットは互いに排他的な補完関係となるが，
セット間の排他だけでなくセット内の排他も同時に指定できる。
セット名を `tt(LPAR())var(name)tt(RPAR())' のように括弧で括って
書くと，そのセットの中の補完候補は，そのセット内の他の候補に対しても
別のセットの候補に対しても排他的となる。つまり，
複数のセットの中から，選ばれるものはただひとつという関係を書ける。
これは，排他的なオプションにエイリアスがある場合などに有用で，

example(_arguments \ 
    -a -b \ 
  - '(compress)' \ 
    {-c,--compress}'[compress]' \ 
  - '(uncompress)' \ 
    {-d,--decompress}'[decompress]')

と書くと，compress セットと uncompress セットは同時には補完されず，
なおかつ compress セットで補完する場合も `tt(-c)' と `tt(--compress)'
は同時には補完されなくなる(□この段落原文から相当変えた)。

もっとも，複数のセットを持たせると補完のためのコードがそれぞれ
別々に解析しなければならないので遅くなることからどうしても必要な場合
以外は使用を控えるのが望ましい(□)。別解としては，
排他的な関係を持つオプションの指定を `tt(-foo:*:...)' のように
書いて，残りの引数をすべて rest-arguments として読み切ってもらう
方法がある(□)。

tt(_arguments) 関数のオプションについて列挙する(□)。

tt(-S) オプション: `tt(-)tt(-)' をオプションの終わりと自動判定する。
たとえば，

example(foobar -a -- -b)

にある `tt(-b)' は引数と見なされる。`tt(-)tt(-)' 自身は引数とも
オプションとも見なされない。

tt(-A)オプション: オプションでない引数の後ろではオプションの補完を
やめる。与えた単語が普通の引数でないと判断するためのパターンを 
tt(-A) オプションの引数として指定する。たとえば，var(optspec) に
オプションとして登録していないものでも「ハイフンで始まるものは
なんでも普通の引数と見なさない」のであれば，`tt(-A "-*")' と
指定する。

tt(-O) オプション: `tt(-O) var(name)' のように指定し，
var(action) を実行するために呼ばれる関数群に，var(name)という名の
配列変数に含まれる要素を引数として渡す。これはたとえば，すべての
var(action) に対して共通の「tt(compadd)用オプション」を渡したいとき
などに有用(△??? 例をクレー)。

tt(-M) オプション: 'tt(-M) var(spec)' のように指定し，
オプション名と値の補完時の「マッチ仕様」を決める。(訳注: 「マッチ仕様」
は zshcompwid(1) に)

この指定は最初のオプション仕様記述の前に来なければならない。デフォルト値は
`tt(r:|[_-]=* r:|=*)' で，これは `tt(_)' と `tt(-)' の後ろでは
「部分マッチ」を許可することを意味する。たとえば，
`-f-b' を補完したときは `-f*-b*' というパターンにマッチするもので
補完するので `tt(-foo-bar)' などに補完されうる(□)。

tt(-C) オプション:  `tt(->)var(state)' のアクションを使う場合に
tt(curcontext) 変数の値をその場に応じた値に変える
よう tt(_arguments) に指示する。この変数は現在の
コンテクストに追随するための変数で，これを使用する関数では
修正した値を返してしまったりすることのないようローカル変数化し，
以下のようにして正しく初期値設定する必要がある。

example(local curcontext="$curcontext")

複数の state を同時に当てはめることができないときなどに有用(△???実例を
クレー)。
This is useful where it is not possible for multiple states to be valid
together.

訳注: 例えば tt(cmd) というコマンド引数での補完で tt(_arguments) を使い，
その中に tt('-foo:foo option:->foo') があったとする。
tt(-foo) オプション
を入力し終えその引数位置で呼ばれたときの tt($curcontext) が
tt(:complete:cmd:option-foo-1) となる。
tt(-C) なしだと tt(:complete:cmd:) のまま変わらない。
訳注終わり。

`tt(-)tt(-)' オプション: (□)GNUのコマンドのオプション流儀のおまかせオプション。
`tt(-)tt(-help)' というオプションでヘルプ出力が出てくるようなものに対し
その出力を取り込んでオプション解析を自動で行なう。もちろん，
ヘルプ出力にちゃんと対応していないコマンドにこれを使うと危険。

対象コマンドのオプションそのものだけでなく，
`tt(-)tt(-)var(opt)=var(val)' という書き方が正当と見なされるオプションなら
そのオプションの引数の種別の推測も試みる。
完全自動での推測がうまくいかない場合はヒントを与えて，
ヘルプ出力から，あるオプションの引数の種別を推測しやすくすることもできる。
ヒントは `var(pattern)tt(:)var(message)tt(:)var(action)' 
という形式で与える(通常の引数使用指定は使われない点に注意)。

var(pattern) のマッチングはヘルプ出力中の，あるオプションに対する説明文に
対して適用され，マッチした場合はそのオプションの引数補完時には，
指定した var(message) と var(action) が利用される。

たとえば，

example(_arguments -- '*\*:toggle:(yes no)' \ 
              '*=FILE*:file:_files' \ 
              '*=DIR*:directory:_files -/' \ 
              '*=PATH*:directory:_files -/')

とすると，ヘルプ行の説明文がアスタリスクで終わってるものの引数は
`tt(yes)' と `tt(no)' で，
`tt(=FILE)' という文字列が含まれているものの引数はファイルで，
`tt(=DIR)' や `tt(=PATH)' が含まれているものの引数はディレクトリで補完する。
実は最後の3つはデフォルトで組み込まれているので明示的に与える必要はない。
よくあるヘルプ行の例として

example(  -C, --directory=DIR          change to directory DIR)

のようなものがあるが，これだと
`tt(-)tt(-directory)' の引数はディレクトリを補完するが
`tt(-C)' の後ろではうまくいかない。

また，tt(_arguments) はオプションの引数が任意かどうかも推測するが
明示的に指定したい場合はヒントのところで var(message) の前のコロンを
2個にすればよい。

var(pattern) が `tt((-))' で終わっている場合は………パス，
If the var(pattern) ends in `tt((-))', this will removed from the
pattern and the var(action) will be used only directly after the
`tt(=)', not in the next word.  This is the behaviour of a normal
specification defined with the form `tt(=-)'.

`tt(_arguments -)tt(-)' には，それ専用の追加オプションがある(ここから□)。

tt(-)tt(-) tt(-i) オプション: 解析に使うヘルプ出力中で
無視すべきパターンを指定する。たとえば，configure オプションなどで
一般的な記法の説明として

example(--enable-FEATURE    not include FEATURE...)

のような行があったりする。これは抽象例であって実際のオプションではないので
無視したい。このようなときは，無視したいパターンを与える。たとえば，


example(_arguments -- -i \ 
    "LPAR()-tt(-(en|dis)able-FEATURE*RPAR()"))

とすると，`tt(-)tt(-enable-FEATURE)' と `tt(-)tt(-disable-FEATURE)' 
というオプションは無視する。


tt(-)tt(-) tt(-s) オプション: `tt(-s) var(pair)' の形で指定して，
オプションエイリアスを定義する。
var(pair) の部分にはパターンとその置き換え語を指定する。
たとえば，tt(configure) の
ヘルプ出力には `tt(-)tt(-enable-foo)' の説明しかないにもかかわらず
実際には `tt(-)tt(-disable-foo)' も容認される。このような場合は，

example(_arguments -- -s "LPAR()#-tt(-enable- -)tt(-disable-RPAR()"))

とするることで，`tt(-)tt(-disable-*)' のほうも補完されるようになる。
(ここまで□)

ここで  tt(_arguments) 関数の一般的な使用例を示す。

example(_arguments '-l+:left border:' \ 
           '-format:paper size:(letter A4)' \ 
           '*-copy:output file:_files::resolution:(300 600)' \ 
           ':postscript file:_files -g \*.\(ps\|eps\)' \ 
           '*:page number:')

この例は，ここで定義している関数が補完するコマンドのオプションにある，
`tt(-l)'，`tt(-format)'，`tt(-copy)' の3つのオプションについて記述している。
最初のものは引数をひとつ取り，引数補完時に使う説明として 
`var(left border)' を使い，補完候補は何も提示しないよう指定している。
また `tt(+)' の指定があるので，`tt(-l)' オプションの引数は
`tt(-l)' にくっつけて書いても，次の引数に書いてもよいことを意味している。

次の `tt(-format)' は，説明文字列を `var(paper size)' にし，
補完候補を `tt(letter)' と `tt(A4)' にしている。

`tt(-copy)' オプションは `tt(*)' によって，そのオプションがコマンドラインに
何回現れても補完することを意味し，また `output file' と
`ressolution' に相当する2つの引数を取ることを意味している。ただし，
2つ目の引数は省略可能である(コロンが2つ)。

最後の2つは，そのコマンドの普通の(オプションでない)引数として
補完されることを意味している。第1引数では説明文字列を
`postscript files' として，ファイル名が `tt(ps) か `tt(eps)' で
終わるものを補完する。
最後の記述は，残りすべての引数で，説明文字列を `page numbers' として
補完せずに入力させることを意味している。
)
findex(_cache_invalid)
item(tt(_cache_invalid) var(cache_identifier))(
補完キャッシュの再構築が必要なときにゼロを返す。
現在のコンテクストの tt(cache-policy) スタイルを参照して判定を下す。

This should provide a function name which is run with the full path to the
relevant cache file as the only argument.

Example:

example(_example_caching_policy () {
    # rebuild if cache is more than a week old
    oldp=( "$1"(Nmw+1) )
    (( $#oldp ))
})
)
findex(_call_function)
item(tt(_call_function) var(return) var(name) [ var(args) ... ])(
関数 var(name) が定義されていれば，引数 var(args) を付けて呼び，
終了コードを変数 var(return) に格納する。 var(return) を空にするか
ハイフンにすると無視される。

tt(_call_function) 関数自身の終了コードは，
関数 var(name) が存在して呼べたらゼロ，そうでなければ非ゼロとなる。
)
findex(_call_program)
item(tt(_call_program) var(tag) var(string) ...)(
訳注: ★これ結構重要なのになー★。

外部コマンドを呼ぶ。ただ呼ぶだけでなく，
ユーザが呼び出すべき外部コマンドをオーバーライドしやすいような
機構を備えている。とくに指定がなければ var(string) を外部コマンドとして
呼び出し，その終了コードを返す。ただし，var(tag) に対する tt(command) 
スタイルが定義されている場合はその値(文字列)を外部コマンドとして呼び出す。
呼び出したコマンドからの出力は，スペース区切りで連結される。

訳注: 例: cvs のサブコマンド名一覧は `tt(cvs --help-commands)' として
得ている。でも「commit じゃなくて ci がいい!」と思っているなら
外部コマンド呼び出しを変えてしまえばよい。
tt(_cvs) 関数定義には，

example($(_call_program commands cvs --help-commands 2>&1))

という部分があるが，これは，tt(':completion:*:cvs:*:commands') 
コンテクストの tt(command) タグで上書きできるので，
cvs 本来のヘルプ画面の `commit' を `ci' に置換したヘルプ画面を
出すような偽コマンド(仮に cvshelpfake とする)を作っておいて，

example(zstyle ':completion:*:cvs:*:commands' \ 
command cvshelpfake)

などとしておく。
tt(_cvs) の場合，cvs のサブコマンドを
初めて補完するときにこのコマンドを呼ぶのでコンテクストのコマンド名の
ところがちゃんと `tt(cvs)' になっているが，補完定義によっては
空だったり，別のコマンド名だったりする場合があるので注意が必要。
訳注終わり。
)
findex(_combination)
item(tt(_combination) [ tt(-s) var(pattern) ] var(tag) var(style) var(spec) ... var(field) var(opts) ...)(
「ホスト名とユーザ名」などのように，複数の値の組み合わせの補完を
行なうときに使う。
var(style) の部分には構成すべきペアのスタイルを指定する。
このスタイルは var(tag) が指定されたコンテクストで照合される。

スタイル名はたとえば，
`tt(users-hosts-ports)' のように，
フィールド名をハイフンで区切ったもので構成される。

値が既に確定しているものに対するフィールドには
`var(field)tt(=)var(pattern)' という書式の var(spec) が与えられる。
たとえば，もしそれまで入力したコマンドラインでユーザ `tt(pws)' を
指定したならば，`tt(users=pws)' という引数が現れるべきである。

訳注: ようするに var(spec) 引数は(普通は)補完時に動的に生成されるもので，
tt(_combination) を呼び出すときには
コマンドライン上に入力したユーザ名やホスト名を自動的に取得して，
それを使って `tt(users=pws)' のような var(spec) をそこに生成すると，
ユーザが `tt(pws)' に合致するようなホスト(とそのポート)だけを
補完候補に選んでくれる。

この関数の使い方については tt(_combination) 関数を定義している
ファイルの使用例を見るのがいちばん速い。ここは読んでも分からん。
てことで，飛ばす。訳注終わり。

The matches generated will be taken from the value of the style.  These
should contain the possible values for the combinations in the appropriate
order (users, hosts, ports in the example above).  The different fields
the values for the different fields are separated by colons.  This
can be altered with the option tt(-s) to tt(_combination) which specifies a
pattern.  Typically this is a character class, as for example
`tt(-s "[:@]")' in the case of the tt(users-hosts) style.    Each
`var(field)tt(=)var(pattern)' specification restricts the
completions which apply to elements of the style with appropriately
matching 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 `tt(users-hosts-ports)' or no
matching hostname when a host is required, the function `tt(_hosts)' will
automatically be called.

If the same name is used for more than one field, in both the
`var(field)tt(=)var(pattern)' and the argument that gives the name of the
field to be completed, the number of the field (starting with one) may
be given after the fieldname, separated from it by a colon.

All arguments after the required field name are passed to
tt(compadd) when generating matches from the style value, or to 
the functions for the fields if they are called.
)
findex(_describe)
item(tt(_describe) [ tt(-oO) | tt(-t) var(tag) ] var(descr) var(name1) [ var(name2) ] var(opts) ... tt(-)tt(-) ...)(
この関数は補完候補と説明文字列を関連付ける。

This function associates completions with descriptions.
Multiple groups separated by tt(-)tt(-) can be supplied, potentially with
different completion options var(opts).

var(descr) は候補一覧の上に出る説明文字列で，これは
tt(descriptions) タグに対する tt(format) スタイルが定義されているときに
表示される。
var(descr) の後ろには，1個か2個の配列変数の名前が続き，
さらに後ろに tt(compadd) に渡すオプションが続く。
1個目の配列は，補完候補の単語とそれに対する説明文字列を
`var(completion)tt(:)var(description)' の書式で書いた要素を含むもの
である。
2個目の配列は，1個目の配列と要素数が同じもので，
1個目配列に対応する補完候補単語として var(completion) の代わりに
2個目配列の対応する要素を追加する(△どういうときに役立つの???)。
説明文字列は1個目の配列にあったものがそのまま残る。

配列の後ろにはいくつかのオプションを指定する。
Finally, a set of completion options can appear.

最初の引数の前に `tt(-o)' オプションを指定すると，追加する候補を
そのコマンドのオプションとして扱うようにする。典型的には
コマンドライン上で `tt(-)'，`tt(-)tt(-)'，`tt(+)' に続けて書くものとして，
それらの文字が入力されない限り一覧や説明文字列が出ない(□)。
厳密には tt(prefix-hidden), tt(prefix-needed), tt(verbose) スタイル
すべてを参照して，その補完候補を一覧に含めるか決める(□)。
`tt(-o)' の代わりに(□訳注: 原文にtypo)
`tt(-O)' オプションにすると，tt(prefix-needed) スタイルは無視する。

`tt(-t)' オプションは var(tag) を指定する。指定しないときの
デフォルトのタグは，tt(-o) オプションを指定したときには `tt(options)' 
で，そうでないときは `tt(values)' である。

If selected by the tt(list-grouped) style, strings with the same
description will appear together in the list.

tt(_describe) uses the tt(_all_labels) function to generate the matches, so
it does not need to appear inside a loop over tag labels.
)
findex(_description)
item(tt(_description) [ tt(-x) ] [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(spec) ... ])(

kokomade
This function is not to be confused with the previous one; it is used as
a helper function for creating options to tt(compadd).  It is buried
inside many of the higher level completion functions and so often does
not need to be called directly.

The styles listed below are tested in the current context using the
given var(tag).  The resulting options for tt(compadd) are put into the
array named var(name) (this is traditionally `tt(expl)', but this
convention is not enforced).  The description for the corresponding set
of matches is passed to the function in var(descr).

The styles tested are: tt(format), tt(hidden), tt(matcher),
tt(ignored-patterns) and tt(group-name).  The tt(format) style is first
tested for the given var(tag) and then for the tt(descriptions) tag if
no value was found, while the remainder are only tested for the tag
given as the first argument.  The function also calls tt(_setup)
which tests some more styles.

The string returned by the tt(format) style (if any) will be modified so
that the sequence `tt(%d)' is replaced by the var(descr) given as the third
argument without any leading or trailing white space.  If, after
removing the white space, the var(descr) is the empty string, the format
style will not be used and the options put into the var(name) array will
not contain an explanation string to be displayed above the matches.

If tt(_description) is called with more than three arguments,
the additional var(spec)s should be of the form `var(char)tt(:)var(str)'.
These supply escape sequence replacements for the tt(format) style:
every appearance of `tt(%)var(char)' will be
replaced by var(string).

If the tt(-x) option is given, the description will be passed to
tt(compadd) using the tt(-x) option instead of the default tt(-X).  This
means that the description will be displayed even if there are no
corresponding matches.

The options placed in the array var(name) take account of the
tt(group-name) style, so matches are placed in a separate group where
necessary.  The group normally has its elements sorted (by passing the
option tt(-J) to tt(compadd)), but if an option starting with `tt(-V)',
`tt(-J)', `tt(-1)', or `tt(-2)' is passed to tt(_description), that
option will be included in the array.  Hence it is possible for the
completion group to be unsorted by giving the option `tt(-V)',
`tt(-1V)', or `tt(-2V)'.

In most cases, the function will be used like this:

example(local expl
_description files expl file
compadd "$expl[@]" - "$files[@]")

Note the use of the parameter tt(expl), the hyphen, and the list of
matches.  Almost all calls to tt(compadd) within the completion system use
a similar format; this ensures that user-specified styles are correctly
passed down to the builtins which implement the internals of completion.
)
findex(_dispatch)
item(tt(_dispatch) var(context string ...))(
This sets the current context to var(context) and looks for completion
functions to handle this context by hunting through the list of command
names or special contexts (as described above for tt(compdef))
given as var(string ...).  The first completion function to be defined
for one of the contexts in the list is used to generate matches.
Typically, the last var(string) is tt(-default-) to cause the function
for default completion to be used as a fallback.

The function sets the parameter
tt($service) to the var(string) being tried, and sets
the var(context/command) field (the fourth) of the tt($curcontext)
parameter to the var(context) given as the first argument.
)
findex(_files)
item(tt(_files))(
The function tt(_files) calls tt(_path_files) with all the arguments it
was passed except for tt(-g) and tt(-/).  The use of these two options
depends on the setting of the  tt(file-patterns) style.

This function accepts the full set of options allowed by
tt(_path_files), described below.
)
findex(_gnu_generic)
item(tt(_gnu_generic))(
This function is a simple wrapper around the tt(_arguments) function
described above.  It can be used to determine automatically the long
options understood by commands that produce a list when passed the
option `tt(-)tt(-help)'.  It is intended to be used as a top-level
completion function in its own right.  For example, to enable option
completion for the commands tt(foo) and tt(bar), use

example(compdef _gnu_generic foo bar)

after the call to tt(compinit).

The completion system as supplied is conservative in its use of this
function, since it is important to be sure the command understands the
option `tt(-)tt(-help)'.
)
findex(_guard)
item(tt(_guard) [ var(options) ] var(pattern descr))(
This function is intended to be used in the var(action) for
the specifications passed to tt(_arguments) and similar functions.  It
returns immediately with a non-zero return status if
the string to be completed does not match the var(pattern).  If the
pattern matches, the var(descr) is displayed; the function then returns
status zero if the word to complete is not empty, non-zero otherwise.

The var(pattern) may be preceded by any of the options understood by
tt(compadd) that are passed down from tt(_description), namely tt(-M),
tt(-J), tt(-V), tt(-1), tt(-2), tt(-n), tt(-F) and tt(-X).  All of these
options will be ignored.  This fits in conveniently with the
argument-passing conventions of actions for tt(_arguments).

As an example, consider a command taking the options tt(-n) and
tt(-none), where tt(-n) must be followed by a numeric value in the
same word.  By using:

example(_arguments '-n-: :_guard "[0-9]#" "numeric value"' '-none')

tt(_arguments) can be made to both display the message `tt(numeric
value)' and complete options after `tt(-n<TAB>)'.  If the `tt(-n)' is
already followed by one or more digits (the pattern passed to
tt(_guard)) only the message will be displayed; if the `tt(-n)' is
followed by another character, only options are completed.
)
findex(_message)
xitem(tt(_message) [ tt(-r12) ] [ tt(-VJ) var(group) ] var(descr))
item(tt(_message -e) [ var(tag) ] var(descr))(
tt(_description) 関数の第3引数と同様に
var(descr) を説明文字列として使用する。ただしこちらは，
マッチするものがあってもなくても表示される。
補完すべきものがないときのヘルプメッセージを出すときに有用。

The tt(format) style is examined with the tt(messages) tag to find a
message; the usual tag, tt(descriptions), is used only if the style is
not set with the former.

If the tt(-r) option is given, no style is used; the var(descr) is
taken literally as the string to display.  This is most useful
when the var(descr) comes from a pre-processed argument list
which already contains an expanded description.

The tt(-12VJ) options and the var(group) are passed to tt(compadd) and
hence determine the group the message string is added to.

The second form gives a description for completions with the tag
var(tag) to be shown even if there are no matches for that tag.  The tag
can be omitted and if so the tag is taken from the parameter
tt($curtag); this is maintained by the completion system and so is
usually correct.
)
findex(_multi_parts)
item(tt(_multi_parts) var(sep) var(array))(
The argument var(sep) is a separator character.
The var(array) may be either the
name of an array parameter or a literal array in the form
`tt(LPAR()foo bar)tt(RPAR())', a parenthesised list of words separated
by whitespace.  The possible completions are the
strings from the array.  However, each chunk delimited by var(sep) will be
completed separately.  For example, the tt(_tar) function uses
`tt(_multi_parts) tt(/) var(patharray)' to complete partial file paths
from the given array of complete file paths.

The tt(-i) option causes tt(_multi_parts) to insert a unique match even
if that requires multiple separators 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 `tt(-V)',
`tt(-J)', `tt(-1)', `tt(-2)', `tt(-n)', `tt(-f)', `tt(-X)', `tt(-M)',
`tt(-P)', `tt(-S)', `tt(-r)', `tt(-R)', and `tt(-q)' options and passes
them to the tt(compadd) builtin.
)
findex(_next_label)
item(tt(_next_label) [ tt(-x) ] [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(options) ... ])(
This function is used to implement the loop over different tag
labels for a particular tag as described above for the tt(tag-order)
style.  On each call it checks to see if there are any more tag labels; if
there is it returns status zero, otherwise non-zero.
As this function requires a current tag to be set, it must always follow
a call to tt(_tags) or tt(_requested).

The tt(-x12VJ) options and the first three arguments are passed to the
tt(_description) function.  Where appropriate the var(tag) will be
replaced by a tag label in this call.  Any description given in
the tt(tag-order) style is preferred to the var(descr) passed to
tt(_next_label).

The var(options) given after the var(descr)
are set in the parameter given by var(name), and hence are to be passed
to tt(compadd) or whatever function is called to add the matches.

Here is a typical use of this function for the tag tt(foo).  The call to
tt(_requested) determines if tag tt(foo) is required at all; the loop
over tt(_next_label) handles any labels defined for the tag in the
tt(tag-order) style.

example(local expl ret=1
...
if _requested foo; then
  ...
  while _next_label foo expl '...'; do
    compadd "$expl[@]" ... && ret=0
  done
  ...
fi
return ret)
)
findex(_normal)
item(tt(_normal))(
This is the standard function called to handle completion outside
any special var(-context-).  It is called both to complete the command
word and also the arguments for a command.  In the second case,
tt(_normal) looks for a special completion for that command, and if
there is none it uses the completion for the tt(-default-) context.

A second use is to reexamine the command line specified by the tt($words)
array and the tt($CURRENT) parameter after those have been modified.
For example, the function tt(_precommand), which
completes after pre-command specifiers such as tt(nohup), removes the
first word from the tt(words) array, decrements the tt(CURRENT) parameter,
then calls tt(_normal) again.  The effect is that `tt(nohup) var(cmd ...)'
is treated in the same way as `var(cmd ...)'.

If the command name matches one of the patterns given by one of the
options tt(-p) or tt(-P) to tt(compdef), the corresponding completion
function is called and then the parameter tt(_compskip) is
checked.  If it is set completion is terminated at that point even if
no matches have been found.  This is the same effect as in the
tt(-first-) context.
)
findex(_options)
item(tt(_options))(
This can be used to complete the names of shell options.  It provides a
matcher specification that ignores a leading `tt(no)', ignores
underscores and allows upper-case letters to
match their lower-case counterparts (for example, `tt(glob)',
`tt(noglob)', `tt(NO_GLOB)' are all completed).  Any arguments
are propagated to the tt(compadd) builtin.
)
findex(_options_set)
findex(_options_unset)
item(tt(_options_set) and tt(_options_unset))(
These functions complete only set or unset options, with the same
matching specification used in the tt(_options) function.

Note that you need to uncomment a few lines in the tt(_main_complete)
function for these functions to work properly.  The lines in question
are used to store the option settings in effect before the completion
widget locally sets the options it needs.  Hence these functions are not
generally used by the completion system.
)
findex(_parameters)
item(tt(_parameters))(
This is used to complete the names of shell parameters.

The option `tt(-g var(pattern))' limits the completion to parameters
whose type matches the var(pattern).  The type of a parameter is that
shown by `tt(print ${(t))var(param)tt(})', hence judicious use of
`tt(*)' in var(pattern) is probably necessary.

All other arguments are passed to the tt(compadd) builtin.
)
findex(_path_files)
item(tt(_path_files))(
This function is used throughout the completion system
to complete filenames.  It allows completion of partial paths.  For
example, the string `tt(/u/i/s/sig)' may be completed to
`tt(/usr/include/sys/signal.h)'.

The options accepted by both tt(_path_files) and tt(_files) are:

startitem()
item(tt(-f))(
Complete all filenames.  This is the default.
)
item(tt(-/))(
Specifies that only directories should be completed.
)
item(tt(-g) var(pattern))(
Specifies that only files matching the var(pattern) should be completed.
)
item(tt(-W) var(paths))(
Specifies path prefixes that are to be prepended to the string from the
command line to generate the filenames but that should not be inserted
as completions nor shown in completion listings.  Here, var(paths) may be
the name of an array parameter, a literal list of paths enclosed in
parentheses or an absolute pathname.
)
item(tt(-F) var(ignored-files))(
This behaves as for the corresponding option to the tt(compadd) builtin.
It gives direct control over which
filenames should be ignored.  If the option is not present, the
tt(ignored-patterns) style is used.
)
enditem()

Both tt(_path_files) and tt(_files) also accept the following options
which are passed to tt(compadd): `tt(-J)', `tt(-V)',
`tt(-1)', `tt(-2)', `tt(-n)', `tt(-X)', `tt(-M)', `tt(-P)', `tt(-S)',
`tt(-q)', `tt(-r)', and `tt(-R)'.

Finally, the tt(_path_files) function  uses the styles tt(expand),
tt(ambiguous), tt(special-dirs), tt(list-suffixes) and tt(file-sort)
described above.
)
findex(_pick_variant)
item(tt(_pick_variant [ tt(-c) var(command) ] [ tt(-r) var(name) ] var(label)tt(=)var(pattern) ... var(label) [ var(args) ... ]))(
tt(compdef) 関数中で
1つのコマンド名で複数の補完バリエーションを持たせるときに使う。
現在補完中のコマンド名に，引数の最後に指定した var(args) を与えて
起動して，その出力に var(pattern) にマッチするものがあればそれに対応する
var(label) を選ぶ。
tt(-r) で変数を指定した場合には，それに選ばれたラベルが代入される。
起動コマンド名を変える場合は tt(-c) オプションを使う。
指定したパターンにマッチしなければ，最後に指定したデフォルトのラベル
var(label) が選ばれて，終了コードが1となる。

この結果は var(_cmd_variant) 連想配列変数にキャッシュされる。
訳注: 原文面影なし。
)
findex(_regex_arguments)
item(tt(_regex_arguments) var(name) var(spec) ...)(
This function generates a completion function var(name) which matches
the specifications var(spec) tt(...), a set of regular expressions as
described below.  After running tt(_regex_arguments), the function
var(name) should be called as a normal completion function.
The pattern to be matched is given by the contents of
the tt(words) array up to the current cursor position joined together
with null characters; no quotation is applied.

The arguments are grouped as sets of alternatives separated by `tt(|)',
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 arbitrary depth by using parentheses; matching proceeds from
inside to outside.

COMMENT(I think I've got this wrong, but I can't think what else it
could mean.  Actually, it still doesn't mean very much.)\
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 remaining word and any
var(action)s for the corresponding patterns are executed.  In this case,
nothing is stripped from the command line string.  The order of
evaluation of the var(action)s can be determined by the tt(tag-order)
style; the various formats supported by tt(_alternative) can be used
in var(action).  The var(descr) is used for setting up the array
parameter tt(expl).

Specification arguments take one of following forms, in which
metacharacters such as `tt(LPAR())', `tt(RPAR())', `tt(#)' and `tt(|)'
should be quoted.

startitem()
item(tt(/)var(pattern)tt(/) [tt(%)var(lookahead)tt(%)] [tt(-)var(guard)] [tt(:)var(tag)tt(:)var(descr)tt(:)var(action)])(
This is a single primitive component.
The function tests whether the combined pattern
`tt((#b)LPAR()(#B))var(pattern)tt(RPAR())var(lookahead)tt(*)' matches
the command line string.  If so, `var(guard)' is evaluated and
its return status is examined to determine if the test has succeeded.
The var(pattern) string `tt([])' is guaranteed never to match.
The var(lookahead) is not stripped from the command line before the next
pattern is examined.

The argument starting with tt(:) is used in the same manner as an argument to
tt(_alternative).

A component is used as follows: var(pattern) is tested to
see if the component already exists on the command line.  If
it does, any following specifications are examined to find something to
complete.  If a component is reached but no such pattern exists yet on the
command line, the string containing the var(action) is used to generate
matches to insert at that point.
)
item(tt(/)var(pattern)tt(/+) [tt(%)var(lookahead)tt(%)] [tt(-)var(guard)] [tt(:)var(tag)tt(:)var(descr)tt(:)var(action)])(
This is similar to `tt(/)var(pattern)tt(/) ...' but the left part of the
command line string (i.e. the part already matched by previous patterns)
is also considered part of the completion target.
)
item(tt(/)var(pattern)tt(/-) [tt(%)var(lookahead)tt(%)] [tt(-)var(guard)] [tt(:)var(tag)tt(:)var(descr)tt(:)var(action)])(
This is similar to `tt(/)var(pattern)tt(/) ...' but the var(action)s of the
current and previously matched patterns are ignored even if the
following `var(pattern)' matches the empty string.
)
item(tt(LPAR()) var(spec) tt(RPAR()))(
Parentheses may be used to groups var(spec)s; note each parenthesis
is a single argument to tt(_regex_arguments).
)
item(var(spec) tt(#))(
This allows any number of repetitions of var(spec).
)
item(var(spec) var(spec))(
The two var(spec)s are to be matched one after the other as described
above.
)
item(var(spec) tt(|) var(spec))(
Either of the two var(spec)s can be matched.
)
enditem()

The function tt(_regex_words) can be used as a helper function to
generate matches for a set of alternative words possibly with
their own arguments as a command line argument.

Examples:

example(_regex_arguments _tst /$'[^\0]#\0'/ \ 
/$'[^\0]#\0'/ :'compadd aaa')

This generates a function tt(_tst) that completes tt(aaa) as its only
argument.  The var(tag) and var(description) for the action have been
omitted for brevity (this works but is not recommended in normal use).
The first component matches the command word, which is arbitrary; the
second matches  any argument.  As the argument is also arbitrary, any
following component would not depend on tt(aaa) being present.

example(_regex_arguments _tst /$'[^\0]#\0'/ \ 
/$'aaa\0'/ :'compadd aaa')

This is a more typical use; it is similar, but any following patterns
would only match if tt(aaa) was present as the first argument.

example(_regex_arguments _tst /$'[^\0]#\0'/ \( \ 
/$'aaa\0'/ :'compadd aaa' \ 
/$'bbb\0'/ :'compadd bbb' \) \#)

In this example, an indefinite number of command arguments may be
completed.  Odd arguments are completed as tt(aaa) and even arguments
as tt(bbb).  Completion fails unless the set of tt(aaa) and tt(bbb)
arguments before the current one is matched correctly.

example(_regex_arguments _tst /$'[^\0]#\0'/ \ 
\( /$'aaa\0'/ :'compadd aaa' \| \ 
/$'bbb\0'/ :'compadd bbb' \) \#)

This is similar, but either tt(aaa) or tt(bbb) may be completed for
any argument.  In this case tt(_regex_words) could be used to generate
a suitable expression for the arguments.

)
findex(_regex_words [ tt(-t) var(term) ])
item(tt(_regex_words) var(tag) var(description) var(spec) ...)(
This function can be used to generate arguments for the
tt(_regex_arguments) command which may be inserted at any point where
a set of rules is expected.  The var(tag) and var(description) give a
standard tag and description pertaining to the current context.  Each
var(spec) contains two or three arguments separated by a colon: note
that there is no leading colon in this case.

Each var(spec) gives one of a set of words that may be completed at
this point, together with arguments.  It is thus roughly equivalent to
the tt(_arguments) function when used in normal (non-regex) completion.

The part of the var(spec) before the first colon is the word to be
completed.  This may contain a tt(*); the entire word, before and after
the tt(*) is completed, but only the text before the tt(*) is required
for the context to be matched, so that further arguments may be
completed after the abbreviated form.

The second part of var(spec) is a description for the word being
completed.

The optional third part of the var(spec) describes how words following
the one being completed are themselves 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) var(term) specifies a terminator for the word
instead of the usual space.  This is handled as an auto-removable suffix
in the manner of the option tt(-s) var(sep) to tt(_values).

The result of the processing by tt(_regex_words) is placed in the array
tt(reply), which should be made local to the calling function.
If the set of words and arguments may be matched repeatedly, a tt(#)
should be appended to the generated array at that point.

For example:

example(local -a reply
_regex_words mydb-commands 'mydb commands' \ 
  'add:add an entry to mydb:$mydb_add_cmds' \ 
  'show:show entries in mydb'
_regex_arguments _mydb "$reply[@]"
_mydb "$@")

This shows a completion function for a command tt(mydb) which takes
two command arguments, tt(add) and tt(show).  tt(show) takes no arguments,
while the arguments for tt(add) have already been prepared in an
array tt(mydb_add_cmds), quite possibly by a previous call to
tt(_regex_words).
)
findex(_requested)
item(tt(_requested) [ tt(-x) ] [ tt(-12VJ) ] var(tag) [ var(name) var(descr) [ var(command) var(args) ... ] ])(
This function is called to decide whether a tag already registered by a
call to tt(_tags) (see below) has been requested by the user and hence
completion should be performed for it.  It returns status zero if the
tag is requested and non-zero otherwise.  The function is typically used
as part of a loop over different tags as follows:

example(_tags foo bar baz
while _tags; do
  if _requested foo; then
    ... # perform completion for foo
  fi
  ... # test the tags bar and baz in the same way
  ... # exit loop if matches were generated
done)

Note that the test for whether matches were generated is not performed
until the end of the tt(_tags) loop.  This is so that the user can set
the tt(tag-order) style to specify a set of tags to be completed at the
same time.

If var(name) and var(descr) are given, tt(_requested) calls the
tt(_description) function with these arguments together with the options
passed to tt(_requested).

If var(command) is given, the tt(_all_labels) function will be called
immediately with the same arguments.  In simple cases this makes it
possible to perform the test for the tag and the matching in one go.
For example:

example(local expl ret=1
_tags foo bar baz
while _tags; do
  _requested foo expl 'description' \ 
      compadd foobar foobaz && ret=0
  ...
  (( ret )) || break
done)

If the var(command) is not tt(compadd), it must nevertheless be prepared
to handle the same options.
)
findex(_retrieve_cache)
item(tt(_retrieve_cache) var(cache_identifier))(
This function retrieves completion information from the file given by
var(cache_identifier), stored in a directory specified by the
tt(cache-path) style which defaults to tt(~/.zcompcache).  The return status
is zero if retrieval was successful.  It will only attempt retrieval
if the tt(use-cache) style is set, so you can call this function
without worrying about whether the user wanted to use the caching
layer.

See tt(_store_cache) below for more details.
)
findex(_sep_parts)
item(tt(_sep_parts))(
(□)tt(foo:bar) のように、区切り文字で区切られた複数の補完対象語を補完する。

This function is passed alternating arrays and separators as arguments.
The arrays specify completions 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 parentheses.  For example, with the array
`tt(hosts=(ftp news))' the call `tt(_sep_parts '(foo bar)' @ hosts)' will
complete the string  `tt(f)' to `tt(foo)' and the string `tt(b@n)' to
`tt(bar@news)'.

This function accepts the tt(compadd) options `tt(-V)', `tt(-J)',
`tt(-1)', `tt(-2)', `tt(-n)', `tt(-X)', `tt(-M)', `tt(-P)', `tt(-S)',
`tt(-r)', `tt(-R)', and `tt(-q)' and passes them on to the tt(compadd)
builtin used to add the matches.
)
findex(_setup)
item(tt(_setup) var(tag) [ var(group) ])(
This function sets up the special
parameters used by the completion system appropriately for the var(tag)
given as the first argument.  It uses the styles tt(list-colors),
tt(list-packed), tt(list-rows-first), tt(last-prompt), tt(accept-exact),
tt(menu) and tt(force-list).

The optional var(group) supplies the name of the group in which the
matches will be placed.  If it is not given, the var(tag) is used as
the group name.

This function is called automatically from tt(_description)
and hence is not normally called explicitly.
)
findex(_store_cache)
item(tt(_store_cache) var(cache_identifier) var(params) ...)(
This function, together with tt(_retrieve_cache) and
tt(_cache_invalid), implements a caching layer which can be used
in any completion function.  Data obtained by
costly operations are stored in parameters;
this function then dumps the values of those parameters to a file.  The
data can then be retrieved quickly from that file via tt(_retrieve_cache),
even in different instances of the shell.

The var(cache_identifier) specifies the file which the data should be
dumped to.  The file is stored in a directory specified by the
tt(cache-path) style which defaults to tt(~/.zcompcache).  The remaining
var(params) arguments are the parameters to dump to the file.

The return status is zero if storage was successful.  The function will
only attempt storage if the tt(use-cache) style is set, so you can
call this function without worrying about whether the user wanted to
use the caching layer.

The completion function may avoid calling tt(_retrieve_cache) when it
already has the completion data available as parameters. 
However, in that case it should
call tt(_cache_invalid) to check whether the data in the parameters and
in the cache are still valid.

See the _perl_modules completion function for a simple example of
the usage of the caching layer.
)
findex(_tags)
item(tt(_tags) [ [ tt(-C) var(name) ] var(tags) ... ])(
If called with arguments, these are taken to be the names of tags
valid for completions in the current context.  These tags are stored
internally and sorted by using the tt(tag-order) style.

Next, tt(_tags) is called repeatedly without arguments from the same
completion function.  This successively 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 tt(_requested) function should be
called (see above).

If `tt(-C) var(name)' is given, var(name) is temporarily stored in the
argument field (the fifth) of the context in the tt(curcontext) parameter
during the call to tt(_tags); the field is restored on exit.  This
allows tt(_tags) to use a more 
specific context without having to change and reset the
tt(curcontext) parameter (which has the same effect).
)
findex(_values)
item(tt(_values) [ tt(-O) var(name) ] [ tt(-s) var(sep) ] [ tt(-S) var(sep) ] [ tt(-wC) ] var(desc) var(spec) ...)(
「パラメータ=値」という形式の任意の並びを補完する。

`tt(-O) var(name)' は
If the first argument is the option `tt(-O) var(name)', it will be used
in the same way as by the tt(_arguments) function.  In other words, the
elements of the var(name) array will be passed to tt(compadd)
when executing an action.

If the first argument (or the first argument after `tt(-O) var(name)')
is `tt(-s)', the next argument is used as the character that separates
multiple values.  This character is automatically added after each value
in an auto-removable fashion (see below); all values completed by
`tt(_values -s)' appear in the same word on the command line, unlike
completion using tt(_arguments).  If this option is not present, only a
single value will be completed per word.

Normally, tt(_values) will only use the current word to determine
which values are already present on the command line and hence are not
to be completed again.  If the tt(-w) option is given, other arguments
are examined as well.

The first non-option argument is used as a string to print as a
description before listing the values.

All other arguments describe the possible values and their
arguments in the same format used for the description of options by
the tt(_arguments) function (see above).  The only differences are that
no minus or plus sign is required at the beginning,
values can have only one argument, and the forms of action
beginning with an equal sign are not supported.

The character separating a value from its argument can be set using the
option tt(-S) (like tt(-s), followed by the character to use as the
separator in the next argument).  By default the equals
sign will be used as the separator between values and arguments.

Example:

example(_values -s , 'description' \ 
        '*foo[bar]' \ 
        '(two)*one[number]:first count:' \ 
        'two[another number]::second count:(1 2 3)')

This describes three possible values: `tt(foo)', `tt(one)', and
`tt(two)'.  The first is described as `tt(bar)', takes no argument 
and may appear more than once.  The second is described as
`tt(number)', may appear more than once, and takes one mandatory
argument described as `tt(first count)'; no action is
specified, so it will not be completed.  The
`tt((two))' at the beginning says that if the value `tt(one)' is on
the line, the value `tt(two)' will no longer be considered a possible
completion.  Finally, the last value (`tt(two)') is described
as `tt(another number)' and takes an optional argument described as
`tt(second count)' for which the completions (to appear after an
`tt(=)') are `tt(1)', `tt(2)', and `tt(3)'.  The tt(_values) function
will complete lists of these values separated by commas.

Like tt(_arguments), this function temporarily adds another context name
component to the arguments element (the fifth) of the current context
while executing the var(action).  Here this name is just the name of the
value for which the argument is completed.

The style tt(verbose) is used to decide if the descriptions for the
values (but not those for the arguments) should be printed.

The associative array tt(val_args) is used to report values and their
arguments; this works similarly to the tt(opt_args) associative array
used by tt(_arguments).  Hence the function calling tt(_values) should
declare the local parameters tt(state), tt(line), tt(context) and
tt(val_args):

example(local context state line
typeset -A val_args)

when using an action of the form `tt(->)var(string)'.  With this
function the tt(context) parameter will be set to the name of the
value whose argument is to be completed.

Note also that tt(_values) normally adds the character used as the
separator between values as an auto-removable suffix (similar to a
`tt(/)' after a directory).  However, this is not possible for a
`tt(->)var(string)' action as the matches for the argument are
generated by the calling function.  To get the usual behaviour, the
the calling function can add the separator var(x) as a suffix by
passing the options `tt(-qS) var(x)' either directly or indirectly to
tt(compadd).

The option tt(-C) is treated in the same way as it is by tt(_arguments).
In that case the parameter tt(curcontext) should be made local instead 
of tt(context) (as described above).
)
findex(_wanted)
item(tt(_wanted) [ tt(-x) ] [ tt(-C) var(name) ]  [ tt(-12VJ) ] var(tag) var(name) var(descr) var(command) var(args) ...)(
In many contexts, completion can only generate one particular set of
matches, usually corresponding to a single tag.  However, it is
still necessary to decide whether the user requires matches of this type.
This function is useful in such a case.

The arguments to tt(_wanted) are the same as those to tt(_requested),
i.e. arguments to be passed to tt(_description).  However, in this case
the var(command) is not optional;  all the processing of tags, including
the loop over both tags and tag labels and the generation of matches,
is carried out automatically by tt(_wanted).

Hence to offer only one tag and immediately add the corresponding
matches with the given description:

example(local expl
_wanted tag expl 'description' \ 
    compadd matches...)

Note that, as for tt(_requested), the var(command) must be able to
accept options to be passed down to tt(compadd).

Like tt(_tags) this function supports the tt(-C) option to give a
different name for the argument context field.  The tt(-x) option has
the same meaning as for tt(_description).
)
enditem()

texinode(Completion Directories)()(Completion Functions)(Completion System)
sect(Completion Directories)
cindex(completion system, directory structure)

In the source distribution, the files are contained in various
subdirectories of the tt(Completion) directory.  They may have been
installed in the same structure, or into one single function directory.
The following is a description of the files found in the original directory
structure.  If you wish to alter an installed file, you will need to copy
it to some directory which appears earlier in your tt(fpath) than the
standard directory where it appears.

startitem()
item(tt(Base))(
The core functions and special completion widgets automatically bound
to keys.  You will certainly need most of these, though will
probably not need to alter them.  Many of these are documented above.
)
item(tt(Zsh))(
Functions for completing arguments of shell builtin commands and
utility functions for this.  Some of these are also used by functions from
the tt(Unix) directory.
)
item(tt(Unix))(
Functions for completing arguments of external commands and suites of
commands.  They may need modifying for your system, although in many cases
some attempt is made to decide which version of a command is present.  For
example, completion for the tt(mount) command tries to determine the system
it is running on, while completion for many other utilities try to decide
whether the GNU version of the command is in use, and hence whether the
tt(-)tt(-help) option is supported.
)
item(tt(X), tt(AIX), tt(BSD), ...)(
Completion and utility function for commands available only on some systems.
These are not arranged hierarchically, so, for example, both the
tt(Linux) and tt(Debian) directories, as well as the tt(X) directory,
may be useful on your system.
)
enditem()