GNU Info

(elisp)Minibuffer Completion

---

Next: Completion Commands Prev: Basic Completion Up: Completion

---

Enter node , (file) or (file)node

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'.  Note: 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'.  Note: 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 (Note: Input
     Methods) and the setting of `enable-multibyte-characters' (Note:
     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'.  Note: 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 Note: Completion Commands.