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

 <h4 class="subsection">Completion Variables</h4> <p>Here are some variables that can be used to alter the default completion behavior. </p>  <dl> <dt id="completion-styles">User Option: <strong>completion-styles</strong>
</dt> <dd><p>The value of this variable is a list of completion style (symbols) to use for performing completion. A <em>completion style</em> is a set of rules for generating completions. Each symbol occurring this list must have a corresponding entry in <code>completion-styles-alist</code>. </p></dd>
</dl> <dl> <dt id="completion-styles-alist">Variable: <strong>completion-styles-alist</strong>
</dt> <dd>
<p>This variable stores a list of available completion styles. Each element in the list has the form </p> <div class="example"> <pre class="example">(<var>style</var> <var>try-completion</var> <var>all-completions</var> <var>doc</var>)
</pre>
</div> <p>Here, <var>style</var> is the name of the completion style (a symbol), which may be used in the <code>completion-styles</code> variable to refer to this style; <var>try-completion</var> is the function that does the completion; <var>all-completions</var> is the function that lists the completions; and <var>doc</var> is a string describing the completion style. </p> <p>The <var>try-completion</var> and <var>all-completions</var> functions should each accept four arguments: <var>string</var>, <var>collection</var>, <var>predicate</var>, and <var>point</var>. The <var>string</var>, <var>collection</var>, and <var>predicate</var> arguments have the same meanings as in <code>try-completion</code> (see <a href="basic-completion">Basic Completion</a>), and the <var>point</var> argument is the position of point within <var>string</var>. Each function should return a non-<code>nil</code> value if it performed its job, and <code>nil</code> if it did not (e.g., if there is no way to complete <var>string</var> according to the completion style). </p> <p>When the user calls a completion command like <code>minibuffer-complete</code> (see <a href="completion-commands">Completion Commands</a>), Emacs looks for the first style listed in <code>completion-styles</code> and calls its <var>try-completion</var> function. If this function returns <code>nil</code>, Emacs moves to the next listed completion style and calls its <var>try-completion</var> function, and so on until one of the <var>try-completion</var> functions successfully performs completion and returns a non-<code>nil</code> value. A similar procedure is used for listing completions, via the <var>all-completions</var> functions. </p> <p>See <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Completion-Styles.html#Completion-Styles">Completion Styles</a> in <cite>The GNU Emacs Manual</cite>, for a description of the available completion styles. </p>
</dd>
</dl> <dl> <dt id="completion-category-overrides">User Option: <strong>completion-category-overrides</strong>
</dt> <dd>
<p>This variable specifies special completion styles and other completion behaviors to use when completing certain types of text. Its value should be an alist with elements of the form <code>(<var>category</var>
. <var>alist</var>)</code>. <var>category</var> is a symbol describing what is being completed; currently, the <code>buffer</code>, <code>file</code>, and <code>unicode-name</code> categories are defined, but others can be defined via specialized completion functions (see <a href="programmed-completion">Programmed Completion</a>). <var>alist</var> is an association list describing how completion should behave for the corresponding category. The following alist keys are supported: </p> <dl compact> <dt><code>styles</code></dt> <dd>
<p>The value should be a list of completion styles (symbols). </p> </dd> <dt><code>cycle</code></dt> <dd><p>The value should be a value for <code>completion-cycle-threshold</code> (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>) for this category. </p></dd> </dl> <p>Additional alist entries may be defined in the future. </p>
</dd>
</dl> <dl> <dt id="completion-extra-properties">Variable: <strong>completion-extra-properties</strong>
</dt> <dd>
<p>This variable is used to specify extra properties of the current completion command. It is intended to be let-bound by specialized completion commands. Its value should be a list of property and value pairs. The following properties are supported: </p> <dl compact> <dt><code>:annotation-function</code></dt> <dd>
<p>The value should be a function to add annotations in the completions buffer. This function must accept one argument, a completion, and should either return <code>nil</code> or a string to be displayed next to the completion. 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 to add prefixes and suffixes to completions. This function must accept one argument, a list of completions, and should return a list of annotated completions. Each element of the returned list must be a three-element list, the completion, a prefix string, and a suffix string. This function takes priority over <code>:annotation-function</code>. </p> </dd> <dt><code>:exit-function</code></dt> <dd><p>The value should be a function to run after performing completion. The function should accept two arguments, <var>string</var> and <var>status</var>, where <var>string</var> is the text to which the field was completed, and <var>status</var> indicates what kind of operation happened: <code>finished</code> if text is now complete, <code>sole</code> if the text cannot be further completed but completion is not finished, or <code>exact</code> if the text is a valid completion but may be further completed. </p></dd> </dl> </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/Completion-Variables.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Completion-Variables.html</a>
  </p>
</div>