Next: , Previous: , Up: Completion   [Contents][Index]

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


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

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-dynamic as a transducer between that interface and the interface for programmed completion functions.

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.

Next: , Previous: , Up: Completion   [Contents][Index]