diff options
Diffstat (limited to 'devdocs/elisp/high_002dlevel-completion.html')
| -rw-r--r-- | devdocs/elisp/high_002dlevel-completion.html | 55 |
1 files changed, 55 insertions, 0 deletions
diff --git a/devdocs/elisp/high_002dlevel-completion.html b/devdocs/elisp/high_002dlevel-completion.html new file mode 100644 index 00000000..84d10904 --- /dev/null +++ b/devdocs/elisp/high_002dlevel-completion.html @@ -0,0 +1,55 @@ + <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 &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 &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 &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>&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 © 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> |