GNU Info

Info Node: (elisp)High-Level Completion

(elisp)High-Level Completion


Next: Reading File Names Prev: Completion Commands Up: Completion
Enter node , (file) or (file)node

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

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

   In most cases, you should not call these functions in the middle of a
Lisp function.  When possible, do all minibuffer input as part of
reading the arguments for a command, in the `interactive'
specification.  Note: Defining Commands.

 - 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 or a buffer.  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 validity; 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 evaluation of 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"

 - Variable: read-buffer-function
     This variable specifies how to read buffer names.  For example, if
     you set this variable to `iswitchb-read-buffer', all Emacs commands
     that call `read-buffer' to read a buffer name will actually use the
     `iswitchb' package to read it.

 - Function: read-command prompt &optional default
     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.

     The argument DEFAULT specifies what to return if the user enters
     null input.  It can be a symbol or a string; if it is a string,
     `read-command' interns it before returning it.  If DEFAULT is
     `nil', that means no default has been specified; then if the user
     enters null input, the return value is `nil'.

          (read-command "Command name? ")
          
          ;; After evaluation of the preceding expression,
          ;;   the following prompt appears with an empty 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
     `completing-read'.  It uses the variable `obarray' so as to
     complete in the set of extant Lisp symbols, and it uses the
     `commandp' predicate so as to accept only command names:

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

 - Function: read-variable prompt &optional default
     This function reads the name of a user variable and returns it as a
     symbol.

     The argument DEFAULT specifies what to return if the user enters
     null input.  It can be a symbol or a string; if it is a string,
     `read-variable' interns it before returning it.  If DEFAULT is
     `nil', that means no default has been specified; then if the user
     enters null input, the return value is `nil'.

          (read-variable "Variable name? ")
          
          ;; After evaluation of 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' returns
     `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))

   See also the functions `read-coding-system' and
`read-non-nil-coding-system', in Note: User-Chosen Coding Systems.


automatically generated by info2www version 1.2.2.9