Document `eval' changes.

* doc/lispref/eval.texi (Eval): Document the LEXICAL arg to eval.

* doc/lispref/variables.texi (Variables, Void Variables): Use "scoping rule"
terminology consistently.
(Variable Scoping): Add index entries, and use "dynamic scope"
terminology in place of "indefinite scope" to reduce confusion.
(Lexical Binding): Document lexical environment format.
(Using Lexical Binding): Add index entries for error messages.

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index b1c2108..595102b 100644 (file)
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,14 @@
+2013-12-25  Chong Yidong  <cyd@gnu.org>
+
+       * eval.texi (Eval): Document the LEXICAL arg to eval.
+
+       * variables.texi (Variables, Void Variables): Use "scoping rule"
+       terminology consistently.
+       (Variable Scoping): Add index entries, and use "dynamic scope"
+       terminology in place of "indefinite scope" to reduce confusion.
+       (Lexical Binding): Document lexical environment format.
+       (Using Lexical Binding): Add index entries for error messages.
+

 2013-12-24  Tassilo Horn  <tsdh@gnu.org>
 
        * control.texi (Pattern matching case statement): Fix missing
 2013-12-24  Tassilo Horn  <tsdh@gnu.org>
 
        * control.texi (Pattern matching case statement): Fix missing

diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi
index df30b90..4a63ec2 100644 (file)
--- a/doc/lispref/eval.texi
+++ b/doc/lispref/eval.texi
@@ -715,12 +715,18 @@ arguments.
 
 @defun eval form &optional lexical
 This is the basic function for 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}.
+@var{form} in the current environment, and returns the result.  The
+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.
+The value of @var{lexical} can also be a non-empty alist specifying a
+particular @dfn{lexical environment} for lexical bindings; however,
+this feature is only useful for specialized purposes, such as in Emacs
+Lisp debuggers.  @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
 
 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/doc/lispref/variables.texi b/doc/lispref/variables.texi
index 941b2d8..5d1a476 100644 (file)
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -10,10 +10,10 @@
 In Lisp, each variable is represented by a Lisp symbol
 (@pxref{Symbols}).  The variable name is simply the symbol's name, and
 the variable's value is stored in the symbol's value cell@footnote{To
 In Lisp, each variable is represented by a Lisp symbol
 (@pxref{Symbols}).  The variable name is simply the symbol's name, and
 the variable's value is stored in the symbol's value cell@footnote{To

-be precise, under the default @dfn{dynamic binding} rules the value
+be precise, under the default @dfn{dynamic scoping} rule, the value

 cell always holds the variable's current value, but this is not the
 cell always holds the variable's current value, but this is not the

-case under @dfn{lexical binding} rules.  @xref{Variable Scoping}, for
-details.}.  @xref{Symbol Components}.  In Emacs Lisp, the use of a
+case under the @dfn{lexical scoping} rule.  @xref{Variable Scoping},
+for details.}.  @xref{Symbol Components}.  In Emacs Lisp, the use of a

 symbol as a variable is independent of its use as a function name.
 
   As previously noted in this manual, a Lisp program is represented
 symbol as a variable is independent of its use as a function name.
 
   As previously noted in this manual, a Lisp program is represented


@@ -292,20 +292,22 @@ has room to execute.
 @cindex void variable
 
   We say that a variable is void if its symbol has an unassigned value
 @cindex void variable
 
   We say that a variable is void if its symbol has an unassigned value

-cell (@pxref{Symbol Components}).  Under Emacs Lisp's default dynamic
-binding rules (@pxref{Variable Scoping}), the value cell stores the
-variable's current (local or global) value.  Note that an unassigned
-value cell is @emph{not} the same as having @code{nil} in the value
-cell.  The symbol @code{nil} is a Lisp object and can be the value of
-a variable, just as any other object can be; but it is still a value.
-If a variable is void, trying to evaluate the variable signals a
-@code{void-variable} error rather than a value.
-
-  Under lexical binding rules, the value cell only holds the
-variable's global value, i.e., the value outside of any lexical
-binding construct.  When a variable is lexically bound, the local value
-is determined by the lexical environment; the variable may have a
-local value if its symbol's value cell is unassigned.
+cell (@pxref{Symbol Components}).
+
+  Under Emacs Lisp's default dynamic scoping rule (@pxref{Variable
+Scoping}), the value cell stores the variable's current (local or
+global) value.  Note that an unassigned value cell is @emph{not} the
+same as having @code{nil} in the value cell.  The symbol @code{nil} is
+a Lisp object and can be the value of a variable, just as any other
+object can be; but it is still a value.  If a variable is void, trying
+to evaluate the variable signals a @code{void-variable} error, instead
+of returning a value.
+
+  Under the optional lexical scoping rule, the value cell only holds
+the variable's global value---the value outside of any lexical binding
+construct.  When a variable is lexically bound, the local value is
+determined by the lexical environment; hence, variables can have local
+values even if their symbols' value cells are unassigned.

 
 @defun makunbound symbol
 This function empties out the value cell of @var{symbol}, making the
 
 @defun makunbound symbol
 This function empties out the value cell of @var{symbol}, making the


@@ -761,6 +763,7 @@ error is signaled.
 
 @node Variable Scoping
 @section Scoping Rules for Variable Bindings
 
 @node Variable Scoping
 @section Scoping Rules for Variable Bindings

+@cindex scoping rule

 
   When you create a local binding for a variable, that binding takes
 effect only within a limited portion of the program (@pxref{Local
 
   When you create a local binding for a variable, that binding takes
 effect only within a limited portion of the program (@pxref{Local


@@ -774,12 +777,12 @@ binding can be accessed.  @dfn{Extent} refers to @emph{when}, as the
 program is executing, the binding exists.
 
 @cindex dynamic binding
 program is executing, the binding exists.
 
 @cindex dynamic binding

-@cindex indefinite scope
+@cindex dynamic scope

 @cindex dynamic extent
   By default, the local bindings that Emacs creates are @dfn{dynamic
 @cindex dynamic extent
   By default, the local bindings that Emacs creates are @dfn{dynamic

-bindings}.  Such a binding has @dfn{indefinite scope}, meaning that
-any part of the program can potentially access the variable binding.
-It also has @dfn{dynamic extent}, meaning that the binding lasts only
+bindings}.  Such a binding has @dfn{dynamic scope}, meaning that any
+part of the program can potentially access the variable binding.  It
+also has @dfn{dynamic extent}, meaning that the binding lasts only

 while the binding construct (such as the body of a @code{let} form) is
 being executed.
 
 while the binding construct (such as the body of a @code{let} form) is
 being executed.
 


@@ -788,11 +791,12 @@ being executed.
 @cindex indefinite extent
   Emacs can optionally create @dfn{lexical bindings}.  A lexical
 binding has @dfn{lexical scope}, meaning that any reference to the
 @cindex indefinite extent
   Emacs can optionally create @dfn{lexical bindings}.  A lexical
 binding has @dfn{lexical scope}, meaning that any reference to the

-variable must be located textually within the binding construct.  It
-also has @dfn{indefinite extent}, meaning that under some
-circumstances the binding can live on even after the binding construct
-has finished executing, by means of special objects called
-@dfn{closures}.
+variable must be located textually within the binding
+construct@footnote{With some exceptions; for instance, a lexical
+binding can also be accessed from the Lisp debugger.}.  It also has
+@dfn{indefinite extent}, meaning that under some circumstances the
+binding can live on even after the binding construct has finished
+executing, by means of special objects called @dfn{closures}.

 
   The following subsections describe dynamic binding and lexical
 binding in greater detail, and how to enable lexical binding in Emacs
 
   The following subsections describe dynamic binding and lexical
 binding in greater detail, and how to enable lexical binding in Emacs


@@ -814,8 +818,8 @@ at any point in the execution of the Lisp program is simply the most
 recently-created dynamic local binding for that symbol, or the global
 binding if there is no such local binding.
 
 recently-created dynamic local binding for that symbol, or the global
 binding if there is no such local binding.
 

-  Dynamic bindings have indefinite scope and dynamic extent, as shown
-by the following example:
+  Dynamic bindings have dynamic scope and extent, as shown by the
+following example:

 
 @example
 @group
 
 @example
 @group


@@ -841,9 +845,9 @@ The function @code{getx} refers to @code{x}.  This is a ``free''
 reference, in the sense that there is no binding for @code{x} within
 that @code{defun} construct itself.  When we call @code{getx} from
 within a @code{let} form in which @code{x} is (dynamically) bound, it
 reference, in the sense that there is no binding for @code{x} within
 that @code{defun} construct itself.  When we call @code{getx} from
 within a @code{let} form in which @code{x} is (dynamically) bound, it

-retrieves the local value of @code{x} (i.e., 1).  But when we call
-@code{getx} outside the @code{let} form, it retrieves the global value
-of @code{x} (i.e., -99).
+retrieves the local value (i.e., 1).  But when we call @code{getx}
+outside the @code{let} form, it retrieves the global value (i.e.,
+-99).

 
   Here is another example, which illustrates setting a dynamically
 bound variable using @code{setq}:
 
   Here is another example, which illustrates setting a dynamically
 bound variable using @code{setq}:


@@ -888,12 +892,11 @@ technique:
 @itemize @bullet
 @item
 If a variable has no global definition, use it as a local variable
 @itemize @bullet
 @item
 If a variable has no global definition, use it as a local variable

-only within a binding construct, e.g., the body of the @code{let}
-form where the variable was bound, or the body of the function for an
-argument variable.  If this convention is followed consistently
-throughout a program, the value of the variable will not affect, nor
-be affected by, any uses of the same variable symbol elsewhere in the
-program.
+only within a binding construct, such as the body of the @code{let}
+form where the variable was bound.  If this convention is followed
+consistently throughout a program, the value of the variable will not
+affect, nor be affected by, any uses of the same variable symbol
+elsewhere in the program.

 
 @item
 Otherwise, define the variable with @code{defvar}, @code{defconst}, or
 
 @item
 Otherwise, define the variable with @code{defvar}, @code{defconst}, or


@@ -925,12 +928,16 @@ variables like @code{case-fold-search}:
 @node Lexical Binding
 @subsection Lexical Binding
 
 @node Lexical Binding
 @subsection Lexical Binding
 

-Optionally, you can create lexical bindings in Emacs Lisp.  A
-lexically bound variable has @dfn{lexical scope}, meaning that any
-reference to the variable must be located textually within the binding
-construct.
+  Lexical binding was introduced to Emacs, as an optional feature, in
+version 24.1.  We expect its importance to increase in the future.
+Lexical binding opens up many more opportunities for optimization, so
+programs using it are likely to run faster in future Emacs versions.
+Lexical binding is also more compatible with concurrency, which we
+want to add to Emacs in the future.

 
 

-  Here is an example
+  A lexically-bound variable has @dfn{lexical scope}, meaning that any
+reference to the variable must be located textually within the binding
+construct.  Here is an example

 @iftex
 (see the next subsection, for how to actually enable lexical binding):
 @end iftex
 @iftex
 (see the next subsection, for how to actually enable lexical binding):
 @end iftex


@@ -969,6 +976,14 @@ wants the current value of a variable, it looks first in the lexical
 environment; if the variable is not specified in there, it looks in
 the symbol's value cell, where the dynamic value is stored.
 
 environment; if the variable is not specified in there, it looks in
 the symbol's value cell, where the dynamic value is stored.
 

+  (Internally, the lexical environment is an alist of symbol-value
+pairs, with the final element in the alist being the symbol @code{t}
+rather than a cons cell.  Such an alist can be passed as the second
+argument to the @code{eval} function, in order to specify a lexical
+environment in which to evaluate a form.  @xref{Eval}.  Most Emacs
+Lisp programs, however, should not interact directly with lexical
+environments in this way; only specialized programs like debuggers.)
+

 @cindex closures, example of using
   Lexical bindings have indefinite extent.  Even after a binding
 construct has finished executing, its lexical environment can be
 @cindex closures, example of using
   Lexical bindings have indefinite extent.  Even after a binding
 construct has finished executing, its lexical environment can be


@@ -1019,13 +1034,6 @@ binding of @code{x} in that lexical environment.
 the body of a @code{defun} or @code{defmacro} cannot refer to
 surrounding lexical variables.
 
 the body of a @code{defun} or @code{defmacro} cannot refer to
 surrounding lexical variables.
 

-  Currently, lexical binding is not much used within the Emacs
-sources.  However, we expect its importance to increase in the future.
-Lexical binding opens up a lot more opportunities for optimization, so
-Emacs Lisp code that makes use of lexical binding is likely to run
-faster in future Emacs versions.  Such code is also much more friendly
-to concurrency, which we want to add to Emacs in the near future.
-

 @node Using Lexical Binding
 @subsection Using Lexical Binding
 
 @node Using Lexical Binding
 @subsection Using Lexical Binding
 


@@ -1069,12 +1077,15 @@ discouraged.  Doing so gives rise to unspecified behavior when lexical
 binding mode is enabled (it may use lexical binding sometimes, and
 dynamic binding other times).
 
 binding mode is enabled (it may use lexical binding sometimes, and
 dynamic binding other times).
 

-  Converting an Emacs Lisp program to lexical binding is pretty easy.
-First, add a file-local variable setting of @code{lexical-binding} to
-@code{t} in the Emacs Lisp source file.  Second, check that every
-variable in the program which needs to be dynamically bound has a
-variable definition, so that it is not inadvertently bound lexically.
+  Converting an Emacs Lisp program to lexical binding is easy.  First,
+add a file-local variable setting of @code{lexical-binding} to
+@code{t} in the header line of the Emacs Lisp source file (@pxref{File
+Local Variables}).  Second, check that every variable in the program
+which needs to be dynamically bound has a variable definition, so that
+it is not inadvertently bound lexically.

 
 

+@cindex free variable
+@cindex unused lexical variable

   A simple way to find out which variables need a variable definition
 is to byte-compile the source file.  @xref{Byte Compilation}.  If a
 non-special variable is used outside of a @code{let} form, the
   A simple way to find out which variables need a variable definition
 is to byte-compile the source file.  @xref{Byte Compilation}.  If a
 non-special variable is used outside of a @code{let} form, the

diff --git a/etc/NEWS b/etc/NEWS
index 2e6da37..00a72f0 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -916,6 +916,7 @@ something (not just adding elements to it).
 \f
 * Lisp Changes in Emacs 24.4
 
 \f
 * Lisp Changes in Emacs 24.4
 

++++

 ** The second argument of `eval' can now specify a lexical environment.
 
 +++
 ** The second argument of `eval' can now specify a lexical environment.
 
 +++