Next: Completion in Buffers, Previous: Completion Variables, Up: Completion
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
argument to completing-read. The function
completing-read arranges to pass your completion function along
to try-completion, all-completions, and other basic
completion functions, which will then let your function do all
the work.
The completion function should accept three arguments:
nil if none. The function should call the predicate for each
possible match, and ignore the match if the predicate returns
nil.
niltry-completion operation. The function should
return nil if there are no matches; it should return t
if the specified string is a unique and exact match; and it should
return the longest common prefix substring of all matches otherwise.
tall-completions operation. The function
should return a list of all possible completions of the specified
string.
lambdatest-completion operation. The function
should return t if the specified string is an exact match for
some completion alternative; nil otherwise.
(boundaries . suffix)completion-boundaries operation. The function
should return (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
suffix.
metadata(metadata . alist), where alist is an alist whose
elements are described below.
If the flag has any other value, the completion function should return
nil.
The following is a list of metadata entries that a completion function
may return in response to a metadata flag argument:
categorycompletion-category-overrides, the usual
completion behavior is overridden. See Completion Variables.
annotation-functiondisplay-sort-functioncycle-sort-functioncompletion-cycle-threshold is non-nil and the user is
cycling through completion alternatives. See Completion Options. Its argument list and return value are
the same as for display-sort-function.
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) 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
completion-table-dynamic. In particular, function can ignore its argument and return a full list of all possible completions. You can think ofcompletion-table-dynamicas a transducer between function and the interface for programmed completion functions.If the optional argument switch-buffer is non-
nil, and completion is performed in the minibuffer, function will be called with current buffer set to the buffer from which the minibuffer was entered.The return value of
completion-table-dynamicis a function that can be used as the 2nd argument totry-completionandall-completions. Note that this function will always return empty metadata and trivial boundaries (see Programmed Completion).
This is a wrapper for
completion-table-dynamicthat 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.