@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, 2000, 2002,
+@c 2003, 2004, 2005 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/variables
@node Variables, Functions, Control Structures, Top
* Buffer-Local Variables:: Variable values in effect only in one buffer.
* Frame-Local Variables:: Variable values in effect only in one frame.
* 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.
+* Variable Aliases:: Variables that are aliases for other variables.
+* Variables with Restricted Values:: Non-constant variables whose value can
+ @emph{not} be an arbitrary Lisp object.
@end menu
@node Global Variables
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
declared equivalently in @file{cus-start.el}.} or by the first character
of their @code{variable-documentation} property. If the property exists
and is a string, and its first character is @samp{*}, then the variable
-is a user option.
+is a user option. Aliases of user options are also user options.
@end defun
@kindex variable-interactive
(setq @var{var} (cons @var{value} @var{var})))
@end example
+@defun add-to-ordered-list symbol element &optional order
+This function sets the variable @var{symbol} by inserting
+@var{element} into the old value, which must be a list, at the
+position specified by @var{order}. If @var{element} is already a
+member of the list, its position in the list is adjusted according
+to @var{order}. Membership is tested using @code{eq}.
+This function returns the resulting list, whether updated or not.
+
+The @var{order} is typically a number (integer or float), and the
+elements of the list are sorted in non-decreasing numerical order.
+
+@var{order} may also be omitted or @code{nil}. Then the numeric order
+of @var{element} stays unchanged if it already has one; otherwise,
+@var{element} has no numeric order. Elements without a numeric list
+order are placed at the end of the list, in no particular order.
+
+Any other value for @var{order} removes the numeric order of @var{element}
+if it already has one; otherwise, it is equivalent to @code{nil}.
+
+The argument @var{symbol} is not implicitly quoted;
+@code{add-to-ordered-list} is an ordinary function, like @code{set}
+and unlike @code{setq}. Quote the argument yourself if that is what
+you want.
+
+The ordering information is stored in a hash table on @var{symbol}'s
+@code{list-order} property.
+@end defun
+
+Here's a scenario showing how to use @code{add-to-ordered-list}:
+
+@example
+(setq foo '())
+ @result{} nil
+
+(add-to-ordered-list 'foo 'a 1) ;; @r{Add @code{a}.}
+ @result{} (a)
+
+(add-to-ordered-list 'foo 'c 3) ;; @r{Add @code{c}.}
+ @result{} (a c)
+
+(add-to-ordered-list 'foo 'b 2) ;; @r{Add @code{b}.}
+ @result{} (a b c)
+
+(add-to-ordered-list 'foo 'b 4) ;; @r{Move @code{b}.}
+ @result{} (a c b)
+
+(add-to-ordered-list 'foo 'd) ;; @r{Append @code{d}.}
+ @result{} (a c b d)
+
+(add-to-ordered-list 'foo 'e) ;; @r{Add @code{e}}.
+ @result{} (a c b e d)
+
+foo ;; @r{@code{foo} was changed.}
+ @result{} (a c b e d)
+@end example
+
@node Variable Scoping
@section Scoping Rules for Variable Bindings
@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
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
If sufficient application is found for either of these two kinds of
local bindings, we will provide it in a subsequent Emacs version.
+@node File Local Variables
+@section File Local Variables
+
+ This section describes the functions and variables that affect
+processing of file local variables. @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. 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{t}.
+@end defopt
+
+@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. 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 (@pxref{Auto Major Mode}).
+
+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 or
+the local variables list specifies a mode and @code{nil} otherwise.
+It does not set the mode nor any other file local variable.
+@end defun
+
+ If a file local variable 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 to set such file local variables.
+
+ For one thing, any variable whose name ends in any of
+@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 given a file local
+value. 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} followed by a
+digit, and @samp{font-lock-syntactic-keywords} cannot be given file
+local values 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}:
+
+@defvar ignored-local-variables
+This variable holds a list of variables that should not be given local
+values by files. 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.
+
+@defopt enable-local-eval
+This variable controls processing of @samp{Eval:} in @samp{-*-} lines
+or local variables
+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 for file local variables.
+
@node Variable Aliases
@section Variable Aliases
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 &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}.
+@defun defvaralias new-alias base-variable &optional docstring
+This function defines the symbol @var{new-alias} as a variable alias
+for symbol @var{base-variable}. This means that retrieving the value of
+@var{new-alias} returns the value of @var{base-variable}, and changing the
+value of @var{new-alias} changes the value of @var{base-variable}.
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.
+documentation for @var{new-alias}; otherwise, the alias gets the same
+documentation as @var{base-variable} has, if any, unless
+@var{base-variable} is itself an alias, in which case @var{new-alias} gets
+the documentation of the variable at the end of the chain of aliases.
+
+This function returns @var{base-variable}.
+@end defun
-This function returns @var{base-var}.
+ Variable aliases are convenient for replacing an old name for a
+variable with a new name. @code{make-obsolete-variable} declares that
+the old name is obsolete and therefore that it may be removed at some
+stage in the future.
+
+@defun make-obsolete-variable obsolete-name current-name &optional when
+This function makes the byte-compiler warn that the variable
+@var{obsolete-name} is obsolete. If @var{current-name} is a symbol, it is
+the variable's new name; then the warning message says to use
+@var{current-name} instead of @var{obsolete-name}. If @var{current-name}
+is a string, this is the message and there is no replacement variable.
+
+If provided, @var{when} should be a string indicating when the
+variable was first made obsolete---for example, a date or a release
+number.
@end defun
+ 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 obsolete-name current-name &optional when docstring
+This macro marks the variable @var{obsolete-name} as obsolete and also
+makes it an alias for the variable @var{current-name}. It is
+equivalent to the following:
+
+@example
+(defvaralias @var{obsolete-name} @var{current-name} @var{docstring})
+(make-obsolete-variable @var{obsolete-name} @var{current-name} @var{when})
+@end example
+@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
@result{} 0
@end example
-@node File Local Variables
-@section File Local Variables
-
- This section describes the functions and variables that affect
-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
-value of @code{t} means process the local variables lists
-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 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. 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.
+@node Variables with Restricted Values
+@section Variables with Restricted Values
-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
+ 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.
- If a file local variable list could specify a function that will
-be called later, or an expression that will 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{-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.
+ 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}:
- 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}:
+@example
+(let ((display-hourglass 5))
+ display-hourglass)
+ @result{} t
+@end example
-@defvar ignored-local-variables
-This variable holds a list of variables that should not be
-set by a file's local variables list. Any value specified
-for one of these variables is ignored.
+@defvar byte-boolean-vars
+This variable holds a list of all variables of type @code{DEFVAR_BOOL}.
@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.
-
-@defopt enable-local-eval
-This variable controls processing of @samp{Eval:} in local variables
-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
+ Variables of type @code{DEFVAR_INT} can only take on integer values.
+Attempting to assign them any other value will result in an error:
- 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.
+@example
+(setq window-min-height 5.0)
+@error{} Wrong type argument: integerp, 5.0
+@end example
@ignore
arch-tag: 5ff62c44-2b51-47bb-99d4-fea5aeec5d3e