21.6.7 Programmed 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:

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, the completions-annotations face is added by default to that string.


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 annotation-function.


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 transform is 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 display-sort-function.

Function: completion-table-dynamic function &optional switch-buffer

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 completion-table-dynamic. In 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-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-dynamic is a function that can be used as the 2nd argument to try-completion and all-completions. Note that this function will always return empty metadata and trivial boundaries.

Function: completion-table-with-cache function &optional ignore-case

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.