20.6.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. Voir la section 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.

The argument prompt should be a string ending with a colon and a space. If default is non-nil, the function inserts it in prompt before the colon to follow the convention for reading from the minibuffer with a default value (voir la section Emacs Programming Tips).

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. If existing is neither nil nor t, confirmation is required after completion. (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. Voir la section 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 (intern ""), that is, a symbol whose name is an empty string.

(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 (intern "").

(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.

In general, read-variable 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 User-Chosen Coding Systems, and read-input-method-name, in Input Methods.

Ce document a été généré par Eric Reinbold le 13 Octobre 2007 en utilisant texi2html 1.78.