Sometimes it is not possible or convenient to create an alist or an obarray containing all the intended possible completions ahead of time. In such a case, you can supply your own function to compute the completion of a given string. This is called programmed completion. Emacs uses programmed completion when completing file names (see File Name Completion), among many other cases.
To use this feature, pass a function as the collection
completing-read. The function
completing-read arranges to pass your completion function along
all-completions, and other basic
completion functions, which will then let your function do all
The completion function should accept three arguments:
nilif none. The function should call the predicate for each possible match, and ignore the match if the predicate returns
This specifies a
try-completion operation. The function should
nil if there are no matches; it should return
if the specified string is a unique and exact match; and it should
return the longest common prefix substring of all matches otherwise.
This specifies an
all-completions operation. The function
should return a list of all possible completions of the specified
This specifies a
test-completion operation. The function
t if the specified string is an exact match for
some completion alternative;
(boundaries . suffix)
This specifies a
completion-boundaries operation. The function
(boundaries start . end), where
start is the position of the beginning boundary in the specified
string, and end is the position of the end boundary in
If a Lisp program returns nontrivial boundaries, it should make sure that the
all-completions operation is consistent with them. The
completions returned by
all-completions should only pertain to
the piece of the prefix and suffix covered by the completion
boundaries. See Basic Completion Functions, for the precise expected semantics
of completion boundaries.
This specifies a request for information about the state of the
current completion. The return value should have the form
(metadata . alist), where alist is an alist whose
elements are described below.
If the flag has any other value, the completion function should return
The following is a list of metadata entries that a completion function
may return in response to a
metadata flag argument:
The value should be a symbol describing what kind of text the
completion function is trying to complete. If the symbol matches one
of the keys in
completion-category-overrides, the usual
completion behavior is overridden. See Completion Variables.
The value should be a function for annotating completions. The
function should take one argument, string, which is a possible
completion. It should return a string, which is displayed after the
completion string in the *Completions* buffer.
Unless this function puts own face on the annotation suffix string,
completions-annotations face is added by default to
The value should be a function for adding prefixes and suffixes to
completions. The function should take one argument,
completions, which is a list of possible completions. It should
return such a list of completions where each element contains a list
of three elements: a completion, a prefix which is displayed before
the completion string in the *Completions* buffer, and
a suffix displayed after the completion string. This function
takes priority over
The value should be a function for grouping the completion candidates.
The function must take two arguments, completion, which is a
completion candidate and transform, which is a boolean flag. If
nil, the function must return the group
title of the group to which the candidate belongs. The returned title
can also be
nil. Otherwise the function must return the
transformed candidate. The transformation can for example remove a
redundant prefix, which is displayed in the group title.
The value should be a function for sorting completions. The function should take one argument, a list of completion strings, and return a sorted list of completion strings. It is allowed to alter the input list destructively.
The value should be a function for sorting completions, when
completion-cycle-threshold is non-
nil and the user is
cycling through completion alternatives. See Completion Options in The GNU Emacs Manual. Its argument list and return value are
the same as for
This function is a convenient way to write a function that can act as
a programmed completion function. The argument function should
be a function that takes one argument, a string, and returns a
completion table (see Basic Completion Functions) containing all the
possible completions. The table returned by function can also
include elements that don’t match the string argument; they are
automatically filtered out by
particular, function can ignore its argument and return a full
list of all possible completions. You can think of
completion-table-dynamic as a transducer between function
and the interface for programmed completion functions.
If the optional argument switch-buffer is non-
completion is performed in the minibuffer, function will be
called with current buffer set to the buffer from which the minibuffer
The return value of
completion-table-dynamic is a function that
can be used as the 2nd argument to
all-completions. Note that this function will always return
empty metadata and trivial boundaries.
This is a wrapper for
completion-table-dynamic that saves the
last argument-result pair. This means that multiple lookups with the
same argument only need to call function once. This can be useful
when a slow operation is involved, such as calling an external process.