@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999,
-@c 2000, 2003, 2004
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000,
+@c 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/variables
@node Variables, Functions, Control Structures, Top
@node Constant Variables
@section Variables that Never Change
-@vindex nil
-@vindex t
@kindex setting-constant
@cindex keyword symbol
+@cindex variable with constant value
+@cindex constant variables
+@cindex symbol that evaluates to itself
+@cindex symbol with constant value
In Emacs Lisp, certain symbols normally evaluate to themselves. These
include @code{nil} and @code{t}, as well as any symbol whose name starts
@end example
@defun keywordp object
-@tindex keywordp
function returns @code{t} if @var{object} is a symbol whose name
starts with @samp{:}, interned in the standard obarray, and returns
@code{nil} otherwise.
@code{max-lisp-eval-depth} provides another limit on depth of nesting.
@xref{Definition of max-lisp-eval-depth,, Eval}.
-The default value is 600. Entry to the Lisp debugger increases the
+The default value is 1000. Entry to the Lisp debugger increases the
value, if there is little room left, to make sure the debugger itself
has room to execute.
@end defvar
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
@item @dots{}-command
The value is a whole shell command.
-@item @samp{}-switches
+@item @dots{}-switches
The value specifies options for a command.
@end table
@end group
@group
-;; @r{Here the value of @code{abracadabra},}
+;; @r{Here, the value of @code{abracadabra},}
;; @r{which is @code{foo},}
;; @r{is the symbol whose value is examined.}
(let ((abracadabra 'foo))
@end quotation
@end defun
- 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 &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
-the argument yourself if that is what you want.
-@end defun
-
-Here's a scenario showing how to use @code{add-to-list}:
-
-@example
-(setq foo '(a b))
- @result{} (a b)
-
-(add-to-list 'foo 'c) ;; @r{Add @code{c}.}
- @result{} (c a b)
-
-(add-to-list 'foo 'b) ;; @r{No effect.}
- @result{} (c a b)
-
-foo ;; @r{@code{foo} was changed.}
- @result{} (c a b)
-@end example
-
- An equivalent expression for @code{(add-to-list '@var{var}
-@var{value})} is this:
-
-@example
-(or (member @var{value} @var{var})
- (setq @var{var} (cons @var{value} @var{var})))
-@end example
-
@node Variable Scoping
@section Scoping Rules for Variable Bindings
@end example
@cindex closures not available
- Some Lisp dialects have ``closures'', objects that are like functions
+ Some Lisp dialects have ``closures,'' objects that are like functions
but record additional variable bindings. Emacs Lisp does not have
closures.
@node Buffer-Local Variables
@section Buffer-Local Variables
-@cindex variables, buffer-local
+@cindex variable, buffer-local
@cindex buffer-local variables
Global and local variable bindings are found in most programming
@defun kill-all-local-variables
This function eliminates all the buffer-local variable bindings of the
-current buffer except for variables marked as ``permanent''. As a
+current buffer except for variables marked as ``permanent.'' As a
result, the buffer will see the default values of most variables.
This function also resets certain other information pertaining to the
@node Frame-Local Variables
@section Frame-Local Variables
+@cindex frame-local variables
Just as variables can have buffer-local bindings, they can also have
frame-local bindings. These bindings belong to one frame, and are in
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.
+specially in Emacs can be buffer-local, but can never be frame-local.
This command returns @var{variable}.
@end deffn
@node File Local Variables
@section File Local Variables
+@cindex 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.
+ A file can specify local variable values; Emacs uses these to create
+buffer-local bindings for those variables in the buffer visiting that
+file. @xref{File variables, , Local Variables in Files, emacs, The
+GNU Emacs Manual}, for basic information about file local variables.
+This section describes the functions and variables that affect
+processing of 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}.
+This variable controls whether to process file local variables.
+The possible values are:
+
+@table @asis
+@item @code{t} (the default)
+Set the safe variables, and query (once) about any unsafe variables.
+@item @code{:safe}
+Set only the safe variables and do not query.
+@item @code{:all}
+Set all the variables and do not query.
+@item @code{nil}
+Don't set any variables.
+@item anything else
+Query (once) about all the variables.
+@end table
@end defopt
@defun hack-local-variables &optional mode-only
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 @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-[0-9]}, 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}:
+visiting a file could take over your Emacs. Emacs takes several
+measures to prevent this.
+
+@cindex safe local variable
+ You can specify safe values for a variable with a
+@code{safe-local-variable} property. The property has to be
+a function of one argument; any value is safe if the function
+returns non-@code{nil} given that value. Many commonly encountered
+file variables standardly have @code{safe-local-variable} properties,
+including @code{fill-column}, @code{fill-prefix}, and
+@code{indent-tabs-mode}. For boolean-valued variables that are safe,
+use @code{booleanp} as the property value. Lambda expressions should
+be quoted so that @code{describe-variable} can display the predicate.
+
+@defopt safe-local-variable-values
+This variable provides another way to mark some variable values as
+safe. It is a list of cons cells @code{(@var{var} . @var{val})},
+where @var{var} is a variable name and @var{val} is a value which is
+safe for that variable.
+
+When Emacs asks the user whether or not to obey a set of file local
+variable specifications, the user can choose to mark them as safe.
+Doing so adds those variable/value pairs to
+@code{safe-local-variable-values}, and saves it to the user's custom
+file.
+@end defopt
+
+@defun safe-local-variable-p sym val
+This function returns non-@code{nil} if it is safe to give @var{sym}
+the value @var{val}, based on the above criteria.
+@end defun
+
+@c @cindex risky local variable Duplicates risky-local-variable
+ Some variables are considered @dfn{risky}. A 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} is considered risky. The
+variables @samp{font-lock-keywords}, @samp{font-lock-keywords}
+followed by a digit, and @samp{font-lock-syntactic-keywords} are also
+considered risky. Finally, any variable whose name has a
+non-@code{nil} @code{risky-local-variable} property is considered
+risky.
+
+@defun risky-local-variable-p sym
+This function returns non-@code{nil} if @var{sym} is a risky variable,
+based on the above criteria.
+@end defun
+
+ If a variable is risky, it will not be entered automatically into
+@code{safe-local-variable-values} as described above. Therefore,
+Emacs will always query before setting a risky variable, unless the
+user explicitly allows the setting by customizing
+@code{safe-local-variable-values} directly.
@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.
+completely 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.
the user what to do for each file. The default value is @code{maybe}.
@end defopt
+@defopt safe-local-eval-forms
+This variable holds a list of expressions that are safe to
+evaluate when found in the @samp{Eval:} ``variable'' in a file
+local variables list.
+@end defopt
+
+ If the expression is a function call and the function has a
+@code{safe-local-eval-function} property, the property value
+determines whether the expression is safe to evaluate. The property
+value can be a predicate to call to test the expression, a list of
+such predicates (it's safe if any predicate succeeds), or @code{t}
+(always safe provided the arguments are constant).
+
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
+@cindex variable aliases
It is sometimes useful to make two variables synonyms, so that both
variables always have the same value, and changing either one also
@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}.
+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}. The two aliased variable names always share the
+same value and the same bindings.
If the @var{docstring} argument is non-@code{nil}, it specifies the
documentation for @var{new-alias}; otherwise, the alias gets the same
@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}. A typical call has
-the form:
-
-@example
-(define-obsolete-variable-alias 'old-var 'new-var "22.1" "Doc.")
-@end example
-
-@noindent
-which is equivalent to the following two lines of code:
+makes it an alias for the variable @var{current-name}. It is
+equivalent to the following:
@example
-(defvaralias 'oldvar 'newvar "Doc.")
-(make-obsolete-variable 'old-var 'new-var "22.1")
+(defvaralias @var{obsolete-name} @var{current-name} @var{docstring})
+(make-obsolete-variable @var{obsolete-name} @var{current-name} @var{when})
@end example
@end defmac