This section describes the basic interface for reading from the minibuffer with completion.
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.
The actual completion is done by passing the completion table
collection and the completion predicate predicate to the
function try-completion
(see Basic Completion Functions). This
happens in certain commands bound in the local keymaps used for
completion. Some of these commands also call test-completion
.
Thus, if predicate is non-nil
, it should be compatible
with collection and completion-ignore-case
.
See Definition of test-completion.
See Programmed Completion, for detailed requirements when collection is a function.
The value of the optional argument require-match determines how the user may exit the minibuffer:
nil
, the usual minibuffer exit commands work regardless of
the input in the minibuffer.
t
, the usual minibuffer exit commands won’t exit unless the
input completes to an element of collection.
confirm
, the user can exit with any input, but is asked for
confirmation if the input is not an element of collection.
confirm-after-completion
, the user can exit with any input,
but is asked for confirmation if the preceding command was a
completion command (i.e., one of the commands in
minibuffer-confirm-exit-commands
) and the resulting input is
not an element of collection. See Minibuffer Commands that Do Completion.
nil
value if the input is
acceptable.
t
, except
that the exit commands won’t exit if it performs completion.
However, empty input is always permitted, regardless of the value of
require-match; in that case, completing-read
returns the
first element of default, if it is a list; ""
, if
default is nil
; or default. The string or strings
in default are also available to the user through the history
commands (see Minibuffer Commands). In addition, the completion
candidates are added to the “future history” when the values in
default are exhausted by M-n; see minibuffer-default-add-function.
The function completing-read
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 Minibuffer Commands that Do Completion.
The argument history specifies which history list variable to
use for saving the input and for minibuffer history commands. It
defaults to minibuffer-history
. If history is the symbol
t
, history is not recorded. See Minibuffer History.
The argument initial is mostly deprecated; we recommend using a
non-nil
value only in conjunction with specifying a cons cell
for history. See Initial Input. For default input, use
default instead.
If the argument inherit-input-method is non-nil
, then the
minibuffer inherits the current input method (see Input Methods) and the setting of enable-multibyte-characters
(see Text Representations) from whichever buffer was current before
entering the minibuffer.
If the variable completion-ignore-case
is
non-nil
, completion ignores case when comparing the input
against the possible matches. See Basic Completion Functions. In this mode
of operation, predicate must also ignore case, or you will get
surprising results.
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 variables to pass
information to the commands that actually do completion.
They are described in the following section.
The value of this variable must be a function, which is called by
completing-read
to actually do its work. It should accept the
same arguments as completing-read
. This can be bound to a
different function to completely override the normal behavior of
completing-read
.