補完,\begin型補完,\section型補完における候補の絞り込みの際に参照されます.
まずは簡単な例として,\usepackageの補完設定を作ってみます.\usepackageは\usepackage[option]{パッケージ名}という書式なので,それをformatで指定します.補完をきかせたい場所を,補完させたい順番に$1,$2で置き換えていきます.今の場合はオプションより先にパッケージ名を入力する方が良いでしょう.(オプションはパッケージに依存するため.)
[\usepackage] format=[$2]{$1}$0
$0は補完位置を表すのではなく,補完が終了した後にカーソルが移動する先を表します.これで良いのですが,[$2]はオプションなので,それを明示するために,この部分を次のように書き換えます.
[\usepackage] format=$2<[$]>{$1}$0
$2の後に<[$]>という書式で$2がオプションであり,その前に[,その後に]を入れることを意味します.フォーマット指定が書けたら,次は補完候補の設定を記述します.
[\usepackage] format=$2<[$]>{$1}$0 $1=amsmath,tikz,graphicx,geometry,xcolor
キー$1で$1の箇所での補完候補を指定します.このようにカンマ区切りで入力を入れておくほか,辞書を用意しておいてその辞書名を書く方法もあります.
[\usepackage] format=$2<[$]>{$1}$0 $1=pack.dic設定された値が辞書ファイルかカンマ区切りリストかは自動で判断されます.オプションに対する設定は$2で行うことができますが,次のようにしてパッケージに応じた設定をすることができます.
[\usepackage] format=$2<[$]>{$1}$0 $1=amsmath,tikz,graphicx,geometry,xcolor /amsmath$2=@multiargs,leqno,reqno,fleqn /xcolor$2=@multiargs,dvipsname,svgname,x11names@から始まるものは,補完時の設定を意味します.今の場合オプションはカンマ区切りの複数引数なので,@multiargsを指定しています.他にもこのような特別設定があります(後述).
このような他の引数に依存した設定は三番目以降の引数でも同様です.たとえば,
[\testcs] format={$1}{$2}{$3} /hoge/fuga$3=x,y,z /hoge$3=a,b,cという指定では,\test{hoge}{fuga}{}で第三引数を補完するとx,y,zが,第二引数がそれ以外の場合,たとえば\test{hoge}{hoge}{}で第三引数を補完するとa,b,cが候補に現れるようになります.*1
各指定をもう少し詳しく見ていきます.
引数のフォーマットを指定します.改行は\n,\は\\としておく必要があります.補完を出したい場所は$1,...,$9です.$10は使えません.\beginの設定はこうなっています.
[\begin] format={$1}$0*\n$0\n\\end{$1}
二つ目以降の$1は一つ目のコピーとなります.$0*は補完マクロの挙動を制御します.祝鳥は$0*をフォーマット内に見つけると,ここで現在のフォーマットの再解釈をおこないます.たとえば次のような設定
[\begin] format={$1}$0*\n$0\n\\end{$1} [\begin{enumerate}] format=\n\\item $0\n\\end{enumerate}をすると,まず\beginの引数補完が始まります.\beginの補完の$1の位置の候補としてenumerateが確定すると,祝鳥は$0*の前まで,つまり{enumerate}までを挿入し,ここでフォーマットを再解釈します.その結果新しい\begin{enumerate}を見つけ,そのフォーマットを採用します.結果,\itemの挿入が行われます.
以下のような制限があります.(今は)入力チェックは行っていませんので,エラーも出ないまま予期不能な動作となると思います.
現在,$0*は次のような効果を持ちます.これは今後も同じ挙動となるかはわかりません.たとえば上のような設定を考えてみます.
[\testcs] format={$1}$0*{$1}$0この設定で,次のような状態で起動したとします.(|はカーソル位置.)
\testcs{|}{second}
この場合,祝鳥は\testcs{}までで解釈をやめ,カーソル位置で補完を開始します.補完終了後,残りのフォーマットのチェックを行います.残りを解釈している際に,二つ目の{second}のsecondの部分がさきほど補完を行った$1と同じであることは認識しますが,祝鳥はフォーマットのチェック中は,入力されている文字列を尊重し書き換えません.結果,補完終了後には次のようになります.
\testcs{first}{second}
一方,\testcsの指定が
[\testcs] format={$1}{$1}$0となっていたとしましょう.このとき同様に
\begin{|}{second}という状態で起動すると,今度は全てのフォーマットのチェックを一気に行い,最初の段階で{second}のsecondの部分が$1であることを認識します.その後カーソル位置で補完を開始しますが,このときは二つの$1を連動させるように動きます.結果,補完終了後には次のようになります.
\testcs{first}{first}
補完対象を指定するキー名は上に書いた通りです.カンマ区切りリストの中には,@で始まる命令(設定変更)や$で始まる命令(特殊な補完候補)を入れることができます.$で始まる命令の後に更にカンマ区切りで候補を並べると,それも追加されます.たとえば$file,xyzとするとファイル一覧とxyzを候補に加えます.
候補に加えて「ヒント」を指定することもできます.たとえば次のような指定
[\testcs] format={$1}$0 $1=a{A},b{B},c{C}では,aをリストボックスで選択している間Aがその下に表示されるようになります.辞書ファイルでも利用可能で,同様に
[\testcs] $1=dic.dic{hint.dic}とします.この場合dic.dicと同じ行のhint.dicの中身が下に表示されます.$collectではこのヒントが自動的に使われます.
コントロールシークエンスの補完は,セクション\,キー$1で指定できます.デフォルトは次の通りです.
[\] $1=comtex.dic
@や$で始まる候補は特殊な命令を表します.基本的には
補完候補が,適当な文字で区切られた複数引数であることを指定します.区切り文字はデフォルトはカンマですが,@multiargs{;}のようにして変更することもできます.
key=valという形が続くkeyval形式であることを示します.補完候補の設定はたとえば次のように行います.
[\includegraphics] format=$1<[$]>{$2}$0 $1=@keyval $1@keyval:key=pagebox,bb,angle,width $1@keyval:val{pagebox}=mediabox,cropbox,bleedbox,trimbox,artbox $1@keyval:val=@skip
@keyval:val{pagebox}でpagebox=となった時の補完候補を指定します.候補の指定方法は$1等と同様です.@keyval:valでpagebox以外のkeyが指定された場合の候補を設定できます.上の例ではpagebox以外はvalの補完をスキップします.
ヒントに対する設定を行います.@hint{no}とするとヒントを表示しません.@hint{fix:ヒントです}とすると,現在の選択候補によらず常に"ヒントです"と表示します.\を表示するには\\とする必要があります.改行は\nで表されます.また\Bと\Eで挟むとその間を太文字で表示します.
この値が指定された引数に達すると,補完マクロが終了します.
補完マクロは,この値が指定された引数の補完を飛ばします.
ソースファイルから候補を集めることを意味します.\labelの引数を\refの補完候補にする例です.
[\ref] format={$1}$0 $1=$collect $1$collect:pattern=\\label\{(.*?)\} $1$collect:target=\1
$1$collect:patternに列挙する対象のパターンを正規表現で指定します.また実際の補完候補にする例をタグ付き正規表現で$1$collect:targetに指定しています.$collect{key}により$1$collectをkeyに変更できます.たとえば
[\label] format={$1}$0 $1=$collect{ref},$collect{pageref} ref:pattern=\\ref\{(.*?)\} ref:target=\1 pageref:pattern=\\pageref\{(.*?)\} pageref:target=\1のようにすると,\refと\pagerefの引数を集めて\labelの引数とします.なお,もちろんこれは次と等価です.
[\label] format={$1}$0 $1=$collect $1$collect:pattern=\\(ref|pageref)\{(.*?)\} $1$collect:target=\1
ファイル一覧を候補に出すことを意味します.\includegraphicsの指定を見てみましょう.
[\includegraphics] format=$1<[$]>{$2}$0 $2=$file $2$file=*.jpg;*.bmp;*.pdf;*.eps;*.png
このように;で区切ってワイルドカードで指定します.
aliasセクション,または各セクションのaliasキーで,エイリアスを指定することができます.たとえば次のどちらかの指定は\inputの設定を\includeのそれと同じにすることを意味します.
[\input] alias=\include
[alias] \input=\include
次のようにすることもできます.
[\input] alias=input [alias] \input=input [input] (input/include共通の設定を書く)
複数の設定をまとめるのに使えるほか,aliasセクションを使えば,セクション名として指定できない名前(]を含む名前)を使うこともできるようになります.