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

 <h4 class="subsection">High-Level Completion Functions</h4> <p>This section describes the higher-level convenience functions for reading certain sorts of names with completion. </p> <p>In most cases, you should not call these functions in the middle of a Lisp function. When possible, do all minibuffer input as part of reading the arguments for a command, in the <code>interactive</code> specification. See <a href="defining-commands">Defining Commands</a>. </p> <dl> <dt id="read-buffer">Function: <strong>read-buffer</strong> <em>prompt &amp;optional default require-match predicate</em>
</dt> <dd>
<p>This function reads the name of a buffer and returns it as a string. It prompts with <var>prompt</var>. The argument <var>default</var> is the default name to use, the value to return if the user exits with an empty minibuffer. If non-<code>nil</code>, it should be a string, a list of strings, or a buffer. If it is a list, the default value is the first element of this list. It is mentioned in the prompt, but is not inserted in the minibuffer as initial input. </p> <p>The argument <var>prompt</var> should be a string ending with a colon and a space. If <var>default</var> is non-<code>nil</code>, the function inserts it in <var>prompt</var> before the colon to follow the convention for reading from the minibuffer with a default value (see <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Programming-Tips.html">Programming Tips</a>). </p> <p>The optional argument <var>require-match</var> has the same meaning as in <code>completing-read</code>. See <a href="minibuffer-completion">Minibuffer Completion</a>. </p> <p>The optional argument <var>predicate</var>, if non-<code>nil</code>, specifies a function to filter the buffers that should be considered: the function will be called with every potential candidate as its argument, and should return <code>nil</code> to reject the candidate, non-<code>nil</code> to accept it. </p> <p>In the following example, the user enters ‘<samp>minibuffer.t</samp>’, and then types <tt class="key">RET</tt>. The argument <var>require-match</var> is <code>t</code>, and the only buffer name starting with the given input is ‘<samp>minibuffer.texi</samp>’, so that name is the value. </p> <div class="example"> <pre class="example">(read-buffer "Buffer name: " "foo" t)
</pre>
<pre class="example">;; <span class="roman">After evaluation of the preceding expression,</span>
;;   <span class="roman">the following prompt appears,</span>
;;   <span class="roman">with an empty minibuffer:</span>
</pre>

<pre class="example">---------- Buffer: Minibuffer ----------
Buffer name (default foo): ∗
---------- Buffer: Minibuffer ----------
</pre>

<pre class="example">;; <span class="roman">The user types <kbd>minibuffer.t <span class="key">RET</span></kbd>.</span>
     ⇒ "minibuffer.texi"
</pre>
</div> </dd>
</dl> <dl> <dt id="read-buffer-function">User Option: <strong>read-buffer-function</strong>
</dt> <dd><p>This variable, if non-<code>nil</code>, specifies a function for reading buffer names. <code>read-buffer</code> calls this function instead of doing its usual work, with the same arguments passed to <code>read-buffer</code>. </p></dd>
</dl> <dl> <dt id="read-buffer-completion-ignore-case">User Option: <strong>read-buffer-completion-ignore-case</strong>
</dt> <dd><p>If this variable is non-<code>nil</code>, <code>read-buffer</code> ignores case when performing completion while reading the buffer name. </p></dd>
</dl> <dl> <dt id="read-command">Function: <strong>read-command</strong> <em>prompt &amp;optional default</em>
</dt> <dd>
<p>This function reads the name of a command and returns it as a Lisp symbol. The argument <var>prompt</var> is used as in <code>read-from-minibuffer</code>. Recall that a command is anything for which <code>commandp</code> returns <code>t</code>, and a command name is a symbol for which <code>commandp</code> returns <code>t</code>. See <a href="interactive-call">Interactive Call</a>. </p> <p>The argument <var>default</var> specifies what to return if the user enters null input. It can be a symbol, a string or a list of strings. If it is a string, <code>read-command</code> interns it before returning it. If it is a list, <code>read-command</code> interns the first element of this list. If <var>default</var> is <code>nil</code>, that means no default has been specified; then if the user enters null input, the return value is <code>(intern "")</code>, that is, a symbol whose name is an empty string, and whose printed representation is <code>##</code> (see <a href="symbol-type">Symbol Type</a>). </p> <div class="example"> <pre class="example">(read-command "Command name? ")

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

<pre class="example">---------- Buffer: Minibuffer ----------
Command name?
---------- Buffer: Minibuffer ----------
</pre>
</div> <p>If the user types <kbd>forward-c <span class="key">RET</span></kbd>, then this function returns <code>forward-char</code>. </p> <p>The <code>read-command</code> function is a simplified interface to <code>completing-read</code>. It uses the variable <code>obarray</code> so as to complete in the set of extant Lisp symbols, and it uses the <code>commandp</code> predicate so as to accept only command names: </p>  <div class="example"> <pre class="example">(read-command <var>prompt</var>)
≡
(intern (completing-read <var>prompt</var> obarray
                         'commandp t nil))
</pre>
</div> </dd>
</dl> <dl> <dt id="read-variable">Function: <strong>read-variable</strong> <em>prompt &amp;optional default</em>
</dt> <dd>
<p>This function reads the name of a customizable variable and returns it as a symbol. Its arguments have the same form as those of <code>read-command</code>. It behaves just like <code>read-command</code>, except that it uses the predicate <code>custom-variable-p</code> instead of <code>commandp</code>. </p>
</dd>
</dl> <dl> <dt id="read-color">Command: <strong>read-color</strong> <em>&amp;optional prompt convert allow-empty display</em>
</dt> <dd>
<p>This function reads a string that is a color specification, either the color’s name or an RGB hex value such as <code>#RRRGGGBBB</code>. It prompts with <var>prompt</var> (default: <code>"Color (name or #RGB triplet):"</code>) and provides completion for color names, but not for hex RGB values. In addition to names of standard colors, completion candidates include the foreground and background colors at point. </p> <p>Valid RGB values are described in <a href="color-names">Color Names</a>. </p> <p>The function’s return value is the string typed by the user in the minibuffer. However, when called interactively or if the optional argument <var>convert</var> is non-<code>nil</code>, it converts any input color name into the corresponding RGB value string and instead returns that. This function requires a valid color specification to be input. Empty color names are allowed when <var>allow-empty</var> is non-<code>nil</code> and the user enters null input. </p> <p>Interactively, or when <var>display</var> is non-<code>nil</code>, the return value is also displayed in the echo area. </p>
</dd>
</dl> <p>See also the functions <code>read-coding-system</code> and <code>read-non-nil-coding-system</code>, in <a href="user_002dchosen-coding-systems">User-Chosen Coding Systems</a>, and <code>read-input-method-name</code>, in <a href="input-methods">Input Methods</a>. </p><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/High_002dLevel-Completion.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/High_002dLevel-Completion.html</a>
  </p>
</div>