Commit 362397ed authored by Chong Yidong's avatar Chong Yidong
Browse files

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.
parent 3a79600a
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
......
......@@ -715,12 +715,18 @@ arguments.
@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
......
......@@ -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
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
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
......@@ -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
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
......@@ -761,6 +763,7 @@ error is signaled.
@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
......@@ -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
@cindex indefinite scope
@cindex dynamic scope
@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.
......@@ -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
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
......@@ -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.
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
......@@ -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
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}:
......@@ -888,12 +892,11 @@ technique:
@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
......@@ -925,12 +928,16 @@ variables like @code{case-fold-search}:
@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
......@@ -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.
(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
......@@ -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.
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
......@@ -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).
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
......
......@@ -916,6 +916,7 @@ something (not just adding elements to it).
* Lisp Changes in Emacs 24.4
+++
** The second argument of `eval' can now specify a lexical environment.
+++
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment