annotate lispref/variables.texi @ 45869:fb2ae7bd271d

(facemenu-map): Rename to Describe Text to Describe Properties and use describe-text-properties.
author Richard M. Stallman <rms@gnu.org>
date Mon, 17 Jun 2002 16:14:37 +0000
parents 51bf5310b422
children 5d5a55d8897b
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
27390
10e53615a9d2 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27389
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000
27189
d2e5f1b7d8e2 Update copyrights.
Gerd Moellmann <gerd@gnu.org>
parents: 27187
diff changeset
4 @c Free Software Foundation, Inc.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
5 @c See the file elisp.texi for copying conditions.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
6 @setfilename ../info/variables
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
7 @node Variables, Functions, Control Structures, Top
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
8 @chapter Variables
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
9 @cindex variable
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
10
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
11 A @dfn{variable} is a name used in a program to stand for a value.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
12 Nearly all programming languages have variables of some sort. In the
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
13 text of a Lisp program, variables are written using the syntax for
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
14 symbols.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
15
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
16 In Lisp, unlike most programming languages, programs are represented
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
17 primarily as Lisp objects and only secondarily as text. The Lisp
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
18 objects used for variables are symbols: the symbol name is the variable
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
19 name, and the variable's value is stored in the value cell of the
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
20 symbol. The use of a symbol as a variable is independent of its use as
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
21 a function name. @xref{Symbol Components}.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
22
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
23 The Lisp objects that constitute a Lisp program determine the textual
7194
3112fb627aa0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6510
diff changeset
24 form of the program---it is simply the read syntax for those Lisp
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
25 objects. This is why, for example, a variable in a textual Lisp program
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
26 is written using the read syntax for the symbol that represents the
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
27 variable.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
28
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
29 @menu
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
30 * Global Variables:: Variable values that exist permanently, everywhere.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
31 * Constant Variables:: Certain "variables" have values that never change.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
32 * Local Variables:: Variable values that exist only temporarily.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
33 * Void Variables:: Symbols that lack values.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
34 * Defining Variables:: A definition says a symbol is used as a variable.
27389
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
35 * Tips for Defining:: Things you should think about when you
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
36 define a variable.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
37 * Accessing Variables:: Examining values of variables whose names
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
38 are known only at run time.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
39 * Setting Variables:: Storing new values in variables.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
40 * Variable Scoping:: How Lisp chooses among local and global values.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
41 * Buffer-Local Variables:: Variable values in effect only in one buffer.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
42 * Frame-Local Variables:: Variable values in effect only in one frame.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
43 * Future Local Variables:: New kinds of local values we might add some day.
39571
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
44 * Variable Aliases:: Variables that are aliases for other variables.
27389
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
45 * File Local Variables:: Handling local variable lists in files.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
46 @end menu
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
47
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
48 @node Global Variables
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
49 @section Global Variables
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
50 @cindex global variable
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
51
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
52 The simplest way to use a variable is @dfn{globally}. This means that
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
53 the variable has just one value at a time, and this value is in effect
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
54 (at least for the moment) throughout the Lisp system. The value remains
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
55 in effect until you specify a new one. When a new value replaces the
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
56 old one, no trace of the old value remains in the variable.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
57
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
58 You specify a value for a symbol with @code{setq}. For example,
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
59
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
60 @example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
61 (setq x '(a b))
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
62 @end example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
63
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
64 @noindent
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
65 gives the variable @code{x} the value @code{(a b)}. Note that
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
66 @code{setq} does not evaluate its first argument, the name of the
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
67 variable, but it does evaluate the second argument, the new value.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
68
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
69 Once the variable has a value, you can refer to it by using the symbol
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
70 by itself as an expression. Thus,
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
71
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
72 @example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
73 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
74 x @result{} (a b)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
75 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
76 @end example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
77
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
78 @noindent
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
79 assuming the @code{setq} form shown above has already been executed.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
80
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
81 If you do set the same variable again, the new value replaces the old
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
82 one:
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
83
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
84 @example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
85 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
86 x
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
87 @result{} (a b)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
88 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
89 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
90 (setq x 4)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
91 @result{} 4
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
92 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
93 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
94 x
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
95 @result{} 4
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
96 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
97 @end example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
98
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
99 @node Constant Variables
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
100 @section Variables that Never Change
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
101 @vindex nil
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
102 @vindex t
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
103 @kindex setting-constant
26200
798aeda17389 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
104 @cindex keyword symbol
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
105
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
106 In Emacs Lisp, certain symbols normally evaluate to themselves. These
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
107 include @code{nil} and @code{t}, as well as any symbol whose name starts
26200
798aeda17389 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
108 with @samp{:} (these are called @dfn{keywords}). These symbols cannot
798aeda17389 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
109 be rebound, nor can their values be changed. Any attempt to set or bind
798aeda17389 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
110 @code{nil} or @code{t} signals a @code{setting-constant} error. The
798aeda17389 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
111 same is true for a keyword (a symbol whose name starts with @samp{:}),
798aeda17389 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
112 if it is interned in the standard obarray, except that setting such a
798aeda17389 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
113 symbol to itself is not an error.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
114
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
115 @example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
116 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
117 nil @equiv{} 'nil
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
118 @result{} nil
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
119 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
120 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
121 (setq nil 500)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
122 @error{} Attempt to set constant symbol: nil
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
123 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
124 @end example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
125
27528
5b4130fa5ab6 keywordp, user-variable-p change.
Dave Love <fx@gnu.org>
parents: 27390
diff changeset
126 @defun keywordp object
5b4130fa5ab6 keywordp, user-variable-p change.
Dave Love <fx@gnu.org>
parents: 27390
diff changeset
127 @tindex keywordp
5b4130fa5ab6 keywordp, user-variable-p change.
Dave Love <fx@gnu.org>
parents: 27390
diff changeset
128 function returns @code{t} if @var{object} is a symbol whose name
5b4130fa5ab6 keywordp, user-variable-p change.
Dave Love <fx@gnu.org>
parents: 27390
diff changeset
129 starts with @samp{:}, interned in the standard obarray, and returns
5b4130fa5ab6 keywordp, user-variable-p change.
Dave Love <fx@gnu.org>
parents: 27390
diff changeset
130 @code{nil} otherwise.
5b4130fa5ab6 keywordp, user-variable-p change.
Dave Love <fx@gnu.org>
parents: 27390
diff changeset
131 @end defun
5b4130fa5ab6 keywordp, user-variable-p change.
Dave Love <fx@gnu.org>
parents: 27390
diff changeset
132
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
133 @node Local Variables
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
134 @section Local Variables
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
135 @cindex binding local variables
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
136 @cindex local variables
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
137 @cindex local binding
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
138 @cindex global binding
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
139
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
140 Global variables have values that last until explicitly superseded
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
141 with new values. Sometimes it is useful to create variable values that
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
142 exist temporarily---only until a certain part of the program finishes.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
143 These values are called @dfn{local}, and the variables so used are
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
144 called @dfn{local variables}.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
145
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
146 For example, when a function is called, its argument variables receive
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
147 new local values that last until the function exits. The @code{let}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
148 special form explicitly establishes new local values for specified
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
149 variables; these last until exit from the @code{let} form.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
150
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
151 @cindex shadowing of variables
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
152 Establishing a local value saves away the previous value (or lack of
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
153 one) of the variable. When the life span of the local value is over,
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
154 the previous value is restored. In the mean time, we say that the
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
155 previous value is @dfn{shadowed} and @dfn{not visible}. Both global and
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
156 local values may be shadowed (@pxref{Scope}).
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
157
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
158 If you set a variable (such as with @code{setq}) while it is local,
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
159 this replaces the local value; it does not alter the global value, or
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
160 previous local values, that are shadowed. To model this behavior, we
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
161 speak of a @dfn{local binding} of the variable as well as a local value.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
162
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
163 The local binding is a conceptual place that holds a local value.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
164 Entry to a function, or a special form such as @code{let}, creates the
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
165 local binding; exit from the function or from the @code{let} removes the
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
166 local binding. As long as the local binding lasts, the variable's value
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
167 is stored within it. Use of @code{setq} or @code{set} while there is a
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
168 local binding stores a different value into the local binding; it does
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
169 not create a new binding.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
170
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
171 We also speak of the @dfn{global binding}, which is where
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
172 (conceptually) the global value is kept.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
173
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
174 @cindex current binding
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
175 A variable can have more than one local binding at a time (for
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
176 example, if there are nested @code{let} forms that bind it). In such a
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
177 case, the most recently created local binding that still exists is the
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
178 @dfn{current binding} of the variable. (This rule is called
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
179 @dfn{dynamic scoping}; see @ref{Variable Scoping}.) If there are no
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
180 local bindings, the variable's global binding is its current binding.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
181 We sometimes call the current binding the @dfn{most-local existing
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
182 binding}, for emphasis. Ordinary evaluation of a symbol always returns
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
183 the value of its current binding.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
184
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
185 The special forms @code{let} and @code{let*} exist to create
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
186 local bindings.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
187
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
188 @defspec let (bindings@dots{}) forms@dots{}
7194
3112fb627aa0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6510
diff changeset
189 This special form binds variables according to @var{bindings} and then
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
190 evaluates all of the @var{forms} in textual order. The @code{let}-form
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
191 returns the value of the last form in @var{forms}.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
192
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
193 Each of the @var{bindings} is either @w{(i) a} symbol, in which case
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
194 that symbol is bound to @code{nil}; or @w{(ii) a} list of the form
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
195 @code{(@var{symbol} @var{value-form})}, in which case @var{symbol} is
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
196 bound to the result of evaluating @var{value-form}. If @var{value-form}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
197 is omitted, @code{nil} is used.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
198
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
199 All of the @var{value-form}s in @var{bindings} are evaluated in the
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
200 order they appear and @emph{before} binding any of the symbols to them.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
201 Here is an example of this: @code{Z} is bound to the old value of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
202 @code{Y}, which is 2, not the new value of @code{Y}, which is 1.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
203
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
204 @example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
205 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
206 (setq Y 2)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
207 @result{} 2
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
208 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
209 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
210 (let ((Y 1)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
211 (Z Y))
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
212 (list Y Z))
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
213 @result{} (1 2)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
214 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
215 @end example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
216 @end defspec
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
217
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
218 @defspec let* (bindings@dots{}) forms@dots{}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
219 This special form is like @code{let}, but it binds each variable right
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
220 after computing its local value, before computing the local value for
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
221 the next variable. Therefore, an expression in @var{bindings} can
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
222 reasonably refer to the preceding symbols bound in this @code{let*}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
223 form. Compare the following example with the example above for
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
224 @code{let}.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
225
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
226 @example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
227 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
228 (setq Y 2)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
229 @result{} 2
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
230 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
231 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
232 (let* ((Y 1)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
233 (Z Y)) ; @r{Use the just-established value of @code{Y}.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
234 (list Y Z))
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
235 @result{} (1 1)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
236 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
237 @end example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
238 @end defspec
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
239
7194
3112fb627aa0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6510
diff changeset
240 Here is a complete list of the other facilities that create local
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
241 bindings:
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
242
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
243 @itemize @bullet
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
244 @item
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
245 Function calls (@pxref{Functions}).
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
246
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
247 @item
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
248 Macro calls (@pxref{Macros}).
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
249
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
250 @item
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
251 @code{condition-case} (@pxref{Errors}).
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
252 @end itemize
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
253
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
254 Variables can also have buffer-local bindings (@pxref{Buffer-Local
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
255 Variables}) and frame-local bindings (@pxref{Frame-Local Variables}); a
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
256 few variables have terminal-local bindings (@pxref{Multiple Displays}).
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
257 These kinds of bindings work somewhat like ordinary local bindings, but
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
258 they are localized depending on ``where'' you are in Emacs, rather than
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
259 localized in time.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
260
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
261 @defvar max-specpdl-size
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
262 @cindex variable limit error
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
263 @cindex evaluation error
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
264 @cindex infinite recursion
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
265 This variable defines the limit on the total number of local variable
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
266 bindings and @code{unwind-protect} cleanups (@pxref{Nonlocal Exits})
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
267 that are allowed before signaling an error (with data @code{"Variable
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
268 binding depth exceeds max-specpdl-size"}).
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
269
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
270 This limit, with the associated error when it is exceeded, is one way
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
271 that Lisp avoids infinite recursion on an ill-defined function.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
272 @code{max-lisp-eval-depth} provides another limit on depth of nesting.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
273 @xref{Eval}.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
274
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
275 The default value is 600. Entry to the Lisp debugger increases the
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
276 value, if there is little room left, to make sure the debugger itself
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
277 has room to execute.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
278 @end defvar
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
279
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
280 @node Void Variables
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
281 @section When a Variable is ``Void''
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
282 @kindex void-variable
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
283 @cindex void variable
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
284
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
285 If you have never given a symbol any value as a global variable, we
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
286 say that that symbol's global value is @dfn{void}. In other words, the
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
287 symbol's value cell does not have any Lisp object in it. If you try to
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
288 evaluate the symbol, you get a @code{void-variable} error rather than
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
289 a value.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
290
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
291 Note that a value of @code{nil} is not the same as void. The symbol
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
292 @code{nil} is a Lisp object and can be the value of a variable just as any
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
293 other object can be; but it is @emph{a value}. A void variable does not
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
294 have any value.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
295
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
296 After you have given a variable a value, you can make it void once more
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
297 using @code{makunbound}.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
298
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
299 @defun makunbound symbol
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
300 This function makes the current variable binding of @var{symbol} void.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
301 Subsequent attempts to use this symbol's value as a variable will signal
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
302 the error @code{void-variable}, unless and until you set it again.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
303
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
304 @code{makunbound} returns @var{symbol}.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
305
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
306 @example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
307 @group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
308 (makunbound 'x) ; @r{Make the global value of @code{x} void.}
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
309 @result{} x
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
310 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
311 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
312 x
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
313 @error{} Symbol's value as variable is void: x
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
314 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
315 @end example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
316
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
317 If @var{symbol} is locally bound, @code{makunbound} affects the most
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
318 local existing binding. This is the only way a symbol can have a void
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
319 local binding, since all the constructs that create local bindings
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
320 create them with values. In this case, the voidness lasts at most as
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
321 long as the binding does; when the binding is removed due to exit from
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
322 the construct that made it, the previous local or global binding is
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
323 reexposed as usual, and the variable is no longer void unless the newly
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
324 reexposed binding was void all along.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
325
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
326 @smallexample
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
327 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
328 (setq x 1) ; @r{Put a value in the global binding.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
329 @result{} 1
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
330 (let ((x 2)) ; @r{Locally bind it.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
331 (makunbound 'x) ; @r{Void the local binding.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
332 x)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
333 @error{} Symbol's value as variable is void: x
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
334 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
335 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
336 x ; @r{The global binding is unchanged.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
337 @result{} 1
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
338
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
339 (let ((x 2)) ; @r{Locally bind it.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
340 (let ((x 3)) ; @r{And again.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
341 (makunbound 'x) ; @r{Void the innermost-local binding.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
342 x)) ; @r{And refer: it's void.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
343 @error{} Symbol's value as variable is void: x
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
344 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
345
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
346 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
347 (let ((x 2))
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
348 (let ((x 3))
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
349 (makunbound 'x)) ; @r{Void inner binding, then remove it.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
350 x) ; @r{Now outer @code{let} binding is visible.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
351 @result{} 2
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
352 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
353 @end smallexample
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
354 @end defun
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
355
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
356 A variable that has been made void with @code{makunbound} is
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
357 indistinguishable from one that has never received a value and has
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
358 always been void.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
359
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
360 You can use the function @code{boundp} to test whether a variable is
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
361 currently void.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
362
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
363 @defun boundp variable
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
364 @code{boundp} returns @code{t} if @var{variable} (a symbol) is not void;
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
365 more precisely, if its current binding is not void. It returns
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
366 @code{nil} otherwise.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
367
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
368 @smallexample
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
369 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
370 (boundp 'abracadabra) ; @r{Starts out void.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
371 @result{} nil
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
372 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
373 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
374 (let ((abracadabra 5)) ; @r{Locally bind it.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
375 (boundp 'abracadabra))
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
376 @result{} t
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
377 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
378 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
379 (boundp 'abracadabra) ; @r{Still globally void.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
380 @result{} nil
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
381 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
382 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
383 (setq abracadabra 5) ; @r{Make it globally nonvoid.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
384 @result{} 5
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
385 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
386 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
387 (boundp 'abracadabra)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
388 @result{} t
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
389 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
390 @end smallexample
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
391 @end defun
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
392
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
393 @node Defining Variables
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
394 @section Defining Global Variables
7194
3112fb627aa0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6510
diff changeset
395 @cindex variable definition
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
396
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
397 You may announce your intention to use a symbol as a global variable
7194
3112fb627aa0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6510
diff changeset
398 with a @dfn{variable definition}: a special form, either @code{defconst}
3112fb627aa0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6510
diff changeset
399 or @code{defvar}.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
400
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
401 In Emacs Lisp, definitions serve three purposes. First, they inform
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
402 people who read the code that certain symbols are @emph{intended} to be
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
403 used a certain way (as variables). Second, they inform the Lisp system
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
404 of these things, supplying a value and documentation. Third, they
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
405 provide information to utilities such as @code{etags} and
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
406 @code{make-docfile}, which create data bases of the functions and
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
407 variables in a program.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
408
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
409 The difference between @code{defconst} and @code{defvar} is primarily
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
410 a matter of intent, serving to inform human readers of whether the value
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
411 should ever change. Emacs Lisp does not restrict the ways in which a
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
412 variable can be used based on @code{defconst} or @code{defvar}
7194
3112fb627aa0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6510
diff changeset
413 declarations. However, it does make a difference for initialization:
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
414 @code{defconst} unconditionally initializes the variable, while
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
415 @code{defvar} initializes it only if it is void.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
416
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
417 @ignore
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
418 One would expect user option variables to be defined with
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
419 @code{defconst}, since programs do not change them. Unfortunately, this
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
420 has bad results if the definition is in a library that is not preloaded:
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
421 @code{defconst} would override any prior value when the library is
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
422 loaded. Users would like to be able to set user options in their init
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
423 files, and override the default values given in the definitions. For
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
424 this reason, user options must be defined with @code{defvar}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
425 @end ignore
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
426
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
427 @defspec defvar symbol [value [doc-string]]
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
428 This special form defines @var{symbol} as a variable and can also
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
429 initialize and document it. The definition informs a person reading
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
430 your code that @var{symbol} is used as a variable that might be set or
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
431 changed. Note that @var{symbol} is not evaluated; the symbol to be
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
432 defined must appear explicitly in the @code{defvar}.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
433
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
434 If @var{symbol} is void and @var{value} is specified, @code{defvar}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
435 evaluates it and sets @var{symbol} to the result. But if @var{symbol}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
436 already has a value (i.e., it is not void), @var{value} is not even
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
437 evaluated, and @var{symbol}'s value remains unchanged. If @var{value}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
438 is omitted, the value of @var{symbol} is not changed in any case.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
439
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
440 If @var{symbol} has a buffer-local binding in the current buffer,
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
441 @code{defvar} operates on the default value, which is buffer-independent,
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
442 not the current (buffer-local) binding. It sets the default value if
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
443 the default value is void. @xref{Buffer-Local Variables}.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
444
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
445 When you evaluate a top-level @code{defvar} form with @kbd{C-M-x} in
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
446 Emacs Lisp mode (@code{eval-defun}), a special feature of
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
447 @code{eval-defun} arranges to set the variable unconditionally, without
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
448 testing whether its value is void.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
449
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
450 If the @var{doc-string} argument appears, it specifies the documentation
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
451 for the variable. (This opportunity to specify documentation is one of
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
452 the main benefits of defining the variable.) The documentation is
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
453 stored in the symbol's @code{variable-documentation} property. The
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
454 Emacs help functions (@pxref{Documentation}) look for this property.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
455
39165
27db1f1aac19 Correct the statement of when to use * in variable doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 37583
diff changeset
456 If the variable is a user option that users would want to set
27db1f1aac19 Correct the statement of when to use * in variable doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 37583
diff changeset
457 interactively, you should use @samp{*} as the first character of
27db1f1aac19 Correct the statement of when to use * in variable doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 37583
diff changeset
458 @var{doc-string}. This lets users set the variable conveniently using
27db1f1aac19 Correct the statement of when to use * in variable doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 37583
diff changeset
459 the @code{set-variable} command. Note that you should nearly always
27db1f1aac19 Correct the statement of when to use * in variable doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 37583
diff changeset
460 use @code{defcustom} instead of @code{defvar} to define these
27db1f1aac19 Correct the statement of when to use * in variable doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 37583
diff changeset
461 variables, so that users can use @kbd{M-x customize} and related
27db1f1aac19 Correct the statement of when to use * in variable doc strings.
Richard M. Stallman <rms@gnu.org>
parents: 37583
diff changeset
462 commands to set them. @xref{Customization}.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
463
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
464 Here are some examples. This form defines @code{foo} but does not
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
465 initialize it:
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
466
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
467 @example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
468 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
469 (defvar foo)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
470 @result{} foo
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
471 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
472 @end example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
473
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
474 This example initializes the value of @code{bar} to @code{23}, and gives
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
475 it a documentation string:
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
476
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
477 @example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
478 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
479 (defvar bar 23
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
480 "The normal weight of a bar.")
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
481 @result{} bar
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
482 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
483 @end example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
484
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
485 The following form changes the documentation string for @code{bar},
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
486 making it a user option, but does not change the value, since @code{bar}
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
487 already has a value. (The addition @code{(1+ nil)} would get an error
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
488 if it were evaluated, but since it is not evaluated, there is no error.)
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
489
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
490 @example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
491 @group
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
492 (defvar bar (1+ nil)
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
493 "*The normal weight of a bar.")
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
494 @result{} bar
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
495 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
496 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
497 bar
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
498 @result{} 23
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
499 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
500 @end example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
501
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
502 Here is an equivalent expression for the @code{defvar} special form:
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
503
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
504 @example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
505 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
506 (defvar @var{symbol} @var{value} @var{doc-string})
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
507 @equiv{}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
508 (progn
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
509 (if (not (boundp '@var{symbol}))
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
510 (setq @var{symbol} @var{value}))
12821
259b1abdec5f Fix defvar equivalent expression.
Richard M. Stallman <rms@gnu.org>
parents: 12820
diff changeset
511 (if '@var{doc-string}
259b1abdec5f Fix defvar equivalent expression.
Richard M. Stallman <rms@gnu.org>
parents: 12820
diff changeset
512 (put '@var{symbol} 'variable-documentation '@var{doc-string}))
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
513 '@var{symbol})
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
514 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
515 @end example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
516
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
517 The @code{defvar} form returns @var{symbol}, but it is normally used
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
518 at top level in a file where its value does not matter.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
519 @end defspec
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
520
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
521 @defspec defconst symbol [value [doc-string]]
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
522 This special form defines @var{symbol} as a value and initializes it.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
523 It informs a person reading your code that @var{symbol} has a standard
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
524 global value, established here, that should not be changed by the user
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
525 or by other programs. Note that @var{symbol} is not evaluated; the
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
526 symbol to be defined must appear explicitly in the @code{defconst}.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
527
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
528 @code{defconst} always evaluates @var{value}, and sets the value of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
529 @var{symbol} to the result if @var{value} is given. If @var{symbol}
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
530 does have a buffer-local binding in the current buffer, @code{defconst}
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
531 sets the default value, not the buffer-local value. (But you should not
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
532 be making buffer-local bindings for a symbol that is defined with
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
533 @code{defconst}.)
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
534
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
535 Here, @code{pi} is a constant that presumably ought not to be changed
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
536 by anyone (attempts by the Indiana State Legislature notwithstanding).
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
537 As the second form illustrates, however, this is only advisory.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
538
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
539 @example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
540 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
541 (defconst pi 3.1415 "Pi to five places.")
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
542 @result{} pi
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
543 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
544 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
545 (setq pi 3)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
546 @result{} pi
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
547 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
548 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
549 pi
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
550 @result{} 3
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
551 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
552 @end example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
553 @end defspec
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
554
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
555 @defun user-variable-p variable
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
556 @cindex user option
7194
3112fb627aa0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6510
diff changeset
557 This function returns @code{t} if @var{variable} is a user option---a
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
558 variable intended to be set by the user for customization---and
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
559 @code{nil} otherwise. (Variables other than user options exist for the
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
560 internal purposes of Lisp programs, and users need not know about them.)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
561
27528
5b4130fa5ab6 keywordp, user-variable-p change.
Dave Love <fx@gnu.org>
parents: 27390
diff changeset
562 User option variables are distinguished from other variables either
5b4130fa5ab6 keywordp, user-variable-p change.
Dave Love <fx@gnu.org>
parents: 27390
diff changeset
563 though being declared using @code{defcustom}@footnote{They may also be
5b4130fa5ab6 keywordp, user-variable-p change.
Dave Love <fx@gnu.org>
parents: 27390
diff changeset
564 declared equivalently in @file{cus-start.el}.} or by the first character
5b4130fa5ab6 keywordp, user-variable-p change.
Dave Love <fx@gnu.org>
parents: 27390
diff changeset
565 of their @code{variable-documentation} property. If the property exists
5b4130fa5ab6 keywordp, user-variable-p change.
Dave Love <fx@gnu.org>
parents: 27390
diff changeset
566 and is a string, and its first character is @samp{*}, then the variable
5b4130fa5ab6 keywordp, user-variable-p change.
Dave Love <fx@gnu.org>
parents: 27390
diff changeset
567 is a user option.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
568 @end defun
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
569
12820
4d6c32d4f782 Add index and xref to variable-interactive.
Richard M. Stallman <rms@gnu.org>
parents: 12802
diff changeset
570 @kindex variable-interactive
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
571 If a user option variable has a @code{variable-interactive} property,
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
572 the @code{set-variable} command uses that value to control reading the
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
573 new value for the variable. The property's value is used as if it were
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
574 specified in @code{interactive} (@pxref{Using Interactive}). However,
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
575 this feature is largely obsoleted by @code{defcustom}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
576 (@pxref{Customization}).
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
577
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7194
diff changeset
578 @strong{Warning:} If the @code{defconst} and @code{defvar} special
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
579 forms are used while the variable has a local binding, they set the
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
580 local binding's value; the global binding is not changed. This is not
27389
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
581 what you usually want. To prevent it, use these special forms at top
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
582 level in a file, where normally no local binding is in effect, and make
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
583 sure to load the file before making a local binding for the variable.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
584
12802
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
585 @node Tips for Defining
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
586 @section Tips for Defining Variables Robustly
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
587
27389
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
588 When you define a variable whose value is a function, or a list of
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
589 functions, use a name that ends in @samp{-function} or
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
590 @samp{-functions}, respectively.
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
591
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
592 There are several other variable name conventions;
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
593 here is a complete list:
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
594
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
595 @table @samp
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
596 @item @dots{}-hook
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
597 The variable is a normal hook (@pxref{Hooks}).
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
598
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
599 @item @dots{}-function
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
600 The value is a function.
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
601
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
602 @item @dots{}-functions
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
603 The value is a list of functions.
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
604
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
605 @item @dots{}-form
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
606 The value is a form (an expression).
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
607
37583
313d4c5de5ca Two minor fixes.
Richard M. Stallman <rms@gnu.org>
parents: 32596
diff changeset
608 @item @dots{}-forms
27389
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
609 The value is a list of forms (expressions).
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
610
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
611 @item @dots{}-predicate
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
612 The value is a predicate---a function of one argument that returns
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
613 non-@code{nil} for ``good'' arguments and @code{nil} for ``bad''
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
614 arguments.
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
615
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
616 @item @dots{}-flag
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
617 The value is significant only as to whether it is @code{nil} or not.
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
618
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
619 @item @dots{}-program
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
620 The value is a program name.
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
621
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
622 @item @dots{}-command
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
623 The value is a whole shell command.
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
624
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
625 @item @samp{}-switches
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
626 The value specifies options for a command.
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
627 @end table
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
628
37583
313d4c5de5ca Two minor fixes.
Richard M. Stallman <rms@gnu.org>
parents: 32596
diff changeset
629 When you define a variable, always consider whether you should mark
27389
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
630 it as ``risky''; see @ref{File Local Variables}.
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
631
12802
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
632 When defining and initializing a variable that holds a complicated
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
633 value (such as a keymap with bindings in it), it's best to put the
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
634 entire computation of the value into the @code{defvar}, like this:
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
635
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
636 @example
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
637 (defvar my-mode-map
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
638 (let ((map (make-sparse-keymap)))
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
639 (define-key map "\C-c\C-a" 'my-command)
12802
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
640 @dots{}
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
641 map)
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
642 @var{docstring})
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
643 @end example
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
644
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
645 @noindent
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
646 This method has several benefits. First, if the user quits while
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
647 loading the file, the variable is either still uninitialized or
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
648 initialized properly, never in-between. If it is still uninitialized,
12802
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
649 reloading the file will initialize it properly. Second, reloading the
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
650 file once the variable is initialized will not alter it; that is
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
651 important if the user has run hooks to alter part of the contents (such
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
652 as, to rebind keys). Third, evaluating the @code{defvar} form with
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
653 @kbd{C-M-x} @emph{will} reinitialize the map completely.
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
654
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
655 Putting so much code in the @code{defvar} form has one disadvantage:
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
656 it puts the documentation string far away from the line which names the
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
657 variable. Here's a safe way to avoid that:
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
658
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
659 @example
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
660 (defvar my-mode-map nil
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
661 @var{docstring})
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
662 (unless my-mode-map
12802
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
663 (let ((map (make-sparse-keymap)))
30502
0dca3aa6405a *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 27808
diff changeset
664 (define-key map "\C-c\C-a" 'my-command)
12802
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
665 @dots{}
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
666 (setq my-mode-map map)))
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
667 @end example
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
668
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
669 @noindent
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
670 This has all the same advantages as putting the initialization inside
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
671 the @code{defvar}, except that you must type @kbd{C-M-x} twice, once on
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
672 each form, if you do want to reinitialize the variable.
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
673
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
674 But be careful not to write the code like this:
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
675
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
676 @example
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
677 (defvar my-mode-map nil
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
678 @var{docstring})
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
679 (unless my-mode-map
12802
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
680 (setq my-mode-map (make-sparse-keymap))
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
681 (define-key my-mode-map "\C-c\C-a" 'my-command)
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
682 @dots{})
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
683 @end example
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
684
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
685 @noindent
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
686 This code sets the variable, then alters it, but it does so in more than
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
687 one step. If the user quits just after the @code{setq}, that leaves the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
688 variable neither correctly initialized nor void nor @code{nil}. Once
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
689 that happens, reloading the file will not initialize the variable; it
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
690 will remain incomplete.
12802
74615e68b2cd New node, Tips for Defining.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
691
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
692 @node Accessing Variables
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
693 @section Accessing Variable Values
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
694
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
695 The usual way to reference a variable is to write the symbol which
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
696 names it (@pxref{Symbol Forms}). This requires you to specify the
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
697 variable name when you write the program. Usually that is exactly what
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
698 you want to do. Occasionally you need to choose at run time which
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
699 variable to reference; then you can use @code{symbol-value}.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
700
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
701 @defun symbol-value symbol
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
702 This function returns the value of @var{symbol}. This is the value in
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
703 the innermost local binding of the symbol, or its global value if it
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
704 has no local bindings.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
705
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
706 @example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
707 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
708 (setq abracadabra 5)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
709 @result{} 5
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
710 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
711 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
712 (setq foo 9)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
713 @result{} 9
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
714 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
715
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
716 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
717 ;; @r{Here the symbol @code{abracadabra}}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
718 ;; @r{is the symbol whose value is examined.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
719 (let ((abracadabra 'foo))
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
720 (symbol-value 'abracadabra))
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
721 @result{} foo
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
722 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
723
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
724 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
725 ;; @r{Here the value of @code{abracadabra},}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
726 ;; @r{which is @code{foo},}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
727 ;; @r{is the symbol whose value is examined.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
728 (let ((abracadabra 'foo))
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
729 (symbol-value abracadabra))
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
730 @result{} 9
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
731 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
732
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
733 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
734 (symbol-value 'abracadabra)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
735 @result{} 5
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
736 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
737 @end example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
738
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
739 A @code{void-variable} error is signaled if the current binding of
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
740 @var{symbol} is void.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
741 @end defun
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
742
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
743 @node Setting Variables
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
744 @section How to Alter a Variable Value
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
745
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
746 The usual way to change the value of a variable is with the special
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
747 form @code{setq}. When you need to compute the choice of variable at
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
748 run time, use the function @code{set}.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
749
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
750 @defspec setq [symbol form]@dots{}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
751 This special form is the most common method of changing a variable's
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
752 value. Each @var{symbol} is given a new value, which is the result of
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
753 evaluating the corresponding @var{form}. The most-local existing
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
754 binding of the symbol is changed.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
755
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
756 @code{setq} does not evaluate @var{symbol}; it sets the symbol that you
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
757 write. We say that this argument is @dfn{automatically quoted}. The
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
758 @samp{q} in @code{setq} stands for ``quoted.''
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
759
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
760 The value of the @code{setq} form is the value of the last @var{form}.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
761
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
762 @example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
763 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
764 (setq x (1+ 2))
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
765 @result{} 3
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
766 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
767 x ; @r{@code{x} now has a global value.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
768 @result{} 3
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
769 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
770 (let ((x 5))
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
771 (setq x 6) ; @r{The local binding of @code{x} is set.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
772 x)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
773 @result{} 6
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
774 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
775 x ; @r{The global value is unchanged.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
776 @result{} 3
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
777 @end example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
778
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
779 Note that the first @var{form} is evaluated, then the first
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
780 @var{symbol} is set, then the second @var{form} is evaluated, then the
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
781 second @var{symbol} is set, and so on:
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
782
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
783 @example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
784 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
785 (setq x 10 ; @r{Notice that @code{x} is set before}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
786 y (1+ x)) ; @r{the value of @code{y} is computed.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
787 @result{} 11
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
788 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
789 @end example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
790 @end defspec
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
791
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
792 @defun set symbol value
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
793 This function sets @var{symbol}'s value to @var{value}, then returns
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
794 @var{value}. Since @code{set} is a function, the expression written for
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
795 @var{symbol} is evaluated to obtain the symbol to set.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
796
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
797 The most-local existing binding of the variable is the binding that is
7194
3112fb627aa0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6510
diff changeset
798 set; shadowed bindings are not affected.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
799
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
800 @example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
801 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
802 (set one 1)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
803 @error{} Symbol's value as variable is void: one
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
804 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
805 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
806 (set 'one 1)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
807 @result{} 1
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
808 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
809 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
810 (set 'two 'one)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
811 @result{} one
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
812 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
813 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
814 (set two 2) ; @r{@code{two} evaluates to symbol @code{one}.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
815 @result{} 2
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
816 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
817 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
818 one ; @r{So it is @code{one} that was set.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
819 @result{} 2
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
820 (let ((one 1)) ; @r{This binding of @code{one} is set,}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
821 (set 'one 3) ; @r{not the global value.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
822 one)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
823 @result{} 3
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
824 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
825 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
826 one
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
827 @result{} 2
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
828 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
829 @end example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
830
7194
3112fb627aa0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6510
diff changeset
831 If @var{symbol} is not actually a symbol, a @code{wrong-type-argument}
3112fb627aa0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6510
diff changeset
832 error is signaled.
3112fb627aa0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6510
diff changeset
833
3112fb627aa0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6510
diff changeset
834 @example
3112fb627aa0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6510
diff changeset
835 (set '(x y) 'z)
3112fb627aa0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6510
diff changeset
836 @error{} Wrong type argument: symbolp, (x y)
3112fb627aa0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6510
diff changeset
837 @end example
3112fb627aa0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6510
diff changeset
838
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
839 Logically speaking, @code{set} is a more fundamental primitive than
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
840 @code{setq}. Any use of @code{setq} can be trivially rewritten to use
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
841 @code{set}; @code{setq} could even be defined as a macro, given the
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
842 availability of @code{set}. However, @code{set} itself is rarely used;
7194
3112fb627aa0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6510
diff changeset
843 beginners hardly need to know about it. It is useful only for choosing
3112fb627aa0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6510
diff changeset
844 at run time which variable to set. For example, the command
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
845 @code{set-variable}, which reads a variable name from the user and then
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
846 sets the variable, needs to use @code{set}.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
847
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
848 @cindex CL note---@code{set} local
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
849 @quotation
7194
3112fb627aa0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6510
diff changeset
850 @b{Common Lisp note:} In Common Lisp, @code{set} always changes the
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
851 symbol's ``special'' or dynamic value, ignoring any lexical bindings.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
852 In Emacs Lisp, all variables and all bindings are dynamic, so @code{set}
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
853 always affects the most local existing binding.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
854 @end quotation
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
855 @end defun
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
856
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
857 One other function for setting a variable is designed to add
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
858 an element to a list if it is not already present in the list.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
859
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
860 @defun add-to-list symbol element
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
861 This function sets the variable @var{symbol} by consing @var{element}
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
862 onto the old value, if @var{element} is not already a member of that
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
863 value. It returns the resulting list, whether updated or not. The
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
864 value of @var{symbol} had better be a list already before the call.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
865
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
866 The argument @var{symbol} is not implicitly quoted; @code{add-to-list}
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
867 is an ordinary function, like @code{set} and unlike @code{setq}. Quote
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
868 the argument yourself if that is what you want.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
869 @end defun
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
870
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
871 Here's a scenario showing how to use @code{add-to-list}:
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
872
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
873 @example
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
874 (setq foo '(a b))
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
875 @result{} (a b)
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
876
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
877 (add-to-list 'foo 'c) ;; @r{Add @code{c}.}
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
878 @result{} (c a b)
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
879
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
880 (add-to-list 'foo 'b) ;; @r{No effect.}
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
881 @result{} (c a b)
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
882
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
883 foo ;; @r{@code{foo} was changed.}
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
884 @result{} (c a b)
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
885 @end example
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
886
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
887 An equivalent expression for @code{(add-to-list '@var{var}
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
888 @var{value})} is this:
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
889
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
890 @example
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
891 (or (member @var{value} @var{var})
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
892 (setq @var{var} (cons @var{value} @var{var})))
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
893 @end example
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
894
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
895 @node Variable Scoping
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
896 @section Scoping Rules for Variable Bindings
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
897
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
898 A given symbol @code{foo} can have several local variable bindings,
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
899 established at different places in the Lisp program, as well as a global
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
900 binding. The most recently established binding takes precedence over
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
901 the others.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
902
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
903 @cindex scope
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
904 @cindex extent
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
905 @cindex dynamic scoping
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
906 Local bindings in Emacs Lisp have @dfn{indefinite scope} and
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
907 @dfn{dynamic extent}. @dfn{Scope} refers to @emph{where} textually in
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
908 the source code the binding can be accessed. ``Indefinite scope'' means
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
909 that any part of the program can potentially access the variable
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
910 binding. @dfn{Extent} refers to @emph{when}, as the program is
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
911 executing, the binding exists. ``Dynamic extent'' means that the binding
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
912 lasts as long as the activation of the construct that established it.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
913
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
914 The combination of dynamic extent and indefinite scope is called
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
915 @dfn{dynamic scoping}. By contrast, most programming languages use
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
916 @dfn{lexical scoping}, in which references to a local variable must be
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
917 located textually within the function or block that binds the variable.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
918
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
919 @cindex CL note---special variables
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
920 @quotation
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
921 @b{Common Lisp note:} Variables declared ``special'' in Common Lisp are
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
922 dynamically scoped, like all variables in Emacs Lisp.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
923 @end quotation
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
924
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
925 @menu
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
926 * Scope:: Scope means where in the program a value is visible.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
927 Comparison with other languages.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
928 * Extent:: Extent means how long in time a value exists.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
929 * Impl of Scope:: Two ways to implement dynamic scoping.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
930 * Using Scoping:: How to use dynamic scoping carefully and avoid problems.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
931 @end menu
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
932
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
933 @node Scope
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
934 @subsection Scope
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
935
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
936 Emacs Lisp uses @dfn{indefinite scope} for local variable bindings.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
937 This means that any function anywhere in the program text might access a
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
938 given binding of a variable. Consider the following function
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
939 definitions:
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
940
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
941 @example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
942 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
943 (defun binder (x) ; @r{@code{x} is bound in @code{binder}.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
944 (foo 5)) ; @r{@code{foo} is some other function.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
945 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
946
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
947 @group
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
948 (defun user () ; @r{@code{x} is used ``free'' in @code{user}.}
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
949 (list x))
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
950 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
951 @end example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
952
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
953 In a lexically scoped language, the binding of @code{x} in
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
954 @code{binder} would never be accessible in @code{user}, because
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
955 @code{user} is not textually contained within the function
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
956 @code{binder}. However, in dynamically-scoped Emacs Lisp, @code{user}
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
957 may or may not refer to the binding of @code{x} established in
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
958 @code{binder}, depending on the circumstances:
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
959
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
960 @itemize @bullet
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
961 @item
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
962 If we call @code{user} directly without calling @code{binder} at all,
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
963 then whatever binding of @code{x} is found, it cannot come from
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
964 @code{binder}.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
965
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
966 @item
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
967 If we define @code{foo} as follows and then call @code{binder}, then the
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
968 binding made in @code{binder} will be seen in @code{user}:
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
969
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
970 @example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
971 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
972 (defun foo (lose)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
973 (user))
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
974 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
975 @end example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
976
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
977 @item
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
978 However, if we define @code{foo} as follows and then call @code{binder},
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
979 then the binding made in @code{binder} @emph{will not} be seen in
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
980 @code{user}:
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
981
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
982 @example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
983 (defun foo (x)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
984 (user))
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
985 @end example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
986
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
987 @noindent
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
988 Here, when @code{foo} is called by @code{binder}, it binds @code{x}.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
989 (The binding in @code{foo} is said to @dfn{shadow} the one made in
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
990 @code{binder}.) Therefore, @code{user} will access the @code{x} bound
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
991 by @code{foo} instead of the one bound by @code{binder}.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
992 @end itemize
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
993
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
994 Emacs Lisp uses dynamic scoping because simple implementations of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
995 lexical scoping are slow. In addition, every Lisp system needs to offer
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
996 dynamic scoping at least as an option; if lexical scoping is the norm,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
997 there must be a way to specify dynamic scoping instead for a particular
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
998 variable. It might not be a bad thing for Emacs to offer both, but
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
999 implementing it with dynamic scoping only was much easier.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1000
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1001 @node Extent
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1002 @subsection Extent
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1003
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1004 @dfn{Extent} refers to the time during program execution that a
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1005 variable name is valid. In Emacs Lisp, a variable is valid only while
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1006 the form that bound it is executing. This is called @dfn{dynamic
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1007 extent}. ``Local'' or ``automatic'' variables in most languages,
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1008 including C and Pascal, have dynamic extent.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1009
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1010 One alternative to dynamic extent is @dfn{indefinite extent}. This
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1011 means that a variable binding can live on past the exit from the form
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1012 that made the binding. Common Lisp and Scheme, for example, support
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1013 this, but Emacs Lisp does not.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1014
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1015 To illustrate this, the function below, @code{make-add}, returns a
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1016 function that purports to add @var{n} to its own argument @var{m}. This
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1017 would work in Common Lisp, but it does not do the job in Emacs Lisp,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1018 because after the call to @code{make-add} exits, the variable @code{n}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1019 is no longer bound to the actual argument 2.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1020
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1021 @example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1022 (defun make-add (n)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1023 (function (lambda (m) (+ n m)))) ; @r{Return a function.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1024 @result{} make-add
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1025 (fset 'add2 (make-add 2)) ; @r{Define function @code{add2}}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1026 ; @r{with @code{(make-add 2)}.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1027 @result{} (lambda (m) (+ n m))
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1028 (add2 4) ; @r{Try to add 2 to 4.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1029 @error{} Symbol's value as variable is void: n
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1030 @end example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1031
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1032 @cindex closures not available
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1033 Some Lisp dialects have ``closures'', objects that are like functions
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1034 but record additional variable bindings. Emacs Lisp does not have
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1035 closures.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1036
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1037 @node Impl of Scope
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1038 @subsection Implementation of Dynamic Scoping
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1039 @cindex deep binding
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1040
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1041 A simple sample implementation (which is not how Emacs Lisp actually
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1042 works) may help you understand dynamic binding. This technique is
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1043 called @dfn{deep binding} and was used in early Lisp systems.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1044
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1045 Suppose there is a stack of bindings, which are variable-value pairs.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1046 At entry to a function or to a @code{let} form, we can push bindings
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1047 onto the stack for the arguments or local variables created there. We
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1048 can pop those bindings from the stack at exit from the binding
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1049 construct.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1050
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1051 We can find the value of a variable by searching the stack from top to
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1052 bottom for a binding for that variable; the value from that binding is
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1053 the value of the variable. To set the variable, we search for the
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1054 current binding, then store the new value into that binding.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1055
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1056 As you can see, a function's bindings remain in effect as long as it
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1057 continues execution, even during its calls to other functions. That is
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1058 why we say the extent of the binding is dynamic. And any other function
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1059 can refer to the bindings, if it uses the same variables while the
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1060 bindings are in effect. That is why we say the scope is indefinite.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1061
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1062 @cindex shallow binding
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1063 The actual implementation of variable scoping in GNU Emacs Lisp uses a
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1064 technique called @dfn{shallow binding}. Each variable has a standard
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1065 place in which its current value is always found---the value cell of the
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1066 symbol.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1067
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1068 In shallow binding, setting the variable works by storing a value in
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1069 the value cell. Creating a new binding works by pushing the old value
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1070 (belonging to a previous binding) onto a stack, and storing the new
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1071 local value in the value cell. Eliminating a binding works by popping
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1072 the old value off the stack, into the value cell.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1073
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1074 We use shallow binding because it has the same results as deep
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1075 binding, but runs faster, since there is never a need to search for a
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1076 binding.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1077
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1078 @node Using Scoping
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1079 @subsection Proper Use of Dynamic Scoping
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1080
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1081 Binding a variable in one function and using it in another is a
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1082 powerful technique, but if used without restraint, it can make programs
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1083 hard to understand. There are two clean ways to use this technique:
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1084
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1085 @itemize @bullet
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1086 @item
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1087 Use or bind the variable only in a few related functions, written close
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1088 together in one file. Such a variable is used for communication within
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1089 one program.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1090
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1091 You should write comments to inform other programmers that they can see
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1092 all uses of the variable before them, and to advise them not to add uses
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1093 elsewhere.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1094
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1095 @item
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1096 Give the variable a well-defined, documented meaning, and make all
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1097 appropriate functions refer to it (but not bind it or set it) wherever
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1098 that meaning is relevant. For example, the variable
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1099 @code{case-fold-search} is defined as ``non-@code{nil} means ignore case
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1100 when searching''; various search and replace functions refer to it
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1101 directly or through their subroutines, but do not bind or set it.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1102
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1103 Then you can bind the variable in other programs, knowing reliably what
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1104 the effect will be.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1105 @end itemize
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1106
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1107 In either case, you should define the variable with @code{defvar}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1108 This helps other people understand your program by telling them to look
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1109 for inter-function usage. It also avoids a warning from the byte
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1110 compiler. Choose the variable's name to avoid name conflicts---don't
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1111 use short names like @code{x}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1112
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1113 @node Buffer-Local Variables
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1114 @section Buffer-Local Variables
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1115 @cindex variables, buffer-local
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1116 @cindex buffer-local variables
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1117
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1118 Global and local variable bindings are found in most programming
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
1119 languages in one form or another. Emacs, however, also supports additional,
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1120 unusual kinds of variable binding: @dfn{buffer-local} bindings, which
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
1121 apply only in one buffer, and @dfn{frame-local} bindings, which apply only in
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1122 one frame. Having different values for a variable in different buffers
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1123 and/or frames is an important customization method.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1124
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1125 This section describes buffer-local bindings; for frame-local
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1126 bindings, see the following section, @ref{Frame-Local Variables}. (A few
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1127 variables have bindings that are local to each terminal; see
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1128 @ref{Multiple Displays}.)
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1129
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1130 @menu
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1131 * Intro to Buffer-Local:: Introduction and concepts.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1132 * Creating Buffer-Local:: Creating and destroying buffer-local bindings.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1133 * Default Value:: The default value is seen in buffers
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1134 that don't have their own buffer-local values.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1135 @end menu
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1136
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1137 @node Intro to Buffer-Local
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1138 @subsection Introduction to Buffer-Local Variables
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1139
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1140 A buffer-local variable has a buffer-local binding associated with a
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1141 particular buffer. The binding is in effect when that buffer is
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1142 current; otherwise, it is not in effect. If you set the variable while
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1143 a buffer-local binding is in effect, the new value goes in that binding,
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1144 so its other bindings are unchanged. This means that the change is
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1145 visible only in the buffer where you made it.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1146
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1147 The variable's ordinary binding, which is not associated with any
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1148 specific buffer, is called the @dfn{default binding}. In most cases,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1149 this is the global binding.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1150
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1151 A variable can have buffer-local bindings in some buffers but not in
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1152 other buffers. The default binding is shared by all the buffers that
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1153 don't have their own bindings for the variable. (This includes all
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
1154 newly-created buffers.) If you set the variable in a buffer that does
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1155 not have a buffer-local binding for it, this sets the default binding
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1156 (assuming there are no frame-local bindings to complicate the matter),
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1157 so the new value is visible in all the buffers that see the default
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1158 binding.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1159
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1160 The most common use of buffer-local bindings is for major modes to change
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1161 variables that control the behavior of commands. For example, C mode and
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1162 Lisp mode both set the variable @code{paragraph-start} to specify that only
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1163 blank lines separate paragraphs. They do this by making the variable
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1164 buffer-local in the buffer that is being put into C mode or Lisp mode, and
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1165 then setting it to the new value for that mode. @xref{Major Modes}.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1166
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1167 The usual way to make a buffer-local binding is with
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1168 @code{make-local-variable}, which is what major mode commands typically
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1169 use. This affects just the current buffer; all other buffers (including
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1170 those yet to be created) will continue to share the default value unless
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1171 they are explicitly given their own buffer-local bindings.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1172
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1173 @cindex automatically buffer-local
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1174 A more powerful operation is to mark the variable as
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1175 @dfn{automatically buffer-local} by calling
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1176 @code{make-variable-buffer-local}. You can think of this as making the
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1177 variable local in all buffers, even those yet to be created. More
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1178 precisely, the effect is that setting the variable automatically makes
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1179 the variable local to the current buffer if it is not already so. All
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1180 buffers start out by sharing the default value of the variable as usual,
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1181 but setting the variable creates a buffer-local binding for the current
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1182 buffer. The new value is stored in the buffer-local binding, leaving
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1183 the default binding untouched. This means that the default value cannot
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1184 be changed with @code{setq} in any buffer; the only way to change it is
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1185 with @code{setq-default}.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1186
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1187 @strong{Warning:} When a variable has buffer-local values in one or
45276
51bf5310b422 (Intro to Buffer-Local): Updated warning and
Kim F. Storm <storm@cua.dk>
parents: 43264
diff changeset
1188 more buffers, binding the variable with @code{let} and changing to a
51bf5310b422 (Intro to Buffer-Local): Updated warning and
Kim F. Storm <storm@cua.dk>
parents: 43264
diff changeset
1189 different current buffer in which a different binding is in
51bf5310b422 (Intro to Buffer-Local): Updated warning and
Kim F. Storm <storm@cua.dk>
parents: 43264
diff changeset
1190 effect, and then exiting the @code{let}, the variable may not be
51bf5310b422 (Intro to Buffer-Local): Updated warning and
Kim F. Storm <storm@cua.dk>
parents: 43264
diff changeset
1191 restored to the value it had before the @code{let}.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1192
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1193 To preserve your sanity, avoid using a variable in that way. If you
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1194 use @code{save-excursion} around each piece of code that changes to a
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1195 different current buffer, you will not have this problem
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1196 (@pxref{Excursions}). Here is an example of what to avoid:
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1197
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1198 @example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1199 @group
45276
51bf5310b422 (Intro to Buffer-Local): Updated warning and
Kim F. Storm <storm@cua.dk>
parents: 43264
diff changeset
1200 (setq foo 'g)
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1201 (set-buffer "a")
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1202 (make-local-variable 'foo)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1203 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1204 (setq foo 'a)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1205 (let ((foo 'temp))
45276
51bf5310b422 (Intro to Buffer-Local): Updated warning and
Kim F. Storm <storm@cua.dk>
parents: 43264
diff changeset
1206 ;; foo @result{} 'temp ; @r{let binding in buffer @samp{a}}
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1207 (set-buffer "b")
45276
51bf5310b422 (Intro to Buffer-Local): Updated warning and
Kim F. Storm <storm@cua.dk>
parents: 43264
diff changeset
1208 ;; foo @result{} 'g ; @r{the global value since foo is not local in @samp{b}}
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1209 @var{body}@dots{})
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1210 @group
45276
51bf5310b422 (Intro to Buffer-Local): Updated warning and
Kim F. Storm <storm@cua.dk>
parents: 43264
diff changeset
1211 foo @result{} 'a ; @r{we are still in buffer @samp{b}, but exiting the let}
51bf5310b422 (Intro to Buffer-Local): Updated warning and
Kim F. Storm <storm@cua.dk>
parents: 43264
diff changeset
1212 ; @r{restored the local value in buffer @samp{a}}
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1213 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1214 @group
45276
51bf5310b422 (Intro to Buffer-Local): Updated warning and
Kim F. Storm <storm@cua.dk>
parents: 43264
diff changeset
1215 (set-buffer "a") ; @r{This can be seen here:}
51bf5310b422 (Intro to Buffer-Local): Updated warning and
Kim F. Storm <storm@cua.dk>
parents: 43264
diff changeset
1216 foo @result{} 'a ; @r{we are back to the local value in buffer @samp{a}}
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1217 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1218 @end example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1219
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1220 @noindent
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1221 But @code{save-excursion} as shown here avoids the problem:
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1222
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1223 @example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1224 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1225 (let ((foo 'temp))
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1226 (save-excursion
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1227 (set-buffer "b")
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1228 @var{body}@dots{}))
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1229 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1230 @end example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1231
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1232 Note that references to @code{foo} in @var{body} access the
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1233 buffer-local binding of buffer @samp{b}.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1234
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1235 When a file specifies local variable values, these become buffer-local
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1236 values when you visit the file. @xref{File Variables,,, emacs, The
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1237 GNU Emacs Manual}.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1238
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1239 @node Creating Buffer-Local
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1240 @subsection Creating and Deleting Buffer-Local Bindings
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1241
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1242 @deffn Command make-local-variable variable
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1243 This function creates a buffer-local binding in the current buffer for
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1244 @var{variable} (a symbol). Other buffers are not affected. The value
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1245 returned is @var{variable}.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1246
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1247 @c Emacs 19 feature
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1248 The buffer-local value of @var{variable} starts out as the same value
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1249 @var{variable} previously had. If @var{variable} was void, it remains
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1250 void.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1251
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1252 @example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1253 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1254 ;; @r{In buffer @samp{b1}:}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1255 (setq foo 5) ; @r{Affects all buffers.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1256 @result{} 5
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1257 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1258 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1259 (make-local-variable 'foo) ; @r{Now it is local in @samp{b1}.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1260 @result{} foo
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1261 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1262 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1263 foo ; @r{That did not change}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1264 @result{} 5 ; @r{the value.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1265 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1266 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1267 (setq foo 6) ; @r{Change the value}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1268 @result{} 6 ; @r{in @samp{b1}.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1269 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1270 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1271 foo
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1272 @result{} 6
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1273 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1274
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1275 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1276 ;; @r{In buffer @samp{b2}, the value hasn't changed.}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1277 (save-excursion
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1278 (set-buffer "b2")
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1279 foo)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1280 @result{} 5
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1281 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1282 @end example
8214
a13093894b9a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1283
a13093894b9a entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1284 Making a variable buffer-local within a @code{let}-binding for that
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1285 variable does not work reliably, unless the buffer in which you do this
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1286 is not current either on entry to or exit from the @code{let}. This is
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1287 because @code{let} does not distinguish between different kinds of
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1288 bindings; it knows only which variable the binding was made for.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 8214
diff changeset
1289
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1290 If the variable is terminal-local, this function signals an error. Such
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1291 variables cannot have buffer-local bindings as well. @xref{Multiple
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1292 Displays}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1293
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
1294 @strong{Note:} Do not use @code{make-local-variable} for a hook
43264
91a36592ab22 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 40724
diff changeset
1295 variable. The hook variables are automatically made buffer-local
91a36592ab22 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 40724
diff changeset
1296 as needed if you use the @var{local} argument to @code{add-hook} or
91a36592ab22 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 40724
diff changeset
1297 @code{remove-hook}.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1298 @end deffn
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1299
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1300 @deffn Command make-variable-buffer-local variable
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1301 This function marks @var{variable} (a symbol) automatically
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1302 buffer-local, so that any subsequent attempt to set it will make it
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1303 local to the current buffer at the time.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1304
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1305 A peculiar wrinkle of this feature is that binding the variable (with
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1306 @code{let} or other binding constructs) does not create a buffer-local
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1307 binding for it. Only setting the variable (with @code{set} or
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1308 @code{setq}) does so.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1309
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1310 The value returned is @var{variable}.
13166
c61ffdb6d9df Explain when to use make-variable-buffer-local.
Richard M. Stallman <rms@gnu.org>
parents: 12821
diff changeset
1311
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1312 @strong{Warning:} Don't assume that you should use
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1313 @code{make-variable-buffer-local} for user-option variables, simply
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1314 because users @emph{might} want to customize them differently in
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1315 different buffers. Users can make any variable local, when they wish
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1316 to. It is better to leave the choice to them.
13166
c61ffdb6d9df Explain when to use make-variable-buffer-local.
Richard M. Stallman <rms@gnu.org>
parents: 12821
diff changeset
1317
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1318 The time to use @code{make-variable-buffer-local} is when it is crucial
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1319 that no two buffers ever share the same binding. For example, when a
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1320 variable is used for internal purposes in a Lisp program which depends
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1321 on having separate values in separate buffers, then using
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1322 @code{make-variable-buffer-local} can be the best solution.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1323 @end deffn
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1324
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1325 @defun local-variable-p variable &optional buffer
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1326 This returns @code{t} if @var{variable} is buffer-local in buffer
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1327 @var{buffer} (which defaults to the current buffer); otherwise,
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1328 @code{nil}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1329 @end defun
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1330
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1331 @defun buffer-local-variables &optional buffer
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1332 This function returns a list describing the buffer-local variables in
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1333 buffer @var{buffer}. (If @var{buffer} is omitted, the current buffer is
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1334 used.) It returns an association list (@pxref{Association Lists}) in
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1335 which each element contains one buffer-local variable and its value.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1336 However, when a variable's buffer-local binding in @var{buffer} is void,
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1337 then the variable appears directly in the resulting list.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1338
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1339 @example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1340 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1341 (make-local-variable 'foobar)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1342 (makunbound 'foobar)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1343 (make-local-variable 'bind-me)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1344 (setq bind-me 69)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1345 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1346 (setq lcl (buffer-local-variables))
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1347 ;; @r{First, built-in variables local in all buffers:}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1348 @result{} ((mark-active . nil)
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1349 (buffer-undo-list . nil)
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1350 (mode-name . "Fundamental")
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1351 @dots{}
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1352 @group
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1353 ;; @r{Next, non-built-in buffer-local variables.}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1354 ;; @r{This one is buffer-local and void:}
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1355 foobar
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1356 ;; @r{This one is buffer-local and nonvoid:}
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1357 (bind-me . 69))
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1358 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1359 @end example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1360
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1361 Note that storing new values into the @sc{cdr}s of cons cells in this
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1362 list does @emph{not} change the buffer-local values of the variables.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1363 @end defun
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1364
40724
867ed25daefa Document buffer-local-value.
Richard M. Stallman <rms@gnu.org>
parents: 39628
diff changeset
1365 @defun buffer-local-value variable buffer
867ed25daefa Document buffer-local-value.
Richard M. Stallman <rms@gnu.org>
parents: 39628
diff changeset
1366 This function returns the buffer-local binding of @var{variable} (a
867ed25daefa Document buffer-local-value.
Richard M. Stallman <rms@gnu.org>
parents: 39628
diff changeset
1367 symbol) in buffer @var{buffer}. If @var{variable} does not have a
867ed25daefa Document buffer-local-value.
Richard M. Stallman <rms@gnu.org>
parents: 39628
diff changeset
1368 buffer-local binding in buffer @var{buffer}, it returns the default
867ed25daefa Document buffer-local-value.
Richard M. Stallman <rms@gnu.org>
parents: 39628
diff changeset
1369 value (@pxref{Default Value}) of @var{variable} instead.
867ed25daefa Document buffer-local-value.
Richard M. Stallman <rms@gnu.org>
parents: 39628
diff changeset
1370 @end defun
867ed25daefa Document buffer-local-value.
Richard M. Stallman <rms@gnu.org>
parents: 39628
diff changeset
1371
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1372 @deffn Command kill-local-variable variable
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1373 This function deletes the buffer-local binding (if any) for
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1374 @var{variable} (a symbol) in the current buffer. As a result, the
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1375 default binding of @var{variable} becomes visible in this buffer. This
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1376 typically results in a change in the value of @var{variable}, since the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1377 default value is usually different from the buffer-local value just
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1378 eliminated.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1379
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1380 If you kill the buffer-local binding of a variable that automatically
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1381 becomes buffer-local when set, this makes the default value visible in
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1382 the current buffer. However, if you set the variable again, that will
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1383 once again create a buffer-local binding for it.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1384
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1385 @code{kill-local-variable} returns @var{variable}.
7194
3112fb627aa0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6510
diff changeset
1386
3112fb627aa0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6510
diff changeset
1387 This function is a command because it is sometimes useful to kill one
3112fb627aa0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6510
diff changeset
1388 buffer-local variable interactively, just as it is useful to create
3112fb627aa0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6510
diff changeset
1389 buffer-local variables interactively.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1390 @end deffn
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1391
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1392 @defun kill-all-local-variables
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1393 This function eliminates all the buffer-local variable bindings of the
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1394 current buffer except for variables marked as ``permanent''. As a
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1395 result, the buffer will see the default values of most variables.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1396
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1397 This function also resets certain other information pertaining to the
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1398 buffer: it sets the local keymap to @code{nil}, the syntax table to the
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1399 value of @code{(standard-syntax-table)}, the case table to
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1400 @code{(standard-case-table)}, and the abbrev table to the value of
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1401 @code{fundamental-mode-abbrev-table}.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1402
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1403 The very first thing this function does is run the normal hook
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1404 @code{change-major-mode-hook} (see below).
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1405
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1406 Every major mode command begins by calling this function, which has the
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1407 effect of switching to Fundamental mode and erasing most of the effects
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1408 of the previous major mode. To ensure that this does its job, the
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1409 variables that major modes set should not be marked permanent.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1410
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1411 @code{kill-all-local-variables} returns @code{nil}.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1412 @end defun
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1413
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1414 @defvar change-major-mode-hook
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1415 The function @code{kill-all-local-variables} runs this normal hook
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1416 before it does anything else. This gives major modes a way to arrange
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1417 for something special to be done if the user switches to a different
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1418 major mode. For best results, make this variable buffer-local, so that
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1419 it will disappear after doing its job and will not interfere with the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1420 subsequent major mode. @xref{Hooks}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1421 @end defvar
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1422
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1423 @c Emacs 19 feature
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1424 @cindex permanent local variable
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1425 A buffer-local variable is @dfn{permanent} if the variable name (a
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1426 symbol) has a @code{permanent-local} property that is non-@code{nil}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1427 Permanent locals are appropriate for data pertaining to where the file
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1428 came from or how to save it, rather than with how to edit the contents.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1429
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1430 @node Default Value
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1431 @subsection The Default Value of a Buffer-Local Variable
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1432 @cindex default value
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1433
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1434 The global value of a variable with buffer-local bindings is also
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1435 called the @dfn{default} value, because it is the value that is in
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1436 effect whenever neither the current buffer nor the selected frame has
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1437 its own binding for the variable.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1438
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1439 The functions @code{default-value} and @code{setq-default} access and
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1440 change a variable's default value regardless of whether the current
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1441 buffer has a buffer-local binding. For example, you could use
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1442 @code{setq-default} to change the default setting of
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1443 @code{paragraph-start} for most buffers; and this would work even when
7194
3112fb627aa0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6510
diff changeset
1444 you are in a C or Lisp mode buffer that has a buffer-local value for
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1445 this variable.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1446
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1447 @c Emacs 19 feature
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1448 The special forms @code{defvar} and @code{defconst} also set the
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1449 default value (if they set the variable at all), rather than any
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1450 buffer-local or frame-local value.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1451
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1452 @defun default-value symbol
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1453 This function returns @var{symbol}'s default value. This is the value
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1454 that is seen in buffers and frames that do not have their own values for
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1455 this variable. If @var{symbol} is not buffer-local, this is equivalent
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1456 to @code{symbol-value} (@pxref{Accessing Variables}).
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1457 @end defun
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1458
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1459 @c Emacs 19 feature
7194
3112fb627aa0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6510
diff changeset
1460 @defun default-boundp symbol
3112fb627aa0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6510
diff changeset
1461 The function @code{default-boundp} tells you whether @var{symbol}'s
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1462 default value is nonvoid. If @code{(default-boundp 'foo)} returns
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1463 @code{nil}, then @code{(default-value 'foo)} would get an error.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1464
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1465 @code{default-boundp} is to @code{default-value} as @code{boundp} is to
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1466 @code{symbol-value}.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1467 @end defun
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1468
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1469 @defspec setq-default [symbol form]@dots{}
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1470 This special form gives each @var{symbol} a new default value, which is
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1471 the result of evaluating the corresponding @var{form}. It does not
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1472 evaluate @var{symbol}, but does evaluate @var{form}. The value of the
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1473 @code{setq-default} form is the value of the last @var{form}.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1474
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1475 If a @var{symbol} is not buffer-local for the current buffer, and is not
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1476 marked automatically buffer-local, @code{setq-default} has the same
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1477 effect as @code{setq}. If @var{symbol} is buffer-local for the current
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1478 buffer, then this changes the value that other buffers will see (as long
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1479 as they don't have a buffer-local value), but not the value that the
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1480 current buffer sees.
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1481
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1482 @example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1483 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1484 ;; @r{In buffer @samp{foo}:}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1485 (make-local-variable 'buffer-local)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1486 @result{} buffer-local
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1487 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1488 @group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1489 (setq buffer-local 'value-in-foo)
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1490 @result{} value-in-foo
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1491 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1492 @group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1493 (setq-default buffer-local 'new-default)
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1494 @result{} new-default
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1495 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1496 @group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1497 buffer-local
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1498 @result{} value-in-foo
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1499 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1500 @group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1501 (default-value 'buffer-local)
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1502 @result{} new-default
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1503 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1504
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1505 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1506 ;; @r{In (the new) buffer @samp{bar}:}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1507 buffer-local
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1508 @result{} new-default
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1509 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1510 @group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1511 (default-value 'buffer-local)
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1512 @result{} new-default
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1513 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1514 @group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1515 (setq buffer-local 'another-default)
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1516 @result{} another-default
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1517 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1518 @group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1519 (default-value 'buffer-local)
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1520 @result{} another-default
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1521 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1522
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1523 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1524 ;; @r{Back in buffer @samp{foo}:}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1525 buffer-local
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1526 @result{} value-in-foo
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1527 (default-value 'buffer-local)
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1528 @result{} another-default
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1529 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1530 @end example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1531 @end defspec
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1532
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1533 @defun set-default symbol value
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1534 This function is like @code{setq-default}, except that @var{symbol} is
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 13166
diff changeset
1535 an ordinary evaluated argument.
6510
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1536
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1537 @example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1538 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1539 (set-default (car '(a b c)) 23)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1540 @result{} 23
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1541 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1542 @group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1543 (default-value 'a)
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1544 @result{} 23
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1545 @end group
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1546 @end example
e18202af3602 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1547 @end defun
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1548
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1549 @node Frame-Local Variables
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1550 @section Frame-Local Variables
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1551
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1552 Just as variables can have buffer-local bindings, they can also have
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1553 frame-local bindings. These bindings belong to one frame, and are in
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1554 effect when that frame is selected. Frame-local bindings are actually
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1555 frame parameters: you create a frame-local binding in a specific frame
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1556 by calling @code{modify-frame-parameters} and specifying the variable
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1557 name as the parameter name.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1558
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1559 To enable frame-local bindings for a certain variable, call the function
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1560 @code{make-variable-frame-local}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1561
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1562 @deffn Command make-variable-frame-local variable
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1563 Enable the use of frame-local bindings for @var{variable}. This does
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1564 not in itself create any frame-local bindings for the variable; however,
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1565 if some frame already has a value for @var{variable} as a frame
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1566 parameter, that value automatically becomes a frame-local binding.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1567
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1568 If the variable is terminal-local, this function signals an error,
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1569 because such variables cannot have frame-local bindings as well.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1570 @xref{Multiple Displays}. A few variables that are implemented
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1571 specially in Emacs can be (and usually are) buffer-local, but can never
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1572 be frame-local.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1573 @end deffn
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1574
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1575 Buffer-local bindings take precedence over frame-local bindings. Thus,
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1576 consider a variable @code{foo}: if the current buffer has a buffer-local
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1577 binding for @code{foo}, that binding is active; otherwise, if the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1578 selected frame has a frame-local binding for @code{foo}, that binding is
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1579 active; otherwise, the default binding of @code{foo} is active.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1580
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1581 Here is an example. First we prepare a few bindings for @code{foo}:
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1582
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1583 @example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1584 (setq f1 (selected-frame))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1585 (make-variable-frame-local 'foo)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1586
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1587 ;; @r{Make a buffer-local binding for @code{foo} in @samp{b1}.}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1588 (set-buffer (get-buffer-create "b1"))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1589 (make-local-variable 'foo)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1590 (setq foo '(b 1))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1591
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1592 ;; @r{Make a frame-local binding for @code{foo} in a new frame.}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1593 ;; @r{Store that frame in @code{f2}.}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1594 (setq f2 (make-frame))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1595 (modify-frame-parameters f2 '((foo . (f 2))))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1596 @end example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1597
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1598 Now we examine @code{foo} in various contexts. Whenever the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1599 buffer @samp{b1} is current, its buffer-local binding is in effect,
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1600 regardless of the selected frame:
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1601
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1602 @example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1603 (select-frame f1)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1604 (set-buffer (get-buffer-create "b1"))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1605 foo
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1606 @result{} (b 1)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1607
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1608 (select-frame f2)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1609 (set-buffer (get-buffer-create "b1"))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1610 foo
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1611 @result{} (b 1)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1612 @end example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1613
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1614 @noindent
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1615 Otherwise, the frame gets a chance to provide the binding; when frame
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1616 @code{f2} is selected, its frame-local binding is in effect:
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1617
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1618 @example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1619 (select-frame f2)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1620 (set-buffer (get-buffer "*scratch*"))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1621 foo
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1622 @result{} (f 2)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1623 @end example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1624
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1625 @noindent
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1626 When neither the current buffer nor the selected frame provides
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1627 a binding, the default binding is used:
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1628
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1629 @example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1630 (select-frame f1)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1631 (set-buffer (get-buffer "*scratch*"))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1632 foo
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1633 @result{} nil
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1634 @end example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1635
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1636 @noindent
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1637 When the active binding of a variable is a frame-local binding, setting
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1638 the variable changes that binding. You can observe the result with
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1639 @code{frame-parameters}:
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1640
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1641 @example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1642 (select-frame f2)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1643 (set-buffer (get-buffer "*scratch*"))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1644 (setq foo 'nobody)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1645 (assq 'foo (frame-parameters f2))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1646 @result{} (foo . nobody)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1647 @end example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1648
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1649 @node Future Local Variables
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1650 @section Possible Future Local Variables
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1651
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1652 We have considered the idea of bindings that are local to a category
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1653 of frames---for example, all color frames, or all frames with dark
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1654 backgrounds. We have not implemented them because it is not clear that
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1655 this feature is really useful. You can get more or less the same
32596
1cb37313bcac Obsolete variable `after-make-frame-hook'.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 30502
diff changeset
1656 results by adding a function to @code{after-make-frame-functions}, set up to
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1657 define a particular frame parameter according to the appropriate
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1658 conditions for each frame.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1659
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1660 It would also be possible to implement window-local bindings. We
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1661 don't know of many situations where they would be useful, and it seems
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1662 that indirect buffers (@pxref{Indirect Buffers}) with buffer-local
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1663 bindings offer a way to handle these situations more robustly.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1664
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1665 If sufficient application is found for either of these two kinds of
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1666 local bindings, we will provide it in a subsequent Emacs version.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1667
39571
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1668 @node Variable Aliases
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1669 @section Variable Aliases
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1670
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1671 It is sometimes useful to make two variables synonyms, so that both
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1672 variables always have the same value, and changing either one also
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1673 changes the other. Whenever you change the name of a
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1674 variable---either because you realize its old name was not well
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1675 chosen, or because its meaning has partly changed---it can be useful
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1676 to keep the old name as an @emph{alias} of the new one for
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1677 compatibility. You can do this with @code{defvaralias}.
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1678
39628
7f0c5b8c1f41 (Variable Aliases): It's `@defmac', not `@defmacro'.
Miles Bader <miles@gnu.org>
parents: 39571
diff changeset
1679 @defmac defvaralias alias-var base-var
39571
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1680 This function defines the symbol @var{alias-var} as a variable alias
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1681 for symbol @var{base-var}. This means that retrieving the value of
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1682 @var{alias-var} returns the value of @var{base-var}, and changing the
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1683 value of @var{alias-var} changes the value of @var{base-var}.
39628
7f0c5b8c1f41 (Variable Aliases): It's `@defmac', not `@defmacro'.
Miles Bader <miles@gnu.org>
parents: 39571
diff changeset
1684 @end defmac
39571
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1685
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1686 @defun indirect-variable variable
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1687 This function returns the variable at the end of the chain of aliases
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1688 of @var{variable}. If @var{variable} is not a symbol, or if @var{variable} is
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1689 not defined as an alias, the function returns @var{variable}.
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1690 @end defun
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1691
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1692 @example
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1693 (defvaralias 'foo 'bar)
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1694 (indirect-variable 'foo)
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1695 @result{} bar
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1696 (indirect-variable 'bar)
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1697 @result{} bar
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1698 (setq bar 2)
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1699 bar
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1700 @result{} 2
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1701 foo
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1702 @result{} 2
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1703 (setq foo 0)
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1704 bar
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1705 @result{} 0
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1706 foo
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1707 @result{} 0
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1708 @end example
9b87a63bcb36 (Variable Aliases): New node.
Gerd Moellmann <gerd@gnu.org>
parents: 39165
diff changeset
1709
27389
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1710 @node File Local Variables
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1711 @section File Local Variables
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1712
27389
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1713 This section describes the functions and variables that affect
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1714 processing of local variables lists in files.
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1715
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1716 @defopt enable-local-variables
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1717 This variable controls whether to process file local variables lists. A
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1718 value of @code{t} means process the local variables lists
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1719 unconditionally; @code{nil} means ignore them; anything else means ask
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1720 the user what to do for each file. The default value is @code{t}.
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1721 @end defopt
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1722
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1723 @defun hack-local-variables &optional force
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1724 This function parses, and binds or evaluates as appropriate, any local
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1725 variables specified by the contents of the current buffer. The variable
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1726 @code{enable-local-variables} has its effect here.
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1727
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1728 The argument @var{force} usually comes from the argument @var{find-file}
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1729 given to @code{normal-mode}.
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1730 @end defun
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1731
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1732 If a file local variable list could specify the a function that will
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1733 be called later, or an expression that will be executed later, simply
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1734 visiting a file could take over your Emacs. To prevent this, Emacs
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1735 takes care not to allow local variable lists to set such variables.
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1736
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1737 For one thing, any variable whose name ends in @samp{-function},
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1738 @samp{-functions}, @samp{-hook}, @samp{-hooks}, @samp{-form},
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1739 @samp{-forms}, @samp{-program}, @samp{-command} or @samp{-predicate}
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1740 cannot be set in a local variable list. In general, you should use such
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1741 a name whenever it is appropriate for the variable's meaning.
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1742
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1743 In addition, any variable whose name has a non-@code{nil}
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1744 @code{risky-local-variable} property is also ignored. So are
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1745 all variables listed in @code{ignored-local-variables}:
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1746
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1747 @defvar ignored-local-variables
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1748 This variable holds a list of variables that should not be
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1749 set by a file's local variables list. Any value specified
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1750 for one of these variables is ignored.
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1751 @end defvar
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1752
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1753 The @samp{Eval:} ``variable'' is also a potential loophole, so Emacs
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1754 normally asks for confirmation before handling it.
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1755
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1756 @defopt enable-local-eval
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1757 This variable controls processing of @samp{Eval:} in local variables
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1758 lists in files being visited. A value of @code{t} means process them
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1759 unconditionally; @code{nil} means ignore them; anything else means ask
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1760 the user what to do for each file. The default value is @code{maybe}.
0eff88dd2524 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27189
diff changeset
1761 @end defopt