diff options
Diffstat (limited to 'devdocs/elisp/file-local-variables.html')
| -rw-r--r-- | devdocs/elisp/file-local-variables.html | 42 |
1 files changed, 42 insertions, 0 deletions
diff --git a/devdocs/elisp/file-local-variables.html b/devdocs/elisp/file-local-variables.html new file mode 100644 index 00000000..299d389e --- /dev/null +++ b/devdocs/elisp/file-local-variables.html @@ -0,0 +1,42 @@ + <h3 class="section">File Local Variables</h3> <p>A file can specify local variable values; Emacs uses these to create buffer-local bindings for those variables in the buffer visiting that file. See <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/File-Variables.html#File-Variables">Local Variables in Files</a> in <cite>The GNU Emacs Manual</cite>, for basic information about file-local variables. This section describes the functions and variables that affect how file-local variables are processed. </p> <p>If a file-local variable could specify an arbitrary function or Lisp expression that would be called later, visiting a file could take over your Emacs. Emacs protects against this by automatically setting only those file-local variables whose specified values are known to be safe. Other file-local variables are set only if the user agrees. </p> <p>For additional safety, <code>read-circle</code> is temporarily bound to <code>nil</code> when Emacs reads file-local variables (see <a href="input-functions">Input Functions</a>). This prevents the Lisp reader from recognizing circular and shared Lisp structures (see <a href="circular-objects">Circular Objects</a>). </p> <dl> <dt id="enable-local-variables">User Option: <strong>enable-local-variables</strong> +</dt> <dd> +<p>This variable controls whether to process file-local variables. The possible values are: </p> <dl compact> <dt> +<code>t</code> (the default)</dt> <dd><p>Set the safe variables, and query (once) about any unsafe variables. </p></dd> <dt><code>:safe</code></dt> <dd><p>Set only the safe variables and do not query. </p></dd> <dt><code>:all</code></dt> <dd><p>Set all the variables and do not query. </p></dd> <dt><code>nil</code></dt> <dd><p>Don’t set any variables. </p></dd> <dt>anything else</dt> <dd><p>Query (once) about all the variables. </p></dd> </dl> </dd> +</dl> <dl> <dt id="inhibit-local-variables-regexps">Variable: <strong>inhibit-local-variables-regexps</strong> +</dt> <dd><p>This is a list of regular expressions. If a file has a name matching an element of this list, then it is not scanned for any form of file-local variable. For examples of why you might want to use this, see <a href="auto-major-mode">Auto Major Mode</a>. </p></dd> +</dl> <dl> <dt id="permanently-enabled-local-variables">Variable: <strong>permanently-enabled-local-variables</strong> +</dt> <dd><p>Some local variable settings will, by default, be heeded even if <code>enable-local-variables</code> is <code>nil</code>. By default, this is only the case for the <code>lexical-binding</code> local variable setting, but this can be controlled by using this variable, which is a list of symbols. </p></dd> +</dl> <dl> <dt id="hack-local-variables">Function: <strong>hack-local-variables</strong> <em>&optional handle-mode</em> +</dt> <dd> +<p>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</code> has its effect here. However, this function does not look for the ‘<samp>mode:</samp>’ local variable in the ‘<samp><span class="nolinebreak">-*-</span></samp>’ line. <code>set-auto-mode</code> does that, also taking <code>enable-local-variables</code> into account (see <a href="auto-major-mode">Auto Major Mode</a>). </p> <p>This function works by walking the alist stored in <code>file-local-variables-alist</code> and applying each local variable in turn. It calls <code>before-hack-local-variables-hook</code> and <code>hack-local-variables-hook</code> before and after applying the variables, respectively. It only calls the before-hook if the alist is non-<code>nil</code>; it always calls the other hook. This function ignores a ‘<samp>mode</samp>’ element if it specifies the same major mode as the buffer already has. </p> <p>If the optional argument <var>handle-mode</var> is <code>t</code>, then all this function does is return a symbol specifying the major mode, if the ‘<samp><span class="nolinebreak">-*-</span></samp>’ line or the local variables list specifies one, and <code>nil</code> otherwise. It does not set the mode or any other file-local variable. If <var>handle-mode</var> has any value other than <code>nil</code> or <code>t</code>, any settings of ‘<samp>mode</samp>’ in the ‘<samp><span class="nolinebreak">-*-</span></samp>’ line or the local variables list are ignored, and the other settings are applied. If <var>handle-mode</var> is <code>nil</code>, all the file local variables are set. </p> +</dd> +</dl> <dl> <dt id="file-local-variables-alist">Variable: <strong>file-local-variables-alist</strong> +</dt> <dd><p>This buffer-local variable holds the alist of file-local variable settings. Each element of the alist is of the form <code>(<var>var</var> . <var>value</var>)</code>, where <var>var</var> is a symbol of the local variable and <var>value</var> is its value. When Emacs visits a file, it first collects all the file-local variables into this alist, and then the <code>hack-local-variables</code> function applies them one by one. </p></dd> +</dl> <dl> <dt id="before-hack-local-variables-hook">Variable: <strong>before-hack-local-variables-hook</strong> +</dt> <dd><p>Emacs calls this hook immediately before applying file-local variables stored in <code>file-local-variables-alist</code>. </p></dd> +</dl> <dl> <dt id="hack-local-variables-hook">Variable: <strong>hack-local-variables-hook</strong> +</dt> <dd><p>Emacs calls this hook immediately after it finishes applying file-local variables stored in <code>file-local-variables-alist</code>. </p></dd> +</dl> <p>You can specify safe values for a variable with a <code>safe-local-variable</code> property. The property has to be a function of one argument; any value is safe if the function returns non-<code>nil</code> given that value. Many commonly-encountered file variables have <code>safe-local-variable</code> properties; these include <code>fill-column</code>, <code>fill-prefix</code>, and <code>indent-tabs-mode</code>. For boolean-valued variables that are safe, use <code>booleanp</code> as the property value. </p> <p>If you want to define <code>safe-local-variable</code> properties for variables defined in C source code, add the names and the properties of those variables to the list in the “Safe local variables” section of <samp>files.el</samp>. </p> <p>When defining a user option using <code>defcustom</code>, you can set its <code>safe-local-variable</code> property by adding the arguments <code>:safe <var>function</var></code> to <code>defcustom</code> (see <a href="variable-definitions">Variable Definitions</a>). However, a safety predicate defined using <code>:safe</code> will only be known once the package that contains the <code>defcustom</code> is loaded, which is often too late. As an alternative, you can use the autoload cookie (see <a href="autoload">Autoload</a>) to assign the option its safety predicate, like this: </p> <div class="lisp"> <pre class="lisp">;;;###autoload (put '<var>var</var> 'safe-local-variable '<var>pred</var>) +</pre> +</div> <p>The safe value definitions specified with <code>autoload</code> are copied into the package’s autoloads file (<samp>loaddefs.el</samp> for most packages bundled with Emacs), and are known to Emacs since the beginning of a session. </p> <dl> <dt id="safe-local-variable-values">User Option: <strong>safe-local-variable-values</strong> +</dt> <dd> +<p>This variable provides another way to mark some variable values as safe. It is a list of cons cells <code>(<var>var</var> . <var>val</var>)</code>, where <var>var</var> is a variable name and <var>val</var> is a value which is safe for that variable. </p> <p>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</code>, and saves it to the user’s custom file. </p> +</dd> +</dl> <dl> <dt id="ignored-local-variable-values">User Option: <strong>ignored-local-variable-values</strong> +</dt> <dd><p>If there are some values of particular local variables that you always want to ignore completely, you can use this variable. Its value has the same form as <code>safe-local-variable-values</code>; a file-local variable setting to the value that appears in the list will always be ignored when processing the local variables specified by the file. As with that variable, when Emacs queries the user about whether to obey file-local variables, the user can choose to ignore their particular values permanently, and that will alter this variable and save it to the user’s custom file. Variable-value pairs that appear in this variable take precedence over the same pairs in <code>safe-local-variable-values</code>. </p></dd> +</dl> <dl> <dt id="safe-local-variable-p">Function: <strong>safe-local-variable-p</strong> <em>sym val</em> +</dt> <dd><p>This function returns non-<code>nil</code> if it is safe to give <var>sym</var> the value <var>val</var>, based on the above criteria. </p></dd> +</dl> <p>Some variables are considered <em>risky</em>. If a variable is risky, it is never entered automatically into <code>safe-local-variable-values</code>; Emacs always queries before setting a risky variable, unless the user explicitly allows a value by customizing <code>safe-local-variable-values</code> directly. </p> <p>Any variable whose name has a non-<code>nil</code> <code>risky-local-variable</code> property is considered risky. When you define a user option using <code>defcustom</code>, you can set its <code>risky-local-variable</code> property by adding the arguments <code>:risky <var>value</var></code> to <code>defcustom</code> (see <a href="variable-definitions">Variable Definitions</a>). In addition, any variable whose name ends in any of ‘<samp>-command</samp>’, ‘<samp>-frame-alist</samp>’, ‘<samp>-function</samp>’, ‘<samp>-functions</samp>’, ‘<samp>-hook</samp>’, ‘<samp>-hooks</samp>’, ‘<samp>-form</samp>’, ‘<samp>-forms</samp>’, ‘<samp>-map</samp>’, ‘<samp>-map-alist</samp>’, ‘<samp>-mode-alist</samp>’, ‘<samp>-program</samp>’, or ‘<samp>-predicate</samp>’ is automatically considered risky. The variables ‘<samp>font-lock-keywords</samp>’, ‘<samp>font-lock-keywords</samp>’ followed by a digit, and ‘<samp>font-lock-syntactic-keywords</samp>’ are also considered risky. </p> <dl> <dt id="risky-local-variable-p">Function: <strong>risky-local-variable-p</strong> <em>sym</em> +</dt> <dd><p>This function returns non-<code>nil</code> if <var>sym</var> is a risky variable, based on the above criteria. </p></dd> +</dl> <dl> <dt id="ignored-local-variables">Variable: <strong>ignored-local-variables</strong> +</dt> <dd><p>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 completely ignored. </p></dd> +</dl> <p>The ‘<samp>Eval:</samp>’ “variable” is also a potential loophole, so Emacs normally asks for confirmation before handling it. </p> <dl> <dt id="enable-local-eval">User Option: <strong>enable-local-eval</strong> +</dt> <dd><p>This variable controls processing of ‘<samp>Eval:</samp>’ in ‘<samp>-*-</samp>’ lines or local variables lists in files being visited. A value of <code>t</code> means process them unconditionally; <code>nil</code> means ignore them; anything else means ask the user what to do for each file. The default value is <code>maybe</code>. </p></dd> +</dl> <dl> <dt id="safe-local-eval-forms">User Option: <strong>safe-local-eval-forms</strong> +</dt> <dd><p>This variable holds a list of expressions that are safe to evaluate when found in the ‘<samp>Eval:</samp>’ “variable” in a file local variables list. </p></dd> +</dl> <p>If the expression is a function call and the function has a <code>safe-local-eval-function</code> property, the property value determines whether the expression is safe to evaluate. The property value can be a predicate to call to test the expression, a list of such predicates (it’s safe if any predicate succeeds), or <code>t</code> (always safe provided the arguments are constant). </p> <p>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. </p><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/File-Local-Variables.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/File-Local-Variables.html</a> + </p> +</div> |