1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
|
<h4 class="subsection">Creating and Deleting Buffer-Local Bindings</h4> <dl> <dt id="make-local-variable">Command: <strong>make-local-variable</strong> <em>variable</em>
</dt> <dd>
<p>This function creates a buffer-local binding in the current buffer for <var>variable</var> (a symbol). Other buffers are not affected. The value returned is <var>variable</var>. </p> <p>The buffer-local value of <var>variable</var> starts out as the same value <var>variable</var> previously had. If <var>variable</var> was void, it remains void. </p> <div class="example"> <pre class="example">;; <span class="roman">In buffer ‘<samp>b1</samp>’:</span>
(setq foo 5) ; <span class="roman">Affects all buffers.</span>
⇒ 5
</pre>
<pre class="example">(make-local-variable 'foo) ; <span class="roman">Now it is local in ‘<samp>b1</samp>’.</span>
⇒ foo
</pre>
<pre class="example">foo ; <span class="roman">That did not change</span>
⇒ 5 ; <span class="roman">the value.</span>
</pre>
<pre class="example">(setq foo 6) ; <span class="roman">Change the value</span>
⇒ 6 ; <span class="roman">in ‘<samp>b1</samp>’.</span>
</pre>
<pre class="example">foo
⇒ 6
</pre>
<pre class="example">;; <span class="roman">In buffer ‘<samp>b2</samp>’, the value hasn’t changed.</span>
(with-current-buffer "b2"
foo)
⇒ 5
</pre>
</div> <p>Making a variable buffer-local within a <code>let</code>-binding for that variable does not work reliably, unless the buffer in which you do this is not current either on entry to or exit from the <code>let</code>. This is because <code>let</code> does not distinguish between different kinds of bindings; it knows only which variable the binding was made for. </p> <p>It is an error to make a constant or a read-only variable buffer-local. See <a href="constant-variables">Constant Variables</a>. </p> <p>If the variable is terminal-local (see <a href="multiple-terminals">Multiple Terminals</a>), this function signals an error. Such variables cannot have buffer-local bindings as well. </p> <p><strong>Warning:</strong> do not use <code>make-local-variable</code> for a hook variable. The hook variables are automatically made buffer-local as needed if you use the <var>local</var> argument to <code>add-hook</code> or <code>remove-hook</code>. </p>
</dd>
</dl> <dl> <dt id="setq-local">Macro: <strong>setq-local</strong> <em>&rest pairs</em>
</dt> <dd>
<p><var>pairs</var> is a list of variable and value pairs. This macro creates a buffer-local binding in the current buffer for each of the variables, and gives them a buffer-local value. It is equivalent to calling <code>make-local-variable</code> followed by <code>setq</code> for each of the variables. The variables should be unquoted symbols. </p> <div class="lisp"> <pre class="lisp">(setq-local var1 "value1"
var2 "value2")
</pre>
</div> </dd>
</dl> <dl> <dt id="make-variable-buffer-local">Command: <strong>make-variable-buffer-local</strong> <em>variable</em>
</dt> <dd>
<p>This function marks <var>variable</var> (a symbol) automatically buffer-local, so that any subsequent attempt to set it will make it local to the current buffer at the time. Unlike <code>make-local-variable</code>, with which it is often confused, this cannot be undone, and affects the behavior of the variable in all buffers. </p> <p>A peculiar wrinkle of this feature is that binding the variable (with <code>let</code> or other binding constructs) does not create a buffer-local binding for it. Only setting the variable (with <code>set</code> or <code>setq</code>), while the variable does not have a <code>let</code>-style binding that was made in the current buffer, does so. </p> <p>If <var>variable</var> does not have a default value, then calling this command will give it a default value of <code>nil</code>. If <var>variable</var> already has a default value, that value remains unchanged. Subsequently calling <code>makunbound</code> on <var>variable</var> will result in a void buffer-local value and leave the default value unaffected. </p> <p>The value returned is <var>variable</var>. </p> <p>It is an error to make a constant or a read-only variable buffer-local. See <a href="constant-variables">Constant Variables</a>. </p> <p><strong>Warning:</strong> Don’t assume that you should use <code>make-variable-buffer-local</code> for user-option variables, simply because users <em>might</em> want to customize them differently in different buffers. Users can make any variable local, when they wish to. It is better to leave the choice to them. </p> <p>The time to use <code>make-variable-buffer-local</code> is when it is crucial that no two buffers ever share the same binding. For example, when a variable is used for internal purposes in a Lisp program which depends on having separate values in separate buffers, then using <code>make-variable-buffer-local</code> can be the best solution. </p>
</dd>
</dl> <dl> <dt id="defvar-local">Macro: <strong>defvar-local</strong> <em>variable value &optional docstring</em>
</dt> <dd><p>This macro defines <var>variable</var> as a variable with initial value <var>value</var> and <var>docstring</var>, and marks it as automatically buffer-local. It is equivalent to calling <code>defvar</code> followed by <code>make-variable-buffer-local</code>. <var>variable</var> should be an unquoted symbol. </p></dd>
</dl> <dl> <dt id="local-variable-p">Function: <strong>local-variable-p</strong> <em>variable &optional buffer</em>
</dt> <dd><p>This returns <code>t</code> if <var>variable</var> is buffer-local in buffer <var>buffer</var> (which defaults to the current buffer); otherwise, <code>nil</code>. </p></dd>
</dl> <dl> <dt id="local-variable-if-set-p">Function: <strong>local-variable-if-set-p</strong> <em>variable &optional buffer</em>
</dt> <dd><p>This returns <code>t</code> if <var>variable</var> either has a buffer-local value in buffer <var>buffer</var>, or is automatically buffer-local. Otherwise, it returns <code>nil</code>. If omitted or <code>nil</code>, <var>buffer</var> defaults to the current buffer. </p></dd>
</dl> <dl> <dt id="buffer-local-value">Function: <strong>buffer-local-value</strong> <em>variable buffer</em>
</dt> <dd><p>This function returns the buffer-local binding of <var>variable</var> (a symbol) in buffer <var>buffer</var>. If <var>variable</var> does not have a buffer-local binding in buffer <var>buffer</var>, it returns the default value (see <a href="default-value">Default Value</a>) of <var>variable</var> instead. </p></dd>
</dl> <dl> <dt id="buffer-local-boundp">Function: <strong>buffer-local-boundp</strong> <em>variable buffer</em>
</dt> <dd><p>This returns non-<code>nil</code> if there’s either a buffer-local binding of <var>variable</var> (a symbol) in buffer <var>buffer</var>, or <var>variable</var> has a global binding. </p></dd>
</dl> <dl> <dt id="buffer-local-variables">Function: <strong>buffer-local-variables</strong> <em>&optional buffer</em>
</dt> <dd>
<p>This function returns a list describing the buffer-local variables in buffer <var>buffer</var>. (If <var>buffer</var> is omitted, the current buffer is used.) Normally, each list element has the form <code>(<var>sym</var> . <var>val</var>)</code>, where <var>sym</var> is a buffer-local variable (a symbol) and <var>val</var> is its buffer-local value. But when a variable’s buffer-local binding in <var>buffer</var> is void, its list element is just <var>sym</var>. </p> <div class="example"> <pre class="example">(make-local-variable 'foobar)
(makunbound 'foobar)
(make-local-variable 'bind-me)
(setq bind-me 69)
</pre>
<pre class="example">(setq lcl (buffer-local-variables))
;; <span class="roman">First, built-in variables local in all buffers:</span>
⇒ ((mark-active . nil)
(buffer-undo-list . nil)
(mode-name . "Fundamental")
…
</pre>
<pre class="example"> ;; <span class="roman">Next, non-built-in buffer-local variables.</span>
;; <span class="roman">This one is buffer-local and void:</span>
foobar
;; <span class="roman">This one is buffer-local and nonvoid:</span>
(bind-me . 69))
</pre>
</div> <p>Note that storing new values into the <small>CDR</small>s of cons cells in this list does <em>not</em> change the buffer-local values of the variables. </p>
</dd>
</dl> <dl> <dt id="kill-local-variable">Command: <strong>kill-local-variable</strong> <em>variable</em>
</dt> <dd>
<p>This function deletes the buffer-local binding (if any) for <var>variable</var> (a symbol) in the current buffer. As a result, the default binding of <var>variable</var> becomes visible in this buffer. This typically results in a change in the value of <var>variable</var>, since the default value is usually different from the buffer-local value just eliminated. </p> <p>If you kill the buffer-local binding of a variable that automatically becomes buffer-local when set, this makes the default value visible in the current buffer. However, if you set the variable again, that will once again create a buffer-local binding for it. </p> <p><code>kill-local-variable</code> returns <var>variable</var>. </p> <p>This function is a command because it is sometimes useful to kill one buffer-local variable interactively, just as it is useful to create buffer-local variables interactively. </p>
</dd>
</dl> <dl> <dt id="kill-all-local-variables">Function: <strong>kill-all-local-variables</strong>
</dt> <dd>
<p>This function eliminates all the buffer-local variable bindings of the current buffer except for variables marked as permanent and local hook functions that have a non-<code>nil</code> <code>permanent-local-hook</code> property (see <a href="setting-hooks">Setting Hooks</a>). As a result, the buffer will see the default values of most variables. </p> <p>This function also resets certain other information pertaining to the buffer: it sets the local keymap to <code>nil</code>, the syntax table to the value of <code>(standard-syntax-table)</code>, the case table to <code>(standard-case-table)</code>, and the abbrev table to the value of <code>fundamental-mode-abbrev-table</code>. </p> <p>The very first thing this function does is run the normal hook <code>change-major-mode-hook</code> (see below). </p> <p>Every major mode command begins by calling this function, which has the effect of switching to Fundamental mode and erasing most of the effects of the previous major mode. To ensure that this does its job, the variables that major modes set should not be marked permanent. </p> <p><code>kill-all-local-variables</code> returns <code>nil</code>. </p>
</dd>
</dl> <dl> <dt id="change-major-mode-hook">Variable: <strong>change-major-mode-hook</strong>
</dt> <dd>
<p>The function <code>kill-all-local-variables</code> runs this normal hook before it does anything else. This gives major modes a way to arrange for something special to be done if the user switches to a different major mode. It is also useful for buffer-specific minor modes that should be forgotten if the user changes the major mode. </p> <p>For best results, make this variable buffer-local, so that it will disappear after doing its job and will not interfere with the subsequent major mode. See <a href="hooks">Hooks</a>. </p>
</dd>
</dl> <p>A buffer-local variable is <em>permanent</em> if the variable name (a symbol) has a <code>permanent-local</code> property that is non-<code>nil</code>. Such variables are unaffected by <code>kill-all-local-variables</code>, and their local bindings are therefore not cleared by changing major modes. Permanent locals are appropriate for data pertaining to where the file came from or how to save it, rather than with how to edit the contents. </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/Creating-Buffer_002dLocal.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Creating-Buffer_002dLocal.html</a>
</p>
</div>
|
