27.9 Evaluating Emacs Lisp Expressions

Emacs Lisp mode is the major mode for editing Emacs Lisp. Its mode command is M-x emacs-lisp-mode.

Emacs provides several commands for evaluating Emacs Lisp expressions. You can use these commands in Emacs Lisp mode, to test your Emacs Lisp code as it is being written. For example, after re-writing a function, you can evaluate the function definition to make it take effect for subsequent function calls. These commands are also available globally, and can be used outside Emacs Lisp mode.

M-:

Read a single Emacs Lisp expression in the minibuffer, evaluate it, and print the value in the echo area ( eval-expression).

C-x C-e

Evaluate the Emacs Lisp expression before point, and print the value in the echo area ( eval-last-sexp).

C-M-x(in Emacs Lisp mode)M-x eval-defun

Evaluate the defun containing or after point, and print the value in the echo area ( eval-defun).

M-x eval-region

Evaluate all the Emacs Lisp expressions in the region.

M-x eval-buffer

Evaluate all the Emacs Lisp expressions in the buffer.

M-: ( eval-expression) reads an expression using the minibuffer, and evaluates it. (Before evaluating the expression, the current buffer switches back to the buffer that was current when you typed M-:, not the minibuffer into which you typed the expression.)

The command C-x C-e ( eval-last-sexp) evaluates the Emacs Lisp expression preceding point in the buffer, and displays the value in the echo area. When the result of an evaluation is an integer, it is displayed together with the value in other formats (octal, hexadecimal, and character if eval-expression-print-maximum-character, described below, allows it).

If M-: or C-x C-e is given a prefix argument, it inserts the value into the current buffer at point, rather than displaying it in the echo area. If the prefix argument is zero, any integer output is inserted together with its value in other formats (octal, hexadecimal, and character). Such a prefix argument also prevents abbreviation of the output according to the variables eval-expression-print-level and eval-expression-print-length (see below). Similarly, a prefix argument of -1 overrides the effect of eval-expression-print-length.

C-x C-e ( eval-last-sexp) treats defvar expressions specially. Normally, evaluating a defvar expression does nothing if the variable it defines already has a value. But this command unconditionally resets the variable to the initial value specified by the defvar; this is convenient for debugging Emacs Lisp programs. defcustom and defface expressions are treated similarly. Note the other commands documented in this section, except eval-defun, do not have this special feature.

The eval-defun command is bound to C-M-x in Emacs Lisp mode. It evaluates the top-level Lisp expression containing or following point, and prints the value in the echo area. In this context, a top-level expression is referred to as a “defun”, but it need not be an actual defun (function definition).

This command handles defvar/ defcustom/ defface forms the same way that eval-last-sexp does.

With a prefix argument, C-M-x instruments the function definition for Edebug, the Emacs Lisp Debugger. See Instrumenting for Edebug in the Emacs Lisp Reference Manual.

The command M-x eval-region parses the text of the region as one or more Lisp expressions, evaluating them one by one. M-x eval-buffer is similar but evaluates the entire buffer.

The options eval-expression-print-level and eval-expression-print-length control the maximum depth and length of lists to print in the result of the evaluation commands before abbreviating them. Supplying a zero prefix argument to eval-expression or eval-last-sexp causes lists to be printed in full. eval-expression-debug-on-error controls whether evaluation errors invoke the debugger when these commands are used; its default is t. eval-expression-print-maximum-character prevents integers which are larger than it from being displayed as characters.