2 @c This is part of the SXEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c Copyright (C) 2005 Sebastian Freundt <hroptatyr@sxemacs.org>
5 @c See the file lispref.texi for copying conditions.
6 @setfilename ../../info/variables.info
8 @node Variables, Functions and Commands, Control Structures, Top
12 A @dfn{variable} is a name used in a program to stand for a value.
13 Nearly all programming languages have variables of some sort. In the
14 text of a Lisp program, variables are written using the syntax for
17 In Lisp, unlike most programming languages, programs are represented
18 primarily as Lisp objects and only secondarily as text. The Lisp
19 objects used for variables are symbols: the symbol name is the variable
20 name, and the variable's value is stored in the value cell of the
21 symbol. The use of a symbol as a variable is independent of its use as
22 a function name. @xref{Symbol Components}.
24 The Lisp objects that constitute a Lisp program determine the textual
25 form of the program---it is simply the read syntax for those Lisp
26 objects. This is why, for example, a variable in a textual Lisp program
27 is written using the read syntax for the symbol that represents the
31 * Global Variables:: Variable values that exist permanently, everywhere.
32 * Constant Variables:: Certain "variables" have values that never change.
33 * Local Variables:: Variable values that exist only temporarily.
34 * Void Variables:: Symbols that lack values.
35 * Defining Variables:: A definition says a symbol is used as a variable.
36 * Accessing Variables:: Examining values of variables whose names
37 are known only at run time.
38 * Setting Variables:: Storing new values in variables.
39 * Variable Scoping:: How Lisp chooses among local and global values.
40 * Buffer-Local Variables:: Variable values in effect only in one buffer.
41 * Variable Aliases:: Making one variable point to another.
45 @node Global Variables
46 @section Global Variables
47 @cindex global variable
49 The simplest way to use a variable is @dfn{globally}. This means that
50 the variable has just one value at a time, and this value is in effect
51 (at least for the moment) throughout the Lisp system. The value remains
52 in effect until you specify a new one. When a new value replaces the
53 old one, no trace of the old value remains in the variable.
55 You specify a value for a symbol with @code{setq}. For example,
62 gives the variable @code{x} the value @code{(a b)}. Note that
63 @code{setq} does not evaluate its first argument, the name of the
64 variable, but it does evaluate the second argument, the new value.
66 Once the variable has a value, you can refer to it by using the symbol
67 by itself as an expression. Thus,
76 assuming the @code{setq} form shown above has already been executed.
78 If you do another @code{setq}, the new value replaces the old one:
96 @node Constant Variables
97 @section Variables That Never Change
100 @kindex setting-constant
102 In SXEmacs Lisp, some symbols always evaluate to themselves: the two
103 special symbols @code{nil} and @code{t}, as well as @dfn{keyword
104 symbols}, that is, symbols whose name begins with the character
105 @samp{@code{:}}. These symbols cannot be rebound, nor can their value
106 cells be changed. An attempt to change the value of @code{nil} or
107 @code{t} signals a @code{setting-constant} error.
116 @error{} Attempt to set constant symbol: nil
121 @node Local Variables
122 @section Local Variables
123 @cindex binding local variables
124 @cindex local variables
125 @cindex local binding
126 @cindex global binding
128 Global variables have values that last until explicitly superseded
129 with new values. Sometimes it is useful to create variable values that
130 exist temporarily---only while within a certain part of the program.
131 These values are called @dfn{local}, and the variables so used are
132 called @dfn{local variables}.
134 For example, when a function is called, its argument variables receive
135 new local values that last until the function exits. The @code{let}
136 special form explicitly establishes new local values for specified
137 variables; these last until exit from the @code{let} form.
139 @cindex shadowing of variables
140 Establishing a local value saves away the previous value (or lack of
141 one) of the variable. When the life span of the local value is over,
142 the previous value is restored. In the mean time, we say that the
143 previous value is @dfn{shadowed} and @dfn{not visible}. Both global and
144 local values may be shadowed (@pxref{Scope}).
146 If you set a variable (such as with @code{setq}) while it is local,
147 this replaces the local value; it does not alter the global value, or
148 previous local values that are shadowed. To model this behavior, we
149 speak of a @dfn{local binding} of the variable as well as a local value.
151 The local binding is a conceptual place that holds a local value.
152 Entry to a function, or a special form such as @code{let}, creates the
153 local binding; exit from the function or from the @code{let} removes the
154 local binding. As long as the local binding lasts, the variable's value
155 is stored within it. Use of @code{setq} or @code{set} while there is a
156 local binding stores a different value into the local binding; it does
157 not create a new binding.
159 We also speak of the @dfn{global binding}, which is where
160 (conceptually) the global value is kept.
162 @cindex current binding
163 A variable can have more than one local binding at a time (for
164 example, if there are nested @code{let} forms that bind it). In such a
165 case, the most recently created local binding that still exists is the
166 @dfn{current binding} of the variable. (This is called @dfn{dynamic
167 scoping}; see @ref{Variable Scoping}.) If there are no local bindings,
168 the variable's global binding is its current binding. We also call the
169 current binding the @dfn{most-local existing binding}, for emphasis.
170 Ordinary evaluation of a symbol always returns the value of its current
173 The special forms @code{let} and @code{let*} exist to create
176 @defspec let (bindings@dots{}) forms@dots{}
177 This special form binds variables according to @var{bindings} and then
178 evaluates all of the @var{forms} in textual order. The @code{let}-form
179 returns the value of the last form in @var{forms}.
181 Each of the @var{bindings} is either @w{(i) a} symbol, in which case
182 that symbol is bound to @code{nil}; or @w{(ii) a} list of the form
183 @code{(@var{symbol} @var{value-form})}, in which case @var{symbol} is
184 bound to the result of evaluating @var{value-form}. If @var{value-form}
185 is omitted, @code{nil} is used.
187 All of the @var{value-form}s in @var{bindings} are evaluated in the
188 order they appear and @emph{before} any of the symbols are bound. Here
189 is an example of this: @code{Z} is bound to the old value of @code{Y},
190 which is 2, not the new value, 1.
206 @defspec let* (bindings@dots{}) forms@dots{}
207 This special form is like @code{let}, but it binds each variable right
208 after computing its local value, before computing the local value for
209 the next variable. Therefore, an expression in @var{bindings} can
210 reasonably refer to the preceding symbols bound in this @code{let*}
211 form. Compare the following example with the example above for
221 (Z Y)) ; @r{Use the just-established value of @code{Y}.}
228 Here is a complete list of the other facilities that create local
233 Function calls (@pxref{Functions and Commands}).
236 Macro calls (@pxref{Macros}).
239 @code{condition-case} (@pxref{Errors}).
242 Variables can also have buffer-local bindings (@pxref{Buffer-Local
243 Variables}). These kinds of bindings work somewhat like ordinary local
244 bindings, but they are localized depending on ``where'' you are in
245 SXEmacs, rather than localized in time.
247 @defvar max-specpdl-size
248 @cindex variable limit error
249 @cindex evaluation error
250 @cindex infinite recursion
251 This variable defines the limit on the total number of local variable
252 bindings and @code{unwind-protect} cleanups (@pxref{Nonlocal Exits})
253 that are allowed before signaling an error (with data @code{"Variable
254 binding depth exceeds max-specpdl-size"}).
256 This limit, with the associated error when it is exceeded, is one way
257 that Lisp avoids infinite recursion on an ill-defined function.
259 The default value is 3000.
261 @code{max-lisp-eval-depth} provides another limit on depth of nesting.
267 @section When a Variable is ``Void''
268 @kindex void-variable
269 @cindex void variable
271 If you have never given a symbol any value as a global variable, we
272 say that that symbol's global value is @dfn{void}. In other words, the
273 symbol's value cell does not have any Lisp object in it. If you try to
274 evaluate the symbol, you get a @code{void-variable} error rather than
277 Note that a value of @code{nil} is not the same as void. The symbol
278 @code{nil} is a Lisp object and can be the value of a variable just as any
279 other object can be; but it is @emph{a value}. A void variable does not
282 After you have given a variable a value, you can make it void once more
283 using @code{makunbound}.
285 @defun makunbound symbol
286 This function makes the current binding of @var{symbol} void.
287 Subsequent attempts to use this symbol's value as a variable will signal
288 the error @code{void-variable}, unless or until you set it again.
290 @code{makunbound} returns @var{symbol}.
294 (makunbound 'x) ; @r{Make the global value}
295 ; @r{of @code{x} void.}
300 @error{} Symbol's value as variable is void: x
304 If @var{symbol} is locally bound, @code{makunbound} affects the most
305 local existing binding. This is the only way a symbol can have a void
306 local binding, since all the constructs that create local bindings
307 create them with values. In this case, the voidness lasts at most as
308 long as the binding does; when the binding is removed due to exit from
309 the construct that made it, the previous or global binding is reexposed
310 as usual, and the variable is no longer void unless the newly reexposed
311 binding was void all along.
315 (setq x 1) ; @r{Put a value in the global binding.}
317 (let ((x 2)) ; @r{Locally bind it.}
318 (makunbound 'x) ; @r{Void the local binding.}
320 @error{} Symbol's value as variable is void: x
323 x ; @r{The global binding is unchanged.}
326 (let ((x 2)) ; @r{Locally bind it.}
327 (let ((x 3)) ; @r{And again.}
328 (makunbound 'x) ; @r{Void the innermost-local binding.}
329 x)) ; @r{And refer: it's void.}
330 @error{} Symbol's value as variable is void: x
336 (makunbound 'x)) ; @r{Void inner binding, then remove it.}
337 x) ; @r{Now outer @code{let} binding is visible.}
343 A variable that has been made void with @code{makunbound} is
344 indistinguishable from one that has never received a value and has
347 You can use the function @code{boundp} to test whether a variable is
350 @defun boundp variable
351 @code{boundp} returns @code{t} if @var{variable} (a symbol) is not void;
352 more precisely, if its current binding is not void. It returns
353 @code{nil} otherwise.
357 (boundp 'abracadabra) ; @r{Starts out void.}
361 (let ((abracadabra 5)) ; @r{Locally bind it.}
362 (boundp 'abracadabra))
366 (boundp 'abracadabra) ; @r{Still globally void.}
370 (setq abracadabra 5) ; @r{Make it globally nonvoid.}
374 (boundp 'abracadabra)
381 @node Defining Variables
382 @section Defining Global Variables
383 @cindex variable definition
385 You may announce your intention to use a symbol as a global variable
386 with a @dfn{variable definition}: a special form, either @code{defconst}
389 In SXEmacs Lisp, definitions serve three purposes. First, they inform
390 people who read the code that certain symbols are @emph{intended} to be
391 used a certain way (as variables). Second, they inform the Lisp system
392 of these things, supplying a value and documentation. Third, they
393 provide information to utilities such as @code{etags} and
394 @code{make-docfile}, which create data bases of the functions and
395 variables in a program.
397 The difference between @code{defconst} and @code{defvar} is primarily
398 a matter of intent, serving to inform human readers of whether programs
399 will change the variable. SXEmacs Lisp does not restrict the ways in
400 which a variable can be used based on @code{defconst} or @code{defvar}
401 declarations. However, it does make a difference for initialization:
402 @code{defconst} unconditionally initializes the variable, while
403 @code{defvar} initializes it only if it is void.
405 One would expect user option variables to be defined with
406 @code{defconst}, since programs do not change them. Unfortunately, this
407 has bad results if the definition is in a library that is not preloaded:
408 @code{defconst} would override any prior value when the library is
409 loaded. Users would like to be able to set user options in their init
410 files, and override the default values given in the definitions. For
411 this reason, user options must be defined with @code{defvar}.
413 @defspec defvar symbol [value [doc-string]]
414 This special form defines @var{symbol} as a value and initializes it.
415 The definition informs a person reading your code that @var{symbol} is
416 used as a variable that programs are likely to set or change. It is
417 also used for all user option variables except in the preloaded parts of
418 XEmacs. Note that @var{symbol} is not evaluated; the symbol to be
419 defined must appear explicitly in the @code{defvar}.
421 If @var{symbol} already has a value (i.e., it is not void), @var{value}
422 is not even evaluated, and @var{symbol}'s value remains unchanged. If
423 @var{symbol} is void and @var{value} is specified, @code{defvar}
424 evaluates it and sets @var{symbol} to the result. (If @var{value} is
425 omitted, the value of @var{symbol} is not changed in any case.)
427 When you evaluate a top-level @code{defvar} form with @kbd{C-M-x} in
428 Emacs Lisp mode (@code{eval-defun}), a special feature of
429 @code{eval-defun} evaluates it as a @code{defconst}. The purpose of
430 this is to make sure the variable's value is reinitialized, when you ask
433 If @var{symbol} has a buffer-local binding in the current buffer,
434 @code{defvar} sets the default value, not the local value.
435 @xref{Buffer-Local Variables}.
437 If the @var{doc-string} argument appears, it specifies the documentation
438 for the variable. (This opportunity to specify documentation is one of
439 the main benefits of defining the variable.) The documentation is
440 stored in the symbol's @code{variable-documentation} property. The
441 SXEmacs help functions (@pxref{Documentation}) look for this property.
443 If the first character of @var{doc-string} is @samp{*}, it means that
444 this variable is considered a user option. This lets users set the
445 variable conveniently using the commands @code{set-variable} and
448 For example, this form defines @code{foo} but does not set its value:
457 The following example sets the value of @code{bar} to @code{23}, and
458 gives it a documentation string:
463 "The normal weight of a bar.")
468 The following form changes the documentation string for @code{bar},
469 making it a user option, but does not change the value, since @code{bar}
470 already has a value. (The addition @code{(1+ 23)} is not even
476 "*The normal weight of a bar.")
485 Here is an equivalent expression for the @code{defvar} special form:
489 (defvar @var{symbol} @var{value} @var{doc-string})
492 (if (not (boundp '@var{symbol}))
493 (setq @var{symbol} @var{value}))
494 (put '@var{symbol} 'variable-documentation '@var{doc-string})
499 The @code{defvar} form returns @var{symbol}, but it is normally used
500 at top level in a file where its value does not matter.
503 @defspec defconst symbol [value [doc-string]]
504 This special form defines @var{symbol} as a value and initializes it.
505 It informs a person reading your code that @var{symbol} has a global
506 value, established here, that will not normally be changed or locally
507 bound by the execution of the program. The user, however, may be
508 welcome to change it. Note that @var{symbol} is not evaluated; the
509 symbol to be defined must appear explicitly in the @code{defconst}.
511 @code{defconst} always evaluates @var{value} and sets the global value
512 of @var{symbol} to the result, provided @var{value} is given. If
513 @var{symbol} has a buffer-local binding in the current buffer,
514 @code{defconst} sets the default value, not the local value.
516 @strong{Please note:} Don't use @code{defconst} for user option
517 variables in libraries that are not standardly preloaded. The user
518 should be able to specify a value for such a variable in the
519 @file{.emacs} file, so that it will be in effect if and when the library
522 Here, @code{pi} is a constant that presumably ought not to be changed
523 by anyone (attempts by the Indiana State Legislature notwithstanding).
524 As the second form illustrates, however, this is only advisory.
528 (defconst pi 3.1415 "Pi to five places.")
542 @defun user-variable-p variable
544 This function returns @code{t} if @var{variable} is a user option---a
545 variable intended to be set by the user for customization---and
546 @code{nil} otherwise. (Variables other than user options exist for the
547 internal purposes of Lisp programs, and users need not know about them.)
549 User option variables are distinguished from other variables by the
550 first character of the @code{variable-documentation} property. If the
551 property exists and is a string, and its first character is @samp{*},
552 then the variable is a user option.
555 If a user option variable has a @code{variable-interactive} property,
556 the @code{set-variable} command uses that value to control reading the
557 new value for the variable. The property's value is used as if it were
558 the argument to @code{interactive}.
560 @strong{Warning:} If the @code{defconst} and @code{defvar} special
561 forms are used while the variable has a local binding, they set the
562 local binding's value; the global binding is not changed. This is not
563 what we really want. To prevent it, use these special forms at top
564 level in a file, where normally no local binding is in effect, and make
565 sure to load the file before making a local binding for the variable.
568 @node Accessing Variables
569 @section Accessing Variable Values
571 The usual way to reference a variable is to write the symbol which
572 names it (@pxref{Symbol Forms}). This requires you to specify the
573 variable name when you write the program. Usually that is exactly what
574 you want to do. Occasionally you need to choose at run time which
575 variable to reference; then you can use @code{symbol-value}.
577 @defun symbol-value symbol
578 This function returns the value of @var{symbol}. This is the value in
579 the innermost local binding of the symbol, or its global value if it
580 has no local bindings.
593 ;; @r{Here the symbol @code{abracadabra}}
594 ;; @r{is the symbol whose value is examined.}
595 (let ((abracadabra 'foo))
596 (symbol-value 'abracadabra))
601 ;; @r{Here the value of @code{abracadabra},}
602 ;; @r{which is @code{foo},}
603 ;; @r{is the symbol whose value is examined.}
604 (let ((abracadabra 'foo))
605 (symbol-value abracadabra))
610 (symbol-value 'abracadabra)
615 A @code{void-variable} error is signaled if @var{symbol} has neither a
616 local binding nor a global value.
620 @node Setting Variables
621 @section How to Alter a Variable Value
623 The usual way to change the value of a variable is with the special
624 form @code{setq}. When you need to compute the choice of variable at
625 run time, use the function @code{set}.
627 @defspec setq [symbol form]@dots{}
628 This special form is the most common method of changing a variable's
629 value. Each @var{symbol} is given a new value, which is the result of
630 evaluating the corresponding @var{form}. The most-local existing
631 binding of the symbol is changed.
633 @code{setq} does not evaluate @var{symbol}; it sets the symbol that you
634 write. We say that this argument is @dfn{automatically quoted}. The
635 @samp{q} in @code{setq} stands for ``quoted.''
637 The value of the @code{setq} form is the value of the last @var{form}.
644 x ; @r{@code{x} now has a global value.}
648 (setq x 6) ; @r{The local binding of @code{x} is set.}
652 x ; @r{The global value is unchanged.}
656 Note that the first @var{form} is evaluated, then the first
657 @var{symbol} is set, then the second @var{form} is evaluated, then the
658 second @var{symbol} is set, and so on:
662 (setq x 10 ; @r{Notice that @code{x} is set before}
663 y (1+ x)) ; @r{the value of @code{y} is computed.}
669 @defun set symbol value
670 This function sets @var{symbol}'s value to @var{value}, then returns
671 @var{value}. Since @code{set} is a function, the expression written for
672 @var{symbol} is evaluated to obtain the symbol to set.
674 The most-local existing binding of the variable is the binding that is
675 set; shadowed bindings are not affected.
680 @error{} Symbol's value as variable is void: one
691 (set two 2) ; @r{@code{two} evaluates to symbol @code{one}.}
695 one ; @r{So it is @code{one} that was set.}
697 (let ((one 1)) ; @r{This binding of @code{one} is set,}
698 (set 'one 3) ; @r{not the global value.}
708 If @var{symbol} is not actually a symbol, a @code{wrong-type-argument}
713 @error{} Wrong type argument: symbolp, (x y)
716 Logically speaking, @code{set} is a more fundamental primitive than
717 @code{setq}. Any use of @code{setq} can be trivially rewritten to use
718 @code{set}; @code{setq} could even be defined as a macro, given the
719 availability of @code{set}. However, @code{set} itself is rarely used;
720 beginners hardly need to know about it. It is useful only for choosing
721 at run time which variable to set. For example, the command
722 @code{set-variable}, which reads a variable name from the user and then
723 sets the variable, needs to use @code{set}.
725 @cindex CL note---@code{set} local
727 @b{Common Lisp note:} In Common Lisp, @code{set} always changes the
728 symbol's special value, ignoring any lexical bindings. In SXEmacs Lisp,
729 all variables and all bindings are (in effect) special, so @code{set}
730 always affects the most local existing binding.
734 One other function for setting a variable is designed to add
735 an element to a list if it is not already present in the list.
737 @defun add-to-list symbol element
738 This function sets the variable @var{symbol} by consing @var{element}
739 onto the old value, if @var{element} is not already a member of that
740 value. It returns the resulting list, whether updated or not. The
741 value of @var{symbol} had better be a list already before the call.
743 The argument @var{symbol} is not implicitly quoted; @code{add-to-list}
744 is an ordinary function, like @code{set} and unlike @code{setq}. Quote
745 the argument yourself if that is what you want.
747 Here's a scenario showing how to use @code{add-to-list}:
753 (add-to-list 'foo 'c) ;; @r{Add @code{c}.}
756 (add-to-list 'foo 'b) ;; @r{No effect.}
759 foo ;; @r{@code{foo} was changed.}
764 An equivalent expression for @code{(add-to-list '@var{var}
765 @var{value})} is this:
768 (or (member @var{value} @var{var})
769 (setq @var{var} (cons @var{value} @var{var})))
773 @node Variable Scoping
774 @section Scoping Rules for Variable Bindings
776 A given symbol @code{foo} may have several local variable bindings,
777 established at different places in the Lisp program, as well as a global
778 binding. The most recently established binding takes precedence over
783 @cindex dynamic scoping
784 Local bindings in SXEmacs Lisp have @dfn{indefinite scope} and
785 @dfn{dynamic extent}. @dfn{Scope} refers to @emph{where} textually in
786 the source code the binding can be accessed. Indefinite scope means
787 that any part of the program can potentially access the variable
788 binding. @dfn{Extent} refers to @emph{when}, as the program is
789 executing, the binding exists. Dynamic extent means that the binding
790 lasts as long as the activation of the construct that established it.
792 The combination of dynamic extent and indefinite scope is called
793 @dfn{dynamic scoping}. By contrast, most programming languages use
794 @dfn{lexical scoping}, in which references to a local variable must be
795 located textually within the function or block that binds the variable.
797 @cindex CL note---special variables
799 @b{Common Lisp note:} Variables declared ``special'' in Common Lisp
800 are dynamically scoped, like variables in SXEmacs Lisp.
804 * Scope:: Scope means where in the program a value is visible.
805 Comparison with other languages.
806 * Extent:: Extent means how long in time a value exists.
807 * Impl of Scope:: Two ways to implement dynamic scoping.
808 * Using Scoping:: How to use dynamic scoping carefully and avoid problems.
815 SXEmacs Lisp uses @dfn{indefinite scope} for local variable bindings.
816 This means that any function anywhere in the program text might access a
817 given binding of a variable. Consider the following function
822 (defun binder (x) ; @r{@code{x} is bound in @code{binder}.}
823 (foo 5)) ; @r{@code{foo} is some other function.}
827 (defun user () ; @r{@code{x} is used in @code{user}.}
832 In a lexically scoped language, the binding of @code{x} in
833 @code{binder} would never be accessible in @code{user}, because
834 @code{user} is not textually contained within the function
835 @code{binder}. However, in dynamically scoped SXEmacs Lisp, @code{user}
836 may or may not refer to the binding of @code{x} established in
837 @code{binder}, depending on circumstances:
841 If we call @code{user} directly without calling @code{binder} at all,
842 then whatever binding of @code{x} is found, it cannot come from
846 If we define @code{foo} as follows and call @code{binder}, then the
847 binding made in @code{binder} will be seen in @code{user}:
857 If we define @code{foo} as follows and call @code{binder}, then the
858 binding made in @code{binder} @emph{will not} be seen in @code{user}:
866 Here, when @code{foo} is called by @code{binder}, it binds @code{x}.
867 (The binding in @code{foo} is said to @dfn{shadow} the one made in
868 @code{binder}.) Therefore, @code{user} will access the @code{x} bound
869 by @code{foo} instead of the one bound by @code{binder}.
876 @dfn{Extent} refers to the time during program execution that a
877 variable name is valid. In SXEmacs Lisp, a variable is valid only while
878 the form that bound it is executing. This is called @dfn{dynamic
879 extent}. ``Local'' or ``automatic'' variables in most languages,
880 including C and Pascal, have dynamic extent.
882 One alternative to dynamic extent is @dfn{indefinite extent}. This
883 means that a variable binding can live on past the exit from the form
884 that made the binding. Common Lisp and Scheme, for example, support
885 this, but SXEmacs Lisp does not.
887 To illustrate this, the function below, @code{make-add}, returns a
888 function that purports to add @var{n} to its own argument @var{m}.
889 This would work in Common Lisp, but it does not work as intended in
890 SXEmacs Lisp, because after the call to @code{make-add} exits, the
891 variable @code{n} is no longer bound to the actual argument 2.
895 (function (lambda (m) (+ n m)))) ; @r{Return a function.}
897 (fset 'add2 (make-add 2)) ; @r{Define function @code{add2}}
898 ; @r{with @code{(make-add 2)}.}
899 @result{} (lambda (m) (+ n m))
900 (add2 4) ; @r{Try to add 2 to 4.}
901 @error{} Symbol's value as variable is void: n
904 @cindex closures not available
905 Some Lisp dialects have ``closures'', objects that are like functions
906 but record additional variable bindings. SXEmacs Lisp does not have
911 @subsection Implementation of Dynamic Scoping
914 A simple sample implementation (which is not how SXEmacs Lisp actually
915 works) may help you understand dynamic binding. This technique is
916 called @dfn{deep binding} and was used in early Lisp systems.
918 Suppose there is a stack of bindings: variable-value pairs. At entry
919 to a function or to a @code{let} form, we can push bindings on the stack
920 for the arguments or local variables created there. We can pop those
921 bindings from the stack at exit from the binding construct.
923 We can find the value of a variable by searching the stack from top to
924 bottom for a binding for that variable; the value from that binding is
925 the value of the variable. To set the variable, we search for the
926 current binding, then store the new value into that binding.
928 As you can see, a function's bindings remain in effect as long as it
929 continues execution, even during its calls to other functions. That is
930 why we say the extent of the binding is dynamic. And any other function
931 can refer to the bindings, if it uses the same variables while the
932 bindings are in effect. That is why we say the scope is indefinite.
934 @cindex shallow binding
935 The actual implementation of variable scoping in SXEmacs Lisp uses a
936 technique called @dfn{shallow binding}. Each variable has a standard
937 place in which its current value is always found---the value cell of the
940 In shallow binding, setting the variable works by storing a value in
941 the value cell. Creating a new binding works by pushing the old value
942 (belonging to a previous binding) on a stack, and storing the local value
943 in the value cell. Eliminating a binding works by popping the old value
944 off the stack, into the value cell.
946 We use shallow binding because it has the same results as deep
947 binding, but runs faster, since there is never a need to search for a
952 @subsection Proper Use of Dynamic Scoping
954 Binding a variable in one function and using it in another is a
955 powerful technique, but if used without restraint, it can make programs
956 hard to understand. There are two clean ways to use this technique:
960 Use or bind the variable only in a few related functions, written close
961 together in one file. Such a variable is used for communication within
964 You should write comments to inform other programmers that they can see
965 all uses of the variable before them, and to advise them not to add uses
969 Give the variable a well-defined, documented meaning, and make all
970 appropriate functions refer to it (but not bind it or set it) wherever
971 that meaning is relevant. For example, the variable
972 @code{case-fold-search} is defined as ``non-@code{nil} means ignore case
973 when searching''; various search and replace functions refer to it
974 directly or through their subroutines, but do not bind or set it.
976 Then you can bind the variable in other programs, knowing reliably what
980 In either case, you should define the variable with @code{defvar}.
981 This helps other people understand your program by telling them to look
982 for inter-function usage. It also avoids a warning from the byte
983 compiler. Choose the variable's name to avoid name conflicts---don't
984 use short names like @code{x}.
987 @node Buffer-Local Variables
988 @section Buffer-Local Variables
989 @cindex variables, buffer-local
990 @cindex buffer-local variables
992 Global and local variable bindings are found in most programming
993 languages in one form or another. SXEmacs also supports another, unusual
994 kind of variable binding: @dfn{buffer-local} bindings, which apply only
995 to one buffer. SXEmacs Lisp is meant for programming editing commands,
996 and having different values for a variable in different buffers is an
997 important customization method.
1000 * Intro to Buffer-Local:: Introduction and concepts.
1001 * Creating Buffer-Local:: Creating and destroying buffer-local bindings.
1002 * Default Value:: The default value is seen in buffers
1003 that don't have their own local values.
1007 @node Intro to Buffer-Local
1008 @subsection Introduction to Buffer-Local Variables
1010 A buffer-local variable has a buffer-local binding associated with a
1011 particular buffer. The binding is in effect when that buffer is
1012 current; otherwise, it is not in effect. If you set the variable while
1013 a buffer-local binding is in effect, the new value goes in that binding,
1014 so the global binding is unchanged; this means that the change is
1015 visible in that buffer alone.
1017 A variable may have buffer-local bindings in some buffers but not in
1018 others. The global binding is shared by all the buffers that don't have
1019 their own bindings. Thus, if you set the variable in a buffer that does
1020 not have a buffer-local binding for it, the new value is visible in all
1021 buffers except those with buffer-local bindings. (Here we are assuming
1022 that there are no @code{let}-style local bindings to complicate the issue.)
1024 The most common use of buffer-local bindings is for major modes to change
1025 variables that control the behavior of commands. For example, C mode and
1026 Lisp mode both set the variable @code{paragraph-start} to specify that only
1027 blank lines separate paragraphs. They do this by making the variable
1028 buffer-local in the buffer that is being put into C mode or Lisp mode, and
1029 then setting it to the new value for that mode.
1031 The usual way to make a buffer-local binding is with
1032 @code{make-local-variable}, which is what major mode commands use. This
1033 affects just the current buffer; all other buffers (including those yet to
1034 be created) continue to share the global value.
1036 @cindex automatically buffer-local
1037 A more powerful operation is to mark the variable as
1038 @dfn{automatically buffer-local} by calling
1039 @code{make-variable-buffer-local}. You can think of this as making the
1040 variable local in all buffers, even those yet to be created. More
1041 precisely, the effect is that setting the variable automatically makes
1042 the variable local to the current buffer if it is not already so. All
1043 buffers start out by sharing the global value of the variable as usual,
1044 but any @code{setq} creates a buffer-local binding for the current
1045 buffer. The new value is stored in the buffer-local binding, leaving
1046 the (default) global binding untouched. The global value can no longer
1047 be changed with @code{setq}; you need to use @code{setq-default} to do
1051 Section about not changing buffers during let bindings. Mly fixed
1054 Local variables in a file you edit are also represented by
1055 buffer-local bindings for the buffer that holds the file within SXEmacs.
1056 @xref{Auto Major Mode}.
1059 @node Creating Buffer-Local
1060 @subsection Creating and Deleting Buffer-Local Bindings
1062 @deffn Command make-local-variable variable
1063 This function creates a buffer-local binding in the current buffer for
1064 @var{variable} (a symbol). Other buffers are not affected. The value
1065 returned is @var{variable}.
1068 The buffer-local value of @var{variable} starts out as the same value
1069 @var{variable} previously had. If @var{variable} was void, it remains
1074 ;; @r{In buffer @samp{b1}:}
1075 (setq foo 5) ; @r{Affects all buffers.}
1079 (make-local-variable 'foo) ; @r{Now it is local in @samp{b1}.}
1083 foo ; @r{That did not change}
1084 @result{} 5 ; @r{the value.}
1087 (setq foo 6) ; @r{Change the value}
1088 @result{} 6 ; @r{in @samp{b1}.}
1096 ;; @r{In buffer @samp{b2}, the value hasn't changed.}
1104 Making a variable buffer-local within a @code{let}-binding for that
1105 variable does not work. This is because @code{let} does not distinguish
1106 between different kinds of bindings; it knows only which variable the
1107 binding was made for.
1109 @strong{Please note:} do not use @code{make-local-variable} for a hook
1110 variable. Instead, use @code{make-local-hook}. @xref{Hooks}.
1113 @deffn Command make-variable-buffer-local variable
1114 This function marks @var{variable} (a symbol) automatically
1115 buffer-local, so that any subsequent attempt to set it will make it
1116 local to the current buffer at the time.
1118 The value returned is @var{variable}.
1121 @defun local-variable-p variable buffer &optional after-set
1122 This returns @code{t} if @var{variable} is buffer-local in buffer
1123 @var{buffer}; else @code{nil}.
1125 If optional third arg @var{after-set} is non-@code{nil}, return @code{t}
1126 if @var{symbol} would be buffer-local after it is set, regardless of
1127 whether it is so presently.
1129 A @code{nil} value for @var{buffer} is @emph{not} the same as
1130 @code{(current-buffer)}, but means "no buffer". Specifically:
1132 If @var{buffer} is @code{nil} and @var{after-set} is @code{nil}, a
1133 return value of @code{t} indicates that the variable is one of the
1134 special built-in variables that is always buffer-local. (This includes
1135 @code{buffer-file-name}, @code{buffer-read-only},
1136 @code{buffer-undo-list}, and others.)
1138 If @var{buffer} is @code{nil} and @var{after-set} is @code{t}, a return
1139 value of @code{t} indicates that the variable has had
1140 @code{make-variable-buffer-local} applied to it.
1143 @defun buffer-local-variables &optional buffer
1144 This function returns a list describing the buffer-local variables in
1145 buffer @var{buffer}. It returns an association list (@pxref{Association
1146 Lists}) in which each association contains one buffer-local variable and
1147 its value. When a buffer-local variable is void in @var{buffer}, then
1148 it appears directly in the resulting list. If @var{buffer} is omitted,
1149 the current buffer is used.
1153 (make-local-variable 'foobar)
1154 (makunbound 'foobar)
1155 (make-local-variable 'bind-me)
1158 (setq lcl (buffer-local-variables))
1159 ;; @r{First, built-in variables local in all buffers:}
1160 @result{} ((mark-active . nil)
1161 (buffer-undo-list nil)
1162 (mode-name . "Fundamental")
1165 ;; @r{Next, non-built-in local variables.}
1166 ;; @r{This one is local and void:}
1168 ;; @r{This one is local and nonvoid:}
1173 Note that storing new values into the @sc{cdr}s of cons cells in this
1174 list does @emph{not} change the local values of the variables.
1177 @deffn Command kill-local-variable variable
1178 This function deletes the buffer-local binding (if any) for
1179 @var{variable} (a symbol) in the current buffer. As a result, the
1180 global (default) binding of @var{variable} becomes visible in this
1181 buffer. Usually this results in a change in the value of
1182 @var{variable}, since the global value is usually different from the
1183 buffer-local value just eliminated.
1185 If you kill the local binding of a variable that automatically becomes
1186 local when set, this makes the global value visible in the current
1187 buffer. However, if you set the variable again, that will once again
1188 create a local binding for it.
1190 @code{kill-local-variable} returns @var{variable}.
1192 This function is a command because it is sometimes useful to kill one
1193 buffer-local variable interactively, just as it is useful to create
1194 buffer-local variables interactively.
1197 @defun kill-all-local-variables
1198 This function eliminates all the buffer-local variable bindings of the
1199 current buffer except for variables marked as ``permanent''. As a
1200 result, the buffer will see the default values of most variables.
1202 This function also resets certain other information pertaining to the
1203 buffer: it sets the local keymap to @code{nil}, the syntax table to the
1204 value of @code{standard-syntax-table}, and the abbrev table to the value
1205 of @code{fundamental-mode-abbrev-table}.
1207 Every major mode command begins by calling this function, which has the
1208 effect of switching to Fundamental mode and erasing most of the effects
1209 of the previous major mode. To ensure that this does its job, the
1210 variables that major modes set should not be marked permanent.
1212 @code{kill-all-local-variables} returns @code{nil}.
1216 @cindex permanent local variable
1217 A local variable is @dfn{permanent} if the variable name (a symbol) has a
1218 @code{permanent-local} property that is non-@code{nil}. Permanent
1219 locals are appropriate for data pertaining to where the file came from
1220 or how to save it, rather than with how to edit the contents.
1224 @subsection The Default Value of a Buffer-Local Variable
1225 @cindex default value
1227 The global value of a variable with buffer-local bindings is also
1228 called the @dfn{default} value, because it is the value that is in
1229 effect except when specifically overridden.
1231 The functions @code{default-value} and @code{setq-default} access and
1232 change a variable's default value regardless of whether the current
1233 buffer has a buffer-local binding. For example, you could use
1234 @code{setq-default} to change the default setting of
1235 @code{paragraph-start} for most buffers; and this would work even when
1236 you are in a C or Lisp mode buffer that has a buffer-local value for
1240 The special forms @code{defvar} and @code{defconst} also set the
1241 default value (if they set the variable at all), rather than any local
1244 @defun default-value symbol
1245 This function returns @var{symbol}'s default value. This is the value
1246 that is seen in buffers that do not have their own values for this
1247 variable. If @var{symbol} is not buffer-local, this is equivalent to
1248 @code{symbol-value} (@pxref{Accessing Variables}).
1252 @defun default-boundp symbol
1253 The function @code{default-boundp} tells you whether @var{symbol}'s
1254 default value is nonvoid. If @code{(default-boundp 'foo)} returns
1255 @code{nil}, then @code{(default-value 'foo)} would get an error.
1257 @code{default-boundp} is to @code{default-value} as @code{boundp} is to
1258 @code{symbol-value}.
1261 @defspec setq-default symbol value
1262 This sets the default value of @var{symbol} to @var{value}. It does not
1263 evaluate @var{symbol}, but does evaluate @var{value}. The value of the
1264 @code{setq-default} form is @var{value}.
1266 If a @var{symbol} is not buffer-local for the current buffer, and is not
1267 marked automatically buffer-local, @code{setq-default} has the same
1268 effect as @code{setq}. If @var{symbol} is buffer-local for the current
1269 buffer, then this changes the value that other buffers will see (as long
1270 as they don't have a buffer-local value), but not the value that the
1271 current buffer sees.
1275 ;; @r{In buffer @samp{foo}:}
1276 (make-local-variable 'local)
1280 (setq local 'value-in-foo)
1281 @result{} value-in-foo
1284 (setq-default local 'new-default)
1285 @result{} new-default
1289 @result{} value-in-foo
1292 (default-value 'local)
1293 @result{} new-default
1297 ;; @r{In (the new) buffer @samp{bar}:}
1299 @result{} new-default
1302 (default-value 'local)
1303 @result{} new-default
1306 (setq local 'another-default)
1307 @result{} another-default
1310 (default-value 'local)
1311 @result{} another-default
1315 ;; @r{Back in buffer @samp{foo}:}
1317 @result{} value-in-foo
1318 (default-value 'local)
1319 @result{} another-default
1324 @defun set-default symbol value
1325 This function is like @code{setq-default}, except that @var{symbol} is
1330 (set-default (car '(a b c)) 23)
1341 @node Variable Aliases
1342 @section Variable Aliases
1343 @cindex variables, indirect
1344 @cindex indirect variables
1345 @cindex variable aliases
1346 @cindex aliases, for variables
1348 You can define a variable as an @dfn{alias} for another. Any time
1349 you reference the former variable, the current value of the latter
1350 is returned. Any time you change the value of the former variable,
1351 the value of the latter is actually changed. This is useful in
1352 cases where you want to rename a variable but still make old code
1353 work (@pxref{Obsoleteness}).
1355 @defun defvaralias variable alias
1356 This function defines @var{variable} as an alias for @var{alias}.
1357 Thenceforth, any operations performed on @var{variable} will actually be
1358 performed on @var{alias}. Both @var{variable} and @var{alias} should be
1359 symbols. If @var{alias} is @code{nil}, remove any aliases for
1360 @var{variable}. @var{alias} can itself be aliased, and the chain of
1361 variable aliases will be followed appropriately. If @var{variable}
1362 already has a value, this value will be shadowed until the alias is
1363 removed, at which point it will be restored. Currently @var{variable}
1364 cannot be a built-in variable, a variable that has a buffer-local value
1365 in any buffer, or the symbols @code{nil} or @code{t}.
1368 @defun variable-alias variable &optional follow-past-lisp-magic
1369 If @var{variable} is aliased to another variable, this function returns
1370 that variable. @var{variable} should be a symbol. If @var{variable} is
1371 not aliased, this function returns @code{nil}.
1374 @defun indirect-variable object &optional follow-past-lisp-magic
1375 This function returns the variable at the end of @var{object}'s
1376 variable-alias chain. If @var{object} is a symbol, follow all variable
1377 aliases and return the final (non-aliased) symbol. If @var{object} is
1378 not a symbol, just return it. Signal a
1379 @code{cyclic-variable-indirection} error if there is a loop in the
1380 variable chain of symbols.