diff options
Diffstat (limited to 'devdocs/elisp/programmed-completion.html')
| -rw-r--r-- | devdocs/elisp/programmed-completion.html | 25 |
1 files changed, 25 insertions, 0 deletions
diff --git a/devdocs/elisp/programmed-completion.html b/devdocs/elisp/programmed-completion.html new file mode 100644 index 00000000..25b350ed --- /dev/null +++ b/devdocs/elisp/programmed-completion.html @@ -0,0 +1,25 @@ + <h4 class="subsection">Programmed Completion</h4> <p>Sometimes it is not possible or convenient to create an alist or an obarray containing all the intended possible completions ahead of time. In such a case, you can supply your own function to compute the completion of a given string. This is called <em>programmed completion</em>. Emacs uses programmed completion when completing file names (see <a href="file-name-completion">File Name Completion</a>), among many other cases. </p> <p>To use this feature, pass a function as the <var>collection</var> argument to <code>completing-read</code>. The function <code>completing-read</code> arranges to pass your completion function along to <code>try-completion</code>, <code>all-completions</code>, and other basic completion functions, which will then let your function do all the work. </p> <p>The completion function should accept three arguments: </p> <ul> <li> The string to be completed. </li> +<li> A predicate function with which to filter possible matches, or <code>nil</code> if none. The function should call the predicate for each possible match, and ignore the match if the predicate returns <code>nil</code>. </li> +<li> A flag specifying the type of completion operation to perform; see <a href="basic-completion">Basic Completion</a>, for the details of those operations. This flag may be one of the following values. <dl compact> <dt><code>nil</code></dt> <dd> +<p>This specifies a <code>try-completion</code> operation. The function should return <code>nil</code> if there are no matches; it should return <code>t</code> if the specified string is a unique and exact match; and it should return the longest common prefix substring of all matches otherwise. </p> </dd> <dt><code>t</code></dt> <dd> +<p>This specifies an <code>all-completions</code> operation. The function should return a list of all possible completions of the specified string. </p> </dd> <dt><code>lambda</code></dt> <dd> +<p>This specifies a <code>test-completion</code> operation. The function should return <code>t</code> if the specified string is an exact match for some completion alternative; <code>nil</code> otherwise. </p> </dd> <dt><code>(boundaries . <var>suffix</var>)</code></dt> <dd> +<p>This specifies a <code>completion-boundaries</code> operation. The function should return <code>(boundaries <var>start</var> . <var>end</var>)</code>, where <var>start</var> is the position of the beginning boundary in the specified string, and <var>end</var> is the position of the end boundary in <var>suffix</var>. </p> <p>If a Lisp program returns nontrivial boundaries, it should make sure that the <code>all-completions</code> operation is consistent with them. The completions returned by <code>all-completions</code> should only pertain to the piece of the prefix and suffix covered by the completion boundaries. See <a href="basic-completion">Basic Completion</a>, for the precise expected semantics of completion boundaries. </p> </dd> <dt><code>metadata</code></dt> <dd><p>This specifies a request for information about the state of the current completion. The return value should have the form <code>(metadata . <var>alist</var>)</code>, where <var>alist</var> is an alist whose elements are described below. </p></dd> </dl> <p>If the flag has any other value, the completion function should return <code>nil</code>. </p> +</li> +</ul> <p>The following is a list of metadata entries that a completion function may return in response to a <code>metadata</code> flag argument: </p> <dl compact> <dt><code>category</code></dt> <dd> +<p>The value should be a symbol describing what kind of text the completion function is trying to complete. If the symbol matches one of the keys in <code>completion-category-overrides</code>, the usual completion behavior is overridden. See <a href="completion-variables">Completion Variables</a>. </p> </dd> <dt><code>annotation-function</code></dt> <dd> +<p>The value should be a function for <em>annotating</em> completions. The function should take one argument, <var>string</var>, which is a possible completion. It should return a string, which is displayed after the completion <var>string</var> in the <samp>*Completions*</samp> buffer. Unless this function puts own face on the annotation suffix string, the <code>completions-annotations</code> face is added by default to that string. </p> </dd> <dt><code>affixation-function</code></dt> <dd> +<p>The value should be a function for adding prefixes and suffixes to completions. The function should take one argument, <var>completions</var>, which is a list of possible completions. It should return such a list of <var>completions</var> where each element contains a list of three elements: a completion, a prefix which is displayed before the completion string in the <samp>*Completions*</samp> buffer, and a suffix displayed after the completion string. This function takes priority over <code>annotation-function</code>. </p> </dd> <dt><code>group-function</code></dt> <dd> +<p>The value should be a function for grouping the completion candidates. The function must take two arguments, <var>completion</var>, which is a completion candidate and <var>transform</var>, which is a boolean flag. If <var>transform</var> is <code>nil</code>, the function must return the group title of the group to which the candidate belongs. The returned title can also be <code>nil</code>. Otherwise the function must return the transformed candidate. The transformation can for example remove a redundant prefix, which is displayed in the group title. </p> </dd> <dt><code>display-sort-function</code></dt> <dd> +<p>The value should be a function for sorting completions. The function should take one argument, a list of completion strings, and return a sorted list of completion strings. It is allowed to alter the input list destructively. </p> </dd> <dt><code>cycle-sort-function</code></dt> <dd><p>The value should be a function for sorting completions, when <code>completion-cycle-threshold</code> is non-<code>nil</code> and the user is cycling through completion alternatives. See <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Completion-Options.html#Completion-Options">Completion Options</a> in <cite>The GNU Emacs Manual</cite>. Its argument list and return value are the same as for <code>display-sort-function</code>. </p></dd> </dl> <dl> <dt id="completion-table-dynamic">Function: <strong>completion-table-dynamic</strong> <em>function &optional switch-buffer</em> +</dt> <dd> +<p>This function is a convenient way to write a function that can act as a programmed completion function. The argument <var>function</var> should be a function that takes one argument, a string, and returns a completion table (see <a href="basic-completion">Basic Completion</a>) containing all the possible completions. The table returned by <var>function</var> can also include elements that don’t match the string argument; they are automatically filtered out by <code>completion-table-dynamic</code>. In particular, <var>function</var> can ignore its argument and return a full list of all possible completions. You can think of <code>completion-table-dynamic</code> as a transducer between <var>function</var> and the interface for programmed completion functions. </p> <p>If the optional argument <var>switch-buffer</var> is non-<code>nil</code>, and completion is performed in the minibuffer, <var>function</var> will be called with current buffer set to the buffer from which the minibuffer was entered. </p> <p>The return value of <code>completion-table-dynamic</code> is a function that can be used as the 2nd argument to <code>try-completion</code> and <code>all-completions</code>. Note that this function will always return empty metadata and trivial boundaries. </p> +</dd> +</dl> <dl> <dt id="completion-table-with-cache">Function: <strong>completion-table-with-cache</strong> <em>function &optional ignore-case</em> +</dt> <dd><p>This is a wrapper for <code>completion-table-dynamic</code> that saves the last argument-result pair. This means that multiple lookups with the same argument only need to call <var>function</var> once. This can be useful when a slow operation is involved, such as calling an external process. </p></dd> +</dl><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/Programmed-Completion.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Programmed-Completion.html</a> + </p> +</div> |