comparison lispref/variables.texi @ 6510:e18202af3602

Initial revision
author Richard M. Stallman <rms@gnu.org>
date Thu, 24 Mar 1994 17:24:15 +0000
parents
children 3112fb627aa0
comparison
equal deleted inserted replaced
6509:9ab67b3b597a 6510:e18202af3602
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/variables
6 @node Variables, Functions, Control Structures, Top
7 @chapter Variables
8 @cindex variable
9
10 A @dfn{variable} is a name used in a program to stand for a value.
11 Nearly all programming languages have variables of some sort. In the
12 text of a Lisp program, variables are written using the syntax for
13 symbols.
14
15 In Lisp, unlike most programming languages, programs are represented
16 primarily as Lisp objects and only secondarily as text. The Lisp
17 objects used for variables are symbols: the symbol name is the variable
18 name, and the variable's value is stored in the value cell of the
19 symbol. The use of a symbol as a variable is independent of its use as
20 a function name. @xref{Symbol Components}.
21
22 The Lisp objects that constitute a Lisp program determine the textual
23 form of the program--it is simply the read syntax for those Lisp
24 objects. This is why, for example, a variable in a textual Lisp program
25 is written using the read syntax for the symbol that represents the
26 variable.
27
28 @menu
29 * Global Variables:: Variable values that exist permanently, everywhere.
30 * Constant Variables:: Certain "variables" have values that never change.
31 * Local Variables:: Variable values that exist only temporarily.
32 * Void Variables:: Symbols that lack values.
33 * Defining Variables:: A definition says a symbol is used as a variable.
34 * Accessing Variables:: Examining values of variables whose names
35 are known only at run time.
36 * Setting Variables:: Storing new values in variables.
37 * Variable Scoping:: How Lisp chooses among local and global values.
38 * Buffer-Local Variables:: Variable values in effect only in one buffer.
39 @end menu
40
41 @node Global Variables
42 @section Global Variables
43 @cindex global variable
44
45 The simplest way to use a variable is @dfn{globally}. This means that
46 the variable has just one value at a time, and this value is in effect
47 (at least for the moment) throughout the Lisp system. The value remains
48 in effect until you specify a new one. When a new value replaces the
49 old one, no trace of the old value remains in the variable.
50
51 You specify a value for a symbol with @code{setq}. For example,
52
53 @example
54 (setq x '(a b))
55 @end example
56
57 @noindent
58 gives the variable @code{x} the value @code{(a b)}. Note that
59 @code{setq} does not evaluate its first argument, the name of the
60 variable, but it does evaluate the second argument, the new value.
61
62 Once the variable has a value, you can refer to it by using the symbol
63 by itself as an expression. Thus,
64
65 @example
66 @group
67 x @result{} (a b)
68 @end group
69 @end example
70
71 @noindent
72 assuming the @code{setq} form shown above has already been executed.
73
74 If you do another @code{setq}, the new value replaces the old one:
75
76 @example
77 @group
78 x
79 @result{} (a b)
80 @end group
81 @group
82 (setq x 4)
83 @result{} 4
84 @end group
85 @group
86 x
87 @result{} 4
88 @end group
89 @end example
90
91 @node Constant Variables
92 @section Variables That Never Change
93 @vindex nil
94 @vindex t
95 @kindex setting-constant
96
97 Emacs Lisp has two special symbols, @code{nil} and @code{t}, that
98 always evaluate to themselves. These symbols cannot be rebound, nor can
99 their value cells be changed. An attempt to change the value of
100 @code{nil} or @code{t} signals a @code{setting-constant} error.
101
102 @example
103 @group
104 nil @equiv{} 'nil
105 @result{} nil
106 @end group
107 @group
108 (setq nil 500)
109 @error{} Attempt to set constant symbol: nil
110 @end group
111 @end example
112
113 @node Local Variables
114 @section Local Variables
115 @cindex binding local variables
116 @cindex local variables
117 @cindex local binding
118 @cindex global binding
119
120 Global variables have values that last until explicitly superseded
121 with new values. Sometimes it is useful to create variable values that
122 exist temporarily---only while within a certain part of the program.
123 These values are called @dfn{local}, and the variables so used are
124 called @dfn{local variables}.
125
126 For example, when a function is called, its argument variables receive
127 new local values that last until the function exits. The @code{let}
128 special form explicitly establishes new local values for specified
129 variables; these last until exit from the @code{let} form.
130
131 @cindex shadowing of variables
132 Establishing a local value saves away the previous value (or lack of
133 one) of the variable. When the life span of the local value is over,
134 the previous value is restored. In the mean time, we say that the
135 previous value is @dfn{shadowed} and @dfn{not visible}. Both global and
136 local values may be shadowed (@pxref{Scope}).
137
138 If you set a variable (such as with @code{setq}) while it is local,
139 this replaces the local value; it does not alter the global value, or
140 previous local values that are shadowed. To model this behavior, we
141 speak of a @dfn{local binding} of the variable as well as a local value.
142
143 The local binding is a conceptual place that holds a local value.
144 Entry to a function, or a special form such as @code{let}, creates the
145 local binding; exit from the function or from the @code{let} removes the
146 local binding. As long as the local binding lasts, the variable's value
147 is stored within it. Use of @code{setq} or @code{set} while there is a
148 local binding stores a different value into the local binding; it does
149 not create a new binding.
150
151 We also speak of the @dfn{global binding}, which is where
152 (conceptually) the global value is kept.
153
154 @cindex current binding
155 A variable can have more than one local binding at a time (for
156 example, if there are nested @code{let} forms that bind it). In such a
157 case, the most recently created local binding that still exists is the
158 @dfn{current binding} of the variable. (This is called @dfn{dynamic
159 scoping}; see @ref{Variable Scoping}.) If there are no local bindings,
160 the variable's global binding is its current binding. We also call the
161 current binding the @dfn{most-local existing binding}, for emphasis.
162 Ordinary evaluation of a symbol always returns the value of its current
163 binding.
164
165 The special forms @code{let} and @code{let*} exist to create
166 local bindings.
167
168 @defspec let (bindings@dots{}) forms@dots{}
169 This function binds variables according to @var{bindings} and then
170 evaluates all of the @var{forms} in textual order. The @code{let}-form
171 returns the value of the last form in @var{forms}.
172
173 Each of the @var{bindings} is either @w{(i) a} symbol, in which case
174 that symbol is bound to @code{nil}; or @w{(ii) a} list of the form
175 @code{(@var{symbol} @var{value-form})}, in which case @var{symbol} is
176 bound to the result of evaluating @var{value-form}. If @var{value-form}
177 is omitted, @code{nil} is used.
178
179 All of the @var{value-form}s in @var{bindings} are evaluated in the
180 order they appear and @emph{before} any of the symbols are bound. Here
181 is an example of this: @code{Z} is bound to the old value of @code{Y},
182 which is 2, not the new value, 1.
183
184 @example
185 @group
186 (setq Y 2)
187 @result{} 2
188 @end group
189 @group
190 (let ((Y 1)
191 (Z Y))
192 (list Y Z))
193 @result{} (1 2)
194 @end group
195 @end example
196 @end defspec
197
198 @defspec let* (bindings@dots{}) forms@dots{}
199 This special form is like @code{let}, but it binds each variable right
200 after computing its local value, before computing the local value for
201 the next variable. Therefore, an expression in @var{bindings} can
202 reasonably refer to the preceding symbols bound in this @code{let*}
203 form. Compare the following example with the example above for
204 @code{let}.
205
206 @example
207 @group
208 (setq Y 2)
209 @result{} 2
210 @end group
211 @group
212 (let* ((Y 1)
213 (Z Y)) ; @r{Use the just-established value of @code{Y}.}
214 (list Y Z))
215 @result{} (1 1)
216 @end group
217 @end example
218 @end defspec
219
220 Here is a complete list of the other facilities which create local
221 bindings:
222
223 @itemize @bullet
224 @item
225 Function calls (@pxref{Functions}).
226
227 @item
228 Macro calls (@pxref{Macros}).
229
230 @item
231 @code{condition-case} (@pxref{Errors}).
232 @end itemize
233
234 @defvar max-specpdl-size
235 @cindex variable limit error
236 @cindex evaluation error
237 @cindex infinite recursion
238 This variable defines the limit on the total number of local variable
239 bindings and @code{unwind-protect} cleanups (@pxref{Nonlocal Exits})
240 that are allowed before signaling an error (with data @code{"Variable
241 binding depth exceeds max-specpdl-size"}).
242
243 This limit, with the associated error when it is exceeded, is one way
244 that Lisp avoids infinite recursion on an ill-defined function.
245
246 The default value is 600.
247
248 @code{max-lisp-eval-depth} provides another limit on depth of nesting.
249 @xref{Eval}.
250 @end defvar
251
252 @node Void Variables
253 @section When a Variable is ``Void''
254 @kindex void-variable
255 @cindex void variable
256
257 If you have never given a symbol any value as a global variable, we
258 say that that symbol's global value is @dfn{void}. In other words, the
259 symbol's value cell does not have any Lisp object in it. If you try to
260 evaluate the symbol, you get a @code{void-variable} error rather than
261 a value.
262
263 Note that a value of @code{nil} is not the same as void. The symbol
264 @code{nil} is a Lisp object and can be the value of a variable just as any
265 other object can be; but it is @emph{a value}. A void variable does not
266 have any value.
267
268 After you have given a variable a value, you can make it void once more
269 using @code{makunbound}.
270
271 @defun makunbound symbol
272 This function makes the current binding of @var{symbol} void.
273 Subsequent attempts to use this symbol's value as a variable will signal
274 the error @code{void-variable}, unless or until you set it again.
275
276 @code{makunbound} returns @var{symbol}.
277
278 @example
279 @group
280 (makunbound 'x) ; @r{Make the global value}
281 ; @r{of @code{x} void.}
282 @result{} x
283 @end group
284 @group
285 x
286 @error{} Symbol's value as variable is void: x
287 @end group
288 @end example
289
290 If @var{symbol} is locally bound, @code{makunbound} affects the most
291 local existing binding. This is the only way a symbol can have a void
292 local binding, since all the constructs that create local bindings
293 create them with values. In this case, the voidness lasts at most as
294 long as the binding does; when the binding is removed due to exit from
295 the construct that made it, the previous or global binding is reexposed
296 as usual, and the variable is no longer void unless the newly reexposed
297 binding was void all along.
298
299 @smallexample
300 @group
301 (setq x 1) ; @r{Put a value in the global binding.}
302 @result{} 1
303 (let ((x 2)) ; @r{Locally bind it.}
304 (makunbound 'x) ; @r{Void the local binding.}
305 x)
306 @error{} Symbol's value as variable is void: x
307 @end group
308 @group
309 x ; @r{The global binding is unchanged.}
310 @result{} 1
311
312 (let ((x 2)) ; @r{Locally bind it.}
313 (let ((x 3)) ; @r{And again.}
314 (makunbound 'x) ; @r{Void the innermost-local binding.}
315 x)) ; @r{And refer: it's void.}
316 @error{} Symbol's value as variable is void: x
317 @end group
318
319 @group
320 (let ((x 2))
321 (let ((x 3))
322 (makunbound 'x)) ; @r{Void inner binding, then remove it.}
323 x) ; @r{Now outer @code{let} binding is visible.}
324 @result{} 2
325 @end group
326 @end smallexample
327 @end defun
328
329 A variable that has been made void with @code{makunbound} is
330 indistinguishable from one that has never received a value and has
331 always been void.
332
333 You can use the function @code{boundp} to test whether a variable is
334 currently void.
335
336 @defun boundp variable
337 @code{boundp} returns @code{t} if @var{variable} (a symbol) is not void;
338 more precisely, if its current binding is not void. It returns
339 @code{nil} otherwise.
340
341 @smallexample
342 @group
343 (boundp 'abracadabra) ; @r{Starts out void.}
344 @result{} nil
345 @end group
346 @group
347 (let ((abracadabra 5)) ; @r{Locally bind it.}
348 (boundp 'abracadabra))
349 @result{} t
350 @end group
351 @group
352 (boundp 'abracadabra) ; @r{Still globally void.}
353 @result{} nil
354 @end group
355 @group
356 (setq abracadabra 5) ; @r{Make it globally nonvoid.}
357 @result{} 5
358 @end group
359 @group
360 (boundp 'abracadabra)
361 @result{} t
362 @end group
363 @end smallexample
364 @end defun
365
366 @node Defining Variables
367 @section Defining Global Variables
368
369 You may announce your intention to use a symbol as a global variable
370 with a definition, using @code{defconst} or @code{defvar}.
371
372 In Emacs Lisp, definitions serve three purposes. First, they inform
373 people who read the code that certain symbols are @emph{intended} to be
374 used a certain way (as variables). Second, they inform the Lisp system
375 of these things, supplying a value and documentation. Third, they
376 provide information to utilities such as @code{etags} and
377 @code{make-docfile}, which create data bases of the functions and
378 variables in a program.
379
380 The difference between @code{defconst} and @code{defvar} is primarily
381 a matter of intent, serving to inform human readers of whether programs
382 will change the variable. Emacs Lisp does not restrict the ways in
383 which a variable can be used based on @code{defconst} or @code{defvar}
384 declarations. However, it also makes a difference for initialization:
385 @code{defconst} unconditionally initializes the variable, while
386 @code{defvar} initializes it only if it is void.
387
388 One would expect user option variables to be defined with
389 @code{defconst}, since programs do not change them. Unfortunately, this
390 has bad results if the definition is in a library that is not preloaded:
391 @code{defconst} would override any prior value when the library is
392 loaded. Users would like to be able to set user options in their init
393 files, and override the default values given in the definitions. For
394 this reason, user options must be defined with @code{defvar}.
395
396 @defspec defvar symbol [value [doc-string]]
397 This special form defines @var{symbol} as a value and initializes it.
398 The definition informs a person reading your code that @var{symbol} is
399 used as a variable that programs are likely to set or change. It is
400 also used for all user option variables except in the preloaded parts of
401 Emacs. Note that @var{symbol} is not evaluated; the symbol to be
402 defined must appear explicitly in the @code{defvar}.
403
404 If @var{symbol} already has a value (i.e., it is not void), @var{value}
405 is not even evaluated, and @var{symbol}'s value remains unchanged. If
406 @var{symbol} is void and @var{value} is specified, @code{defvar}
407 evaluates it and sets @var{symbol} to the result. (If @var{value} is
408 omitted, the value of @var{symbol} is not changed in any case.)
409
410 If @var{symbol} has a buffer-local binding in the current buffer,
411 @code{defvar} sets the default value, not the local value.
412 @xref{Buffer-Local Variables}.
413
414 If the @var{doc-string} argument appears, it specifies the documentation
415 for the variable. (This opportunity to specify documentation is one of
416 the main benefits of defining the variable.) The documentation is
417 stored in the symbol's @code{variable-documentation} property. The
418 Emacs help functions (@pxref{Documentation}) look for this property.
419
420 If the first character of @var{doc-string} is @samp{*}, it means that
421 this variable is considered a user option. This lets users set the
422 variable conventiently using the commands @code{set-variable} and
423 @code{edit-options}.
424
425 For example, this form defines @code{foo} but does not set its value:
426
427 @example
428 @group
429 (defvar foo)
430 @result{} foo
431 @end group
432 @end example
433
434 The following example sets the value of @code{bar} to @code{23}, and
435 gives it a documentation string:
436
437 @example
438 @group
439 (defvar bar 23
440 "The normal weight of a bar.")
441 @result{} bar
442 @end group
443 @end example
444
445 The following form changes the documentation string for @code{bar},
446 making it a user option, but does not change the value, since @code{bar}
447 already has a value. (The addition @code{(1+ 23)} is not even
448 performed.)
449
450 @example
451 @group
452 (defvar bar (1+ 23)
453 "*The normal weight of a bar.")
454 @result{} bar
455 @end group
456 @group
457 bar
458 @result{} 23
459 @end group
460 @end example
461
462 Here is an equivalent expression for the @code{defvar} special form:
463
464 @example
465 @group
466 (defvar @var{symbol} @var{value} @var{doc-string})
467 @equiv{}
468 (progn
469 (if (not (boundp '@var{symbol}))
470 (setq @var{symbol} @var{value}))
471 (put '@var{symbol} 'variable-documentation '@var{doc-string})
472 '@var{symbol})
473 @end group
474 @end example
475
476 The @code{defvar} form returns @var{symbol}, but it is normally used
477 at top level in a file where its value does not matter.
478 @end defspec
479
480 @defspec defconst symbol [value [doc-string]]
481 This special form defines @var{symbol} as a value and initializes it.
482 It informs a person reading your code that @var{symbol} has a global
483 value, established here, that will not normally be changed or locally
484 bound by the execution of the program. The user, however, may be
485 welcome to change it. Note that @var{symbol} is not evaluated; the
486 symbol to be defined must appear explicitly in the @code{defconst}.
487
488 @code{defconst} always evaluates @var{value} and sets the global value
489 of @var{symbol} to the result, provided @var{value} is given. If
490 @var{symbol} has a buffer-local binding in the current buffer,
491 @code{defconst} sets the default value, not the local value.
492
493 @strong{Please note:} don't use @code{defconst} for user option
494 variables in libraries that are not standardly preloaded. The user
495 should be able to specify a value for such a variable in the
496 @file{.emacs} file, so that it will be in effect if and when the library
497 is loaded later.
498
499 Here, @code{pi} is a constant that presumably ought not to be changed
500 by anyone (attempts by the Indiana State Legislature notwithstanding).
501 As the second form illustrates, however, this is only advisory.
502
503 @example
504 @group
505 (defconst pi 3.1415 "Pi to five places.")
506 @result{} pi
507 @end group
508 @group
509 (setq pi 3)
510 @result{} pi
511 @end group
512 @group
513 pi
514 @result{} 3
515 @end group
516 @end example
517 @end defspec
518
519 @defun user-variable-p variable
520 @cindex user option
521 This function returns @code{t} if @var{variable} is a user option--- a
522 variable intended to be set by the user for customization---and
523 @code{nil} otherwise. (Variables other than user options exist for the
524 internal purposes of Lisp programs, and users need not know about them.)
525
526 User option variables are distinguished from other variables by the
527 first character of the @code{variable-documentation} property. If the
528 property exists and is a string, and its first character is @samp{*},
529 then the variable is a user option.
530 @end defun
531
532 If a user option variable has a @code{variable-interactive} property,
533 @code{set-variable} uses that value to control reading the new value for
534 the variable. The property's value is used as if it were the argument
535 to @code{interactive}.
536
537 @strong{Warning:} if the @code{defconst} and @code{defvar} special
538 forms are used while the variable has a local binding, they set the
539 local binding's value; the global binding is not changed. This is not
540 what we really want. To prevent it, use these special forms at top
541 level in a file, where normally no local binding is in effect, and make
542 sure to load the file before making a local binding for the variable.
543
544 @node Accessing Variables
545 @section Accessing Variable Values
546
547 The usual way to reference a variable is to write the symbol which
548 names it (@pxref{Symbol Forms}). This requires you to specify the
549 variable name when you write the program. Usually that is exactly what
550 you want to do. Occasionally you need to choose at run time which
551 variable to reference; then you can use @code{symbol-value}.
552
553 @defun symbol-value symbol
554 This function returns the value of @var{symbol}. This is the value in
555 the innermost local binding of the symbol, or its global value if it
556 has no local bindings.
557
558 @example
559 @group
560 (setq abracadabra 5)
561 @result{} 5
562 @end group
563 @group
564 (setq foo 9)
565 @result{} 9
566 @end group
567
568 @group
569 ;; @r{Here the symbol @code{abracadabra}}
570 ;; @r{is the symbol whose value is examined.}
571 (let ((abracadabra 'foo))
572 (symbol-value 'abracadabra))
573 @result{} foo
574 @end group
575
576 @group
577 ;; @r{Here the value of @code{abracadabra},}
578 ;; @r{which is @code{foo},}
579 ;; @r{is the symbol whose value is examined.}
580 (let ((abracadabra 'foo))
581 (symbol-value abracadabra))
582 @result{} 9
583 @end group
584
585 @group
586 (symbol-value 'abracadabra)
587 @result{} 5
588 @end group
589 @end example
590
591 A @code{void-variable} error is signaled if @var{symbol} has neither a
592 local binding nor a global value.
593 @end defun
594
595 @node Setting Variables
596 @section How to Alter a Variable Value
597
598 The usual way to change the value of a variable is with the special
599 form @code{setq}. When you need to compute the choice of variable at
600 run time, use the function @code{set}.
601
602 @defspec setq [symbol form]@dots{}
603 This special form is the most common method of changing a variable's
604 value. Each @var{symbol} is given a new value, which is the result of
605 evaluating the corresponding @var{form}. The most-local existing
606 binding of the symbol is changed.
607
608 @code{setq} does not evaluate @var{symbol}; it sets the symbol that you
609 write. We say that this argument is @dfn{automatically quoted}. The
610 @samp{q} in @code{setq} stands for ``quoted.''
611
612 The value of the @code{setq} form is the value of the last @var{form}.
613
614 @example
615 @group
616 (setq x (1+ 2))
617 @result{} 3
618 @end group
619 x ; @r{@code{x} now has a global value.}
620 @result{} 3
621 @group
622 (let ((x 5))
623 (setq x 6) ; @r{The local binding of @code{x} is set.}
624 x)
625 @result{} 6
626 @end group
627 x ; @r{The global value is unchanged.}
628 @result{} 3
629 @end example
630
631 Note that the first @var{form} is evaluated, then the first
632 @var{symbol} is set, then the second @var{form} is evaluated, then the
633 second @var{symbol} is set, and so on:
634
635 @example
636 @group
637 (setq x 10 ; @r{Notice that @code{x} is set before}
638 y (1+ x)) ; @r{the value of @code{y} is computed.}
639 @result{} 11
640 @end group
641 @end example
642 @end defspec
643
644 @defun set symbol value
645 This function sets @var{symbol}'s value to @var{value}, then returns
646 @var{value}. Since @code{set} is a function, the expression written for
647 @var{symbol} is evaluated to obtain the symbol to set.
648
649 The most-local existing binding of the variable is the binding that is
650 set; shadowed bindings are not affected. If @var{symbol} is not
651 actually a symbol, a @code{wrong-type-argument} error is signaled.
652
653 @example
654 @group
655 (set one 1)
656 @error{} Symbol's value as variable is void: one
657 @end group
658 @group
659 (set 'one 1)
660 @result{} 1
661 @end group
662 @group
663 (set 'two 'one)
664 @result{} one
665 @end group
666 @group
667 (set two 2) ; @r{@code{two} evaluates to symbol @code{one}.}
668 @result{} 2
669 @end group
670 @group
671 one ; @r{So it is @code{one} that was set.}
672 @result{} 2
673 (let ((one 1)) ; @r{This binding of @code{one} is set,}
674 (set 'one 3) ; @r{not the global value.}
675 one)
676 @result{} 3
677 @end group
678 @group
679 one
680 @result{} 2
681 @end group
682 @end example
683
684 Logically speaking, @code{set} is a more fundamental primitive than
685 @code{setq}. Any use of @code{setq} can be trivially rewritten to use
686 @code{set}; @code{setq} could even be defined as a macro, given the
687 availability of @code{set}. However, @code{set} itself is rarely used;
688 beginners hardly need to know about it. It is needed for choosing which
689 variable to set is made at run time. For example, the command
690 @code{set-variable}, which reads a variable name from the user and then
691 sets the variable, needs to use @code{set}.
692
693 @cindex CL note---@code{set} local
694 @quotation
695 @b{Common Lisp note:} in Common Lisp, @code{set} always changes the
696 symbol's special value, ignoring any lexical bindings. In Emacs Lisp,
697 all variables and all bindings are (in effect) special, so @code{set}
698 always affects the most local existing binding.
699 @end quotation
700 @end defun
701
702 @node Variable Scoping
703 @section Scoping Rules for Variable Bindings
704
705 A given symbol @code{foo} may have several local variable bindings,
706 established at different places in the Lisp program, as well as a global
707 binding. The most recently established binding takes precedence over
708 the others.
709
710 @cindex scope
711 @cindex extent
712 @cindex dynamic scoping
713 Local bindings in Emacs Lisp have @dfn{indefinite scope} and
714 @dfn{dynamic extent}. @dfn{Scope} refers to @emph{where} textually in
715 the source code the binding can be accessed. Indefinite scope means
716 that any part of the program can potentially access the variable
717 binding. @dfn{Extent} refers to @emph{when}, as the program is
718 executing, the binding exists. Dynamic extent means that the binding
719 lasts as long as the activation of the construct that established it.
720
721 The combination of dynamic extent and indefinite scope is called
722 @dfn{dynamic scoping}. By contrast, most programming languages use
723 @dfn{lexical scoping}, in which references to a local variable must be
724 located textually within the function or block that binds the variable.
725
726 @cindex CL note---special variables
727 @quotation
728 @b{Common Lisp note:} variables declared ``special'' in Common Lisp
729 are dynamically scoped like variables in Emacs Lisp.
730 @end quotation
731
732 @menu
733 * Scope:: Scope means where in the program a value is visible.
734 Comparison with other languages.
735 * Extent:: Extent means how long in time a value exists.
736 * Impl of Scope:: Two ways to implement dynamic scoping.
737 * Using Scoping:: How to use dynamic scoping carefully and avoid problems.
738 @end menu
739
740 @node Scope
741 @subsection Scope
742
743 Emacs Lisp uses @dfn{indefinite scope} for local variable bindings.
744 This means that any function anywhere in the program text might access a
745 given binding of a variable. Consider the following function
746 definitions:
747
748 @example
749 @group
750 (defun binder (x) ; @r{@code{x} is bound in @code{binder}.}
751 (foo 5)) ; @r{@code{foo} is some other function.}
752 @end group
753
754 @group
755 (defun user () ; @r{@code{x} is used in @code{user}.}
756 (list x))
757 @end group
758 @end example
759
760 In a lexically scoped language, the binding of @code{x} in
761 @code{binder} would never be accessible in @code{user}, because
762 @code{user} is not textually contained within the function
763 @code{binder}. However, in dynamically scoped Emacs Lisp, @code{user}
764 may or may not refer to the binding of @code{x} established in
765 @code{binder}, depending on circumstances:
766
767 @itemize @bullet
768 @item
769 If we call @code{user} directly without calling @code{binder} at all,
770 then whatever binding of @code{x} is found, it cannot come from
771 @code{binder}.
772
773 @item
774 If we define @code{foo} as follows and call @code{binder}, then the
775 binding made in @code{binder} will be seen in @code{user}:
776
777 @example
778 @group
779 (defun foo (lose)
780 (user))
781 @end group
782 @end example
783
784 @item
785 If we define @code{foo} as follows and call @code{binder}, then the
786 binding made in @code{binder} @emph{will not} be seen in @code{user}:
787
788 @example
789 (defun foo (x)
790 (user))
791 @end example
792
793 @noindent
794 Here, when @code{foo} is called by @code{binder}, it binds @code{x}.
795 (The binding in @code{foo} is said to @dfn{shadow} the one made in
796 @code{binder}.) Therefore, @code{user} will access the @code{x} bound
797 by @code{foo} instead of the one bound by @code{binder}.
798 @end itemize
799
800 @node Extent
801 @subsection Extent
802
803 @dfn{Extent} refers to the time during program execution that a
804 variable name is valid. In Emacs Lisp, a variable is valid only while
805 the form that bound it is executing. This is called @dfn{dynamic
806 extent}. ``Local'' or ``automatic'' variables in most languages,
807 including C and Pascal, have dynamic extent.
808
809 One alternative to dynamic extent is @dfn{indefinite extent}. This
810 means that a variable binding can live on past the exit from the form
811 that made the binding. Common Lisp and Scheme, for example, support
812 this, but Emacs Lisp does not.
813
814 To illustrate this, the function below, @code{make-add}, returns a
815 function that purports to add @var{n} to its own argument @var{m}.
816 This would work in Common Lisp, but it does not work as intended in
817 Emacs Lisp, because after the call to @code{make-add} exits, the
818 variable @code{n} is no longer bound to the actual argument 2.
819
820 @example
821 (defun make-add (n)
822 (function (lambda (m) (+ n m)))) ; @r{Return a function.}
823 @result{} make-add
824 (fset 'add2 (make-add 2)) ; @r{Define function @code{add2}}
825 ; @r{with @code{(make-add 2)}.}
826 @result{} (lambda (m) (+ n m))
827 (add2 4) ; @r{Try to add 2 to 4.}
828 @error{} Symbol's value as variable is void: n
829 @end example
830
831 @cindex closures not available
832 Some Lisp dialects have ``closures'', objects that are like functions
833 but record additional variable bindings. Emacs Lisp does not have
834 closures.
835
836 @node Impl of Scope
837 @subsection Implementation of Dynamic Scoping
838 @cindex deep binding
839
840 A simple sample implementation (which is not how Emacs Lisp actually
841 works) may help you understand dynamic binding. This technique is
842 called @dfn{deep binding} and was used in early Lisp systems.
843
844 Suppose there is a stack of bindings: variable-value pairs. At entry
845 to a function or to a @code{let} form, we can push bindings on the stack
846 for the arguments or local variables created there. We can pop those
847 bindings from the stack at exit from the binding construct.
848
849 We can find the value of a variable by searching the stack from top to
850 bottom for a binding for that variable; the value from that binding is
851 the value of the variable. To set the variable, we search for the
852 current binding, then store the new value into that binding.
853
854 As you can see, a function's bindings remain in effect as long as it
855 continues execution, even during its calls to other functions. That is
856 why we say the extent of the binding is dynamic. And any other function
857 can refer to the bindings, if it uses the same variables while the
858 bindings are in effect. That is why we say the scope is indefinite.
859
860 @cindex shallow binding
861 The actual implementation of variable scoping in GNU Emacs Lisp uses a
862 technique called @dfn{shallow binding}. Each variable has a standard
863 place in which its current value is always found---the value cell of the
864 symbol.
865
866 In shallow binding, setting the variable works by storing a value in
867 the value cell. Creating a new binding works by pushing the old value
868 (belonging to a previous binding) on a stack, and storing the local value
869 in the value cell. Eliminating a binding works by popping the old value
870 off the stack, into the value cell.
871
872 We use shallow binding because it has the same results as deep
873 binding, but runs faster, since there is never a need to search for a
874 binding.
875
876 @node Using Scoping
877 @subsection Proper Use of Dynamic Scoping
878
879 Binding a variable in one function and using it in another is a
880 powerful technique, but if used without restraint, it can make programs
881 hard to understand. There are two clean ways to use this technique:
882
883 @itemize @bullet
884 @item
885 Use or bind the variable only in a few related functions, written close
886 together in one file. Such a variable is used for communication within
887 one program.
888
889 You should write comments to inform other programmers that they can see
890 all uses of the variable before them, and to advise them not to add uses
891 elsewhere.
892
893 @item
894 Give the variable a well-defined, documented meaning, and make all
895 appropriate functions refer to it (but not bind it or set it) wherever
896 that meaning is relevant. For example, the variable
897 @code{case-fold-search} is defined as ``non-@code{nil} means ignore case
898 when searching''; various search and replace functions refer to it
899 directly or through their subroutines, but do not bind or set it.
900
901 Then you can bind the variable in other programs, knowing reliably what
902 the effect will be.
903 @end itemize
904
905 @node Buffer-Local Variables
906 @section Buffer-Local Variables
907 @cindex variables, buffer-local
908 @cindex buffer-local variables
909
910 Global and local variable bindings are found in most programming
911 languages in one form or another. Emacs also supports another, unusual
912 kind of variable binding: @dfn{buffer-local} bindings, which apply only
913 to one buffer. Emacs Lisp is meant for programming editing commands,
914 and having different values for a variable in different buffers is an
915 important customization method.
916
917 @menu
918 * Intro to Buffer-Local:: Introduction and concepts.
919 * Creating Buffer-Local:: Creating and destroying buffer-local bindings.
920 * Default Value:: The default value is seen in buffers
921 that don't have their own local values.
922 @end menu
923
924 @node Intro to Buffer-Local
925 @subsection Introduction to Buffer-Local Variables
926
927 A buffer-local variable has a buffer-local binding associated with a
928 particular buffer. The binding is in effect when that buffer is
929 current; otherwise, it is not in effect. If you set the variable while
930 a buffer-local binding is in effect, the new value goes in that binding,
931 so the global binding is unchanged; this means that the change is
932 visible in that buffer alone.
933
934 A variable may have buffer-local bindings in some buffers but not in
935 others. The global binding is shared by all the buffers that don't have
936 their own bindings. Thus, if you set the variable in a buffer that does
937 not have a buffer-local binding for it, the new value is visible in all
938 buffers except those with buffer-local bindings. (Here we are assuming
939 that there are no @code{let}-style local bindings to complicate the issue.)
940
941 The most common use of buffer-local bindings is for major modes to change
942 variables that control the behavior of commands. For example, C mode and
943 Lisp mode both set the variable @code{paragraph-start} to specify that only
944 blank lines separate paragraphs. They do this by making the variable
945 buffer-local in the buffer that is being put into C mode or Lisp mode, and
946 then setting it to the new value for that mode.
947
948 The usual way to make a buffer-local binding is with
949 @code{make-local-variable}, which is what major mode commands use. This
950 affects just the current buffer; all other buffers (including those yet to
951 be created) continue to share the global value.
952
953 @cindex automatically buffer-local
954 A more powerful operation is to mark the variable as
955 @dfn{automatically buffer-local} by calling
956 @code{make-variable-buffer-local}. You can think of this as making the
957 variable local in all buffers, even those yet to be created. More
958 precisely, the effect is that setting the variable automatically makes
959 the variable local to the current buffer if it is not already so. All
960 buffers start out by sharing the global value of the variable as usual,
961 but any @code{setq} creates a buffer-local binding for the current
962 buffer. The new value is stored in the buffer-local binding, leaving
963 the (default) global binding untouched. The global value can no longer
964 be changed with @code{setq}; you need to use @code{setq-default} to do
965 that.
966
967 @strong{Warning:} when a variable has local values in one or more
968 buffers, you can get Emacs very confused by binding the variable with
969 @code{let}, changing to a different current buffer in which a different
970 binding is in effect, and then exiting the @code{let}. This can
971 scramble the values of the global and local bindings.
972
973 To preserve your sanity, avoid that series of actions. If you use
974 @code{save-excursion} around each piece of code that changes to a
975 different current buffer, you will not have this problem. Here is an
976 example of what to avoid:
977
978 @example
979 @group
980 (setq foo 'b)
981 (set-buffer "a")
982 (make-local-variable 'foo)
983 @end group
984 (setq foo 'a)
985 (let ((foo 'temp))
986 (set-buffer "b")
987 @dots{})
988 @group
989 foo @result{} 'a ; @r{The old buffer-local value from buffer @samp{a}}
990 ; @r{is now the default value.}
991 @end group
992 @group
993 (set-buffer "a")
994 foo @result{} 'temp ; @r{The local value that should be gone}
995 ; @r{is now the buffer-local value in buffer @samp{a}.}
996 @end group
997 @end example
998
999 @noindent
1000 But @code{save-excursion} as shown here avoids the problem:
1001
1002 @example
1003 @group
1004 (let ((foo 'temp))
1005 (save-excursion
1006 (set-buffer "b")
1007 @var{body}@dots{}))
1008 @end group
1009 @end example
1010
1011 Note that references to @code{foo} in @var{body} access the
1012 buffer-local binding of buffer @samp{b}.
1013
1014 When a file specifies local variable values, these become buffer-local
1015 value when you visit the file. @xref{Auto Major Mode}.
1016
1017 @node Creating Buffer-Local
1018 @subsection Creating and Deleting Buffer-Local Bindings
1019
1020 @deffn Command make-local-variable variable
1021 This function creates a buffer-local binding in the current buffer for
1022 @var{variable} (a symbol). Other buffers are not affected. The value
1023 returned is @var{variable}.
1024
1025 @c Emacs 19 feature
1026 The buffer-local value of @var{variable} starts out as the same value
1027 @var{variable} previously had. If @var{variable} was void, it remains
1028 void.
1029
1030 @example
1031 @group
1032 ;; @r{In buffer @samp{b1}:}
1033 (setq foo 5) ; @r{Affects all buffers.}
1034 @result{} 5
1035 @end group
1036 @group
1037 (make-local-variable 'foo) ; @r{Now it is local in @samp{b1}.}
1038 @result{} foo
1039 @end group
1040 @group
1041 foo ; @r{That did not change}
1042 @result{} 5 ; @r{the value.}
1043 @end group
1044 @group
1045 (setq foo 6) ; @r{Change the value}
1046 @result{} 6 ; @r{in @samp{b1}.}
1047 @end group
1048 @group
1049 foo
1050 @result{} 6
1051 @end group
1052
1053 @group
1054 ;; @r{In buffer @samp{b2}, the value hasn't changed.}
1055 (save-excursion
1056 (set-buffer "b2")
1057 foo)
1058 @result{} 5
1059 @end group
1060 @end example
1061 @end deffn
1062
1063 @deffn Command make-variable-buffer-local variable
1064 This function marks @var{variable} (a symbol) automatically
1065 buffer-local, so that any subsequent attempt to set it will make it
1066 local to the current buffer at the time.
1067
1068 The value returned is @var{variable}.
1069 @end deffn
1070
1071 @defun buffer-local-variables &optional buffer
1072 This function returns a list describing the buffer-local variables in
1073 buffer @var{buffer}. It returns an association list (@pxref{Association
1074 Lists}) in which each association contains one buffer-local variable and
1075 its value. When a buffer-local variable is void in @var{buffer}, then
1076 it appears directly in the resulting list. If @var{buffer} is omitted,
1077 the current buffer is used.
1078
1079 @example
1080 @group
1081 (make-local-variable 'foobar)
1082 (makunbound 'foobar)
1083 (make-local-variable 'bind-me)
1084 (setq bind-me 69)
1085 @end group
1086 (setq lcl (buffer-local-variables))
1087 ;; @r{First, built-in variables local in all buffers:}
1088 @result{} ((mark-active . nil)
1089 (buffer-undo-list nil)
1090 (mode-name . "Fundamental")
1091 @dots{}
1092 @group
1093 ;; @r{Next, non-built-in local variables.}
1094 ;; @r{This one is local and void:}
1095 foobar
1096 ;; @r{This one is local and nonvoid:}
1097 (bind-me . 69))
1098 @end group
1099 @end example
1100
1101 Note that storing new values into the @sc{cdr}s of cons cells in this
1102 list does @emph{not} change the local values of the variables.
1103 @end defun
1104
1105 @deffn Command kill-local-variable variable
1106 This function deletes the buffer-local binding (if any) for
1107 @var{variable} (a symbol) in the current buffer. As a result, the
1108 global (default) binding of @var{variable} becomes visible in this
1109 buffer. Usually this results in a change in the value of
1110 @var{variable}, since the global value is usually different from the
1111 buffer-local value just eliminated.
1112
1113 If you kill the local binding of a variable that automatically becomes
1114 local when set, this makes the global value visible in the current
1115 buffer. However, if you set the variable again, that will once again
1116 create a local binding for it.
1117
1118 @code{kill-local-variable} returns @var{variable}.
1119 @end deffn
1120
1121 @defun kill-all-local-variables
1122 This function eliminates all the buffer-local variable bindings of the
1123 current buffer except for variables marked as ``permanent''. As a
1124 result, the buffer will see the default values of most variables.
1125
1126 This function also resets certain other information pertaining to the
1127 buffer: it sets the local keymap to @code{nil}, the syntax table to the
1128 value of @code{standard-syntax-table}, and the abbrev table to the value
1129 of @code{fundamental-mode-abbrev-table}.
1130
1131 Every major mode command begins by calling this function, which has the
1132 effect of switching to Fundamental mode and erasing most of the effects
1133 of the previous major mode. To ensure that this does its job, the
1134 variables that major modes set should not be marked permanent.
1135
1136 @code{kill-all-local-variables} returns @code{nil}.
1137 @end defun
1138
1139 @c Emacs 19 feature
1140 @cindex permanent local variable
1141 A local variable is @dfn{permanent} if the variable name (a symbol) has a
1142 @code{permanent-local} property that is non-@code{nil}. Permanent
1143 locals are appropriate for data pertaining to where the file came from
1144 or how to save it, rather than with how to edit the contents.
1145
1146 @node Default Value
1147 @subsection The Default Value of a Buffer-Local Variable
1148 @cindex default value
1149
1150 The global value of a variable with buffer-local bindings is also
1151 called the @dfn{default} value, because it is the value that is in
1152 effect except when specifically overridden.
1153
1154 The functions @code{default-value} and @code{setq-default} access and
1155 change a variable's default value regardless of whether the current
1156 buffer has a buffer-local binding. For example, you could use
1157 @code{setq-default} to change the default setting of
1158 @code{paragraph-start} for most buffers; and this would work even when
1159 you are in a C or Lisp mode buffer which has a buffer-local value for
1160 this variable.
1161
1162 @c Emacs 19 feature
1163 The special forms @code{defvar} and @code{defconst} also set the
1164 default value (if they set the variable at all), rather than any local
1165 value.
1166
1167 @defun default-value symbol
1168 This function returns @var{symbol}'s default value. This is the value
1169 that is seen in buffers that do not have their own values for this
1170 variable. If @var{symbol} is not buffer-local, this is equivalent to
1171 @code{symbol-value} (@pxref{Accessing Variables}).
1172 @end defun
1173
1174 @c Emacs 19 feature
1175 @defun default-boundp variable
1176 The function @code{default-boundp} tells you whether @var{variable}'s
1177 default value is nonvoid. If @code{(default-boundp 'foo)} returns
1178 @code{nil}, then @code{(default-value 'foo)} would get an error.
1179
1180 @code{default-boundp} is to @code{default-value} as @code{boundp} is to
1181 @code{symbol-value}.
1182 @end defun
1183
1184 @defspec setq-default symbol value
1185 This sets the default value of @var{symbol} to @var{value}. It does not
1186 evaluate @var{symbol}, but does evaluate @var{value}. The value of the
1187 @code{setq-default} form is @var{value}.
1188
1189 If a @var{symbol} is not buffer-local for the current buffer, and is not
1190 marked automatically buffer-local, @code{setq-default} has the same
1191 effect as @code{setq}. If @var{symbol} is buffer-local for the current
1192 buffer, then this changes the value that other buffers will see (as long
1193 as they don't have a buffer-local value), but not the value that the
1194 current buffer sees.
1195
1196 @example
1197 @group
1198 ;; @r{In buffer @samp{foo}:}
1199 (make-local-variable 'local)
1200 @result{} local
1201 @end group
1202 @group
1203 (setq local 'value-in-foo)
1204 @result{} value-in-foo
1205 @end group
1206 @group
1207 (setq-default local 'new-default)
1208 @result{} new-default
1209 @end group
1210 @group
1211 local
1212 @result{} value-in-foo
1213 @end group
1214 @group
1215 (default-value 'local)
1216 @result{} new-default
1217 @end group
1218
1219 @group
1220 ;; @r{In (the new) buffer @samp{bar}:}
1221 local
1222 @result{} new-default
1223 @end group
1224 @group
1225 (default-value 'local)
1226 @result{} new-default
1227 @end group
1228 @group
1229 (setq local 'another-default)
1230 @result{} another-default
1231 @end group
1232 @group
1233 (default-value 'local)
1234 @result{} another-default
1235 @end group
1236
1237 @group
1238 ;; @r{Back in buffer @samp{foo}:}
1239 local
1240 @result{} value-in-foo
1241 (default-value 'local)
1242 @result{} another-default
1243 @end group
1244 @end example
1245 @end defspec
1246
1247 @defun set-default symbol value
1248 This function is like @code{setq-default}, except that @var{symbol} is
1249 evaluated.
1250
1251 @example
1252 @group
1253 (set-default (car '(a b c)) 23)
1254 @result{} 23
1255 @end group
1256 @group
1257 (default-value 'a)
1258 @result{} 23
1259 @end group
1260 @end example
1261 @end defun
1262