Buffer-Local Variables

It is often very useful to be able to give variables different values for different editor buffers -- most major modes need to record some buffer-specific information. Jade allows you to do this by giving a variable buffer-local bindings.

There are two strengths of buffer-local variables: you can either give a variable a buffer-local value in a single buffer, with other buffers treating the variable as normal, or a variable can be marked as being automatically buffer-local, each time the variable is set the current buffer's value of the variable is updated.

Each buffer maintains an alist of the symbols which have buffer-local values in the buffer and the actual values themselves, this alist may be read with the buffer-variables function.

When the value of a variable is referenced (via the symbol-value function) the current buffer's alist of local values is examined for a binding of the variable being referenced; if one is found that is the value of the variable, otherwise the default value (the value stored in the symbol's value cell) is used.

Setting a variable also searches for a buffer-local binding; if one exists its value is modified, not the default value. If the variable has previously been marked as being automatically buffer-local (by make-variable-buffer-local) a buffer-local binding is automatically created if one doesn't already exist.

Currently there is one main problem with buffer-local variables: they can't have temporary values bound to them (or rather, they can but I guarantee it won't work how you expect), so for the time being, don't try to bind local values (with let or let*) to a buffer-local variable.

Function: make-local-variable symbol

This function gives the variable symbol a buffer-local binding in the current buffer. The value of this binding will be the same as the variable's default value.

If symbol already has a buffer-local value in this buffer nothing happens.

Returns symbol.

Function: make-variable-buffer-local symbol

This function marks the variable symbol as being automatically buffer-local.

This means that any attempts at setting the value of symbol will actually set the current buffer's local value (if necessary a new buffer-local binding will be created in the buffer).

Returns symbol.

(make-variable-buffer-local 'buffer-modtime)
    => buffer-modtime

Function: default-value symbol

This function returns the default value of the variable symbol.

(setq foo 'default)
    => default
(make-local-variable 'foo)      ;Create a value in this buffer
    => foo
(setq foo 'local)
    => local
foo
    => local
(symbol-value 'foo)
    => local
(default-value 'foo)
    => default

Function: default-boundp symbol

Returns t if the variable symbol has a non-void default value.

Special Form: setq-default symbol form ...

Similar to the setq special form except that the default value of each variable is set. In non-buffer-local symbols there is no difference between setq and setq-default.

Function: set-default symbol new-value

Sets the default value of the variable symbol to new-value, then returns new-value.

Function: kill-local-variable symbol

This function removes the buffer-local binding of the variable symbol from the current buffer (if one exists) then returns symbol.

Function: kill-all-local-variables

This function removes all the buffer-local bindings associated with the current buffer. Subsequently, any buffer-local variables referenced while this buffer is current will use their default values.

The usual way to define an automatically buffer-local variable is to use defvar and make-variable-buffer-local, for example,

(defvar my-local-variable default-value
  "Doc string for my-local-variable.")
(make-variable-buffer-local 'my-local-variable)

Note that if you want to reference the value of a buffer-local variable in a buffer other than the current buffer, use the with-buffer special form (see section The Current Buffer). For example, the form,

(with-buffer other-buffer some-variable)

will produce the value of the variable some-variable in the buffer other-buffer.

Go to the first, previous, next, last section, table of contents.