diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi index c0dc3d472e3..fc9a64d375e 100644 --- a/doc/emacs/trouble.texi +++ b/doc/emacs/trouble.texi @@ -594,7 +594,6 @@ with the manual, one of them must be wrong; that is a bug. @cindex bug reporting @cindex report an Emacs bug, how to -@findex emacs-version When you decide that there is a bug, it is important to report it and to report it in a way which is useful. What is most useful is an exact description of what commands you type, starting with the shell @@ -717,6 +716,7 @@ should include all these things: The version number of Emacs. Without this, we won't know whether there is any point in looking for the bug in the current version of GNU Emacs. +@findex emacs-version @kbd{M-x report-emacs-bug} includes this information automatically, but if you are not using that command for your report you can get the version number by typing @kbd{M-x emacs-version @key{RET}}. If that diff --git a/doc/lispref/anti.texi b/doc/lispref/anti.texi index ef28415d591..556203b69f0 100644 --- a/doc/lispref/anti.texi +++ b/doc/lispref/anti.texi @@ -164,9 +164,10 @@ come, and learning to use yet another API is a burden. @item The function @code{read-multiple-choice} is also gone, in recognition -of the fact that nothing makes Emacs Lisp hacker rejoice more than the -need to sit down and write yet another interactive question-and-answer -function, and make it optimal for each specific case. +of the fact that nothing makes Emacs Lisp hackers rejoice more than +the need to sit down and write yet another interactive +question-and-answer function, and make it optimal for each specific +case. @item The function @code{add-variable-watcher} and the corresponding diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi index a72e1eb69fc..cfd2fb7715b 100644 --- a/doc/lispref/buffers.texi +++ b/doc/lispref/buffers.texi @@ -891,7 +891,7 @@ This function operates on each frame's @code{buffer-list} parameter as well as the fundamental buffer list; therefore, the buffer that you bury will come last in the value of @code{(buffer-list @var{frame})} and in the value of @code{(buffer-list)}. In addition, it also puts the buffer -at the end of the list of buffer of the selected window (@pxref{Window +at the end of the list of buffers of the selected window (@pxref{Window History}) provided it is shown in that window. If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi index 0e39866d349..e665b84f9b8 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 b80bc88a585..4d04335d83a 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. +@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 diff --git a/lisp/org/ob-lisp.el b/lisp/org/ob-lisp.el index c156ca34a7c..d4a7c37133d 100644 --- a/lisp/org/ob-lisp.el +++ b/lisp/org/ob-lisp.el @@ -54,7 +54,7 @@ Valid values include `slime-eval' and `sly-eval'." :group 'org-babel :version "26.1" :package-version '(Org . "9.0") - :type 'function) + :type 'symbol) (defcustom org-babel-lisp-dir-fmt "(let ((*default-pathname-defaults* #P%S\n)) %%s\n)" diff --git a/src/lisp.h b/src/lisp.h index a7f0a1d78ff..aefdaeaf12f 100644 --- a/src/lisp.h +++ b/src/lisp.h @@ -2685,13 +2685,12 @@ struct Lisp_Buffer_Objfwd variable, you must first make sure the right binding is loaded; then you can access the value in (or through) `realvalue'. - `buffer' and `frame' are the buffer and frame for which the loaded - binding was found. If those have changed, to make sure the right - binding is loaded it is necessary to find which binding goes with - the current buffer and selected frame, then load it. To load it, - first unload the previous binding, then copy the value of the new - binding into `realvalue' (or through it). Also update - LOADED-BINDING to point to the newly loaded binding. + `where' is the buffer for which the loaded binding was found. If + it has changed, to make sure the right binding is loaded it is + necessary to find which binding goes with the current buffer, then + load it. To load it, first unload the previous binding, then copy + the value of the new binding into `realvalue' (or through it). + Also update LOADED-BINDING to point to the newly loaded binding. `local_if_set' indicates that merely setting the variable creates a local binding for the current buffer. Otherwise the latter, setting @@ -2707,14 +2706,14 @@ struct Lisp_Buffer_Local_Value bool_bf found : 1; /* If non-NULL, a forwarding to the C var where it should also be set. */ union Lisp_Fwd *fwd; /* Should never be (Buffer|Kboard)_Objfwd. */ - /* The buffer or frame for which the loaded binding was found. */ + /* The buffer for which the loaded binding was found. */ Lisp_Object where; /* A cons cell that holds the default value. It has the form (SYMBOL . DEFAULT-VALUE). */ Lisp_Object defcell; /* The cons cell from `where's parameter alist. It always has the form (SYMBOL . VALUE) - Note that if `forward' is non-nil, VALUE may be out of date. + Note that if `fwd' is non-NULL, VALUE may be out of date. Also if the currently loaded binding is the default binding, then this is `eq'ual to defcell. */ Lisp_Object valcell;