-\1f
-File: lispref.info, Node: Basic Completion, Next: Minibuffer Completion, Up: Completion
-
-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 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'; then `all-completions' returns whatever
- the function returns. *Note Programmed Completion::.
-
- If NOSPACE is non-`nil', completions that start with a space are
- ignored unless STRING also starts with a space.
-
- 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', XEmacs does not
- consider case significant in completion.
-
-\1f
-File: lispref.info, Node: Minibuffer Completion, Next: Completion Commands, Prev: Basic Completion, Up: Completion
-
-Completion and the Minibuffer
------------------------------
-
- This section describes the basic interface for reading from the
-minibuffer with completion.
-
- - Function: completing-read prompt collection &optional predicate
- require-match initial hist
- This function reads a string in the minibuffer, assisting the user
- by providing completion. It activates the minibuffer with prompt
- PROMPT, which must be a string. If INITIAL is non-`nil',
- `completing-read' inserts it into the minibuffer as part of the
- input. Then it allows the user to edit the input, providing
- several commands to attempt completion.
-
- The actual completion is done by passing COLLECTION and PREDICATE
- to the function `try-completion'. This happens in certain
- commands bound in the local keymaps used for completion.
-
- If REQUIRE-MATCH is `t', the usual minibuffer exit commands won't
- exit unless the input completes to an element of COLLECTION. If
- REQUIRE-MATCH is neither `nil' nor `t', then the exit commands
- won't exit unless the input typed is itself an element of
- COLLECTION. If REQUIRE-MATCH is `nil', the exit commands work
- regardless of the input in the minibuffer.
-
- The user can exit with null input by typing <RET> with an empty
- minibuffer. Then `completing-read' returns `nil'. This is how
- the user requests whatever default the command uses for the value
- being read. The user can return using <RET> in this way regardless
- of the value of REQUIRE-MATCH.
-
- The function `completing-read' works by calling `read-minibuffer'.
- It uses `minibuffer-local-completion-map' as the keymap if
- REQUIRE-MATCH is `nil', and uses `minibuffer-local-must-match-map'
- if REQUIRE-MATCH is non-`nil'. *Note Completion Commands::.
-
- The argument HIST specifies which history list variable to use for
- saving the input and for minibuffer history commands. It defaults
- to `minibuffer-history'. *Note Minibuffer History::.
-
- Completion ignores case when comparing the input against the
- possible matches, if the built-in variable
- `completion-ignore-case' is non-`nil'. *Note Basic Completion::.
-
- Here's an example of using `completing-read':
-
- (completing-read
- "Complete a foo: "
- '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
- nil t "fo")
-
- ;; After evaluation of the preceding expression,
- ;; the following appears in the minibuffer:
-
- ---------- Buffer: Minibuffer ----------
- Complete a foo: fo-!-
- ---------- Buffer: Minibuffer ----------
-
- If the user then types `<DEL> <DEL> b <RET>', `completing-read'
- returns `barfoo'.
-
- The `completing-read' function binds three variables to pass
- information to the commands that actually do completion. These
- variables are `minibuffer-completion-table',
- `minibuffer-completion-predicate' and
- `minibuffer-completion-confirm'. For more information about them,
- see *Note Completion Commands::.
-
-\1f
-File: lispref.info, Node: Completion Commands, Next: High-Level Completion, Prev: Minibuffer Completion, Up: Completion
-
-Minibuffer Commands That Do Completion
---------------------------------------
-
- This section describes the keymaps, commands and user options used in
-the minibuffer to do completion.
-
- - Variable: minibuffer-local-completion-map
- `completing-read' uses this value as the local keymap when an
- exact match of one of the completions is not required. By
- default, this keymap makes the following bindings:
-
- `?'
- `minibuffer-completion-help'
-
- <SPC>
- `minibuffer-complete-word'
-
- <TAB>
- `minibuffer-complete'
-
- with other characters bound as in `minibuffer-local-map' (*note
- Text from Minibuffer::).
-
- - Variable: minibuffer-local-must-match-map
- `completing-read' uses this value as the local keymap when an
- exact match of one of the completions is required. Therefore, no
- keys are bound to `exit-minibuffer', the command that exits the
- minibuffer unconditionally. By default, this keymap makes the
- following bindings:
-
- `?'
- `minibuffer-completion-help'
-
- <SPC>
- `minibuffer-complete-word'
-
- <TAB>
- `minibuffer-complete'
-
- <LFD>
- `minibuffer-complete-and-exit'
-
- <RET>
- `minibuffer-complete-and-exit'
-
- with other characters bound as in `minibuffer-local-map'.
-
- - Variable: minibuffer-completion-table
- The value of this variable is the alist or obarray used for
- completion in the minibuffer. This is the global variable that
- contains what `completing-read' passes to `try-completion'. It is
- used by minibuffer completion commands such as
- `minibuffer-complete-word'.
-
- - Variable: minibuffer-completion-predicate
- This variable's value is the predicate that `completing-read'
- passes to `try-completion'. The variable is also used by the other
- minibuffer completion functions.
-
- - Command: minibuffer-complete-word
- This function completes the minibuffer contents by at most a single
- word. Even if the minibuffer contents have only one completion,
- `minibuffer-complete-word' does not add any characters beyond the
- first character that is not a word constituent. *Note Syntax
- Tables::.
-
- - Command: minibuffer-complete
- This function completes the minibuffer contents as far as possible.
-
- - Command: minibuffer-complete-and-exit
- This function completes the minibuffer contents, and exits if
- confirmation is not required, i.e., if
- `minibuffer-completion-confirm' is non-`nil'. If confirmation
- _is_ required, it is given by repeating this command
- immediately--the command is programmed to work without confirmation
- when run twice in succession.
-
- - Variable: minibuffer-completion-confirm
- When the value of this variable is non-`nil', XEmacs asks for
- confirmation of a completion before exiting the minibuffer. The
- function `minibuffer-complete-and-exit' checks the value of this
- variable before it exits.
-
- - Command: minibuffer-completion-help
- This function creates a list of the possible completions of the
- current minibuffer contents. It works by calling `all-completions'
- using the value of the variable `minibuffer-completion-table' as
- the COLLECTION argument, and the value of
- `minibuffer-completion-predicate' as the PREDICATE argument. The
- list of completions is displayed as text in a buffer named
- `*Completions*'.
-
- - Function: display-completion-list completions
- This function displays COMPLETIONS to the stream in
- `standard-output', usually a buffer. (*Note Read and Print::, for
- more information about streams.) The argument COMPLETIONS is
- normally a list of completions just returned by `all-completions',
- but it does not have to be. Each element may be a symbol or a
- string, either of which is simply printed, or a list of two
- strings, which is printed as if the strings were concatenated.
-
- This function is called by `minibuffer-completion-help'. The most
- common way to use it is together with
- `with-output-to-temp-buffer', like this:
-
- (with-output-to-temp-buffer "*Completions*"
- (display-completion-list
- (all-completions (buffer-string) my-alist)))
-
- - User Option: completion-auto-help
- If this variable is non-`nil', the completion commands
- automatically display a list of possible completions whenever
- nothing can be completed because the next character is not
- uniquely determined.
-