# HG changeset patch # User Chong Yidong # Date 1139880125 0 # Node ID 68b8fcd1410c351fe53f935273518f7250acbe9b # Parent 4ea80a7bd411ed9881a513fe6de0dd228e534c45 * variables.texi (File Local Variables): Document new file local variable behavior. diff -r 4ea80a7bd411 -r 68b8fcd1410c lispref/ChangeLog --- a/lispref/ChangeLog Tue Feb 14 01:21:48 2006 +0000 +++ b/lispref/ChangeLog Tue Feb 14 01:22:05 2006 +0000 @@ -1,3 +1,8 @@ +2006-02-13 Chong Yidong + + * variables.texi (File Local Variables): Document new file local + variable behavior. + 2006-02-10 Kim F. Storm * eval.texi (Function Indirection): Add NOERROR to indirect-function. diff -r 4ea80a7bd411 -r 68b8fcd1410c lispref/variables.texi --- a/lispref/variables.texi Tue Feb 14 01:21:48 2006 +0000 +++ b/lispref/variables.texi Tue Feb 14 01:22:05 2006 +0000 @@ -1752,9 +1752,9 @@ @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 @@ -1773,46 +1773,70 @@ 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. +visiting a file could take over your Emacs. Emacs takes several +measures to prevent this. + +@cindex safe local variable + When Emacs encounters a file local variable whose safety is not +guaranteed, it asks the user whether or not to obey the file variable +specifications. If the user says no, Emacs ignores @emph{all} the +file variables specified in that file. A variable can be marked as +@dfn{safe} by setting its @code{safe-local-variable} property. If the +property is @code{t}, that variable is always considered safe, +regardless of the value assigned to it. The +@code{safe-local-variable} property can also be a a function taking +exactly one argument. In that case, Emacs considers it safe to give +the variable a certain value if the function returns non-@code{nil} +when called with that value as argument. Many commonly-encountered +file variables possess @code{safe-local-variable} by default, +including @code{fill-column}, @code{fill-prefix}, and +@code{indent-tabs-mode}. - For one thing, any variable whose name ends in any of -@samp{-command}, @samp{-frame-alist}, @samp{-function}, +@defopt safe-local-variable-values +This variable provides another way to mark variables as safe. It is a +list of cons cells @var{(var . val)}, where @var{var} is a variable +name and @var{val} is a value of that variable that is safe. + +When Emacs asks the user whether or not to obey a set of file variable +specifications, the user can choose to mark them as safe. This 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} 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. +@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. - 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}: +@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 it by editing @code{safe-local-variable-values} +via Customize. @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.