(lispref.info)Minibuffer Completion
Next: Completion Commands Prev: Programmed 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 user is not allowed to exit unless
the input completes to an element of COLLECTION. If REQUIRE-MATCH
is neither `nil' nor `t', then `completing-read' does not exit
unless the input typed is itself an element of COLLECTION. To
accomplish this, `completing-read' calls `read-minibuffer'. It
uses the value of `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'.
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.
Case is ignored when comparing the input against the possible
matches if the built-in variable `completion-ignore-case' is
non-`nil'. Note: Basic Completion.
For example:
(completing-read
"Complete a foo: "
'(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
nil t "fo")
;; After evaluating 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 which actually do completion. Here
they are:
`minibuffer-completion-table'
This variable is bound to the COLLECTION argument. It is
passed to the `try-completion' function.
`minibuffer-completion-predicate'
This variable is bound to the PREDICATE argument. It is
passed to the `try-completion' function.
`minibuffer-completion-confirm'
This variable is bound to the REQUIRE-MATCH argument. It is
used in the `minibuffer-complete-and-exit' function.
automatically generated by info2www