19.6.1 基本的な補完関数

以下の補完関数は、その関数自身ではミニバッファーで何も行いません。ここではミニバッファーを使用する高レベルの補完機能とともに、これらの関数について説明します。

Function: try-completion string collection &optional predicate

この関数はcollection内のstringに可能なすべての補完の共通する最長部分文字列をリターンする。

collectionは補完テーブル(completion table)と呼ばれる。値は文字列リスト、コンスセル、obarray、ハッシュテーブル、または補完関数でなければならない。

try-completionは補完テーブルにより指定された許容できる補完それぞれにたいして、stringと比較を行う。許容できる補完マッチが存在しなければnilをリターンする。マッチする補完が1つだけで、それが完全一致ならばtをリターンする。それ以外は、すべてのマッチ可能な補完に共通する最長の初期シーケンスをリターンする。

collectionがリストなら、許容できる補完(permissible completions)はそのリストの要素によって指定される。リストの要素は文字列、またはCARが文字列、または(symbol-nameによって文字列に変換される)シンボルであるようなコンスセルである。リストに他の型の要素が含まれる場合は無視される。

collectionがobarray(Creating Symbolsを参照)なら、そのobarray内のすべてのシンボル名が許容できる補完セットを形成する。

collectionがハッシュテーブルの場合には、文字列のキーが利用可能な補完(possible completions)になる。他のキーは無視される。

collectionとして関数を使用することもできる。この場合にはその関数だけが補完を処理する役目を担う。つまりtry-completionは、この関数が何をリターンしようともそれをリターンする。この関数はstring、predicate、nilの3つの引数で呼び出される(3つ目の引数は同じ関数をall-completionsでも使用して、どちらの場合でも適切なことを行うため)。Programmed Completionを参照のこと。

引数predicateが非nilの場合には、collectionがハッシュテーブルなら1引数、それ以外は2引数の関数でなければならない。これは利用可能なマッチのテストに使用され、マッチはpredicateが非nilをリターンしたときだけ受け入れられる。predicateに与えられる引数は文字列、alistのコンスセル(CARが文字列)、またはobarrayのシンボル(シンボル名ではない)のいずれか。collectionがハッシュテーブルなら、predicateは文字列キー(string key)と連想値(associated value)の2引数で呼び出される。

これらに加えて許容され得るためには、補完はcompletion-regexp-list内のすべての正規表現にもマッチしなければならない。(collectionが関数なら、その関数自身がcompletion-regexp-listを処理する必要がある)。

以下の1つ目の例では、文字列‘foo’がalistのうち3つのCARとマッチされている。すべてのマッチは文字‘fooba’で始まるので、それが結果となる。2つ目の例では可能なマッチは1つだけで、しかも完全一致なのでリターン値はtになる。

(try-completion
 "foo"
 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
     ⇒ "fooba"

(try-completion "foo" '(("barfoo" 2) ("foo" 3)))
     ⇒ t

以下の例では文字‘forw’で始まるシンボルが多数あり、それらはすべて単語‘forward’で始まる。ほとんどのシンボルはその後に‘-’が続くが、すべてではないので‘forward’までしか補完できない。

(try-completion "forw" obarray)
     ⇒ "forward"

最後に以下の例では述語testに渡される利用可能なマッチは3つのうち2つだけである(文字列‘foobaz’は短すぎる)。これらは両方とも文字列‘foobar’で始まる。

(defun test (s)
  (> (length (car s)) 6))
     ⇒ test

(try-completion
 "foo"
 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
 'test)
     ⇒ "foobar"

Function: all-completions string collection &optional predicate

この関数はstringの利用可能な補完すべてのリストをリターンする。この関数の引数はtry-completionの引数と同じであり、try-completionが行うのと同じ方法でcompletion-regexp-listを使用する。

collectionか関数ならstring、predicate、tの3つの引数で呼び出される。この場合はその関数がリターンするのが何であれ、all-completionsはそれをリターンする。Programmed Completionを参照のこと。

以下の例はtry-completionの例の関数testを使用している。

(defun test (s)
  (> (length (car s)) 6))
     ⇒ test

(all-completions
 "foo"
 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
 'test)
     ⇒ ("foobar1" "foobar2")

Function: test-completion string collection &optional predicate

この関数はstringがcollectionとpredicateで指定された有効な補完候補ならnilをリターンする。引数はtry-completionの引数と同じ。たとえばcollectionが文字列リストなら、stringがリスト内に存在して、かつpredicateを満足すればtrueとなる。

この関数はtry-completionが行うのと同じ方法でcompletion-regexp-listを使用する。

predicateが非nilでcollectionが同じ文字列を複数含む場合には、completion-ignore-caseにしたがってcompare-stringsで判定してそれらすべてをリターンするか、もしくは何もリターンしない。それ以外ではtest-completionのリターン値は基本的に予測できない。

collectionが関数の場合はstring、predicate、lambdaの3つの引数で呼び出される。それが何をリターンするにせよtest-completionはそれをリターンする。

Function: completion-boundaries string collection predicate suffix

この関数はポイントの前のテキストがstring、ポイントの後がsuffixと仮定して、collectionが扱うフィールドの境界(boundary)をリターンする。

補完は通常は文字列(string)全体に作用するので、すべての普通のコレクション(collection)にたいして、この関数は常に(0 . (length suffix))をリターンするだろう。しかしファイルにたいする補完などの、より複雑な補完は1回に1フィールド行われる。たとえばたとえ"/usr/share/doc"が存在しても、"/usr/sh"の補完に"/usr/share/"は含まれるが、"/usr/share/doc"は含まれないだろう。また"/usr/sh"にたいするall-completionsに"/usr/share/"は含まれず、"share/"だけが含まれるだろう。stringが"/usr/sh"、suffixが"e/doc"なら、completion-boundariesは(5 . 1)をリターンするだろう。これはcollectionが"/usr/"の後ろにあり"/doc"の前にある領域に関する補完情報だけをリターンするであろうことを告げている。

補完alistを変数に格納した場合は、変数のrisky-local-variableプロパティに非nilをセットして、その変数が“risky(危険)”だとマークすべきである。File Local Variablesを参照のこと。

Variable: completion-ignore-case

この変数の値が非nilなら、補完でのcase(大文字小文字)の違いは意味をもたない。read-file-nameでは、この変数はread-file-name-completion-ignore-case (Reading File Namesを参照)にオーバーライドされる。read-bufferでは、この変数はread-buffer-completion-ignore-case (High-Level Completionを参照)にオーバーライドされる。

Variable: completion-regexp-list

これは正規表現のリストである。補完関数はこのリスト内のすべての正規表現にマッチした場合のみ許容できる補完と判断する。case-fold-search (Searching and Caseを参照)ではcompletion-ignore-caseの値にバインドされる。

Macro: lazy-completion-table var fun

この変数は変数varを補完のためのcollectionとしてlazy(lazy: 力のない、だらけさせる、のろのろした、怠惰な、不精な、眠気を誘う)な方法で初期化する。ここでlazyとは、collection内の実際のコンテンツを必要になるまで計算しないという意味。このマクロはvarに格納する値の生成に使用する。varを使用して最初に補完を行ったとき、真の値が実際に計算される。これは引数なしでfunを呼び出すことにより行われる。funがリターンする値はvarの永続的な値となる。

以下は例:

(defvar foo (lazy-completion-table foo make-my-alist))

既存の補完テーブルを受け取って変更したバージョンをリターンする関数がいくつかあります。completion-table-case-foldは大文字小文字を区別しない、case-insensitiveなテーブルをリターンします。completion-table-in-turnとcompletion-table-mergeは、複数の入力テーブルを異なる方法で組み合わせます。completion-table-subvertはテーブルを異なる初期プレフィックス(initial prefix)で変更します。completion-table-with-quotingはクォートされたテキストの処理に適したテーブルをリターンします。completion-table-with-predicateは述語関数(predicate function)によるフィルタリングを行います。completion-table-with-terminatorは終端文字列(terminating string)を追加します。