path: root/devdocs/elisp/minibuffer-completion.html

 <h4 class="subsection">Completion and the Minibuffer</h4>   <p>This section describes the basic interface for reading from the minibuffer with completion. </p> <dl> <dt id="completing-read">Function: <strong>completing-read</strong> <em>prompt collection &amp;optional predicate require-match initial history default inherit-input-method</em>
</dt> <dd>
<p>This function reads a string in the minibuffer, assisting the user by providing completion. It activates the minibuffer with prompt <var>prompt</var>, which must be a string. </p> <p>The actual completion is done by passing the completion table <var>collection</var> and the completion predicate <var>predicate</var> to the function <code>try-completion</code> (see <a href="basic-completion">Basic Completion</a>). This happens in certain commands bound in the local keymaps used for completion. Some of these commands also call <code>test-completion</code>. Thus, if <var>predicate</var> is non-<code>nil</code>, it should be compatible with <var>collection</var> and <code>completion-ignore-case</code>. See <a href="basic-completion#Definition-of-test_002dcompletion">Definition of test-completion</a>. </p> <p>See <a href="programmed-completion">Programmed Completion</a>, for detailed requirements when <var>collection</var> is a function. </p> <p>The value of the optional argument <var>require-match</var> determines how the user may exit the minibuffer: </p> <ul> <li> If <code>nil</code>, the usual minibuffer exit commands work regardless of the input in the minibuffer. </li>
<li> If <code>t</code>, the usual minibuffer exit commands won’t exit unless the input completes to an element of <var>collection</var>. </li>
<li> If <code>confirm</code>, the user can exit with any input, but is asked for confirmation if the input is not an element of <var>collection</var>. </li>
<li> If <code>confirm-after-completion</code>, the user can exit with any input, but is asked for confirmation if the preceding command was a completion command (i.e., one of the commands in <code>minibuffer-confirm-exit-commands</code>) and the resulting input is not an element of <var>collection</var>. See <a href="completion-commands">Completion Commands</a>. </li>
<li> Any other value of <var>require-match</var> behaves like <code>t</code>, except that the exit commands won’t exit if it performs completion. </li>
</ul> <p>However, empty input is always permitted, regardless of the value of <var>require-match</var>; in that case, <code>completing-read</code> returns the first element of <var>default</var>, if it is a list; <code>""</code>, if <var>default</var> is <code>nil</code>; or <var>default</var>. The string or strings in <var>default</var> are also available to the user through the history commands. </p> <p>The function <code>completing-read</code> uses <code>minibuffer-local-completion-map</code> as the keymap if <var>require-match</var> is <code>nil</code>, and uses <code>minibuffer-local-must-match-map</code> if <var>require-match</var> is non-<code>nil</code>. See <a href="completion-commands">Completion Commands</a>. </p> <p>The argument <var>history</var> specifies which history list variable to use for saving the input and for minibuffer history commands. It defaults to <code>minibuffer-history</code>. If <var>history</var> is the symbol <code>t</code>, history is not recorded. See <a href="minibuffer-history">Minibuffer History</a>. </p> <p>The argument <var>initial</var> is mostly deprecated; we recommend using a non-<code>nil</code> value only in conjunction with specifying a cons cell for <var>history</var>. See <a href="initial-input">Initial Input</a>. For default input, use <var>default</var> instead. </p> <p>If the argument <var>inherit-input-method</var> is non-<code>nil</code>, then the minibuffer inherits the current input method (see <a href="input-methods">Input Methods</a>) and the setting of <code>enable-multibyte-characters</code> (see <a href="text-representations">Text Representations</a>) from whichever buffer was current before entering the minibuffer. </p> <p>If the variable <code>completion-ignore-case</code> is non-<code>nil</code>, completion ignores case when comparing the input against the possible matches. See <a href="basic-completion">Basic Completion</a>. In this mode of operation, <var>predicate</var> must also ignore case, or you will get surprising results. </p> <p>Here’s an example of using <code>completing-read</code>: </p> <div class="example"> <pre class="example">(completing-read
 "Complete a foo: "
 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
 nil t "fo")
</pre>

<pre class="example">;; <span class="roman">After evaluation of the preceding expression,</span>
;;   <span class="roman">the following appears in the minibuffer:</span>

---------- Buffer: Minibuffer ----------
Complete a foo: fo∗
---------- Buffer: Minibuffer ----------
</pre>
</div> <p>If the user then types <kbd><span class="key">DEL</span> <span class="key">DEL</span> b <span class="key">RET</span></kbd>, <code>completing-read</code> returns <code>barfoo</code>. </p> <p>The <code>completing-read</code> function binds variables to pass information to the commands that actually do completion. They are described in the following section. </p>
</dd>
</dl> <dl> <dt id="completing-read-function">Variable: <strong>completing-read-function</strong>
</dt> <dd><p>The value of this variable must be a function, which is called by <code>completing-read</code> to actually do its work. It should accept the same arguments as <code>completing-read</code>. This can be bound to a different function to completely override the normal behavior of <code>completing-read</code>. </p></dd>
</dl><div class="_attribution">
  <p class="_attribution-p">
    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Minibuffer-Completion.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Minibuffer-Completion.html</a>
  </p>
</div>