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

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, or "", if default is nil. The value of default (if non-nil) is also available to the user through the history commands.

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

The argument initial is mostly deprecated; we recommend using a non-nil value only in conjunction with specifying a cons cell for hist. 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 built-in variable completion-ignore-case is non-nil, completion ignores case when comparing the input against the possible matches. See Basic Completion. 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.