24.2 Reading Text Strings with the Minibuffer

Most often, the minibuffer is used to read text as a string. It can also be used to read a Lisp object in textual form. The most basic primitive for minibuffer input is read-from-minibuffer; it can do either one.

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 spec. See Defining Commands.

Function: read-from-minibuffer prompt-string &optional initial-contents keymap read hist abbrev-table default

This function is the most general way to get input through 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, if initial-contents is a string, read-from-minibuffer inserts it into the minibuffer, leaving point at the end. The minibuffer appears with this text as its contents.

The value of initial-contents may also be a cons cell of the form (string . position). This means to insert string in the minibuffer but put point position characters from the beginning, rather than at the end.

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 a default value to make available through the history commands. It should be a string, or nil.

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 abbrev-table specifies local-abbrev-table in the minibuffer (see Standard Abbrev Tables).

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.

When the user types a command to exit the minibuffer, read-from-minibuffer uses the text in the minibuffer to produce its return value. Normally it simply makes 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.)

Usage note: The initial-contents argument and the default argument are two alternative features for more or less the same job. It does not make sense to use both features in a single call to read-from-minibuffer. In general, we recommend using default, since this permits the user to insert the default value when it is wanted, but does not burden the user with deleting it from the minibuffer on other occasions. However, if user is supposed to edit default value, initial-contents may be preferred.

Function: read-string prompt &optional initial history default-value

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

The optional argument history, if non-nil, specifies a history list and optionally the initial position in the list. The optional argument default-value specifies a default value to return if the user enters null input; it should be a string.

This function is a simplified interface to the read-from-minibuffer function:

(read-string prompt initial history default)
≡
(read-from-minibuffer prompt initial nil nil
                      history nil default)))

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

next-history-element

M-p

previous-history-element

M-r

next-matching-history-element

M-s

previous-matching-history-element