diff options
Diffstat (limited to 'devdocs/elisp/basic-completion.html')
| -rw-r--r-- | devdocs/elisp/basic-completion.html | 63 |
1 files changed, 63 insertions, 0 deletions
diff --git a/devdocs/elisp/basic-completion.html b/devdocs/elisp/basic-completion.html new file mode 100644 index 00000000..e7781b79 --- /dev/null +++ b/devdocs/elisp/basic-completion.html @@ -0,0 +1,63 @@ + <h4 class="subsection">Basic Completion Functions</h4> <p>The following completion functions have nothing in themselves to do with minibuffers. We describe them here to keep them near the higher-level completion features that do use the minibuffer. </p> <dl> <dt id="try-completion">Function: <strong>try-completion</strong> <em>string collection &optional predicate</em> +</dt> <dd> +<p>This function returns the longest common substring of all possible completions of <var>string</var> in <var>collection</var>. </p> <p><var>collection</var> is called the <em>completion table</em>. Its value must be a list of strings or cons cells, an obarray, a hash table, or a completion function. </p> <p><code>try-completion</code> compares <var>string</var> against each of the permissible completions specified by the completion table. If no permissible completions match, it returns <code>nil</code>. If there is just one matching completion, and the match is exact, it returns <code>t</code>. Otherwise, it returns the longest initial sequence common to all possible matching completions. </p> <p>If <var>collection</var> is a list, the permissible completions are specified by the elements of the list, each of which should be either a string, or a cons cell whose <small>CAR</small> is either a string or a symbol (a symbol is converted to a string using <code>symbol-name</code>). If the list contains elements of any other type, those are ignored. </p> <p>If <var>collection</var> is an obarray (see <a href="creating-symbols">Creating Symbols</a>), the names of all symbols in the obarray form the set of permissible completions. </p> <p>If <var>collection</var> is a hash table, then the keys that are strings or symbols are the possible completions. Other keys are ignored. </p> <p>You can also use a function as <var>collection</var>. Then the function is solely responsible for performing completion; <code>try-completion</code> returns whatever this function returns. The function is called with three arguments: <var>string</var>, <var>predicate</var> and <code>nil</code> (the third argument is so that the same function can be used in <code>all-completions</code> and do the appropriate thing in either case). See <a href="programmed-completion">Programmed Completion</a>. </p> <p>If the argument <var>predicate</var> is non-<code>nil</code>, then it must be a function of one argument, unless <var>collection</var> is a hash table, in which case it should be a function of two arguments. It is used to test each possible match, and the match is accepted only if <var>predicate</var> returns non-<code>nil</code>. The argument given to <var>predicate</var> is either a string or a cons cell (the <small>CAR</small> of which is a string) from the alist, or a symbol (<em>not</em> a symbol name) from the obarray. If <var>collection</var> is a hash table, <var>predicate</var> is called with two arguments, the string key and the associated value. </p> <p>In addition, to be acceptable, a completion must also match all the regular expressions in <code>completion-regexp-list</code>. (Unless <var>collection</var> is a function, in which case that function has to handle <code>completion-regexp-list</code> itself.) </p> <p>In the first of the following examples, the string ‘<samp>foo</samp>’ is matched by three of the alist <small>CAR</small>s. All of the matches begin with the characters ‘<samp>fooba</samp>’, so that is the result. In the second example, there is only one possible match, and it is exact, so the return value is <code>t</code>. </p> <div class="example"> <pre class="example">(try-completion + "foo" + '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))) + ⇒ "fooba" +</pre> + +<pre class="example">(try-completion "foo" '(("barfoo" 2) ("foo" 3))) + ⇒ t +</pre> +</div> <p>In the following example, numerous symbols begin with the characters ‘<samp>forw</samp>’, and all of them begin with the word ‘<samp>forward</samp>’. In most of the symbols, this is followed with a ‘<samp>-</samp>’, but not in all, so no more than ‘<samp>forward</samp>’ can be completed. </p> <div class="example"> <pre class="example">(try-completion "forw" obarray) + ⇒ "forward" +</pre> +</div> <p>Finally, in the following example, only two of the three possible matches pass the predicate <code>test</code> (the string ‘<samp>foobaz</samp>’ is too short). Both of those begin with the string ‘<samp>foobar</samp>’. </p> <div class="example"> <pre class="example">(defun test (s) + (> (length (car s)) 6)) + ⇒ test +</pre> +<pre class="example">(try-completion + "foo" + '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) + 'test) + ⇒ "foobar" +</pre> +</div> </dd> +</dl> <dl> <dt id="all-completions">Function: <strong>all-completions</strong> <em>string collection &optional predicate</em> +</dt> <dd> +<p>This function returns a list of all possible completions of <var>string</var>. The arguments to this function are the same as those of <code>try-completion</code>, and it uses <code>completion-regexp-list</code> in the same way that <code>try-completion</code> does. </p> <p>If <var>collection</var> is a function, it is called with three arguments: <var>string</var>, <var>predicate</var> and <code>t</code>; then <code>all-completions</code> returns whatever the function returns. See <a href="programmed-completion">Programmed Completion</a>. </p> <p>Here is an example, using the function <code>test</code> shown in the example for <code>try-completion</code>: </p> <div class="example"> <pre class="example">(defun test (s) + (> (length (car s)) 6)) + ⇒ test +</pre> + +<pre class="example">(all-completions + "foo" + '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) + 'test) + ⇒ ("foobar1" "foobar2") +</pre> +</div> </dd> +</dl> <dl> <dt id="test-completion">Function: <strong>test-completion</strong> <em>string collection &optional predicate</em> +</dt> <dd> +<p>This function returns non-<code>nil</code> if <var>string</var> is a valid completion alternative specified by <var>collection</var> and <var>predicate</var>. The arguments are the same as in <code>try-completion</code>. For instance, if <var>collection</var> is a list of strings, this is true if <var>string</var> appears in the list and <var>predicate</var> is satisfied. </p> <p>This function uses <code>completion-regexp-list</code> in the same way that <code>try-completion</code> does. </p> <p>If <var>predicate</var> is non-<code>nil</code> and if <var>collection</var> contains several strings that are equal to each other, as determined by <code>compare-strings</code> according to <code>completion-ignore-case</code>, then <var>predicate</var> should accept either all or none of them. Otherwise, the return value of <code>test-completion</code> is essentially unpredictable. </p> <p>If <var>collection</var> is a function, it is called with three arguments, the values <var>string</var>, <var>predicate</var> and <code>lambda</code>; whatever it returns, <code>test-completion</code> returns in turn. </p> +</dd> +</dl> <dl> <dt id="completion-boundaries">Function: <strong>completion-boundaries</strong> <em>string collection predicate suffix</em> +</dt> <dd> +<p>This function returns the boundaries of the field on which <var>collection</var> will operate, assuming that <var>string</var> holds the text before point and <var>suffix</var> holds the text after point. </p> <p>Normally completion operates on the whole string, so for all normal collections, this will always return <code>(0 . (length +<var>suffix</var>))</code>. But more complex completion, such as completion on files, is done one field at a time. For example, completion of <code>"/usr/sh"</code> will include <code>"/usr/share/"</code> but not <code>"/usr/share/doc"</code> even if <code>"/usr/share/doc"</code> exists. Also <code>all-completions</code> on <code>"/usr/sh"</code> will not include <code>"/usr/share/"</code> but only <code>"share/"</code>. So if <var>string</var> is <code>"/usr/sh"</code> and <var>suffix</var> is <code>"e/doc"</code>, <code>completion-boundaries</code> will return <code>(5 . 1)</code> which tells us that the <var>collection</var> will only return completion information that pertains to the area after <code>"/usr/"</code> and before <code>"/doc"</code>. <code>try-completion</code> is not affected by nontrivial boundaries; e.g., <code>try-completion</code> on <code>"/usr/sh"</code> might still return <code>"/usr/share/"</code>, not <code>"share/"</code>. </p> +</dd> +</dl> <p>If you store a completion alist in a variable, you should mark the variable as risky by giving it a non-<code>nil</code> <code>risky-local-variable</code> property. See <a href="file-local-variables">File Local Variables</a>. </p> <dl> <dt id="completion-ignore-case">Variable: <strong>completion-ignore-case</strong> +</dt> <dd><p>If the value of this variable is non-<code>nil</code>, case is not considered significant in completion. Within <code>read-file-name</code>, this variable is overridden by <code>read-file-name-completion-ignore-case</code> (see <a href="reading-file-names">Reading File Names</a>); within <code>read-buffer</code>, it is overridden by <code>read-buffer-completion-ignore-case</code> (see <a href="high_002dlevel-completion">High-Level Completion</a>). </p></dd> +</dl> <dl> <dt id="completion-regexp-list">Variable: <strong>completion-regexp-list</strong> +</dt> <dd><p>This is a list of regular expressions. The completion functions only consider a completion acceptable if it matches all regular expressions in this list, with <code>case-fold-search</code> (see <a href="searching-and-case">Searching and Case</a>) bound to the value of <code>completion-ignore-case</code>. </p></dd> +</dl> <dl> <dt id="lazy-completion-table">Macro: <strong>lazy-completion-table</strong> <em>var fun</em> +</dt> <dd> +<p>This macro provides a way to initialize the variable <var>var</var> as a collection for completion in a lazy way, not computing its actual contents until they are first needed. You use this macro to produce a value that you store in <var>var</var>. The actual computation of the proper value is done the first time you do completion using <var>var</var>. It is done by calling <var>fun</var> with no arguments. The value <var>fun</var> returns becomes the permanent value of <var>var</var>. </p> <p>Here is an example: </p> <div class="example"> <pre class="example">(defvar foo (lazy-completion-table foo make-my-alist)) +</pre> +</div> </dd> +</dl> <p>There are several functions that take an existing completion table and return a modified version. <code>completion-table-case-fold</code> returns a case-insensitive table. <code>completion-table-in-turn</code> and <code>completion-table-merge</code> combine multiple input tables in different ways. <code>completion-table-subvert</code> alters a table to use a different initial prefix. <code>completion-table-with-quoting</code> returns a table suitable for operating on quoted text. <code>completion-table-with-predicate</code> filters a table with a predicate function. <code>completion-table-with-terminator</code> adds a terminating string. </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/Basic-Completion.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Basic-Completion.html</a> + </p> +</div> |