elisp: Basic Completion
19.6.1 Basic Completion Functions
---------------------------------
The following completion functions have nothing in themselves to do with
minibuffers. We describe them here to keep them near the higher-level
completion features that do use the minibuffer.
-- Function: try-completion string collection &optional predicate
This function returns the longest common substring of all possible
completions of STRING in COLLECTION.
COLLECTION is called the “completion table”. Its value must be a
list of strings or cons cells, an obarray, a hash table, or a
completion function.
‘try-completion’ compares STRING against each of the permissible
completions specified by the completion table. If no permissible
completions match, it returns ‘nil’. If there is just one matching
completion, and the match is exact, it returns ‘t’. Otherwise, it
returns the longest initial sequence common to all possible
matching completions.
If COLLECTION is a list, the permissible completions are specified
by the elements of the list, each of which should be either a
string, or a cons cell whose CAR is either a string or a symbol (a
symbol is converted to a string using ‘symbol-name’). If the list
contains elements of any other type, those are ignored.
If COLLECTION is an obarray (
Creating Symbols), the names
of all symbols in the obarray form the set of permissible
completions.
If COLLECTION is a hash table, then the keys that are strings or
symbols are the possible completions. Other keys are ignored.
You can also use a function as COLLECTION. Then the function is
solely responsible for performing completion; ‘try-completion’
returns whatever this function returns. The function is called
with three arguments: STRING, PREDICATE and ‘nil’ (the third
argument is so that the same function can be used in
‘all-completions’ and do the appropriate thing in either case).
Programmed Completion.
If the argument PREDICATE is non-‘nil’, then it must be a function
of one argument, unless COLLECTION is a hash table, in which case
it should be a function of two arguments. It is used to test each
possible match, and the match is accepted only if PREDICATE returns
non-‘nil’. The argument given to PREDICATE is either a string or a
cons cell (the CAR of which is a string) from the alist, or a
symbol (_not_ a symbol name) from the obarray. If COLLECTION is a
hash table, PREDICATE is called with two arguments, the string key
and the associated value.
In addition, to be acceptable, a completion must also match all the
regular expressions in ‘completion-regexp-list’. (Unless
COLLECTION is a function, in which case that function has to handle
‘completion-regexp-list’ itself.)
In the first of the following examples, the string ‘foo’ is matched
by three of the alist CARs. All of the matches begin with the
characters ‘fooba’, so that is the result. In the second example,
there is only one possible match, and it is exact, so the return
value is ‘t’.
(try-completion
"foo"
'(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
⇒ "fooba"
(try-completion "foo" '(("barfoo" 2) ("foo" 3)))
⇒ t
In the following example, numerous symbols begin with the
characters ‘forw’, and all of them begin with the word ‘forward’.
In most of the symbols, this is followed with a ‘-’, but not in
all, so no more than ‘forward’ can be completed.
(try-completion "forw" obarray)
⇒ "forward"
Finally, in the following example, only two of the three possible
matches pass the predicate ‘test’ (the string ‘foobaz’ is too
short). Both of those begin with the string ‘foobar’.
(defun test (s)
(> (length (car s)) 6))
⇒ test
(try-completion
"foo"
'(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
'test)
⇒ "foobar"
-- Function: all-completions string collection &optional predicate
This function returns a list of all possible completions of STRING.
The arguments to this function are the same as those of
‘try-completion’, and it uses ‘completion-regexp-list’ in the same
way that ‘try-completion’ does.
If COLLECTION is a function, it is called with three arguments:
STRING, PREDICATE and ‘t’; then ‘all-completions’ returns whatever
the function returns. Programmed Completion.
Here is an example, using the function ‘test’ shown in the example
for ‘try-completion’:
(defun test (s)
(> (length (car s)) 6))
⇒ test
(all-completions
"foo"
'(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
'test)
⇒ ("foobar1" "foobar2")
-- Function: test-completion string collection &optional predicate
This function returns non-‘nil’ if STRING is a valid completion
alternative specified by COLLECTION and PREDICATE. The arguments
are the same as in ‘try-completion’. For instance, if COLLECTION
is a list of strings, this is true if STRING appears in the list
and PREDICATE is satisfied.
This function uses ‘completion-regexp-list’ in the same way that
‘try-completion’ does.
If PREDICATE is non-‘nil’ and if COLLECTION contains several
strings that are equal to each other, as determined by
‘compare-strings’ according to ‘completion-ignore-case’, then
PREDICATE should accept either all or none of them. Otherwise, the
return value of ‘test-completion’ is essentially unpredictable.
If COLLECTION is a function, it is called with three arguments, the
values STRING, PREDICATE and ‘lambda’; whatever it returns,
‘test-completion’ returns in turn.
-- Function: completion-boundaries string collection predicate suffix
This function returns the boundaries of the field on which
COLLECTION will operate, assuming that STRING holds the text before
point and SUFFIX holds the text after point.
Normally completion operates on the whole string, so for all normal
collections, this will always return ‘(0 . (length SUFFIX))’. But
more complex completion such as completion on files is done one
field at a time. For example, completion of ‘"/usr/sh"’ will
include ‘"/usr/share/"’ but not ‘"/usr/share/doc"’ even if
‘"/usr/share/doc"’ exists. Also ‘all-completions’ on ‘"/usr/sh"’
will not include ‘"/usr/share/"’ but only ‘"share/"’. So if STRING
is ‘"/usr/sh"’ and SUFFIX is ‘"e/doc"’, ‘completion-boundaries’
will return ‘(5 . 1)’ which tells us that the COLLECTION will only
return completion information that pertains to the area after
‘"/usr/"’ and before ‘"/doc"’.
If you store a completion alist in a variable, you should mark the
variable as risky by giving it a non-‘nil’ ‘risky-local-variable’
property. File Local Variables.
-- Variable: completion-ignore-case
If the value of this variable is non-‘nil’, case is not considered
significant in completion. Within ‘read-file-name’, this variable
is overridden by ‘read-file-name-completion-ignore-case’ (
Reading File Names); within ‘read-buffer’, it is overridden by
‘read-buffer-completion-ignore-case’ (High-Level
Completion).
-- Variable: completion-regexp-list
This is a list of regular expressions. The completion functions
only consider a completion acceptable if it matches all regular
expressions in this list, with ‘case-fold-search’ (Searching
and Case) bound to the value of ‘completion-ignore-case’.
-- Macro: lazy-completion-table var fun
This macro provides a way to initialize the variable VAR as a
collection for completion in a lazy way, not computing its actual
contents until they are first needed. You use this macro to
produce a value that you store in VAR. The actual computation of
the proper value is done the first time you do completion using
VAR. It is done by calling FUN with no arguments. The value FUN
returns becomes the permanent value of VAR.
Here is an example:
(defvar foo (lazy-completion-table foo make-my-alist))
There are several functions that take an existing completion table
and return a modified version. ‘completion-table-case-fold’ returns a
case-insensitive table. ‘completion-table-in-turn’ and
‘completion-table-merge’ combine multiple input tables in different
ways. ‘completion-table-subvert’ alters a table to use a different
initial prefix. ‘completion-table-with-quoting’ returns a table
suitable for operating on quoted text.
‘completion-table-with-predicate’ filters a table with a predicate
function. ‘completion-table-with-terminator’ adds a terminating string.
Info Catalog
elisp: Completion
elisp: Minibuffer Completion