24.3 Reading Lisp Objects with the Minibuffer

This section describes functions for reading Lisp objects with the minibuffer.

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

This function reads a Lisp object using the minibuffer, and returns it without evaluating it. The arguments prompt and initial are used as in read-from-minibuffer.

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 is a simplified interface to the read-from-minibuffer function:

(read-expression prompt initial history default-value)
≡
(read-from-minibuffer prompt initial nil t
                      history nil default-value)

Here is an example in which we supply the string "(testing)" as initial input:

(read-expression
 "Enter an expression: " (format "%s" '(testing)))

;; Here is how the minibuffer is displayed:

---------- Buffer: Minibuffer ----------
Enter an expression: (testing)∗
---------- Buffer: Minibuffer ----------

The user can type RET immediately to use the initial input as a default, or can edit the input.

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

This is a FSF Emacs compatible function. Use read-expression instead.

Function: eval-minibuffer prompt &optional initial history default-value

This function reads a Lisp expression using the minibuffer, evaluates it, then returns the result. The arguments prompt and initial are used as in read-from-minibuffer.

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 simply evaluates the result of a call to read-expression:

(eval-minibuffer prompt initial)
≡
(eval (read-expression prompt initial))

Function: edit-and-eval-command prompt form &optional history

This function reads a Lisp expression in the minibuffer, and then evaluates it. The difference between this command and eval-minibuffer is that here the initial form is not optional and it is treated as a Lisp object to be converted to printed representation rather than as a string of text. It is printed with prin1, so if it is a string, double-quote characters (‘"’) appear in the initial text. See Output Functions.

The first thing edit-and-eval-command does is to activate the minibuffer with prompt as the prompt. Then it inserts the printed representation of form in the minibuffer, and lets the user edit it. When the user exits the minibuffer, the edited text is read with read and then evaluated. The resulting value becomes the value of edit-and-eval-command.

In the following example, we offer the user an expression with initial text which is a valid form already:

(edit-and-eval-command "Please edit: " '(forward-word 1))

;; After evaluation of the preceding expression,
;;   the following appears in the minibuffer:

---------- Buffer: Minibuffer ----------
Please edit: (forward-word 1)∗
---------- Buffer: Minibuffer ----------

Typing RET right away would exit the minibuffer and evaluate the expression, thus moving point forward one word. edit-and-eval-command returns t in this example.