From 48e7f5493e4ffd31cb705adf982485c3b30fbbac Mon Sep 17 00:00:00 2001 From: =?utf8?q?Mattias=20Engdeg=C3=A5rd?= Date: Mon, 23 Oct 2023 11:12:33 +0200 Subject: [PATCH] Improved `eval` documentation Prompted by Michael Heerdegen. * src/eval.c (Feval): * doc/lispref/eval.texi (Eval): Be more precise about the LEXICAL argument. --- doc/lispref/eval.texi | 9 +++++---- src/eval.c | 10 +++++++--- 2 files changed, 12 insertions(+), 7 deletions(-) diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi index ea35d4d38c7..8af0ee49d02 100644 --- a/doc/lispref/eval.texi +++ b/doc/lispref/eval.texi @@ -740,16 +740,17 @@ type of the @var{form} object determines how it is evaluated. @xref{Forms}. The argument @var{lexical} specifies the scoping rule for local -variables (@pxref{Variable Scoping}). If it is omitted or @code{nil}, -that means to evaluate @var{form} using the default dynamic scoping -rule. If it is @code{t}, that means to use the lexical scoping rule. +variables (@pxref{Variable Scoping}). If it is @code{t}, that means +to evaluate @var{form} using lexical scoping; this is the recommended +value. If it is omitted or @code{nil}, that means to use the old +dynamic-only variable scoping rule. The value of @var{lexical} can also be a non-empty list specifying a particular @dfn{lexical environment} for lexical bindings; however, this feature is only useful for specialized purposes, such as in Emacs Lisp debuggers. Each member of the list is either a cons cell which represents a lexical symbol-value pair, or a symbol representing a -dynamically bound variable. +(special) variable that would use dynamic scoping if bound. Since @code{eval} is a function, the argument expression that appears in a call to @code{eval} is evaluated twice: once as preparation before diff --git a/src/eval.c b/src/eval.c index 9268b65aa85..f5397e9fb72 100644 --- a/src/eval.c +++ b/src/eval.c @@ -2364,9 +2364,13 @@ static Lisp_Object list_of_t; /* Never-modified constant containing (t). */ DEFUN ("eval", Feval, Seval, 1, 2, 0, doc: /* Evaluate FORM and return its value. -If LEXICAL is t, evaluate using lexical scoping. -LEXICAL can also be an actual lexical environment, in the form of an -alist mapping symbols to their value. */) +If LEXICAL is `t', evaluate using lexical binding by default. +This is the recommended value. + +If absent or `nil', use dynamic scoping only. + +LEXICAL can also represent an actual lexical environment; see the Info +node `(elisp)Eval' for details. */) (Lisp_Object form, Lisp_Object lexical) { specpdl_ref count = SPECPDL_INDEX (); -- 2.39.2