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
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-pointruns, it calls the functions in the list one by one, without any argument. Each function should return
nilunless 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); 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-propertiesare 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-pointmoves on to the next function in
completion-at-point-functionsinstead of reporting a completion failure.
The functions on this hook should generally return quickly, since they may be called very often (e.g., from
post-command-hook). 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-functionsmany 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-dynamicto 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-functionsto do that according to the completion styles it decides to use.
A function in
completion-at-point-functionsmay 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-functionsto return a non-
nilvalue is used by
completion-at-point. The remaining functions are not called. The exception to this is when there is an
:exclusivespecification, 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.