42 |
* Buffer-Local Variables:: Variable values in effect only in one buffer. |
* Buffer-Local Variables:: Variable values in effect only in one buffer. |
43 |
* Frame-Local Variables:: Variable values in effect only in one frame. |
* Frame-Local Variables:: Variable values in effect only in one frame. |
44 |
* Future Local Variables:: New kinds of local values we might add some day. |
* Future Local Variables:: New kinds of local values we might add some day. |
|
* Variable Aliases:: Variables that are aliases for other variables. |
|
45 |
* File Local Variables:: Handling local variable lists in files. |
* File Local Variables:: Handling local variable lists in files. |
46 |
|
* Variable Aliases:: Variables that are aliases for other variables. |
47 |
* Variables with Restricted Values:: Non-constant variables whose value can |
* Variables with Restricted Values:: Non-constant variables whose value can |
48 |
@emph{not} be an arbitrary Lisp object. |
@emph{not} be an arbitrary Lisp object. |
49 |
@end menu |
@end menu |
1688 |
If sufficient application is found for either of these two kinds of |
If sufficient application is found for either of these two kinds of |
1689 |
local bindings, we will provide it in a subsequent Emacs version. |
local bindings, we will provide it in a subsequent Emacs version. |
1690 |
|
|
1691 |
|
@node File Local Variables |
1692 |
|
@section File Local Variables |
1693 |
|
|
1694 |
|
This section describes the functions and variables that affect |
1695 |
|
processing of file local variables. @xref{File variables, , |
1696 |
|
Local Variables in Files, emacs, The GNU Emacs Manual}, for basic |
1697 |
|
information about file local variables. |
1698 |
|
|
1699 |
|
@defopt enable-local-variables |
1700 |
|
This variable controls whether to process file local variables. A |
1701 |
|
value of @code{t} means process them unconditionally; @code{nil} means |
1702 |
|
ignore them; anything else means ask the user what to do for each |
1703 |
|
file. The default value is @code{t}. |
1704 |
|
@end defopt |
1705 |
|
|
1706 |
|
@defun hack-local-variables &optional mode-only |
1707 |
|
This function parses, and binds or evaluates as appropriate, any local |
1708 |
|
variables specified by the contents of the current buffer. The variable |
1709 |
|
@code{enable-local-variables} has its effect here. However, this |
1710 |
|
function does not look for the @samp{mode:} local variable in the |
1711 |
|
@w{@samp{-*-}} line. @code{set-auto-mode} does that, also taking |
1712 |
|
@code{enable-local-variables} into account (@pxref{Auto Major Mode}). |
1713 |
|
|
1714 |
|
If the optional argument @var{mode-only} is non-@code{nil}, then all |
1715 |
|
this function does is return @code{t} if the @w{@samp{-*-}} line or |
1716 |
|
the local variables list specifies a mode and @code{nil} otherwise. |
1717 |
|
It does not set the mode nor any other file local variable. |
1718 |
|
@end defun |
1719 |
|
|
1720 |
|
If a file local variable could specify a function that would |
1721 |
|
be called later, or an expression that would be executed later, simply |
1722 |
|
visiting a file could take over your Emacs. To prevent this, Emacs |
1723 |
|
takes care not to allow to set such file local variables. |
1724 |
|
|
1725 |
|
For one thing, any variable whose name ends in @samp{-command}, |
1726 |
|
@samp{-frame-alist}, @samp{-function}, @samp{-functions}, |
1727 |
|
@samp{-hook}, @samp{-hooks}, @samp{-form}, @samp{-forms}, @samp{-map}, |
1728 |
|
@samp{-map-alist}, @samp{-mode-alist}, @samp{-program}, or |
1729 |
|
@samp{-predicate} cannot be given a file local value. In general, |
1730 |
|
you should use such a name whenever it is appropriate for the |
1731 |
|
variable's meaning. The variables @samp{font-lock-keywords}, |
1732 |
|
@samp{font-lock-keywords-[0-9]}, and |
1733 |
|
@samp{font-lock-syntactic-keywords} cannot be given file local values either. |
1734 |
|
These rules can be overridden by giving the variable's |
1735 |
|
name a non-@code{nil} @code{safe-local-variable} property. If one |
1736 |
|
gives it a @code{safe-local-variable} property of @code{t}, then one |
1737 |
|
can give the variable any file local value. One can also give any |
1738 |
|
symbol, including the above, a @code{safe-local-variable} property |
1739 |
|
that is a function taking exactly one argument. In that case, giving |
1740 |
|
a variable with that name a file local value is only allowed if the |
1741 |
|
function returns non-@code{nil} when called with that value as |
1742 |
|
argument. |
1743 |
|
|
1744 |
|
In addition, any variable whose name has a non-@code{nil} |
1745 |
|
@code{risky-local-variable} property is also ignored. So are all |
1746 |
|
variables listed in @code{ignored-local-variables}: |
1747 |
|
|
1748 |
|
@defvar ignored-local-variables |
1749 |
|
This variable holds a list of variables that should not be given local |
1750 |
|
values by files. Any value specified for one of these variables is |
1751 |
|
ignored. |
1752 |
|
@end defvar |
1753 |
|
|
1754 |
|
@defun risky-local-variable-p sym &optional val |
1755 |
|
If @var{val} is non-@code{nil}, returns non-@code{nil} if giving |
1756 |
|
@var{sym} a file local value of @var{val} would be risky, for any of |
1757 |
|
the reasons stated above. If @var{val} is @code{nil} or omitted, only |
1758 |
|
returns @code{nil} if @var{sym} can be safely assigned any file local |
1759 |
|
value whatsoever. |
1760 |
|
@end defun |
1761 |
|
|
1762 |
|
The @samp{Eval:} ``variable'' is also a potential loophole, so Emacs |
1763 |
|
normally asks for confirmation before handling it. |
1764 |
|
|
1765 |
|
@defopt enable-local-eval |
1766 |
|
This variable controls processing of @samp{Eval:} in @samp{-*-} lines |
1767 |
|
or local variables |
1768 |
|
lists in files being visited. A value of @code{t} means process them |
1769 |
|
unconditionally; @code{nil} means ignore them; anything else means ask |
1770 |
|
the user what to do for each file. The default value is @code{maybe}. |
1771 |
|
@end defopt |
1772 |
|
|
1773 |
|
Text properties are also potential loopholes, since their values |
1774 |
|
could include functions to call. So Emacs discards all text |
1775 |
|
properties from string values specified for file local variables. |
1776 |
|
|
1777 |
@node Variable Aliases |
@node Variable Aliases |
1778 |
@section Variable Aliases |
@section Variable Aliases |
1779 |
|
|
1866 |
@result{} 0 |
@result{} 0 |
1867 |
@end example |
@end example |
1868 |
|
|
|
@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 |
|
|
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 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 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. |
|
|
|
|
|
@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. |
|
|
|
|
1869 |
@node Variables with Restricted Values |
@node Variables with Restricted Values |
1870 |
@section Variables with Restricted Values |
@section Variables with Restricted Values |
1871 |
|
|