20.5.4 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. See section 21.2 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. See section 21.3 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 33.10.4 User-Chosen Coding Systems.