X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/3fdb4c50a9ffd90cad4819b5405af03f805882aa..be051bc0e6a3dede4e185830d271fb4766030922:/lispref/variables.texi

diff --git a/lispref/variables.texi b/lispref/variables.texi
index dbb4f73024..49a8f0d7a2 100644
--- a/lispref/variables.texi
+++ b/lispref/variables.texi
@@ -1,7 +1,8 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000
-@c   Free Software Foundation, Inc. 
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999,
+@c 2000, 2003, 2004
+@c   Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/variables
 @node Variables, Functions, Control Structures, Top
@@ -43,6 +44,8 @@ variable.
 * Future Local Variables::  New kinds of local values we might add some day.
 * Variable Aliases::      Variables that are aliases for other variables.
 * File Local Variables::  Handling local variable lists in files.
+* Variables with Restricted Values::  Non-constant variables whose value can
+                                        @emph{not} be an arbitrary Lisp object.
 @end menu
 
 @node Global Variables
@@ -198,18 +201,18 @@ is omitted, @code{nil} is used.
 
 All of the @var{value-form}s in @var{bindings} are evaluated in the
 order they appear and @emph{before} binding any of the symbols to them.
-Here is an example of this: @code{Z} is bound to the old value of
-@code{Y}, which is 2, not the new value of @code{Y}, which is 1.
+Here is an example of this: @code{z} is bound to the old value of
+@code{y}, which is 2, not the new value of @code{y}, which is 1.
 
 @example
 @group
-(setq Y 2)
+(setq y 2)
      @result{} 2
 @end group
 @group
-(let ((Y 1) 
-      (Z Y))
-  (list Y Z))
+(let ((y 1)
+      (z y))
+  (list y z))
      @result{} (1 2)
 @end group
 @end example
@@ -225,13 +228,13 @@ form.  Compare the following example with the example above for
 
 @example
 @group
-(setq Y 2)
+(setq y 2)
      @result{} 2
 @end group
 @group
-(let* ((Y 1)
-       (Z Y))    ; @r{Use the just-established value of @code{Y}.}
-  (list Y Z))
+(let* ((y 1)
+       (z y))    ; @r{Use the just-established value of @code{y}.}
+  (list y z))
      @result{} (1 1)
 @end group
 @end example
@@ -259,18 +262,20 @@ they are localized depending on ``where'' you are in Emacs, rather than
 localized in time.
 
 @defvar max-specpdl-size
+@anchor{Definition of max-specpdl-size}
 @cindex variable limit error
 @cindex evaluation error
 @cindex infinite recursion
 This variable defines the limit on the total number of local variable
-bindings and @code{unwind-protect} cleanups (@pxref{Nonlocal Exits})
-that are allowed before signaling an error (with data @code{"Variable
-binding depth exceeds max-specpdl-size"}).
+bindings and @code{unwind-protect} cleanups (@pxref{Cleanups,,
+Cleaning Up from Nonlocal Exits}) that are allowed before signaling an
+error (with data @code{"Variable binding depth exceeds
+max-specpdl-size"}).
 
 This limit, with the associated error when it is exceeded, is one way
 that Lisp avoids infinite recursion on an ill-defined function.
 @code{max-lisp-eval-depth} provides another limit on depth of nesting.
-@xref{Eval}.
+@xref{Definition of max-lisp-eval-depth,, Eval}.
 
 The default value is 600.  Entry to the Lisp debugger increases the
 value, if there is little room left, to make sure the debugger itself
@@ -518,7 +523,7 @@ The @code{defvar} form returns @var{symbol}, but it is normally used
 at top level in a file where its value does not matter.
 @end defspec
 
-@defspec defconst symbol [value [doc-string]]
+@defspec defconst symbol value [doc-string]
 This special form defines @var{symbol} as a value and initializes it.
 It informs a person reading your code that @var{symbol} has a standard
 global value, established here, that should not be changed by the user
@@ -526,10 +531,10 @@ or by other programs.  Note that @var{symbol} is not evaluated; the
 symbol to be defined must appear explicitly in the @code{defconst}.
 
 @code{defconst} always evaluates @var{value}, and sets the value of
-@var{symbol} to the result if @var{value} is given.  If @var{symbol}
-does have a buffer-local binding in the current buffer, @code{defconst}
-sets the default value, not the buffer-local value.  (But you should not
-be making buffer-local bindings for a symbol that is defined with
+@var{symbol} to the result.  If @var{symbol} does have a buffer-local
+binding in the current buffer, @code{defconst} sets the default value,
+not the buffer-local value.  (But you should not be making
+buffer-local bindings for a symbol that is defined with
 @code{defconst}.)
 
 Here, @code{pi} is a constant that presumably ought not to be changed
@@ -576,11 +581,12 @@ this feature is largely obsoleted by @code{defcustom}
 (@pxref{Customization}).
 
   @strong{Warning:} If the @code{defconst} and @code{defvar} special
-forms are used while the variable has a local binding, they set the
-local binding's value; the global binding is not changed.  This is not
-what you usually want.  To prevent it, use these special forms at top
-level in a file, where normally no local binding is in effect, and make
-sure to load the file before making a local binding for the variable.
+forms are used while the variable has a local binding (made with
+@code{let}, or a function argument), they set the local-binding's
+value; the top-level binding is not changed.  This is not what you
+usually want.  To prevent it, use these special forms at top level in
+a file, where normally no local binding is in effect, and make sure to
+load the file before making a local binding for the variable.
 
 @node Tips for Defining
 @section Tips for Defining Variables Robustly
@@ -767,7 +773,7 @@ The value of the @code{setq} form is the value of the last @var{form}.
 x                   ; @r{@code{x} now has a global value.}
      @result{} 3
 @group
-(let ((x 5)) 
+(let ((x 5))
   (setq x 6)        ; @r{The local binding of @code{x} is set.}
   x)
      @result{} 6
@@ -784,7 +790,7 @@ second @var{symbol} is set, and so on:
 @group
 (setq x 10          ; @r{Notice that @code{x} is set before}
       y (1+ x))     ;   @r{the value of @code{y} is computed.}
-     @result{} 11             
+     @result{} 11
 @end group
 @end example
 @end defspec
@@ -857,11 +863,16 @@ always affects the most local existing binding.
   One other function for setting a variable is designed to add
 an element to a list if it is not already present in the list.
 
-@defun add-to-list symbol element
+@defun add-to-list symbol element &optional append
 This function sets the variable @var{symbol} by consing @var{element}
 onto the old value, if @var{element} is not already a member of that
 value.  It returns the resulting list, whether updated or not.  The
 value of @var{symbol} had better be a list already before the call.
+Membership is tested using @code{equal}.
+
+Normally, if @var{element} is added, it is added to the front of
+@var{symbol}, but if the optional argument @var{append} is
+non-@code{nil}, it is added at the end.
 
 The argument @var{symbol} is not implicitly quoted; @code{add-to-list}
 is an ordinary function, like @code{set} and unlike @code{setq}.  Quote
@@ -903,6 +914,7 @@ the others.
 @cindex scope
 @cindex extent
 @cindex dynamic scoping
+@cindex lexical scoping
   Local bindings in Emacs Lisp have @dfn{indefinite scope} and
 @dfn{dynamic extent}.  @dfn{Scope} refers to @emph{where} textually in
 the source code the binding can be accessed.  ``Indefinite scope'' means
@@ -1184,16 +1196,17 @@ the default binding untouched.  This means that the default value cannot
 be changed with @code{setq} in any buffer; the only way to change it is
 with @code{setq-default}.
 
-  @strong{Warning:} When a variable has buffer-local values in one or
-more buffers, binding the variable with @code{let} and changing to a
-different current buffer in which a different binding is in
-effect, and then exiting the @code{let}, the variable may not be
-restored to the value it had before the @code{let}.
-
-  To preserve your sanity, avoid using a variable in that way.  If you
-use @code{save-excursion} around each piece of code that changes to a
-different current buffer, you will not have this problem
-(@pxref{Excursions}).  Here is an example of what to avoid:
+  @strong{Warning:} When a variable has buffer-local or frame-local
+bindings in one or more buffers, @code{let} rebinds the binding that's
+currently in effect.  For instance, if the current buffer has a
+buffer-local value, @code{let} temporarily rebinds that.  If no
+buffer-local or frame-local bindings are in effect, @code{let} rebinds
+the default value.  If inside the @code{let} you then change to a
+different current buffer in which a different binding is in effect,
+you won't see the @code{let} binding any more.  And if you exit the
+@code{let} while still in the other buffer, you won't see the
+unbinding occur (though it will occur properly).  Here is an example
+to illustrate:
 
 @example
 @group
@@ -1208,24 +1221,12 @@ different current buffer, you will not have this problem
   ;; foo @result{} 'g     ; @r{the global value since foo is not local in @samp{b}}
   @var{body}@dots{})
 @group
-foo @result{} 'a        ; @r{we are still in buffer @samp{b}, but exiting the let}
-                 ; @r{restored the local value in buffer @samp{a}}
-@end group
-@group
-(set-buffer "a") ; @r{This can be seen here:}
-foo @result{} 'a        ; @r{we are back to the local value in buffer @samp{a}}
+foo @result{} 'g        ; @r{exiting restored the local value in buffer @samp{a},}
+                 ; @r{but we don't see that in buffer @samp{b}}
 @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{}))
+(set-buffer "a") ; @r{verify the local value was restored}
+foo @result{} 'a
 @end group
 @end example
 
@@ -1291,9 +1292,9 @@ If the variable is terminal-local, this function signals an error.  Such
 variables cannot have buffer-local bindings as well.  @xref{Multiple
 Displays}.
 
-@strong{Note:} Do not use @code{make-local-variable} for a hook
-variable.  The hook variables are automatically made buffer-local
-as needed if you use the @var{local} argument to @code{add-hook} or
+@strong{Warning:} do not use @code{make-local-variable} for a hook
+variable.  The hook variables are automatically made buffer-local as
+needed if you use the @var{local} argument to @code{add-hook} or
 @code{remove-hook}.
 @end deffn
 
@@ -1305,7 +1306,14 @@ local to the current buffer at the time.
 A peculiar wrinkle of this feature is that binding the variable (with
 @code{let} or other binding constructs) does not create a buffer-local
 binding for it.  Only setting the variable (with @code{set} or
-@code{setq}) does so.
+@code{setq}), while the variable does not have a @code{let}-style
+binding that was made in the current buffer, does so.
+
+If @var{variable} does not have a default value, then calling this
+command will give it a default value of @code{nil}.  If @var{variable}
+already has a default value, that value remains unchanged.
+Subsequently calling @code{makunbound} on @var{variable} will result
+in a void buffer-local value and leave the default value unaffected.
 
 The value returned is @var{variable}.
 
@@ -1328,6 +1336,19 @@ This returns @code{t} if @var{variable} is buffer-local in buffer
 @code{nil}.
 @end defun
 
+@defun local-variable-if-set-p variable &optional buffer
+This returns @code{t} if @var{variable} will become buffer-local in
+buffer @var{buffer} (which defaults to the current buffer) if it is
+set there.
+@end defun
+
+@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
+
 @defun buffer-local-variables &optional buffer
 This function returns a list describing the buffer-local variables in
 buffer @var{buffer}.  (If @var{buffer} is omitted, the current buffer is
@@ -1350,7 +1371,7 @@ then the variable appears directly in the resulting list.
     (mode-name . "Fundamental")
     @dots{}
 @group
-    ;; @r{Next, non-built-in buffer-local variables.} 
+    ;; @r{Next, non-built-in buffer-local variables.}
     ;; @r{This one is buffer-local and void:}
     foobar
     ;; @r{This one is buffer-local and nonvoid:}
@@ -1362,13 +1383,6 @@ Note that storing new values into the @sc{cdr}s of cons cells in this
 list does @emph{not} change the buffer-local values of the variables.
 @end defun
 
-@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
-
 @deffn Command kill-local-variable variable
 This function deletes the buffer-local binding (if any) for
 @var{variable} (a symbol) in the current buffer.  As a result, the
@@ -1415,8 +1429,11 @@ variables that major modes set should not be marked permanent.
 The function @code{kill-all-local-variables} runs this normal hook
 before it does anything else.  This gives major modes a way to arrange
 for something special to be done if the user switches to a different
-major mode.  For best results, make this variable buffer-local, so that
-it will disappear after doing its job and will not interfere with the
+major mode.  It is also useful for buffer-specific minor modes
+that should be forgotten if the user changes the major mode.
+
+For best results, make this variable buffer-local, so that it will
+disappear after doing its job and will not interfere with the
 subsequent major mode.  @xref{Hooks}.
 @end defvar
 
@@ -1565,11 +1582,17 @@ not in itself create any frame-local bindings for the variable; however,
 if some frame already has a value for @var{variable} as a frame
 parameter, that value automatically becomes a frame-local binding.
 
+If @var{variable} does not have a default value, then calling this
+command will give it a default value of @code{nil}.  If @var{variable}
+already has a default value, that value remains unchanged.
+
 If the variable is terminal-local, this function signals an error,
 because such variables cannot have frame-local bindings as well.
 @xref{Multiple Displays}.  A few variables that are implemented
 specially in Emacs can be (and usually are) buffer-local, but can never
 be frame-local.
+
+This command returns @var{variable}.
 @end deffn
 
   Buffer-local bindings take precedence over frame-local bindings.  Thus,
@@ -1676,21 +1699,55 @@ chosen, or because its meaning has partly changed---it can be useful
 to keep the old name as an @emph{alias} of the new one for
 compatibility.  You can do this with @code{defvaralias}.
 
-@defun defvaralias alias-var base-var [docstring]
+@defun defvaralias alias-var base-var &optional docstring
 This function defines the symbol @var{alias-var} as a variable alias
 for symbol @var{base-var}. This means that retrieving the value of
 @var{alias-var} returns the value of @var{base-var}, and changing the
 value of @var{alias-var} changes the value of @var{base-var}.
 
-If the @var{docstring} argument is present, it specifies the documentation for
-@var{alias-var}; otherwise, it has the same documentation as @var{base-var},
-if any.
+If the @var{docstring} argument is non-@code{nil}, it specifies the
+documentation for @var{alias-var}; otherwise, the alias gets the same
+documentation as @var{base-var} has, if any, unless @var{base-var} is
+itself an alias, in which case @var{alias-var} gets the documentation
+of the variable at the end of the chain of aliases.
+
+This function returns @var{base-var}.
 @end defun
 
+Variables aliases are often used prior to replacing an old name for a variable
+with a new name. To allow some time for existing code to adapt to this change,
+@code{make-obsolete-variable} declares that the old name is obsolete and
+therefore that it may be removed at some stage in the future.
+
+@defmac make-obsolete-variable variable new &optional when
+This macro makes the byte-compiler warn that symbol @var{variable} is
+obsolete and that symbol @var{new} should be used instead.  If
+@var{new} is a string, this is the message and there is no replacement
+variable.  If it is provided, @var{when} should be a string indicating
+when the variable was first made obsolete, for example a date or a
+release number.
+@end defmac
+
+You can make two variables synonyms and declare one obsolete at the
+same time using the macro @code{define-obsolete-variable-alias}.
+
+@defmac define-obsolete-variable-alias variable new &optional when docstring
+This macro defines the symbol @var{variable} as a variable alias for
+symbol @var{new} and warns that @var{variable} is obsolete.  If it is
+provided, @var{when} should be a string indicating when @var{variable}
+was first made obsolete.  The optional argument @var{docstring}
+specifies the documentation string for @var{variable}.  If
+@var{docstring} is omitted or nil, @var{variable} uses the
+documentation string of @var{new} unless it already has one.
+@end defmac
+
 @defun indirect-variable variable
 This function returns the variable at the end of the chain of aliases
 of @var{variable}.  If @var{variable} is not a symbol, or if @var{variable} is
 not defined as an alias, the function returns @var{variable}.
+
+This function signals a @code{cyclic-variable-indirection} error if
+there is a loop in the chain of symbols.
 @end defun
 
 @example
@@ -1702,8 +1759,10 @@ not defined as an alias, the function returns @var{variable}.
 (setq bar 2)
 bar
      @result{} 2
+@group
 foo
      @result{} 2
+@end group
 (setq foo 0)
 bar
      @result{} 0
@@ -1715,7 +1774,9 @@ foo
 @section File Local Variables
 
   This section describes the functions and variables that affect
-processing of local variables lists in files.
+processing of local variables lists in files. @xref{File variables, ,
+Local Variables in Files, emacs, The GNU Emacs Manual}, for basic
+information about file local variables.
 
 @defopt enable-local-variables
 This variable controls whether to process file local variables lists.  A
@@ -1724,29 +1785,48 @@ unconditionally; @code{nil} means ignore them; anything else means ask
 the user what to do for each file.  The default value is @code{t}.
 @end defopt
 
-@defun hack-local-variables &optional force
+@defun hack-local-variables &optional mode-only
 This function parses, and binds or evaluates as appropriate, any local
 variables specified by the contents of the current buffer.  The variable
-@code{enable-local-variables} has its effect here.
-
-The argument @var{force} usually comes from the argument @var{find-file}
-given to @code{normal-mode}.
+@code{enable-local-variables} has its effect here.  However, this
+function does not look for the @samp{mode:} local variable in the
+@w{@samp{-*-}} line.  @code{set-auto-mode} does that, also taking
+@code{enable-local-variables} into account.
+
+If the optional argument @var{mode-only} is non-@code{nil}, then all
+this function does is return @code{t} if the @w{@samp{-*-}} line
+specifies a mode and @code{nil} otherwise.  It does not set the mode
+nor any other file local variable.  It does not check whether a mode
+is specified in the local variables list at the end of the file.
 @end defun
 
-  If a file local variable list could specify the a function that will
-be called later, or an expression that will be executed later, simply
+  If a file local variable list could specify a function that would
+be called later, or an expression that would be executed later, simply
 visiting a file could take over your Emacs.  To prevent this, Emacs
 takes care not to allow local variable lists to set such variables.
 
-  For one thing, any variable whose name ends in @samp{-function},
-@samp{-functions}, @samp{-hook}, @samp{-hooks}, @samp{-form},
-@samp{-forms}, @samp{-program}, @samp{-command} or @samp{-predicate}
-cannot be set in a local variable list.  In general, you should use such
-a name whenever it is appropriate for the variable's meaning.
+  For one thing, any variable whose name ends in @samp{-command},
+@samp{-frame-alist}, @samp{-function}, @samp{-functions},
+@samp{-hook}, @samp{-hooks}, @samp{-form}, @samp{-forms}, @samp{-map},
+@samp{-map-alist}, @samp{-mode-alist}, @samp{-program}, or
+@samp{-predicate} cannot be set in a local variable list.  In general,
+you should use such a name whenever it is appropriate for the
+variable's meaning.  The variables @samp{font-lock-keywords},
+@samp{font-lock-keywords-[0-9]}, and
+@samp{font-lock-syntactic-keywords} cannot be set in a local variable
+list, either.  These rules can be overridden by giving the variable's
+name a non-@code{nil} @code{safe-local-variable} property.  If one
+gives it a @code{safe-local-variable} property of @code{t}, then one
+can give the variable any file local value.  One can also give any
+symbol, including the above, a @code{safe-local-variable} property
+that is a function taking exactly one argument.  In that case, giving
+a variable with that name a file local value is only allowed if the
+function returns non-@code{nil} when called with that value as
+argument.
 
   In addition, any variable whose name has a non-@code{nil}
-@code{risky-local-variable} property is also ignored.  So are
-all variables listed in @code{ignored-local-variables}:
+@code{risky-local-variable} property is also ignored.  So are all
+variables listed in @code{ignored-local-variables}:
 
 @defvar ignored-local-variables
 This variable holds a list of variables that should not be
@@ -1754,6 +1834,14 @@ set by a file's local variables list.  Any value specified
 for one of these variables is ignored.
 @end defvar
 
+@defun risky-local-variable-p sym &optional val
+If @var{val} is non-@code{nil}, returns non-@code{nil} if giving
+@var{sym} a file local value of @var{val} would be risky, for any of
+the reasons stated above.  If @var{val} is @code{nil} or omitted, only
+returns @code{nil} if @var{sym} can be safely assigned any file local
+value whatsoever.
+@end defun
+
   The @samp{Eval:} ``variable'' is also a potential loophole, so Emacs
 normally asks for confirmation before handling it.
 
@@ -1763,3 +1851,47 @@ lists in files being visited.  A value of @code{t} means process them
 unconditionally; @code{nil} means ignore them; anything else means ask
 the user what to do for each file.  The default value is @code{maybe}.
 @end defopt
+
+  Text properties are also potential loopholes, since their values
+could include functions to call.  So Emacs discards all text
+properties from string values specified in a file's local variables
+list.
+
+@node Variables with Restricted Values
+@section Variables with Restricted Values
+
+  Ordinary Lisp variables can be assigned any value that is a valid
+Lisp object.  However, certain Lisp variables are not defined in Lisp,
+but in C.  Most of these variables are defined in the C code using
+@code{DEFVAR_LISP}.  Like variables defined in Lisp, these can take on
+any value.  However, some variables are defined using
+@code{DEFVAR_INT} or @code{DEFVAR_BOOL}.  @xref{Defining Lisp
+variables in C,, Writing Emacs Primitives}, in particular the
+description of functions of the type @code{syms_of_@var{filename}},
+for a brief discussion of the C implementation.
+
+  Variables of type @code{DEFVAR_BOOL} can only take on the values
+@code{nil} or @code{t}.  Attempting to assign them any other value
+will set them to @code{t}:
+
+@example
+(let ((display-hourglass 5))
+  display-hourglass)
+     @result{} t
+@end example
+
+@defvar byte-boolean-vars
+This variable holds a list of all variables of type @code{DEFVAR_BOOL}.
+@end defvar
+
+  Variables of type @code{DEFVAR_INT} can only take on integer values.
+Attempting to assign them any other value will result in an error:
+
+@example
+(setq window-min-height 5.0)
+@error{} Wrong type argument: integerp, 5.0
+@end example
+
+@ignore
+   arch-tag: 5ff62c44-2b51-47bb-99d4-fea5aeec5d3e
+@end ignore