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 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 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 in completion-styles
(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.
Supplying a function for collection is strongly recommended if generating the list of completions is an expensive operation. Emacs may internally call functions in completion-at-point-functions 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)))))
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 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:
completion-in-regionstart end collection &optional predicate
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
completing-read (see Minibuffer Completion), it does not activate the minibuffer.
For this function to work, point must be somewhere between start and end.