20.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 inherit-input-method

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 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 20.5.3 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 20.4 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 section 33.11 Input Methods) and the setting of enable-multibyte-characters (see section 33.1 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 20.5.1 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 20.5.3 Minibuffer Commands that Do Completion.