Sometimes it is not possible to create an alist or an obarray containing all the intended possible completions. 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. Your function should call the predicate for each possible match,
and ignore the possible match if the predicate returns nil.
There are currently four methods, i.e. four flag values, one for each of the four different basic operations:
nil specifies try-completion. The completion function
should return the completion of the specified string, or t if the
string is a unique and exact match already, or nil if the string
matches no possibility.
If the string is an exact match for one possibility, but also matches
other longer possibilities, the function should return the string, not
t.
t specifies all-completions. The completion function
should return a list of all possible completions of the specified
string.
lambda specifies test-completion. The completion
function should return t if the specified string is an exact
match for some possibility; nil otherwise.
(boundaries . SUFFIX) specifies completion-boundaries.
The function should return a value of the form (boundaries
START . END) where START is the position of the beginning boundary in
in the string to complete, and END is the position of the end boundary
in SUFFIX.
It would be consistent and clean for completion functions to allow lambda expressions (lists that are functions) as well as function symbols as collection, but this is impossible. Lists as completion tables already have other meanings, and it would be unreliable to treat one differently just because it is also a possible function. So you must arrange for any function you wish to use for completion to be encapsulated in a symbol.
This function is a convenient way to write a function that can act as 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.
The value of this variable, if non-
nil, should be a function for “annotating” the entries in the ‘*Completions*’ buffer. The function should accept a single argument, the completion string for an entry. It should return an additional string to display next to that entry in the ‘*Completions*’ buffer, ornilif no additional string is to be displayed.The function can determine the collection used for the current completion via the variable
minibuffer-completion-table(see Completion Commands).