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