GNU Info

(elisp)Basic Completion

---

Next: Minibuffer Completion Up: Completion

---

Enter node , (file) or (file)node

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 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' 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 (Note: Association Lists), the CARs of
     the alist elements form the set of permissible completions.

     If COLLECTION is an obarray (Note: 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.)  Note: 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
          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'.  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'; then `all-completions' returns whatever
     the function returns.  Note: 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', Emacs does not
     consider case significant in completion.