20.2 Reading Text Strings with the Minibuffer

The most basic primitive for minibuffer input is read-from-minibuffer, which can be used to read either a string or a Lisp object in textual form. The function read-regexp is used for reading regular expressions (see Regular Expressions), which are a special kind of string. There are also specialized functions for reading commands, variables, file names, etc. (see Completion).

In most cases, you should not call minibuffer input functions in the middle of a Lisp function. Instead, do all minibuffer input as part of reading the arguments for a command, in the interactive specification. See Defining Commands.

— Function: read-from-minibuffer prompt-string &optional initial-contents keymap read hist default inherit-input-method

This function is the most general way to get input from the minibuffer. By default, it accepts arbitrary text and returns it as a string; however, if read is non-nil, then it uses read to convert the text into a Lisp object (see Input Functions).

The first thing this function does is to activate a minibuffer and display it with prompt-string as the prompt. This value must be a string. Then the user can edit text in the minibuffer.

When the user types a command to exit the minibuffer, read-from-minibuffer constructs the return value from the text in the minibuffer. Normally it returns a string containing that text. However, if read is non-nil, read-from-minibuffer reads the text and returns the resulting Lisp object, unevaluated. (See Input Functions, for information about reading.)

The argument default specifies default values to make available through the history commands. It should be a string, a list of strings, or nil. The string or strings become the minibuffer's “future history,” available to the user with M-n.

If read is non-nil, then default is also used as the input to read, if the user enters empty input. If default is a list of strings, the first string is used as the input. If default is nil, empty input results in an end-of-file error. However, in the usual case (where read is nil), read-from-minibuffer ignores default when the user enters empty input and returns an empty string, "". In this respect, it differs from all the other minibuffer input functions in this chapter.

If keymap is non-nil, that keymap is the local keymap to use in the minibuffer. If keymap is omitted or nil, the value of minibuffer-local-map is used as the keymap. Specifying a keymap is the most important way to customize the minibuffer for various applications such as completion.

The argument hist specifies which history list variable to use for saving the input and for history commands used in the minibuffer. It defaults to minibuffer-history. See Minibuffer History.

If the variable minibuffer-allow-text-properties is non-nil, then the string which is returned includes whatever text properties were present in the minibuffer. Otherwise all the text properties are stripped when the value is returned.

If the argument inherit-input-method is non-nil, then the minibuffer inherits the current input method (see Input Methods) and the setting of enable-multibyte-characters (see Text Representations) from whichever buffer was current before entering the minibuffer.

Use of initial-contents is mostly deprecated; we recommend using a non-nil value only in conjunction with specifying a cons cell for hist. See Initial Input.

— Function: read-string prompt &optional initial history default inherit-input-method

This function reads a string from the minibuffer and returns it. The arguments prompt, initial, history and inherit-input-method are used as in read-from-minibuffer. The keymap used is minibuffer-local-map.

The optional argument default is used as in read-from-minibuffer, except that, if non-nil, it also specifies a default value to return if the user enters null input. As in read-from-minibuffer it should be a string, a list of strings, or nil which is equivalent to an empty string. When default is a string, that string is the default value. When it is a list of strings, the first string is the default value. (All these strings are available to the user in the “future minibuffer history.”)

This function works by calling the read-from-minibuffer function:

          (read-string prompt initial history default inherit)
          ==
          (let ((value
                 (read-from-minibuffer prompt initial nil nil
                                       history default inherit)))
            (if (and (equal value "") default)
                (if (consp default) (car default) default)
              value))
— Function: read-regexp prompt &optional default-value

This function reads a regular expression as a string from the minibuffer and returns it. The argument prompt is used as in read-from-minibuffer. The keymap used is minibuffer-local-map, and regexp-history is used as the history list (see regexp-history).

The optional argument default-value specifies a default value to return if the user enters null input; it should be a string, or nil which is equivalent to an empty string.

In addition, read-regexp collects a few useful candidates for input and passes them to read-from-minibuffer, to make them available to the user as the “future minibuffer history list” (see future list). These candidates are:

This function works by calling the read-from-minibuffer function, after computing the list of defaults as described above.

— Variable: minibuffer-allow-text-properties

If this variable is nil, then read-from-minibuffer strips all text properties from the minibuffer input before returning it. This variable also affects read-string. However, read-no-blanks-input (see below), as well as read-minibuffer and related functions (see Reading Lisp Objects With the Minibuffer), and all functions that do minibuffer input with completion, discard text properties unconditionally, regardless of the value of this variable.

— Variable: minibuffer-local-map

This is the default local keymap for reading from the minibuffer. By default, it makes the following bindings:

C-j
exit-minibuffer
<RET>
exit-minibuffer
C-g
abort-recursive-edit
M-n
<DOWN>
next-history-element
M-p
<UP>
previous-history-element
M-s
next-matching-history-element
M-r
previous-matching-history-element

— Function: read-no-blanks-input prompt &optional initial inherit-input-method

This function reads a string from the minibuffer, but does not allow whitespace characters as part of the input: instead, those characters terminate the input. The arguments prompt, initial, and inherit-input-method are used as in read-from-minibuffer.

This is a simplified interface to the read-from-minibuffer function, and passes the value of the minibuffer-local-ns-map keymap as the keymap argument for that function. Since the keymap minibuffer-local-ns-map does not rebind C-q, it is possible to put a space into the string, by quoting it.

This function discards text properties, regardless of the value of minibuffer-allow-text-properties.

          (read-no-blanks-input prompt initial)
          ==
          (let (minibuffer-allow-text-properties)
            (read-from-minibuffer prompt initial minibuffer-local-ns-map))
— Variable: minibuffer-local-ns-map

This built-in variable is the keymap used as the minibuffer local keymap in the function read-no-blanks-input. By default, it makes the following bindings, in addition to those of minibuffer-local-map:

<SPC>
exit-minibuffer
<TAB>
exit-minibuffer
?
self-insert-and-exit

blog comments powered by Disqus