Info Catalog elisp: Basic Completion elisp: Completion elisp: Completion Commands

elisp: Minibuffer Completion

 
 19.6.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 history 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 the completion table
      COLLECTION and the completion predicate PREDICATE to the function
      ‘try-completion’ (Basic 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’.  Definition of test-completion.
 
      Programmed Completion, for detailed requirements when
      COLLECTION is a function.
 
      The value of the optional argument REQUIRE-MATCH determines how the
      user may exit the minibuffer:
 
         • If ‘nil’, the usual minibuffer exit commands work regardless
           of the input in the minibuffer.
 
         • If ‘t’, the usual minibuffer exit commands won’t exit unless
           the input completes to an element of COLLECTION.
 
         • If ‘confirm’, the user can exit with any input, but is asked
           for confirmation if the input is not an element of COLLECTION.
 
         • If ‘confirm-after-completion’, the user can exit with any
           input, but is asked for confirmation if the preceding command
           was a completion command (i.e., one of the commands in
           ‘minibuffer-confirm-exit-commands’) and the resulting input is
           not an element of COLLECTION.  Completion Commands.
 
         • Any other value of REQUIRE-MATCH behaves like ‘t’, except that
           the exit commands won’t exit if it performs completion.
 
      However, empty input is always permitted, regardless of the value
      of REQUIRE-MATCH; in that case, ‘completing-read’ returns the first
      element of DEFAULT, if it is a list; ‘""’, if DEFAULT is ‘nil’; or
      DEFAULT.  The string or strings in DEFAULT are 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’.  Completion Commands.
 
      The argument HISTORY specifies which history list variable to use
      for saving the input and for minibuffer history commands.  It
      defaults to ‘minibuffer-history’.  Minibuffer History.
 
      The argument INITIAL is mostly deprecated; we recommend using a
      non-‘nil’ value only in conjunction with specifying a cons cell for
      HISTORY.  Initial Input.  For default input, use DEFAULT
      instead.
 
      If the argument INHERIT-INPUT-METHOD is non-‘nil’, then the
      Text Representations::) from whichever buffer was current before
      entering the minibuffer.
 
      If the variable ‘completion-ignore-case’ is non-‘nil’, completion
      ignores case when comparing the input against the possible matches.
      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.
 
  -- Variable: completing-read-function
      The value of this variable must be a function, which is called by
      ‘completing-read’ to actually do its work.  It should accept the
      same arguments as ‘completing-read’.  This can be bound to a
      different function to completely override the normal behavior of
      ‘completing-read’.
 

Info Catalog elisp: Basic Completion elisp: Completion elisp: Completion Commands