19.6.1 Basic Completion Functions

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

Function: try-completion string collection &optional predicate

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

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

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

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の場合、補完での大文字小文字の違いは意味をもたない。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)を追加します。