[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] /srv/bzr/emacs/trunk r106923: Update Variables chapter of
|
From: |
Chong Yidong |
|
Subject: |
[Emacs-diffs] /srv/bzr/emacs/trunk r106923: Update Variables chapter of Lisp manual to handle lexical binding. |
|
Date: |
Wed, 25 Jan 2012 00:08:00 +0800 |
|
User-agent: |
Bazaar (2.3.1) |
------------------------------------------------------------
revno: 106923
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Wed 2012-01-25 00:08:00 +0800
message:
Update Variables chapter of Lisp manual to handle lexical binding.
* doc/lispref/variables.texi (Variables, Local Variables, Void Variables):
Edit to make the descriptions less specific to dynamic binding.
(Local Variables): Default max-specpdl-size is now 1300.
(Defining Variables): Edits for lexical scoping. Delete
information about starting docstrings with *. De-document
user-variable-p.
(Tips for Defining): Remove an unimportant discussion of quitting
in the middle of a load.
(Accessing Variables, Setting Variables): Discuss lexical binding.
(Variable Scoping): Rewrite.
(Scope, Extent, Impl of Scope): Nodes deleted.
(Dynamic Binding): New node, with material from Scope, Extent, and
Impl of Scope nodes.
(Dynamic Binding Tips): Rename from Using Scoping.
(Lexical Binding): Rewrite.
(Using Lexical Binding): Rename from Converting to Lexical
Binding. Convert to subsection.
* doc/lispref/customize.texi (Variable Definitions): Add custom-variable-p.
Move user-variable-p documentation here.
modified:
doc/lispref/ChangeLog
doc/lispref/customize.texi
doc/lispref/elisp.texi
doc/lispref/objects.texi
doc/lispref/variables.texi
=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog 2012-01-23 04:23:50 +0000
+++ b/doc/lispref/ChangeLog 2012-01-24 16:08:00 +0000
@@ -1,3 +1,26 @@
+2012-01-24 Chong Yidong <address@hidden>
+
+ * variables.texi (Variables, Local Variables, Void Variables):
+ Edit to make the descriptions less specific to dynamic binding.
+ (Local Variables): Default max-specpdl-size is now 1300.
+ (Defining Variables): Edits for lexical scoping. Delete
+ information about starting docstrings with *. De-document
+ user-variable-p.
+ (Tips for Defining): Remove an unimportant discussion of quitting
+ in the middle of a load.
+ (Accessing Variables, Setting Variables): Discuss lexical binding.
+ (Variable Scoping): Rewrite.
+ (Scope, Extent, Impl of Scope): Nodes deleted.
+ (Dynamic Binding): New node, with material from Scope, Extent, and
+ Impl of Scope nodes.
+ (Dynamic Binding Tips): Rename from Using Scoping.
+ (Lexical Binding): Rewrite.
+ (Using Lexical Binding): Rename from Converting to Lexical
+ Binding. Convert to subsection.
+
+ * customize.texi (Variable Definitions): Add custom-variable-p.
+ Move user-variable-p documentation here.
+
2012-01-23 Chong Yidong <address@hidden>
* strings.texi (Text Comparison): Minor qualification.
=== modified file 'doc/lispref/customize.texi'
--- a/doc/lispref/customize.texi 2012-01-19 07:21:25 +0000
+++ b/doc/lispref/customize.texi 2012-01-24 16:08:00 +0000
@@ -262,12 +262,6 @@
This macro declares @var{option} as a customizable @dfn{user option}.
You should not quote @var{option}.
-This causes the function @code{user-variable-p} to return @code{t}
-when given @var{option} as an argument. @xref{Defining Variables}.
-The argument @var{doc} specifies the documentation string for the
-variable. (Note that there is no need to start @var{doc} with a
address@hidden)
-
The argument @var{standard} is an expression that specifies the
standard value for @var{option}. Evaluating the @code{defcustom} form
evaluates @var{standard}, but does not necessarily install the
@@ -285,6 +279,9 @@
@var{standard}, because they are not expanded when editing the value,
so list values will appear to have the wrong structure.
+The argument @var{doc} specifies the documentation string for the
+variable.
+
Every @code{defcustom} should specify @code{:group} at least once.
If you specify the @code{:set} keyword, to make the variable take other
@@ -474,6 +471,22 @@
or in the various hooks it calls.
@end defun
address@hidden custom-variable-p arg
+This function returns address@hidden if @var{arg} is a customizable
+variable. A customizable variable is either a variable that has a
address@hidden or @code{custom-autoload} property (usually
+meaning it was declared with @code{defcustom}), or an alias for
+another customizable variable.
address@hidden defun
+
address@hidden user-variable-p arg
+This function is like @code{custom-variable-p}, except it also returns
address@hidden if the first character of the variable's documentation string
+is the character @samp{*}. That is an obsolete way of indicating a
+user option, so for most purposes you may consider
address@hidden as equivalent to @code{custom-variable-p}.
address@hidden defun
+
@node Customization Types
@section Customization Types
=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi 2012-01-23 04:23:50 +0000
+++ b/doc/lispref/elisp.texi 2012-01-24 16:08:00 +0000
@@ -436,12 +436,10 @@
Scoping Rules for Variable Bindings
-* Scope:: Scope means where in the program a value
- is visible. Comparison with other languages.
-* Extent:: Extent means how long in time a value exists.
-* Impl of Scope:: Two ways to implement dynamic scoping.
-* Using Scoping:: How to use dynamic scoping carefully and
- avoid problems.
+* Dynamic Binding:: The default for binding local variables in Emacs.
+* Dynamic Binding Tips:: Avoiding problems with dynamic binding.
+* Lexical Binding:: A different type of local variable binding.
+* Using Lexical Binding:: How to enable lexical binding.
Buffer-Local Variables
=== modified file 'doc/lispref/objects.texi'
--- a/doc/lispref/objects.texi 2012-01-21 16:04:55 +0000
+++ b/doc/lispref/objects.texi 2012-01-24 16:08:00 +0000
@@ -1795,6 +1795,9 @@
@item consp
@xref{List-related Predicates, consp}.
address@hidden custom-variable-p
address@hidden Definitions, custom-variable-p}.
+
@item display-table-p
@xref{Display Tables, display-table-p}.
@@ -1870,9 +1873,6 @@
@item syntax-table-p
@xref{Syntax Tables, syntax-table-p}.
address@hidden user-variable-p
address@hidden Variables, user-variable-p}.
-
@item vectorp
@xref{Vectors, vectorp}.
=== modified file 'doc/lispref/variables.texi'
--- a/doc/lispref/variables.texi 2012-01-21 03:15:07 +0000
+++ b/doc/lispref/variables.texi 2012-01-24 16:08:00 +0000
@@ -8,20 +8,23 @@
@cindex variable
A @dfn{variable} is a name used in a program to stand for a value.
-Nearly all programming languages have variables of some sort. In the
-text of a Lisp program, variables are written using the syntax for
-symbols.
-
- In Lisp, unlike most programming languages, programs are represented
-primarily as Lisp objects and only secondarily as text. The Lisp
-objects used for variables are symbols: the symbol name is the
-variable name, and the variable's value is stored in the value cell of
-the symbol. The use of a symbol as a variable is independent of its
-use as a function name. @xref{Symbol Components}.
-
- The textual form of a Lisp program is given by the read syntax of
-the Lisp objects that constitute the program. Hence, a variable in a
-textual Lisp program is written using the read syntax for the symbol
+In Lisp, each variable is represented by a Lisp symbol
+(@pxref{Symbols}). The symbol's name serves as the variable name, and
+the symbol's value cell holds the variable's address@hidden
+speaking, the symbol's value cell always holds the variable's current
+value under the default @dfn{dynamic binding} rules. Under
address@hidden binding} rules, the value cell holds the variable's
address@hidden value}. @xref{Variable Scoping}, for details.}.
address@hidden 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
+primarily by Lisp objects, and only secondarily as text. The textual
+form of a Lisp program is given by the read syntax of the Lisp objects
+that constitute the program. Hence, the textual form of a variable in
+a Lisp program is written using the read syntax for the symbol
representing the variable.
@menu
@@ -145,63 +148,63 @@
@cindex global binding
Global variables have values that last until explicitly superseded
-with new values. Sometimes it is useful to create variable values that
-exist temporarily---only until a certain part of the program finishes.
-These values are called @dfn{local}, and the variables so used are
-called @dfn{local variables}.
-
- For example, when a function is called, its argument variables receive
-new local values that last until the function exits. The @code{let}
-special form explicitly establishes new local values for specified
-variables; these last until exit from the @code{let} form.
-
address@hidden shadowing of variables
- Establishing a local value saves away the variable's previous value
-(or lack of one). We say that the previous value is @dfn{shadowed}
-and @dfn{not visible}. Both global and local values may be shadowed
-(@pxref{Scope}). After the life span of the local value is over, the
-previous value (or lack of one) is restored.
-
- If you set a variable (such as with @code{setq}) while it is local,
-this replaces the local value; it does not alter the global value, or
-previous local values, that are shadowed. To model this behavior, we
-speak of a @dfn{local binding} of the variable as well as a local value.
-
- The local binding is a conceptual place that holds a local value.
-Entering a function, or a special form such as @code{let}, creates the
-local binding; exiting the function or the @code{let} removes the
-local binding. While the local binding lasts, the variable's value is
-stored within it. Using @code{setq} or @code{set} while there is a
-local binding stores a different value into the local binding; it does
-not create a new binding.
+with new values. Sometimes it is useful to give a variable a
address@hidden value}---a value that takes effect only within a certain
+part of a Lisp program. When a variable has a local value, we say
+that it has a @dfn{local binding}, or that it is a @dfn{local
+variable}.
+
+ For example, when a function is called, its argument variables
+receive local values, which are the actual arguments supplied to the
+function call; these local bindings take effect within the body of the
+function. To take another example, the @code{let} special form
+explicitly establishes local bindings for specific variables, which
+take effect within the body of the @code{let} form.
We also speak of the @dfn{global binding}, which is where
(conceptually) the global value is kept.
address@hidden shadowing of variables
+ Establishing a local binding saves away the variable's previous
+value (or lack of one). We say that the previous value is
address@hidden Both global and local values may be shadowed. If a
+local binding is in effect, using @code{setq} on the local variable
+stores the specified value in the local binding. When that local
+binding is no longer in effect, the previously shadowed value (or lack
+of one) comes back.
+
@cindex current binding
- A variable can have more than one local binding at a time (for
-example, if there are nested @code{let} forms that bind it). In such a
-case, the most recently created local binding that still exists is the
address@hidden binding} of the variable. (This rule is called
address@hidden scoping}; see @ref{Variable Scoping}.) If there are no
-local bindings, the variable's global binding is its current binding.
-We sometimes call the current binding the @dfn{most-local existing
-binding}, for emphasis. Ordinary evaluation of a symbol always returns
-the value of its current binding.
-
- The special forms @code{let} and @code{let*} exist to create
-local bindings.
+ A variable can have more than one local binding at a time (e.g.@: if
+there are nested @code{let} forms that bind the variable). The
address@hidden binding} is the local binding that is actually in effect.
+It determines the value returned by evaluating the variable symbol,
+and it is the binding acted on by @code{setq}.
+
+ For most purposes, you can think of the current binding as the
+``innermost'' local binding, or the global binding if there is no
+local binding. To be more precise, a rule called the @dfn{scoping
+rule} determines where in a program a local binding takes effect. The
+default scoping rule in Emacs Lisp is called @dfn{dynamic scoping},
+which simply states that the current binding at any given point in the
+execution of a program is the most recently-created local binding for
+that variable that still exists. For details about dynamic scoping,
+and an alternative scoping rule called @dfn{lexical scoping},
address@hidden Scoping}.
+
+ The special forms @code{let} and @code{let*} exist to create local
+bindings:
@defspec let (address@hidden) address@hidden
-This special form binds variables according to @var{bindings} and then
-evaluates all of the @var{forms} in textual order. The @code{let}-form
-returns the value of the last form in @var{forms}.
+This special form sets up local bindings for a certain set of
+variables, as specified by @var{bindings}, and then evaluates all of
+the @var{forms} in textual order. Its return value is the value of
+the last form in @var{forms}.
Each of the @var{bindings} is either @w{(i) a} symbol, in which case
-that symbol is bound to @code{nil}; or @w{(ii) a} list of the form
address@hidden(@var{symbol} @var{value-form})}, in which case @var{symbol} is
-bound to the result of evaluating @var{value-form}. If @var{value-form}
-is omitted, @code{nil} is used.
+that symbol is locally bound to @code{nil}; or @w{(ii) a} list of the
+form @code{(@var{symbol} @var{value-form})}, in which case
address@hidden is locally bound to the result of evaluating
address@hidden If @var{value-form} is omitted, @code{nil} is used.
All of the @var{value-form}s in @var{bindings} are evaluated in the
order they appear and @emph{before} binding any of the symbols to them.
@@ -213,6 +216,7 @@
(setq y 2)
@result{} 2
@end group
+
@group
(let ((y 1)
(z y))
@@ -226,15 +230,15 @@
This special form is like @code{let}, but it binds each variable right
after computing its local value, before computing the local value for
the next variable. Therefore, an expression in @var{bindings} can
-reasonably refer to the preceding symbols bound in this @code{let*}
-form. Compare the following example with the example above for
address@hidden
+refer to the preceding symbols bound in this @code{let*} form.
+Compare the following example with the example above for @code{let}.
@example
@group
(setq y 2)
@result{} 2
@end group
+
@group
(let* ((y 1)
(z y)) ; @r{Use the just-established value of @code{y}.}
@@ -262,7 +266,7 @@
Variables}); a few variables have terminal-local bindings
(@pxref{Multiple Terminals}). These kinds of bindings work somewhat
like ordinary local bindings, but they are localized depending on
-``where'' you are in Emacs, rather than localized in time.
+``where'' you are in Emacs.
@defopt max-specpdl-size
@anchor{Definition of max-specpdl-size}
@@ -280,7 +284,7 @@
@code{max-lisp-eval-depth} provides another limit on depth of nesting.
@xref{Definition of max-lisp-eval-depth,, Eval}.
-The default value is 1000. Entry to the Lisp debugger increases the
+The default value is 1300. Entry to the Lisp debugger increases the
value, if there is little room left, to make sure the debugger itself
has room to execute.
@end defopt
@@ -291,45 +295,32 @@
@cindex void variable
If you have never given a symbol any value as a global variable, we
-say that that symbol's global value is @dfn{void}. In other words, the
-symbol's value cell does not have any Lisp object in it. If you try to
-evaluate the symbol, you get a @code{void-variable} error rather than
-a value.
-
- Note that a value of @code{nil} is not the same as void. The symbol
address@hidden is a Lisp object and can be the value of a variable just as any
-other object can be; but it is @emph{a value}. A void variable does not
-have any value.
-
- After you have given a variable a value, you can make it void once more
-using @code{makunbound}.
+say that that symbol's global value is @dfn{void}. Note that this
+does @emph{not} mean the value is @code{nil}. 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.
+
+ More precisely, a variable is void if its symbol has an unassigned
+value cell (@pxref{Symbol Components}). Under Emacs Lisp's default
+dynamic binding rules, the value cell stores the variable's current
+(local or global) value; if a variable is void, trying to evaluate the
+variable signals a @code{void-variable} error rather than a value.
+But when a variable is lexically bound, it can have a local value
+which is determined by the lexical environment, even if the value cell
+is empty and the variable is technically void. @xref{Variable
+Scoping}.
@defun makunbound symbol
-This function makes the current variable binding of @var{symbol} void.
-Subsequent attempts to use this symbol's value as a variable will signal
-the error @code{void-variable}, unless and until you set it again.
-
address@hidden returns @var{symbol}.
-
address@hidden
address@hidden
-(makunbound 'x) ; @r{Make the global value of @code{x} void.}
- @result{} x
address@hidden group
address@hidden
-x
address@hidden Symbol's value as variable is void: x
address@hidden group
address@hidden example
-
-If @var{symbol} is locally bound, @code{makunbound} affects the most
-local existing binding. This is the only way a symbol can have a void
-local binding, since all the constructs that create local bindings
-create them with values. In this case, the voidness lasts at most as
-long as the binding does; when the binding is removed due to exit from
-the construct that made it, the previous local or global binding is
-reexposed as usual, and the variable is no longer void unless the newly
-reexposed binding was void all along.
+This function empties out the value cell of @var{symbol}, making the
+variable void. It returns @var{symbol}.
+
+If @var{symbol} has a (dynamic) local binding, @code{makunbound} voids
+the current binding, and this voidness lasts only as long as the local
+binding is in effect. Afterwards, the previously shadowed local or
+global binding is reexposed; then the variable will no longer be void,
+unless the reexposed binding is void too.
+
+Here are some examples (assuming dynamic binding is in effect):
@smallexample
@group
@@ -361,17 +352,11 @@
@end smallexample
@end defun
- A variable that has been made void with @code{makunbound} is
-indistinguishable from one that has never received a value and has
-always been void.
-
- You can use the function @code{boundp} to test whether a variable is
-currently void.
-
@defun boundp variable
address@hidden returns @code{t} if @var{variable} (a symbol) is not void;
-more precisely, if its current binding is not void. It returns
address@hidden otherwise.
+This function returns @code{t} if @var{variable} (a symbol) is not
+void, and @code{nil} if it is void.
+
+Here are some examples (assuming dynamic binding is in effect):
@smallexample
@group
@@ -402,52 +387,41 @@
@section Defining Global Variables
@cindex variable definition
- You may announce your intention to use a symbol as a global variable
-with a @dfn{variable definition}: a special form, either @code{defconst}
-or @code{defvar}.
-
- In Emacs Lisp, definitions serve three purposes. First, they inform
-people who read the code that certain symbols are @emph{intended} to be
-used a certain way (as variables). Second, they inform the Lisp system
-of these things, supplying a value and documentation. Third, they
-provide information to utilities such as @code{etags} and
address@hidden, which create data bases of the functions and
-variables in a program.
-
- The difference between @code{defconst} and @code{defvar} is primarily
-a matter of intent, serving to inform human readers of whether the value
-should ever change. Emacs Lisp does not restrict the ways in which a
-variable can be used based on @code{defconst} or @code{defvar}
-declarations. However, it does make a difference for initialization:
address@hidden unconditionally initializes the variable, while
address@hidden initializes it only if it is void.
-
address@hidden
- One would expect user option variables to be defined with
address@hidden, since programs do not change them. Unfortunately, this
-has bad results if the definition is in a library that is not preloaded:
address@hidden would override any prior value when the library is
-loaded. Users would like to be able to set user options in their init
-files, and override the default values given in the definitions. For
-this reason, user options must be defined with @code{defvar}.
address@hidden ignore
+ A @dfn{variable definition} is a construct that announces your
+intention to use a symbol as a global variable. It uses the special
+forms @code{defvar} or @code{defconst}, which are documented below.
+
+ A variable definition serves three purposes. First, it informs
+people who read the code that the symbol is @emph{intended} to be used
+a certain way (as a variable). Second, it informs the Lisp system of
+this, optionally supplying an initial value and a documentation
+string. Third, it provides information to programming tools such as
address@hidden, allowing them to find where the variable was defined.
+
+ The difference between @code{defconst} and @code{defvar} is mainly a
+matter of intent, serving to inform human readers of whether the value
+should ever change. Emacs Lisp does not actually prevent you from
+changing the value of a variable defined with @code{defconst}. One
+notable difference between the two forms is that @code{defconst}
+unconditionally initializes the variable, whereas @code{defvar}
+initializes it only if it is originally void.
+
+ To define a customizable variable, you should use @code{defcustom}
+(which calls @code{defvar} as a subroutine). @xref{Customization}.
@defspec defvar symbol [value [doc-string]]
-This special form defines @var{symbol} as a variable and can also
-initialize and document it. The definition informs a person reading
-your code that @var{symbol} is used as a variable that might be set or
-changed. It also declares this variable as @dfn{special}, meaning that it
-should always use dynamic scoping rules. Note that @var{symbol} is not
-evaluated; the symbol to be defined must appear explicitly in the
address@hidden
+This special form defines @var{symbol} as a variable. Note that
address@hidden is not evaluated; the symbol to be defined should appear
+explicitly in the @code{defvar} form. The variable is marked as
address@hidden, meaning that it should always be dynamically bound
+(@pxref{Variable Scoping}).
If @var{symbol} is void and @var{value} is specified, @code{defvar}
-evaluates it and sets @var{symbol} to the result. But if @var{symbol}
-already has a value (i.e., it is not void), @var{value} is not even
-evaluated, and @var{symbol}'s value remains unchanged.
-If @var{value} is omitted, the value of @var{symbol} is not changed in any
-case; instead, the only effect of @code{defvar} is to declare locally that this
-variable exists elsewhere and should hence always use dynamic scoping rules.
+evaluates @var{value} and sets @var{symbol} to the result. But if
address@hidden already has a value (i.e.@: it is not void), @var{value}
+is not even evaluated, and @var{symbol}'s value remains unchanged. If
address@hidden is omitted, the value of @var{symbol} is not changed in
+any case.
If @var{symbol} has a buffer-local binding in the current buffer,
@code{defvar} operates on the default value, which is buffer-independent,
@@ -459,19 +433,9 @@
@code{eval-defun} arranges to set the variable unconditionally, without
testing whether its value is void.
-If the @var{doc-string} argument appears, it specifies the documentation
-for the variable. (This opportunity to specify documentation is one of
-the main benefits of defining the variable.) The documentation is
-stored in the symbol's @code{variable-documentation} property. The
-Emacs help functions (@pxref{Documentation}) look for this property.
-
-If the documentation string begins with the character @samp{*}, Emacs
-allows users to set it interactively using the @code{set-variable}
-command. However, you should nearly always use @code{defcustom}
-instead of @code{defvar} to define such variables, so that users can
-use @kbd{M-x customize} and related commands to set them. In that
-case, it is not necessary to begin the documentation string with
address@hidden @xref{Customization}.
+If the @var{doc-string} argument is supplied, it specifies the
+documentation string for the variable (stored in the symbol's
address@hidden property). @xref{Documentation}.
Here are some examples. This form defines @code{foo} but does not
initialize it:
@@ -494,38 +458,6 @@
@end group
@end example
-The following form changes the documentation string for @code{bar},
-making it a user option, but does not change the value, since @code{bar}
-already has a value. (The addition @code{(1+ nil)} would get an error
-if it were evaluated, but since it is not evaluated, there is no error.)
-
address@hidden
address@hidden
-(defvar bar (1+ nil)
- "*The normal weight of a bar.")
- @result{} bar
address@hidden group
address@hidden
-bar
- @result{} 23
address@hidden group
address@hidden example
-
-Here is an equivalent expression for the @code{defvar} special form:
-
address@hidden
address@hidden
-(defvar @var{symbol} @var{value} @var{doc-string})
address@hidden
-(progn
- (if (not (boundp '@var{symbol}))
- (setq @var{symbol} @var{value}))
- (if '@var{doc-string}
- (put '@var{symbol} 'variable-documentation '@var{doc-string}))
- '@var{symbol})
address@hidden group
address@hidden example
-
The @code{defvar} form returns @var{symbol}, but it is normally used
at top level in a file where its value does not matter.
@end defspec
@@ -538,6 +470,11 @@
or by other programs. Note that @var{symbol} is not evaluated; the
symbol to be defined must appear explicitly in the @code{defconst}.
+The @code{defconst} form, like @code{defvar}, marks the variable as
address@hidden, meaning that it should always be dynamically bound
+(@pxref{Variable Scoping}). In addition, it marks the variable as
+risky (@pxref{File Local Variables}).
+
@code{defconst} always evaluates @var{value}, and sets the value of
@var{symbol} to the result. If @var{symbol} does have a buffer-local
binding in the current buffer, @code{defconst} sets the default value,
@@ -567,37 +504,13 @@
@end example
@end defspec
address@hidden user-variable-p variable
address@hidden user option
-This function returns @code{t} if @var{variable} is a user option---a
-variable intended to be set by the user for customization---and
address@hidden otherwise. (Variables other than user options exist for the
-internal purposes of Lisp programs, and users need not know about them.)
-
-User option variables are distinguished from other variables either
-though being declared using @address@hidden may also be
-declared equivalently in @file{cus-start.el}.} or by the first character
-of their @code{variable-documentation} property. If the property exists
-and is a string, and its first character is @samp{*}, then the variable
-is a user option. Aliases of user options are also user options.
address@hidden defun
-
address@hidden @code{variable-interactive} property
address@hidden set-variable
- If a user option variable has a @code{variable-interactive} property,
-the @code{set-variable} command uses that value to control reading the
-new value for the variable. The property's value is used as if it were
-specified in @code{interactive} (@pxref{Using Interactive}). However,
-this feature is largely obsoleted by @code{defcustom}
-(@pxref{Customization}).
-
- @strong{Warning:} If the @code{defconst} and @code{defvar} special
-forms are used while the variable has a local binding (made with
address@hidden, or a function argument), they set the local-binding's
-value; the top-level binding is not changed. This is not what you
-usually want. To prevent it, use these special forms at top level in
-a file, where normally no local binding is in effect, and make sure to
-load the file before making a local binding for the variable.
+ @strong{Warning:} If you use a @code{defconst} or @code{defvar}
+special form while the variable has a local binding (made with
address@hidden, or a function argument), it sets the local binding rather
+than the global binding. This is not what you usually want. To
+prevent this, use these special forms at top level in a file, where
+normally no local binding is in effect, and make sure to load the file
+before making a local binding for the variable.
@node Tips for Defining
@section Tips for Defining Variables Robustly
@@ -667,9 +580,9 @@
initialized properly, never in-between. If it is still uninitialized,
reloading the file will initialize it properly. Second, reloading the
file once the variable is initialized will not alter it; that is
-important if the user has run hooks to alter part of the contents (such
-as, to rebind keys). Third, evaluating the @code{defvar} form with
address@hidden @emph{will} reinitialize the map completely.
+important if the user has run hooks to alter part of the contents
+(such as, to rebind keys). Third, evaluating the @code{defvar} form
+with @kbd{C-M-x} will reinitialize the map completely.
Putting so much code in the @code{defvar} form has one disadvantage:
it puts the documentation string far away from the line which names the
@@ -690,37 +603,27 @@
the @code{defvar}, except that you must type @kbd{C-M-x} twice, once on
each form, if you do want to reinitialize the variable.
- But be careful not to write the code like this:
-
address@hidden
-(defvar my-mode-map nil
- @var{docstring})
-(unless my-mode-map
- (setq my-mode-map (make-sparse-keymap))
- (define-key my-mode-map "\C-c\C-a" 'my-command)
- @dots{})
address@hidden example
-
address@hidden
-This code sets the variable, then alters it, but it does so in more than
-one step. If the user quits just after the @code{setq}, that leaves the
-variable neither correctly initialized nor void nor @code{nil}. Once
-that happens, reloading the file will not initialize the variable; it
-will remain incomplete.
-
@node Accessing Variables
@section Accessing Variable Values
The usual way to reference a variable is to write the symbol which
-names it (@pxref{Symbol Forms}). This requires you to specify the
-variable name when you write the program. Usually that is exactly what
-you want to do. Occasionally you need to choose at run time which
-variable to reference; then you can use @code{symbol-value}.
+names it. @xref{Symbol Forms}.
+
+ Occasionally, you may want to reference a variable which is only
+determined at run time. In that case, you cannot specify the variable
+name in the text of the program. You can use the @code{symbol-value}
+function to extract the value.
@defun symbol-value symbol
This function returns the value of @var{symbol}. This is the value in
-the innermost local binding of the symbol, or its global value if it
-has no local bindings.
+the symbol's value cell, which is where the variable's current
+(dynamic) value is stored. If the variable has no local binding, this
+is simply its global value.
+
+If the variable is lexically bound, the value reported by
address@hidden is the dynamic value, and not the local lexical
+value (which is determined by the lexical environment rather than the
+symbol's value cell). @xref{Variable Scoping}.
@example
@group
@@ -755,12 +658,12 @@
@end group
@end example
-A @code{void-variable} error is signaled if the current binding of
address@hidden is void.
+A @code{void-variable} error is signaled if @var{symbol} is void as a
+variable.
@end defun
@node Setting Variables
address@hidden How to Alter a Variable Value
address@hidden Setting Variable Values
The usual way to change the value of a variable is with the special
form @code{setq}. When you need to compute the choice of variable at
@@ -769,8 +672,8 @@
@defspec setq [symbol address@hidden
This special form is the most common method of changing a variable's
value. Each @var{symbol} is given a new value, which is the result of
-evaluating the corresponding @var{form}. The most-local existing
-binding of the symbol is changed.
+evaluating the corresponding @var{form}. The current binding of the
+symbol is changed.
@code{setq} does not evaluate @var{symbol}; it sets the symbol that you
write. We say that this argument is @dfn{automatically quoted}. The
@@ -809,12 +712,17 @@
@end defspec
@defun set symbol value
-This function sets @var{symbol}'s value to @var{value}, then returns
address@hidden Since @code{set} is a function, the expression written for
address@hidden is evaluated to obtain the symbol to set.
+This function puts @var{value} in the value cell of @var{symbol}.
+Since it is a function rather than a special form, the expression
+written for @var{symbol} is evaluated to obtain the symbol to set.
+The return value is @var{value}.
-The most-local existing binding of the variable is the binding that is
-set; shadowed bindings are not affected.
+When dynamic variable binding is in effect (the default), @code{set}
+has the same effect as @code{setq}, apart from the fact that
address@hidden evaluates its @var{symbol} argument whereas @code{setq}
+does not. But when a variable is lexically bound, @code{set} affects
+its @emph{dynamic} value, whereas @code{setq} affects its current
+(lexical) value. @xref{Variable Scoping}.
@example
@group
@@ -854,327 +762,337 @@
(set '(x y) 'z)
@error{} Wrong type argument: symbolp, (x y)
@end example
-
-Logically speaking, @code{set} is a more fundamental primitive than
address@hidden Any use of @code{setq} can be trivially rewritten to use
address@hidden; @code{setq} could even be defined as a macro, given the
-availability of @code{set}. However, @code{set} itself is rarely used;
-beginners hardly need to know about it. It is useful only for choosing
-at run time which variable to set. For example, the command
address@hidden, which reads a variable name from the user and then
-sets the variable, needs to use @code{set}.
-
address@hidden CL address@hidden local
address@hidden
address@hidden Lisp note:} In Common Lisp, @code{set} always changes the
-symbol's ``special'' or dynamic value, ignoring any lexical bindings.
-In Emacs Lisp, all variables and all bindings are dynamic, so @code{set}
-always affects the most local existing binding.
address@hidden quotation
@end defun
@node Variable Scoping
@section Scoping Rules for Variable Bindings
- A given symbol @code{foo} can have several local variable bindings,
-established at different places in the Lisp program, as well as a global
-binding. The most recently established binding takes precedence over
-the others.
+ When you create a local binding for a variable, that binding takes
+effect only within a limited portion of the program (@pxref{Local
+Variables}). This section describes exactly what this means.
@cindex scope
@cindex extent
address@hidden dynamic scoping
address@hidden lexical scoping
- By default, local bindings in Emacs Lisp have @dfn{indefinite scope} and
address@hidden extent}. @dfn{Scope} refers to @emph{where} textually in
-the source code the binding can be accessed. ``Indefinite scope'' means
-that any part of the program can potentially access the variable
-binding. @dfn{Extent} refers to @emph{when}, as the program is
-executing, the binding exists. ``Dynamic extent'' means that the binding
-lasts as long as the activation of the construct that established it.
-
- The combination of dynamic extent and indefinite scope is called
address@hidden scoping}. By contrast, most programming languages use
address@hidden scoping}, in which references to a local variable must be
-located textually within the function or block that binds the variable.
-Emacs can also support lexical scoping, upon request (@pxref{Lexical
-Binding}).
-
address@hidden CL note---special variables
address@hidden
address@hidden Lisp note:} Variables declared ``special'' in Common Lisp are
-dynamically scoped, like all variables in Emacs Lisp.
address@hidden quotation
+ Each local binding has a certain @dfn{scope} and @dfn{extent}.
address@hidden refers to @emph{where} in the textual source code the
+binding can be accessed. @dfn{Extent} refers to @emph{when}, as the
+program is executing, the binding exists.
+
address@hidden dynamic binding
address@hidden indefinite scope
address@hidden 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
+while the binding construct (such as the body of a @code{let} form) is
+being executed.
+
address@hidden lexical binding
address@hidden lexical scope
address@hidden 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
address@hidden
+
+ The following subsections describe dynamic binding and lexical
+binding in greater detail, and how to enable lexical binding in Emacs
+Lisp programs.
@menu
-* Scope:: Scope means where in the program a value is
visible.
- Comparison with other languages.
-* Extent:: Extent means how long in time a value exists.
-* Impl of Scope:: Two ways to implement dynamic scoping.
-* Using Scoping:: How to use dynamic scoping carefully and avoid
problems.
-* Lexical Binding:: Use of lexical scoping.
+* Dynamic Binding:: The default for binding local variables in Emacs.
+* Dynamic Binding Tips:: Avoiding problems with dynamic binding.
+* Lexical Binding:: A different type of local variable binding.
+* Using Lexical Binding:: How to enable lexical binding.
@end menu
address@hidden Scope
address@hidden Scope
-
- Emacs Lisp uses @dfn{indefinite scope} for local variable bindings.
-This means that any function anywhere in the program text might access a
-given binding of a variable. Consider the following function
-definitions:
-
address@hidden
address@hidden
-(defun binder (x) ; @address@hidden is bound in @code{binder}.}
- (foo 5)) ; @address@hidden is some other function.}
address@hidden group
-
address@hidden
-(defun user () ; @address@hidden is used ``free'' in @code{user}.}
- (list x))
address@hidden group
address@hidden example
-
- In a lexically scoped language, the binding of @code{x} in
address@hidden would never be accessible in @code{user}, because
address@hidden is not textually contained within the function
address@hidden However, in dynamically-scoped Emacs Lisp, @code{user}
-may or may not refer to the binding of @code{x} established in
address@hidden, depending on the circumstances:
address@hidden Dynamic Binding
address@hidden Dynamic Binding
+
+ By default, the local variable bindings made by Emacs are dynamic
+bindings. When a variable is dynamically bound, its current binding
+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:
+
address@hidden
address@hidden
+(defvar x -99) ; @address@hidden receives an initial value of -99.}
+
+(defun getx ()
+ x) ; @address@hidden is used ``free'' in this function.}
+
+(let ((x 1)) ; @address@hidden is dynamically bound.}
+ (getx))
+ @result{} 1
+
+;; @r{After the @code{let} form finishes, @code{x} reverts to its}
+;; @r{previous value, which is -99.}
+
+(getx)
+ @result{} -99
address@hidden group
address@hidden example
+
address@hidden
+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
address@hidden outside the @code{let} form, it retrieves the global value
+of @code{x} (i.e.@: -99).
+
+ Here is another example, which illustrates setting a dynamically
+bound variable using @code{setq}:
+
address@hidden
address@hidden
+(defvar x -99) ; @address@hidden receives an initial value of -99.}
+
+(defun addx ()
+ (setq x (1+ x))) ; @r{Add 1 to @code{x} and return its new value.}
+
+(let ((x 1))
+ (addx)
+ (addx))
+ @result{} 3 ; @r{The two @code{addx} calls add to @code{x}
twice.}
+
+;; @r{After the @code{let} form finishes, @code{x} reverts to its}
+;; @r{previous value, which is -99.}
+
+(addx)
+ @result{} -98
address@hidden group
address@hidden example
+
+ Dynamic binding is implemented in Emacs Lisp in a simple way. Each
+symbol has a value cell, which specifies its current dynamic value (or
+absence of value). @xref{Symbol Components}. When a symbol is given
+a dynamic local binding, Emacs records the contents of the value cell
+(or absence thereof) in a stack, and stores the new local value in the
+value cell. When the binding construct finishes executing, Emacs pops
+the old value off the stack, and puts it in the value cell.
+
address@hidden Dynamic Binding Tips
address@hidden Proper Use of Dynamic Binding
+
+ Dynamic binding is a powerful feature, as it allows programs to
+refer to variables that are not defined within their local textual
+scope. However, if used without restraint, this can also make
+programs hard to understand. There are two clean ways to use this
+technique:
@itemize @bullet
@item
-If we call @code{user} directly without calling @code{binder} at all,
-then whatever binding of @code{x} is found, it cannot come from
address@hidden
+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.
@item
-If we define @code{foo} as follows and then call @code{binder}, then the
-binding made in @code{binder} will be seen in @code{user}:
+Otherwise, define the variable with @code{defvar}, @code{defconst}, or
address@hidden @xref{Defining Variables}. Usually, the definition
+should be at top-level in an Emacs Lisp file. As far as possible, it
+should include a documentation string which explains the meaning and
+purpose of the variable. You should also choose the variable's name
+to avoid name conflicts (@pxref{Coding Conventions}).
+
+Then you can bind the variable anywhere in a program, knowing reliably
+what the effect will be. Wherever you encounter the variable, it will
+be easy to refer back to the definition, e.g.@: via the @kbd{C-h v}
+command (provided the variable definition has been loaded into Emacs).
address@hidden Help,,, emacs, The GNU Emacs Manual}.
+
+For example, it is common to use local bindings for customizable
+variables like @code{case-fold-search}:
@example
@group
-(defun foo (lose)
- (user))
+(defun search-for-abc ()
+ "Search for the string \"abc\", ignoring case differences."
+ (let ((case-fold-search nil))
+ (re-search-forward "abc")))
@end group
@end example
-
address@hidden
-However, if we define @code{foo} as follows and then call @code{binder},
-then the binding made in @code{binder} @emph{will not} be seen in
address@hidden:
-
address@hidden
-(defun foo (x)
- (user))
address@hidden example
-
address@hidden
-Here, when @code{foo} is called by @code{binder}, it binds @code{x}.
-(The binding in @code{foo} is said to @dfn{shadow} the one made in
address@hidden) Therefore, @code{user} will access the @code{x} bound
-by @code{foo} instead of the one bound by @code{binder}.
@end itemize
-Emacs Lisp used dynamic scoping by default because simple implementations of
-lexical scoping are slow. In addition, every Lisp system needs to offer
-dynamic scoping at least as an option; if lexical scoping is the norm, there
-must be a way to specify dynamic scoping instead for a particular variable.
-Nowadays, Emacs offers both, but the default is still to use exclusively
-dynamic scoping.
-
address@hidden Extent
address@hidden Extent
-
- @dfn{Extent} refers to the time during program execution that a
-variable name is valid. In Emacs Lisp, a variable is valid only while
-the form that bound it is executing. This is called @dfn{dynamic
-extent}. ``Local'' or ``automatic'' variables in most languages,
-including C and Pascal, have dynamic extent.
-
- One alternative to dynamic extent is @dfn{indefinite extent}. This
-means that a variable binding can live on past the exit from the form
-that made the binding. Common Lisp and Scheme, for example, support
-this, but Emacs Lisp does not.
-
- To illustrate this, the function below, @code{make-add}, returns a
-function that purports to add @var{n} to its own argument @var{m}. This
-would work in Common Lisp, but it does not do the job in Emacs Lisp,
-because after the call to @code{make-add} exits, the variable @code{n}
-is no longer bound to the actual argument 2.
-
address@hidden
-(defun make-add (n)
- (function (lambda (m) (+ n m)))) ; @r{Return a function.}
- @result{} make-add
-(fset 'add2 (make-add 2)) ; @r{Define function @code{add2}}
- ; @r{with @code{(make-add 2)}.}
- @result{} (lambda (m) (+ n m))
-(add2 4) ; @r{Try to add 2 to 4.}
address@hidden Symbol's value as variable is void: n
address@hidden example
-
address@hidden closures not available
- Some Lisp dialects have ``closures,'' objects that are like functions
-but record additional variable bindings. Emacs Lisp does not have
-closures.
-
address@hidden Impl of Scope
address@hidden Implementation of Dynamic Scoping
address@hidden deep binding
-
- A simple sample implementation (which is not how Emacs Lisp actually
-works) may help you understand dynamic binding. This technique is
-called @dfn{deep binding} and was used in early Lisp systems.
-
- Suppose there is a stack of bindings, which are variable-value pairs.
-At entry to a function or to a @code{let} form, we can push bindings
-onto the stack for the arguments or local variables created there. We
-can pop those bindings from the stack at exit from the binding
address@hidden Lexical Binding
address@hidden 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.
- We can find the value of a variable by searching the stack from top to
-bottom for a binding for that variable; the value from that binding is
-the value of the variable. To set the variable, we search for the
-current binding, then store the new value into that binding.
-
- As you can see, a function's bindings remain in effect as long as it
-continues execution, even during its calls to other functions. That is
-why we say the extent of the binding is dynamic. And any other function
-can refer to the bindings, if it uses the same variables while the
-bindings are in effect. That is why we say the scope is indefinite.
-
address@hidden shallow binding
- The actual implementation of variable scoping in GNU Emacs Lisp uses a
-technique called @dfn{shallow binding}. Each variable has a standard
-place in which its current value is always found---the value cell of the
-symbol.
-
- In shallow binding, setting the variable works by storing a value in
-the value cell. Creating a new binding works by pushing the old value
-(belonging to a previous binding) onto a stack, and storing the new
-local value in the value cell. Eliminating a binding works by popping
-the old value off the stack, into the value cell.
-
- We use shallow binding because it has the same results as deep
-binding, but runs faster, since there is never a need to search for a
-binding.
-
address@hidden Using Scoping
address@hidden Proper Use of Dynamic Scoping
-
- Binding a variable in one function and using it in another is a
-powerful technique, but if used without restraint, it can make programs
-hard to understand. There are two clean ways to use this technique:
-
address@hidden @bullet
address@hidden
-Use or bind the variable only in a few related functions, written close
-together in one file. Such a variable is used for communication within
-one program.
-
-You should write comments to inform other programmers that they can see
-all uses of the variable before them, and to advise them not to add uses
-elsewhere.
-
address@hidden
-Give the variable a well-defined, documented meaning, and make all
-appropriate functions refer to it (but not bind it or set it) wherever
-that meaning is relevant. For example, the variable
address@hidden is defined as address@hidden means ignore case
-when searching''; various search and replace functions refer to it
-directly or through their subroutines, but do not bind or set it.
-
-Then you can bind the variable in other programs, knowing reliably what
-the effect will be.
address@hidden itemize
-
- In either case, you should define the variable with @code{defvar}.
-This helps other people understand your program by telling them to look
-for inter-function usage. It also avoids a warning from the byte
-compiler. Choose the variable's name to avoid name conflicts---don't
-use short names like @code{x}.
-
-
address@hidden Lexical Binding
address@hidden Use of Lexical Scoping
-
-Emacs Lisp can be evaluated in two different modes: in dynamic binding
-mode or lexical binding mode. In dynamic binding mode, all local
-variables use dynamic scoping, whereas in lexical binding mode
-variables that have been declared @dfn{special} (i.e., declared with
address@hidden, @code{defcustom} or @code{defconst}) use dynamic
-scoping and all others use lexical scoping.
+ Here is an example
address@hidden
+(see the next subsection, for how to actually enable lexical binding):
address@hidden iftex
address@hidden
+(@pxref{Using Lexical Binding}, for how to actually enable lexical binding):
address@hidden ifnottex
+
address@hidden
address@hidden
+(defun getx ()
+ x) ; @address@hidden is used ``free'' in this function.}
+
+(let ((x 1)) ; @address@hidden is lexically bound.}
+ (+ x 3))
+ @result{} 4
+
+(let ((x 1)) ; @address@hidden is lexically bound.}
+ (getx))
address@hidden Symbol's value as variable is void: x
address@hidden group
address@hidden example
+
address@hidden
+Here, the variable @code{x} has no global value. When it is lexically
+bound within a @code{let} form, it can be used in the textual confines
+of that @code{let} form. But it can @emph{not} be used from within a
address@hidden function called from the @code{let} form, since the
+function definition of @code{getx} occurs outside the @code{let} form
+itself.
+
address@hidden lexical environment
+ Here is how lexical binding works. Each binding construct defines a
address@hidden environment}, specifying the symbols that are bound
+within the construct and their local values. When the Lisp evaluator
+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 dynamical value is stored.
+
address@hidden closures
+ Lexical bindings have indefinite extent. Even after a binding
+construct has finished executing, its lexical environment can be
+``kept around'' in Lisp objects called @dfn{closures}. A closure is
+created whenever you evaluate a lambda expression (@pxref{Lambda
+Expressions}) with lexical binding enabled. It is represented by a
+list whose @sc{car} is the symbol @code{closure}. It is a function,
+in the sense that it can be passed as an argument to @code{funcall};
+when called as a function, any lexical variable references within its
+definition will use the retained lexical environment.
+
+ Here is an example which illustrates the use of a closure:
+
address@hidden
+(defvar my-ticker nil) ; @r{We will use this dynamically bound}
+ ; @r{variable to store a closure.}
+
+(let ((x 0)) ; @address@hidden is lexically bound.}
+ (setq my-ticker (lambda ()
+ (setq x (1+ x)))))
+ @result{} (closure ((x . 0) t) ()
+ (1+ x))
+
+(funcall my-ticker)
+ @result{} 1
+
+(funcall my-ticker)
+ @result{} 2
+
+(funcall my-ticker)
+ @result{} 3
+
+x ; @r{Note that @code{x} has no global value.}
address@hidden Symbol's value as variable is void: x
address@hidden example
+
address@hidden
+The @code{let} binding defines a lexical environment in which the
+variable @code{x} is locally bound to 0. Within this binding
+construct, we define a lambda expression which increments @code{x} by
+one and returns the incremented value. This lambda expression is
+automatically turned into a closure, in which the lexical environment
+lives on even after the @code{let} binding construct has exited. Each
+time we evaluate the closure, it increments @code{x}, using the
+binding of @code{x} in that lexical environment.
+
+ Note that functions like @code{symbol-value}, @code{boundp}, and
address@hidden only retrieve or modify a variable's dynamic binding
+(i.e.@: the contents of its symbol's value cell). Also, the code in
+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.
+
address@hidden Using Lexical Binding
address@hidden Using Lexical Binding
+
+ When loading an Emacs Lisp file or evaluating a Lisp buffer, lexical
+binding is enabled if the buffer-local variable @code{lexical-binding}
+is address@hidden:
@defvar lexical-binding
-When non-nil, evaluation of Lisp code uses lexical scoping for non-special
-local variables instead of dynamic scoping. If nil, dynamic scoping is used
-for all local variables. This variable is typically set for a whole Elisp file
-via file local variables (@pxref{File Local Variables}).
+If this buffer-local variable is address@hidden, Emacs Lisp files and
+buffers are evaluated using lexical binding instead of dynamic
+binding. (However, special variables are still dynamically bound; see
+below.) If @code{nil}, dynamic binding is used for all local
+variables. This variable is typically set for a whole Emacs Lisp
+file, as a file local variable (@pxref{File Local Variables}).
@end defvar
address@hidden
+When evaluating Emacs Lisp code directly using an @code{eval} call,
+lexical binding is enabled if the @var{lexical} argument to
address@hidden is address@hidden @xref{Eval}.
+
address@hidden special variables
+ Even when lexical binding is enabled, certain variables will
+continue to be dynamically bound. These are called @dfn{special
+variables}. Every variable that has been defined with @code{defvar},
address@hidden or @code{defconst} is a special variable
+(@pxref{Defining Variables}). All other variables are subject to
+lexical binding.
+
@defun special-variable-p SYMBOL
-Return whether SYMBOL has been declared as a special variable, via
address@hidden or @code{defconst}.
+This function returns address@hidden if @var{symbol} is a special
+variable (i.e.@: it has a @code{defvar}, @code{defcustom}, or
address@hidden variable definition). Otherwise, the return value is
address@hidden
@end defun
-The use of a special variable as a formal argument in a function is generally
-discouraged and its behavior in lexical binding mode is unspecified (it may use
-lexical scoping sometimes and dynamic scoping other times).
-
-Functions like @code{symbol-value}, @code{boundp}, or @code{set} only know
-about dynamically scoped variables, so you cannot get the value of a lexical
-variable via @code{symbol-value} and neither can you change it via @code{set}.
-Another particularity is that code in the body of a @code{defun} or
address@hidden cannot refer to surrounding lexical variables.
-
-Evaluation of a @code{lambda} expression in lexical binding mode will not just
-return that lambda expression unchanged, as in the dynamic binding case, but
-will instead construct a new object that remembers the current lexical
-environment in which that lambda expression was defined, so that the function
-body can later be evaluated in the proper context. Those objects are called
address@hidden They are also functions, in the sense that they are accepted
-by @code{funcall}, and they are represented by a cons cell whose @code{car} is
-the symbol @code{closure}.
-
address@hidden
-* Converting to Lexical Binding:: How to start using lexical scoping
address@hidden menu
-
address@hidden Converting to Lexical Binding
address@hidden Converting a package to use lexical scoping
-
-Lexical scoping, as currently implemented, does not bring many significant
-benefits, unless you are a seasoned functional programmer addicted to
-higher-order functions. But its importance will increase in the future:
-lexical scoping opens up a lot more opportunities for optimization, so
-lexically scoped code is likely to run faster in future Emacs versions, and it
-is much more friendly to concurrency, which we want to add in the near future.
-
-Converting a package to lexical binding is usually pretty easy and should not
-break backward compatibility: just add a file-local variable setting
address@hidden to @code{t} and add declarations of the form
address@hidden(defvar @var{VAR})} for every variable which still needs to use
-dynamic scoping.
-
-To find which variables need this declaration, the simplest solution is to
-check the byte-compiler's warnings. The byte-compiler will usually find those
-variables either because they are used outside of a let-binding (leading to
-warnings about reference or assignment to ``free variable @var{VAR}'') or
-because they are let-bound but not used within the let-binding (leading to
-warnings about ``unused lexical variable @var{VAR}'').
-
-In cases where a dynamically scoped variable was bound as a function argument,
-you will also need to move this binding to a @code{let}. These cases are also
-flagged by the byte-compiler.
-
-To silence byte-compiler warnings about unused variables, just use a variable
-name that start with an underscore, which the byte-compiler interpret as an
-indication that this is a variable known not to be used.
-
-In most cases, the resulting code will then work with either setting of
address@hidden, so it can still be used with older Emacsen (which will
-simply ignore the @code{lexical-binding} variable setting).
+ The use of a special variable as a formal argument in a function is
+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
address@hidden 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.
+
+ 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
+byte-compiler will warn about reference or assignment to a ``free
+variable''. If a non-special variable is bound but not used within a
address@hidden form, the byte-compiler will warn about an ``unused lexical
+variable''. The byte-compiler will also issue a warning if you use a
+special variable as a function argument.
+
+ (To silence byte-compiler warnings about unused variables, just use
+a variable name that start with an underscore. The byte-compiler
+interprets this as an indication that this is a variable known not to
+be used.)
@node Buffer-Local Variables
@section Buffer-Local Variables
- [Emacs-diffs] /srv/bzr/emacs/trunk r106923: Update Variables chapter of Lisp manual to handle lexical binding.,
Chong Yidong <=