comparison doc/lispref/variables.texi @ 85688:b210bba3f477

Merge from emacs--rel--22 Patches applied: * emacs--rel--22 (patch 131-137) - Update from CVS - Merge from gnus--rel--5.10 * gnus--rel--5.10 (patch 261-262) - Update from CVS Revision: [e-mail]/emacs--devo--0--patch-908

85687:666ace46440f

* 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.
* File Local Variables::  Handling local variable lists in files.
* Variable Aliases::      Variables that are aliases for other variables.
* Variables with Restricted Values::  Non-constant variables whose value can
                                        @emph{not} be an arbitrary Lisp object.

@item
@code{condition-case} (@pxref{Errors}).
@end itemize

  Variables can also have buffer-local bindings (@pxref{Buffer-Local
Variables}) and frame-local bindings (@pxref{Frame-Local Variables}); a
few variables have terminal-local bindings (@pxref{Multiple Displays}).
These kinds of bindings work somewhat like ordinary local bindings, but
they are localized depending on ``where'' you are in Emacs, rather than
localized in time.

@defvar max-specpdl-size
@anchor{Definition of max-specpdl-size}
@cindex variable limit error
@cindex evaluation error

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

  Global and local variable bindings are found in most programming
languages in one form or another.  Emacs, however, also supports additional,
unusual kinds of variable binding: @dfn{buffer-local} bindings, which
apply only in one buffer, and @dfn{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 each 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

  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

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 or frame-local
bindings in one or more buffers, @code{let} rebinds the binding that's
currently in effect.  For instance, if the current buffer has a
buffer-local value, @code{let} temporarily rebinds that.  If no
buffer-local or frame-local bindings are in effect, @code{let} rebinds
the default value.  If inside the @code{let} you then change to a
different current buffer in which a different binding is in effect,
you won't see the @code{let} binding any more.  And if you exit the
@code{let} while still in the other buffer, you won't see the
unbinding occur (though it will occur properly).  Here is an example

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

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

@node Frame-Local Variables
@section Frame-Local Variables
@cindex 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}.

@deffn Command 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 @var{variable} does not have a default value, then calling this
command will give it a default value of @code{nil}.  If @var{variable}
already has a default value, that value remains unchanged.

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

This command returns @var{variable}.
@end deffn

  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

85688:b210bba3f477

* 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.
* Future Local Variables::  New kinds of local values we might add some day.
* File Local Variables::  Handling local variable lists in files.
* Variable Aliases::      Variables that are aliases for other variables.
* Variables with Restricted Values::  Non-constant variables whose value can
                                        @emph{not} be an arbitrary Lisp object.

@item
@code{condition-case} (@pxref{Errors}).
@end itemize

  Variables can also have buffer-local bindings (@pxref{Buffer-Local
Variables}); a few variables have terminal-local bindings
(@pxref{Multiple Displays}).  These kinds of bindings work somewhat
like ordinary local bindings, but they are localized depending on
``where'' you are in Emacs, rather than localized in time.

@defvar max-specpdl-size
@anchor{Definition of max-specpdl-size}
@cindex variable limit error
@cindex evaluation error

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

  Global and local variable bindings are found in most programming
languages in one form or another.  Emacs, however, also supports
additional, unusual kinds of variable binding, such as
@dfn{buffer-local} bindings, which apply only in one buffer.  Having
different values for a variable in different buffers is an important
customization method.  (A few variables have bindings that are local
to each 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

  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,
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

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
bindings in one or more buffers, @code{let} rebinds the binding that's
currently in effect.  For instance, if the current buffer has a
buffer-local value, @code{let} temporarily rebinds that.  If no
buffer-local bindings are in effect, @code{let} rebinds
the default value.  If inside the @code{let} you then change to a
different current buffer in which a different binding is in effect,
you won't see the @code{let} binding any more.  And if you exit the
@code{let} while still in the other buffer, you won't see the
unbinding occur (though it will occur properly).  Here is an example

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 and frames that do not have their own values for
this variable.  If @var{symbol} is not buffer-local, this is equivalent

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

@node Future Local Variables
@section Possible Future Local Variables

  We have considered the idea of bindings that are local to a category