(lispref.info)Minibuffer Completion

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'.  Note: Minibuffer History.

     Case is ignored when comparing the input against the possible
     matches if the built-in variable `completion-ignore-case' is
     non-`nil'.  Note: Basic Completion.

     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.