This section describes the basic interface for reading from the minibuffer with 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 nil, the exit commands work regardless
of the input in the minibuffer. 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 already in the buffer matches an element of collection.
However, empty input is always permitted, regardless of the value of
require-match; in that case, completing-read returns
default. The value of default (if non-nil) is also
available to the user through the history commands.
The user can exit with null input by typing RET with an empty
minibuffer. Then completing-read returns "". 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, and regardless of whether the empty string
is included in collection.
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. See section Minibuffer Commands That Do Completion.
The argument hist specifies which history list variable to use for
saving the input and for minibuffer history commands. It defaults to
minibuffer-history. See section Minibuffer History.
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.
In most cases, we recommend using default, and not initial.
If the argument inherit-input-method is non-nil, then the
minibuffer inherits the current input method (see section Input Methods) and the setting of enable-multibyte-characters
(see section Text Representations) from whichever buffer was current before
entering the minibuffer.
Completion ignores case when comparing the input against the possible
matches, if the built-in variable completion-ignore-case is
non-nil. See section Basic Completion Functions.
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 section Minibuffer Commands That Do Completion.
Go to the first, previous, next, last section, table of contents.