1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
|
<h4 class="subsection">Completion in Ordinary Buffers</h4> <p>Although completion is usually done in the minibuffer, the completion facility can also be used on the text in ordinary Emacs buffers. In many major modes, in-buffer completion is performed by the <kbd>C-M-i</kbd> or <kbd>M-<span class="key">TAB</span></kbd> command, bound to <code>completion-at-point</code>. See <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Symbol-Completion.html#Symbol-Completion">Symbol Completion</a> in <cite>The GNU Emacs Manual</cite>. This command uses the abnormal hook variable <code>completion-at-point-functions</code>: </p> <dl> <dt id="completion-at-point-functions">Variable: <strong>completion-at-point-functions</strong>
</dt> <dd>
<p>The value of this abnormal hook should be a list of functions, which are used to compute a completion table (see <a href="basic-completion">Basic Completion</a>) for completing the text at point. It can be used by major modes to provide mode-specific completion tables (see <a href="major-mode-conventions">Major Mode Conventions</a>). </p> <p>When the command <code>completion-at-point</code> runs, it calls the functions in the list one by one, without any argument. Each function should return <code>nil</code> unless it can and wants to take responsibility for the completion data for the text at point. Otherwise it should return a list of the following form: </p> <div class="example"> <pre class="example">(<var>start</var> <var>end</var> <var>collection</var> . <var>props</var>)
</pre>
</div> <p><var>start</var> and <var>end</var> delimit the text to complete (which should enclose point). <var>collection</var> is a completion table for completing that text, in a form suitable for passing as the second argument to <code>try-completion</code> (see <a href="basic-completion">Basic Completion</a>); completion alternatives will be generated from this completion table in the usual way, via the completion styles defined in <code>completion-styles</code> (see <a href="completion-variables">Completion Variables</a>). <var>props</var> is a property list for additional information; any of the properties in <code>completion-extra-properties</code> are recognized (see <a href="completion-variables">Completion Variables</a>), as well as the following additional ones: </p> <dl compact> <dt><code>:predicate</code></dt> <dd>
<p>The value should be a predicate that completion candidates need to satisfy. </p> </dd> <dt><code>:exclusive</code></dt> <dd><p>If the value is <code>no</code>, then if the completion table fails to match the text at point, <code>completion-at-point</code> moves on to the next function in <code>completion-at-point-functions</code> instead of reporting a completion failure. </p></dd> </dl> <p>The functions on this hook should generally return quickly, since they may be called very often (e.g., from <code>post-command-hook</code>). Supplying a function for <var>collection</var> is strongly recommended if generating the list of completions is an expensive operation. Emacs may internally call functions in <code>completion-at-point-functions</code> many times, but care about the value of <var>collection</var> for only some of these calls. By supplying a function for <var>collection</var>, Emacs can defer generating completions until necessary. You can use <code>completion-table-dynamic</code> to create a wrapper function: </p> <div class="example"> <pre class="example">;; Avoid this pattern.
(let ((beg ...) (end ...) (my-completions (my-make-completions)))
(list beg end my-completions))
;; Use this instead.
(let ((beg ...) (end ...))
(list beg
end
(completion-table-dynamic
(lambda (_)
(my-make-completions)))))
</pre>
</div> <p>Additionally, the <var>collection</var> should generally not be pre-filtered based on the current text between <var>start</var> and <var>end</var>, because that is the responsibility of the caller of <code>completion-at-point-functions</code> to do that according to the completion styles it decides to use. </p> <p>A function in <code>completion-at-point-functions</code> may also return a function instead of a list as described above. In that case, that returned function is called, with no argument, and it is entirely responsible for performing the completion. We discourage this usage; it is only intended to help convert old code to using <code>completion-at-point</code>. </p> <p>The first function in <code>completion-at-point-functions</code> to return a non-<code>nil</code> value is used by <code>completion-at-point</code>. The remaining functions are not called. The exception to this is when there is an <code>:exclusive</code> specification, as described above. </p>
</dd>
</dl> <p>The following function provides a convenient way to perform completion on an arbitrary stretch of text in an Emacs buffer: </p> <dl> <dt id="completion-in-region">Function: <strong>completion-in-region</strong> <em>start end collection &optional predicate</em>
</dt> <dd>
<p>This function completes the text in the current buffer between the positions <var>start</var> and <var>end</var>, using <var>collection</var>. The argument <var>collection</var> has the same meaning as in <code>try-completion</code> (see <a href="basic-completion">Basic Completion</a>). </p> <p>This function inserts the completion text directly into the current buffer. Unlike <code>completing-read</code> (see <a href="minibuffer-completion">Minibuffer Completion</a>), it does not activate the minibuffer. </p> <p>For this function to work, point must be somewhere between <var>start</var> and <var>end</var>. </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/Completion-in-Buffers.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Completion-in-Buffers.html</a>
</p>
</div>
|
