comparison lispref/variables.texi @ 21682:90da2489c498

*** empty log message ***

21681:11eafe90b842

* Accessing Variables::   Examining values of variables whose names
                            are known only at run time.
* Setting Variables::     Storing new values in variables.
* Variable Scoping::      How Lisp chooses among local and global values.
* Buffer-Local Variables::  Variable values in effect only in one buffer.
@end menu

@node Global Variables
@section Global Variables
@cindex global variable

@end example

@noindent
assuming the @code{setq} form shown above has already been executed.

  If you do another @code{setq}, the new value replaces the old one:

@example
@group
x
     @result{} (a b)

@section Variables That Never Change
@vindex nil
@vindex t
@kindex setting-constant

  In Emacs Lisp, certain symbols normally evaluate to themselves.
These include @code{nil} and @code{t}, as well as any symbol whose
name starts with @samp{:}.

  The symbols @code{nil} and @code{t} @emph{always} evaluate to
themselves.  These symbols cannot be rebound, nor can their values be
changed.  Any attempt to change the value of @code{nil} or @code{t}
signals a @code{setting-constant} error.

@example
@group
nil @equiv{} 'nil
     @result{} nil

@group
(setq nil 500)
@error{} Attempt to set constant symbol: nil
@end group
@end example

@node Local Variables
@section Local Variables
@cindex binding local variables
@cindex local variables
@cindex local binding
@cindex global binding

  Global variables have values that last until explicitly superseded
with new values.  Sometimes it is useful to create variable values that
exist temporarily---only while within a certain part of the program.
These values are called @dfn{local}, and the variables so used are
called @dfn{local variables}.

  For example, when a function is called, its argument variables receive
new local values that last until the function exits.  The @code{let}

previous value is @dfn{shadowed} and @dfn{not visible}.  Both global and
local values may be shadowed (@pxref{Scope}).

  If you set a variable (such as with @code{setq}) while it is local,
this replaces the local value; it does not alter the global value, or
previous local values that are shadowed.  To model this behavior, we
speak of a @dfn{local binding} of the variable as well as a local value.

  The local binding is a conceptual place that holds a local value.
Entry to a function, or a special form such as @code{let}, creates the
local binding; exit from the function or from the @code{let} removes the

@cindex current binding
  A variable can have more than one local binding at a time (for
example, if there are nested @code{let} forms that bind it).  In such a
case, the most recently created local binding that still exists is the
@dfn{current binding} of the variable.  (This is called @dfn{dynamic
scoping}; see @ref{Variable Scoping}.)  If there are no local bindings,
the variable's global binding is its current binding.  We also call the
current binding the @dfn{most-local existing binding}, for emphasis.
Ordinary evaluation of a symbol always returns the value of its current
binding.

  The special forms @code{let} and @code{let*} exist to create
local bindings.

@defspec let (bindings@dots{}) forms@dots{}

@code{makunbound} returns @var{symbol}.

@example
@group
(makunbound 'x)      ; @r{Make the global value}
                     ;   @r{of @code{x} void.}
     @result{} x
@end group
@group
x
@error{} Symbol's value as variable is void: x

If @var{symbol} is locally bound, @code{makunbound} affects the most
local existing binding.  This is the only way a symbol can have a void
local binding, since all the constructs that create local bindings
create them with values.  In this case, the voidness lasts at most as
long as the binding does; when the binding is removed due to exit from
the construct that made it, the previous or global binding is reexposed
as usual, and the variable is no longer void unless the newly reexposed
binding was void all along.

@smallexample
@group
(setq x 1)               ; @r{Put a value in the global binding.}
     @result{} 1

stored in the symbol's @code{variable-documentation} property.  The
Emacs help functions (@pxref{Documentation}) look for this property.

If the first character of @var{doc-string} is @samp{*}, it means that
this variable is considered a user option.  This lets users set the
variable conventiently using the commands @code{set-variable} and
@code{edit-options}.  However, it is better to use @code{defcustom}
instead of @code{defvar}, for user option variables, to specify
customization information.  @xref{Customization}.

Here are some examples.  This form defines @code{foo} but does not
initialize it:

@end example

@noindent
This method has several benefits.  First, if the user quits while
loading the file, the variable is either still uninitialized or
initialized properly, never in-between.  If it is uninitialized,
reloading the file will initialize it properly.  Second, reloading the
file once the variable is initialized will not alter it; that is
important if the user has run hooks to alter part of the contents (such
as, to rebind keys).  Third, evaluating the @code{defvar} form with
@kbd{C-M-x} @emph{will} reinitialize the map completely.

  (define-key my-mode-map "\C-c\C-a" 'my-command)
  @dots{})
@end example

@noindent
This code sets the variable, then alters it, but only if the variable
had been @code{ni}.  If the user quits just after the @code{setq}, that
leaves the variable neither correctly initialized nor void nor
@code{nil}.  Once that happens, reloading the file will not initialize
the variable; it will remain incomplete.

@node Accessing Variables
@section Accessing Variable Values

  The usual way to reference a variable is to write the symbol which

(symbol-value 'abracadabra)
     @result{} 5
@end group
@end example

A @code{void-variable} error is signaled if @var{symbol} has neither a
local binding nor a global one.
@end defun

@node Setting Variables
@section How to Alter a Variable Value

value of @var{symbol} had better be a list already before the call.

The argument @var{symbol} is not implicitly quoted; @code{add-to-list}
is an ordinary function, like @code{set} and unlike @code{setq}.  Quote
the argument yourself if that is what you want.

Here's a scenario showing how to use @code{add-to-list}:

@example
(setq foo '(a b))

     @result{} (c a b)

foo                       ;; @r{@code{foo} was changed.}
     @result{} (c a b)
@end example
@end defun

  An equivalent expression for @code{(add-to-list '@var{var}
@var{value})} is this:

@example

  A simple sample implementation (which is not how Emacs Lisp actually
works) may help you understand dynamic binding.  This technique is
called @dfn{deep binding} and was used in early Lisp systems.

  Suppose there is a stack of bindings: variable-value pairs.  At entry
to a function or to a @code{let} form, we can push bindings onto the stack
for the arguments or local variables created there.  We can pop those
bindings from the stack at exit from the binding construct.

  We can find the value of a variable by searching the stack from top to
bottom for a binding for that variable; the value from that binding is
the value of the variable.  To set the variable, we search for the
current binding, then store the new value into that binding.

@section Buffer-Local Variables
@cindex variables, buffer-local
@cindex buffer-local variables

  Global and local variable bindings are found in most programming
languages in one form or another.  Emacs also supports another, unusual
kind of variable binding: @dfn{buffer-local} bindings, which apply only
to one buffer.  Emacs Lisp is meant for programming editing commands,
and having different values for a variable in different buffers is an
important customization method.  (A few variables have bindings that
are local to a given X terminal; see @ref{Multiple Displays}.)

@menu
* Intro to Buffer-Local::      Introduction and concepts.
* Creating Buffer-Local::      Creating and destroying buffer-local bindings.
* Default Value::              The default value is seen in buffers
                                 that don't have their own local values.
@end menu

@node Intro to Buffer-Local
@subsection Introduction to Buffer-Local Variables

specific buffer, is called the @dfn{default binding}.  In most cases,
this is the global binding.

  A variable can have buffer-local bindings in some buffers but not in
other buffers.  The default binding is shared by all the buffers that
don't have their own bindings for the variable.  If you set the variable
in a buffer that does not have a buffer-local binding for it, this sets
the default binding, so the new value is visible in all the buffers that
see the default binding.

  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 @code{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
@code{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 default value.

@cindex automatically buffer-local
  A more powerful operation is to mark the variable as
@dfn{automatically buffer-local} by calling
@code{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 default value of the variable as usual,
but any @code{setq} creates a buffer-local binding for the current
buffer.  The new value is stored in the buffer-local binding, leaving
the default binding untouched.  The default value can no longer be
changed with @code{setq} in this buffer; you need to use
@code{setq-default} to do that.

  @strong{Warning:} When a variable has buffer-local values in one or
more buffers, you can get Emacs very confused by binding the variable
with @code{let}, changing to a different current buffer in which a
different binding is in effect, and then exiting the @code{let}.  This

  Note that references to @code{foo} in @var{body} access the
buffer-local binding of buffer @samp{b}.

  When a file specifies local variable values, these become buffer-local
values when you visit the file.  @xref{Auto Major Mode}.

@node Creating Buffer-Local
@subsection Creating and Deleting Buffer-Local Bindings

@deffn Command make-local-variable variable

     @result{} 5
@end group
@end example

Making a variable buffer-local within a @code{let}-binding for that
variable does not work.  This is because @code{let} does not distinguish
between different kinds of bindings; it knows only which variable the
binding was made for.

If the variable is terminal-local, this function signals an error.  Such
variables cannot have buffer-local bindings as well.  @xref{Multiple
Displays}.

@deffn Command make-variable-buffer-local variable
This function marks @var{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 @var{variable}.

@strong{Note:} It is a mistake to use @code{make-variable-buffer-local}
for user-option variables, simply because users @emph{might} want to
customize them differently in different buffers.  Users can make any
variable local, when they wish to.

The main use of @code{make-variable-buffer-local} is when a variable is
used for internal purposes, and the Lisp program depends on having
separate values in separate buffers.
@end deffn

@defun local-variable-p variable &optional buffer
This returns @code{t} if @var{variable} is buffer-local in buffer
@var{buffer} (which defaults to the current buffer); otherwise,
@code{nil}.
@end defun

@defun buffer-local-variables &optional buffer
This function returns a list describing the buffer-local variables in
buffer @var{buffer}.  It returns an association list (@pxref{Association
Lists}) in which each association contains one buffer-local variable and
its value.  When a buffer-local variable is void in @var{buffer}, then
it appears directly in the resulting list.  If @var{buffer} is omitted,
the current buffer is used.

@example
@group
(make-local-variable 'foobar)
(makunbound 'foobar)

buffer: it sets the local keymap to @code{nil}, the syntax table to the
value of @code{standard-syntax-table}, and the abbrev table to the value
of @code{fundamental-mode-abbrev-table}.

The very first thing this function does is run the normal hook
@code{change-major-mode-hook} (@pxref{Major Mode Conventions}).

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.

@code{kill-all-local-variables} returns @code{nil}.
@end defun

@c Emacs 19 feature
@cindex permanent local variable
A buffer-local variable is @dfn{permanent} if the variable name (a
symbol) has a @code{permanent-local} property that is non-@code{nil}.

@subsection The Default Value of a Buffer-Local Variable
@cindex default value

  The global value of a variable with buffer-local bindings is also
called the @dfn{default} value, because it is the value that is in
effect except when specifically overridden.

  The functions @code{default-value} and @code{setq-default} access and
change a variable's default value regardless of whether the current
buffer has a buffer-local binding.  For example, you could use
@code{setq-default} to change the default setting of

this variable.

@c Emacs 19 feature
  The special forms @code{defvar} and @code{defconst} also set the
default value (if they set the variable at all), rather than any
buffer-local value.

@defun default-value symbol
This function returns @var{symbol}'s default value.  This is the value
that is seen in buffers that do not have their own values for this
variable.  If @var{symbol} is not buffer-local, this is equivalent to
@code{symbol-value} (@pxref{Accessing Variables}).
@end defun

@c Emacs 19 feature
@defun default-boundp symbol
The function @code{default-boundp} tells you whether @var{symbol}'s

current buffer sees.

@example
@group
;; @r{In buffer @samp{foo}:}
(make-local-variable 'local)
     @result{} local
@end group
@group
(setq local 'value-in-foo)
     @result{} value-in-foo
@end group
@group
(setq-default local 'new-default)
     @result{} new-default
@end group
@group
local
     @result{} value-in-foo
@end group
@group
(default-value 'local)
     @result{} new-default
@end group

@group
;; @r{In (the new) buffer @samp{bar}:}
local
     @result{} new-default
@end group
@group
(default-value 'local)
     @result{} new-default
@end group
@group
(setq local 'another-default)
     @result{} another-default
@end group
@group
(default-value 'local)
     @result{} another-default
@end group

@group
;; @r{Back in buffer @samp{foo}:}
local
     @result{} value-in-foo
(default-value 'local)
     @result{} another-default
@end group
@end example
@end defspec

(default-value 'a)
     @result{} 23
@end group
@end example
@end defun

21682:90da2489c498

* Accessing Variables::   Examining values of variables whose names
                            are known only at run time.
* Setting Variables::     Storing new values in variables.
* Variable Scoping::      How Lisp chooses among local and global values.
* Buffer-Local Variables::  Variable values in effect only in one buffer.
* Frame-Local Variables::   Variable values in effect only in one frame.
* Future Local Variables::  New kinds of local values we might add some day.
@end menu

@node Global Variables
@section Global Variables
@cindex global variable

@end example

@noindent
assuming the @code{setq} form shown above has already been executed.

  If you do set the same variable again, the new value replaces the old
one:

@example
@group
x
     @result{} (a b)

@section Variables That Never Change
@vindex nil
@vindex t
@kindex setting-constant

  In Emacs Lisp, certain symbols normally evaluate to themselves.  These
include @code{nil} and @code{t}, as well as any symbol whose name starts
with @samp{:}.  These symbols cannot be rebound, nor can their values be
changed.  Any attempt to set or bind @code{nil} or @code{t} signals a
@code{setting-constant} error.  The same is true for a symbol whose name
starts with @samp{:}, except that you are allowed to set such symbol to
itself.

@example
@group
nil @equiv{} 'nil
     @result{} nil

@group
(setq nil 500)
@error{} Attempt to set constant symbol: nil
@end group
@end example

@tindex keyword-symbols-constant-flag
@defvar keyword-symbols-constant-flag
If this variable is @code{nil}, you are allowed to set and bind symbols
whose names start with @samp{:} as you wish.  This is to make it
possible to run old Lisp programs which do that.
@end defvar

@node Local Variables
@section Local Variables
@cindex binding local variables
@cindex local variables
@cindex local binding
@cindex global binding

  Global variables have values that last until explicitly superseded
with new values.  Sometimes it is useful to create variable values that
exist temporarily---only until a certain part of the program finishes.
These values are called @dfn{local}, and the variables so used are
called @dfn{local variables}.

  For example, when a function is called, its argument variables receive
new local values that last until the function exits.  The @code{let}

previous value is @dfn{shadowed} and @dfn{not visible}.  Both global and
local values may be shadowed (@pxref{Scope}).

  If you set a variable (such as with @code{setq}) while it is local,
this replaces the local value; it does not alter the global value, or
previous local values, that are shadowed.  To model this behavior, we
speak of a @dfn{local binding} of the variable as well as a local value.

  The local binding is a conceptual place that holds a local value.
Entry to a function, or a special form such as @code{let}, creates the
local binding; exit from the function or from the @code{let} removes the

@cindex current binding
  A variable can have more than one local binding at a time (for
example, if there are nested @code{let} forms that bind it).  In such a
case, the most recently created local binding that still exists is the
@dfn{current binding} of the variable.  (This rule is called
@dfn{dynamic scoping}; see @ref{Variable Scoping}.)  If there are no
local bindings, the variable's global binding is its current binding.
We sometimes call the current binding the @dfn{most-local existing
binding}, for emphasis.  Ordinary evaluation of a symbol always returns
the value of its current binding.

  The special forms @code{let} and @code{let*} exist to create
local bindings.

@defspec let (bindings@dots{}) forms@dots{}

@code{makunbound} returns @var{symbol}.

@example
@group
(makunbound 'x)      ; @r{Make the global value of @code{x} void.}
     @result{} x
@end group
@group
x
@error{} Symbol's value as variable is void: x

If @var{symbol} is locally bound, @code{makunbound} affects the most
local existing binding.  This is the only way a symbol can have a void
local binding, since all the constructs that create local bindings
create them with values.  In this case, the voidness lasts at most as
long as the binding does; when the binding is removed due to exit from
the construct that made it, the previous local or global binding is
reexposed as usual, and the variable is no longer void unless the newly
reexposed binding was void all along.

@smallexample
@group
(setq x 1)               ; @r{Put a value in the global binding.}
     @result{} 1

stored in the symbol's @code{variable-documentation} property.  The
Emacs help functions (@pxref{Documentation}) look for this property.

If the first character of @var{doc-string} is @samp{*}, it means that
this variable is considered a user option.  This lets users set the
variable conveniently using the commands @code{set-variable} and
@code{edit-options}.  However, it is better to use @code{defcustom}
instead of @code{defvar} for user option variables, so you can specify
customization information.  @xref{Customization}.

Here are some examples.  This form defines @code{foo} but does not
initialize it:

@end example

@noindent
This method has several benefits.  First, if the user quits while
loading the file, the variable is either still uninitialized or
initialized properly, never in-between.  If it is still uninitialized,
reloading the file will initialize it properly.  Second, reloading the
file once the variable is initialized will not alter it; that is
important if the user has run hooks to alter part of the contents (such
as, to rebind keys).  Third, evaluating the @code{defvar} form with
@kbd{C-M-x} @emph{will} reinitialize the map completely.

  (define-key my-mode-map "\C-c\C-a" 'my-command)
  @dots{})
@end example

@noindent
This code sets the variable, then alters it, but it does so in more than
one step.  If the user quits just after the @code{setq}, that leaves the
variable neither correctly initialized nor void nor @code{nil}.  Once
that happens, reloading the file will not initialize the variable; it
will remain incomplete.

@node Accessing Variables
@section Accessing Variable Values

  The usual way to reference a variable is to write the symbol which

(symbol-value 'abracadabra)
     @result{} 5
@end group
@end example

A @code{void-variable} error is signaled if the current binding of
@var{symbol} is void.
@end defun

@node Setting Variables
@section How to Alter a Variable Value

value of @var{symbol} had better be a list already before the call.

The argument @var{symbol} is not implicitly quoted; @code{add-to-list}
is an ordinary function, like @code{set} and unlike @code{setq}.  Quote
the argument yourself if that is what you want.
@end defun

Here's a scenario showing how to use @code{add-to-list}:

@example
(setq foo '(a b))

     @result{} (c a b)

foo                       ;; @r{@code{foo} was changed.}
     @result{} (c a b)
@end example

  An equivalent expression for @code{(add-to-list '@var{var}
@var{value})} is this:

@example

  A simple sample implementation (which is not how Emacs Lisp actually
works) may help you understand dynamic binding.  This technique is
called @dfn{deep binding} and was used in early Lisp systems.

  Suppose there is a stack of bindings, which are variable-value pairs.
At entry to a function or to a @code{let} form, we can push bindings
onto the stack for the arguments or local variables created there.  We
can pop those bindings from the stack at exit from the binding
construct.

  We can find the value of a variable by searching the stack from top to
bottom for a binding for that variable; the value from that binding is
the value of the variable.  To set the variable, we search for the
current binding, then store the new value into that binding.

@section Buffer-Local Variables
@cindex variables, buffer-local
@cindex buffer-local variables

  Global and local variable bindings are found in most programming
languages in one form or another.  Emacs also supports additional,
unusual kinds of variable binding: @dfn{buffer-local} bindings, which
apply only in one buffer, and frame-local bindings, which apply only in
one frame.  Having different values for a variable in different buffers
and/or frames is an important customization method.

  This section describes buffer-local bindings; for frame-local
bindings, see the following section, @ref{Frame-Local Variables}.  (A few
variables have bindings that are local to a X terminal; see
@ref{Multiple Displays}.)

@menu
* Intro to Buffer-Local::      Introduction and concepts.
* Creating Buffer-Local::      Creating and destroying buffer-local bindings.
* Default Value::              The default value is seen in buffers
                                 that don't have their own buffer-local values.
@end menu

@node Intro to Buffer-Local
@subsection Introduction to Buffer-Local Variables

specific buffer, is called the @dfn{default binding}.  In most cases,
this is the global binding.

  A variable can have buffer-local bindings in some buffers but not in
other buffers.  The default binding is shared by all the buffers that
don't have their own bindings for the variable.  (This includes all
newly created buffers.)  If you set the variable in a buffer that does
not have a buffer-local binding for it, this sets the default binding
(assuming there are no frame-local bindings to complicate the matter),
so the new value is visible in all the buffers that see the default
binding.

  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 @code{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.  @xref{Major Modes}.

  The usual way to make a buffer-local binding is with
@code{make-local-variable}, which is what major mode commands typically
use.  This affects just the current buffer; all other buffers (including
those yet to be created) will continue to share the default value unless
they are explicitly given their own buffer-local bindings.

@cindex automatically buffer-local
  A more powerful operation is to mark the variable as
@dfn{automatically buffer-local} by calling
@code{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 default value of the variable as usual,
but setting the variable creates a buffer-local binding for the current
buffer.  The new value is stored in the buffer-local binding, leaving
the default binding untouched.  This means that the default value cannot
be changed with @code{setq} in any buffer; the only way to change it is
with @code{setq-default}.

  @strong{Warning:} When a variable has buffer-local values in one or
more buffers, you can get Emacs very confused by binding the variable
with @code{let}, changing to a different current buffer in which a
different binding is in effect, and then exiting the @code{let}.  This

  Note that references to @code{foo} in @var{body} access the
buffer-local binding of buffer @samp{b}.

  When a file specifies local variable values, these become buffer-local
values when you visit the file.  @xref{File Variables,,, emacs, The
GNU Emacs Manual}.

@node Creating Buffer-Local
@subsection Creating and Deleting Buffer-Local Bindings

@deffn Command make-local-variable variable

     @result{} 5
@end group
@end example

Making a variable buffer-local within a @code{let}-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}.  This is
because @code{let} does not distinguish between different kinds of
bindings; it knows only which variable the binding was made for.

If the variable is terminal-local, this function signals an error.  Such
variables cannot have buffer-local bindings as well.  @xref{Multiple
Displays}.

@deffn Command make-variable-buffer-local variable
This function marks @var{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.

A peculiar wrinkle of this feature is that binding the variable (with
@code{let} or other binding constructs) does not create a buffer-local
binding for it.  Only setting the variable (with @code{set} or
@code{setq}) does so.

The value returned is @var{variable}.

@strong{Warning:} Don't assume that you should use
@code{make-variable-buffer-local} for user-option variables, simply
because users @emph{might} 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.

The time to use @code{make-variable-buffer-local} 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} can be the best solution.
@end deffn

@defun local-variable-p variable &optional buffer
This returns @code{t} if @var{variable} is buffer-local in buffer
@var{buffer} (which defaults to the current buffer); otherwise,
@code{nil}.
@end defun

@defun buffer-local-variables &optional buffer
This function returns a list describing the buffer-local variables in
buffer @var{buffer}.  (If @var{buffer} is omitted, the current buffer is
used.)  It returns an association list (@pxref{Association Lists}) in
which each element contains one buffer-local variable and its value.
However, when a variable's buffer-local binding in @var{buffer} is void,
then the variable appears directly in the resulting list.

@example
@group
(make-local-variable 'foobar)
(makunbound 'foobar)

buffer: it sets the local keymap to @code{nil}, the syntax table to the
value of @code{standard-syntax-table}, and the abbrev table to the value
of @code{fundamental-mode-abbrev-table}.

The very first thing this function does is run the normal hook
@code{change-major-mode-hook} (see below).

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.

@code{kill-all-local-variables} returns @code{nil}.
@end defun

@defvar change-major-mode-hook
The function @code{kill-all-local-variables} 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.  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.  @xref{Hooks}.
@end defvar

@c Emacs 19 feature
@cindex permanent local variable
A buffer-local variable is @dfn{permanent} if the variable name (a
symbol) has a @code{permanent-local} property that is non-@code{nil}.

@subsection The Default Value of a Buffer-Local Variable
@cindex default value

  The global value of a variable with buffer-local bindings is also
called the @dfn{default} value, because it is the value that is in
effect whenever neither the current buffer nor the selected frame has
its own binding for the variable.

  The functions @code{default-value} and @code{setq-default} access and
change a variable's default value regardless of whether the current
buffer has a buffer-local binding.  For example, you could use
@code{setq-default} to change the default setting of

this variable.

@c Emacs 19 feature
  The special forms @code{defvar} and @code{defconst} also set the
default value (if they set the variable at all), rather than any
buffer-local or frame-local value.

@defun default-value symbol
This function returns @var{symbol}'s default value.  This is the value
that is seen in buffers and frames that do not have their own values for
this variable.  If @var{symbol} is not buffer-local, this is equivalent
to @code{symbol-value} (@pxref{Accessing Variables}).
@end defun

@c Emacs 19 feature
@defun default-boundp symbol
The function @code{default-boundp} tells you whether @var{symbol}'s

current buffer sees.

@example
@group
;; @r{In buffer @samp{foo}:}
(make-local-variable 'buffer-local)
     @result{} buffer-local
@end group
@group
(setq buffer-local 'value-in-foo)
     @result{} value-in-foo
@end group
@group
(setq-default buffer-local 'new-default)
     @result{} new-default
@end group
@group
buffer-local
     @result{} value-in-foo
@end group
@group
(default-value 'buffer-local)
     @result{} new-default
@end group

@group
;; @r{In (the new) buffer @samp{bar}:}
buffer-local
     @result{} new-default
@end group
@group
(default-value 'buffer-local)
     @result{} new-default
@end group
@group
(setq buffer-local 'another-default)
     @result{} another-default
@end group
@group
(default-value 'buffer-local)
     @result{} another-default
@end group

@group
;; @r{Back in buffer @samp{foo}:}
buffer-local
     @result{} value-in-foo
(default-value 'buffer-local)
     @result{} another-default
@end group
@end example
@end defspec

(default-value 'a)
     @result{} 23
@end group
@end example
@end defun

@node Frame-Local Variables
@section Frame-Local Variables

  Just as variables can have buffer-local bindings, they can also have
frame-local bindings.  These bindings belong to one frame, and are in
effect when that frame is selected.  Frame-local bindings are actually
frame parameters: you create a frame-local binding in a specific frame
by calling @code{modify-frame-parameters} and specifying the variable
name as the parameter name.

  To enable frame-local bindings for a certain variable, call the function
@code{make-variable-frame-local}.

@defun make-variable-frame-local variable
Enable the use of frame-local bindings for @var{variable}.  This does
not in itself create any frame-local bindings for the variable; however,
if some frame already has a value for @var{variable} as a frame
parameter, that value automatically becomes a frame-local binding.

If the variable is terminal-local, this function signals an error.  Such
variables cannot have buffer-local bindings as well.  @xref{Multiple
Displays}.  A few variables that are implemented specially in Emacs
can be (and usually are) buffer-local, but can never be frame-local.
@end defun

  Buffer-local bindings take precedence over frame-local bindings.  Thus,
consider a variable @code{foo}: if the current buffer has a buffer-local
binding for @code{foo}, that binding is active; otherwise, if the
selected frame has a frame-local binding for @code{foo}, that binding is
active; otherwise, the default binding of @code{foo} is active.

  Here is an example.  First we prepare a few bindings for @code{foo}:

@example
(setq f1 (selected-frame))
(make-variable-frame-local 'foo)

;; @r{Make a buffer-local binding for @code{foo} in @samp{b1}.}
(set-buffer (get-buffer-create "b1"))
(make-local-variable 'foo)
(setq foo '(b 1))

;; @r{Make a frame-local binding for @code{foo} in a new frame.}
;; @r{Store that frame in @code{f2}.}
(setq f2 (make-frame))
(modify-frame-parameters f2 '((foo . (f 2))))
@end example

  Now we examine @code{foo} in various contexts.  Whenever the
buffer @samp{b1} is current, its buffer-local binding is in effect,
regardless of the selected frame:

@example
(select-frame f1)
(set-buffer (get-buffer-create "b1"))
foo
     @result{} (b 1)

(select-frame f2)
(set-buffer (get-buffer-create "b1"))
foo
     @result{} (b 1)
@end example

@noindent
Otherwise, the frame gets a chance to provide the binding; when frame
@code{f2} is selected, its frame-local binding is in effect:

@example
(select-frame f2)
(set-buffer (get-buffer "*scratch*"))
foo
     @result{} (f 2)
@end example

@noindent
When neither the current buffer nor the selected frame provides
a binding, the default binding is used:

@example
(select-frame f1)
(set-buffer (get-buffer "*scratch*"))
foo
     @result{} nil
@end example

@noindent
When the active binding of a variable is a frame-local binding, setting
the variable changes that binding.  You can observe the result with
@code{frame-parameters}:

@example
(select-frame f2)
(set-buffer (get-buffer "*scratch*"))
(setq foo 'nobody)
(assq 'foo (frame-parameters f2))
     @result{} (foo . nobody)
@end example

@node Future Local Variables
@section Possible Future Local Variables

  We have considered the idea of bindings that are local to a category
of frames---for example, all color frames, or all frames with dark
backgrounds.  We have not implemented them because it is not clear that
this feature is really useful.  You can get more or less the same
results by adding a function to @code{after-make-frame-hook}, set up to
define a particular frame parameter according to the appropriate
conditions for each frame.

  It would also be possible to implement window-local bindings.  We
don't know of many situations where they would be useful, and it seems
that indirect buffers (@pxref{Indirect Buffers}) with buffer-local
bindings offer a way to handle these situations more robustly.

  If sufficient application is found for either of these two kinds of
local bindings, we will provide it in a subsequent Emacs version.