/[emacs]/emacs/lispref/variables.texi
ViewVC logotype

Diff of /emacs/lispref/variables.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.31.2.1 by miles, Fri Apr 4 06:20:42 2003 UTC revision 1.31.2.2 by miles, Tue Oct 14 23:10:12 2003 UTC
# Line 198  is omitted, @code{nil} is used. Line 198  is omitted, @code{nil} is used.
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
# Line 225  form.  Compare the following example wit Line 225  form.  Compare the following example wit
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
# Line 576  this feature is largely obsoleted by @co Line 576  this feature is largely obsoleted by @co
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
# Line 903  the others. Line 904  the others.
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
# Line 1184  the default binding untouched.  This mea Line 1186  the default binding untouched.  This mea
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
# Line 1208  different current buffer, you will not h Line 1211  different current buffer, you will not h
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    
# Line 1291  If the variable is terminal-local, this Line 1282  If the variable is terminal-local, this
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    
# Line 1328  This returns @code{t} if @var{variable} Line 1319  This returns @code{t} if @var{variable}
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
# Line 1362  Note that storing new values into the @s Line 1360  Note that storing new values into the @s
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
# Line 1676  chosen, or because its meaning has partl Line 1667  chosen, or because its meaning has partl
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
# Line 1760  for one of these variables is ignored. Line 1751  for one of these variables is ignored.
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
# Line 1772  lists in files being visited.  A value o Line 1764  lists in files being visited.  A value o
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

Legend:
Removed from v.1.31.2.1  
changed lines
  Added in v.1.31.2.2

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26