この節では、補完機能を用いてミニバッファから読み出すための基本的なインターフェースについて説明します。
この関数はミニバッファ内の文字列を読み込み、補完機能を提供することでユーザーを支援します。文字列である必要があるプロンプト prompt を用いてミニバッファをアクティブにします。
実際の補完は、補完テーブル collection と補完述語 predicate を関数 try-completion
に渡すことで行われます（基本的な補完関数
を参照）。これは、補完に使用されるローカルキーマップにバインドされた特定のコマンドで行われます。これらのコマンドの中には、test-completion を呼び出すものもあります。したがって、predicate が nil 以外である場合、collection および completion-ignore-case と互換性がある必要があります。test-completion
の定義 を参照してください。
collection が関数である場合の詳細な要件については、プログラム済み補完を参照してください。
オプション引数 require-match の値によって、ユーザーがミニバッファを終了する方法が決まります：
nil の場合、ミニバッファ内の入力に関わらず、通常のミニバッファ終了コマンドが動作します。
t の場合、入力が collection
の要素に達するまで、通常のミニバッファ終了コマンドは機能しません。
confirm の場合、ユーザーは任意の入力で終了できますが、入力が collection の要素でない場合は確認を求められます。
confirm-after-completion
の場合、ユーザーは任意の入力で終了できますが、直前のコマンドが補完コマンド（すなわち minibuffer-confirm-exit-commands
に含まれるコマンドのいずれか）であり、かつその結果得られた入力が collection
の要素ではない場合は、確認が求められます。補完を行うミニバッファコマンド を参照してください。
nil以外の値を返す必要があります。
t
と同様に動作しますが、補完が実行された場合には終了コマンドが終了しません。
ただし、require-match の値にかかわらず、空の入力は常に許可されます。その場合、completing-read は、default
がリストであればその最初の要素を、default が nil であれば "" を、あるいは
default を返します。default
内の文字列（または複数の文字列）も、履歴コマンド（ミニバッファコマンド を参照）を通じて利用可能です。さらに、default の値が M-n
によって使い果たされると、補完候補が「将来の履歴」に追加されます。minibuffer-default-add-function
を参照してください。
関数 completing-read は、require-match が nil の場合は minibuffer-local-completion-map を、require-match が nil 以外の場合は minibuffer-local-must-match-map をキーマップとして使用します。補完を行うミニバッファコマンド を参照してください。
引数 history
は、入力の保存およびミニバッファ履歴コマンドに使用する履歴リスト変数を指定します。デフォルトは minibuffer-history です。history
がシンボル t である場合、履歴は記録されません。ミニバッファ履歴 を参照してください。
引数 initial はほぼ非推奨となっています。history にコンスセルを指定する場合に限り、nil
以外の値を使用することを推奨します。初期入力
を参照してください。デフォルトの入力には、代わりに default を使用してください。
引数 inherit-input-method が nil 以外の場合、ミニバッファは、ミニバッファに入る前に有効だったバッファから、現在の入力メソッド（入力メソッド を参照）および enable-multibyte-characters の設定（テキスト表現 を参照）を継承します。
変数 completion-ignore-case が nil 以外の場合、補完機能は入力と候補を照合する際に大文字小文字を区別しません。基本的な補完機能を参照してください。この動作モードでは、predicate
も同様に大文字小文字を区別しない必要があります。そうしないと、予期しない結果が生じることがあります。
completing-readの使用例を以下に示します。
(completing-read
"Complete a foo: "
'(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
nil t "fo")
;; After evaluation of the preceding expression, ;; the following appears in the minibuffer: ---------- Buffer: Minibuffer ---------- Complete a foo: fo∗ ---------- Buffer: Minibuffer ----------
その後、ユーザーが DEL DEL b RET と入力すると、completing-read は barfoo
を返します。
completing-read
関数は、実際に補完を行うコマンドに情報を渡すための変数をバインドします。これらの変数については、次のセクションで説明します。
この変数の値は関数である必要があり、completing-read
によって呼び出されて実際に処理を実行します。また、completing-read
と同じ引数を受け取る必要があります。これを別の関数にバインドすることで、completing-read の通常の動作を完全に上書きできます。
リストの複数の要素や、接続の複数のパラメータ（例：ユーザー、ホスト、ポート）など、複数の文字列をユーザーに入力させる必要がある場合は、completing-read-multiple
を使用できます。これにより、区切り文字（デフォルトはタブとカンマ。変更するには crm-separator
をカスタマイズしてください）で区切られた複数の文字列を入力でき、ユーザーが入力した個々の文字列に対して補完機能が提供されます。読み取られた文字列は、リストとして返されます。