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
nilif 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-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.
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-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-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 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.