⟦07062e05c⟧

TextFile

@setfilename ../info/variables
@node Variables, Functions, Symbols, Top
@chapter Variables

  A @dfn{variable} is a name used in a program to stand for a value.
Nearly all programming languages have variables of some sort in the
textual representation of the program.  In a Lisp program in textual
form, variables are written like symbols.

  In Lisp, unlike most programming languages, programs are not merely
text; they have a textual form, and a form as clusters of Lisp objects.
When a Lisp program is in the form of Lisp objects, the object that
represents a variable is a symbol (@pxref{Symbols}).  Therefore, when a
Lisp program is written as text, the variables are written just as
symbols are written.

  The current value of a variable always resides in the symbol's
value cell (@pxref{Symbol Components}).

@menu
* Global Variables::    
* Void Variables::      
* Defining Variables::
* Accessing Variables:: 
* Setting Variables::   
* Local Variables::     
* Variable Resolution:: 
* Buffer Local Variables::      
* Default Value::
@end menu

@node Global Variables, Constant Variables, Variables, Variables
@section Global Variables

  The simplest way to use a variable is @dfn{globally}.  This means
that the variable has just one value at a time, and this value is in
effect (until replaced with another value) throughout the Lisp system.
After a new value replaces the old one, no memory of the old value
remains.

  You give the symbol its value with @code{setq}.  For example, 

@example
(setq x '(a b))
@end example

@noindent
gives the variable @code{x} the value @samp{(a b)}.  Note that the
first argument of @code{setq}, the name of the variable, is not
evaluated; but the second argument, the desired value, is evaluated
normally.

  Once you have done this, you can refer to the variable by using the
symbol by itself as an expression.  Thus,

@example
x
     @result{} (a b)
@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
x
     @result{} (a b)
(setq x 4)
     @result{} 4
x
     @result{} 4
@end example

@node Constant Variables, Local Variables, Global Variables, Variables
@section Variables that Never Change
@vindex nil
@vindex t
@cindex setting-constant error

  Emacs Lisp has two special symbols, @code{nil} and @code{t}, that
always evaluate to themselves.  These symbols cannot be rebound, nor can
their value cells be changed.  An attempt to change the value results in
a @code{setting-constant} error.

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

@node Local Variables, Void Variables, Constant Variables, Variables
@section Local Variables
@cindex binding local variables
@cindex binding arguments
@cindex local variables

  Global variables are given values that last until explicitly superseded
with new values.  Sometimes it is useful to create variable values that
exist temporarily---only until exit from 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 variables which last until the function exits.  The @code{let}
special form explicitly establishes new local values for specified variables;
these last until exit from the @code{let} form.

  If you set the variable with @code{setq} or @code{set} while a local
value is in effect, this replaces the local value; it does not alter the
global value, or previous local values which are not currently visible.  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 place that holds a local value.  Function calling,
or @code{let}, creates the local binding; exit from the function or from
the @code{let} removes the local binding.  As long as the local binding
lasts, the variable's value is stored within it.  Use of @code{setq} or
@code{set} while there is a local binding stores a different value into the
local binding; it does not create a new binding.

  We also speak of the global binding, which is where (conceptually)
the global value is kept.

  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.  If there are no local bindings, the variable's
current binding is its global binding.  Ordinary evaluation of a symbol
always returns the value of its current binding.

  Sometimes we call the current binding the @dfn{most-local existing
binding}, for emphasis.

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

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

This function binds variables according to @var{bindings} and then
evaluates all of the @var{forms} in textual order.  The @code{let}-form
returns the value of the last form in @var{forms}.

Each of the @var{bindings} is either @w{(i)} a symbol, in which case that
symbol is bound to @code{nil}; or @w{(ii)} a list of the form
@code{(@var{symbol} @var{form})}, in which case @var{symbol} is bound to
the result of evaluating @var{form} (@var{form} may be omitted, in which
case @code{nil} is used).

All of the @var{form}s in @var{bindings} are evaluated in the order they
appear and @emph{before} any of the symbols are bound.  The example
illustrates this: @code{Z} is bound to the old value of @code{Y}, which is
2, not the new value, 1.

@example
(setq Y 2)
     @result{} 2
(let ((Y 1) 
      (Z Y))
  (list Y Z))
     @result{} (1 2)
@end example
@end defspec

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

This special form is like @code{let}, except that the symbols in
@var{bindings} are bound as they are encountered before the remaining forms
are evaluated.  Therefore, an expression in the @var{bindings} may
reasonably refer to symbols already bound by this @var{bindings}.  Compare
the following example with the example above for @code{let}.

@example
(setq Y 2)
     @result{} 2
(let* ((Y 1)
       (Z Y))    ; @r{Use the just-established value of @code{Y}.}
  (list Y Z))
     @result{} (1 1)
@end example
@end defspec

  Here is a complete list of the other situations which create local
bindings:

@itemize @bullet
@item
Function calls (@pxref{Functions}).

@item
Macro calls (@pxref{Macros}).

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

@vindex max-specpdl-size
  The number of local variable bindings at any given time, of all
variables combined, is limited to the value of @code{max-specpdl-size}
(@pxref{Eval}).  This limit is designed to catch infinite recursions.
If it gets in your way, you can set it as large as you like.

@node Void Variables, Defining Variables, Local Variables, Variables
@section When a Variable is ``Void''

@kindex void-variable
@cindex void variable
  If you have never given a symbol any value as a global variable, we say
that that symbol's value is @dfn{void}.  In other words, the symbol's value
cell does not have any Lisp object in it.  If you try to evaluate this
symbol, the result is a @code{void-variable} error.

  Note that a value of @code{nil} is not the same as void.  The symbol
@code{nil} is a Lisp object and can be the value of a variable just as any
other object can be; but it is @emph{a value}.  A void variable does not
have any value.

  After you have given a variable a value, you can make it void once more
using @code{makunbound}.

@defun makunbound symbol
This function makes the current binding of @var{symbol} void.  This
causes a future attempt to use this symbol as a variable to signal the
error @code{void-variable}, unless or until you set it again.

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

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

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 that 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.

@example
(setq x 1)               ; @r{Put a value in the global binding.}
     @result{} 1
(let ((x 2))             ; @r{Locally bind it.}
  (makunbound 'x)        ; @r{Void the local binding.}
  x)
@error{} Symbol's value as variable is void: x
x                        ; @r{The global binding is unchanged.}
     @result{} 1

(let ((x 2))             ; @r{Locally bind it.}
  (let ((x 3))           ; @r{And again.}
    (makunbound 'x)      ; @r{Void the innermost-local binding.}
    x))                  ; @r{And refer: it's void.}
@error{} Symbol's value as variable is void: x

(let ((x 2))
  (let ((x 3))
    (makunbound 'x))     ; @r{Void inner binding, then remove it.}
  x)                     ; @r{Now outer @code{let} binding is visible.}
     @result{} 2
@end example
@end defun

  A symbol that has been made void with @code{makunbound} is
indistinguishable as a variable from one that has never received a value
and has always been void.

  You can use the function @code{boundp} to test whether a symbol is
currently void.

@defun boundp symbol
@code{boundp} returns @code{t} if @var{symbol} is not void; to be more
precise, if its current binding is not void.  It returns @code{nil}
otherwise.

@example
(boundp 'abracadabra)                ; @r{Starts out void.}
     @result{} nil
(let ((abracadabra 5))               ; @r{Locally bind it.}
  (boundp 'abracadabra))
     @result{} t
(boundp 'abracadabra)                ; @r{Still globally void.}
     @result{} nil
(setq abracadabra 5)                 ; @r{Make it globally nonvoid.}
     @result{} 5
(boundp 'abracadabra)
     @result{} t
@end example
@end defun

@node Defining Variables, Accessing Variables, Void Variables, Variables
@section Defining Global Variables

  You may declare your intention to use a symbol as a global variable with
@code{defconst} or @code{defvar}.

  In GNU Emacs Lisp, definitions serve three purposes.  First, they inform
the user who reads the code that certain symbols are @emph{intended} to be
used as variables.  Second, they inform the Lisp system of these things,
supplying a value and documentation.  Third, they provide information to
utilities such as @code{etags} and @code{make-docfile}, which create data
bases of the functions and variables in a program.

  The difference between @code{defconst} and @code{defvar} is primarily a
matter intent, of interest to human readers, but it also makes a difference
for initialization.  Emacs Lisp does not restrict the ways in which a
variable can be used based on @code{defconst} or @code{defvar}
declarations.

  A user-option defined in a library that is not loaded into Emacs by
default should be defined with @code{defvar}, so that the user can give his
own value to the variable before loading the library.  If @code{defconst}
were used to define the user option, loading the library would always
override any previous value of the variable.

@defspec defvar symbol [value [doc-string]]
This special form informs a person reading your code that @var{symbol}
will be used as a variable that the programs are likely to set or
change.  It is also used for all user-option variables except in the
preloaded parts of Emacs.  Note that @var{symbol} is not evaluated;
the symbol to be defined must appear explicitly in the
@code{defconst}.

If @var{symbol} already has a value (i.e. it is not void), @var{value}
is not even evaluated, and @var{symbol}'s value remains unchanged.  If
@var{symbol} is void and @var{value} is specified, it is evaluated and
@var{symbol} is set to the result.  (If @var{value} is not specified,
the value of @var{symbol} is never changed.)

The @code{defvar} form returns @var{symbol}, but it is normally used
at top level in a file where its value does not matter.

@c !!! Should this be @kindex?
@cindex @code{variable-documentation}
If the @var{doc-string} argument appears, it specifies the
documentation for the variable.  (This opportunity to specify
documentation is one of the main benefits of defining the variable.)
The documentation is stored on the symbol under the property
@code{variable-documentation}.  The Emacs help functions
(@pxref{Documentation}) look for this property.

If the first character of @var{doc-string} is @samp{*}, it says this
variable is considered to be a user option.

For example, the form below defines @code{foo} but does not set the
value cell of @code{foo}.

@example
(defvar foo)
     @result{} foo
@end example

The second example sets the value of @code{bar} to @code{23}, and
gives it a documentation string.

@example
(defvar bar 23 "The normal weight of a bar.")
     @result{} bar
@end example

The following form changes the documentation string for @code{bar},
making it a user option, but does not change the value (the addition
@code{(1+ 23)} is not even performed, since @code{bar} is already
nonvoid).

@example
(defvar bar (1+ 23) "*The normal weight of a bar.")
     @result{} bar
bar
     @result{} 23
@end example

Here is an equivalent expression for the @code{defvar} special form:

@example
(defvar @var{symbol} @var{value} @var{doc-string})
@equiv{}
(progn
  (if (not (boundp '@var{symbol}))
      (setq @var{symbol} @var{value}))
  (put '@var{symbol} 'variable-documentation '@var{doc-string})
  '@var{symbol})
@end example
@end defspec

@defspec defconst symbol [value [doc-string]]
This special form informs a person reading your code that @var{symbol}
has a global value, established here, that will not normally be
locally bound, or changed by the execution of the program.  The user,
however, may be welcome to change it.  Note that @var{symbol} is not
evaluated; the symbol to be defined must appear explicitly in the
@code{defconst}.

@code{defconst} always evaluates @var{value} and sets the global value
of @var{symbol} to the result, provided @var{value} is given.

@b{Note:} don't use @code{defconst} for user-option variables in
libraries that are not normally loaded.  The user should be able to
specify a value for such a variable in the @file{.emacs} file, so that
it will be in effect if/when the library is loaded later.  

Here, @code{pi} is a constant which presumably ought not to be changed
by anyone (attempts by the U.S.  Congress notwithstanding).  However,
as the second form illustrates, this is only advisory.

@example
(defconst pi 3 "Pi to one place.")
     @result{} pi
(setq pi 4)
     @result{} pi
pi
     @result{} 4
@end example
@end defspec

@defun user-variable-p variable
@cindex user variable
This function returns @code{t} if @var{variable} is intended to be set
by the user for customization, as opposed to by programs.  (Other
variables exist for the internal purposes of Lisp programs, and users
need not know about them.)

The decision is based on the first character of the property
@code{variable-documentation} of @var{variable}.  If the property
exists and is a string, and its first character is @samp{*}, then the
result is @code{t}; otherwise, the result is @code{nil}.
@end defun

  Note that if the @code{defconst} and @code{defvar} special forms are used
while the variable has a local binding, the local binding's value is set;
the global binding is therefore not changed.  But the canonical way to use
these special forms is at top level in a file, where normally there are no
local bindings in effect.

@node Accessing Variables, Setting Variables, Defining Variables, Variables
@section Accessing Variable Values

  The usual way to reference a variable is just to write the symbol which
names it (@pxref{Symbol Forms}).  However, this requires you to choose the
variable to reference when you write the program.  Usually that is exactly
what you want to do, but occasionally you need to choose at run time which
variable to reference.  Then you can use @code{symbol-value}.

@defun symbol-value symbol
This function returns the value of @var{symbol}.  This is the value in
the innermost local binding of the symbol, or its global value if it
has no local bindings.

@example
(setq abracadabra 5)
     @result{} 5
(let ((abracadabra 'foo))
  (symbol-value 'abracadabra))
     @result{} foo
(symbol-value 'abracadabra)
     @result{} 5
@end example

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

@node Setting Variables, Variable Resolution, Accessing Variables, Variables
@section How to Alter a Variable Value

@defspec setq [symbol form]@dots{}
This special form is the most common method of changing a variable's
value.  Each @var{symbol} is given a new value, which is the result of
evaluating the corresponding @var{form}.  Naturally it is the
most-local existing binding of each symbol that is changed.

The value of the @code{setq} form is the value of the last @var{form}.

@example
(setq x (1+ 2))
     @result{} 3
x                     ; @r{@code{x} now has a global value.}
     @result{} 3
(let ((x 5)) 
  (setq x 6)          ; @r{The local binding of @code{x} is set.}
  x)
     @result{} 6
x                     ; @r{The global value is unchanged.}
     @result{} 3
@end example

Note that the first @var{form} is evaluated, then the first
@var{symbol} is set, then the second @var{form} is evaluated, then the
second @var{symbol} is set, and so on:

@example
(setq x 10            ; @r{Notice that @code{x} is set}
      y (1+ x))       ; @r{before the value of @code{y} is computed.}
     @result{} 11             
@end example
@end defspec

@defun set symbol value
This function sets @var{symbol}'s value to @var{value}, then
returns @var{value}.  Since @code{set} is a function, the expression
written for @var{symbol} is evaluated to obtain the symbol to be
set.

As usual, it is the most-local existing binding of the variable that
is set.  If @var{symbol} is not actually a symbol, a
@code{wrong-type-argument} error is signaled.

@example
(set one 1)
@error{} Symbol's value as variable is void: one
(set 'one 1)
     @result{} 1
(set 'two 'one)
     @result{} one
(set two 2)            ; @code{two} evaluates to symbol @code{one}.
     @result{} 2
one                    ; So it is @code{one} that was set.
     @result{} 2
(let ((one 1))         ; This binding of @code{one} is set,
  (set 'one 3)      ; not the global value.
  one)
     @result{} 3
one
     @result{} 2
@end example

Logically speaking, @code{set} is a more fundamental primitive that
@code{setq}.  Any use of @code{setq} can be trivially rewritten to use
@code{set}; @code{setq} could even be defined as a macro, given the
availability of @code{set}.

However, @code{set} itself is rarely used; beginners hardly need to
know about it.  It is needed only when the choice of variable to be
set is made at run time.  For example, the command
@code{set-variable}, which reads a variable name from the user and
then sets it, needs to use @code{set}.

@quotation
@cindex Common Lisp set
@b{Common Lisp Note:} In Common Lisp, @code{set} always changes the
symbol's special value, ignoring any lexical bindings.  In Emacs Lisp, all
variables and all bindings are special, so @code{set} always affects the
most local existing binding.
@end quotation
@end defun

@node Variable Resolution, Buffer Local Variables, Setting Variables, Variables
@section Local Variable Resolution
@cindex variable resolution

  There is only one canonical symbol @code{foo}, but various variable
values may be in effect for it, from different places in the Lisp programs.
Therefore, when the variable is evaluated, Emacs Lisp must decide which
of these values is currently in effect.  The process by which this is done
is called @dfn{variable resolution}.

@cindex scope
@cindex extent
@cindex dynamic scoping
  Local bindings in Emacs Lisp have @dfn{indefinite scope} and @dfn{dynamic
extent}.  @dfn{Scope} refers to @emph{where} textually in the source code
the binding can be accessed.  @dfn{Extent} refers to @emph{when}, as the
program is executing, the binding exists.  The combination of dynamic
extent and indefinite scope is called @dfn{dynamic scoping}.  By contrast,
most programming languages use @dfn{lexical scoping}, in which references
to a local variable must be textually within the function or block that
binds the variable.

@quotation
@strong{Common Lisp note:} variables declared ``special'' in Common Lisp
behave exactly this way.
@end quotation

@menu
* Impl of Scope Rules::
* Scope::       
* Extent::      
@end menu

@node Impl of Scope Rules, Scope, Variable Resolution, Variable Resolution
@subsection Sample Implementation of Dynamic Scoping

  A simple sample implementation (which is not how Emacs Lisp is actually
implemented) might help you understand dynamic binding.

  Suppose there is a stack of bindings: variable-value pairs.  To find the
value of a variable, search 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, search for a binding, then store the new value into
that binding.

  At entry to a function or to a @code{let} form, we can push bindings on
the stack for the arguments or local variables created there.  At exit, we
can remove those bindings.

  As you can see, a function's argument bindings remain in effect as long
as it continues execution, even during its calls to other functions.  That
is why we say the extent of the binding is dynamic.  And these other
functions can refer to the bindings, if they use these variables.  That is
why we say the scope is indefinite.

  Binding a variable in one function and using it in another is a powerful
technique, but if used without restraint, it can make programs hard to
understand.  There are two clean ways to use this technique:

@itemize @bullet
@item
Only a few related functions, written close together in one file, use or
bind the variable.  Its purpose is communication within one program.

You should write comments to inform other programmers that they can see
all uses of the variable before them, and to advise them not to add uses
elsewhere.

@item
The variable has a well-defined, documented meaning, and various
functions refer to it (but do not bind it or set it) wherever that
meaning is relevant.  For example, the variable @code{case-fold-search}
is defined as ``non-@code{nil} means ignore case when searching'';
various search and replace functions refer to it directly or through
their subroutines, but do not bind or set it.

Now you can bind the variable in other programs, knowing reliably what
the effect will be.
@end itemize

@node Scope, Extent, Impl of Scope Rules, Variable Resolution
@subsection Scope

  Emacs Lisp uses @dfn{indefinite scope} for local variable bindings.  This
means that it finds values of free variables by looking backward on the
(dynamic) call chain.  It follows that any function anywhere in the program
text might access a given binding of a variable.  Consider the following
function definitions:

@example
(defun binder (x)  ; @r{@code{x} is bound in @code{binder}.}
   (foo 5))        ; @r{@code{foo} is some other function.}

(defun user ()     ; @r{@code{x} is used in @code{user}.}
  (list x))
@end example

  In a lexically scoped language, the binding of @code{x} from
@code{binder} would never be accessible in @code{user}, because @code{user}
is not textually contained within the function @code{binder}.

  However, in dynamically scoped Emacs Lisp, @code{user} may or may not
refer to the binding of @code{x} established in @code{binder}, depending on
circumstances:

@itemize @bullet
@item
If we call @code{user} directly without calling @code{binder} at all, then
whatever binding of @code{x} is found, it won't be from @code{binder}.

@item
If we define @code{foo} as follows and call @code{binder}, then the
binding made in @code{binder} will be seen in @code{user}:

@example
(defun foo (lose)
  (user))
@end example

@item
If we define @code{foo} as follows and call @code{binder}, then the
binding made in @code{binder} @emph{will not} be seen in @code{user}:

@example
(defun foo (x)
  (user))
@end example

@noindent
Here, when @code{foo} is called by @code{binder}, it binds @code{x}.
(The binding in @code{foo} is said to @dfn{shadow} the one made in
@code{binder}.)  Therefore, @code{user} will access the @code{x} bound
by @code{foo} instead of the one bound by @code{binder}.
@end itemize

@node Extent,  , Scope, Variable Resolution
@subsection Extent

  @dfn{Extent} refers to the time during program execution that a variable
name is valid.  In Emacs Lisp, a variable is valid only while the form
that bound it is executing.  This is called @dfn{dynamic extent}.
Most languages, including C and Pascal, have dynamic extent.

  One alternative to dynamic extent is @dfn{indefinite extent}.  This
means that a variable binding can live on past the exit from the form
that made the binding.  Common Lisp and Scheme, for example, support
this, but Emacs Lisp does not.

  To illustrate this, the function below, @code{make-add}, returns a
function that purports to add @var{n} to its own argument @var{m}.
This would work in Common Lisp, but it does not work as intended in
Emacs Lisp, because after the call to @code{make-add} exits, the
variable @code{n} is no longer bound to the actual argument 2.

@example
(defun make-add (n)
    (function (lambda (m) (+ n m))))  ; Return a function.
     @result{} make-add
(fset 'add2 (make-add 2))  ; Define function add2 with (make-add 2).
     @result{} (lambda (m) (+ n m))
(add2 4)                   ; Try to add 2 to 4.
@error{} Symbol's value as variable is void: n
@end example

@node Buffer Local Variables, Default Value, Variable Resolution, Variables
@section Buffer Local Variables
@cindex variables, buffer-local
@cindex buffer-local variables

  Global and local variables are common features of almost all
programming languages, if not necessarily in the same form that they
take in Emacs Lisp.  Emacs Lisp is meant for programming editing
commands, though, and the central object of editing is the buffer
(@xref{Buffers}.)  Therefore, Emacs Lisp also supports @dfn{buffer-local
variables}, which may have differing values in various buffers.

  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 shunted aside.  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 @code{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 @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 global value.

@cindex automatically buffer local
  A more powerful effect is to mark the variable as @dfn{automatically
buffer local}, with @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 global value of
the variable as usual, but any @code{setq} while in a buffer creates a
buffer-local binding for that 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 @code{setq}; you need
@code{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 Emacs.  @xref{Setting
the Major Mode}.

@deffn Command make-local-variable symbol
This function creates a buffer-local binding for @var{symbol} in the
current buffer.  Other buffers are not affected.  The value returned
is @var{symbol}.

The buffer-local value of @var{symbol} starts out as the same value
@var{symbol} previously had.

@example
;; @r{In buffer A:}
(setq foo 5)                ; @r{Affects all buffers.}
     @result{} 5
(make-local-variable 'foo)  ; @r{Now it is local in A.}
     @result{} foo
foo                         ; @r{That did not change the value.}
     @result{} 5
(setq foo 6)                ; @r{Change the value in A.}
     @result{} 6
foo
     @result{} 6

;; @r{In buffer B, the value hasn't changed.}
(save-excursion
  (set-buffer "B")
  foo)
     @result{} 5
@end example
@end deffn

@deffn Command make-variable-buffer-local symbol
This function marks @var{symbol} automatically buffer local, so that
any attempt to set it will make it local to the current buffer at the
time.

The value returned is @var{symbol}.
@end deffn

@defun buffer-local-variables &optional buffer
This function tells you what the buffer local variables are in buffer
@var{buffer}.  It returns an association list (@pxref{Association Lists}) 
in which each pair is a buffer-local variable and its value.
If @var{buffer} is omitted, the current buffer is used.

@example
(setq lcl (buffer-local-variables))
     @result{} ((fill-column . 75)
    (case-fold-search . t)
    @dots{}
    (mark-ring #<marker at 5454 in buffers.texinfo>)
    (require-final-newline . t))
@end example

Note that changing the values in this list will @emph{not} change the
local value of the variable.
@end defun

@deffn Command kill-local-variable symbol
This function deletes the buffer-local binding (if any) for
@var{symbol} in the current buffer.  As a result, the global (default)
binding of @var{symbol} are now visible in this buffer.  Usually this
causes the value of @var{symbol} to change, since the global value is
not the same as the buffer-local value that was just eliminated.

@code{kill-local-variable} returns @var{symbol}.
@end deffn

@defun kill-all-local-variables
This function eliminates all the buffer-local variable bindings of the
current buffer.  As a result, the buffer will see the default values
of all variables.  Every major mode command begins by calling this
function, which erases most of the effects of the previous major mode.

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

@node Default Value,  , Buffer Local Variables, Variables
@section The Default Value of a Buffer-Local Variable

  The functions @code{default-value} and @code{setq-default} allow you to
access and change the global value regardless of whether the current buffer
has a buffer-local binding.  You could use @code{setq-default} to change
the default setting of @code{paragraph-start} for most buffers; and this
would work even when you are in a C or Lisp mode buffer which has a
buffer-local value for this variable.

@defun default-value symbol
Return @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, than this is the same as
@code{symbol-value} (@pxref{Accessing Variables}).
@end defun

@defspec setq-default symbol value
This function sets the default (global) value of @var{symbol} to
@var{value}.  @var{symbol} is not evaluated, but @var{value} is.  The
value of the @code{setq-default} form is @var{value}.

The default value is seen in buffers that do not have their own
buffer-local values for this variable.

If a @var{symbol} is not buffer-local for the current buffer, this is
equivalent to @code{setq} in the current buffer for that symbol.  If
@var{symbol} is buffer-local for the current buffer, then this changes
the value that most other buffers will see (as long as they don't have
a buffer-local value), but not the value that the current buffer sees.

@example
(make-variable-buffer-local 'local)
     @result{} local

;; In buffer foo:
(setq local 'value-in-foo)
     @result{} value-in-foo
(setq-default local 'new-default)
     @result{} new-default
local
     @result{} value-in-foo
(default-value 'local)
     @result{} new-default

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

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

@defun set-default symbol value
This function is like @code{setq-default} except that @var{symbol} is
evaluated.

@example
(set-default (car '(a b c)) 23)
     @result{} 23
(default-value 'a)
     @result{} 23
@end example
@end defun
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦07062e05c⟧ TextFile

Derivation

TextFile
