Next: Reading File Names, Previous: Completion Commands, Up: Completion
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. See Defining Commands.
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"
This variable specifies how to read buffer names. For example, if you set this variable to
iswitchb-read-buffer
, all Emacs commands that callread-buffer
to read a buffer name will actually use theiswitchb
package to read it.
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 whichcommandp
returnst
, and a command name is a symbol for whichcommandp
returnst
. See 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 isnil
, that means no default has been specified; then if the user enters null input, the return value isnil
.(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 tocompleting-read
. It uses the variableobarray
so as to complete in the set of extant Lisp symbols, and it uses thecommandp
predicate so as to accept only command names:(read-command prompt) == (intern (completing-read prompt obarray 'commandp t nil))
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 isnil
, that means no default has been specified; then if the user enters null input, the return value isnil
.(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
returnsfill-prefix
.This function is similar to
read-command
, but uses the predicateuser-variable-p
instead ofcommandp
:(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 User-Chosen Coding Systems.