Previous: Programmed Completion, Up: Completion
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 C-M-i or M-<TAB> command, bound to
completion-at-point
. See Symbol Completion. This command uses the abnormal hook variable
completion-at-point-functions
:
The value of this abnormal hook should be a list of functions, which are used to compute a completion table for completing the text at point. It can be used by major modes to provide mode-specific completion tables (see Major Mode Conventions).
When the command
completion-at-point
runs, it calls the functions in the list one by one, without any argument. Each function should returnnil
if it is unable to produce a completion table for the text at point. Otherwise it should return a list of the form(start end collection . props)start and end delimit the text to complete (which should enclose point). collection is a completion table for completing that text, in a form suitable for passing as the second argument to
try-completion
(see Basic Completion); completion alternatives will be generated from this completion table in the usual way, via the completion styles defined incompletion-styles
(see Completion Variables). props is a property list for additional information; any of the properties incompletion-extra-properties
are recognized (see Completion Variables), as well as the following additional ones:
:predicate
- The value should be a predicate that completion candidates need to satisfy.
:exclusive
- If the value is
no
, then if the completion table fails to match the text at point,completion-at-point
moves on to the next function incompletion-at-point-functions
instead of reporting a completion failure.A function in
completion-at-point-functions
may also return a function. 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 intended to help convert old code to usingcompletion-at-point
.The first function in
completion-at-point-functions
to return a non-nil
value is used bycompletion-at-point
. The remaining functions are not called. The exception to this is when there is an:exclusive
specification, as described above.
The following function provides a convenient way to perform completion on an arbitrary stretch of text in an Emacs buffer:
This function completes the text in the current buffer between the positions start and end, using collection. The argument collection has the same meaning as in
try-completion
(see Basic Completion).This function inserts the completion text directly into the current buffer. Unlike
completing-read
(see Minibuffer Completion), it does not activate the minibuffer.For this function to work, point must be somewhere between start and end.