24.5.1 Basic Completion Functions

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.

Function: try-completion string collection &optional predicate

This function returns the longest common prefix 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 returns nil. If only one permissible completion matches, and the match is exact, then try-completion returns t. 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 and nil. (The reason for the third argument is so that the same function can be used in all-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)))
     ⇒ 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.

If collection is a function, it is called with three arguments: string, predicate and t; then all-completions returns whatever the function returns. See 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")

Variable: completion-ignore-case

If the value of this variable is non-nil, SXEmacs does not consider case significant in completion.