(lispref.info)Local Variables


Next: Void Variables Prev: Constant Variables Up: Variables

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 while within a certain part of the
program.  These values are called "local", and the variables so used
are called "local variables".

   For example, when a function is called, its argument variables
receive new local values which last until the function exits.
Similarly, the `let' special form explicitly establishes new local
values for specified variables; these last until exit from the `let'
form.

   When a local value is established, the previous value (or lack of
one) of the variable is saved away.  When the life span of the local
value is over, the previous value is restored.  In the mean time, we
say that the previous value is "shadowed" and "not visible".  Both
global and local values may be shadowed (Note: Scope.).

   If you set a variable (such as with `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 "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 `let', creates the local
binding; exit from the function or from the `let' removes the local
binding.  As long as the local binding lasts, the variable's value is
stored within it.  Use of `setq' or `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 `let' forms that bind it).  In such a
case, the most recently created local binding that still exists is the
"current binding" of the variable.  (This is called "dynamic scoping";
see Note: Variable Scoping.)  If there are no local bindings, the
variable's global binding is its current binding.  We also call the
current binding the "most-local existing binding", for emphasis.
Ordinary evaluation of a symbol always returns the value of its current
binding.

   The special forms `let' and `let*' exist to create local bindings.

 - Special Form: let (BINDINGS...) FORMS...
     This function binds variables according to BINDINGS and then
     evaluates all of the FORMS in textual order.  The `let'-form
     returns the value of the last form in FORMS.

     Each of the BINDINGS is either (i) a symbol, in which case that
     symbol is bound to `nil'; or (ii) a list of the form `(SYMBOL
     VALUE-FORM)', in which case SYMBOL is bound to the result of
     evaluating VALUE-FORM.  If VALUE-FORM is omitted, `nil' is used.

     All of the VALUE-FORMs in BINDINGS are evaluated in the order they
     appear and *before* any of the symbols are bound.  Here is an
     example of this: `Z' is bound to the old value of `Y', which is 2,
     not the new value, 1.

          (setq Y 2)
               => 2
          (let ((Y 1)
                (Z Y))
            (list Y Z))
               => (1 2)

 - Special Form: let* (BINDINGS...) FORMS...
     This special form is like `let', except that each symbol in
     BINDINGS is bound as soon as its new value is computed, before the
     computation of the values of the following local bindings.
     Therefore, an expression in BINDINGS may reasonably refer to the
     preceding symbols bound in this `let*' form.  Compare the
     following example with the example above for `let'.

          (setq Y 2)
               => 2
          (let* ((Y 1)
                 (Z Y))    ; Use the just-established value of `Y'.
            (list Y Z))
               => (1 1)

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

   * Function calls (Note: Functions.).

   * Macro calls (Note: Macros.).

   * `condition-case' (Note: Errors.).

 - Variable: max-specpdl-size
     This variable defines the limit on the total number of local
     variable bindings and `unwind-protect' cleanups (Note: Nonlocal
     Exits.) that are allowed before signaling an error (with data
     `"Variable binding depth exceeds max-specpdl-size"').

     This limit, with the associated error when it is exceeded, is one
     way that Lisp avoids infinite recursion on an ill-defined function.

     The default value is 600.

     `max-lisp-eval-depth' provides another limit on depth of nesting.
     Note: Eval.


automatically generated by info2www