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
+ − 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 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
+ − 228 Function calls (@pxref{Functions}).
+ − 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
+ − 897 but record additional variable bindings. XEmacs Lisp does not have
+ − 898 closures.
+ − 899
+ − 900 @node Impl of Scope
+ − 901 @subsection Implementation of Dynamic Scoping
+ − 902 @cindex deep binding
+ − 903
+ − 904 A simple sample implementation (which is not how XEmacs Lisp actually
+ − 905 works) may help you understand dynamic binding. This technique is
+ − 906 called @dfn{deep binding} and was used in early Lisp systems.
+ − 907
+ − 908 Suppose there is a stack of bindings: variable-value pairs. At entry
+ − 909 to a function or to a @code{let} form, we can push bindings on the stack
+ − 910 for the arguments or local variables created there. We can pop those
+ − 911 bindings from the stack at exit from the binding construct.
+ − 912
+ − 913 We can find the value of a variable by searching the stack from top to
+ − 914 bottom for a binding for that variable; the value from that binding is
+ − 915 the value of the variable. To set the variable, we search for the
+ − 916 current binding, then store the new value into that binding.
+ − 917
+ − 918 As you can see, a function's bindings remain in effect as long as it
+ − 919 continues execution, even during its calls to other functions. That is
+ − 920 why we say the extent of the binding is dynamic. And any other function
+ − 921 can refer to the bindings, if it uses the same variables while the
+ − 922 bindings are in effect. That is why we say the scope is indefinite.
+ − 923
+ − 924 @cindex shallow binding
+ − 925 The actual implementation of variable scoping in XEmacs Lisp uses a
+ − 926 technique called @dfn{shallow binding}. Each variable has a standard
+ − 927 place in which its current value is always found---the value cell of the
+ − 928 symbol.
+ − 929
+ − 930 In shallow binding, setting the variable works by storing a value in
+ − 931 the value cell. Creating a new binding works by pushing the old value
+ − 932 (belonging to a previous binding) on a stack, and storing the local value
+ − 933 in the value cell. Eliminating a binding works by popping the old value
+ − 934 off the stack, into the value cell.
+ − 935
+ − 936 We use shallow binding because it has the same results as deep
+ − 937 binding, but runs faster, since there is never a need to search for a
+ − 938 binding.
+ − 939
+ − 940 @node Using Scoping
+ − 941 @subsection Proper Use of Dynamic Scoping
+ − 942
+ − 943 Binding a variable in one function and using it in another is a
+ − 944 powerful technique, but if used without restraint, it can make programs
+ − 945 hard to understand. There are two clean ways to use this technique:
+ − 946
+ − 947 @itemize @bullet
+ − 948 @item
+ − 949 Use or bind the variable only in a few related functions, written close
+ − 950 together in one file. Such a variable is used for communication within
+ − 951 one program.
+ − 952
+ − 953 You should write comments to inform other programmers that they can see
+ − 954 all uses of the variable before them, and to advise them not to add uses
+ − 955 elsewhere.
+ − 956
+ − 957 @item
+ − 958 Give the variable a well-defined, documented meaning, and make all
+ − 959 appropriate functions refer to it (but not bind it or set it) wherever
+ − 960 that meaning is relevant. For example, the variable
+ − 961 @code{case-fold-search} is defined as ``non-@code{nil} means ignore case
+ − 962 when searching''; various search and replace functions refer to it
+ − 963 directly or through their subroutines, but do not bind or set it.
+ − 964
+ − 965 Then you can bind the variable in other programs, knowing reliably what
+ − 966 the effect will be.
+ − 967 @end itemize
+ − 968
+ − 969 In either case, you should define the variable with @code{defvar}.
+ − 970 This helps other people understand your program by telling them to look
+ − 971 for inter-function usage. It also avoids a warning from the byte
+ − 972 compiler. Choose the variable's name to avoid name conflicts---don't
+ − 973 use short names like @code{x}.
+ − 974
+ − 975 @node Buffer-Local Variables
+ − 976 @section Buffer-Local Variables
+ − 977 @cindex variables, buffer-local
+ − 978 @cindex buffer-local variables
+ − 979
+ − 980 Global and local variable bindings are found in most programming
+ − 981 languages in one form or another. XEmacs also supports another, unusual
+ − 982 kind of variable binding: @dfn{buffer-local} bindings, which apply only
+ − 983 to one buffer. XEmacs Lisp is meant for programming editing commands,
+ − 984 and having different values for a variable in different buffers is an
+ − 985 important customization method.
+ − 986
+ − 987 @menu
+ − 988 * Intro to Buffer-Local:: Introduction and concepts.
+ − 989 * Creating Buffer-Local:: Creating and destroying buffer-local bindings.
+ − 990 * Default Value:: The default value is seen in buffers
+ − 991 that don't have their own local values.
+ − 992 @end menu
+ − 993
+ − 994 @node Intro to Buffer-Local
+ − 995 @subsection Introduction to Buffer-Local Variables
+ − 996
+ − 997 A buffer-local variable has a buffer-local binding associated with a
+ − 998 particular buffer. The binding is in effect when that buffer is
+ − 999 current; otherwise, it is not in effect. If you set the variable while
+ − 1000 a buffer-local binding is in effect, the new value goes in that binding,
+ − 1001 so the global binding is unchanged; this means that the change is
+ − 1002 visible in that buffer alone.
+ − 1003
+ − 1004 A variable may have buffer-local bindings in some buffers but not in
+ − 1005 others. The global binding is shared by all the buffers that don't have
+ − 1006 their own bindings. Thus, if you set the variable in a buffer that does
+ − 1007 not have a buffer-local binding for it, the new value is visible in all
+ − 1008 buffers except those with buffer-local bindings. (Here we are assuming
+ − 1009 that there are no @code{let}-style local bindings to complicate the issue.)
+ − 1010
+ − 1011 The most common use of buffer-local bindings is for major modes to change
+ − 1012 variables that control the behavior of commands. For example, C mode and
+ − 1013 Lisp mode both set the variable @code{paragraph-start} to specify that only
+ − 1014 blank lines separate paragraphs. They do this by making the variable
+ − 1015 buffer-local in the buffer that is being put into C mode or Lisp mode, and
+ − 1016 then setting it to the new value for that mode.
+ − 1017
+ − 1018 The usual way to make a buffer-local binding is with
+ − 1019 @code{make-local-variable}, which is what major mode commands use. This
+ − 1020 affects just the current buffer; all other buffers (including those yet to
+ − 1021 be created) continue to share the global value.
+ − 1022
+ − 1023 @cindex automatically buffer-local
+ − 1024 A more powerful operation is to mark the variable as
+ − 1025 @dfn{automatically buffer-local} by calling
+ − 1026 @code{make-variable-buffer-local}. You can think of this as making the
+ − 1027 variable local in all buffers, even those yet to be created. More
+ − 1028 precisely, the effect is that setting the variable automatically makes
+ − 1029 the variable local to the current buffer if it is not already so. All
+ − 1030 buffers start out by sharing the global value of the variable as usual,
+ − 1031 but any @code{setq} creates a buffer-local binding for the current
+ − 1032 buffer. The new value is stored in the buffer-local binding, leaving
+ − 1033 the (default) global binding untouched. The global value can no longer
+ − 1034 be changed with @code{setq}; you need to use @code{setq-default} to do
+ − 1035 that.
+ − 1036
+ − 1037 @ignore
+ − 1038 Section about not changing buffers during let bindings. Mly fixed
+ − 1039 this for XEmacs.
+ − 1040 @end ignore
+ − 1041 Local variables in a file you edit are also represented by
+ − 1042 buffer-local bindings for the buffer that holds the file within XEmacs.
+ − 1043 @xref{Auto Major Mode}.
+ − 1044
+ − 1045 @node Creating Buffer-Local
+ − 1046 @subsection Creating and Deleting Buffer-Local Bindings
+ − 1047
+ − 1048 @deffn Command make-local-variable variable
+ − 1049 This function creates a buffer-local binding in the current buffer for
+ − 1050 @var{variable} (a symbol). Other buffers are not affected. The value
+ − 1051 returned is @var{variable}.
+ − 1052
+ − 1053 @c Emacs 19 feature
+ − 1054 The buffer-local value of @var{variable} starts out as the same value
+ − 1055 @var{variable} previously had. If @var{variable} was void, it remains
+ − 1056 void.
+ − 1057
+ − 1058 @example
+ − 1059 @group
+ − 1060 ;; @r{In buffer @samp{b1}:}
+ − 1061 (setq foo 5) ; @r{Affects all buffers.}
+ − 1062 @result{} 5
+ − 1063 @end group
+ − 1064 @group
+ − 1065 (make-local-variable 'foo) ; @r{Now it is local in @samp{b1}.}
+ − 1066 @result{} foo
+ − 1067 @end group
+ − 1068 @group
+ − 1069 foo ; @r{That did not change}
+ − 1070 @result{} 5 ; @r{the value.}
+ − 1071 @end group
+ − 1072 @group
+ − 1073 (setq foo 6) ; @r{Change the value}
+ − 1074 @result{} 6 ; @r{in @samp{b1}.}
+ − 1075 @end group
+ − 1076 @group
+ − 1077 foo
+ − 1078 @result{} 6
+ − 1079 @end group
+ − 1080
+ − 1081 @group
+ − 1082 ;; @r{In buffer @samp{b2}, the value hasn't changed.}
+ − 1083 (save-excursion
+ − 1084 (set-buffer "b2")
+ − 1085 foo)
+ − 1086 @result{} 5
+ − 1087 @end group
+ − 1088 @end example
+ − 1089
+ − 1090 Making a variable buffer-local within a @code{let}-binding for that
+ − 1091 variable does not work. This is because @code{let} does not distinguish
+ − 1092 between different kinds of bindings; it knows only which variable the
+ − 1093 binding was made for.
+ − 1094
+ − 1095 @strong{Please note:} do not use @code{make-local-variable} for a hook
+ − 1096 variable. Instead, use @code{make-local-hook}. @xref{Hooks}.
+ − 1097 @end deffn
+ − 1098
+ − 1099 @deffn Command make-variable-buffer-local variable
+ − 1100 This function marks @var{variable} (a symbol) automatically
+ − 1101 buffer-local, so that any subsequent attempt to set it will make it
+ − 1102 local to the current buffer at the time.
+ − 1103
+ − 1104 The value returned is @var{variable}.
+ − 1105 @end deffn
+ − 1106
444
+ − 1107 @defun local-variable-p variable buffer &optional after-set
428
+ − 1108 This returns @code{t} if @var{variable} is buffer-local in buffer
444
+ − 1109 @var{buffer}; else @code{nil}.
+ − 1110
+ − 1111 If optional third arg @var{after-set} is non-@code{nil}, return @code{t}
+ − 1112 if @var{symbol} would be buffer-local after it is set, regardless of
+ − 1113 whether it is so presently.
+ − 1114
+ − 1115 A @code{nil} value for @var{buffer} is @emph{not} the same as
+ − 1116 @code{(current-buffer)}, but means "no buffer". Specifically:
+ − 1117
+ − 1118 If @var{buffer} is @code{nil} and @var{after-set} is @code{nil}, a
+ − 1119 return value of @code{t} indicates that the variable is one of the
+ − 1120 special built-in variables that is always buffer-local. (This includes
+ − 1121 @code{buffer-file-name}, @code{buffer-read-only},
+ − 1122 @code{buffer-undo-list}, and others.)
+ − 1123
+ − 1124 If @var{buffer} is @code{nil} and @var{after-set} is @code{t}, a return
+ − 1125 value of @code{t} indicates that the variable has had
+ − 1126 @code{make-variable-buffer-local} applied to it.
428
+ − 1127 @end defun
+ − 1128
+ − 1129 @defun buffer-local-variables &optional buffer
+ − 1130 This function returns a list describing the buffer-local variables in
+ − 1131 buffer @var{buffer}. It returns an association list (@pxref{Association
+ − 1132 Lists}) in which each association contains one buffer-local variable and
+ − 1133 its value. When a buffer-local variable is void in @var{buffer}, then
+ − 1134 it appears directly in the resulting list. If @var{buffer} is omitted,
+ − 1135 the current buffer is used.
+ − 1136
+ − 1137 @example
+ − 1138 @group
+ − 1139 (make-local-variable 'foobar)
+ − 1140 (makunbound 'foobar)
+ − 1141 (make-local-variable 'bind-me)
+ − 1142 (setq bind-me 69)
+ − 1143 @end group
+ − 1144 (setq lcl (buffer-local-variables))
+ − 1145 ;; @r{First, built-in variables local in all buffers:}
+ − 1146 @result{} ((mark-active . nil)
+ − 1147 (buffer-undo-list nil)
+ − 1148 (mode-name . "Fundamental")
+ − 1149 @dots{}
+ − 1150 @group
444
+ − 1151 ;; @r{Next, non-built-in local variables.}
428
+ − 1152 ;; @r{This one is local and void:}
+ − 1153 foobar
+ − 1154 ;; @r{This one is local and nonvoid:}
+ − 1155 (bind-me . 69))
+ − 1156 @end group
+ − 1157 @end example
+ − 1158
+ − 1159 Note that storing new values into the @sc{cdr}s of cons cells in this
+ − 1160 list does @emph{not} change the local values of the variables.
+ − 1161 @end defun
+ − 1162
+ − 1163 @deffn Command kill-local-variable variable
+ − 1164 This function deletes the buffer-local binding (if any) for
+ − 1165 @var{variable} (a symbol) in the current buffer. As a result, the
+ − 1166 global (default) binding of @var{variable} becomes visible in this
+ − 1167 buffer. Usually this results in a change in the value of
+ − 1168 @var{variable}, since the global value is usually different from the
+ − 1169 buffer-local value just eliminated.
+ − 1170
+ − 1171 If you kill the local binding of a variable that automatically becomes
+ − 1172 local when set, this makes the global value visible in the current
+ − 1173 buffer. However, if you set the variable again, that will once again
+ − 1174 create a local binding for it.
+ − 1175
+ − 1176 @code{kill-local-variable} returns @var{variable}.
+ − 1177
+ − 1178 This function is a command because it is sometimes useful to kill one
+ − 1179 buffer-local variable interactively, just as it is useful to create
+ − 1180 buffer-local variables interactively.
+ − 1181 @end deffn
+ − 1182
+ − 1183 @defun kill-all-local-variables
+ − 1184 This function eliminates all the buffer-local variable bindings of the
+ − 1185 current buffer except for variables marked as ``permanent''. As a
+ − 1186 result, the buffer will see the default values of most variables.
+ − 1187
+ − 1188 This function also resets certain other information pertaining to the
+ − 1189 buffer: it sets the local keymap to @code{nil}, the syntax table to the
+ − 1190 value of @code{standard-syntax-table}, and the abbrev table to the value
+ − 1191 of @code{fundamental-mode-abbrev-table}.
+ − 1192
+ − 1193 Every major mode command begins by calling this function, which has the
+ − 1194 effect of switching to Fundamental mode and erasing most of the effects
+ − 1195 of the previous major mode. To ensure that this does its job, the
+ − 1196 variables that major modes set should not be marked permanent.
+ − 1197
+ − 1198 @code{kill-all-local-variables} returns @code{nil}.
+ − 1199 @end defun
+ − 1200
+ − 1201 @c Emacs 19 feature
+ − 1202 @cindex permanent local variable
+ − 1203 A local variable is @dfn{permanent} if the variable name (a symbol) has a
+ − 1204 @code{permanent-local} property that is non-@code{nil}. Permanent
+ − 1205 locals are appropriate for data pertaining to where the file came from
+ − 1206 or how to save it, rather than with how to edit the contents.
+ − 1207
+ − 1208 @node Default Value
+ − 1209 @subsection The Default Value of a Buffer-Local Variable
+ − 1210 @cindex default value
+ − 1211
+ − 1212 The global value of a variable with buffer-local bindings is also
+ − 1213 called the @dfn{default} value, because it is the value that is in
+ − 1214 effect except when specifically overridden.
+ − 1215
+ − 1216 The functions @code{default-value} and @code{setq-default} access and
+ − 1217 change a variable's default value regardless of whether the current
+ − 1218 buffer has a buffer-local binding. For example, you could use
+ − 1219 @code{setq-default} to change the default setting of
+ − 1220 @code{paragraph-start} for most buffers; and this would work even when
+ − 1221 you are in a C or Lisp mode buffer that has a buffer-local value for
+ − 1222 this variable.
+ − 1223
+ − 1224 @c Emacs 19 feature
+ − 1225 The special forms @code{defvar} and @code{defconst} also set the
+ − 1226 default value (if they set the variable at all), rather than any local
+ − 1227 value.
+ − 1228
+ − 1229 @defun default-value symbol
+ − 1230 This function returns @var{symbol}'s default value. This is the value
+ − 1231 that is seen in buffers that do not have their own values for this
+ − 1232 variable. If @var{symbol} is not buffer-local, this is equivalent to
+ − 1233 @code{symbol-value} (@pxref{Accessing Variables}).
+ − 1234 @end defun
+ − 1235
+ − 1236 @c Emacs 19 feature
+ − 1237 @defun default-boundp symbol
+ − 1238 The function @code{default-boundp} tells you whether @var{symbol}'s
+ − 1239 default value is nonvoid. If @code{(default-boundp 'foo)} returns
+ − 1240 @code{nil}, then @code{(default-value 'foo)} would get an error.
+ − 1241
+ − 1242 @code{default-boundp} is to @code{default-value} as @code{boundp} is to
+ − 1243 @code{symbol-value}.
+ − 1244 @end defun
+ − 1245
+ − 1246 @defspec setq-default symbol value
+ − 1247 This sets the default value of @var{symbol} to @var{value}. It does not
+ − 1248 evaluate @var{symbol}, but does evaluate @var{value}. The value of the
+ − 1249 @code{setq-default} form is @var{value}.
+ − 1250
+ − 1251 If a @var{symbol} is not buffer-local for the current buffer, and is not
+ − 1252 marked automatically buffer-local, @code{setq-default} has the same
+ − 1253 effect as @code{setq}. If @var{symbol} is buffer-local for the current
+ − 1254 buffer, then this changes the value that other buffers will see (as long
+ − 1255 as they don't have a buffer-local value), but not the value that the
+ − 1256 current buffer sees.
+ − 1257
+ − 1258 @example
+ − 1259 @group
+ − 1260 ;; @r{In buffer @samp{foo}:}
+ − 1261 (make-local-variable 'local)
+ − 1262 @result{} local
+ − 1263 @end group
+ − 1264 @group
+ − 1265 (setq local 'value-in-foo)
+ − 1266 @result{} value-in-foo
+ − 1267 @end group
+ − 1268 @group
+ − 1269 (setq-default local 'new-default)
+ − 1270 @result{} new-default
+ − 1271 @end group
+ − 1272 @group
+ − 1273 local
+ − 1274 @result{} value-in-foo
+ − 1275 @end group
+ − 1276 @group
+ − 1277 (default-value 'local)
+ − 1278 @result{} new-default
+ − 1279 @end group
+ − 1280
+ − 1281 @group
+ − 1282 ;; @r{In (the new) buffer @samp{bar}:}
+ − 1283 local
+ − 1284 @result{} new-default
+ − 1285 @end group
+ − 1286 @group
+ − 1287 (default-value 'local)
+ − 1288 @result{} new-default
+ − 1289 @end group
+ − 1290 @group
+ − 1291 (setq local 'another-default)
+ − 1292 @result{} another-default
+ − 1293 @end group
+ − 1294 @group
+ − 1295 (default-value 'local)
+ − 1296 @result{} another-default
+ − 1297 @end group
+ − 1298
+ − 1299 @group
+ − 1300 ;; @r{Back in buffer @samp{foo}:}
+ − 1301 local
+ − 1302 @result{} value-in-foo
+ − 1303 (default-value 'local)
+ − 1304 @result{} another-default
+ − 1305 @end group
+ − 1306 @end example
+ − 1307 @end defspec
+ − 1308
+ − 1309 @defun set-default symbol value
+ − 1310 This function is like @code{setq-default}, except that @var{symbol} is
+ − 1311 evaluated.
+ − 1312
+ − 1313 @example
+ − 1314 @group
+ − 1315 (set-default (car '(a b c)) 23)
+ − 1316 @result{} 23
+ − 1317 @end group
+ − 1318 @group
+ − 1319 (default-value 'a)
+ − 1320 @result{} 23
+ − 1321 @end group
+ − 1322 @end example
+ − 1323 @end defun
+ − 1324
+ − 1325 @node Variable Aliases
+ − 1326 @section Variable Aliases
+ − 1327 @cindex variables, indirect
+ − 1328 @cindex indirect variables
+ − 1329 @cindex variable aliases
+ − 1330 @cindex aliases, for variables
+ − 1331
+ − 1332 You can define a variable as an @dfn{alias} for another. Any time
+ − 1333 you reference the former variable, the current value of the latter
+ − 1334 is returned. Any time you change the value of the former variable,
+ − 1335 the value of the latter is actually changed. This is useful in
+ − 1336 cases where you want to rename a variable but still make old code
+ − 1337 work (@pxref{Obsoleteness}).
+ − 1338
+ − 1339 @defun defvaralias variable alias
+ − 1340 This function defines @var{variable} as an alias for @var{alias}.
+ − 1341 Thenceforth, any operations performed on @var{variable} will actually be
+ − 1342 performed on @var{alias}. Both @var{variable} and @var{alias} should be
+ − 1343 symbols. If @var{alias} is @code{nil}, remove any aliases for
+ − 1344 @var{variable}. @var{alias} can itself be aliased, and the chain of
+ − 1345 variable aliases will be followed appropriately. If @var{variable}
+ − 1346 already has a value, this value will be shadowed until the alias is
+ − 1347 removed, at which point it will be restored. Currently @var{variable}
+ − 1348 cannot be a built-in variable, a variable that has a buffer-local value
+ − 1349 in any buffer, or the symbols @code{nil} or @code{t}.
+ − 1350 @end defun
+ − 1351
444
+ − 1352 @defun variable-alias variable &optional follow-past-lisp-magic
428
+ − 1353 If @var{variable} is aliased to another variable, this function returns
+ − 1354 that variable. @var{variable} should be a symbol. If @var{variable} is
+ − 1355 not aliased, this function returns @code{nil}.
+ − 1356 @end defun
+ − 1357
444
+ − 1358 @defun indirect-variable object &optional follow-past-lisp-magic
428
+ − 1359 This function returns the variable at the end of @var{object}'s
+ − 1360 variable-alias chain. If @var{object} is a symbol, follow all variable
+ − 1361 aliases and return the final (non-aliased) symbol. If @var{object} is
+ − 1362 not a symbol, just return it. Signal a
+ − 1363 @code{cyclic-variable-indirection} error if there is a loop in the
+ − 1364 variable chain of symbols.
+ − 1365 @end defun
+ − 1366
+ − 1367