20.6.1 Basic Completion Functions

The completion functions try-completion, all-completions and test-completion 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.

If you store a completion alist in a variable, you should mark the variable as “risky” with a non-nil risky-local-variable property.

Function: try-completion string collection &optional predicate

This function returns the longest common substring of all possible completions of string in collection. The value of collection must be a list of strings or symbols, an alist, an obarray, a hash table, 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 (voir la section Association Lists), the permissible completions are the elements of the alist that are either strings, symbols, or conses whose CAR is a string or symbol. Symbols are converted to strings using symbol-name. Other elements of the alist are ignored. (Remember that in Emacs Lisp, the elements of alists do not have to be conses.) In particular, a list of strings or symbols is allowed, even though we usually do not think of such lists as alists.

If collection is an obarray (@pxref{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 collection is a hash table, then the keys that are strings are the possible completions. Other keys are ignored.

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.) Voir la section 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 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 nospace

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. Also, this function uses completion-regexp-list in the same way that try-completion does. The optional argument nospace only matters if string is the empty string. In that case, if nospace is non-nil, completions that start with a space are ignored.

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

Variable: completion-ignore-case

If the value of this variable is non-nil, Emacs does not consider case significant in 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 (voir la section 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 of use:

(defvar foo (lazy-completion-table foo make-my-alist))

Ce document a été généré par Eric Reinbold le 13 Octobre 2007 en utilisant texi2html 1.78.