24.5.2 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 default

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 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.

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-expression. 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 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.

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 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 Completion Commands.