(lispref.info)Basic Completion


Next: Programmed Completion Up: Completion

Basic Completion Functions
--------------------------

 - 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 which implements a virtual
     set of strings.

     If COLLECTION is an alist (Note: Association Lists.), completion
     compares the CAR of each cons cell in it against STRING; if the
     beginning of the CAR equals STRING, the cons cell matches.  If no
     cons cells match, `try-completion' returns `nil'.  If only one
     cons cell matches, and the match is exact, then `try-completion'
     returns `t'.  Otherwise, the value is the longest initial sequence
     common to all the matching strings in the alist.

     If COLLECTION is an obarray (Note: Creating Symbols.), the names
     of all symbols in the obarray form the space of possible
     completions.  They are tested and used just like the CARs of the
     elements of an association list.  (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.

     It is also possible to use a function symbol 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
     This function returns a list of all possible completions, instead
     of the longest substring they share.  The parameters to this
     function are the same as to `try-completion'.

     If COLLECTION is a function, it is called with three arguments:
     STRING, PREDICATE and `t', and `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))
           (function test))
               => ("foobar1" "foobar2")

 - Variable: completion-ignore-case
     If the value of this variable is non-`nil', Emacs does not
     consider case significant in completion.

   The two functions `try-completion' and `all-completions' have
nothing in themselves to do with minibuffers.  However, completion is
most often used there, which is why it is described in this chapter.


automatically generated by info2www