1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Error Symbols, Prev: Handling Errors, Up: Errors
55 Error Symbols and Condition Names
56 .................................
58 When you signal an error, you specify an "error symbol" to specify
59 the kind of error you have in mind. Each error has one and only one
60 error symbol to categorize it. This is the finest classification of
61 errors defined by the XEmacs Lisp language.
63 These narrow classifications are grouped into a hierarchy of wider
64 classes called "error conditions", identified by "condition names".
65 The narrowest such classes belong to the error symbols themselves: each
66 error symbol is also a condition name. There are also condition names
67 for more extensive classes, up to the condition name `error' which
68 takes in all kinds of errors. Thus, each error has one or more
69 condition names: `error', the error symbol if that is distinct from
70 `error', and perhaps some intermediate classifications.
72 In other words, each error condition "inherits" from another error
73 condition, with `error' sitting at the top of the inheritance hierarchy.
75 - Function: define-error error-symbol error-message &optional
77 This function defines a new error, denoted by ERROR-SYMBOL.
78 ERROR-MESSAGE is an informative message explaining the error, and
79 will be printed out when an unhandled error occurs. ERROR-SYMBOL
80 is a sub-error of INHERITS-FROM (which defaults to `error').
82 `define-error' internally works by putting on ERROR-SYMBOL an
83 `error-message' property whose value is ERROR-MESSAGE, and an
84 `error-conditions' property that is a list of ERROR-SYMBOL
85 followed by each of its super-errors, up to and including `error'.
86 You will sometimes see code that sets this up directly rather than
87 calling `define-error', but you should _not_ do this yourself,
88 unless you wish to maintain compatibility with FSF Emacs, which
89 does not provide `define-error'.
91 Here is how we define a new error symbol, `new-error', that belongs
92 to a range of errors called `my-own-errors':
94 (define-error 'my-own-errors "A whole range of errors" 'error)
95 (define-error 'new-error "A new error" 'my-own-errors)
97 `new-error' has three condition names: `new-error', the narrowest
98 classification; `my-own-errors', which we imagine is a wider
99 classification; and `error', which is the widest of all.
101 Note that it is not legal to try to define an error unless its
102 super-error is also defined. For instance, attempting to define
103 `new-error' before `my-own-errors' are defined will signal an error.
105 The error string should start with a capital letter but it should
106 not end with a period. This is for consistency with the rest of Emacs.
108 Naturally, XEmacs will never signal `new-error' on its own; only an
109 explicit call to `signal' (*note Signaling Errors::) in your code can
112 (signal 'new-error '(x y))
113 error--> A new error: x, y
115 This error can be handled through any of the three condition names.
116 This example handles `new-error' and any other errors in the class
123 The significant way that errors are classified is by their condition
124 names--the names used to match errors with handlers. An error symbol
125 serves only as a convenient way to specify the intended error message
126 and list of condition names. It would be cumbersome to give `signal' a
127 list of condition names rather than one error symbol.
129 By contrast, using only error symbols without condition names would
130 seriously decrease the power of `condition-case'. Condition names make
131 it possible to categorize errors at various levels of generality when
132 you write an error handler. Using error symbols alone would eliminate
133 all but the narrowest level of classification.
135 *Note Standard Errors::, for a list of all the standard error symbols
136 and their conditions.
139 File: lispref.info, Node: Cleanups, Prev: Errors, Up: Nonlocal Exits
141 Cleaning Up from Nonlocal Exits
142 -------------------------------
144 The `unwind-protect' construct is essential whenever you temporarily
145 put a data structure in an inconsistent state; it permits you to ensure
146 the data are consistent in the event of an error or throw.
148 - Special Form: unwind-protect body cleanup-forms...
149 `unwind-protect' executes the BODY with a guarantee that the
150 CLEANUP-FORMS will be evaluated if control leaves BODY, no matter
151 how that happens. The BODY may complete normally, or execute a
152 `throw' out of the `unwind-protect', or cause an error; in all
153 cases, the CLEANUP-FORMS will be evaluated.
155 If the BODY forms finish normally, `unwind-protect' returns the
156 value of the last BODY form, after it evaluates the CLEANUP-FORMS.
157 If the BODY forms do not finish, `unwind-protect' does not return
158 any value in the normal sense.
160 Only the BODY is actually protected by the `unwind-protect'. If
161 any of the CLEANUP-FORMS themselves exits nonlocally (e.g., via a
162 `throw' or an error), `unwind-protect' is _not_ guaranteed to
163 evaluate the rest of them. If the failure of one of the
164 CLEANUP-FORMS has the potential to cause trouble, then protect it
165 with another `unwind-protect' around that form.
167 The number of currently active `unwind-protect' forms counts,
168 together with the number of local variable bindings, against the
169 limit `max-specpdl-size' (*note Local Variables::).
171 For example, here we make an invisible buffer for temporary use, and
172 make sure to kill it before finishing:
175 (let ((buffer (get-buffer-create " *temp*")))
179 (kill-buffer buffer))))
181 You might think that we could just as well write `(kill-buffer
182 (current-buffer))' and dispense with the variable `buffer'. However,
183 the way shown above is safer, if BODY happens to get an error after
184 switching to a different buffer! (Alternatively, you could write
185 another `save-excursion' around the body, to ensure that the temporary
186 buffer becomes current in time to kill it.)
188 Here is an actual example taken from the file `ftp.el'. It creates
189 a process (*note Processes::) to try to establish a connection to a
190 remote machine. As the function `ftp-login' is highly susceptible to
191 numerous problems that the writer of the function cannot anticipate, it
192 is protected with a form that guarantees deletion of the process in the
193 event of failure. Otherwise, XEmacs might fill up with useless
199 (setq process (ftp-setup-buffer host file))
200 (if (setq win (ftp-login process host user password))
201 (message "Logged in")
202 (error "Ftp login failed")))
203 (or win (and process (delete-process process)))))
205 This example actually has a small bug: if the user types `C-g' to
206 quit, and the quit happens immediately after the function
207 `ftp-setup-buffer' returns but before the variable `process' is set,
208 the process will not be killed. There is no easy way to fix this bug,
209 but at least it is very unlikely.
211 Here is another example which uses `unwind-protect' to make sure to
212 kill a temporary buffer. In this example, the value returned by
213 `unwind-protect' is used.
215 (defun shell-command-string (cmd)
216 "Return the output of the shell command CMD, as a string."
218 (set-buffer (generate-new-buffer " OS*cmd"))
219 (shell-command cmd t)
222 (kill-buffer (current-buffer)))))
225 File: lispref.info, Node: Variables, Next: Functions, Prev: Control Structures, Up: Top
230 A "variable" is a name used in a program to stand for a value.
231 Nearly all programming languages have variables of some sort. In the
232 text of a Lisp program, variables are written using the syntax for
235 In Lisp, unlike most programming languages, programs are represented
236 primarily as Lisp objects and only secondarily as text. The Lisp
237 objects used for variables are symbols: the symbol name is the variable
238 name, and the variable's value is stored in the value cell of the
239 symbol. The use of a symbol as a variable is independent of its use as
240 a function name. *Note Symbol Components::.
242 The Lisp objects that constitute a Lisp program determine the textual
243 form of the program--it is simply the read syntax for those Lisp
244 objects. This is why, for example, a variable in a textual Lisp program
245 is written using the read syntax for the symbol that represents the
250 * Global Variables:: Variable values that exist permanently, everywhere.
251 * Constant Variables:: Certain "variables" have values that never change.
252 * Local Variables:: Variable values that exist only temporarily.
253 * Void Variables:: Symbols that lack values.
254 * Defining Variables:: A definition says a symbol is used as a variable.
255 * Accessing Variables:: Examining values of variables whose names
256 are known only at run time.
257 * Setting Variables:: Storing new values in variables.
258 * Variable Scoping:: How Lisp chooses among local and global values.
259 * Buffer-Local Variables:: Variable values in effect only in one buffer.
260 * Variable Aliases:: Making one variable point to another.
263 File: lispref.info, Node: Global Variables, Next: Constant Variables, Up: Variables
268 The simplest way to use a variable is "globally". This means that
269 the variable has just one value at a time, and this value is in effect
270 (at least for the moment) throughout the Lisp system. The value remains
271 in effect until you specify a new one. When a new value replaces the
272 old one, no trace of the old value remains in the variable.
274 You specify a value for a symbol with `setq'. For example,
278 gives the variable `x' the value `(a b)'. Note that `setq' does not
279 evaluate its first argument, the name of the variable, but it does
280 evaluate the second argument, the new value.
282 Once the variable has a value, you can refer to it by using the
283 symbol by itself as an expression. Thus,
287 assuming the `setq' form shown above has already been executed.
289 If you do another `setq', the new value replaces the old one:
299 File: lispref.info, Node: Constant Variables, Next: Local Variables, Prev: Global Variables, Up: Variables
301 Variables That Never Change
302 ===========================
304 In XEmacs Lisp, some symbols always evaluate to themselves: the two
305 special symbols `nil' and `t', as well as "keyword symbols", that is,
306 symbols whose name begins with the character ``:''. These symbols
307 cannot be rebound, nor can their value cells be changed. An attempt to
308 change the value of `nil' or `t' signals a `setting-constant' error.
313 error--> Attempt to set constant symbol: nil
316 File: lispref.info, Node: Local Variables, Next: Void Variables, Prev: Constant Variables, Up: Variables
321 Global variables have values that last until explicitly superseded
322 with new values. Sometimes it is useful to create variable values that
323 exist temporarily--only while within a certain part of the program.
324 These values are called "local", and the variables so used are called
327 For example, when a function is called, its argument variables
328 receive new local values that last until the function exits. The `let'
329 special form explicitly establishes new local values for specified
330 variables; these last until exit from the `let' form.
332 Establishing a local value saves away the previous value (or lack of
333 one) of the variable. When the life span of the local value is over,
334 the previous value is restored. In the mean time, we say that the
335 previous value is "shadowed" and "not visible". Both global and local
336 values may be shadowed (*note Scope::).
338 If you set a variable (such as with `setq') while it is local, this
339 replaces the local value; it does not alter the global value, or
340 previous local values that are shadowed. To model this behavior, we
341 speak of a "local binding" of the variable as well as a local value.
343 The local binding is a conceptual place that holds a local value.
344 Entry to a function, or a special form such as `let', creates the local
345 binding; exit from the function or from the `let' removes the local
346 binding. As long as the local binding lasts, the variable's value is
347 stored within it. Use of `setq' or `set' while there is a local
348 binding stores a different value into the local binding; it does not
349 create a new binding.
351 We also speak of the "global binding", which is where (conceptually)
352 the global value is kept.
354 A variable can have more than one local binding at a time (for
355 example, if there are nested `let' forms that bind it). In such a
356 case, the most recently created local binding that still exists is the
357 "current binding" of the variable. (This is called "dynamic scoping";
358 see *Note Variable Scoping::.) If there are no local bindings, the
359 variable's global binding is its current binding. We also call the
360 current binding the "most-local existing binding", for emphasis.
361 Ordinary evaluation of a symbol always returns the value of its current
364 The special forms `let' and `let*' exist to create local bindings.
366 - Special Form: let (bindings...) forms...
367 This special form binds variables according to BINDINGS and then
368 evaluates all of the FORMS in textual order. The `let'-form
369 returns the value of the last form in FORMS.
371 Each of the BINDINGS is either (i) a symbol, in which case that
372 symbol is bound to `nil'; or (ii) a list of the form `(SYMBOL
373 VALUE-FORM)', in which case SYMBOL is bound to the result of
374 evaluating VALUE-FORM. If VALUE-FORM is omitted, `nil' is used.
376 All of the VALUE-FORMs in BINDINGS are evaluated in the order they
377 appear and _before_ any of the symbols are bound. Here is an
378 example of this: `Z' is bound to the old value of `Y', which is 2,
379 not the new value, 1.
388 - Special Form: let* (bindings...) forms...
389 This special form is like `let', but it binds each variable right
390 after computing its local value, before computing the local value
391 for the next variable. Therefore, an expression in BINDINGS can
392 reasonably refer to the preceding symbols bound in this `let*'
393 form. Compare the following example with the example above for
399 (Z Y)) ; Use the just-established value of `Y'.
403 Here is a complete list of the other facilities that create local
406 * Function calls (*note Functions::).
408 * Macro calls (*note Macros::).
410 * `condition-case' (*note Errors::).
412 Variables can also have buffer-local bindings (*note Buffer-Local
413 Variables::). These kinds of bindings work somewhat like ordinary local
414 bindings, but they are localized depending on "where" you are in Emacs,
415 rather than localized in time.
417 - Variable: max-specpdl-size
418 This variable defines the limit on the total number of local
419 variable bindings and `unwind-protect' cleanups (*note Nonlocal
420 Exits::) that are allowed before signaling an error (with data
421 `"Variable binding depth exceeds max-specpdl-size"').
423 This limit, with the associated error when it is exceeded, is one
424 way that Lisp avoids infinite recursion on an ill-defined function.
426 The default value is 600.
428 `max-lisp-eval-depth' provides another limit on depth of nesting.
432 File: lispref.info, Node: Void Variables, Next: Defining Variables, Prev: Local Variables, Up: Variables
434 When a Variable is "Void"
435 =========================
437 If you have never given a symbol any value as a global variable, we
438 say that that symbol's global value is "void". In other words, the
439 symbol's value cell does not have any Lisp object in it. If you try to
440 evaluate the symbol, you get a `void-variable' error rather than a
443 Note that a value of `nil' is not the same as void. The symbol
444 `nil' is a Lisp object and can be the value of a variable just as any
445 other object can be; but it is _a value_. A void variable does not
448 After you have given a variable a value, you can make it void once
449 more using `makunbound'.
451 - Function: makunbound symbol
452 This function makes the current binding of SYMBOL void.
453 Subsequent attempts to use this symbol's value as a variable will
454 signal the error `void-variable', unless or until you set it again.
456 `makunbound' returns SYMBOL.
458 (makunbound 'x) ; Make the global value
462 error--> Symbol's value as variable is void: x
464 If SYMBOL is locally bound, `makunbound' affects the most local
465 existing binding. This is the only way a symbol can have a void
466 local binding, since all the constructs that create local bindings
467 create them with values. In this case, the voidness lasts at most
468 as long as the binding does; when the binding is removed due to
469 exit from the construct that made it, the previous or global
470 binding is reexposed as usual, and the variable is no longer void
471 unless the newly reexposed binding was void all along.
473 (setq x 1) ; Put a value in the global binding.
475 (let ((x 2)) ; Locally bind it.
476 (makunbound 'x) ; Void the local binding.
478 error--> Symbol's value as variable is void: x
479 x ; The global binding is unchanged.
482 (let ((x 2)) ; Locally bind it.
483 (let ((x 3)) ; And again.
484 (makunbound 'x) ; Void the innermost-local binding.
485 x)) ; And refer: it's void.
486 error--> Symbol's value as variable is void: x
490 (makunbound 'x)) ; Void inner binding, then remove it.
491 x) ; Now outer `let' binding is visible.
494 A variable that has been made void with `makunbound' is
495 indistinguishable from one that has never received a value and has
498 You can use the function `boundp' to test whether a variable is
501 - Function: boundp variable
502 `boundp' returns `t' if VARIABLE (a symbol) is not void; more
503 precisely, if its current binding is not void. It returns `nil'
506 (boundp 'abracadabra) ; Starts out void.
508 (let ((abracadabra 5)) ; Locally bind it.
509 (boundp 'abracadabra))
511 (boundp 'abracadabra) ; Still globally void.
513 (setq abracadabra 5) ; Make it globally nonvoid.
515 (boundp 'abracadabra)
519 File: lispref.info, Node: Defining Variables, Next: Accessing Variables, Prev: Void Variables, Up: Variables
521 Defining Global Variables
522 =========================
524 You may announce your intention to use a symbol as a global variable
525 with a "variable definition": a special form, either `defconst' or
528 In XEmacs Lisp, definitions serve three purposes. First, they inform
529 people who read the code that certain symbols are _intended_ to be used
530 a certain way (as variables). Second, they inform the Lisp system of
531 these things, supplying a value and documentation. Third, they provide
532 information to utilities such as `etags' and `make-docfile', which
533 create data bases of the functions and variables in a program.
535 The difference between `defconst' and `defvar' is primarily a matter
536 of intent, serving to inform human readers of whether programs will
537 change the variable. XEmacs Lisp does not restrict the ways in which a
538 variable can be used based on `defconst' or `defvar' declarations.
539 However, it does make a difference for initialization: `defconst'
540 unconditionally initializes the variable, while `defvar' initializes it
543 One would expect user option variables to be defined with
544 `defconst', since programs do not change them. Unfortunately, this has
545 bad results if the definition is in a library that is not preloaded:
546 `defconst' would override any prior value when the library is loaded.
547 Users would like to be able to set user options in their init files,
548 and override the default values given in the definitions. For this
549 reason, user options must be defined with `defvar'.
551 - Special Form: defvar symbol [value [doc-string]]
552 This special form defines SYMBOL as a value and initializes it.
553 The definition informs a person reading your code that SYMBOL is
554 used as a variable that programs are likely to set or change. It
555 is also used for all user option variables except in the preloaded
556 parts of XEmacs. Note that SYMBOL is not evaluated; the symbol to
557 be defined must appear explicitly in the `defvar'.
559 If SYMBOL already has a value (i.e., it is not void), VALUE is not
560 even evaluated, and SYMBOL's value remains unchanged. If SYMBOL
561 is void and VALUE is specified, `defvar' evaluates it and sets
562 SYMBOL to the result. (If VALUE is omitted, the value of SYMBOL
563 is not changed in any case.)
565 When you evaluate a top-level `defvar' form with `C-M-x' in Emacs
566 Lisp mode (`eval-defun'), a special feature of `eval-defun'
567 evaluates it as a `defconst'. The purpose of this is to make sure
568 the variable's value is reinitialized, when you ask for it
571 If SYMBOL has a buffer-local binding in the current buffer,
572 `defvar' sets the default value, not the local value. *Note
573 Buffer-Local Variables::.
575 If the DOC-STRING argument appears, it specifies the documentation
576 for the variable. (This opportunity to specify documentation is
577 one of the main benefits of defining the variable.) The
578 documentation is stored in the symbol's `variable-documentation'
579 property. The XEmacs help functions (*note Documentation::) look
582 If the first character of DOC-STRING is `*', it means that this
583 variable is considered a user option. This lets users set the
584 variable conveniently using the commands `set-variable' and
587 For example, this form defines `foo' but does not set its value:
592 The following example sets the value of `bar' to `23', and gives
593 it a documentation string:
596 "The normal weight of a bar.")
599 The following form changes the documentation string for `bar',
600 making it a user option, but does not change the value, since `bar'
601 already has a value. (The addition `(1+ 23)' is not even
605 "*The normal weight of a bar.")
610 Here is an equivalent expression for the `defvar' special form:
612 (defvar SYMBOL VALUE DOC-STRING)
615 (if (not (boundp 'SYMBOL))
617 (put 'SYMBOL 'variable-documentation 'DOC-STRING)
620 The `defvar' form returns SYMBOL, but it is normally used at top
621 level in a file where its value does not matter.
623 - Special Form: defconst symbol [value [doc-string]]
624 This special form defines SYMBOL as a value and initializes it.
625 It informs a person reading your code that SYMBOL has a global
626 value, established here, that will not normally be changed or
627 locally bound by the execution of the program. The user, however,
628 may be welcome to change it. Note that SYMBOL is not evaluated;
629 the symbol to be defined must appear explicitly in the `defconst'.
631 `defconst' always evaluates VALUE and sets the global value of
632 SYMBOL to the result, provided VALUE is given. If SYMBOL has a
633 buffer-local binding in the current buffer, `defconst' sets the
634 default value, not the local value.
636 *Please note:* Don't use `defconst' for user option variables in
637 libraries that are not standardly preloaded. The user should be
638 able to specify a value for such a variable in the `.emacs' file,
639 so that it will be in effect if and when the library is loaded
642 Here, `pi' is a constant that presumably ought not to be changed
643 by anyone (attempts by the Indiana State Legislature
644 notwithstanding). As the second form illustrates, however, this
647 (defconst pi 3.1415 "Pi to five places.")
654 - Function: user-variable-p variable
655 This function returns `t' if VARIABLE is a user option--a variable
656 intended to be set by the user for customization--and `nil'
657 otherwise. (Variables other than user options exist for the
658 internal purposes of Lisp programs, and users need not know about
661 User option variables are distinguished from other variables by the
662 first character of the `variable-documentation' property. If the
663 property exists and is a string, and its first character is `*',
664 then the variable is a user option.
666 If a user option variable has a `variable-interactive' property, the
667 `set-variable' command uses that value to control reading the new value
668 for the variable. The property's value is used as if it were the
669 argument to `interactive'.
671 *Warning:* If the `defconst' and `defvar' special forms are used
672 while the variable has a local binding, they set the local binding's
673 value; the global binding is not changed. This is not what we really
674 want. To prevent it, use these special forms at top level in a file,
675 where normally no local binding is in effect, and make sure to load the
676 file before making a local binding for the variable.
679 File: lispref.info, Node: Accessing Variables, Next: Setting Variables, Prev: Defining Variables, Up: Variables
681 Accessing Variable Values
682 =========================
684 The usual way to reference a variable is to write the symbol which
685 names it (*note Symbol Forms::). This requires you to specify the
686 variable name when you write the program. Usually that is exactly what
687 you want to do. Occasionally you need to choose at run time which
688 variable to reference; then you can use `symbol-value'.
690 - Function: symbol-value symbol
691 This function returns the value of SYMBOL. This is the value in
692 the innermost local binding of the symbol, or its global value if
693 it has no local bindings.
700 ;; Here the symbol `abracadabra'
701 ;; is the symbol whose value is examined.
702 (let ((abracadabra 'foo))
703 (symbol-value 'abracadabra))
706 ;; Here the value of `abracadabra',
708 ;; is the symbol whose value is examined.
709 (let ((abracadabra 'foo))
710 (symbol-value abracadabra))
713 (symbol-value 'abracadabra)
716 A `void-variable' error is signaled if SYMBOL has neither a local
717 binding nor a global value.
720 File: lispref.info, Node: Setting Variables, Next: Variable Scoping, Prev: Accessing Variables, Up: Variables
722 How to Alter a Variable Value
723 =============================
725 The usual way to change the value of a variable is with the special
726 form `setq'. When you need to compute the choice of variable at run
727 time, use the function `set'.
729 - Special Form: setq [symbol form]...
730 This special form is the most common method of changing a
731 variable's value. Each SYMBOL is given a new value, which is the
732 result of evaluating the corresponding FORM. The most-local
733 existing binding of the symbol is changed.
735 `setq' does not evaluate SYMBOL; it sets the symbol that you
736 write. We say that this argument is "automatically quoted". The
737 `q' in `setq' stands for "quoted."
739 The value of the `setq' form is the value of the last FORM.
743 x ; `x' now has a global value.
746 (setq x 6) ; The local binding of `x' is set.
749 x ; The global value is unchanged.
752 Note that the first FORM is evaluated, then the first SYMBOL is
753 set, then the second FORM is evaluated, then the second SYMBOL is
756 (setq x 10 ; Notice that `x' is set before
757 y (1+ x)) ; the value of `y' is computed.
760 - Function: set symbol value
761 This function sets SYMBOL's value to VALUE, then returns VALUE.
762 Since `set' is a function, the expression written for SYMBOL is
763 evaluated to obtain the symbol to set.
765 The most-local existing binding of the variable is the binding
766 that is set; shadowed bindings are not affected.
769 error--> Symbol's value as variable is void: one
774 (set two 2) ; `two' evaluates to symbol `one'.
776 one ; So it is `one' that was set.
778 (let ((one 1)) ; This binding of `one' is set,
779 (set 'one 3) ; not the global value.
785 If SYMBOL is not actually a symbol, a `wrong-type-argument' error
789 error--> Wrong type argument: symbolp, (x y)
791 Logically speaking, `set' is a more fundamental primitive than
792 `setq'. Any use of `setq' can be trivially rewritten to use
793 `set'; `setq' could even be defined as a macro, given the
794 availability of `set'. However, `set' itself is rarely used;
795 beginners hardly need to know about it. It is useful only for
796 choosing at run time which variable to set. For example, the
797 command `set-variable', which reads a variable name from the user
798 and then sets the variable, needs to use `set'.
800 Common Lisp note: In Common Lisp, `set' always changes the
801 symbol's special value, ignoring any lexical bindings. In
802 XEmacs Lisp, all variables and all bindings are (in effect)
803 special, so `set' always affects the most local existing
806 One other function for setting a variable is designed to add an
807 element to a list if it is not already present in the list.
809 - Function: add-to-list symbol element
810 This function sets the variable SYMBOL by consing ELEMENT onto the
811 old value, if ELEMENT is not already a member of that value. It
812 returns the resulting list, whether updated or not. The value of
813 SYMBOL had better be a list already before the call.
815 The argument SYMBOL is not implicitly quoted; `add-to-list' is an
816 ordinary function, like `set' and unlike `setq'. Quote the
817 argument yourself if that is what you want.
819 Here's a scenario showing how to use `add-to-list':
824 (add-to-list 'foo 'c) ;; Add `c'.
827 (add-to-list 'foo 'b) ;; No effect.
830 foo ;; `foo' was changed.
833 An equivalent expression for `(add-to-list 'VAR VALUE)' is this:
835 (or (member VALUE VAR)
836 (setq VAR (cons VALUE VAR)))
839 File: lispref.info, Node: Variable Scoping, Next: Buffer-Local Variables, Prev: Setting Variables, Up: Variables
841 Scoping Rules for Variable Bindings
842 ===================================
844 A given symbol `foo' may have several local variable bindings,
845 established at different places in the Lisp program, as well as a global
846 binding. The most recently established binding takes precedence over
849 Local bindings in XEmacs Lisp have "indefinite scope" and "dynamic
850 extent". "Scope" refers to _where_ textually in the source code the
851 binding can be accessed. Indefinite scope means that any part of the
852 program can potentially access the variable binding. "Extent" refers
853 to _when_, as the program is executing, the binding exists. Dynamic
854 extent means that the binding lasts as long as the activation of the
855 construct that established it.
857 The combination of dynamic extent and indefinite scope is called
858 "dynamic scoping". By contrast, most programming languages use
859 "lexical scoping", in which references to a local variable must be
860 located textually within the function or block that binds the variable.
862 Common Lisp note: Variables declared "special" in Common Lisp are
863 dynamically scoped, like variables in XEmacs Lisp.
867 * Scope:: Scope means where in the program a value is visible.
868 Comparison with other languages.
869 * Extent:: Extent means how long in time a value exists.
870 * Impl of Scope:: Two ways to implement dynamic scoping.
871 * Using Scoping:: How to use dynamic scoping carefully and avoid problems.
874 File: lispref.info, Node: Scope, Next: Extent, Up: Variable Scoping
879 XEmacs Lisp uses "indefinite scope" for local variable bindings.
880 This means that any function anywhere in the program text might access a
881 given binding of a variable. Consider the following function
884 (defun binder (x) ; `x' is bound in `binder'.
885 (foo 5)) ; `foo' is some other function.
887 (defun user () ; `x' is used in `user'.
890 In a lexically scoped language, the binding of `x' in `binder' would
891 never be accessible in `user', because `user' is not textually
892 contained within the function `binder'. However, in dynamically scoped
893 XEmacs Lisp, `user' may or may not refer to the binding of `x'
894 established in `binder', depending on circumstances:
896 * If we call `user' directly without calling `binder' at all, then
897 whatever binding of `x' is found, it cannot come from `binder'.
899 * If we define `foo' as follows and call `binder', then the binding
900 made in `binder' will be seen in `user':
905 * If we define `foo' as follows and call `binder', then the binding
906 made in `binder' _will not_ be seen in `user':
911 Here, when `foo' is called by `binder', it binds `x'. (The
912 binding in `foo' is said to "shadow" the one made in `binder'.)
913 Therefore, `user' will access the `x' bound by `foo' instead of
914 the one bound by `binder'.
917 File: lispref.info, Node: Extent, Next: Impl of Scope, Prev: Scope, Up: Variable Scoping
922 "Extent" refers to the time during program execution that a variable
923 name is valid. In XEmacs Lisp, a variable is valid only while the form
924 that bound it is executing. This is called "dynamic extent". "Local"
925 or "automatic" variables in most languages, including C and Pascal,
928 One alternative to dynamic extent is "indefinite extent". This
929 means that a variable binding can live on past the exit from the form
930 that made the binding. Common Lisp and Scheme, for example, support
931 this, but XEmacs Lisp does not.
933 To illustrate this, the function below, `make-add', returns a
934 function that purports to add N to its own argument M. This would work
935 in Common Lisp, but it does not work as intended in XEmacs Lisp,
936 because after the call to `make-add' exits, the variable `n' is no
937 longer bound to the actual argument 2.
940 (function (lambda (m) (+ n m)))) ; Return a function.
942 (fset 'add2 (make-add 2)) ; Define function `add2'
943 ; with `(make-add 2)'.
944 => (lambda (m) (+ n m))
945 (add2 4) ; Try to add 2 to 4.
946 error--> Symbol's value as variable is void: n
948 Some Lisp dialects have "closures", objects that are like functions
949 but record additional variable bindings. XEmacs Lisp does not have
953 File: lispref.info, Node: Impl of Scope, Next: Using Scoping, Prev: Extent, Up: Variable Scoping
955 Implementation of Dynamic Scoping
956 ---------------------------------
958 A simple sample implementation (which is not how XEmacs Lisp actually
959 works) may help you understand dynamic binding. This technique is
960 called "deep binding" and was used in early Lisp systems.
962 Suppose there is a stack of bindings: variable-value pairs. At entry
963 to a function or to a `let' form, we can push bindings on the stack for
964 the arguments or local variables created there. We can pop those
965 bindings from the stack at exit from the binding construct.
967 We can find the value of a variable by searching the stack from top
968 to bottom for a binding for that variable; the value from that binding
969 is the value of the variable. To set the variable, we search for the
970 current binding, then store the new value into that binding.
972 As you can see, a function's bindings remain in effect as long as it
973 continues execution, even during its calls to other functions. That is
974 why we say the extent of the binding is dynamic. And any other function
975 can refer to the bindings, if it uses the same variables while the
976 bindings are in effect. That is why we say the scope is indefinite.
978 The actual implementation of variable scoping in XEmacs Lisp uses a
979 technique called "shallow binding". Each variable has a standard place
980 in which its current value is always found--the value cell of the
983 In shallow binding, setting the variable works by storing a value in
984 the value cell. Creating a new binding works by pushing the old value
985 (belonging to a previous binding) on a stack, and storing the local
986 value in the value cell. Eliminating a binding works by popping the
987 old value off the stack, into the value cell.
989 We use shallow binding because it has the same results as deep
990 binding, but runs faster, since there is never a need to search for a
994 File: lispref.info, Node: Using Scoping, Prev: Impl of Scope, Up: Variable Scoping
996 Proper Use of Dynamic Scoping
997 -----------------------------
999 Binding a variable in one function and using it in another is a
1000 powerful technique, but if used without restraint, it can make programs
1001 hard to understand. There are two clean ways to use this technique:
1003 * Use or bind the variable only in a few related functions, written
1004 close together in one file. Such a variable is used for
1005 communication within one program.
1007 You should write comments to inform other programmers that they
1008 can see all uses of the variable before them, and to advise them
1009 not to add uses elsewhere.
1011 * Give the variable a well-defined, documented meaning, and make all
1012 appropriate functions refer to it (but not bind it or set it)
1013 wherever that meaning is relevant. For example, the variable
1014 `case-fold-search' is defined as "non-`nil' means ignore case when
1015 searching"; various search and replace functions refer to it
1016 directly or through their subroutines, but do not bind or set it.
1018 Then you can bind the variable in other programs, knowing reliably
1019 what the effect will be.
1021 In either case, you should define the variable with `defvar'. This
1022 helps other people understand your program by telling them to look for
1023 inter-function usage. It also avoids a warning from the byte compiler.
1024 Choose the variable's name to avoid name conflicts--don't use short
1028 File: lispref.info, Node: Buffer-Local Variables, Next: Variable Aliases, Prev: Variable Scoping, Up: Variables
1030 Buffer-Local Variables
1031 ======================
1033 Global and local variable bindings are found in most programming
1034 languages in one form or another. XEmacs also supports another, unusual
1035 kind of variable binding: "buffer-local" bindings, which apply only to
1036 one buffer. XEmacs Lisp is meant for programming editing commands, and
1037 having different values for a variable in different buffers is an
1038 important customization method.
1042 * Intro to Buffer-Local:: Introduction and concepts.
1043 * Creating Buffer-Local:: Creating and destroying buffer-local bindings.
1044 * Default Value:: The default value is seen in buffers
1045 that don't have their own local values.
1048 File: lispref.info, Node: Intro to Buffer-Local, Next: Creating Buffer-Local, Up: Buffer-Local Variables
1050 Introduction to Buffer-Local Variables
1051 --------------------------------------
1053 A buffer-local variable has a buffer-local binding associated with a
1054 particular buffer. The binding is in effect when that buffer is
1055 current; otherwise, it is not in effect. If you set the variable while
1056 a buffer-local binding is in effect, the new value goes in that binding,
1057 so the global binding is unchanged; this means that the change is
1058 visible in that buffer alone.
1060 A variable may have buffer-local bindings in some buffers but not in
1061 others. The global binding is shared by all the buffers that don't have
1062 their own bindings. Thus, if you set the variable in a buffer that does
1063 not have a buffer-local binding for it, the new value is visible in all
1064 buffers except those with buffer-local bindings. (Here we are assuming
1065 that there are no `let'-style local bindings to complicate the issue.)
1067 The most common use of buffer-local bindings is for major modes to
1068 change variables that control the behavior of commands. For example, C
1069 mode and Lisp mode both set the variable `paragraph-start' to specify
1070 that only blank lines separate paragraphs. They do this by making the
1071 variable buffer-local in the buffer that is being put into C mode or
1072 Lisp mode, and then setting it to the new value for that mode.
1074 The usual way to make a buffer-local binding is with
1075 `make-local-variable', which is what major mode commands use. This
1076 affects just the current buffer; all other buffers (including those yet
1077 to be created) continue to share the global value.
1079 A more powerful operation is to mark the variable as "automatically
1080 buffer-local" by calling `make-variable-buffer-local'. You can think
1081 of this as making the variable local in all buffers, even those yet to
1082 be created. More precisely, the effect is that setting the variable
1083 automatically makes the variable local to the current buffer if it is
1084 not already so. All buffers start out by sharing the global value of
1085 the variable as usual, but any `setq' creates a buffer-local binding
1086 for the current buffer. The new value is stored in the buffer-local
1087 binding, leaving the (default) global binding untouched. The global
1088 value can no longer be changed with `setq'; you need to use
1089 `setq-default' to do that.
1091 Local variables in a file you edit are also represented by
1092 buffer-local bindings for the buffer that holds the file within XEmacs.
1093 *Note Auto Major Mode::.
1096 File: lispref.info, Node: Creating Buffer-Local, Next: Default Value, Prev: Intro to Buffer-Local, Up: Buffer-Local Variables
1098 Creating and Deleting Buffer-Local Bindings
1099 -------------------------------------------
1101 - Command: make-local-variable variable
1102 This function creates a buffer-local binding in the current buffer
1103 for VARIABLE (a symbol). Other buffers are not affected. The
1104 value returned is VARIABLE.
1106 The buffer-local value of VARIABLE starts out as the same value
1107 VARIABLE previously had. If VARIABLE was void, it remains void.
1110 (setq foo 5) ; Affects all buffers.
1112 (make-local-variable 'foo) ; Now it is local in `b1'.
1114 foo ; That did not change
1116 (setq foo 6) ; Change the value
1121 ;; In buffer `b2', the value hasn't changed.
1127 Making a variable buffer-local within a `let'-binding for that
1128 variable does not work. This is because `let' does not distinguish
1129 between different kinds of bindings; it knows only which variable
1130 the binding was made for.
1132 *Please note:* do not use `make-local-variable' for a hook
1133 variable. Instead, use `make-local-hook'. *Note Hooks::.
1135 - Command: make-variable-buffer-local variable
1136 This function marks VARIABLE (a symbol) automatically
1137 buffer-local, so that any subsequent attempt to set it will make it
1138 local to the current buffer at the time.
1140 The value returned is VARIABLE.
1142 - Function: local-variable-p variable &optional buffer
1143 This returns `t' if VARIABLE is buffer-local in buffer BUFFER
1144 (which defaults to the current buffer); otherwise, `nil'.
1146 - Function: buffer-local-variables &optional buffer
1147 This function returns a list describing the buffer-local variables
1148 in buffer BUFFER. It returns an association list (*note
1149 Association Lists::) in which each association contains one
1150 buffer-local variable and its value. When a buffer-local variable
1151 is void in BUFFER, then it appears directly in the resulting list.
1152 If BUFFER is omitted, the current buffer is used.
1154 (make-local-variable 'foobar)
1155 (makunbound 'foobar)
1156 (make-local-variable 'bind-me)
1158 (setq lcl (buffer-local-variables))
1159 ;; First, built-in variables local in all buffers:
1160 => ((mark-active . nil)
1161 (buffer-undo-list nil)
1162 (mode-name . "Fundamental")
1164 ;; Next, non-built-in local variables.
1165 ;; This one is local and void:
1167 ;; This one is local and nonvoid:
1170 Note that storing new values into the CDRs of cons cells in this
1171 list does _not_ change the local values of the variables.
1173 - Command: kill-local-variable variable
1174 This function deletes the buffer-local binding (if any) for
1175 VARIABLE (a symbol) in the current buffer. As a result, the
1176 global (default) binding of VARIABLE becomes visible in this
1177 buffer. Usually this results in a change in the value of
1178 VARIABLE, since the global value is usually different from the
1179 buffer-local value just eliminated.
1181 If you kill the local binding of a variable that automatically
1182 becomes local when set, this makes the global value visible in the
1183 current buffer. However, if you set the variable again, that will
1184 once again create a local binding for it.
1186 `kill-local-variable' returns VARIABLE.
1188 This function is a command because it is sometimes useful to kill
1189 one buffer-local variable interactively, just as it is useful to
1190 create buffer-local variables interactively.
1192 - Function: kill-all-local-variables
1193 This function eliminates all the buffer-local variable bindings of
1194 the current buffer except for variables marked as "permanent". As
1195 a result, the buffer will see the default values of most variables.
1197 This function also resets certain other information pertaining to
1198 the buffer: it sets the local keymap to `nil', the syntax table to
1199 the value of `standard-syntax-table', and the abbrev table to the
1200 value of `fundamental-mode-abbrev-table'.
1202 Every major mode command begins by calling this function, which
1203 has the effect of switching to Fundamental mode and erasing most
1204 of the effects of the previous major mode. To ensure that this
1205 does its job, the variables that major modes set should not be
1208 `kill-all-local-variables' returns `nil'.
1210 A local variable is "permanent" if the variable name (a symbol) has a
1211 `permanent-local' property that is non-`nil'. Permanent locals are
1212 appropriate for data pertaining to where the file came from or how to
1213 save it, rather than with how to edit the contents.