X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/51cd2a8c642a6ade362424bc123f46f5cf6fe338..53ba8be73bc3546c067af32feeb377334d0fe872:/lispref/variables.texi?ds=sidebyside diff --git a/lispref/variables.texi b/lispref/variables.texi index 0f546af67b..f3e81c3ddd 100644 --- a/lispref/variables.texi +++ b/lispref/variables.texi @@ -1,8 +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, -@c 2000, 2003, 2004 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2002, +@c 2003, 2004, 2005, 2006 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/variables @node Variables, Functions, Control Structures, Top @@ -569,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 @@ -903,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 @@ -1589,8 +1644,7 @@ 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. +specially in Emacs can be buffer-local, but can never be frame-local. This command returns @var{variable}. @end deffn @@ -1698,9 +1752,9 @@ 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}. +value of @code{t} means to process them, querying the user if unsafe +variables are encountered; @code{nil} means ignore them; anything else +means to query the user for each file. The default value is @code{t}. @end defopt @defun hack-local-variables &optional mode-only @@ -1719,46 +1773,66 @@ It does not set the mode nor any other file local variable. 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. If the property is @code{t}, +setting that variable in a file is always considered safe, regardless +of the value used. If the property is a function of one argument, +then 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}. + +@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 + +@cindex 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. @@ -1822,19 +1896,12 @@ 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}. 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