Next: Completion Commands, Previous: Basic Completion, Up: Completion
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 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 ist
, the usual minibuffer exit commands won't exit unless the input completes to an element of collection. If require-match is neithernil
nort
, 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 callingread-minibuffer
. It usesminibuffer-local-completion-map
as the keymap if require-match isnil
, and usesminibuffer-local-must-match-map
if require-match is non-nil
. See 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
. See 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.We discourage use of a non-
nil
value for initial, because it is an intrusive interface. The history list feature (which did not exist when we introduced initial) offers a far more convenient and general way for the user to get the default and edit it, and it is always available.If the argument inherit-input-method is non-
nil
, then the minibuffer inherits the current input method (see Input Methods) and the setting ofenable-multibyte-characters
(see 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 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
returnsbarfoo
.The
completing-read
function binds three variables to pass information to the commands that actually do completion. These variables areminibuffer-completion-table
,minibuffer-completion-predicate
andminibuffer-completion-confirm
. For more information about them, see Completion Commands.