2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-2017 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
9 A @dfn{variable} is a name used in a program to stand for a value.
10 In Lisp, each variable is represented by a Lisp symbol
11 (@pxref{Symbols}). The variable name is simply the symbol's name, and
12 the variable's value is stored in the symbol's value cell@footnote{To
13 be precise, under the default @dfn{dynamic scoping} rule, the value
14 cell always holds the variable's current value, but this is not the
15 case under the @dfn{lexical scoping} rule. @xref{Variable Scoping},
16 for details.}. @xref{Symbol Components}. In Emacs Lisp, the use of a
17 symbol as a variable is independent of its use as a function name.
19 As previously noted in this manual, a Lisp program is represented
20 primarily by Lisp objects, and only secondarily as text. The textual
21 form of a Lisp program is given by the read syntax of the Lisp objects
22 that constitute the program. Hence, the textual form of a variable in
23 a Lisp program is written using the read syntax for the symbol
24 representing the variable.
27 * Global Variables:: Variable values that exist permanently, everywhere.
28 * Constant Variables:: Variables that never change.
29 * Local Variables:: Variable values that exist only temporarily.
30 * Void Variables:: Symbols that lack values.
31 * Defining Variables:: A definition says a symbol is used as a variable.
32 * Tips for Defining:: Things you should think about when you
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 * Watching Variables:: Running a function when a variable is changed.
38 * Variable Scoping:: How Lisp chooses among local and global values.
39 * Buffer-Local Variables:: Variable values in effect only in one buffer.
40 * File Local Variables:: Handling local variable lists in files.
41 * Directory Local Variables:: Local variables common to all files in a directory.
42 * Connection Local Variables:: Local variables common for remote connections.
43 * Variable Aliases:: Variables that are aliases for other variables.
44 * Variables with Restricted Values:: Non-constant variables whose value can
45 @emph{not} be an arbitrary Lisp object.
46 * Generalized Variables:: Extending the concept of variables.
49 @node Global Variables
50 @section Global Variables
51 @cindex global variable
53 The simplest way to use a variable is @dfn{globally}. This means that
54 the variable has just one value at a time, and this value is in effect
55 (at least for the moment) throughout the Lisp system. The value remains
56 in effect until you specify a new one. When a new value replaces the
57 old one, no trace of the old value remains in the variable.
59 You specify a value for a symbol with @code{setq}. For example,
66 gives the variable @code{x} the value @code{(a b)}. Note that
67 @code{setq} is a special form (@pxref{Special Forms}); it does not
68 evaluate its first argument, the name of the variable, but it does
69 evaluate the second argument, the new value.
71 Once the variable has a value, you can refer to it by using the
72 symbol itself as an expression. Thus,
81 assuming the @code{setq} form shown above has already been executed.
83 If you do set the same variable again, the new value replaces the old
101 @node Constant Variables
102 @section Variables that Never Change
103 @cindex @code{setting-constant} error
104 @cindex keyword symbol
105 @cindex variable with constant value
106 @cindex constant variables
107 @cindex symbol that evaluates to itself
108 @cindex symbol with constant value
110 In Emacs Lisp, certain symbols normally evaluate to themselves. These
111 include @code{nil} and @code{t}, as well as any symbol whose name starts
112 with @samp{:} (these are called @dfn{keywords}). These symbols cannot
113 be rebound, nor can their values be changed. Any attempt to set or bind
114 @code{nil} or @code{t} signals a @code{setting-constant} error. The
115 same is true for a keyword (a symbol whose name starts with @samp{:}),
116 if it is interned in the standard obarray, except that setting such a
117 symbol to itself is not an error.
126 @error{} Attempt to set constant symbol: nil
130 @defun keywordp object
131 function returns @code{t} if @var{object} is a symbol whose name
132 starts with @samp{:}, interned in the standard obarray, and returns
133 @code{nil} otherwise.
136 These constants are fundamentally different from the constants
137 defined using the @code{defconst} special form (@pxref{Defining
138 Variables}). A @code{defconst} form serves to inform human readers
139 that you do not intend to change the value of a variable, but Emacs
140 does not raise an error if you actually change it.
142 @cindex read-only variables
143 A small number of additional symbols are made read-only for various
144 practical reasons. These include @code{enable-multibyte-characters},
145 @code{most-positive-fixnum}, @code{most-negative-fixnum}, and a few
146 others. Any attempt to set or bind these also signals a
147 @code{setting-constant} error.
149 @node Local Variables
150 @section Local Variables
151 @cindex binding local variables
152 @cindex local variables
153 @cindex local binding
154 @cindex global binding
156 Global variables have values that last until explicitly superseded
157 with new values. Sometimes it is useful to give a variable a
158 @dfn{local value}---a value that takes effect only within a certain
159 part of a Lisp program. When a variable has a local value, we say
160 that it is @dfn{locally bound} to that value, and that it is a
161 @dfn{local variable}.
163 For example, when a function is called, its argument variables
164 receive local values, which are the actual arguments supplied to the
165 function call; these local bindings take effect within the body of the
166 function. To take another example, the @code{let} special form
167 explicitly establishes local bindings for specific variables, which
168 take effect within the body of the @code{let} form.
170 We also speak of the @dfn{global binding}, which is where
171 (conceptually) the global value is kept.
173 @cindex shadowing of variables
174 Establishing a local binding saves away the variable's previous
175 value (or lack of one). We say that the previous value is
176 @dfn{shadowed}. Both global and local values may be shadowed. If a
177 local binding is in effect, using @code{setq} on the local variable
178 stores the specified value in the local binding. When that local
179 binding is no longer in effect, the previously shadowed value (or lack
182 @cindex current binding
183 A variable can have more than one local binding at a time (e.g., if
184 there are nested @code{let} forms that bind the variable). The
185 @dfn{current binding} is the local binding that is actually in effect.
186 It determines the value returned by evaluating the variable symbol,
187 and it is the binding acted on by @code{setq}.
189 For most purposes, you can think of the current binding as the
190 innermost local binding, or the global binding if there is no
191 local binding. To be more precise, a rule called the @dfn{scoping
192 rule} determines where in a program a local binding takes effect. The
193 default scoping rule in Emacs Lisp is called @dfn{dynamic scoping},
194 which simply states that the current binding at any given point in the
195 execution of a program is the most recently-created binding for that
196 variable that still exists. For details about dynamic scoping, and an
197 alternative scoping rule called @dfn{lexical scoping}, @xref{Variable
200 The special forms @code{let} and @code{let*} exist to create local
203 @defspec let (bindings@dots{}) forms@dots{}
204 This special form sets up local bindings for a certain set of
205 variables, as specified by @var{bindings}, and then evaluates all of
206 the @var{forms} in textual order. Its return value is the value of
207 the last form in @var{forms}.
209 Each of the @var{bindings} is either @w{(i) a} symbol, in which case
210 that symbol is locally bound to @code{nil}; or @w{(ii) a} list of the
211 form @code{(@var{symbol} @var{value-form})}, in which case
212 @var{symbol} is locally bound to the result of evaluating
213 @var{value-form}. If @var{value-form} is omitted, @code{nil} is used.
215 All of the @var{value-form}s in @var{bindings} are evaluated in the
216 order they appear and @emph{before} binding any of the symbols to them.
217 Here is an example of this: @code{z} is bound to the old value of
218 @code{y}, which is 2, not the new value of @code{y}, which is 1.
234 On the other hand, the order of @emph{bindings} is unspecified: in the
235 following example, either 1 or 2 might be printed.
243 Therefore, avoid binding a variable more than once in a single
247 @defspec let* (bindings@dots{}) forms@dots{}
248 This special form is like @code{let}, but it binds each variable right
249 after computing its local value, before computing the local value for
250 the next variable. Therefore, an expression in @var{bindings} can
251 refer to the preceding symbols bound in this @code{let*} form.
252 Compare the following example with the example above for @code{let}.
262 (z y)) ; @r{Use the just-established value of @code{y}.}
269 Here is a complete list of the other facilities that create local
274 Function calls (@pxref{Functions}).
277 Macro calls (@pxref{Macros}).
280 @code{condition-case} (@pxref{Errors}).
283 Variables can also have buffer-local bindings (@pxref{Buffer-Local
284 Variables}); a few variables have terminal-local bindings
285 (@pxref{Multiple Terminals}). These kinds of bindings work somewhat
286 like ordinary local bindings, but they are localized depending on
287 where you are in Emacs.
289 @defopt max-specpdl-size
290 @anchor{Definition of max-specpdl-size}
291 @cindex variable limit error
292 @cindex evaluation error
293 @cindex infinite recursion
294 This variable defines the limit on the total number of local variable
295 bindings and @code{unwind-protect} cleanups (see @ref{Cleanups,,
296 Cleaning Up from Nonlocal Exits}) that are allowed before Emacs
297 signals an error (with data @code{"Variable binding depth exceeds
300 This limit, with the associated error when it is exceeded, is one way
301 that Lisp avoids infinite recursion on an ill-defined function.
302 @code{max-lisp-eval-depth} provides another limit on depth of nesting.
303 @xref{Definition of max-lisp-eval-depth,, Eval}.
305 The default value is 1300. Entry to the Lisp debugger increases the
306 value, if there is little room left, to make sure the debugger itself
311 @section When a Variable is Void
312 @cindex @code{void-variable} error
313 @cindex void variable
315 We say that a variable is void if its symbol has an unassigned value
316 cell (@pxref{Symbol Components}).
318 Under Emacs Lisp's default dynamic scoping rule (@pxref{Variable
319 Scoping}), the value cell stores the variable's current (local or
320 global) value. Note that an unassigned value cell is @emph{not} the
321 same as having @code{nil} in the value cell. The symbol @code{nil} is
322 a Lisp object and can be the value of a variable, just as any other
323 object can be; but it is still a value. If a variable is void, trying
324 to evaluate the variable signals a @code{void-variable} error, instead
325 of returning a value.
327 Under the optional lexical scoping rule, the value cell only holds
328 the variable's global value---the value outside of any lexical binding
329 construct. When a variable is lexically bound, the local value is
330 determined by the lexical environment; hence, variables can have local
331 values even if their symbols' value cells are unassigned.
333 @defun makunbound symbol
334 This function empties out the value cell of @var{symbol}, making the
335 variable void. It returns @var{symbol}.
337 If @var{symbol} has a dynamic local binding, @code{makunbound} voids
338 the current binding, and this voidness lasts only as long as the local
339 binding is in effect. Afterwards, the previously shadowed local or
340 global binding is reexposed; then the variable will no longer be void,
341 unless the reexposed binding is void too.
343 Here are some examples (assuming dynamic binding is in effect):
347 (setq x 1) ; @r{Put a value in the global binding.}
349 (let ((x 2)) ; @r{Locally bind it.}
350 (makunbound 'x) ; @r{Void the local binding.}
352 @error{} Symbol's value as variable is void: x
355 x ; @r{The global binding is unchanged.}
358 (let ((x 2)) ; @r{Locally bind it.}
359 (let ((x 3)) ; @r{And again.}
360 (makunbound 'x) ; @r{Void the innermost-local binding.}
361 x)) ; @r{And refer: it's void.}
362 @error{} Symbol's value as variable is void: x
368 (makunbound 'x)) ; @r{Void inner binding, then remove it.}
369 x) ; @r{Now outer @code{let} binding is visible.}
375 @defun boundp variable
376 This function returns @code{t} if @var{variable} (a symbol) is not
377 void, and @code{nil} if it is void.
379 Here are some examples (assuming dynamic binding is in effect):
383 (boundp 'abracadabra) ; @r{Starts out void.}
387 (let ((abracadabra 5)) ; @r{Locally bind it.}
388 (boundp 'abracadabra))
392 (boundp 'abracadabra) ; @r{Still globally void.}
396 (setq abracadabra 5) ; @r{Make it globally nonvoid.}
400 (boundp 'abracadabra)
406 @node Defining Variables
407 @section Defining Global Variables
408 @cindex variable definition
410 A @dfn{variable definition} is a construct that announces your
411 intention to use a symbol as a global variable. It uses the special
412 forms @code{defvar} or @code{defconst}, which are documented below.
414 A variable definition serves three purposes. First, it informs
415 people who read the code that the symbol is @emph{intended} to be used
416 a certain way (as a variable). Second, it informs the Lisp system of
417 this, optionally supplying an initial value and a documentation
418 string. Third, it provides information to programming tools such as
419 @command{etags}, allowing them to find where the variable was defined.
421 The difference between @code{defconst} and @code{defvar} is mainly a
422 matter of intent, serving to inform human readers of whether the value
423 should ever change. Emacs Lisp does not actually prevent you from
424 changing the value of a variable defined with @code{defconst}. One
425 notable difference between the two forms is that @code{defconst}
426 unconditionally initializes the variable, whereas @code{defvar}
427 initializes it only if it is originally void.
429 To define a customizable variable, you should use @code{defcustom}
430 (which calls @code{defvar} as a subroutine). @xref{Variable
433 @defspec defvar symbol [value [doc-string]]
434 This special form defines @var{symbol} as a variable. Note that
435 @var{symbol} is not evaluated; the symbol to be defined should appear
436 explicitly in the @code{defvar} form. The variable is marked as
437 @dfn{special}, meaning that it should always be dynamically bound
438 (@pxref{Variable Scoping}).
440 If @var{value} is specified, and @var{symbol} is void (i.e., it has no
441 dynamically bound value; @pxref{Void Variables}), then @var{value} is
442 evaluated and @var{symbol} is set to the result. But if @var{symbol}
443 is not void, @var{value} is not evaluated, and @var{symbol}'s value is
444 left unchanged. If @var{value} is omitted, the value of @var{symbol}
445 is not changed in any case. Using @code{defvar} with no value is one
446 method of suppressing byte compilation warnings, see @ref{Compiler
449 If @var{symbol} has a buffer-local binding in the current buffer,
450 @code{defvar} acts on the default value, which is buffer-independent,
451 rather than the buffer-local binding. It sets the default value if
452 the default value is void. @xref{Buffer-Local Variables}.
454 If @var{symbol} is already lexically bound (e.g., if the @code{defvar}
455 form occurs in a @code{let} form with lexical binding enabled), then
456 @code{defvar} sets the dynamic value. The lexical binding remains in
457 effect until its binding construct exits. @xref{Variable Scoping}.
459 When you evaluate a top-level @code{defvar} form with @kbd{C-M-x} in
460 Emacs Lisp mode (@code{eval-defun}), a special feature of
461 @code{eval-defun} arranges to set the variable unconditionally, without
462 testing whether its value is void.
464 If the @var{doc-string} argument is supplied, it specifies the
465 documentation string for the variable (stored in the symbol's
466 @code{variable-documentation} property). @xref{Documentation}.
468 Here are some examples. This form defines @code{foo} but does not
478 This example initializes the value of @code{bar} to @code{23}, and gives
479 it a documentation string:
484 "The normal weight of a bar.")
489 The @code{defvar} form returns @var{symbol}, but it is normally used
490 at top level in a file where its value does not matter.
493 @cindex constant variables
494 @defspec defconst symbol value [doc-string]
495 This special form defines @var{symbol} as a value and initializes it.
496 It informs a person reading your code that @var{symbol} has a standard
497 global value, established here, that should not be changed by the user
498 or by other programs. Note that @var{symbol} is not evaluated; the
499 symbol to be defined must appear explicitly in the @code{defconst}.
501 The @code{defconst} form, like @code{defvar}, marks the variable as
502 @dfn{special}, meaning that it should always be dynamically bound
503 (@pxref{Variable Scoping}). In addition, it marks the variable as
504 risky (@pxref{File Local Variables}).
506 @code{defconst} always evaluates @var{value}, and sets the value of
507 @var{symbol} to the result. If @var{symbol} does have a buffer-local
508 binding in the current buffer, @code{defconst} sets the default value,
509 not the buffer-local value. (But you should not be making
510 buffer-local bindings for a symbol that is defined with
513 An example of the use of @code{defconst} is Emacs's definition of
514 @code{float-pi}---the mathematical constant @math{pi}, which ought not
515 to be changed by anyone (attempts by the Indiana State Legislature
516 notwithstanding). As the second form illustrates, however,
517 @code{defconst} is only advisory.
521 (defconst float-pi 3.141592653589793 "The value of Pi.")
535 @strong{Warning:} If you use a @code{defconst} or @code{defvar}
536 special form while the variable has a local binding (made with
537 @code{let}, or a function argument), it sets the local binding rather
538 than the global binding. This is not what you usually want. To
539 prevent this, use these special forms at top level in a file, where
540 normally no local binding is in effect, and make sure to load the file
541 before making a local binding for the variable.
543 @node Tips for Defining
544 @section Tips for Defining Variables Robustly
546 When you define a variable whose value is a function, or a list of
547 functions, use a name that ends in @samp{-function} or
548 @samp{-functions}, respectively.
550 There are several other variable name conventions;
551 here is a complete list:
555 The variable is a normal hook (@pxref{Hooks}).
557 @item @dots{}-function
558 The value is a function.
560 @item @dots{}-functions
561 The value is a list of functions.
564 The value is a form (an expression).
567 The value is a list of forms (expressions).
569 @item @dots{}-predicate
570 The value is a predicate---a function of one argument that returns
571 non-@code{nil} for success and @code{nil} for failure.
574 The value is significant only as to whether it is @code{nil} or not.
575 Since such variables often end up acquiring more values over time,
576 this convention is not strongly recommended.
578 @item @dots{}-program
579 The value is a program name.
581 @item @dots{}-command
582 The value is a whole shell command.
584 @item @dots{}-switches
585 The value specifies options for a command.
587 @item @var{prefix}--@dots{}
588 The variable is intended for internal use and is defined in the file
589 @file{@var{prefix}.el}. (Emacs code contributed before 2018 may
590 follow other conventions, which are being phased out.)
592 @item @dots{}-internal
593 The variable is intended for internal use and is defined in C code.
594 (Emacs code contributed before 2018 may follow other conventions,
595 which are being phased out.)
598 When you define a variable, always consider whether you should mark
599 it as safe or risky; see @ref{File Local Variables}.
601 When defining and initializing a variable that holds a complicated
602 value (such as a keymap with bindings in it), it's best to put the
603 entire computation of the value into the @code{defvar}, like this:
607 (let ((map (make-sparse-keymap)))
608 (define-key map "\C-c\C-a" 'my-command)
615 This method has several benefits. First, if the user quits while
616 loading the file, the variable is either still uninitialized or
617 initialized properly, never in-between. If it is still uninitialized,
618 reloading the file will initialize it properly. Second, reloading the
619 file once the variable is initialized will not alter it; that is
620 important if the user has run hooks to alter part of the contents
621 (such as, to rebind keys). Third, evaluating the @code{defvar} form
622 with @kbd{C-M-x} will reinitialize the map completely.
624 Putting so much code in the @code{defvar} form has one disadvantage:
625 it puts the documentation string far away from the line which names the
626 variable. Here's a safe way to avoid that:
629 (defvar my-mode-map nil
632 (let ((map (make-sparse-keymap)))
633 (define-key map "\C-c\C-a" 'my-command)
635 (setq my-mode-map map)))
639 This has all the same advantages as putting the initialization inside
640 the @code{defvar}, except that you must type @kbd{C-M-x} twice, once on
641 each form, if you do want to reinitialize the variable.
643 @node Accessing Variables
644 @section Accessing Variable Values
646 The usual way to reference a variable is to write the symbol which
647 names it. @xref{Symbol Forms}.
649 Occasionally, you may want to reference a variable which is only
650 determined at run time. In that case, you cannot specify the variable
651 name in the text of the program. You can use the @code{symbol-value}
652 function to extract the value.
654 @defun symbol-value symbol
655 This function returns the value stored in @var{symbol}'s value cell.
656 This is where the variable's current (dynamic) value is stored. If
657 the variable has no local binding, this is simply its global value.
658 If the variable is void, a @code{void-variable} error is signaled.
660 If the variable is lexically bound, the value reported by
661 @code{symbol-value} is not necessarily the same as the variable's
662 lexical value, which is determined by the lexical environment rather
663 than the symbol's value cell. @xref{Variable Scoping}.
676 ;; @r{Here the symbol @code{abracadabra}}
677 ;; @r{is the symbol whose value is examined.}
678 (let ((abracadabra 'foo))
679 (symbol-value 'abracadabra))
684 ;; @r{Here, the value of @code{abracadabra},}
685 ;; @r{which is @code{foo},}
686 ;; @r{is the symbol whose value is examined.}
687 (let ((abracadabra 'foo))
688 (symbol-value abracadabra))
693 (symbol-value 'abracadabra)
699 @node Setting Variables
700 @section Setting Variable Values
702 The usual way to change the value of a variable is with the special
703 form @code{setq}. When you need to compute the choice of variable at
704 run time, use the function @code{set}.
706 @defspec setq [symbol form]@dots{}
707 This special form is the most common method of changing a variable's
708 value. Each @var{symbol} is given a new value, which is the result of
709 evaluating the corresponding @var{form}. The current binding of the
712 @code{setq} does not evaluate @var{symbol}; it sets the symbol that you
713 write. We say that this argument is @dfn{automatically quoted}. The
714 @samp{q} in @code{setq} stands for ``quoted''.
716 The value of the @code{setq} form is the value of the last @var{form}.
723 x ; @r{@code{x} now has a global value.}
727 (setq x 6) ; @r{The local binding of @code{x} is set.}
731 x ; @r{The global value is unchanged.}
735 Note that the first @var{form} is evaluated, then the first
736 @var{symbol} is set, then the second @var{form} is evaluated, then the
737 second @var{symbol} is set, and so on:
741 (setq x 10 ; @r{Notice that @code{x} is set before}
742 y (1+ x)) ; @r{the value of @code{y} is computed.}
748 @defun set symbol value
749 This function puts @var{value} in the value cell of @var{symbol}.
750 Since it is a function rather than a special form, the expression
751 written for @var{symbol} is evaluated to obtain the symbol to set.
752 The return value is @var{value}.
754 When dynamic variable binding is in effect (the default), @code{set}
755 has the same effect as @code{setq}, apart from the fact that
756 @code{set} evaluates its @var{symbol} argument whereas @code{setq}
757 does not. But when a variable is lexically bound, @code{set} affects
758 its @emph{dynamic} value, whereas @code{setq} affects its current
759 (lexical) value. @xref{Variable Scoping}.
764 @error{} Symbol's value as variable is void: one
775 (set two 2) ; @r{@code{two} evaluates to symbol @code{one}.}
779 one ; @r{So it is @code{one} that was set.}
781 (let ((one 1)) ; @r{This binding of @code{one} is set,}
782 (set 'one 3) ; @r{not the global value.}
792 If @var{symbol} is not actually a symbol, a @code{wrong-type-argument}
797 @error{} Wrong type argument: symbolp, (x y)
801 @node Watching Variables
802 @section Running a function when a variable is changed.
803 @cindex variable watchpoints
804 @cindex watchpoints for Lisp variables
806 It is sometimes useful to take some action when a variable changes its
807 value. The watchpoint facility provides the means to do so. Some
808 possible uses for this feature include keeping display in sync with
809 variable settings, and invoking the debugger to track down unexpected
810 changes to variables (@pxref{Variable Debugging}).
812 The following functions may be used to manipulate and query the watch
813 functions for a variable.
815 @defun add-variable-watcher symbol watch-function
816 This function arranges for @var{watch-function} to be called whenever
817 @var{symbol} is modified. Modifications through aliases
818 (@pxref{Variable Aliases}) will have the same effect.
820 @var{watch-function} will be called with 4 arguments: (@var{symbol}
821 @var{newval} @var{operation} @var{where}).
823 @var{symbol} is the variable being changed.
824 @var{newval} is the value it will be changed to.
825 @var{operation} is a symbol representing the kind of change, one of:
826 `set', `let', `unlet', `makunbound', and `defvaralias'.
827 @var{where} is a buffer if the buffer-local value of the variable is
828 being changed, nil otherwise.
831 @defun remove-variable-watch symbol watch-function
832 This function removes @var{watch-function} from @var{symbol}'s list of
836 @defun get-variable-watchers symbol
837 This function returns the list of @var{symbol}'s active watcher
841 @subsection Limitations
843 There are a couple of ways in which a variable could be modified (or at
844 least appear to be modified) without triggering a watchpoint.
846 Since watchpoints are attached to symbols, modification to the
847 objects contained within variables (e.g., by a list modification
848 function @pxref{Modifying Lists}) is not caught by this mechanism.
850 Additionally, C code can modify the value of variables directly,
851 bypassing the watchpoint mechanism.
853 A minor limitation of this feature, again because it targets symbols,
854 is that only variables of dynamic scope may be watched. This poses
855 little difficulty, since modifications to lexical variables can be
856 discovered easily by inspecting the code within the scope of the
857 variable (unlike dynamic variables, which can be modified by any code
858 at all, @pxref{Variable Scoping}).
861 @node Variable Scoping
862 @section Scoping Rules for Variable Bindings
865 When you create a local binding for a variable, that binding takes
866 effect only within a limited portion of the program (@pxref{Local
867 Variables}). This section describes exactly what this means.
871 Each local binding has a certain @dfn{scope} and @dfn{extent}.
872 @dfn{Scope} refers to @emph{where} in the textual source code the
873 binding can be accessed. @dfn{Extent} refers to @emph{when}, as the
874 program is executing, the binding exists.
876 @cindex dynamic binding
877 @cindex dynamic scope
878 @cindex dynamic extent
879 By default, the local bindings that Emacs creates are @dfn{dynamic
880 bindings}. Such a binding has @dfn{dynamic scope}, meaning that any
881 part of the program can potentially access the variable binding. It
882 also has @dfn{dynamic extent}, meaning that the binding lasts only
883 while the binding construct (such as the body of a @code{let} form) is
886 @cindex lexical binding
887 @cindex lexical scope
888 @cindex indefinite extent
889 Emacs can optionally create @dfn{lexical bindings}. A lexical
890 binding has @dfn{lexical scope}, meaning that any reference to the
891 variable must be located textually within the binding
892 construct@footnote{With some exceptions; for instance, a lexical
893 binding can also be accessed from the Lisp debugger.}. It also has
894 @dfn{indefinite extent}, meaning that under some circumstances the
895 binding can live on even after the binding construct has finished
896 executing, by means of special objects called @dfn{closures}.
898 The following subsections describe dynamic binding and lexical
899 binding in greater detail, and how to enable lexical binding in Emacs
903 * Dynamic Binding:: The default for binding local variables in Emacs.
904 * Dynamic Binding Tips:: Avoiding problems with dynamic binding.
905 * Lexical Binding:: A different type of local variable binding.
906 * Using Lexical Binding:: How to enable lexical binding.
909 @node Dynamic Binding
910 @subsection Dynamic Binding
912 By default, the local variable bindings made by Emacs are dynamic
913 bindings. When a variable is dynamically bound, its current binding
914 at any point in the execution of the Lisp program is simply the most
915 recently-created dynamic local binding for that symbol, or the global
916 binding if there is no such local binding.
918 Dynamic bindings have dynamic scope and extent, as shown by the
923 (defvar x -99) ; @r{@code{x} receives an initial value of @minus{}99.}
926 x) ; @r{@code{x} is used free in this function.}
928 (let ((x 1)) ; @r{@code{x} is dynamically bound.}
932 ;; @r{After the @code{let} form finishes, @code{x} reverts to its}
933 ;; @r{previous value, which is @minus{}99.}
941 The function @code{getx} refers to @code{x}. This is a @dfn{free}
942 reference, in the sense that there is no binding for @code{x} within
943 that @code{defun} construct itself. When we call @code{getx} from
944 within a @code{let} form in which @code{x} is (dynamically) bound, it
945 retrieves the local value (i.e., 1). But when we call @code{getx}
946 outside the @code{let} form, it retrieves the global value (i.e.,
949 Here is another example, which illustrates setting a dynamically
950 bound variable using @code{setq}:
954 (defvar x -99) ; @r{@code{x} receives an initial value of @minus{}99.}
957 (setq x (1+ x))) ; @r{Add 1 to @code{x} and return its new value.}
962 @result{} 3 ; @r{The two @code{addx} calls add to @code{x} twice.}
964 ;; @r{After the @code{let} form finishes, @code{x} reverts to its}
965 ;; @r{previous value, which is @minus{}99.}
972 Dynamic binding is implemented in Emacs Lisp in a simple way. Each
973 symbol has a value cell, which specifies its current dynamic value (or
974 absence of value). @xref{Symbol Components}. When a symbol is given
975 a dynamic local binding, Emacs records the contents of the value cell
976 (or absence thereof) in a stack, and stores the new local value in the
977 value cell. When the binding construct finishes executing, Emacs pops
978 the old value off the stack, and puts it in the value cell.
980 @node Dynamic Binding Tips
981 @subsection Proper Use of Dynamic Binding
983 Dynamic binding is a powerful feature, as it allows programs to
984 refer to variables that are not defined within their local textual
985 scope. However, if used without restraint, this can also make
986 programs hard to understand. There are two clean ways to use this
991 If a variable has no global definition, use it as a local variable
992 only within a binding construct, such as the body of the @code{let}
993 form where the variable was bound. If this convention is followed
994 consistently throughout a program, the value of the variable will not
995 affect, nor be affected by, any uses of the same variable symbol
996 elsewhere in the program.
999 Otherwise, define the variable with @code{defvar}, @code{defconst}, or
1000 @code{defcustom}. @xref{Defining Variables}. Usually, the definition
1001 should be at top-level in an Emacs Lisp file. As far as possible, it
1002 should include a documentation string which explains the meaning and
1003 purpose of the variable. You should also choose the variable's name
1004 to avoid name conflicts (@pxref{Coding Conventions}).
1006 Then you can bind the variable anywhere in a program, knowing reliably
1007 what the effect will be. Wherever you encounter the variable, it will
1008 be easy to refer back to the definition, e.g., via the @kbd{C-h v}
1009 command (provided the variable definition has been loaded into Emacs).
1010 @xref{Name Help,,, emacs, The GNU Emacs Manual}.
1012 For example, it is common to use local bindings for customizable
1013 variables like @code{case-fold-search}:
1017 (defun search-for-abc ()
1018 "Search for the string \"abc\", ignoring case differences."
1019 (let ((case-fold-search nil))
1020 (re-search-forward "abc")))
1025 @node Lexical Binding
1026 @subsection Lexical Binding
1028 Lexical binding was introduced to Emacs, as an optional feature, in
1029 version 24.1. We expect its importance to increase with time.
1030 Lexical binding opens up many more opportunities for optimization, so
1031 programs using it are likely to run faster in future Emacs versions.
1032 Lexical binding is also more compatible with concurrency, which was
1033 added to Emacs in version 26.1.
1035 A lexically-bound variable has @dfn{lexical scope}, meaning that any
1036 reference to the variable must be located textually within the binding
1037 construct. Here is an example
1039 (see the next subsection, for how to actually enable lexical binding):
1042 (@pxref{Using Lexical Binding}, for how to actually enable lexical binding):
1047 (let ((x 1)) ; @r{@code{x} is lexically bound.}
1052 x) ; @r{@code{x} is used free in this function.}
1054 (let ((x 1)) ; @r{@code{x} is lexically bound.}
1056 @error{} Symbol's value as variable is void: x
1061 Here, the variable @code{x} has no global value. When it is lexically
1062 bound within a @code{let} form, it can be used in the textual confines
1063 of that @code{let} form. But it can @emph{not} be used from within a
1064 @code{getx} function called from the @code{let} form, since the
1065 function definition of @code{getx} occurs outside the @code{let} form
1068 @cindex lexical environment
1069 Here is how lexical binding works. Each binding construct defines a
1070 @dfn{lexical environment}, specifying the variables that are bound
1071 within the construct and their local values. When the Lisp evaluator
1072 wants the current value of a variable, it looks first in the lexical
1073 environment; if the variable is not specified in there, it looks in
1074 the symbol's value cell, where the dynamic value is stored.
1076 (Internally, the lexical environment is an alist of symbol-value
1077 pairs, with the final element in the alist being the symbol @code{t}
1078 rather than a cons cell. Such an alist can be passed as the second
1079 argument to the @code{eval} function, in order to specify a lexical
1080 environment in which to evaluate a form. @xref{Eval}. Most Emacs
1081 Lisp programs, however, should not interact directly with lexical
1082 environments in this way; only specialized programs like debuggers.)
1084 @cindex closures, example of using
1085 Lexical bindings have indefinite extent. Even after a binding
1086 construct has finished executing, its lexical environment can be
1087 ``kept around'' in Lisp objects called @dfn{closures}. A closure is
1088 created when you define a named or anonymous function with lexical
1089 binding enabled. @xref{Closures}, for details.
1091 When a closure is called as a function, any lexical variable
1092 references within its definition use the retained lexical environment.
1096 (defvar my-ticker nil) ; @r{We will use this dynamically bound}
1097 ; @r{variable to store a closure.}
1099 (let ((x 0)) ; @r{@code{x} is lexically bound.}
1100 (setq my-ticker (lambda ()
1102 @result{} (closure ((x . 0) t) ()
1114 x ; @r{Note that @code{x} has no global value.}
1115 @error{} Symbol's value as variable is void: x
1119 The @code{let} binding defines a lexical environment in which the
1120 variable @code{x} is locally bound to 0. Within this binding
1121 construct, we define a lambda expression which increments @code{x} by
1122 one and returns the incremented value. This lambda expression is
1123 automatically turned into a closure, in which the lexical environment
1124 lives on even after the @code{let} binding construct has exited. Each
1125 time we evaluate the closure, it increments @code{x}, using the
1126 binding of @code{x} in that lexical environment.
1128 Note that unlike dynamic variables which are tied to the symbol
1129 object itself, the relationship between lexical variables and symbols
1130 is only present in the interpreter (or compiler). Therefore,
1131 functions which take a symbol argument (like @code{symbol-value},
1132 @code{boundp}, and @code{set}) can only retrieve or modify a
1133 variable's dynamic binding (i.e., the contents of its symbol's value
1136 @node Using Lexical Binding
1137 @subsection Using Lexical Binding
1139 When loading an Emacs Lisp file or evaluating a Lisp buffer, lexical
1140 binding is enabled if the buffer-local variable @code{lexical-binding}
1143 @defvar lexical-binding
1144 If this buffer-local variable is non-@code{nil}, Emacs Lisp files and
1145 buffers are evaluated using lexical binding instead of dynamic
1146 binding. (However, special variables are still dynamically bound; see
1147 below.) If @code{nil}, dynamic binding is used for all local
1148 variables. This variable is typically set for a whole Emacs Lisp
1149 file, as a file local variable (@pxref{File Local Variables}).
1150 Note that unlike other such variables, this one must be set in the
1151 first line of a file.
1155 When evaluating Emacs Lisp code directly using an @code{eval} call,
1156 lexical binding is enabled if the @var{lexical} argument to
1157 @code{eval} is non-@code{nil}. @xref{Eval}.
1159 @cindex special variables
1160 Even when lexical binding is enabled, certain variables will
1161 continue to be dynamically bound. These are called @dfn{special
1162 variables}. Every variable that has been defined with @code{defvar},
1163 @code{defcustom} or @code{defconst} is a special variable
1164 (@pxref{Defining Variables}). All other variables are subject to
1167 @defun special-variable-p symbol
1168 This function returns non-@code{nil} if @var{symbol} is a special
1169 variable (i.e., it has a @code{defvar}, @code{defcustom}, or
1170 @code{defconst} variable definition). Otherwise, the return value is
1174 The use of a special variable as a formal argument in a function is
1175 discouraged. Doing so gives rise to unspecified behavior when lexical
1176 binding mode is enabled (it may use lexical binding sometimes, and
1177 dynamic binding other times).
1179 Converting an Emacs Lisp program to lexical binding is easy. First,
1180 add a file-local variable setting of @code{lexical-binding} to
1181 @code{t} in the header line of the Emacs Lisp source file (@pxref{File
1182 Local Variables}). Second, check that every variable in the program
1183 which needs to be dynamically bound has a variable definition, so that
1184 it is not inadvertently bound lexically.
1186 @cindex free variable
1187 @cindex unused lexical variable
1188 A simple way to find out which variables need a variable definition
1189 is to byte-compile the source file. @xref{Byte Compilation}. If a
1190 non-special variable is used outside of a @code{let} form, the
1191 byte-compiler will warn about reference or assignment to a free
1192 variable. If a non-special variable is bound but not used within a
1193 @code{let} form, the byte-compiler will warn about an unused lexical
1194 variable. The byte-compiler will also issue a warning if you use a
1195 special variable as a function argument.
1197 (To silence byte-compiler warnings about unused variables, just use
1198 a variable name that starts with an underscore. The byte-compiler
1199 interprets this as an indication that this is a variable known not to
1202 @node Buffer-Local Variables
1203 @section Buffer-Local Variables
1204 @cindex variable, buffer-local
1205 @cindex buffer-local variables
1207 Global and local variable bindings are found in most programming
1208 languages in one form or another. Emacs, however, also supports
1209 additional, unusual kinds of variable binding, such as
1210 @dfn{buffer-local} bindings, which apply only in one buffer. Having
1211 different values for a variable in different buffers is an important
1212 customization method. (Variables can also have bindings that are
1213 local to each terminal. @xref{Multiple Terminals}.)
1216 * Intro to Buffer-Local:: Introduction and concepts.
1217 * Creating Buffer-Local:: Creating and destroying buffer-local bindings.
1218 * Default Value:: The default value is seen in buffers
1219 that don't have their own buffer-local values.
1222 @node Intro to Buffer-Local
1223 @subsection Introduction to Buffer-Local Variables
1225 A buffer-local variable has a buffer-local binding associated with a
1226 particular buffer. The binding is in effect when that buffer is
1227 current; otherwise, it is not in effect. If you set the variable while
1228 a buffer-local binding is in effect, the new value goes in that binding,
1229 so its other bindings are unchanged. This means that the change is
1230 visible only in the buffer where you made it.
1232 The variable's ordinary binding, which is not associated with any
1233 specific buffer, is called the @dfn{default binding}. In most cases,
1234 this is the global binding.
1236 A variable can have buffer-local bindings in some buffers but not in
1237 other buffers. The default binding is shared by all the buffers that
1238 don't have their own bindings for the variable. (This includes all
1239 newly-created buffers.) If you set the variable in a buffer that does
1240 not have a buffer-local binding for it, this sets the default binding,
1241 so the new value is visible in all the buffers that see the default
1244 The most common use of buffer-local bindings is for major modes to change
1245 variables that control the behavior of commands. For example, C mode and
1246 Lisp mode both set the variable @code{paragraph-start} to specify that only
1247 blank lines separate paragraphs. They do this by making the variable
1248 buffer-local in the buffer that is being put into C mode or Lisp mode, and
1249 then setting it to the new value for that mode. @xref{Major Modes}.
1251 The usual way to make a buffer-local binding is with
1252 @code{make-local-variable}, which is what major mode commands typically
1253 use. This affects just the current buffer; all other buffers (including
1254 those yet to be created) will continue to share the default value unless
1255 they are explicitly given their own buffer-local bindings.
1257 @cindex automatically buffer-local
1258 A more powerful operation is to mark the variable as
1259 @dfn{automatically buffer-local} by calling
1260 @code{make-variable-buffer-local}. You can think of this as making the
1261 variable local in all buffers, even those yet to be created. More
1262 precisely, the effect is that setting the variable automatically makes
1263 the variable local to the current buffer if it is not already so. All
1264 buffers start out by sharing the default value of the variable as usual,
1265 but setting the variable creates a buffer-local binding for the current
1266 buffer. The new value is stored in the buffer-local binding, leaving
1267 the default binding untouched. This means that the default value cannot
1268 be changed with @code{setq} in any buffer; the only way to change it is
1269 with @code{setq-default}.
1271 @strong{Warning:} When a variable has buffer-local
1272 bindings in one or more buffers, @code{let} rebinds the binding that's
1273 currently in effect. For instance, if the current buffer has a
1274 buffer-local value, @code{let} temporarily rebinds that. If no
1275 buffer-local bindings are in effect, @code{let} rebinds
1276 the default value. If inside the @code{let} you then change to a
1277 different current buffer in which a different binding is in effect,
1278 you won't see the @code{let} binding any more. And if you exit the
1279 @code{let} while still in the other buffer, you won't see the
1280 unbinding occur (though it will occur properly). Here is an example
1287 (make-local-variable 'foo)
1291 ;; foo @result{} 'temp ; @r{let binding in buffer @samp{a}}
1293 ;; foo @result{} 'g ; @r{the global value since foo is not local in @samp{b}}
1296 foo @result{} 'g ; @r{exiting restored the local value in buffer @samp{a},}
1297 ; @r{but we don't see that in buffer @samp{b}}
1300 (set-buffer "a") ; @r{verify the local value was restored}
1306 Note that references to @code{foo} in @var{body} access the
1307 buffer-local binding of buffer @samp{b}.
1309 When a file specifies local variable values, these become buffer-local
1310 values when you visit the file. @xref{File Variables,,, emacs, The
1313 A buffer-local variable cannot be made terminal-local
1314 (@pxref{Multiple Terminals}).
1316 @node Creating Buffer-Local
1317 @subsection Creating and Deleting Buffer-Local Bindings
1319 @deffn Command make-local-variable variable
1320 This function creates a buffer-local binding in the current buffer for
1321 @var{variable} (a symbol). Other buffers are not affected. The value
1322 returned is @var{variable}.
1324 The buffer-local value of @var{variable} starts out as the same value
1325 @var{variable} previously had. If @var{variable} was void, it remains
1330 ;; @r{In buffer @samp{b1}:}
1331 (setq foo 5) ; @r{Affects all buffers.}
1335 (make-local-variable 'foo) ; @r{Now it is local in @samp{b1}.}
1339 foo ; @r{That did not change}
1340 @result{} 5 ; @r{the value.}
1343 (setq foo 6) ; @r{Change the value}
1344 @result{} 6 ; @r{in @samp{b1}.}
1352 ;; @r{In buffer @samp{b2}, the value hasn't changed.}
1353 (with-current-buffer "b2"
1359 Making a variable buffer-local within a @code{let}-binding for that
1360 variable does not work reliably, unless the buffer in which you do this
1361 is not current either on entry to or exit from the @code{let}. This is
1362 because @code{let} does not distinguish between different kinds of
1363 bindings; it knows only which variable the binding was made for.
1365 It is an error to make a constant or a read-only variable
1366 buffer-local. @xref{Constant Variables}.
1368 If the variable is terminal-local (@pxref{Multiple Terminals}), this
1369 function signals an error. Such variables cannot have buffer-local
1372 @strong{Warning:} do not use @code{make-local-variable} for a hook
1373 variable. The hook variables are automatically made buffer-local as
1374 needed if you use the @var{local} argument to @code{add-hook} or
1378 @defmac setq-local variable value
1379 This macro creates a buffer-local binding in the current buffer for
1380 @var{variable}, and gives it the buffer-local value @var{value}. It
1381 is equivalent to calling @code{make-local-variable} followed by
1382 @code{setq}. @var{variable} should be an unquoted symbol.
1385 @deffn Command make-variable-buffer-local variable
1386 This function marks @var{variable} (a symbol) automatically
1387 buffer-local, so that any subsequent attempt to set it will make it
1388 local to the current buffer at the time. Unlike
1389 @code{make-local-variable}, with which it is often confused, this
1390 cannot be undone, and affects the behavior of the variable in all
1393 A peculiar wrinkle of this feature is that binding the variable (with
1394 @code{let} or other binding constructs) does not create a buffer-local
1395 binding for it. Only setting the variable (with @code{set} or
1396 @code{setq}), while the variable does not have a @code{let}-style
1397 binding that was made in the current buffer, does so.
1399 If @var{variable} does not have a default value, then calling this
1400 command will give it a default value of @code{nil}. If @var{variable}
1401 already has a default value, that value remains unchanged.
1402 Subsequently calling @code{makunbound} on @var{variable} will result
1403 in a void buffer-local value and leave the default value unaffected.
1405 The value returned is @var{variable}.
1407 It is an error to make a constant or a read-only variable
1408 buffer-local. @xref{Constant Variables}.
1410 @strong{Warning:} Don't assume that you should use
1411 @code{make-variable-buffer-local} for user-option variables, simply
1412 because users @emph{might} want to customize them differently in
1413 different buffers. Users can make any variable local, when they wish
1414 to. It is better to leave the choice to them.
1416 The time to use @code{make-variable-buffer-local} is when it is crucial
1417 that no two buffers ever share the same binding. For example, when a
1418 variable is used for internal purposes in a Lisp program which depends
1419 on having separate values in separate buffers, then using
1420 @code{make-variable-buffer-local} can be the best solution.
1423 @defmac defvar-local variable value &optional docstring
1424 This macro defines @var{variable} as a variable with initial value
1425 @var{value} and @var{docstring}, and marks it as automatically
1426 buffer-local. It is equivalent to calling @code{defvar} followed by
1427 @code{make-variable-buffer-local}. @var{variable} should be an
1431 @defun local-variable-p variable &optional buffer
1432 This returns @code{t} if @var{variable} is buffer-local in buffer
1433 @var{buffer} (which defaults to the current buffer); otherwise,
1437 @defun local-variable-if-set-p variable &optional buffer
1438 This returns @code{t} if @var{variable} either has a buffer-local
1439 value in buffer @var{buffer}, or is automatically buffer-local.
1440 Otherwise, it returns @code{nil}. If omitted or @code{nil},
1441 @var{buffer} defaults to the current buffer.
1444 @defun buffer-local-value variable buffer
1445 This function returns the buffer-local binding of @var{variable} (a
1446 symbol) in buffer @var{buffer}. If @var{variable} does not have a
1447 buffer-local binding in buffer @var{buffer}, it returns the default
1448 value (@pxref{Default Value}) of @var{variable} instead.
1451 @defun buffer-local-variables &optional buffer
1452 This function returns a list describing the buffer-local variables in
1453 buffer @var{buffer}. (If @var{buffer} is omitted, the current buffer
1454 is used.) Normally, each list element has the form
1455 @w{@code{(@var{sym} . @var{val})}}, where @var{sym} is a buffer-local
1456 variable (a symbol) and @var{val} is its buffer-local value. But when
1457 a variable's buffer-local binding in @var{buffer} is void, its list
1458 element is just @var{sym}.
1462 (make-local-variable 'foobar)
1463 (makunbound 'foobar)
1464 (make-local-variable 'bind-me)
1467 (setq lcl (buffer-local-variables))
1468 ;; @r{First, built-in variables local in all buffers:}
1469 @result{} ((mark-active . nil)
1470 (buffer-undo-list . nil)
1471 (mode-name . "Fundamental")
1474 ;; @r{Next, non-built-in buffer-local variables.}
1475 ;; @r{This one is buffer-local and void:}
1477 ;; @r{This one is buffer-local and nonvoid:}
1482 Note that storing new values into the @sc{cdr}s of cons cells in this
1483 list does @emph{not} change the buffer-local values of the variables.
1486 @deffn Command kill-local-variable variable
1487 This function deletes the buffer-local binding (if any) for
1488 @var{variable} (a symbol) in the current buffer. As a result, the
1489 default binding of @var{variable} becomes visible in this buffer. This
1490 typically results in a change in the value of @var{variable}, since the
1491 default value is usually different from the buffer-local value just
1494 If you kill the buffer-local binding of a variable that automatically
1495 becomes buffer-local when set, this makes the default value visible in
1496 the current buffer. However, if you set the variable again, that will
1497 once again create a buffer-local binding for it.
1499 @code{kill-local-variable} returns @var{variable}.
1501 This function is a command because it is sometimes useful to kill one
1502 buffer-local variable interactively, just as it is useful to create
1503 buffer-local variables interactively.
1506 @cindex local variables, killed by major mode
1507 @defun kill-all-local-variables
1508 This function eliminates all the buffer-local variable bindings of the
1509 current buffer except for variables marked as permanent and local
1510 hook functions that have a non-@code{nil} @code{permanent-local-hook}
1511 property (@pxref{Setting Hooks}). As a result, the buffer will see
1512 the default values of most variables.
1514 This function also resets certain other information pertaining to the
1515 buffer: it sets the local keymap to @code{nil}, the syntax table to the
1516 value of @code{(standard-syntax-table)}, the case table to
1517 @code{(standard-case-table)}, and the abbrev table to the value of
1518 @code{fundamental-mode-abbrev-table}.
1520 The very first thing this function does is run the normal hook
1521 @code{change-major-mode-hook} (see below).
1523 Every major mode command begins by calling this function, which has the
1524 effect of switching to Fundamental mode and erasing most of the effects
1525 of the previous major mode. To ensure that this does its job, the
1526 variables that major modes set should not be marked permanent.
1528 @code{kill-all-local-variables} returns @code{nil}.
1531 @defvar change-major-mode-hook
1532 The function @code{kill-all-local-variables} runs this normal hook
1533 before it does anything else. This gives major modes a way to arrange
1534 for something special to be done if the user switches to a different
1535 major mode. It is also useful for buffer-specific minor modes
1536 that should be forgotten if the user changes the major mode.
1538 For best results, make this variable buffer-local, so that it will
1539 disappear after doing its job and will not interfere with the
1540 subsequent major mode. @xref{Hooks}.
1543 @cindex permanent local variable
1544 A buffer-local variable is @dfn{permanent} if the variable name (a
1545 symbol) has a @code{permanent-local} property that is non-@code{nil}.
1546 Such variables are unaffected by @code{kill-all-local-variables}, and
1547 their local bindings are therefore not cleared by changing major modes.
1548 Permanent locals are appropriate for data pertaining to where the file
1549 came from or how to save it, rather than with how to edit the contents.
1552 @subsection The Default Value of a Buffer-Local Variable
1553 @cindex default value
1555 The global value of a variable with buffer-local bindings is also
1556 called the @dfn{default} value, because it is the value that is in
1557 effect whenever neither the current buffer nor the selected frame has
1558 its own binding for the variable.
1560 The functions @code{default-value} and @code{setq-default} access and
1561 change a variable's default value regardless of whether the current
1562 buffer has a buffer-local binding. For example, you could use
1563 @code{setq-default} to change the default setting of
1564 @code{paragraph-start} for most buffers; and this would work even when
1565 you are in a C or Lisp mode buffer that has a buffer-local value for
1569 The special forms @code{defvar} and @code{defconst} also set the
1570 default value (if they set the variable at all), rather than any
1573 @defun default-value symbol
1574 This function returns @var{symbol}'s default value. This is the value
1575 that is seen in buffers and frames that do not have their own values for
1576 this variable. If @var{symbol} is not buffer-local, this is equivalent
1577 to @code{symbol-value} (@pxref{Accessing Variables}).
1581 @defun default-boundp symbol
1582 The function @code{default-boundp} tells you whether @var{symbol}'s
1583 default value is nonvoid. If @code{(default-boundp 'foo)} returns
1584 @code{nil}, then @code{(default-value 'foo)} would get an error.
1586 @code{default-boundp} is to @code{default-value} as @code{boundp} is to
1587 @code{symbol-value}.
1590 @defspec setq-default [symbol form]@dots{}
1591 This special form gives each @var{symbol} a new default value, which is
1592 the result of evaluating the corresponding @var{form}. It does not
1593 evaluate @var{symbol}, but does evaluate @var{form}. The value of the
1594 @code{setq-default} form is the value of the last @var{form}.
1596 If a @var{symbol} is not buffer-local for the current buffer, and is not
1597 marked automatically buffer-local, @code{setq-default} has the same
1598 effect as @code{setq}. If @var{symbol} is buffer-local for the current
1599 buffer, then this changes the value that other buffers will see (as long
1600 as they don't have a buffer-local value), but not the value that the
1601 current buffer sees.
1605 ;; @r{In buffer @samp{foo}:}
1606 (make-local-variable 'buffer-local)
1607 @result{} buffer-local
1610 (setq buffer-local 'value-in-foo)
1611 @result{} value-in-foo
1614 (setq-default buffer-local 'new-default)
1615 @result{} new-default
1619 @result{} value-in-foo
1622 (default-value 'buffer-local)
1623 @result{} new-default
1627 ;; @r{In (the new) buffer @samp{bar}:}
1629 @result{} new-default
1632 (default-value 'buffer-local)
1633 @result{} new-default
1636 (setq buffer-local 'another-default)
1637 @result{} another-default
1640 (default-value 'buffer-local)
1641 @result{} another-default
1645 ;; @r{Back in buffer @samp{foo}:}
1647 @result{} value-in-foo
1648 (default-value 'buffer-local)
1649 @result{} another-default
1654 @defun set-default symbol value
1655 This function is like @code{setq-default}, except that @var{symbol} is
1656 an ordinary evaluated argument.
1660 (set-default (car '(a b c)) 23)
1670 A variable can be let-bound (@pxref{Local Variables}) to a value.
1671 This makes its global value shadowed by the binding;
1672 @code{default-value} will then return the value from that binding, not
1673 the global value, and @code{set-default} will be prevented from
1674 setting the global value (it will change the let-bound value instead).
1675 The following two functions allow to reference the global value even
1676 if it's shadowed by a let-binding.
1678 @cindex top-level default value
1679 @defun default-toplevel-value symbol
1680 This function returns the @dfn{top-level} default value of
1681 @var{symbol}, which is its value outside of any let-binding.
1686 (defvar variable 'global-value)
1690 (let ((variable 'let-binding))
1691 (default-value 'variable))
1692 @result{} let-binding
1695 (let ((variable 'let-binding))
1696 (default-toplevel-value 'variable))
1697 @result{} global-value
1701 @defun set-default-toplevel-value symbol value
1702 This function sets the top-level default value of @var{symbol} to the
1703 specified @var{value}. This comes in handy when you want to set the
1704 global value of @var{symbol} regardless of whether your code runs in
1705 the context of @var{symbol}'s let-binding.
1709 @node File Local Variables
1710 @section File Local Variables
1711 @cindex file local variables
1713 A file can specify local variable values; Emacs uses these to create
1714 buffer-local bindings for those variables in the buffer visiting that
1715 file. @xref{File Variables, , Local Variables in Files, emacs, The
1716 GNU Emacs Manual}, for basic information about file-local variables.
1717 This section describes the functions and variables that affect how
1718 file-local variables are processed.
1720 If a file-local variable could specify an arbitrary function or Lisp
1721 expression that would be called later, visiting a file could take over
1722 your Emacs. Emacs protects against this by automatically setting only
1723 those file-local variables whose specified values are known to be
1724 safe. Other file-local variables are set only if the user agrees.
1726 For additional safety, @code{read-circle} is temporarily bound to
1727 @code{nil} when Emacs reads file-local variables (@pxref{Input
1728 Functions}). This prevents the Lisp reader from recognizing circular
1729 and shared Lisp structures (@pxref{Circular Objects}).
1731 @defopt enable-local-variables
1732 This variable controls whether to process file-local variables.
1733 The possible values are:
1736 @item @code{t} (the default)
1737 Set the safe variables, and query (once) about any unsafe variables.
1739 Set only the safe variables and do not query.
1741 Set all the variables and do not query.
1743 Don't set any variables.
1745 Query (once) about all the variables.
1749 @defvar inhibit-local-variables-regexps
1750 This is a list of regular expressions. If a file has a name
1751 matching an element of this list, then it is not scanned for
1752 any form of file-local variable. For examples of why you might want
1753 to use this, @pxref{Auto Major Mode}.
1756 @defun hack-local-variables &optional handle-mode
1757 This function parses, and binds or evaluates as appropriate, any local
1758 variables specified by the contents of the current buffer. The variable
1759 @code{enable-local-variables} has its effect here. However, this
1760 function does not look for the @samp{mode:} local variable in the
1761 @w{@samp{-*-}} line. @code{set-auto-mode} does that, also taking
1762 @code{enable-local-variables} into account (@pxref{Auto Major Mode}).
1764 This function works by walking the alist stored in
1765 @code{file-local-variables-alist} and applying each local variable in
1766 turn. It calls @code{before-hack-local-variables-hook} and
1767 @code{hack-local-variables-hook} before and after applying the
1768 variables, respectively. It only calls the before-hook if the alist
1769 is non-@code{nil}; it always calls the other hook. This
1770 function ignores a @samp{mode} element if it specifies the same major
1771 mode as the buffer already has.
1773 If the optional argument @var{handle-mode} is @code{t}, then all this
1774 function does is return a symbol specifying the major mode, if the
1775 @w{@samp{-*-}} line or the local variables list specifies one, and
1776 @code{nil} otherwise. It does not set the mode or any other
1777 file-local variable. If @var{handle-mode} has any value other than
1778 @code{nil} or @code{t}, any settings of @samp{mode} in the
1779 @w{@samp{-*-}} line or the local variables list are ignored, and the
1780 other settings are applied. If @var{handle-mode} is @code{nil}, all
1781 the file local variables are set.
1784 @defvar file-local-variables-alist
1785 This buffer-local variable holds the alist of file-local variable
1786 settings. Each element of the alist is of the form
1787 @w{@code{(@var{var} . @var{value})}}, where @var{var} is a symbol of
1788 the local variable and @var{value} is its value. When Emacs visits a
1789 file, it first collects all the file-local variables into this alist,
1790 and then the @code{hack-local-variables} function applies them one by
1794 @defvar before-hack-local-variables-hook
1795 Emacs calls this hook immediately before applying file-local variables
1796 stored in @code{file-local-variables-alist}.
1799 @defvar hack-local-variables-hook
1800 Emacs calls this hook immediately after it finishes applying
1801 file-local variables stored in @code{file-local-variables-alist}.
1804 @cindex safe local variable
1805 You can specify safe values for a variable with a
1806 @code{safe-local-variable} property. The property has to be a
1807 function of one argument; any value is safe if the function returns
1808 non-@code{nil} given that value. Many commonly-encountered file
1809 variables have @code{safe-local-variable} properties; these include
1810 @code{fill-column}, @code{fill-prefix}, and @code{indent-tabs-mode}.
1811 For boolean-valued variables that are safe, use @code{booleanp} as the
1814 When defining a user option using @code{defcustom}, you can set its
1815 @code{safe-local-variable} property by adding the arguments
1816 @code{:safe @var{function}} to @code{defcustom} (@pxref{Variable
1819 @defopt safe-local-variable-values
1820 This variable provides another way to mark some variable values as
1821 safe. It is a list of cons cells @code{(@var{var} . @var{val})},
1822 where @var{var} is a variable name and @var{val} is a value which is
1823 safe for that variable.
1825 When Emacs asks the user whether or not to obey a set of file-local
1826 variable specifications, the user can choose to mark them as safe.
1827 Doing so adds those variable/value pairs to
1828 @code{safe-local-variable-values}, and saves it to the user's custom
1832 @defun safe-local-variable-p sym val
1833 This function returns non-@code{nil} if it is safe to give @var{sym}
1834 the value @var{val}, based on the above criteria.
1837 @c @cindex risky local variable Duplicates risky-local-variable
1838 Some variables are considered @dfn{risky}. If a variable is risky,
1839 it is never entered automatically into
1840 @code{safe-local-variable-values}; Emacs always queries before setting
1841 a risky variable, unless the user explicitly allows a value by
1842 customizing @code{safe-local-variable-values} directly.
1844 Any variable whose name has a non-@code{nil}
1845 @code{risky-local-variable} property is considered risky. When you
1846 define a user option using @code{defcustom}, you can set its
1847 @code{risky-local-variable} property by adding the arguments
1848 @code{:risky @var{value}} to @code{defcustom} (@pxref{Variable
1849 Definitions}). In addition, any variable whose name ends in any of
1850 @samp{-command}, @samp{-frame-alist}, @samp{-function},
1851 @samp{-functions}, @samp{-hook}, @samp{-hooks}, @samp{-form},
1852 @samp{-forms}, @samp{-map}, @samp{-map-alist}, @samp{-mode-alist},
1853 @samp{-program}, or @samp{-predicate} is automatically considered
1854 risky. The variables @samp{font-lock-keywords},
1855 @samp{font-lock-keywords} followed by a digit, and
1856 @samp{font-lock-syntactic-keywords} are also considered risky.
1858 @defun risky-local-variable-p sym
1859 This function returns non-@code{nil} if @var{sym} is a risky variable,
1860 based on the above criteria.
1863 @defvar ignored-local-variables
1864 This variable holds a list of variables that should not be given local
1865 values by files. Any value specified for one of these variables is
1869 The @samp{Eval:} ``variable'' is also a potential loophole, so Emacs
1870 normally asks for confirmation before handling it.
1872 @defopt enable-local-eval
1873 This variable controls processing of @samp{Eval:} in @samp{-*-} lines
1875 lists in files being visited. A value of @code{t} means process them
1876 unconditionally; @code{nil} means ignore them; anything else means ask
1877 the user what to do for each file. The default value is @code{maybe}.
1880 @defopt safe-local-eval-forms
1881 This variable holds a list of expressions that are safe to
1882 evaluate when found in the @samp{Eval:} ``variable'' in a file
1883 local variables list.
1886 If the expression is a function call and the function has a
1887 @code{safe-local-eval-function} property, the property value
1888 determines whether the expression is safe to evaluate. The property
1889 value can be a predicate to call to test the expression, a list of
1890 such predicates (it's safe if any predicate succeeds), or @code{t}
1891 (always safe provided the arguments are constant).
1893 Text properties are also potential loopholes, since their values
1894 could include functions to call. So Emacs discards all text
1895 properties from string values specified for file-local variables.
1897 @node Directory Local Variables
1898 @section Directory Local Variables
1899 @cindex directory local variables
1901 A directory can specify local variable values common to all files in
1902 that directory; Emacs uses these to create buffer-local bindings for
1903 those variables in buffers visiting any file in that directory. This
1904 is useful when the files in the directory belong to some @dfn{project}
1905 and therefore share the same local variables.
1907 There are two different methods for specifying directory local
1908 variables: by putting them in a special file, or by defining a
1909 @dfn{project class} for that directory.
1911 @defvr Constant dir-locals-file
1912 This constant is the name of the file where Emacs expects to find the
1913 directory-local variables. The name of the file is
1914 @file{.dir-locals.el}@footnote{
1915 The MS-DOS version of Emacs uses @file{_dir-locals.el} instead, due to
1916 limitations of the DOS filesystems.
1917 }. A file by that name in a directory causes Emacs to apply its
1918 settings to any file in that directory or any of its subdirectories
1919 (optionally, you can exclude subdirectories; see below).
1920 If some of the subdirectories have their own @file{.dir-locals.el}
1921 files, Emacs uses the settings from the deepest file it finds starting
1922 from the file's directory and moving up the directory tree. This
1923 constant is also used to derive the name of a second dir-locals file
1924 @file{.dir-locals-2.el}. If this second dir-locals file is present,
1925 then that is loaded instead of @file{.dir-locals.el}. This is useful
1926 when @file{.dir-locals.el} is under version control in a shared
1927 repository and cannot be used for personal customizations. The file
1928 specifies local variables as a specially formatted list; see
1929 @ref{Directory Variables, , Per-directory Local Variables, emacs, The
1930 GNU Emacs Manual}, for more details.
1933 @defun hack-dir-local-variables
1934 This function reads the @code{.dir-locals.el} file and stores the
1935 directory-local variables in @code{file-local-variables-alist} that is
1936 local to the buffer visiting any file in the directory, without
1937 applying them. It also stores the directory-local settings in
1938 @code{dir-locals-class-alist}, where it defines a special class for
1939 the directory in which @file{.dir-locals.el} file was found. This
1940 function works by calling @code{dir-locals-set-class-variables} and
1941 @code{dir-locals-set-directory-class}, described below.
1944 @defun hack-dir-local-variables-non-file-buffer
1945 This function looks for directory-local variables, and immediately
1946 applies them in the current buffer. It is intended to be called in
1947 the mode commands for non-file buffers, such as Dired buffers, to let
1948 them obey directory-local variable settings. For non-file buffers,
1949 Emacs looks for directory-local variables in @code{default-directory}
1950 and its parent directories.
1953 @defun dir-locals-set-class-variables class variables
1954 This function defines a set of variable settings for the named
1955 @var{class}, which is a symbol. You can later assign the class to one
1956 or more directories, and Emacs will apply those variable settings to
1957 all files in those directories. The list in @var{variables} can be of
1958 one of the two forms: @code{(@var{major-mode} . @var{alist})} or
1959 @code{(@var{directory} . @var{list})}. With the first form, if the
1960 file's buffer turns on a mode that is derived from @var{major-mode},
1961 then the all the variables in the associated @var{alist} are applied;
1962 @var{alist} should be of the form @code{(@var{name} . @var{value})}.
1963 A special value @code{nil} for @var{major-mode} means the settings are
1964 applicable to any mode. In @var{alist}, you can use a special
1965 @var{name}: @code{subdirs}. If the associated value is
1966 @code{nil}, the alist is only applied to files in the relevant
1967 directory, not to those in any subdirectories.
1969 With the second form of @var{variables}, if @var{directory} is the
1970 initial substring of the file's directory, then @var{list} is applied
1971 recursively by following the above rules; @var{list} should be of one
1972 of the two forms accepted by this function in @var{variables}.
1975 @defun dir-locals-set-directory-class directory class &optional mtime
1976 This function assigns @var{class} to all the files in @code{directory}
1977 and its subdirectories. Thereafter, all the variable settings
1978 specified for @var{class} will be applied to any visited file in
1979 @var{directory} and its children. @var{class} must have been already
1980 defined by @code{dir-locals-set-class-variables}.
1982 Emacs uses this function internally when it loads directory variables
1983 from a @code{.dir-locals.el} file. In that case, the optional
1984 argument @var{mtime} holds the file modification time (as returned by
1985 @code{file-attributes}). Emacs uses this time to check stored
1986 local variables are still valid. If you are assigning a class
1987 directly, not via a file, this argument should be @code{nil}.
1990 @defvar dir-locals-class-alist
1991 This alist holds the class symbols and the associated variable
1992 settings. It is updated by @code{dir-locals-set-class-variables}.
1995 @defvar dir-locals-directory-cache
1996 This alist holds directory names, their assigned class names, and
1997 modification times of the associated directory local variables file
1998 (if there is one). The function @code{dir-locals-set-directory-class}
2002 @defvar enable-dir-local-variables
2003 If @code{nil}, directory-local variables are ignored. This variable
2004 may be useful for modes that want to ignore directory-locals while
2005 still respecting file-local variables (@pxref{File Local Variables}).
2008 @node Connection Local Variables
2009 @section Connection Local Variables
2010 @cindex connection local variables
2012 Connection-local variables provide a general mechanism for different
2013 variable settings in buffers with a remote connection. They are bound
2014 and set depending on the remote connection a buffer is dedicated to.
2016 @defun connection-local-set-profile-variables profile variables
2017 This function defines a set of variable settings for the connection
2018 @var{profile}, which is a symbol. You can later assign the connection
2019 profile to one or more remote connections, and Emacs will apply those
2020 variable settings to all process buffers for those connections. The
2021 list in @var{variables} is an alist of the form
2022 @code{(@var{name}@tie{}.@tie{}@var{value})}. Example:
2026 (connection-local-set-profile-variables
2028 '((shell-file-name . "/bin/bash")
2029 (shell-command-switch . "-c")
2030 (shell-interactive-switch . "-i")
2031 (shell-login-switch . "-l")))
2035 (connection-local-set-profile-variables
2037 '((shell-file-name . "/bin/ksh")
2038 (shell-command-switch . "-c")
2039 (shell-interactive-switch . "-i")
2040 (shell-login-switch . "-l")))
2044 (connection-local-set-profile-variables
2046 '((null-device . "/dev/null")))
2051 @defvar connection-local-profile-alist
2052 This alist holds the connection profile symbols and the associated
2053 variable settings. It is updated by
2054 @code{connection-local-set-profile-variables}.
2057 @defun connection-local-set-profiles criteria &rest profiles
2058 This function assigns @var{profiles}, which are symbols, to all remote
2059 connections identified by @var{criteria}. @var{criteria} is a plist
2060 identifying a connection and the application using this connection.
2061 Property names might be @code{:application}, @code{:protocol},
2062 @code{:user} and @code{:machine}. The property value of
2063 @code{:application} is a symbol, all other property values are
2064 strings. All properties are optional; if @var{criteria} is nil, it
2065 always applies. Example:
2069 (connection-local-set-profiles
2070 '(:application 'tramp :protocol "ssh" :machine "localhost")
2071 'remote-bash 'remote-null-device)
2075 (connection-local-set-profiles
2076 '(:application 'tramp :protocol "sudo"
2077 :user "root" :machine "localhost")
2078 'remote-ksh 'remote-null-device)
2082 If @var{criteria} is nil, it applies for all remote connections.
2083 Therefore, the example above would be equivalent to
2087 (connection-local-set-profiles
2088 '(:application 'tramp :protocol "ssh" :machine "localhost")
2093 (connection-local-set-profiles
2094 '(:application 'tramp :protocol "sudo"
2095 :user "root" :machine "localhost")
2100 (connection-local-set-profiles
2101 nil 'remote-null-device)
2105 Any connection profile of @var{profiles} must have been already
2106 defined by @code{connection-local-set-profile-variables}.
2109 @defvar connection-local-criteria-alist
2110 This alist contains connection criteria and their assigned profile
2111 names. The function @code{connection-local-set-profiles} updates this
2115 @defun hack-connection-local-variables criteria
2116 This function collects applicable connection-local variables
2117 associated with @var{criteria} in
2118 @code{connection-local-variables-alist}, without applying them.
2123 (hack-connection-local-variables
2124 '(:application 'tramp :protocol "ssh" :machine "localhost"))
2128 connection-local-variables-alist
2129 @result{} ((null-device . "/dev/null")
2130 (shell-login-switch . "-l")
2131 (shell-interactive-switch . "-i")
2132 (shell-command-switch . "-c")
2133 (shell-file-name . "/bin/bash"))
2138 @defun hack-connection-local-variables-apply criteria
2139 This function looks for connection-local variables according to
2140 @var{criteria}, and immediately applies them in the current buffer.
2143 @defmac with-connection-local-profiles profiles &rest body
2144 All connection-local variables, which are specified by a connection
2145 profile in @var{profiles}, are applied.
2147 After that, @var{body} is executed, and the connection-local variables
2148 are unwound. Example:
2152 (connection-local-set-profile-variables
2154 '((perl-command-name . "/usr/local/bin/perl")
2155 (perl-command-switch . "-e %s")))
2159 (with-connection-local-profiles '(remote-perl)
2160 do something useful)
2165 @defvar enable-connection-local-variables
2166 If @code{nil}, connection-local variables are ignored. This variable
2167 shall be changed temporarily only in special modes.
2170 @node Variable Aliases
2171 @section Variable Aliases
2172 @cindex variable aliases
2173 @cindex alias, for variables
2175 It is sometimes useful to make two variables synonyms, so that both
2176 variables always have the same value, and changing either one also
2177 changes the other. Whenever you change the name of a
2178 variable---either because you realize its old name was not well
2179 chosen, or because its meaning has partly changed---it can be useful
2180 to keep the old name as an @emph{alias} of the new one for
2181 compatibility. You can do this with @code{defvaralias}.
2183 @defun defvaralias new-alias base-variable &optional docstring
2184 This function defines the symbol @var{new-alias} as a variable alias
2185 for symbol @var{base-variable}. This means that retrieving the value
2186 of @var{new-alias} returns the value of @var{base-variable}, and
2187 changing the value of @var{new-alias} changes the value of
2188 @var{base-variable}. The two aliased variable names always share the
2189 same value and the same bindings.
2191 If the @var{docstring} argument is non-@code{nil}, it specifies the
2192 documentation for @var{new-alias}; otherwise, the alias gets the same
2193 documentation as @var{base-variable} has, if any, unless
2194 @var{base-variable} is itself an alias, in which case @var{new-alias} gets
2195 the documentation of the variable at the end of the chain of aliases.
2197 This function returns @var{base-variable}.
2200 Variable aliases are convenient for replacing an old name for a
2201 variable with a new name. @code{make-obsolete-variable} declares that
2202 the old name is obsolete and therefore that it may be removed at some
2203 stage in the future.
2205 @defun make-obsolete-variable obsolete-name current-name when &optional access-type
2206 This function makes the byte compiler warn that the variable
2207 @var{obsolete-name} is obsolete. If @var{current-name} is a symbol,
2208 it is the variable's new name; then the warning message says to use
2209 @var{current-name} instead of @var{obsolete-name}. If
2210 @var{current-name} is a string, this is the message and there is no
2211 replacement variable. @var{when} should be a string indicating when
2212 the variable was first made obsolete (usually a version number
2215 The optional argument @var{access-type}, if non-@code{nil}, should
2216 specify the kind of access that will trigger obsolescence warnings; it
2217 can be either @code{get} or @code{set}.
2220 You can make two variables synonyms and declare one obsolete at the
2221 same time using the macro @code{define-obsolete-variable-alias}.
2223 @defmac define-obsolete-variable-alias obsolete-name current-name &optional when docstring
2224 This macro marks the variable @var{obsolete-name} as obsolete and also
2225 makes it an alias for the variable @var{current-name}. It is
2226 equivalent to the following:
2229 (defvaralias @var{obsolete-name} @var{current-name} @var{docstring})
2230 (make-obsolete-variable @var{obsolete-name} @var{current-name} @var{when})
2234 @defun indirect-variable variable
2235 This function returns the variable at the end of the chain of aliases
2236 of @var{variable}. If @var{variable} is not a symbol, or if @var{variable} is
2237 not defined as an alias, the function returns @var{variable}.
2239 This function signals a @code{cyclic-variable-indirection} error if
2240 there is a loop in the chain of symbols.
2244 (defvaralias 'foo 'bar)
2245 (indirect-variable 'foo)
2247 (indirect-variable 'bar)
2263 @node Variables with Restricted Values
2264 @section Variables with Restricted Values
2265 @cindex lisp variables defined in C, restrictions
2267 Ordinary Lisp variables can be assigned any value that is a valid
2268 Lisp object. However, certain Lisp variables are not defined in Lisp,
2269 but in C@. Most of these variables are defined in the C code using
2270 @code{DEFVAR_LISP}. Like variables defined in Lisp, these can take on
2271 any value. However, some variables are defined using
2272 @code{DEFVAR_INT} or @code{DEFVAR_BOOL}. @xref{Defining Lisp
2273 variables in C,, Writing Emacs Primitives}, in particular the
2274 description of functions of the type @code{syms_of_@var{filename}},
2275 for a brief discussion of the C implementation.
2277 Variables of type @code{DEFVAR_BOOL} can only take on the values
2278 @code{nil} or @code{t}. Attempting to assign them any other value
2279 will set them to @code{t}:
2282 (let ((display-hourglass 5))
2287 @defvar byte-boolean-vars
2288 This variable holds a list of all variables of type @code{DEFVAR_BOOL}.
2291 Variables of type @code{DEFVAR_INT} can take on only integer values.
2292 Attempting to assign them any other value will result in an error:
2295 (setq undo-limit 1000.0)
2296 @error{} Wrong type argument: integerp, 1000.0
2299 @node Generalized Variables
2300 @section Generalized Variables
2302 @cindex generalized variable
2304 A @dfn{generalized variable} or @dfn{place form} is one of the many places
2305 in Lisp memory where values can be stored. The simplest place form is
2306 a regular Lisp variable. But the @sc{car}s and @sc{cdr}s of lists, elements
2307 of arrays, properties of symbols, and many other locations are also
2308 places where Lisp values are stored.
2310 Generalized variables are analogous to lvalues in the C
2311 language, where @samp{x = a[i]} gets an element from an array
2312 and @samp{a[i] = x} stores an element using the same notation.
2313 Just as certain forms like @code{a[i]} can be lvalues in C, there
2314 is a set of forms that can be generalized variables in Lisp.
2317 * Setting Generalized Variables:: The @code{setf} macro.
2318 * Adding Generalized Variables:: Defining new @code{setf} forms.
2321 @node Setting Generalized Variables
2322 @subsection The @code{setf} Macro
2324 The @code{setf} macro is the most basic way to operate on generalized
2325 variables. The @code{setf} form is like @code{setq}, except that it
2326 accepts arbitrary place forms on the left side rather than just
2327 symbols. For example, @code{(setf (car a) b)} sets the car of
2328 @code{a} to @code{b}, doing the same operation as @code{(setcar a b)},
2329 but without having to remember two separate functions for setting and
2330 accessing every type of place.
2332 @defmac setf [place form]@dots{}
2333 This macro evaluates @var{form} and stores it in @var{place}, which
2334 must be a valid generalized variable form. If there are several
2335 @var{place} and @var{form} pairs, the assignments are done sequentially
2336 just as with @code{setq}. @code{setf} returns the value of the last
2340 The following Lisp forms will work as generalized variables, and
2341 so may appear in the @var{place} argument of @code{setf}:
2345 A symbol naming a variable. In other words, @code{(setf x y)} is
2346 exactly equivalent to @code{(setq x y)}, and @code{setq} itself is
2347 strictly speaking redundant given that @code{setf} exists. Many
2348 programmers continue to prefer @code{setq} for setting simple
2349 variables, though, purely for stylistic or historical reasons.
2350 The macro @code{(setf x y)} actually expands to @code{(setq x y)},
2351 so there is no performance penalty for using it in compiled code.
2354 A call to any of the following standard Lisp functions:
2357 aref cddr symbol-function
2358 car elt symbol-plist
2359 caar get symbol-value
2366 A call to any of the following Emacs-specific functions:
2369 alist-get process-get
2370 frame-parameter process-sentinel
2371 terminal-parameter window-buffer
2372 keymap-parent window-display-table
2373 match-data window-dedicated-p
2374 overlay-get window-hscroll
2375 overlay-start window-parameter
2376 overlay-end window-point
2377 process-buffer window-start
2378 process-filter default-value
2383 @code{setf} signals an error if you pass a @var{place} form that it
2384 does not know how to handle.
2386 @c And for cl-lib's cl-getf.
2387 Note that for @code{nthcdr}, the list argument of the function must
2388 itself be a valid @var{place} form. For example, @code{(setf (nthcdr
2389 0 foo) 7)} will set @code{foo} itself to 7.
2390 @c The use of @code{nthcdr} as a @var{place} form is an extension
2391 @c to standard Common Lisp.
2393 @c FIXME I don't think is a particularly good way to do it,
2394 @c but these macros are introduced before generalized variables are.
2395 The macros @code{push} (@pxref{List Variables}) and @code{pop}
2396 (@pxref{List Elements}) can manipulate generalized variables,
2397 not just lists. @code{(pop @var{place})} removes and returns the first
2398 element of the list stored in @var{place}. It is analogous to
2399 @code{(prog1 (car @var{place}) (setf @var{place} (cdr @var{place})))},
2400 except that it takes care to evaluate all subforms only once.
2401 @code{(push @var{x} @var{place})} inserts @var{x} at the front of
2402 the list stored in @var{place}. It is analogous to @code{(setf
2403 @var{place} (cons @var{x} @var{place}))}, except for evaluation of the
2404 subforms. Note that @code{push} and @code{pop} on an @code{nthcdr}
2405 place can be used to insert or delete at any position in a list.
2407 The @file{cl-lib} library defines various extensions for generalized
2408 variables, including additional @code{setf} places.
2409 @xref{Generalized Variables,,, cl, Common Lisp Extensions}.
2412 @node Adding Generalized Variables
2413 @subsection Defining new @code{setf} forms
2415 This section describes how to define new forms that @code{setf} can
2418 @defmac gv-define-simple-setter name setter &optional fix-return
2419 This macro enables you to easily define @code{setf} methods for simple
2420 cases. @var{name} is the name of a function, macro, or special form.
2421 You can use this macro whenever @var{name} has a directly
2422 corresponding @var{setter} function that updates it, e.g.,
2423 @code{(gv-define-simple-setter car setcar)}.
2425 This macro translates a call of the form
2428 (setf (@var{name} @var{args}@dots{}) @var{value})
2433 (@var{setter} @var{args}@dots{} @var{value})
2437 Such a @code{setf} call is documented to return @var{value}. This is
2438 no problem with, e.g., @code{car} and @code{setcar}, because
2439 @code{setcar} returns the value that it set. If your @var{setter}
2440 function does not return @var{value}, use a non-@code{nil} value for
2441 the @var{fix-return} argument of @code{gv-define-simple-setter}. This
2442 expands into something equivalent to
2444 (let ((temp @var{value}))
2445 (@var{setter} @var{args}@dots{} temp)
2448 so ensuring that it returns the correct result.
2452 @defmac gv-define-setter name arglist &rest body
2453 This macro allows for more complex @code{setf} expansions than the
2454 previous form. You may need to use this form, for example, if there
2455 is no simple setter function to call, or if there is one but it
2456 requires different arguments to the place form.
2458 This macro expands the form
2459 @code{(setf (@var{name} @var{args}@dots{}) @var{value})} by
2460 first binding the @code{setf} argument forms
2461 @code{(@var{value} @var{args}@dots{})} according to @var{arglist},
2462 and then executing @var{body}. @var{body} should return a Lisp
2463 form that does the assignment, and finally returns the value that was
2464 set. An example of using this macro is:
2467 (gv-define-setter caar (val x) `(setcar (car ,x) ,val))
2471 @findex gv-define-expander
2473 @c FIXME? Not sure what or how much to say about these.
2474 @c See cl.texi for an example of using gv-letplace.
2475 For more control over the expansion, see the macro @code{gv-define-expander}.
2476 The macro @code{gv-letplace} can be useful in defining macros that
2477 perform similarly to @code{setf}; for example, the @code{incf} macro
2478 of Common Lisp. Consult the source file @file{gv.el} for more details.
2480 @cindex CL note---no @code{setf} functions
2482 @b{Common Lisp note:} Common Lisp defines another way to specify the
2483 @code{setf} behavior of a function, namely @code{setf} functions,
2484 whose names are lists @code{(setf @var{name})} rather than symbols.
2485 For example, @code{(defun (setf foo) @dots{})} defines the function
2486 that is used when @code{setf} is applied to @code{foo}. Emacs does
2487 not support this. It is a compile-time error to use @code{setf} on a
2488 form that has not already had an appropriate expansion defined. In
2489 Common Lisp, this is not an error since the function @code{(setf
2490 @var{func})} might be defined later.