Commit 10b1f2fd authored by Noam Postavsky's avatar Noam Postavsky

Explain more about (defvar foo) form (Bug#18059)

* doc/lispref/variables.texi (Defining Variables)
(Using Lexical Binding):
* doc/lispref/compile.texi (Compiler Errors): Emphasize that omitting
VALUE for `defvar' marks the variable special only locally.
* doc/lispref/variables.texi (Using Lexical Binding): Add example of
using `defvar' without VALUE.
parent 68c2f336
......@@ -500,7 +500,8 @@ You can tell the compiler that a function is defined using
@item
Likewise, you can tell the compiler that a variable is defined using
@code{defvar} with no initial value. (Note that this marks the
variable as special, i.e.@: dynamically bound.) @xref{Defining
variable as special, i.e.@: dynamically bound, but only within the
current lexical scope, or file if at top-level.) @xref{Defining
Variables}.
@end itemize
......
......@@ -443,9 +443,13 @@ dynamically bound value; @pxref{Void Variables}), then @var{value} is
evaluated and @var{symbol} is set to the result. But if @var{symbol}
is not void, @var{value} is not evaluated, and @var{symbol}'s value is
left unchanged. If @var{value} is omitted, the value of @var{symbol}
is not changed in any case. Using @code{defvar} with no value is one
method of suppressing byte compilation warnings, see @ref{Compiler
Errors}.
is not changed in any case.
Note that specifying a value, even @code{nil}, marks the variable as
special permanently. Whereas if @var{value} is omitted then the
variable is only marked special locally (i.e.@: within the current
lexical scope, or file if at the top-level). This can be useful for
suppressing byte compilation warnings, see @ref{Compiler Errors}.
If @var{symbol} has a buffer-local binding in the current buffer,
@code{defvar} acts on the default value, which is buffer-independent,
......@@ -489,6 +493,9 @@ it a documentation string:
The @code{defvar} form returns @var{symbol}, but it is normally used
at top level in a file where its value does not matter.
For a more elaborate example of using @code{defvar} without a value,
see @ref{Local defvar example}.
@end defspec
@cindex constant variables
......@@ -1165,6 +1172,32 @@ variables}. Every variable that has been defined with @code{defvar},
(@pxref{Defining Variables}). All other variables are subject to
lexical binding.
@anchor{Local defvar example}
Using @code{defvar} without a value, it is possible to bind a variable
dynamically just in one file, or in just one part of a file while
still binding it lexically elsewhere. For example:
@example
@group
(let (_)
(defvar x) ; @r{Let-bindings of @code{x} will be dynamic within this let.}
(let ((x -99)) ; @r{This is a dynamic binding of @code{x}.}
(defun get-dynamic-x ()
x)))
(let ((x 'lexical)) ; @r{This is a lexical binding of @code{x}.}
(defun get-lexical-x ()
x))
(let (_)
(defvar x)
(let ((x 'dynamic))
(list (get-lexical-x)
(get-dynamic-x))))
@result{} (lexical dynamic)
@end group
@end example
@defun special-variable-p symbol
This function returns non-@code{nil} if @var{symbol} is a special
variable (i.e., it has a @code{defvar}, @code{defcustom}, or
......
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