X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/a5b99fab3a802e4fec3dc0d86d70b656d4b01c3a..94bc79845c7bec68561e086d7494749a40e48c23:/doc/lispref/eval.texi diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi index 81b5c27d94..e81efd1089 100644 --- a/doc/lispref/eval.texi +++ b/doc/lispref/eval.texi @@ -1,7 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 2001, 2002, 2003, -@c 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. +@c Copyright (C) 1990-1994, 1998, 2001-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/eval @node Evaluation, Control Structures, Symbols, Top @@ -40,12 +39,15 @@ interpreter. @cindex form @cindex expression - A Lisp object that is intended for evaluation is called an -@dfn{expression} or a @dfn{form}. The fact that forms are data -objects and not merely text is one of the fundamental differences -between Lisp-like languages and typical programming languages. Any -object can be evaluated, but in practice only numbers, symbols, lists -and strings are evaluated very often. +@cindex S-expression + A Lisp object that is intended for evaluation is called a @dfn{form} +or @dfn{expression}@footnote{It is sometimes also referred to as an +@dfn{S-expression} or @dfn{sexp}, but we generally do not use this +terminology in this manual.}. The fact that forms are data objects +and not merely text is one of the fundamental differences between +Lisp-like languages and typical programming languages. Any object can +be evaluated, but in practice only numbers, symbols, lists and strings +are evaluated very often. In subsequent sections, we will describe the details of what evaluation means for each kind of form. @@ -65,8 +67,8 @@ evaluate a @dfn{function call} form such as @code{(car x)}, Emacs first evaluates the argument (the subform @code{x}). After evaluating the argument, Emacs @dfn{executes} the function (@code{car}), and if the function is written in Lisp, execution works by evaluating the -@dfn{body} of the function. (In this example, however, @code{car} is -not a Lisp function; it is a primitive function implemented in C.) +@dfn{body} of the function (in this example, however, @code{car} is +not a Lisp function; it is a primitive function implemented in C). @xref{Functions}, for more information about functions and function calls. @@ -78,9 +80,8 @@ variables (@pxref{Variables}).@footnote{This definition of that can affect the result of a program.} Whenever a form refers to a variable without creating a new binding for it, the variable evaluates to the value given by the current environment. Evaluating a form may -create a new environment for recursive evaluation, by binding -variables (@pxref{Local Variables}). Such environments are temporary, -and vanish when the evaluation of the form is complete. +also temporarily alter the environment by binding variables +(@pxref{Local Variables}). @cindex side effect Evaluating a form may also make changes that persist; these changes @@ -98,19 +99,19 @@ interpretation. @xref{Command Loop}. @node Forms @section Kinds of Forms - A Lisp object that is intended to be evaluated is called a @dfn{form}. -How Emacs evaluates a form depends on its data type. Emacs has three -different kinds of form that are evaluated differently: symbols, lists, -and ``all other types.'' This section describes all three kinds, one by -one, starting with the ``all other types'' which are self-evaluating -forms. + A Lisp object that is intended to be evaluated is called a +@dfn{form} (or an @dfn{expression}). How Emacs evaluates a form +depends on its data type. Emacs has three different kinds of form +that are evaluated differently: symbols, lists, and ``all other +types.'' This section describes all three kinds, one by one, starting +with the ``all other types'' which are self-evaluating forms. @menu * Self-Evaluating Forms:: Forms that evaluate to themselves. * Symbol Forms:: Symbols evaluate as variables. * Classifying Lists:: How to distinguish various sorts of list forms. * Function Indirection:: When a symbol appears as the car of a list, - we find the real function via the symbol. + we find the real function via the symbol. * Function Forms:: Forms that call functions. * Macro Forms:: Forms that call macros. * Special Forms:: "Special forms" are idiosyncratic primitives, @@ -178,9 +179,9 @@ program. Here is an example: @cindex symbol evaluation When a symbol is evaluated, it is treated as a variable. The result -is the variable's value, if it has one. If it has none (if its value -cell is void), an error is signaled. For more information on the use of -variables, see @ref{Variables}. +is the variable's value, if it has one. If the symbol has no value as +a variable, the Lisp interpreter signals an error. For more +information on the use of variables, see @ref{Variables}. In the following example, we set the value of a symbol with @code{setq}. Then we evaluate the symbol, and get back the value that @@ -586,6 +587,11 @@ occurrence in a program being run. On rare occasions, you may need to write code that evaluates a form that is computed at run time, such as after reading a form from text being edited or getting one from a property list. On these occasions, use the @code{eval} function. +Often @code{eval} is not needed and something else should be used instead. +For example, to get the value of a variable, while @code{eval} works, +@code{symbol-value} is preferable; or rather than store expressions +in a property list that then need to go through @code{eval}, it is better to +store functions instead that are then passed to @code{funcall}. The functions and variables described in this section evaluate forms, specify limits to the evaluation process, or record recently returned @@ -597,11 +603,15 @@ to store an expression in the data structure and evaluate it. Using functions provides the ability to pass information to them as arguments. -@defun eval form -This is the basic function evaluating an expression. It evaluates +@defun eval form &optional lexical +This is the basic function for evaluating an expression. It evaluates @var{form} in the current environment and returns the result. How the evaluation proceeds depends on the type of the object (@pxref{Forms}). +The argument @var{lexical}, if non-@code{nil}, means to evaluate +@var{form} using lexical scoping rules for variables, instead of the +default dynamic scoping rules. @xref{Lexical Binding}. + Since @code{eval} is a function, the argument expression that appears in a call to @code{eval} is evaluated twice: once as preparation before @code{eval} is called, and again by the @code{eval} function itself. @@ -672,7 +682,7 @@ output of the output functions is printed in the echo area. @code{eval-current-buffer} is an alias for this command. @end deffn -@defvar max-lisp-eval-depth +@defopt max-lisp-eval-depth @anchor{Definition of max-lisp-eval-depth} This variable defines the maximum depth allowed in calls to @code{eval}, @code{apply}, and @code{funcall} before an error is signaled (with error @@ -697,7 +707,7 @@ execute. @code{max-specpdl-size} provides another limit on nesting. @xref{Definition of max-specpdl-size,, Local Variables}. -@end defvar +@end defopt @defvar values The value of this variable is a list of the values returned by all the @@ -748,7 +758,3 @@ particular elements, like this: @end group @end example @end defvar - -@ignore - arch-tag: f723a4e0-31b3-453f-8afc-0bf8fd276d57 -@end ignore