Next: Minibuffer Completion, Up: Completion
The two functions try-completion
and all-completions
have nothing in themselves to do with minibuffers. We describe them in
this chapter so as to keep them near the higher-level completion
features that do use the minibuffer.
This function returns the longest common substring of all possible completions of string in collection. The value of collection must be an alist, an obarray, or a function that implements a virtual set of strings (see below).
Completion compares string against each of the permissible completions specified by collection; if the beginning of the permissible completion equals string, it matches. If no permissible completions match,
try-completion
returnsnil
. If only one permissible completion matches, and the match is exact, thentry-completion
returnst
. Otherwise, the value is the longest initial sequence common to all the permissible completions that match.If collection is an alist (see Association Lists), the cars of the alist elements form the set of permissible completions.
If collection is an obarray (see Creating Symbols), the names of all symbols in the obarray form the set of permissible completions. The global variable
obarray
holds an obarray containing the names of all interned Lisp symbols.Note that the only valid way to make a new obarray is to create it empty and then add symbols to it one by one using
intern
. Also, you cannot intern a given symbol in more than one obarray.If the argument predicate is non-
nil
, then it must be a function of one argument. 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 cons cell from the alist (the car of which is a string) or else it is a symbol (not a symbol name) from the obarray.You can also use a symbol that is 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 andnil
. (The reason for the third argument is so that the same function can be used inall-completions
and do the appropriate thing in either case.) See Programmed Completion.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 value is
t
.(try-completion "foo" '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))) => "fooba" (try-completion "foo" '(("barfoo" 2) ("foo" 3))) => tIn 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"
This function returns a list of all possible completions of string. The arguments to this function (aside from nospace) are the same as those of
try-completion
. If nospace is non-nil
, completions that start with a space are ignored unless string also starts with a space.If collection is a function, it is called with three arguments: string, predicate and
t
; thenall-completions
returns whatever the function returns. See Programmed Completion.Here is an example, using the function
test
shown in the example fortry-completion
:(defun test (s) (> (length (car s)) 6)) => test (all-completions "foo" '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) 'test) => ("foobar1" "foobar2")