-\1f
-File: lispref.info, Node: Intro to Buffer-Local, Next: Creating Buffer-Local, Up: Buffer-Local Variables
-
-Introduction to Buffer-Local Variables
---------------------------------------
-
- A buffer-local variable has a buffer-local binding associated with a
-particular buffer. The binding is in effect when that buffer is
-current; otherwise, it is not in effect. If you set the variable while
-a buffer-local binding is in effect, the new value goes in that binding,
-so the global binding is unchanged; this means that the change is
-visible in that buffer alone.
-
- A variable may have buffer-local bindings in some buffers but not in
-others. The global binding is shared by all the buffers that don't have
-their own bindings. Thus, if you set the variable in a buffer that does
-not have a buffer-local binding for it, the new value is visible in all
-buffers except those with buffer-local bindings. (Here we are assuming
-that there are no `let'-style local bindings to complicate the issue.)
-
- The most common use of buffer-local bindings is for major modes to
-change variables that control the behavior of commands. For example, C
-mode and Lisp mode both set the variable `paragraph-start' to specify
-that only blank lines separate paragraphs. They do this by making the
-variable buffer-local in the buffer that is being put into C mode or
-Lisp mode, and then setting it to the new value for that mode.
-
- The usual way to make a buffer-local binding is with
-`make-local-variable', which is what major mode commands use. This
-affects just the current buffer; all other buffers (including those yet
-to be created) continue to share the global value.
-
- A more powerful operation is to mark the variable as "automatically
-buffer-local" by calling `make-variable-buffer-local'. You can think
-of this as making the variable local in all buffers, even those yet to
-be created. More precisely, the effect is that setting the variable
-automatically makes the variable local to the current buffer if it is
-not already so. All buffers start out by sharing the global value of
-the variable as usual, but any `setq' creates a buffer-local binding
-for the current buffer. The new value is stored in the buffer-local
-binding, leaving the (default) global binding untouched. The global
-value can no longer be changed with `setq'; you need to use
-`setq-default' to do that.
-
- Local variables in a file you edit are also represented by
-buffer-local bindings for the buffer that holds the file within XEmacs.
-*Note Auto Major Mode::.
-
-\1f
-File: lispref.info, Node: Creating Buffer-Local, Next: Default Value, Prev: Intro to Buffer-Local, Up: Buffer-Local Variables
-
-Creating and Deleting Buffer-Local Bindings
--------------------------------------------
-
- - Command: make-local-variable VARIABLE
- This function creates a buffer-local binding in the current buffer
- for VARIABLE (a symbol). Other buffers are not affected. The
- value returned is VARIABLE.
-
- The buffer-local value of VARIABLE starts out as the same value
- VARIABLE previously had. If VARIABLE was void, it remains void.
-
- ;; In buffer `b1':
- (setq foo 5) ; Affects all buffers.
- => 5
- (make-local-variable 'foo) ; Now it is local in `b1'.
- => foo
- foo ; That did not change
- => 5 ; the value.
- (setq foo 6) ; Change the value
- => 6 ; in `b1'.
- foo
- => 6
-
- ;; In buffer `b2', the value hasn't changed.
- (save-excursion
- (set-buffer "b2")
- foo)
- => 5
-
- Making a variable buffer-local within a `let'-binding for that
- variable does not work. This is because `let' does not distinguish
- between different kinds of bindings; it knows only which variable
- the binding was made for.
-
- *Please note:* do not use `make-local-variable' for a hook
- variable. Instead, use `make-local-hook'. *Note Hooks::.
-
- - Command: make-variable-buffer-local VARIABLE
- This function marks VARIABLE (a symbol) automatically
- buffer-local, so that any subsequent attempt to set it will make it
- local to the current buffer at the time.
-
- The value returned is VARIABLE.
-
- - Function: local-variable-p VARIABLE &optional BUFFER
- This returns `t' if VARIABLE is buffer-local in buffer BUFFER
- (which defaults to the current buffer); otherwise, `nil'.
-
- - Function: buffer-local-variables &optional BUFFER
- This function returns a list describing the buffer-local variables
- in buffer BUFFER. It returns an association list (*note
- Association Lists::.) in which each association contains one
- buffer-local variable and its value. When a buffer-local variable
- is void in BUFFER, then it appears directly in the resulting list.
- If BUFFER is omitted, the current buffer is used.
-
- (make-local-variable 'foobar)
- (makunbound 'foobar)
- (make-local-variable 'bind-me)
- (setq bind-me 69)
- (setq lcl (buffer-local-variables))
- ;; First, built-in variables local in all buffers:
- => ((mark-active . nil)
- (buffer-undo-list nil)
- (mode-name . "Fundamental")
- ...
- ;; Next, non-built-in local variables.
- ;; This one is local and void:
- foobar
- ;; This one is local and nonvoid:
- (bind-me . 69))
-
- Note that storing new values into the CDRs of cons cells in this
- list does *not* change the local values of the variables.
-
- - Command: kill-local-variable VARIABLE
- This function deletes the buffer-local binding (if any) for
- VARIABLE (a symbol) in the current buffer. As a result, the
- global (default) binding of VARIABLE becomes visible in this
- buffer. Usually this results in a change in the value of
- VARIABLE, since the global value is usually different from the
- buffer-local value just eliminated.
-
- If you kill the local binding of a variable that automatically
- becomes local when set, this makes the global value visible in the
- current buffer. However, if you set the variable again, that will
- once again create a local binding for it.
-
- `kill-local-variable' returns VARIABLE.
-
- 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.
-
- - Function: kill-all-local-variables
- This function eliminates all the buffer-local variable bindings of
- the current buffer except for variables marked as "permanent". As
- a result, the buffer will see the default values of most variables.
-
- This function also resets certain other information pertaining to
- the buffer: it sets the local keymap to `nil', the syntax table to
- the value of `standard-syntax-table', and the abbrev table to the
- value of `fundamental-mode-abbrev-table'.
-
- 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.
-
- `kill-all-local-variables' returns `nil'.
-
- A local variable is "permanent" if the variable name (a symbol) has a
-`permanent-local' property that is non-`nil'. 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.
-