想定されるすべての補完候補を含むalistやobarrayを事前に作成することが、不可能であったり不便であったりする場合があります。そのような場合には、指定した文字列の補完を計算する独自の関数を指定できます。これをプログラムによる補完と呼びます。Emacsは、ファイル名の補完（ファイル名の補完を参照）をはじめ、多くのケースでプログラムによる補完を利用しています。
この機能を利用するには、collection 引数として関数を completing-read に渡します。関数 completing-read は、完了関数を try-completion や all-completions、およびその他の基本的な完了関数に渡すよう処理し、これによりそれらの関数が実際の処理をすべて担うようになります。
完了関数は、3つの引数を受け取る必要があります：
nil。関数は、候補となるマッチごとに述語を呼び出し、述語が nil を返した場合はそのマッチを無視する必要があります。
nilこれは try-completion 操作を指定します。関数は、一致するものがない場合は nil を、指定された文字列が一意かつ完全一致する場合は t
を、それ以外の場合はすべての一致箇所における最長の共通接頭辞部分文字列を返す必要があります。
tこれは all-completions
操作を指定します。関数は、指定された文字列の考えられるすべての補完候補のリストを返す必要があります。
lambdaこれは test-completion
操作を指定します。指定された文字列がいずれかの補完候補と完全に一致する場合は t
を、それ以外の場合は nil を返す必要があります。
(boundaries . suffix)これは completion-boundaries 操作を指定します。関数は (boundaries start . end) を返す必要があります。ここで、start
は指定された文字列における開始境界の位置であり、end は suffix における終了境界の位置です。
Lispプログラムが非自明な境界を返す場合、all-completions
操作がそれらと整合していることを確実にする必要があります。all-completions
によって返される補完は、補完境界がカバーする接頭辞および接尾辞の部分にのみ関連する必要があります。補完境界の厳密な期待セマンティクスについては、基本補完関数を参照してください。
metadata ¶これは、現在の完了状態に関する情報の取得を要求するものです。戻り値は (metadata . alist) の形式である必要があり、ここで alist
は以下に説明する要素からなるアリストです。
フラグにそれ以外の値が設定されている場合、完了関数は nil を返す必要があります。
以下は、補完機能が metadata
フラグ引数に応じて返す可能性のあるメタデータエントリの一覧です。
category ¶この値は、補完機能がどのようなテキストを補完しようとしているかを示すシンボルである必要があります。このシンボルが completion-category-overrides
のキーのいずれかと一致する場合、通常の補完動作が上書きされます。補完変数 を参照してください。
annotation-function ¶値は、補完をアノテーションするための関数である必要があります。この関数は、補完候補であるstringを1つの引数として受け取ります。そして、*Completions*バッファ内の補完stringの後に表示される文字列を返す必要があります。この関数がアノテーションの接尾辞文字列に独自のフェイスを設定しない限り、デフォルトでcompletions-annotationsフェイスがその文字列に追加されます。
affixation-function ¶valueは、補完にプレフィックスとサフィックスを追加するための関数である必要があります。この関数は、候補となる補完のリストであるcompletionsを1つの引数として受け取ります。そして、completionsのリストを返します。各要素は、補完、*Completions*バッファ内で補完文字列の前に表示されるプレフィックス、および補完文字列の後に表示されるサフィックスという3つの要素からなるリストです。この関数はannotation-functionよりも優先されます。
group-function ¶valueには、補完候補をグループ化するための関数を指定します。この関数は、補完候補であるcompletionと、ブールフラグであるtransformの2つの引数を取る必要があります。transformがnilである場合、関数はその候補が属するグループのグループタイトルを返す必要があります。返されるタイトルはnilであっても構いません。それ以外の場合は、変換後の候補を返す必要があります。変換では、例えばグループタイトルに表示される冗長なプレフィックスを削除することができます。
display-sort-function
¶値は、補完候補をソートするための関数である必要があります。この関数は、補完候補文字列のリストを1つの引数として受け取り、ソート済みの補完候補文字列のリストを返します。入力リストを破壊的に変更しても構いません。
cycle-sort-function
¶この値は、completion-cycle-threshold が nil
ではなく、ユーザーが補完候補を順に切り替えている際の、補完結果をソートするための関数である必要があります。The
GNU Emacs Manual の Completion
Options を参照してください。その引数リストと戻り値は、display-sort-function の場合と同様です。
この関数は、プログラムによる補完機能として動作する関数を記述するための便利な方法です。引数 function には、1つの引数（文字列）を受け取り、考えられるすべての補完候補を含む補完テーブル（基本的な補完関数 を参照）を返す関数を指定します。function が返すテーブルには、文字列引数に一致しない要素が含まれることもありますが、これらは completion-table-dynamic によって自動的に除外されます。特に、function は引数を無視して、考えられるすべての補完候補の完全なリストを返すことができます。completion-table-dynamic は、function とプログラムによる補完関数用のインターフェースとの間のトランスデューサと考えることができます。
オプション引数 switch-buffer が nil
以外であり、ミニバッファ内で補完が行われる場合、function
は現在のバッファにミニバッファに入った際のバッファを設定して呼び出されます。
completion-table-dynamic の戻り値は、try-completion および all-completions
の第2引数として使用できる関数です。なお、この関数は常に空のメタデータと自明な境界を返します。
これは completion-table-dynamic
のラッパーで、直前の引数と結果のペアを保存します。これにより、同じ引数による複数回のルックアップでも、function
を一度呼び出すだけで済むようになります。外部プロセスの呼び出しなど、処理に時間がかかる操作が含まれる場合に有用です。
この関数は、既存の補完テーブル table と同様に動作する補完テーブルを作成しますが、新しいテーブルではアリスト metadata を補完メタデータとして使用します。