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
try-completionoperation. The function should return
tif the specified string is a unique and exact match; if there is more than one match, it should return the common substring of all matches (if the string is an exact match for one completion alternative but also matches other longer alternatives, the return value is the string); if there are no matches, it should return
all-completionsoperation. The function should return a list of all possible completions of the specified string.
test-completionoperation. The function should return
tif the specified string is an exact match for some completion alternative;
completion-boundariesoperation. The function should return
), where start is the position of the beginning boundary in the specified string, and end is the position of the end boundary in suffix.
), 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:
completion-category-overrides, the usual completion behavior is overridden. See Completion Variables.
niland the user is cycling through completion alternatives. See Completion Options. 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 an alist of possible completions of it. You can think of
completion-table-dynamicas a transducer between that interface and the interface for programmed completion functions.
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.