(lispref.info)High-Level Completion


Next: Reading File Names Prev: Completion Commands Up: Completion

High-Level Completion  Functions
--------------------------------

   This section describes the higher-level convenient functions for
reading certain sorts of names with completion.

 - Function: read-buffer PROMPT &optional DEFAULT EXISTING
     This function reads the name of a buffer and returns it as a
     string.  The argument DEFAULT is the default name to use, the
     value to return if the user exits with an empty minibuffer.  If
     non-`nil', it should be a string.  It is mentioned in the prompt,
     but is not inserted in the minibuffer as initial input.

     If EXISTING is non-`nil', then the name specified must be that of
     an  existing buffer.  The usual commands to exit the minibuffer do
     not exit if the text is not valid, and RET does completion to
     attempt to find a valid name.  (However, DEFAULT is not checked
     for this; it is returned, whatever it is, if the user exits with
     the minibuffer empty.)

     In the following example, the user enters `minibuffer.t', and then
     types RET.  The argument EXISTING is `t', and the only buffer name
     starting with the given input is `minibuffer.texi', so that name
     is the value.

          (read-buffer "Buffer name? " "foo" t)
          ;; After evaluating the preceding expression,
          ;;   the following prompt appears,
          ;;   with an empty minibuffer:

          ---------- Buffer: Minibuffer ----------
          Buffer name? (default foo) -!-
          ---------- Buffer: Minibuffer ----------

          ;; The user types `minibuffer.t RET'.
          
               => "minibuffer.texi"

 - Function: read-command PROMPT
     This function reads the name of a command and returns it as a Lisp
     symbol.  The argument PROMPT is used as in `read-from-minibuffer'.
     Recall that a command is anything for which `commandp' returns
     `t', and a command name is a symbol for which `commandp' returns
     `t'.  Note: Interactive Call.

          (read-command "Command name? ")
          ;; After evaluating the preceding expression,
          ;;   the following appears in the minibuffer:

          ---------- Buffer: Minibuffer ----------
          Command name?
          ---------- Buffer: Minibuffer ----------

     If the user types `forward-c RET', then this function returns
     `forward-char'.

     The `read-command' function is a simplified interface to the
     `completing-read' function.  It uses the `commandp' predicate to
     allow only commands to be entered, and it uses the variable
     `obarray' so as to be able to complete all extant Lisp symbols:

          (read-command PROMPT)
          ==
          (intern (completing-read PROMPT obarray 'commandp t nil))

 - Function: read-variable PROMPT
     This function reads the name of a user variable and returns it as a
     symbol.

          (read-variable "Variable name? ")
          
          ;; After evaluating the preceding expression,
          ;;   the following prompt appears,
          ;;   with an empty minibuffer:

          ---------- Buffer: Minibuffer ----------
          Variable name? -!-
          ---------- Buffer: Minibuffer ----------

     If the user then types `fill-p RET', `read-variable' will return
     `fill-prefix'.

     This function is similar to `read-command', but uses the predicate
     `user-variable-p' instead of `commandp':

          (read-variable PROMPT)
          ==
          (intern
           (completing-read PROMPT obarray 'user-variable-p t nil))


automatically generated by info2www