[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] feature/gnus-select 1a1bb0c 185/218: Explain more about (d
From: |
Andrew G Cohen |
Subject: |
[Emacs-diffs] feature/gnus-select 1a1bb0c 185/218: Explain more about (defvar foo) form (Bug#18059) |
Date: |
Fri, 14 Dec 2018 03:35:39 -0500 (EST) |
branch: feature/gnus-select
commit 1a1bb0c3374daa757fbc336ee5ba30df231a7ab7
Author: Noam Postavsky <address@hidden>
Commit: Andrew G Cohen <address@hidden>
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.
---
doc/lispref/compile.texi | 3 ++-
doc/lispref/variables.texi | 39 ++++++++++++++++++++++++++++++++++++---
2 files changed, 38 insertions(+), 4 deletions(-)
diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi
index 0e39866..e665b84 100644
--- a/doc/lispref/compile.texi
+++ b/doc/lispref/compile.texi
@@ -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
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index b80bc88..4d04335 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -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.
address@hidden 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:
+
address@hidden
address@hidden
+(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)
address@hidden group
address@hidden example
+
@defun special-variable-p symbol
This function returns address@hidden if @var{symbol} is a special
variable (i.e., it has a @code{defvar}, @code{defcustom}, or
- [Emacs-diffs] feature/gnus-select 5502f96 161/218: * lisp/ibuf-ext.el (ibuffer-never-search-content-mode): Fix type., (continued)
- [Emacs-diffs] feature/gnus-select 5502f96 161/218: * lisp/ibuf-ext.el (ibuffer-never-search-content-mode): Fix type., Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select 6dbf88e 171/218: Fix the MSDOS build, Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select d5a07be 172/218: * etc/NEWS: Add an entry for auth-source-pass., Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select c1d88db 173/218: Document DEFUN attributes, Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select 0d04cb6 176/218: Fix byte-opt lists of pure functions etc., Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select b36a2f9 178/218: * lisp/org/ob-lisp.el (org-babel-lisp-eval-fn): Tweak type., Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select 4fdc730 177/218: sql.el defcustom fixes, Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select fe87972 186/218: * doc/emacs/trouble.texi: Fix location of `emacs-version' index., Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select 21aa752 184/218: Make update_autogen work in git worktrees, Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select 7985c87 188/218: * src/alloc.c: Avoid O(N²) complexity when unchaining markers (bug#24548)., Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select 1a1bb0c 185/218: Explain more about (defvar foo) form (Bug#18059),
Andrew G Cohen <=
- [Emacs-diffs] feature/gnus-select d46646d 195/218: Replace cl in some obsolete files, Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select e70347a 202/218: Limit build load, Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select f06346b 198/218: Clarify syntax of radixed integers, Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select 7bb9822 203/218: Remove variables labeled as obsolete that do nothing, Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select 6d35e8a 183/218: Quieten cl-lib related compiler warnings, Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select fdbaac5 213/218: Fix problem with trailing slash in Tramp, Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select 29d2a98 214/218: * src/marker.c: Try and speed up byte<->char conversion with many markers., Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select 5a33078 217/218: Trivial fixes for last changes to package.el and marker.c, Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select 491c4c3 201/218: Ensure configure is running if necessary, Andrew G Cohen, 2018/12/14
- [Emacs-diffs] feature/gnus-select 3cd3c00 210/218: Allow `&rest' or `&optional' without following variable (Bug#29165), Andrew G Cohen, 2018/12/14