Go to the previous, next section.

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

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 user is not allowed to exit unless the input completes to an element of collection. If require-match is neither nil nor t, then completing-read does not exit unless the input typed is itself an element of collection. To accomplish this, completing-read calls read-minibuffer. It uses the value of 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.

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.

Case is ignored when comparing the input against the possible matches if the built-in variable completion-ignore-case is non-nil. See section Basic Completion Functions.

For example:

(completing-read
 "Complete a foo: "
 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
 nil t "fo")

;; After evaluating 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 which actually do completion. Here they are:

minibuffer-completion-table

This variable is bound to the collection argument. It is passed to the try-completion function.

minibuffer-completion-predicate

This variable is bound to the predicate argument. It is passed to the try-completion function.

minibuffer-completion-confirm

This variable is bound to the require-match argument. It is used in the minibuffer-complete-and-exit function.

Go to the previous, next section.