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 in The GNU
Emacs Manual. This command uses the abnormal hook variable
The value of this abnormal hook should be a list of functions, which are used to compute a completion table (see Basic Completion Functions) 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
nil 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:
(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 Functions); completion
alternatives will be generated from this completion table in the usual
way, via the completion styles defined in
(see Completion Variables). props is a property list for
additional information; any of the properties in
completion-extra-properties are recognized (see Completion Variables), as well as the following additional ones:
The value should be a predicate that completion candidates need to satisfy.
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 in
completion-at-point-functions instead of
reporting a completion failure.
The functions on this hook should generally return quickly, since they
may be called very often (e.g., from
Supplying a function for collection is strongly recommended if
generating the list of completions is an expensive operation. Emacs
may internally call functions in
many times, but care about the value of collection for only some
of these calls. By supplying a function for collection, Emacs
can defer generating completions until necessary. You can use
completion-table-dynamic to create a wrapper function:
;; 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)))))
Additionally, the collection should generally not be
pre-filtered based on the current text between start and
end, because that is the responsibility of the caller of
completion-at-point-functions to do that according to the
completion styles it decides to use.
A function in
completion-at-point-functions 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
The first function in
completion-at-point-functions to return a
nil value is used by
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 Functions).
This function inserts the completion text directly into the current
completing-read (see Completion and the Minibuffer), it does not activate the minibuffer.
For this function to work, point must be somewhere between start and end.