This section describes the basic interface for reading from the minibuffer with completion.
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 ""
. 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.
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.