198 |
|
|
199 |
All of the @var{value-form}s in @var{bindings} are evaluated in the |
All of the @var{value-form}s in @var{bindings} are evaluated in the |
200 |
order they appear and @emph{before} binding any of the symbols to them. |
order they appear and @emph{before} binding any of the symbols to them. |
201 |
Here is an example of this: @code{Z} is bound to the old value of |
Here is an example of this: @code{z} is bound to the old value of |
202 |
@code{Y}, which is 2, not the new value of @code{Y}, which is 1. |
@code{y}, which is 2, not the new value of @code{y}, which is 1. |
203 |
|
|
204 |
@example |
@example |
205 |
@group |
@group |
206 |
(setq Y 2) |
(setq y 2) |
207 |
@result{} 2 |
@result{} 2 |
208 |
@end group |
@end group |
209 |
@group |
@group |
210 |
(let ((Y 1) |
(let ((y 1) |
211 |
(Z Y)) |
(z y)) |
212 |
(list Y Z)) |
(list y z)) |
213 |
@result{} (1 2) |
@result{} (1 2) |
214 |
@end group |
@end group |
215 |
@end example |
@end example |
225 |
|
|
226 |
@example |
@example |
227 |
@group |
@group |
228 |
(setq Y 2) |
(setq y 2) |
229 |
@result{} 2 |
@result{} 2 |
230 |
@end group |
@end group |
231 |
@group |
@group |
232 |
(let* ((Y 1) |
(let* ((y 1) |
233 |
(Z Y)) ; @r{Use the just-established value of @code{Y}.} |
(z y)) ; @r{Use the just-established value of @code{y}.} |
234 |
(list Y Z)) |
(list y z)) |
235 |
@result{} (1 1) |
@result{} (1 1) |
236 |
@end group |
@end group |
237 |
@end example |
@end example |
576 |
(@pxref{Customization}). |
(@pxref{Customization}). |
577 |
|
|
578 |
@strong{Warning:} If the @code{defconst} and @code{defvar} special |
@strong{Warning:} If the @code{defconst} and @code{defvar} special |
579 |
forms are used while the variable has a local binding, they set the |
forms are used while the variable has a local binding (made with |
580 |
local binding's value; the global binding is not changed. This is not |
@code{let}, or a function argument), they set the local-binding's |
581 |
what you usually want. To prevent it, use these special forms at top |
value; the top-level binding is not changed. This is not what you |
582 |
level in a file, where normally no local binding is in effect, and make |
usually want. To prevent it, use these special forms at top level in |
583 |
sure to load the file before making a local binding for the variable. |
a file, where normally no local binding is in effect, and make sure to |
584 |
|
load the file before making a local binding for the variable. |
585 |
|
|
586 |
@node Tips for Defining |
@node Tips for Defining |
587 |
@section Tips for Defining Variables Robustly |
@section Tips for Defining Variables Robustly |
904 |
@cindex scope |
@cindex scope |
905 |
@cindex extent |
@cindex extent |
906 |
@cindex dynamic scoping |
@cindex dynamic scoping |
907 |
|
@cindex lexical scoping |
908 |
Local bindings in Emacs Lisp have @dfn{indefinite scope} and |
Local bindings in Emacs Lisp have @dfn{indefinite scope} and |
909 |
@dfn{dynamic extent}. @dfn{Scope} refers to @emph{where} textually in |
@dfn{dynamic extent}. @dfn{Scope} refers to @emph{where} textually in |
910 |
the source code the binding can be accessed. ``Indefinite scope'' means |
the source code the binding can be accessed. ``Indefinite scope'' means |
1186 |
be changed with @code{setq} in any buffer; the only way to change it is |
be changed with @code{setq} in any buffer; the only way to change it is |
1187 |
with @code{setq-default}. |
with @code{setq-default}. |
1188 |
|
|
1189 |
@strong{Warning:} When a variable has buffer-local values in one or |
@strong{Warning:} When a variable has buffer-local or frame-local |
1190 |
more buffers, binding the variable with @code{let} and changing to a |
bindings in one or more buffers, @code{let} rebinds the binding that's |
1191 |
different current buffer in which a different binding is in |
currently in effect. For instance, if the current buffer has a |
1192 |
effect, and then exiting the @code{let}, the variable may not be |
buffer-local value, @code{let} temporarily rebinds that. If no |
1193 |
restored to the value it had before the @code{let}. |
buffer-local or frame-local bindings are in effect, @code{let} rebinds |
1194 |
|
the default value. If inside the @code{let} you then change to a |
1195 |
To preserve your sanity, avoid using a variable in that way. If you |
different current buffer in which a different binding is in effect, |
1196 |
use @code{save-excursion} around each piece of code that changes to a |
you won't see the @code{let} binding any more. And if you exit the |
1197 |
different current buffer, you will not have this problem |
@code{let} while still in the other buffer, you won't see the |
1198 |
(@pxref{Excursions}). Here is an example of what to avoid: |
unbinding occur (though it will occur properly). Here is an example |
1199 |
|
to illustrate: |
1200 |
|
|
1201 |
@example |
@example |
1202 |
@group |
@group |
1211 |
;; foo @result{} 'g ; @r{the global value since foo is not local in @samp{b}} |
;; foo @result{} 'g ; @r{the global value since foo is not local in @samp{b}} |
1212 |
@var{body}@dots{}) |
@var{body}@dots{}) |
1213 |
@group |
@group |
1214 |
foo @result{} 'a ; @r{we are still in buffer @samp{b}, but exiting the let} |
foo @result{} 'g ; @r{exiting restored the local value in buffer @samp{a},} |
1215 |
; @r{restored the local value in buffer @samp{a}} |
; @r{but we don't see that in buffer @samp{b}} |
1216 |
@end group |
@end group |
1217 |
@group |
@group |
1218 |
(set-buffer "a") ; @r{This can be seen here:} |
(set-buffer "a") ; @r{verify the local value was restored} |
1219 |
foo @result{} 'a ; @r{we are back to the local value in buffer @samp{a}} |
foo @result{} 'a |
|
@end group |
|
|
@end example |
|
|
|
|
|
@noindent |
|
|
But @code{save-excursion} as shown here avoids the problem: |
|
|
|
|
|
@example |
|
|
@group |
|
|
(let ((foo 'temp)) |
|
|
(save-excursion |
|
|
(set-buffer "b") |
|
|
@var{body}@dots{})) |
|
1220 |
@end group |
@end group |
1221 |
@end example |
@end example |
1222 |
|
|
1282 |
variables cannot have buffer-local bindings as well. @xref{Multiple |
variables cannot have buffer-local bindings as well. @xref{Multiple |
1283 |
Displays}. |
Displays}. |
1284 |
|
|
1285 |
@strong{Note:} Do not use @code{make-local-variable} for a hook |
@strong{Warning:} do not use @code{make-local-variable} for a hook |
1286 |
variable. The hook variables are automatically made buffer-local |
variable. The hook variables are automatically made buffer-local as |
1287 |
as needed if you use the @var{local} argument to @code{add-hook} or |
needed if you use the @var{local} argument to @code{add-hook} or |
1288 |
@code{remove-hook}. |
@code{remove-hook}. |
1289 |
@end deffn |
@end deffn |
1290 |
|
|
1319 |
@code{nil}. |
@code{nil}. |
1320 |
@end defun |
@end defun |
1321 |
|
|
1322 |
|
@defun buffer-local-value variable buffer |
1323 |
|
This function returns the buffer-local binding of @var{variable} (a |
1324 |
|
symbol) in buffer @var{buffer}. If @var{variable} does not have a |
1325 |
|
buffer-local binding in buffer @var{buffer}, it returns the default |
1326 |
|
value (@pxref{Default Value}) of @var{variable} instead. |
1327 |
|
@end defun |
1328 |
|
|
1329 |
@defun buffer-local-variables &optional buffer |
@defun buffer-local-variables &optional buffer |
1330 |
This function returns a list describing the buffer-local variables in |
This function returns a list describing the buffer-local variables in |
1331 |
buffer @var{buffer}. (If @var{buffer} is omitted, the current buffer is |
buffer @var{buffer}. (If @var{buffer} is omitted, the current buffer is |
1360 |
list does @emph{not} change the buffer-local values of the variables. |
list does @emph{not} change the buffer-local values of the variables. |
1361 |
@end defun |
@end defun |
1362 |
|
|
|
@defun buffer-local-value variable buffer |
|
|
This function returns the buffer-local binding of @var{variable} (a |
|
|
symbol) in buffer @var{buffer}. If @var{variable} does not have a |
|
|
buffer-local binding in buffer @var{buffer}, it returns the default |
|
|
value (@pxref{Default Value}) of @var{variable} instead. |
|
|
@end defun |
|
|
|
|
1363 |
@deffn Command kill-local-variable variable |
@deffn Command kill-local-variable variable |
1364 |
This function deletes the buffer-local binding (if any) for |
This function deletes the buffer-local binding (if any) for |
1365 |
@var{variable} (a symbol) in the current buffer. As a result, the |
@var{variable} (a symbol) in the current buffer. As a result, the |
1667 |
to keep the old name as an @emph{alias} of the new one for |
to keep the old name as an @emph{alias} of the new one for |
1668 |
compatibility. You can do this with @code{defvaralias}. |
compatibility. You can do this with @code{defvaralias}. |
1669 |
|
|
1670 |
@defun defvaralias alias-var base-var [docstring] |
@defun defvaralias alias-var base-var &optional docstring |
1671 |
This function defines the symbol @var{alias-var} as a variable alias |
This function defines the symbol @var{alias-var} as a variable alias |
1672 |
for symbol @var{base-var}. This means that retrieving the value of |
for symbol @var{base-var}. This means that retrieving the value of |
1673 |
@var{alias-var} returns the value of @var{base-var}, and changing the |
@var{alias-var} returns the value of @var{base-var}, and changing the |
1674 |
value of @var{alias-var} changes the value of @var{base-var}. |
value of @var{alias-var} changes the value of @var{base-var}. |
1675 |
|
|
1676 |
If the @var{docstring} argument is present, it specifies the documentation for |
If the @var{docstring} argument is non-@code{nil}, it specifies the |
1677 |
@var{alias-var}; otherwise, it has the same documentation as @var{base-var}, |
documentation for @var{alias-var}; otherwise, the alias gets the same |
1678 |
if any. |
documentation as @var{base-var} has, if any. |
1679 |
@end defun |
@end defun |
1680 |
|
|
1681 |
@defun indirect-variable variable |
@defun indirect-variable variable |
1751 |
@end defvar |
@end defvar |
1752 |
|
|
1753 |
@defun risky-local-variable-p sym |
@defun risky-local-variable-p sym |
1754 |
Returns non-nil if @var{sym} is risky for any of the reasons stated above. |
Returns non-@code{nil} if @var{sym} is risky for any of the reasons |
1755 |
|
stated above. |
1756 |
@end defun |
@end defun |
1757 |
|
|
1758 |
The @samp{Eval:} ``variable'' is also a potential loophole, so Emacs |
The @samp{Eval:} ``variable'' is also a potential loophole, so Emacs |
1764 |
unconditionally; @code{nil} means ignore them; anything else means ask |
unconditionally; @code{nil} means ignore them; anything else means ask |
1765 |
the user what to do for each file. The default value is @code{maybe}. |
the user what to do for each file. The default value is @code{maybe}. |
1766 |
@end defopt |
@end defopt |
1767 |
|
|
1768 |
|
Text properties are also potential loopholes, since their values |
1769 |
|
could include functions to call. So Emacs discards all text |
1770 |
|
properties from string values specified in a file's local variables |
1771 |
|
list. |
1772 |
|
|
1773 |
|
@ignore |
1774 |
|
arch-tag: 5ff62c44-2b51-47bb-99d4-fea5aeec5d3e |
1775 |
|
@end ignore |