20.6.8 通常バッファーでの補完

補完は通常はミニバッファー内で行われますが、補完機能は通常のEmacsバッファー内のテキストにも使用できます。多くのメジャーモードで、コマンドC-M-iまたはM-TABによってバッファー内補完が行われ、それらはcompletion-at-pointにバインドされています。Symbol Completion in The GNU Emacs Manualを参照してください。このコマンドはアブノーマルフック変数completion-at-point-functionsを使用します:

Variable: completion-at-point-functions

このアブノーマルフックの値は関数のリスト。これらの関数はポイント位置のテキストの補完にたいする補完テーブルの計算に使用される(Basic Completionを参照)。これはメジャーモードによるモード固有の補完テーブル(Major Mode Conventionsを参照)の提供に使用できる。

コマンドcompletion-at-pointが実行されると引数なしでリスト内の関数が1つずつ呼び出される。それぞれの関数はポイント位置のテキストにたいして補完テーブルを生成でき、かつそれに責任を負いたいのでなければnilをリターンすること。それ以外なら以下の形式のリストをリターンすること:

(start end collection . props)

ここでstartとendは補完する(ポイントを取り囲む)テキストの区切りである。collectionはそのテキストを補完する補完テーブルであり、try-completion (Basic Completionを参照)の2つ目の引数として渡すのに適した形式である。補完候補はcompletion-styles (Completion Variablesを参照)で定義された補完スタイルを通じて、この補完テーブルを通常の方法で使用して生成されるだろう。propsは追加の情報のためのプロパティリストである。completion-extra-properties内のすべてのプロパティ(Completion Variablesを参照)と、以下の追加のプロパティが認識される:

:predicate

値は補完候補が満足する必要がある述語。

:exclusive

値がnoの場合は、もし補完テーブルがポイント位置のテキストのマッチに失敗したなら、補完の失敗を報告するかわりにcompletion-at-pointはcompletion-at-point-functions内の次の関数へ移動する。

このフック上の関数は(たとえばpost-command-hookから)頻繁に呼び出され得るので一般的には素早くリターンすること。補完リストの生成が高価な処理ならcollectionにたいする関数の提供を強く推奨する。Emacsはcompletion-at-point-functions内の関数を頻繁に呼び出すかもしれないが、それらの呼び出しのいくつかにたいしてのみcollectionの値を考慮する。collectionにたいして関数を提供することによりEmacsは必要になるまで補完の生成を遅延できる。ラッパー関数を作成するためにcompletion-table-dynamicを使用できる:

;; このパターンは避けて
(let ((beg ...) (end ...) (my-completions (my-make-completions)))
  (list beg end my-completions))

;; かわりに以下を使用する
(let ((beg ...) (end ...))
  (list beg
        end
        (completion-table-dynamic
          (lambda (_)
            (my-make-completions)))))

さらに一般的にはcollectionはstartとendの間のカレントのテキストにもとづいて事前にフィルターされるべきではない。なぜなら使用を判断した補完スタイルに応じてこれを行うのはcompletion-at-point-functionsの呼び出し側の責任だからである。

completion-at-point-functions内の関数も上述のリストのかわりに関数をリターンするかもしれない。その場合には引数なしでリターンされた関数が呼び出されて、その関数が補完処理の全責任を負う。この方法は推奨されない。これはcompletion-at-pointを使用する古いコードの救済だけを意図したものだからである。

非nil値を最初にリターンしたcompletion-at-point-functions内の関数が、completion-at-pointによって使用される。残りの関数は呼び出されない。例外は上述の:exclusive指定があるとき。

以下の関数はEmacsバッファー内の任意に拡張されたテキストにたいして便利な補完方法を提供します:

Function: completion-in-region start end collection &optional predicate

この関数はcollectionを使用してカレントバッファー内の位置startとendの間のテキストを補完する。引数collectionはtry-completion (Basic Completionを参照)のときと同じ意味をもつ。

この関数は補完テキストを直接カレントバッファーに挿入する。completing-read (Minibuffer Completionを参照)とは異なり、ミニバッファーをアクティブにしない。

この関数が機能するためには、ポイントがstartとendの間になければならない。