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