X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/18684a3ad1cfb3ccc6c7223aa4de8a9a90fce05b..99543e8b33e5914918a8caa9b1c5b5cf5400c57b:/lispref/variables.texi diff --git a/lispref/variables.texi b/lispref/variables.texi index c395702a40..1f26b56db8 100644 --- a/lispref/variables.texi +++ b/lispref/variables.texi @@ -1,7 +1,7 @@ @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 @@ -41,8 +41,8 @@ variable. * 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 @@ -260,8 +260,8 @@ These kinds of bindings work somewhat like ordinary local bindings, but they are localized depending on ``where'' you are in Emacs, rather than localized in time. -@anchor{Definition of max-specpdl-size} @defvar max-specpdl-size +@anchor{Definition of max-specpdl-size} @cindex variable limit error @cindex evaluation error @cindex infinite recursion @@ -568,7 +568,7 @@ though being declared using @code{defcustom}@footnote{They may also be 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 @@ -902,6 +902,62 @@ foo ;; @r{@code{foo} was changed.} (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 @@ -1428,8 +1484,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 @@ -1684,74 +1743,19 @@ bindings offer a way to handle these situations more robustly. If sufficient application is found for either of these two kinds of local bindings, we will provide it in a subsequent Emacs version. -@node Variable Aliases -@section 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 -changes the other. Whenever you change the name of a -variable---either because you realize its old name was not well -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 &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 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 - -@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 -(defvaralias 'foo 'bar) -(indirect-variable 'foo) - @result{} bar -(indirect-variable 'bar) - @result{} bar -(setq bar 2) -bar - @result{} 2 -@group -foo - @result{} 2 -@end group -(setq foo 0) -bar - @result{} 0 -foo - @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, , +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 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}. +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 @@ -1760,47 +1764,46 @@ 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. +@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 -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. +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 list could specify a function that would + 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 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. +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 -set by a file's local variables list. Any value specified -for one of these variables is ignored. +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 @@ -1815,7 +1818,8 @@ value whatsoever. normally asks for confirmation before handling it. @defopt enable-local-eval -This variable controls processing of @samp{Eval:} in local variables +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}. @@ -1823,8 +1827,93 @@ the user what to do for each file. The default value is @code{maybe}. 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. +properties from string values specified for file local variables. + +@node Variable Aliases +@section 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 +changes the other. Whenever you change the name of a +variable---either because you realize its old name was not well +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 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{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 + + 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 +(defvaralias 'foo 'bar) +(indirect-variable 'foo) + @result{} bar +(indirect-variable 'bar) + @result{} bar +(setq bar 2) +bar + @result{} 2 +@group +foo + @result{} 2 +@end group +(setq foo 0) +bar + @result{} 0 +foo + @result{} 0 +@end example @node Variables with Restricted Values @section Variables with Restricted Values