Remove mention of `require' in ediff.texi

[bpt/emacs.git] / doc / lispref / eval.texi

diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi
index e6ec489..74f3d9c 100644 (file)
--- 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 -*-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  Free Software Foundation, Inc.
+@c Copyright (C) 1990-1994, 1998, 2001-2011  Free Software Foundation, Inc.

 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/eval
 @node Evaluation, Control Structures, Symbols, Top
 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/eval
 @node Evaluation, Control Structures, Symbols, Top


@@ -30,75 +29,70 @@ function @code{eval}.
 @node Intro Eval
 @section Introduction to Evaluation
 
 @node Intro Eval
 @section Introduction to Evaluation
 

-  The Lisp interpreter, or evaluator, is the program that computes
-the value of an expression that is given to it.  When a function
-written in Lisp is called, the evaluator computes the value of the
-function by evaluating the expressions in the function body.  Thus,
-running any Lisp program really means running the Lisp interpreter.
-
-  How the evaluator handles an object depends primarily on the data
-type of the object.
+  The Lisp interpreter, or evaluator, is the part of Emacs that
+computes the value of an expression that is given to it.  When a
+function written in Lisp is called, the evaluator computes the value
+of the function by evaluating the expressions in the function body.
+Thus, running any Lisp program really means running the Lisp
+interpreter.

 @end ifnottex
 
 @end ifnottex
 

-@cindex forms
+@cindex form

 @cindex expression
   A Lisp object that is intended for evaluation is called an
 @cindex expression
   A Lisp object that is intended for evaluation is called an

-@dfn{expression} or a @dfn{form}.  The fact that expressions are data
+@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.
 
 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.
 

-  It is very common to read a Lisp expression and then evaluate the
-expression, but reading and evaluation are separate activities, and
-either can be performed alone.  Reading per se does not evaluate
-anything; it converts the printed representation of a Lisp object to the
-object itself.  It is up to the caller of @code{read} whether this
+  In subsequent sections, we will describe the details of what
+evaluation means for each kind of form.
+
+  It is very common to read a Lisp form and then evaluate the form,
+but reading and evaluation are separate activities, and either can be
+performed alone.  Reading per se does not evaluate anything; it
+converts the printed representation of a Lisp object to the object
+itself.  It is up to the caller of @code{read} to specify whether this

 object is a form to be evaluated, or serves some entirely different
 purpose.  @xref{Input Functions}.
 
 object is a form to be evaluated, or serves some entirely different
 purpose.  @xref{Input Functions}.
 

-  Do not confuse evaluation with command key interpretation.  The
-editor command loop translates keyboard input into a command (an
-interactively callable function) using the active keymaps, and then
-uses @code{call-interactively} to invoke the command.  The execution of
-the command itself involves evaluation if the command is written in
-Lisp, but that is not a part of command key interpretation itself.
-@xref{Command Loop}.
-

 @cindex recursive evaluation
 @cindex recursive evaluation

-  Evaluation is a recursive process.  That is, evaluation of a form may
-call @code{eval} to evaluate parts of the form.  For example, evaluation
-of a function call first evaluates each argument of the function call,
-and then evaluates each form in the function body.  Consider evaluation
-of the form @code{(car x)}: the subform @code{x} must first be evaluated
-recursively, so that its value can be passed as an argument to the
-function @code{car}.
-
-  Evaluation of a function call ultimately calls the function specified
-in it.  @xref{Functions}.  The execution of the function may itself work
-by evaluating the function definition; or the function may be a Lisp
-primitive implemented in C, or it may be a byte-compiled function
-(@pxref{Byte Compilation}).
+  Evaluation is a recursive process, and evaluating a form often
+involves evaluating parts within that form.  For instance, when you
+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.)
+@xref{Functions}, for more information about functions and function
+calls.

 
 @cindex environment
 
 @cindex environment

-  The evaluation of forms takes place in a context called the
-@dfn{environment}, which consists of the current values and bindings of
-all Lisp variables.@footnote{This definition of ``environment'' is
-specifically not intended to include all the data that can affect the
-result of a program.}  Whenever a form refers to a variable without
-creating a new binding for it, the value of the variable's binding in
-the current environment is used.  @xref{Variables}.
+  Evaluation takes place in a context called the @dfn{environment},
+which consists of the current values and bindings of all Lisp
+variables (@pxref{Variables}).@footnote{This definition of
+``environment'' is specifically not intended to include all the data
+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.

 
 @cindex side effect
 
 @cindex side effect

-  Evaluation of a form may create new environments for recursive
-evaluation by binding variables (@pxref{Local Variables}).  These
-environments are temporary and vanish by the time evaluation of the form
-is complete.  The form may also make changes that persist; these changes
-are called @dfn{side effects}.  An example of a form that produces side
-effects is @code{(setq foo 1)}.
+  Evaluating a form may also make changes that persist; these changes
+are called @dfn{side effects}.  An example of a form that produces a
+side effect is @code{(setq foo 1)}.

 
 

-  The details of what evaluation means for each kind of form are
-described below (@pxref{Forms}).
+  Do not confuse evaluation with command key interpretation.  The
+editor command loop translates keyboard input into a command (an
+interactively callable function) using the active keymaps, and then
+uses @code{call-interactively} to execute that command.  Executing the
+command usually involves evaluation, if the command is written in
+Lisp; however, this step is not considered a part of command key
+interpretation.  @xref{Command Loop}.

 
 @node Forms
 @section Kinds of Forms
 
 @node Forms
 @section Kinds of Forms


@@ -115,7 +109,7 @@ forms.
 * 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,
 * 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,
 * Function Forms::          Forms that call functions.
 * Macro Forms::             Forms that call macros.
 * Special Forms::           "Special forms" are idiosyncratic primitives,


@@ -130,13 +124,13 @@ forms.
 @cindex literal evaluation
 @cindex self-evaluating form
 
 @cindex literal evaluation
 @cindex self-evaluating form
 

-  A @dfn{self-evaluating form} is any form that is not a list or symbol.
-Self-evaluating forms evaluate to themselves: the result of evaluation
-is the same object that was evaluated.  Thus, the number 25 evaluates to
-25, and the string @code{"foo"} evaluates to the string @code{"foo"}.
-Likewise, evaluation of a vector does not cause evaluation of the
-elements of the vector---it returns the same vector with its contents
-unchanged.
+  A @dfn{self-evaluating form} is any form that is not a list or
+symbol.  Self-evaluating forms evaluate to themselves: the result of
+evaluation is the same object that was evaluated.  Thus, the number 25
+evaluates to 25, and the string @code{"foo"} evaluates to the string
+@code{"foo"}.  Likewise, evaluating a vector does not cause evaluation
+of the elements of the vector---it returns the same vector with its
+contents unchanged.

 
 @example
 @group
 
 @example
 @group


@@ -236,13 +230,12 @@ Scheme.
 @cindex indirection for functions
 @cindex void function
 
 @cindex indirection for functions
 @cindex void function
 

-  If the first element of the list is a symbol then evaluation examines
-the symbol's function cell, and uses its contents instead of the
-original symbol.  If the contents are another symbol, this process,
-called @dfn{symbol function indirection}, is repeated until it obtains a
-non-symbol.  @xref{Function Names}, for more information about using a
-symbol as a name for a function stored in the function cell of the
-symbol.
+  If the first element of the list is a symbol then evaluation
+examines the symbol's function cell, and uses its contents instead of
+the original symbol.  If the contents are another symbol, this
+process, called @dfn{symbol function indirection}, is repeated until
+it obtains a non-symbol.  @xref{Function Names}, for more information
+about symbol function indirection.

 
   One possible consequence of this process is an infinite loop, in the
 event that a symbol's function cell refers to the same symbol.  Or a
 
   One possible consequence of this process is an infinite loop, in the
 event that a symbol's function cell refers to the same symbol.  Or a


@@ -253,10 +246,10 @@ which ought to be a function or other suitable object.
 
 @kindex invalid-function
   More precisely, we should now have a Lisp function (a lambda
 
 @kindex invalid-function
   More precisely, we should now have a Lisp function (a lambda

-expression), a byte-code function, a primitive function, a Lisp macro, a
-special form, or an autoload object.  Each of these types is a case
-described in one of the following sections.  If the object is not one of
-these types, the error @code{invalid-function} is signaled.
+expression), a byte-code function, a primitive function, a Lisp macro,
+a special form, or an autoload object.  Each of these types is a case
+described in one of the following sections.  If the object is not one
+of these types, Emacs signals an @code{invalid-function} error.

 
   The following example illustrates the symbol indirection process.  We
 use @code{fset} to set the function cell of a symbol and
 
   The following example illustrates the symbol indirection process.  We
 use @code{fset} to set the function cell of a symbol and


@@ -410,7 +403,8 @@ expansion.
 
 @node Special Forms
 @subsection Special Forms
 
 @node Special Forms
 @subsection Special Forms

-@cindex special form evaluation
+@cindex special forms
+@cindex evaluation of special forms

 
   A @dfn{special form} is a primitive function specially marked so that
 its arguments are not all evaluated.  Most special forms define control
 
   A @dfn{special form} is a primitive function specially marked so that
 its arguments are not all evaluated.  Most special forms define control


@@ -591,6 +585,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.
 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
 
   The functions and variables described in this section evaluate forms,
 specify limits to the evaluation process, or record recently returned


@@ -602,10 +601,13 @@ to store an expression in the data structure and evaluate it.  Using
 functions provides the ability to pass information to them as
 arguments.
 
 functions provides the ability to pass information to them as
 arguments.
 

-@defun eval form
+@defun eval form &optional lexical

 This is the basic function 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}).
 This is the basic function 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}).

+@var{lexical} if non-nil means to evaluate @var{form} using lexical scoping
+rules (@pxref{Lexical Binding}) instead of the default dynamic scoping used
+historically in Emacs Lisp.

 
 Since @code{eval} is a function, the argument expression that appears
 in a call to @code{eval} is evaluated twice: once as preparation before
 
 Since @code{eval} is a function, the argument expression that appears
 in a call to @code{eval} is evaluated twice: once as preparation before


@@ -677,7 +679,7 @@ output of the output functions is printed in the echo area.
 @code{eval-current-buffer} is an alias for this command.
 @end deffn
 
 @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
 @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


@@ -694,14 +696,15 @@ The depth limit counts internal uses of @code{eval}, @code{apply}, and
 expressions, and recursive evaluation of function call arguments and
 function body forms, as well as explicit calls in Lisp code.
 
 expressions, and recursive evaluation of function call arguments and
 function body forms, as well as explicit calls in Lisp code.
 

-The default value of this variable is 300.  If you set it to a value
-less than 100, Lisp will reset it to 100 if the given value is reached.
-Entry to the Lisp debugger increases the value, if there is little room
-left, to make sure the debugger itself has room to execute.
+The default value of this variable is 400.  If you set it to a value
+less than 100, Lisp will reset it to 100 if the given value is
+reached.  Entry to the Lisp debugger increases the value, if there is
+little room left, to make sure the debugger itself has room to
+execute.

 
 @code{max-specpdl-size} provides another limit on nesting.
 @xref{Definition of max-specpdl-size,, Local Variables}.
 
 @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
 
 @defvar values
 The value of this variable is a list of the values returned by all the


@@ -752,7 +755,3 @@ particular elements, like this:
 @end group
 @end example
 @end defvar
 @end group
 @end example
 @end defvar

-
-@ignore
-   arch-tag: f723a4e0-31b3-453f-8afc-0bf8fd276d57
-@end ignore