comparison lispref/variables.texi @ 62365:69b2883d6502

(File Local Variables): Do not refer to the `-*-' line as a "local variables list". Add pxref.

62364:55c2e9c1c3cb

@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.

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 list 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

  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.
@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 @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

  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.

@node Variables with Restricted Values
@section Variables with Restricted Values

  Ordinary Lisp variables can be assigned any value that is a valid

62365:69b2883d6502

@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 @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

  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 @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 Variables with Restricted Values
@section Variables with Restricted Values

  Ordinary Lisp variables can be assigned any value that is a valid