XEmacs 21.4.15
[chise/xemacs-chise.git.1] / info / lispref.info-2
1 This is ../info/lispref.info, produced by makeinfo version 4.6 from
2 lispref/lispref.texi.
3
4 INFO-DIR-SECTION XEmacs Editor
5 START-INFO-DIR-ENTRY
6 * Lispref: (lispref).           XEmacs Lisp Reference Manual.
7 END-INFO-DIR-ENTRY
8
9    Edition History:
10
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
20
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.
24
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.
28
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.
33
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.
38
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.
45
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.
51
52 \1f
53 File: lispref.info,  Node: List Elements,  Next: Building Lists,  Prev: List-related Predicates,  Up: Lists
54
55 Accessing Elements of Lists
56 ===========================
57
58  - Function: car cons-cell
59      This function returns the value pointed to by the first pointer of
60      the cons cell CONS-CELL.  Expressed another way, this function
61      returns the CAR of CONS-CELL.
62
63      As a special case, if CONS-CELL is `nil', then `car' is defined to
64      return `nil'; therefore, any list is a valid argument for `car'.
65      An error is signaled if the argument is not a cons cell or `nil'.
66
67           (car '(a b c))
68                => a
69           (car '())
70                => nil
71
72  - Function: cdr cons-cell
73      This function returns the value pointed to by the second pointer of
74      the cons cell CONS-CELL.  Expressed another way, this function
75      returns the CDR of CONS-CELL.
76
77      As a special case, if CONS-CELL is `nil', then `cdr' is defined to
78      return `nil'; therefore, any list is a valid argument for `cdr'.
79      An error is signaled if the argument is not a cons cell or `nil'.
80
81           (cdr '(a b c))
82                => (b c)
83           (cdr '())
84                => nil
85
86  - Function: car-safe object
87      This function lets you take the CAR of a cons cell while avoiding
88      errors for other data types.  It returns the CAR of OBJECT if
89      OBJECT is a cons cell, `nil' otherwise.  This is in contrast to
90      `car', which signals an error if OBJECT is not a list.
91
92           (car-safe OBJECT)
93           ==
94           (let ((x OBJECT))
95             (if (consp x)
96                 (car x)
97               nil))
98
99  - Function: cdr-safe object
100      This function lets you take the CDR of a cons cell while avoiding
101      errors for other data types.  It returns the CDR of OBJECT if
102      OBJECT is a cons cell, `nil' otherwise.  This is in contrast to
103      `cdr', which signals an error if OBJECT is not a list.
104
105           (cdr-safe OBJECT)
106           ==
107           (let ((x OBJECT))
108             (if (consp x)
109                 (cdr x)
110               nil))
111
112  - Function: nth n list
113      This function returns the Nth element of LIST.  Elements are
114      numbered starting with zero, so the CAR of LIST is element number
115      zero.  If the length of LIST is N or less, the value is `nil'.
116
117      If N is negative, `nth' returns the first element of LIST.
118
119           (nth 2 '(1 2 3 4))
120                => 3
121           (nth 10 '(1 2 3 4))
122                => nil
123           (nth -3 '(1 2 3 4))
124                => 1
125           
126           (nth n x) == (car (nthcdr n x))
127
128  - Function: nthcdr n list
129      This function returns the Nth CDR of LIST.  In other words, it
130      removes the first N links of LIST and returns what follows.
131
132      If N is zero or negative, `nthcdr' returns all of LIST.  If the
133      length of LIST is N or less, `nthcdr' returns `nil'.
134
135           (nthcdr 1 '(1 2 3 4))
136                => (2 3 4)
137           (nthcdr 10 '(1 2 3 4))
138                => nil
139           (nthcdr -3 '(1 2 3 4))
140                => (1 2 3 4)
141
142 Many convenience functions are provided to make it easier for you to
143 access particular elements in a nested list.  All of these can be
144 rewritten in terms of the functions just described.
145
146  - Function: caar cons-cell
147  - Function: cadr cons-cell
148  - Function: cdar cons-cell
149  - Function: cddr cons-cell
150  - Function: caaar cons-cell
151  - Function: caadr cons-cell
152  - Function: cadar cons-cell
153  - Function: caddr cons-cell
154  - Function: cdaar cons-cell
155  - Function: cdadr cons-cell
156  - Function: cddar cons-cell
157  - Function: cdddr cons-cell
158  - Function: caaaar cons-cell
159  - Function: caaadr cons-cell
160  - Function: caadar cons-cell
161  - Function: caaddr cons-cell
162  - Function: cadaar cons-cell
163  - Function: cadadr cons-cell
164  - Function: caddar cons-cell
165  - Function: cadddr cons-cell
166  - Function: cdaaar cons-cell
167  - Function: cdaadr cons-cell
168  - Function: cdadar cons-cell
169  - Function: cdaddr cons-cell
170  - Function: cddaar cons-cell
171  - Function: cddadr cons-cell
172  - Function: cdddar cons-cell
173  - Function: cddddr cons-cell
174      Each of these functions is equivalent to one or more applications
175      of `car' and/or `cdr'.  For example,
176
177           (cadr x)
178
179      is equivalent to
180
181           (car (cdr x))
182
183      and
184
185           (cdaddr x)
186
187      is equivalent to
188
189           (cdr (car (cdr (cdr x))))
190
191      That is to say, read the a's and d's from right to left and apply
192      a `car' or `cdr' for each a or d found, respectively.
193
194  - Function: first list
195      This is equivalent to `(nth 0 LIST)', i.e. the first element of
196      LIST. (Note that this is also equivalent to `car'.)
197
198  - Function: second list
199      This is equivalent to `(nth 1 LIST)', i.e. the second element of
200      LIST.
201
202  - Function: third list
203  - Function: fourth list
204  - Function: fifth list
205  - Function: sixth list
206  - Function: seventh list
207  - Function: eighth list
208  - Function: ninth list
209  - Function: tenth list
210      These are equivalent to `(nth 2 LIST)' through `(nth 9 LIST)'
211      respectively, i.e. the third through tenth elements of LIST.
212
213 \1f
214 File: lispref.info,  Node: Building Lists,  Next: Modifying Lists,  Prev: List Elements,  Up: Lists
215
216 Building Cons Cells and Lists
217 =============================
218
219 Many functions build lists, as lists reside at the very heart of Lisp.
220 `cons' is the fundamental list-building function; however, it is
221 interesting to note that `list' is used more times in the source code
222 for Emacs than `cons'.
223
224  - Function: cons object1 object2
225      This function is the fundamental function used to build new list
226      structure.  It creates a new cons cell, making OBJECT1 the CAR,
227      and OBJECT2 the CDR.  It then returns the new cons cell.  The
228      arguments OBJECT1 and OBJECT2 may be any Lisp objects, but most
229      often OBJECT2 is a list.
230
231           (cons 1 '(2))
232                => (1 2)
233           (cons 1 '())
234                => (1)
235           (cons 1 2)
236                => (1 . 2)
237
238      `cons' is often used to add a single element to the front of a
239      list.  This is called "consing the element onto the list".  For
240      example:
241
242           (setq list (cons newelt list))
243
244      Note that there is no conflict between the variable named `list'
245      used in this example and the function named `list' described below;
246      any symbol can serve both purposes.
247
248  - Function: list &rest objects
249      This function creates a list with OBJECTS as its elements.  The
250      resulting list is always `nil'-terminated.  If no OBJECTS are
251      given, the empty list is returned.
252
253           (list 1 2 3 4 5)
254                => (1 2 3 4 5)
255           (list 1 2 '(3 4 5) 'foo)
256                => (1 2 (3 4 5) foo)
257           (list)
258                => nil
259
260  - Function: make-list length object
261      This function creates a list of length LENGTH, in which all the
262      elements have the identical value OBJECT.  Compare `make-list'
263      with `make-string' (*note Creating Strings::).
264
265           (make-list 3 'pigs)
266                => (pigs pigs pigs)
267           (make-list 0 'pigs)
268                => nil
269
270  - Function: append &rest sequences
271      This function returns a list containing all the elements of
272      SEQUENCES.  The SEQUENCES may be lists, vectors, or strings, but
273      the last one should be a list.  All arguments except the last one
274      are copied, so none of them are altered.
275
276      More generally, the final argument to `append' may be any Lisp
277      object.  The final argument is not copied or converted; it becomes
278      the CDR of the last cons cell in the new list.  If the final
279      argument is itself a list, then its elements become in effect
280      elements of the result list.  If the final element is not a list,
281      the result is a "dotted list" since its final CDR is not `nil' as
282      required in a true list.
283
284      See `nconc' in *Note Rearrangement::, for a way to join lists with
285      no copying.
286
287      Here is an example of using `append':
288
289           (setq trees '(pine oak))
290                => (pine oak)
291           (setq more-trees (append '(maple birch) trees))
292                => (maple birch pine oak)
293           
294           trees
295                => (pine oak)
296           more-trees
297                => (maple birch pine oak)
298           (eq trees (cdr (cdr more-trees)))
299                => t
300
301      You can see how `append' works by looking at a box diagram.  The
302      variable `trees' is set to the list `(pine oak)' and then the
303      variable `more-trees' is set to the list `(maple birch pine oak)'.
304      However, the variable `trees' continues to refer to the original
305      list:
306
307           more-trees                trees
308           |                           |
309           |     ___ ___      ___ ___   -> ___ ___      ___ ___
310            --> |___|___|--> |___|___|--> |___|___|--> |___|___|--> nil
311                  |            |            |            |
312                  |            |            |            |
313                   --> maple    -->birch     --> pine     --> oak
314
315      An empty sequence contributes nothing to the value returned by
316      `append'.  As a consequence of this, a final `nil' argument forces
317      a copy of the previous argument.
318
319           trees
320                => (pine oak)
321           (setq wood (append trees ()))
322                => (pine oak)
323           wood
324                => (pine oak)
325           (eq wood trees)
326                => nil
327
328      This once was the usual way to copy a list, before the function
329      `copy-sequence' was invented.  *Note Sequences Arrays Vectors::.
330
331      With the help of `apply', we can append all the lists in a list of
332      lists:
333
334           (apply 'append '((a b c) nil (x y z) nil))
335                => (a b c x y z)
336
337      If no SEQUENCES are given, `nil' is returned:
338
339           (append)
340                => nil
341
342      Here are some examples where the final argument is not a list:
343
344           (append '(x y) 'z)
345                => (x y . z)
346           (append '(x y) [z])
347                => (x y . [z])
348
349      The second example shows that when the final argument is a
350      sequence but not a list, the sequence's elements do not become
351      elements of the resulting list.  Instead, the sequence becomes the
352      final CDR, like any other non-list final argument.
353
354      The `append' function also allows integers as arguments.  It
355      converts them to strings of digits, making up the decimal print
356      representation of the integer, and then uses the strings instead
357      of the original integers.  *Don't use this feature; we plan to
358      eliminate it.  If you already use this feature, change your
359      programs now!*  The proper way to convert an integer to a decimal
360      number in this way is with `format' (*note Formatting Strings::)
361      or `number-to-string' (*note String Conversion::).
362
363  - Function: reverse list
364      This function creates a new list whose elements are the elements of
365      LIST, but in reverse order.  The original argument LIST is _not_
366      altered.
367
368           (setq x '(1 2 3 4))
369                => (1 2 3 4)
370           (reverse x)
371                => (4 3 2 1)
372           x
373                => (1 2 3 4)
374
375 \1f
376 File: lispref.info,  Node: Modifying Lists,  Next: Sets And Lists,  Prev: Building Lists,  Up: Lists
377
378 Modifying Existing List Structure
379 =================================
380
381 You can modify the CAR and CDR contents of a cons cell with the
382 primitives `setcar' and `setcdr'.
383
384      Common Lisp note: Common Lisp uses functions `rplaca' and `rplacd'
385      to alter list structure; they change structure the same way as
386      `setcar' and `setcdr', but the Common Lisp functions return the
387      cons cell while `setcar' and `setcdr' return the new CAR or CDR.
388
389 * Menu:
390
391 * Setcar::          Replacing an element in a list.
392 * Setcdr::          Replacing part of the list backbone.
393                       This can be used to remove or add elements.
394 * Rearrangement::   Reordering the elements in a list; combining lists.
395
396 \1f
397 File: lispref.info,  Node: Setcar,  Next: Setcdr,  Up: Modifying Lists
398
399 Altering List Elements with `setcar'
400 ------------------------------------
401
402 Changing the CAR of a cons cell is done with `setcar'.  When used on a
403 list, `setcar' replaces one element of a list with a different element.
404
405  - Function: setcar cons-cell object
406      This function stores OBJECT as the new CAR of CONS-CELL, replacing
407      its previous CAR.  It returns the value OBJECT.  For example:
408
409           (setq x '(1 2))
410                => (1 2)
411           (setcar x 4)
412                => 4
413           x
414                => (4 2)
415
416    When a cons cell is part of the shared structure of several lists,
417 storing a new CAR into the cons changes one element of each of these
418 lists.  Here is an example:
419
420      ;; Create two lists that are partly shared.
421      (setq x1 '(a b c))
422           => (a b c)
423      (setq x2 (cons 'z (cdr x1)))
424           => (z b c)
425      
426      ;; Replace the CAR of a shared link.
427      (setcar (cdr x1) 'foo)
428           => foo
429      x1                           ; Both lists are changed.
430           => (a foo c)
431      x2
432           => (z foo c)
433      
434      ;; Replace the CAR of a link that is not shared.
435      (setcar x1 'baz)
436           => baz
437      x1                           ; Only one list is changed.
438           => (baz foo c)
439      x2
440           => (z foo c)
441
442    Here is a graphical depiction of the shared structure of the two
443 lists in the variables `x1' and `x2', showing why replacing `b' changes
444 them both:
445
446              ___ ___        ___ ___      ___ ___
447      x1---> |___|___|----> |___|___|--> |___|___|--> nil
448               |        -->   |            |
449               |       |      |            |
450                --> a  |       --> b        --> c
451                       |
452             ___ ___   |
453      x2--> |___|___|--
454              |
455              |
456               --> z
457
458    Here is an alternative form of box diagram, showing the same
459 relationship:
460
461      x1:
462       --------------       --------------       --------------
463      | car   | cdr  |     | car   | cdr  |     | car   | cdr  |
464      |   a   |   o------->|   b   |   o------->|   c   |  nil |
465      |       |      |  -->|       |      |     |       |      |
466       --------------  |    --------------       --------------
467                       |
468      x2:              |
469       --------------  |
470      | car   | cdr  | |
471      |   z   |   o----
472      |       |      |
473       --------------
474
475 \1f
476 File: lispref.info,  Node: Setcdr,  Next: Rearrangement,  Prev: Setcar,  Up: Modifying Lists
477
478 Altering the CDR of a List
479 --------------------------
480
481 The lowest-level primitive for modifying a CDR is `setcdr':
482
483  - Function: setcdr cons-cell object
484      This function stores OBJECT as the new CDR of CONS-CELL, replacing
485      its previous CDR.  It returns the value OBJECT.
486
487    Here is an example of replacing the CDR of a list with a different
488 list.  All but the first element of the list are removed in favor of a
489 different sequence of elements.  The first element is unchanged,
490 because it resides in the CAR of the list, and is not reached via the
491 CDR.
492
493      (setq x '(1 2 3))
494           => (1 2 3)
495      (setcdr x '(4))
496           => (4)
497      x
498           => (1 4)
499
500    You can delete elements from the middle of a list by altering the
501 CDRs of the cons cells in the list.  For example, here we delete the
502 second element, `b', from the list `(a b c)', by changing the CDR of
503 the first cell:
504
505      (setq x1 '(a b c))
506           => (a b c)
507      (setcdr x1 (cdr (cdr x1)))
508           => (c)
509      x1
510           => (a c)
511
512    Here is the result in box notation:
513
514                         --------------------
515                        |                    |
516       --------------   |   --------------   |    --------------
517      | car   | cdr  |  |  | car   | cdr  |   -->| car   | cdr  |
518      |   a   |   o-----   |   b   |   o-------->|   c   |  nil |
519      |       |      |     |       |      |      |       |      |
520       --------------       --------------        --------------
521
522 The second cons cell, which previously held the element `b', still
523 exists and its CAR is still `b', but it no longer forms part of this
524 list.
525
526    It is equally easy to insert a new element by changing CDRs:
527
528      (setq x1 '(a b c))
529           => (a b c)
530      (setcdr x1 (cons 'd (cdr x1)))
531           => (d b c)
532      x1
533           => (a d b c)
534
535    Here is this result in box notation:
536
537       --------------        -------------       -------------
538      | car  | cdr   |      | car  | cdr  |     | car  | cdr  |
539      |   a  |   o   |   -->|   b  |   o------->|   c  |  nil |
540      |      |   |   |  |   |      |      |     |      |      |
541       --------- | --   |    -------------       -------------
542                 |      |
543           -----         --------
544          |                      |
545          |    ---------------   |
546          |   | car   | cdr   |  |
547           -->|   d   |   o------
548              |       |       |
549               ---------------
550
551 \1f
552 File: lispref.info,  Node: Rearrangement,  Prev: Setcdr,  Up: Modifying Lists
553
554 Functions that Rearrange Lists
555 ------------------------------
556
557 Here are some functions that rearrange lists "destructively" by
558 modifying the CDRs of their component cons cells.  We call these
559 functions "destructive" because they chew up the original lists passed
560 to them as arguments, to produce a new list that is the returned value.
561
562    See `delq', in *Note Sets And Lists::, for another function that
563 modifies cons cells.
564
565  - Function: nconc &rest lists
566      This function returns a list containing all the elements of LISTS.
567      Unlike `append' (*note Building Lists::), the LISTS are _not_
568      copied.  Instead, the last CDR of each of the LISTS is changed to
569      refer to the following list.  The last of the LISTS is not
570      altered.  For example:
571
572           (setq x '(1 2 3))
573                => (1 2 3)
574           (nconc x '(4 5))
575                => (1 2 3 4 5)
576           x
577                => (1 2 3 4 5)
578
579      Since the last argument of `nconc' is not itself modified, it is
580      reasonable to use a constant list, such as `'(4 5)', as in the
581      above example.  For the same reason, the last argument need not be
582      a list:
583
584           (setq x '(1 2 3))
585                => (1 2 3)
586           (nconc x 'z)
587                => (1 2 3 . z)
588           x
589                => (1 2 3 . z)
590
591      A common pitfall is to use a quoted constant list as a non-last
592      argument to `nconc'.  If you do this, your program will change
593      each time you run it!  Here is what happens:
594
595           (defun add-foo (x)            ; We want this function to add
596             (nconc '(foo) x))           ;   `foo' to the front of its arg.
597           
598           (symbol-function 'add-foo)
599                => (lambda (x) (nconc (quote (foo)) x))
600           
601           (setq xx (add-foo '(1 2)))    ; It seems to work.
602                => (foo 1 2)
603           (setq xy (add-foo '(3 4)))    ; What happened?
604                => (foo 1 2 3 4)
605           (eq xx xy)
606                => t
607           
608           (symbol-function 'add-foo)
609                => (lambda (x) (nconc (quote (foo 1 2 3 4) x)))
610
611  - Function: nreverse list
612      This function reverses the order of the elements of LIST.  Unlike
613      `reverse', `nreverse' alters its argument by reversing the CDRs in
614      the cons cells forming the list.  The cons cell that used to be
615      the last one in LIST becomes the first cell of the value.
616
617      For example:
618
619           (setq x '(1 2 3 4))
620                => (1 2 3 4)
621           x
622                => (1 2 3 4)
623           (nreverse x)
624                => (4 3 2 1)
625           ;; The cell that was first is now last.
626           x
627                => (1)
628
629      To avoid confusion, we usually store the result of `nreverse' back
630      in the same variable which held the original list:
631
632           (setq x (nreverse x))
633
634      Here is the `nreverse' of our favorite example, `(a b c)',
635      presented graphically:
636
637           Original list head:                       Reversed list:
638            -------------        -------------        ------------
639           | car  | cdr  |      | car  | cdr  |      | car | cdr  |
640           |   a  |  nil |<--   |   b  |   o  |<--   |   c |   o  |
641           |      |      |   |  |      |   |  |   |  |     |   |  |
642            -------------    |   --------- | -    |   -------- | -
643                             |             |      |            |
644                              -------------        ------------
645
646  - Function: sort list predicate
647      This function sorts LIST stably, though destructively, and returns
648      the sorted list.  It compares elements using PREDICATE.  A stable
649      sort is one in which elements with equal sort keys maintain their
650      relative order before and after the sort.  Stability is important
651      when successive sorts are used to order elements according to
652      different criteria.
653
654      The argument PREDICATE must be a function that accepts two
655      arguments.  It is called with two elements of LIST.  To get an
656      increasing order sort, the PREDICATE should return `t' if the
657      first element is "less than" the second, or `nil' if not.
658
659      The destructive aspect of `sort' is that it rearranges the cons
660      cells forming LIST by changing CDRs.  A nondestructive sort
661      function would create new cons cells to store the elements in their
662      sorted order.  If you wish to make a sorted copy without
663      destroying the original, copy it first with `copy-sequence' and
664      then sort.
665
666      Sorting does not change the CARs of the cons cells in LIST; the
667      cons cell that originally contained the element `a' in LIST still
668      has `a' in its CAR after sorting, but it now appears in a
669      different position in the list due to the change of CDRs.  For
670      example:
671
672           (setq nums '(1 3 2 6 5 4 0))
673                => (1 3 2 6 5 4 0)
674           (sort nums '<)
675                => (0 1 2 3 4 5 6)
676           nums
677                => (1 2 3 4 5 6)
678
679      Note that the list in `nums' no longer contains 0; this is the same
680      cons cell that it was before, but it is no longer the first one in
681      the list.  Don't assume a variable that formerly held the argument
682      now holds the entire sorted list!  Instead, save the result of
683      `sort' and use that.  Most often we store the result back into the
684      variable that held the original list:
685
686           (setq nums (sort nums '<))
687
688      *Note Sorting::, for more functions that perform sorting.  See
689      `documentation' in *Note Accessing Documentation::, for a useful
690      example of `sort'.
691
692 \1f
693 File: lispref.info,  Node: Sets And Lists,  Next: Association Lists,  Prev: Modifying Lists,  Up: Lists
694
695 Using Lists as Sets
696 ===================
697
698 A list can represent an unordered mathematical set--simply consider a
699 value an element of a set if it appears in the list, and ignore the
700 order of the list.  To form the union of two sets, use `append' (as
701 long as you don't mind having duplicate elements).  Other useful
702 functions for sets include `memq' and `delq', and their `equal'
703 versions, `member' and `delete'.
704
705      Common Lisp note: Common Lisp has functions `union' (which avoids
706      duplicate elements) and `intersection' for set operations, but
707      XEmacs Lisp does not have them.  You can write them in Lisp if you
708      wish.
709
710  - Function: memq object list
711      This function tests to see whether OBJECT is a member of LIST.  If
712      it is, `memq' returns a list starting with the first occurrence of
713      OBJECT.  Otherwise, it returns `nil'.  The letter `q' in `memq'
714      says that it uses `eq' to compare OBJECT against the elements of
715      the list.  For example:
716
717           (memq 'b '(a b c b a))
718                => (b c b a)
719           (memq '(2) '((1) (2)))    ; `(2)' and `(2)' are not `eq'.
720                => nil
721
722  - Function: delq object list
723      This function destructively removes all elements `eq' to OBJECT
724      from LIST.  The letter `q' in `delq' says that it uses `eq' to
725      compare OBJECT against the elements of the list, like `memq'.
726
727    When `delq' deletes elements from the front of the list, it does so
728 simply by advancing down the list and returning a sublist that starts
729 after those elements:
730
731      (delq 'a '(a b c)) == (cdr '(a b c))
732
733    When an element to be deleted appears in the middle of the list,
734 removing it involves changing the CDRs (*note Setcdr::).
735
736      (setq sample-list '(a b c (4)))
737           => (a b c (4))
738      (delq 'a sample-list)
739           => (b c (4))
740      sample-list
741           => (a b c (4))
742      (delq 'c sample-list)
743           => (a b (4))
744      sample-list
745           => (a b (4))
746
747    Note that `(delq 'c sample-list)' modifies `sample-list' to splice
748 out the third element, but `(delq 'a sample-list)' does not splice
749 anything--it just returns a shorter list.  Don't assume that a variable
750 which formerly held the argument LIST now has fewer elements, or that
751 it still holds the original list!  Instead, save the result of `delq'
752 and use that.  Most often we store the result back into the variable
753 that held the original list:
754
755      (setq flowers (delq 'rose flowers))
756
757    In the following example, the `(4)' that `delq' attempts to match
758 and the `(4)' in the `sample-list' are not `eq':
759
760      (delq '(4) sample-list)
761           => (a c (4))
762
763    The following two functions are like `memq' and `delq' but use
764 `equal' rather than `eq' to compare elements.  They are new in Emacs 19.
765
766  - Function: member object list
767      The function `member' tests to see whether OBJECT is a member of
768      LIST, comparing members with OBJECT using `equal'.  If OBJECT is a
769      member, `member' returns a list starting with its first occurrence
770      in LIST.  Otherwise, it returns `nil'.
771
772      Compare this with `memq':
773
774           (member '(2) '((1) (2)))  ; `(2)' and `(2)' are `equal'.
775                => ((2))
776           (memq '(2) '((1) (2)))    ; `(2)' and `(2)' are not `eq'.
777                => nil
778           ;; Two strings with the same contents are `equal'.
779           (member "foo" '("foo" "bar"))
780                => ("foo" "bar")
781
782  - Function: delete object list
783      This function destructively removes all elements `equal' to OBJECT
784      from LIST.  It is to `delq' as `member' is to `memq': it uses
785      `equal' to compare elements with OBJECT, like `member'; when it
786      finds an element that matches, it removes the element just as
787      `delq' would.  For example:
788
789           (delete '(2) '((2) (1) (2)))
790                => '((1))
791
792      Common Lisp note: The functions `member' and `delete' in XEmacs
793      Lisp are derived from Maclisp, not Common Lisp.  The Common Lisp
794      versions do not use `equal' to compare elements.
795
796    See also the function `add-to-list', in *Note Setting Variables::,
797 for another way to add an element to a list stored in a variable.
798
799 \1f
800 File: lispref.info,  Node: Association Lists,  Next: Property Lists,  Prev: Sets And Lists,  Up: Lists
801
802 Association Lists
803 =================
804
805 An "association list", or "alist" for short, records a mapping from
806 keys to values.  It is a list of cons cells called "associations": the
807 CAR of each cell is the "key", and the CDR is the "associated value".(1)
808
809    Here is an example of an alist.  The key `pine' is associated with
810 the value `cones'; the key `oak' is associated with `acorns'; and the
811 key `maple' is associated with `seeds'.
812
813      '((pine . cones)
814        (oak . acorns)
815        (maple . seeds))
816
817    The associated values in an alist may be any Lisp objects; so may the
818 keys.  For example, in the following alist, the symbol `a' is
819 associated with the number `1', and the string `"b"' is associated with
820 the _list_ `(2 3)', which is the CDR of the alist element:
821
822      ((a . 1) ("b" 2 3))
823
824    Sometimes it is better to design an alist to store the associated
825 value in the CAR of the CDR of the element.  Here is an example:
826
827      '((rose red) (lily white) (buttercup yellow))
828
829 Here we regard `red' as the value associated with `rose'.  One
830 advantage of this method is that you can store other related
831 information--even a list of other items--in the CDR of the CDR.  One
832 disadvantage is that you cannot use `rassq' (see below) to find the
833 element containing a given value.  When neither of these considerations
834 is important, the choice is a matter of taste, as long as you are
835 consistent about it for any given alist.
836
837    Note that the same alist shown above could be regarded as having the
838 associated value in the CDR of the element; the value associated with
839 `rose' would be the list `(red)'.
840
841    Association lists are often used to record information that you might
842 otherwise keep on a stack, since new associations may be added easily to
843 the front of the list.  When searching an association list for an
844 association with a given key, the first one found is returned, if there
845 is more than one.
846
847    In XEmacs Lisp, it is _not_ an error if an element of an association
848 list is not a cons cell.  The alist search functions simply ignore such
849 elements.  Many other versions of Lisp signal errors in such cases.
850
851    Note that property lists are similar to association lists in several
852 respects.  A property list behaves like an association list in which
853 each key can occur only once.  *Note Property Lists::, for a comparison
854 of property lists and association lists.
855
856  - Function: assoc key alist
857      This function returns the first association for KEY in ALIST.  It
858      compares KEY against the alist elements using `equal' (*note
859      Equality Predicates::).  It returns `nil' if no association in
860      ALIST has a CAR `equal' to KEY.  For example:
861
862           (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
863                => ((pine . cones) (oak . acorns) (maple . seeds))
864           (assoc 'oak trees)
865                => (oak . acorns)
866           (cdr (assoc 'oak trees))
867                => acorns
868           (assoc 'birch trees)
869                => nil
870
871      Here is another example, in which the keys and values are not
872      symbols:
873
874           (setq needles-per-cluster
875                 '((2 "Austrian Pine" "Red Pine")
876                   (3 "Pitch Pine")
877                   (5 "White Pine")))
878           
879           (cdr (assoc 3 needles-per-cluster))
880                => ("Pitch Pine")
881           (cdr (assoc 2 needles-per-cluster))
882                => ("Austrian Pine" "Red Pine")
883
884  - Function: rassoc value alist
885      This function returns the first association with value VALUE in
886      ALIST.  It returns `nil' if no association in ALIST has a CDR
887      `equal' to VALUE.
888
889      `rassoc' is like `assoc' except that it compares the CDR of each
890      ALIST association instead of the CAR.  You can think of this as
891      "reverse `assoc'", finding the key for a given value.
892
893  - Function: assq key alist
894      This function is like `assoc' in that it returns the first
895      association for KEY in ALIST, but it makes the comparison using
896      `eq' instead of `equal'.  `assq' returns `nil' if no association
897      in ALIST has a CAR `eq' to KEY.  This function is used more often
898      than `assoc', since `eq' is faster than `equal' and most alists
899      use symbols as keys.  *Note Equality Predicates::.
900
901           (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
902                => ((pine . cones) (oak . acorns) (maple . seeds))
903           (assq 'pine trees)
904                => (pine . cones)
905
906      On the other hand, `assq' is not usually useful in alists where the
907      keys may not be symbols:
908
909           (setq leaves
910                 '(("simple leaves" . oak)
911                   ("compound leaves" . horsechestnut)))
912           
913           (assq "simple leaves" leaves)
914                => nil
915           (assoc "simple leaves" leaves)
916                => ("simple leaves" . oak)
917
918  - Function: rassq value alist
919      This function returns the first association with value VALUE in
920      ALIST.  It returns `nil' if no association in ALIST has a CDR `eq'
921      to VALUE.
922
923      `rassq' is like `assq' except that it compares the CDR of each
924      ALIST association instead of the CAR.  You can think of this as
925      "reverse `assq'", finding the key for a given value.
926
927      For example:
928
929           (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
930           
931           (rassq 'acorns trees)
932                => (oak . acorns)
933           (rassq 'spores trees)
934                => nil
935
936      Note that `rassq' cannot search for a value stored in the CAR of
937      the CDR of an element:
938
939           (setq colors '((rose red) (lily white) (buttercup yellow)))
940           
941           (rassq 'white colors)
942                => nil
943
944      In this case, the CDR of the association `(lily white)' is not the
945      symbol `white', but rather the list `(white)'.  This becomes
946      clearer if the association is written in dotted pair notation:
947
948           (lily white) == (lily . (white))
949
950  - Function: remassoc key alist
951      This function deletes by side effect any associations with key KEY
952      in ALIST--i.e. it removes any elements from ALIST whose `car' is
953      `equal' to KEY.  The modified ALIST is returned.
954
955      If the first member of ALIST has a `car' that is `equal' to KEY,
956      there is no way to remove it by side effect; therefore, write
957      `(setq foo (remassoc key foo))' to be sure of changing the value
958      of `foo'.
959
960  - Function: remassq key alist
961      This function deletes by side effect any associations with key KEY
962      in ALIST--i.e. it removes any elements from ALIST whose `car' is
963      `eq' to KEY.  The modified ALIST is returned.
964
965      This function is exactly like `remassoc', but comparisons between
966      KEY and keys in ALIST are done using `eq' instead of `equal'.
967
968  - Function: remrassoc value alist
969      This function deletes by side effect any associations with value
970      VALUE in ALIST--i.e. it removes any elements from ALIST whose
971      `cdr' is `equal' to VALUE.  The modified ALIST is returned.
972
973      If the first member of ALIST has a `car' that is `equal' to VALUE,
974      there is no way to remove it by side effect; therefore, write
975      `(setq foo (remassoc value foo))' to be sure of changing the value
976      of `foo'.
977
978      `remrassoc' is like `remassoc' except that it compares the CDR of
979      each ALIST association instead of the CAR.  You can think of this
980      as "reverse `remassoc'", removing an association based on its
981      value instead of its key.
982
983  - Function: remrassq value alist
984      This function deletes by side effect any associations with value
985      VALUE in ALIST--i.e. it removes any elements from ALIST whose
986      `cdr' is `eq' to VALUE.  The modified ALIST is returned.
987
988      This function is exactly like `remrassoc', but comparisons between
989      VALUE and values in ALIST are done using `eq' instead of `equal'.
990
991  - Function: copy-alist alist
992      This function returns a two-level deep copy of ALIST: it creates a
993      new copy of each association, so that you can alter the
994      associations of the new alist without changing the old one.
995
996           (setq needles-per-cluster
997                 '((2 . ("Austrian Pine" "Red Pine"))
998                   (3 . ("Pitch Pine"))
999                   (5 . ("White Pine"))))
1000           =>
1001           ((2 "Austrian Pine" "Red Pine")
1002            (3 "Pitch Pine")
1003            (5 "White Pine"))
1004           
1005           (setq copy (copy-alist needles-per-cluster))
1006           =>
1007           ((2 "Austrian Pine" "Red Pine")
1008            (3 "Pitch Pine")
1009            (5 "White Pine"))
1010           
1011           (eq needles-per-cluster copy)
1012                => nil
1013           (equal needles-per-cluster copy)
1014                => t
1015           (eq (car needles-per-cluster) (car copy))
1016                => nil
1017           (cdr (car (cdr needles-per-cluster)))
1018                => ("Pitch Pine")
1019           (eq (cdr (car (cdr needles-per-cluster)))
1020               (cdr (car (cdr copy))))
1021                => t
1022
1023      This example shows how `copy-alist' makes it possible to change
1024      the associations of one copy without affecting the other:
1025
1026           (setcdr (assq 3 copy) '("Martian Vacuum Pine"))
1027           (cdr (assq 3 needles-per-cluster))
1028                => ("Pitch Pine")
1029
1030    ---------- Footnotes ----------
1031
1032    (1) This usage of "key" is not related to the term "key sequence";
1033 it means a value used to look up an item in a table.  In this case, the
1034 table is the alist, and the alist associations are the items.
1035
1036 \1f
1037 File: lispref.info,  Node: Property Lists,  Next: Weak Lists,  Prev: Association Lists,  Up: Lists
1038
1039 Property Lists
1040 ==============
1041
1042 A "property list" (or "plist") is another way of representing a mapping
1043 from keys to values.  Instead of the list consisting of conses of a key
1044 and a value, the keys and values alternate as successive entries in the
1045 list.  Thus, the association list
1046
1047      ((a . 1) (b . 2) (c . 3))
1048
1049    has the equivalent property list form
1050
1051      (a 1 b 2 c 3)
1052
1053    Property lists are used to represent the properties associated with
1054 various sorts of objects, such as symbols, strings, frames, etc.  The
1055 convention is that property lists can be modified in-place, while
1056 association lists generally are not.
1057
1058    Plists come in two varieties: "normal" plists, whose keys are
1059 compared with `eq', and "lax" plists, whose keys are compared with
1060 `equal',
1061
1062  - Function: valid-plist-p plist
1063      Given a plist, this function returns non-`nil' if its format is
1064      correct.  If it returns `nil', `check-valid-plist' will signal an
1065      error when given the plist; that means it's a malformed or circular
1066      plist or has non-symbols as keywords.
1067
1068  - Function: check-valid-plist plist
1069      Given a plist, this function signals an error if there is anything
1070      wrong with it.  This means that it's a malformed or circular plist.
1071
1072 * Menu:
1073
1074 * Working With Normal Plists::       Functions for normal plists.
1075 * Working With Lax Plists::          Functions for lax plists.
1076 * Converting Plists To/From Alists:: Alist to plist and vice-versa.
1077
1078 \1f
1079 File: lispref.info,  Node: Working With Normal Plists,  Next: Working With Lax Plists,  Up: Property Lists
1080
1081 Working With Normal Plists
1082 --------------------------
1083
1084  - Function: plist-get plist property &optional default
1085      This function extracts a value from a property list.  The function
1086      returns the value corresponding to the given PROPERTY, or DEFAULT
1087      if PROPERTY is not one of the properties on the list.
1088
1089  - Function: plist-put plist property value
1090      This function changes the value in PLIST of PROPERTY to VALUE.  If
1091      PROPERTY is already a property on the list, its value is set to
1092      VALUE, otherwise the new PROPERTY VALUE pair is added.  The new
1093      plist is returned; use `(setq x (plist-put x property value))' to
1094      be sure to use the new value.  The PLIST is modified by side
1095      effects.
1096
1097  - Function: plist-remprop plist property
1098      This function removes from PLIST the property PROPERTY and its
1099      value.  The new plist is returned; use `(setq x (plist-remprop x
1100      property))' to be sure to use the new value.  The PLIST is
1101      modified by side effects.
1102
1103  - Function: plist-member plist property
1104      This function returns `t' if PROPERTY has a value specified in
1105      PLIST.
1106
1107    In the following functions, if optional arg NIL-MEANS-NOT-PRESENT is
1108 non-`nil', then a property with a `nil' value is ignored or removed.
1109 This feature is a virus that has infected old Lisp implementations (and
1110 thus E-Lisp, due to RMS's enamorment with old Lisps), but should not be
1111 used except for backward compatibility.
1112
1113  - Function: plists-eq a b &optional nil-means-not-present
1114      This function returns non-`nil' if property lists A and B are `eq'
1115      (i.e. their values are `eq').
1116
1117  - Function: plists-equal a b &optional nil-means-not-present
1118      This function returns non-`nil' if property lists A and B are
1119      `equal' (i.e. their values are `equal'; their keys are still
1120      compared using `eq').
1121
1122  - Function: canonicalize-plist plist &optional nil-means-not-present
1123      This function destructively removes any duplicate entries from a
1124      plist.  In such cases, the first entry applies.
1125
1126      The new plist is returned.  If NIL-MEANS-NOT-PRESENT is given, the
1127      return value may not be `eq' to the passed-in value, so make sure
1128      to `setq' the value back into where it came from.
1129
1130 \1f
1131 File: lispref.info,  Node: Working With Lax Plists,  Next: Converting Plists To/From Alists,  Prev: Working With Normal Plists,  Up: Property Lists
1132
1133 Working With Lax Plists
1134 -----------------------
1135
1136 Recall that a "lax plist" is a property list whose keys are compared
1137 using `equal' instead of `eq'.
1138
1139  - Function: lax-plist-get lax-plist property &optional default
1140      This function extracts a value from a lax property list.  The
1141      function returns the value corresponding to the given PROPERTY, or
1142      DEFAULT if PROPERTY is not one of the properties on the list.
1143
1144  - Function: lax-plist-put lax-plist property value
1145      This function changes the value in LAX-PLIST of PROPERTY to VALUE.
1146
1147  - Function: lax-plist-remprop lax-plist property
1148      This function removes from LAX-PLIST the property PROPERTY and its
1149      value.  The new plist is returned; use `(setq x (lax-plist-remprop
1150      x property))' to be sure to use the new value.  The LAX-PLIST is
1151      modified by side effects.
1152
1153  - Function: lax-plist-member lax-plist property
1154      This function returns `t' if PROPERTY has a value specified in
1155      LAX-PLIST.
1156
1157    In the following functions, if optional arg NIL-MEANS-NOT-PRESENT is
1158 non-`nil', then a property with a `nil' value is ignored or removed.
1159 This feature is a virus that has infected old Lisp implementations (and
1160 thus E-Lisp, due to RMS's enamorment with old Lisps), but should not be
1161 used except for backward compatibility.
1162
1163  - Function: lax-plists-eq a b &optional nil-means-not-present
1164      This function returns non-`nil' if lax property lists A and B are
1165      `eq' (i.e. their values are `eq'; their keys are still compared
1166      using `equal').
1167
1168  - Function: lax-plists-equal a b &optional nil-means-not-present
1169      This function returns non-`nil' if lax property lists A and B are
1170      `equal' (i.e. their values are `equal').
1171
1172  - Function: canonicalize-lax-plist lax-plist &optional
1173           nil-means-not-present
1174      This function destructively removes any duplicate entries from a
1175      lax plist.  In such cases, the first entry applies.
1176
1177      The new plist is returned.  If NIL-MEANS-NOT-PRESENT is given, the
1178      return value may not be `eq' to the passed-in value, so make sure
1179      to `setq' the value back into where it came from.
1180
1181 \1f
1182 File: lispref.info,  Node: Converting Plists To/From Alists,  Prev: Working With Lax Plists,  Up: Property Lists
1183
1184 Converting Plists To/From Alists
1185 --------------------------------
1186
1187  - Function: alist-to-plist alist
1188      This function converts association list ALIST into the equivalent
1189      property-list form.  The plist is returned.  This converts from
1190
1191           ((a . 1) (b . 2) (c . 3))
1192
1193      into
1194
1195           (a 1 b 2 c 3)
1196
1197      The original alist is not modified.
1198
1199  - Function: plist-to-alist plist
1200      This function converts property list PLIST into the equivalent
1201      association-list form.  The alist is returned.  This converts from
1202
1203           (a 1 b 2 c 3)
1204
1205      into
1206
1207           ((a . 1) (b . 2) (c . 3))
1208
1209      The original plist is not modified.
1210
1211    The following two functions are equivalent to the preceding two
1212 except that they destructively modify their arguments, using cons cells
1213 from the original list to form the new list rather than allocating new
1214 cons cells.
1215
1216  - Function: destructive-alist-to-plist alist
1217      This function destructively converts association list ALIST into
1218      the equivalent property-list form.  The plist is returned.
1219
1220  - Function: destructive-plist-to-alist plist
1221      This function destructively converts property list PLIST into the
1222      equivalent association-list form.  The alist is returned.
1223
1224 \1f
1225 File: lispref.info,  Node: Weak Lists,  Prev: Property Lists,  Up: Lists
1226
1227 Weak Lists
1228 ==========
1229
1230 A "weak list" is a special sort of list whose members are not counted
1231 as references for the purpose of garbage collection.  This means that,
1232 for any object in the list, if there are no references to the object
1233 anywhere outside of the list (or other weak list or weak hash table),
1234 that object will disappear the next time a garbage collection happens.
1235 Weak lists can be useful for keeping track of things such as unobtrusive
1236 lists of another function's buffers or markers.  When that function is
1237 done with the elements, they will automatically disappear from the list.
1238
1239    Weak lists are used internally, for example, to manage the list
1240 holding the children of an extent--an extent that is unused but has a
1241 parent will still be reclaimed, and will automatically be removed from
1242 its parent's list of children.
1243
1244    Weak lists are similar to weak hash tables (*note Weak Hash
1245 Tables::).
1246
1247  - Function: weak-list-p object
1248      This function returns non-`nil' if OBJECT is a weak list.
1249
1250    Weak lists come in one of four types:
1251
1252 `simple'
1253      Objects in the list disappear if not referenced outside of the
1254      list.
1255
1256 `assoc'
1257      Objects in the list disappear if they are conses and either the
1258      car or the cdr of the cons is not referenced outside of the list.
1259
1260 `key-assoc'
1261      Objects in the list disappear if they are conses and the car is not
1262      referenced outside of the list.
1263
1264 `value-assoc'
1265      Objects in the list disappear if they are conses and the cdr is not
1266      referenced outside of the list.
1267
1268  - Function: make-weak-list &optional type
1269      This function creates a new weak list of type TYPE.  TYPE is a
1270      symbol (one of `simple', `assoc', `key-assoc', or `value-assoc',
1271      as described above) and defaults to `simple'.
1272
1273  - Function: weak-list-type weak
1274      This function returns the type of the given weak-list object.
1275
1276  - Function: weak-list-list weak
1277      This function returns the list contained in a weak-list object.
1278
1279  - Function: set-weak-list-list weak new-list
1280      This function changes the list contained in a weak-list object.
1281
1282 \1f
1283 File: lispref.info,  Node: Sequences Arrays Vectors,  Next: Symbols,  Prev: Lists,  Up: Top
1284
1285 Sequences, Arrays, and Vectors
1286 ******************************
1287
1288 Recall that the "sequence" type is the union of four other Lisp types:
1289 lists, vectors, bit vectors, and strings.  In other words, any list is
1290 a sequence, any vector is a sequence, any bit vector is a sequence, and
1291 any string is a sequence.  The common property that all sequences have
1292 is that each is an ordered collection of elements.
1293
1294    An "array" is a single primitive object that has a slot for each
1295 elements.  All the elements are accessible in constant time, but the
1296 length of an existing array cannot be changed.  Strings, vectors, and
1297 bit vectors are the three types of arrays.
1298
1299    A list is a sequence of elements, but it is not a single primitive
1300 object; it is made of cons cells, one cell per element.  Finding the
1301 Nth element requires looking through N cons cells, so elements farther
1302 from the beginning of the list take longer to access.  But it is
1303 possible to add elements to the list, or remove elements.
1304
1305    The following diagram shows the relationship between these types:
1306
1307                ___________________________________
1308               |                                   |
1309               |          Sequence                 |
1310               |  ______   ______________________  |
1311               | |      | |                      | |
1312               | | List | |         Array        | |
1313               | |      | |  ________   _______  | |
1314               | |______| | |        | |       | | |
1315               |          | | Vector | | String| | |
1316               |          | |________| |_______| | |
1317               |          |  __________________  | |
1318               |          | |                  | | |
1319               |          | |    Bit Vector    | | |
1320               |          | |__________________| | |
1321               |          |______________________| |
1322               |___________________________________|
1323
1324    The elements of vectors and lists may be any Lisp objects.  The
1325 elements of strings are all characters.  The elements of bit vectors
1326 are the numbers 0 and 1.
1327
1328 * Menu:
1329
1330 * Sequence Functions::    Functions that accept any kind of sequence.
1331 * Arrays::                Characteristics of arrays in XEmacs Lisp.
1332 * Array Functions::       Functions specifically for arrays.
1333 * Vectors::               Special characteristics of XEmacs Lisp vectors.
1334 * Vector Functions::      Functions specifically for vectors.
1335 * Bit Vectors::           Special characteristics of XEmacs Lisp bit vectors.
1336 * Bit Vector Functions::  Functions specifically for bit vectors.
1337
1338 \1f
1339 File: lispref.info,  Node: Sequence Functions,  Next: Arrays,  Up: Sequences Arrays Vectors
1340
1341 Sequences
1342 =========
1343
1344 In XEmacs Lisp, a "sequence" is either a list, a vector, a bit vector,
1345 or a string.  The common property that all sequences have is that each
1346 is an ordered collection of elements.  This section describes functions
1347 that accept any kind of sequence.
1348
1349  - Function: sequencep object
1350      Returns `t' if OBJECT is a list, vector, bit vector, or string,
1351      `nil' otherwise.
1352
1353  - Function: copy-sequence sequence
1354      Returns a copy of SEQUENCE.  The copy is the same type of object
1355      as the original sequence, and it has the same elements in the same
1356      order.
1357
1358      Storing a new element into the copy does not affect the original
1359      SEQUENCE, and vice versa.  However, the elements of the new
1360      sequence are not copies; they are identical (`eq') to the elements
1361      of the original.  Therefore, changes made within these elements, as
1362      found via the copied sequence, are also visible in the original
1363      sequence.
1364
1365      If the sequence is a string with extents or text properties, the
1366      extents and text properties in the copy are also copied, not
1367      shared with the original. (This means that modifying the extents
1368      or text properties of the original will not affect the copy.)
1369      However, the actual values of the properties are shared.  *Note
1370      Extents::, *Note Text Properties::.
1371
1372      See also `append' in *Note Building Lists::, `concat' in *Note
1373      Creating Strings::, `vconcat' in *Note Vectors::, and `bvconcat'
1374      in *Note Bit Vectors::, for other ways to copy sequences.
1375
1376           (setq bar '(1 2))
1377                => (1 2)
1378           (setq x (vector 'foo bar))
1379                => [foo (1 2)]
1380           (setq y (copy-sequence x))
1381                => [foo (1 2)]
1382           
1383           (eq x y)
1384                => nil
1385           (equal x y)
1386                => t
1387           (eq (elt x 1) (elt y 1))
1388                => t
1389           
1390           ;; Replacing an element of one sequence.
1391           (aset x 0 'quux)
1392           x => [quux (1 2)]
1393           y => [foo (1 2)]
1394           
1395           ;; Modifying the inside of a shared element.
1396           (setcar (aref x 1) 69)
1397           x => [quux (69 2)]
1398           y => [foo (69 2)]
1399           
1400           ;; Creating a bit vector.
1401           (bit-vector 1 0 1 1 0 1 0 0)
1402                => #*10110100
1403
1404  - Function: length sequence
1405      Returns the number of elements in SEQUENCE.  If SEQUENCE is a cons
1406      cell that is not a list (because the final CDR is not `nil'), a
1407      `wrong-type-argument' error is signaled.
1408
1409           (length '(1 2 3))
1410               => 3
1411           (length ())
1412               => 0
1413           (length "foobar")
1414               => 6
1415           (length [1 2 3])
1416               => 3
1417           (length #*01101)
1418               => 5
1419
1420  - Function: elt sequence index
1421      This function returns the element of SEQUENCE indexed by INDEX.
1422      Legitimate values of INDEX are integers ranging from 0 up to one
1423      less than the length of SEQUENCE.  If SEQUENCE is a list, then
1424      out-of-range values of INDEX return `nil'; otherwise, they trigger
1425      an `args-out-of-range' error.
1426
1427           (elt [1 2 3 4] 2)
1428                => 3
1429           (elt '(1 2 3 4) 2)
1430                => 3
1431           (char-to-string (elt "1234" 2))
1432                => "3"
1433           (elt #*00010000 3)
1434                => 1
1435           (elt [1 2 3 4] 4)
1436                error-->Args out of range: [1 2 3 4], 4
1437           (elt [1 2 3 4] -1)
1438                error-->Args out of range: [1 2 3 4], -1
1439
1440      This function generalizes `aref' (*note Array Functions::) and
1441      `nth' (*note List Elements::).
1442
1443 \1f
1444 File: lispref.info,  Node: Arrays,  Next: Array Functions,  Prev: Sequence Functions,  Up: Sequences Arrays Vectors
1445
1446 Arrays
1447 ======
1448
1449 An "array" object has slots that hold a number of other Lisp objects,
1450 called the elements of the array.  Any element of an array may be
1451 accessed in constant time.  In contrast, an element of a list requires
1452 access time that is proportional to the position of the element in the
1453 list.
1454
1455    When you create an array, you must specify how many elements it has.
1456 The amount of space allocated depends on the number of elements.
1457 Therefore, it is impossible to change the size of an array once it is
1458 created; you cannot add or remove elements.  However, you can replace an
1459 element with a different value.
1460
1461    XEmacs defines three types of array, all of which are
1462 one-dimensional: "strings", "vectors", and "bit vectors".  A vector is a
1463 general array; its elements can be any Lisp objects.  A string is a
1464 specialized array; its elements must be characters.  A bit vector is
1465 another specialized array; its elements must be bits (an integer, either
1466 0 or 1).  Each type of array has its own read syntax.  *Note String
1467 Type::, *Note Vector Type::, and *Note Bit Vector Type::.
1468
1469    All kinds of array share these characteristics:
1470
1471    * The first element of an array has index zero, the second element
1472      has index 1, and so on.  This is called "zero-origin" indexing.
1473      For example, an array of four elements has indices 0, 1, 2, and 3.
1474
1475    * The elements of an array may be referenced or changed with the
1476      functions `aref' and `aset', respectively (*note Array
1477      Functions::).
1478
1479    In principle, if you wish to have an array of text characters, you
1480 could use either a string or a vector.  In practice, we always choose
1481 strings for such applications, for four reasons:
1482
1483    * They usually occupy one-fourth the space of a vector of the same
1484      elements.  (This is one-eighth the space for 64-bit machines such
1485      as the DEC Alpha, and may also be different when MULE support is
1486      compiled into XEmacs.)
1487
1488    * Strings are printed in a way that shows the contents more clearly
1489      as characters.
1490
1491    * Strings can hold extent and text properties.  *Note Extents::,
1492      *Note Text Properties::.
1493
1494    * Many of the specialized editing and I/O facilities of XEmacs
1495      accept only strings.  For example, you cannot insert a vector of
1496      characters into a buffer the way you can insert a string.  *Note
1497      Strings and Characters::.
1498
1499    By contrast, for an array of keyboard input characters (such as a key
1500 sequence), a vector may be necessary, because many keyboard input
1501 characters are non-printable and are represented with symbols rather
1502 than with characters.  *Note Key Sequence Input::.
1503
1504    Similarly, when representing an array of bits, a bit vector has the
1505 following advantages over a regular vector:
1506
1507    * They occupy 1/32nd the space of a vector of the same elements.
1508      (1/64th on 64-bit machines such as the DEC Alpha.)
1509
1510    * Bit vectors are printed in a way that shows the contents more
1511      clearly as bits.
1512
1513 \1f
1514 File: lispref.info,  Node: Array Functions,  Next: Vectors,  Prev: Arrays,  Up: Sequences Arrays Vectors
1515
1516 Functions that Operate on Arrays
1517 ================================
1518
1519 In this section, we describe the functions that accept strings, vectors,
1520 and bit vectors.
1521
1522  - Function: arrayp object
1523      This function returns `t' if OBJECT is an array (i.e., a string,
1524      vector, or bit vector).
1525
1526           (arrayp "asdf")
1527           => t
1528           (arrayp [a])
1529           => t
1530           (arrayp #*101)
1531           => t
1532
1533  - Function: aref array index
1534      This function returns the INDEXth element of ARRAY.  The first
1535      element is at index zero.
1536
1537           (setq primes [2 3 5 7 11 13])
1538                => [2 3 5 7 11 13]
1539           (aref primes 4)
1540                => 11
1541           (elt primes 4)
1542                => 11
1543           
1544           (aref "abcdefg" 1)
1545                => ?b
1546           
1547           (aref #*1101 2)
1548                => 0
1549
1550      See also the function `elt', in *Note Sequence Functions::.
1551
1552  - Function: aset array index object
1553      This function sets the INDEXth element of ARRAY to be OBJECT.  It
1554      returns OBJECT.
1555
1556           (setq w [foo bar baz])
1557                => [foo bar baz]
1558           (aset w 0 'fu)
1559                => fu
1560           w
1561                => [fu bar baz]
1562           
1563           (setq x "asdfasfd")
1564                => "asdfasfd"
1565           (aset x 3 ?Z)
1566                => ?Z
1567           x
1568                => "asdZasfd"
1569           
1570           (setq bv #*1111)
1571                => #*1111
1572           (aset bv 2 0)
1573                => 0
1574           bv
1575                => #*1101
1576
1577      If ARRAY is a string and OBJECT is not a character, a
1578      `wrong-type-argument' error results.
1579
1580  - Function: fillarray array object
1581      This function fills the array ARRAY with OBJECT, so that each
1582      element of ARRAY is OBJECT.  It returns ARRAY.
1583
1584           (setq a [a b c d e f g])
1585                => [a b c d e f g]
1586           (fillarray a 0)
1587                => [0 0 0 0 0 0 0]
1588           a
1589                => [0 0 0 0 0 0 0]
1590           
1591           (setq s "When in the course")
1592                => "When in the course"
1593           (fillarray s ?-)
1594                => "------------------"
1595           
1596           (setq bv #*1101)
1597                => #*1101
1598           (fillarray bv 0)
1599                => #*0000
1600
1601      If ARRAY is a string and OBJECT is not a character, a
1602      `wrong-type-argument' error results.
1603
1604    The general sequence functions `copy-sequence' and `length' are
1605 often useful for objects known to be arrays.  *Note Sequence
1606 Functions::.
1607
1608 \1f
1609 File: lispref.info,  Node: Vectors,  Next: Vector Functions,  Prev: Array Functions,  Up: Sequences Arrays Vectors
1610
1611 Vectors
1612 =======
1613
1614 Arrays in Lisp, like arrays in most languages, are blocks of memory
1615 whose elements can be accessed in constant time.  A "vector" is a
1616 general-purpose array; its elements can be any Lisp objects.  (The other
1617 kind of array in XEmacs Lisp is the "string", whose elements must be
1618 characters.)  Vectors in XEmacs serve as obarrays (vectors of symbols),
1619 although this is a shortcoming that should be fixed.  They are also used
1620 internally as part of the representation of a byte-compiled function; if
1621 you print such a function, you will see a vector in it.
1622
1623    In XEmacs Lisp, the indices of the elements of a vector start from
1624 zero and count up from there.
1625
1626    Vectors are printed with square brackets surrounding the elements.
1627 Thus, a vector whose elements are the symbols `a', `b' and `a' is
1628 printed as `[a b a]'.  You can write vectors in the same way in Lisp
1629 input.
1630
1631    A vector, like a string or a number, is considered a constant for
1632 evaluation: the result of evaluating it is the same vector.  This does
1633 not evaluate or even examine the elements of the vector.  *Note
1634 Self-Evaluating Forms::.
1635
1636    Here are examples of these principles:
1637
1638      (setq avector [1 two '(three) "four" [five]])
1639           => [1 two (quote (three)) "four" [five]]
1640      (eval avector)
1641           => [1 two (quote (three)) "four" [five]]
1642      (eq avector (eval avector))
1643           => t
1644
1645 \1f
1646 File: lispref.info,  Node: Vector Functions,  Next: Bit Vectors,  Prev: Vectors,  Up: Sequences Arrays Vectors
1647
1648 Functions That Operate on Vectors
1649 =================================
1650
1651 Here are some functions that relate to vectors:
1652
1653  - Function: vectorp object
1654      This function returns `t' if OBJECT is a vector.
1655
1656           (vectorp [a])
1657                => t
1658           (vectorp "asdf")
1659                => nil
1660
1661  - Function: vector &rest objects
1662      This function creates and returns a vector whose elements are the
1663      arguments, OBJECTS.
1664
1665           (vector 'foo 23 [bar baz] "rats")
1666                => [foo 23 [bar baz] "rats"]
1667           (vector)
1668                => []
1669
1670  - Function: make-vector length object
1671      This function returns a new vector consisting of LENGTH elements,
1672      each initialized to OBJECT.
1673
1674           (setq sleepy (make-vector 9 'Z))
1675                => [Z Z Z Z Z Z Z Z Z]
1676
1677  - Function: vconcat &rest sequences
1678      This function returns a new vector containing all the elements of
1679      the SEQUENCES.  The arguments SEQUENCES may be lists, vectors, or
1680      strings.  If no SEQUENCES are given, an empty vector is returned.
1681
1682      The value is a newly constructed vector that is not `eq' to any
1683      existing vector.
1684
1685           (setq a (vconcat '(A B C) '(D E F)))
1686                => [A B C D E F]
1687           (eq a (vconcat a))
1688                => nil
1689           (vconcat)
1690                => []
1691           (vconcat [A B C] "aa" '(foo (6 7)))
1692                => [A B C 97 97 foo (6 7)]
1693
1694      The `vconcat' function also allows integers as arguments.  It
1695      converts them to strings of digits, making up the decimal print
1696      representation of the integer, and then uses the strings instead
1697      of the original integers.  *Don't use this feature; we plan to
1698      eliminate it.  If you already use this feature, change your
1699      programs now!*  The proper way to convert an integer to a decimal
1700      number in this way is with `format' (*note Formatting Strings::)
1701      or `number-to-string' (*note String Conversion::).
1702
1703      For other concatenation functions, see `mapconcat' in *Note
1704      Mapping Functions::, `concat' in *Note Creating Strings::, `append'
1705      in *Note Building Lists::, and `bvconcat' in *Note Bit Vector
1706      Functions::.
1707
1708    The `append' function provides a way to convert a vector into a list
1709 with the same elements (*note Building Lists::):
1710
1711      (setq avector [1 two (quote (three)) "four" [five]])
1712           => [1 two (quote (three)) "four" [five]]
1713      (append avector nil)
1714           => (1 two (quote (three)) "four" [five])
1715
1716 \1f
1717 File: lispref.info,  Node: Bit Vectors,  Next: Bit Vector Functions,  Prev: Vector Functions,  Up: Sequences Arrays Vectors
1718
1719 Bit Vectors
1720 ===========
1721
1722 Bit vectors are specialized vectors that can only represent arrays of
1723 1's and 0's.  Bit vectors have a very efficient representation and are
1724 useful for representing sets of boolean (true or false) values.
1725
1726    There is no limit on the size of a bit vector.  You could, for
1727 example, create a bit vector with 100,000 elements if you really wanted
1728 to.
1729
1730    Bit vectors have a special printed representation consisting of `#*'
1731 followed by the bits of the vector.  For example, a bit vector whose
1732 elements are 0, 1, 1, 0, and 1, respectively, is printed as
1733
1734      #*01101
1735
1736    Bit vectors are considered constants for evaluation, like vectors,
1737 strings, and numbers.  *Note Self-Evaluating Forms::.
1738
1739 \1f
1740 File: lispref.info,  Node: Bit Vector Functions,  Prev: Bit Vectors,  Up: Sequences Arrays Vectors
1741
1742 Functions That Operate on Bit Vectors
1743 =====================================
1744
1745 Here are some functions that relate to bit vectors:
1746
1747  - Function: bit-vector-p object
1748      This function returns `t' if OBJECT is a bit vector.
1749
1750           (bit-vector-p #*01)
1751                => t
1752           (bit-vector-p [0 1])
1753                => nil
1754           (bit-vector-p "01")
1755                => nil
1756
1757  - Function: bitp object
1758      This function returns `t' if OBJECT is either 0 or 1.
1759
1760  - Function: bit-vector &rest bits
1761      This function creates and returns a bit vector whose elements are
1762      the arguments BITS.  Each argument must be a bit, i.e. one of the
1763      two integers 0 or 1.
1764
1765           (bit-vector 0 0 0 1 0 0 0 0 1 0)
1766                => #*0001000010
1767           (bit-vector)
1768                => #*
1769
1770  - Function: make-bit-vector length bit
1771      This function creates and returns a bit vector consisting of
1772      LENGTH elements, each initialized to BIT, which must be one of the
1773      two integers 0 or 1.
1774
1775           (setq picket-fence (make-bit-vector 9 1))
1776                => #*111111111
1777
1778  - Function: bvconcat &rest sequences
1779      This function returns a new bit vector containing all the elements
1780      of the SEQUENCES.  The arguments SEQUENCES may be lists, vectors,
1781      or bit vectors, all of whose elements are the integers 0 or 1.  If
1782      no SEQUENCES are given, an empty bit vector is returned.
1783
1784      The value is a newly constructed bit vector that is not `eq' to any
1785      existing bit vector.
1786
1787           (setq a (bvconcat '(1 1 0) '(0 0 1)))
1788                => #*110001
1789           (eq a (bvconcat a))
1790                => nil
1791           (bvconcat)
1792                => #*
1793           (bvconcat [1 0 0 0 0] #*111 '(0 0 0 0 1))
1794                => #*1000011100001
1795
1796      For other concatenation functions, see `mapconcat' in *Note
1797      Mapping Functions::, `concat' in *Note Creating Strings::,
1798      `vconcat' in *Note Vector Functions::, and `append' in *Note
1799      Building Lists::.
1800
1801    The `append' function provides a way to convert a bit vector into a
1802 list with the same elements (*note Building Lists::):
1803
1804      (setq bv #*00001110)
1805           => #*00001110
1806      (append bv nil)
1807           => (0 0 0 0 1 1 1 0)
1808
1809 \1f
1810 File: lispref.info,  Node: Symbols,  Next: Evaluation,  Prev: Sequences Arrays Vectors,  Up: Top
1811
1812 Symbols
1813 *******
1814
1815 A "symbol" is an object with a unique name.  This chapter describes
1816 symbols, their components, their property lists, and how they are
1817 created and interned.  Separate chapters describe the use of symbols as
1818 variables and as function names; see *Note Variables::, and *Note
1819 Functions::.  For the precise read syntax for symbols, see *Note Symbol
1820 Type::.
1821
1822    You can test whether an arbitrary Lisp object is a symbol with
1823 `symbolp':
1824
1825  - Function: symbolp object
1826      This function returns `t' if OBJECT is a symbol, `nil' otherwise.
1827
1828 * Menu:
1829
1830 * Symbol Components::       Symbols have names, values, function definitions
1831                               and property lists.
1832 * Definitions::             A definition says how a symbol will be used.
1833 * Creating Symbols::        How symbols are kept unique.
1834 * Symbol Properties::       Each symbol has a property list
1835                               for recording miscellaneous information.
1836
1837 \1f
1838 File: lispref.info,  Node: Symbol Components,  Next: Definitions,  Up: Symbols
1839
1840 Symbol Components
1841 =================
1842
1843 Each symbol has four components (or "cells"), each of which references
1844 another object:
1845
1846 Print name
1847      The "print name cell" holds a string that names the symbol for
1848      reading and printing.  See `symbol-name' in *Note Creating
1849      Symbols::.
1850
1851 Value
1852      The "value cell" holds the current value of the symbol as a
1853      variable.  When a symbol is used as a form, the value of the form
1854      is the contents of the symbol's value cell.  See `symbol-value' in
1855      *Note Accessing Variables::.
1856
1857 Function
1858      The "function cell" holds the function definition of the symbol.
1859      When a symbol is used as a function, its function definition is
1860      used in its place.  This cell is also used to make a symbol stand
1861      for a keymap or a keyboard macro, for editor command execution.
1862      Because each symbol has separate value and function cells,
1863      variables and function names do not conflict.  See
1864      `symbol-function' in *Note Function Cells::.
1865
1866 Property list
1867      The "property list cell" holds the property list of the symbol.
1868      See `symbol-plist' in *Note Symbol Properties::.
1869
1870    The print name cell always holds a string, and cannot be changed.
1871 The other three cells can be set individually to any specified Lisp
1872 object.
1873
1874    The print name cell holds the string that is the name of the symbol.
1875 Since symbols are represented textually by their names, it is important
1876 not to have two symbols with the same name.  The Lisp reader ensures
1877 this: every time it reads a symbol, it looks for an existing symbol with
1878 the specified name before it creates a new one.  (In XEmacs Lisp, this
1879 lookup uses a hashing algorithm and an obarray; see *Note Creating
1880 Symbols::.)
1881
1882    In normal usage, the function cell usually contains a function or
1883 macro, as that is what the Lisp interpreter expects to see there (*note
1884 Evaluation::).  Keyboard macros (*note Keyboard Macros::), keymaps
1885 (*note Keymaps::) and autoload objects (*note Autoloading::) are also
1886 sometimes stored in the function cell of symbols.  We often refer to
1887 "the function `foo'" when we really mean the function stored in the
1888 function cell of the symbol `foo'.  We make the distinction only when
1889 necessary.
1890
1891    The property list cell normally should hold a correctly formatted
1892 property list (*note Property Lists::), as a number of functions expect
1893 to see a property list there.
1894
1895    The function cell or the value cell may be "void", which means that
1896 the cell does not reference any object.  (This is not the same thing as
1897 holding the symbol `void', nor the same as holding the symbol `nil'.)
1898 Examining a cell that is void results in an error, such as `Symbol's
1899 value as variable is void'.
1900
1901    The four functions `symbol-name', `symbol-value', `symbol-plist',
1902 and `symbol-function' return the contents of the four cells of a
1903 symbol.  Here as an example we show the contents of the four cells of
1904 the symbol `buffer-file-name':
1905
1906      (symbol-name 'buffer-file-name)
1907           => "buffer-file-name"
1908      (symbol-value 'buffer-file-name)
1909           => "/gnu/elisp/symbols.texi"
1910      (symbol-plist 'buffer-file-name)
1911           => (variable-documentation 29529)
1912      (symbol-function 'buffer-file-name)
1913           => #<subr buffer-file-name>
1914
1915 Because this symbol is the variable which holds the name of the file
1916 being visited in the current buffer, the value cell contents we see are
1917 the name of the source file of this chapter of the XEmacs Lisp Reference
1918 Manual.  The property list cell contains the list
1919 `(variable-documentation 29529)' which tells the documentation
1920 functions where to find the documentation string for the variable
1921 `buffer-file-name' in the `DOC' file.  (29529 is the offset from the
1922 beginning of the `DOC' file to where that documentation string begins.)
1923 The function cell contains the function for returning the name of the
1924 file.  `buffer-file-name' names a primitive function, which has no read
1925 syntax and prints in hash notation (*note Primitive Function Type::).  A
1926 symbol naming a function written in Lisp would have a lambda expression
1927 (or a byte-code object) in this cell.
1928
1929 \1f
1930 File: lispref.info,  Node: Definitions,  Next: Creating Symbols,  Prev: Symbol Components,  Up: Symbols
1931
1932 Defining Symbols
1933 ================
1934
1935 A "definition" in Lisp is a special form that announces your intention
1936 to use a certain symbol in a particular way.  In XEmacs Lisp, you can
1937 define a symbol as a variable, or define it as a function (or macro),
1938 or both independently.
1939
1940    A definition construct typically specifies a value or meaning for the
1941 symbol for one kind of use, plus documentation for its meaning when used
1942 in this way.  Thus, when you define a symbol as a variable, you can
1943 supply an initial value for the variable, plus documentation for the
1944 variable.
1945
1946    `defvar' and `defconst' are special forms that define a symbol as a
1947 global variable.  They are documented in detail in *Note Defining
1948 Variables::.
1949
1950    `defun' defines a symbol as a function, creating a lambda expression
1951 and storing it in the function cell of the symbol.  This lambda
1952 expression thus becomes the function definition of the symbol.  (The
1953 term "function definition", meaning the contents of the function cell,
1954 is derived from the idea that `defun' gives the symbol its definition
1955 as a function.)  `defsubst', `define-function' and `defalias' are other
1956 ways of defining a function.  *Note Functions::.
1957
1958    `defmacro' defines a symbol as a macro.  It creates a macro object
1959 and stores it in the function cell of the symbol.  Note that a given
1960 symbol can be a macro or a function, but not both at once, because both
1961 macro and function definitions are kept in the function cell, and that
1962 cell can hold only one Lisp object at any given time.  *Note Macros::.
1963
1964    In XEmacs Lisp, a definition is not required in order to use a symbol
1965 as a variable or function.  Thus, you can make a symbol a global
1966 variable with `setq', whether you define it first or not.  The real
1967 purpose of definitions is to guide programmers and programming tools.
1968 They inform programmers who read the code that certain symbols are
1969 _intended_ to be used as variables, or as functions.  In addition,
1970 utilities such as `etags' and `make-docfile' recognize definitions, and
1971 add appropriate information to tag tables and the `DOC' file. *Note
1972 Accessing Documentation::.
1973
1974 \1f
1975 File: lispref.info,  Node: Creating Symbols,  Next: Symbol Properties,  Prev: Definitions,  Up: Symbols
1976
1977 Creating and Interning Symbols
1978 ==============================
1979
1980 To understand how symbols are created in XEmacs Lisp, you must know how
1981 Lisp reads them.  Lisp must ensure that it finds the same symbol every
1982 time it reads the same set of characters.  Failure to do so would cause
1983 complete confusion.
1984
1985    When the Lisp reader encounters a symbol, it reads all the characters
1986 of the name.  Then it "hashes" those characters to find an index in a
1987 table called an "obarray".  Hashing is an efficient method of looking
1988 something up.  For example, instead of searching a telephone book cover
1989 to cover when looking up Jan Jones, you start with the J's and go from
1990 there.  That is a simple version of hashing.  Each element of the
1991 obarray is a "bucket" which holds all the symbols with a given hash
1992 code; to look for a given name, it is sufficient to look through all
1993 the symbols in the bucket for that name's hash code.
1994
1995    If a symbol with the desired name is found, the reader uses that
1996 symbol.  If the obarray does not contain a symbol with that name, the
1997 reader makes a new symbol and adds it to the obarray.  Finding or adding
1998 a symbol with a certain name is called "interning" it, and the symbol
1999 is then called an "interned symbol".
2000
2001    Interning ensures that each obarray has just one symbol with any
2002 particular name.  Other like-named symbols may exist, but not in the
2003 same obarray.  Thus, the reader gets the same symbols for the same
2004 names, as long as you keep reading with the same obarray.
2005
2006    No obarray contains all symbols; in fact, some symbols are not in any
2007 obarray.  They are called "uninterned symbols".  An uninterned symbol
2008 has the same four cells as other symbols; however, the only way to gain
2009 access to it is by finding it in some other object or as the value of a
2010 variable.
2011
2012    In XEmacs Lisp, an obarray is actually a vector.  Each element of the
2013 vector is a bucket; its value is either an interned symbol whose name
2014 hashes to that bucket, or 0 if the bucket is empty.  Each interned
2015 symbol has an internal link (invisible to the user) to the next symbol
2016 in the bucket.  Because these links are invisible, there is no way to
2017 find all the symbols in an obarray except using `mapatoms' (below).
2018 The order of symbols in a bucket is not significant.
2019
2020    In an empty obarray, every element is 0, and you can create an
2021 obarray with `(make-vector LENGTH 0)'.  *This is the only valid way to
2022 create an obarray.*  Prime numbers as lengths tend to result in good
2023 hashing; lengths one less than a power of two are also good.
2024
2025    *Do not try to put symbols in an obarray yourself.*  This does not
2026 work--only `intern' can enter a symbol in an obarray properly.  *Do not
2027 try to intern one symbol in two obarrays.*  This would garble both
2028 obarrays, because a symbol has just one slot to hold the following
2029 symbol in the obarray bucket.  The results would be unpredictable.
2030
2031    It is possible for two different symbols to have the same name in
2032 different obarrays; these symbols are not `eq' or `equal'.  However,
2033 this normally happens only as part of the abbrev mechanism (*note
2034 Abbrevs::).
2035
2036      Common Lisp note: In Common Lisp, a single symbol may be interned
2037      in several obarrays.
2038
2039    Most of the functions below take a name and sometimes an obarray as
2040 arguments.  A `wrong-type-argument' error is signaled if the name is
2041 not a string, or if the obarray is not a vector.
2042
2043  - Function: symbol-name symbol
2044      This function returns the string that is SYMBOL's name.  For
2045      example:
2046
2047           (symbol-name 'foo)
2048                => "foo"
2049
2050      Changing the string by substituting characters, etc, does change
2051      the name of the symbol, but fails to update the obarray, so don't
2052      do it!
2053
2054  - Function: make-symbol name
2055      This function returns a newly-allocated, uninterned symbol whose
2056      name is NAME (which must be a string).  Its value and function
2057      definition are void, and its property list is `nil'.  In the
2058      example below, the value of `sym' is not `eq' to `foo' because it
2059      is a distinct uninterned symbol whose name is also `foo'.
2060
2061           (setq sym (make-symbol "foo"))
2062                => foo
2063           (eq sym 'foo)
2064                => nil
2065
2066  - Function: intern name &optional obarray
2067      This function returns the interned symbol whose name is NAME.  If
2068      there is no such symbol in the obarray OBARRAY, `intern' creates a
2069      new one, adds it to the obarray, and returns it.  If OBARRAY is
2070      omitted, the value of the global variable `obarray' is used.
2071
2072           (setq sym (intern "foo"))
2073                => foo
2074           (eq sym 'foo)
2075                => t
2076           
2077           (setq sym1 (intern "foo" other-obarray))
2078                => foo
2079           (eq sym 'foo)
2080                => nil
2081
2082  - Function: intern-soft name &optional obarray
2083      This function returns the symbol in OBARRAY whose name is NAME, or
2084      `nil' if OBARRAY has no symbol with that name.  Therefore, you can
2085      use `intern-soft' to test whether a symbol with a given name is
2086      already interned.  If OBARRAY is omitted, the value of the global
2087      variable `obarray' is used.
2088
2089           (intern-soft "frazzle")        ; No such symbol exists.
2090                => nil
2091           (make-symbol "frazzle")        ; Create an uninterned one.
2092                => frazzle
2093           (intern-soft "frazzle")        ; That one cannot be found.
2094                => nil
2095           (setq sym (intern "frazzle"))  ; Create an interned one.
2096                => frazzle
2097           (intern-soft "frazzle")        ; That one can be found!
2098                => frazzle
2099           (eq sym 'frazzle)              ; And it is the same one.
2100                => t
2101
2102  - Variable: obarray
2103      This variable is the standard obarray for use by `intern' and
2104      `read'.
2105
2106  - Function: mapatoms function &optional obarray
2107      This function calls FUNCTION for each symbol in the obarray
2108      OBARRAY.  It returns `nil'.  If OBARRAY is omitted, it defaults to
2109      the value of `obarray', the standard obarray for ordinary symbols.
2110
2111           (setq count 0)
2112                => 0
2113           (defun count-syms (s)
2114             (setq count (1+ count)))
2115                => count-syms
2116           (mapatoms 'count-syms)
2117                => nil
2118           count
2119                => 1871
2120
2121      See `documentation' in *Note Accessing Documentation::, for another
2122      example using `mapatoms'.
2123
2124  - Function: unintern symbol &optional obarray
2125      This function deletes SYMBOL from the obarray OBARRAY.  If
2126      `symbol' is not actually in the obarray, `unintern' does nothing.
2127      If OBARRAY is `nil', the current obarray is used.
2128
2129      If you provide a string instead of a symbol as SYMBOL, it stands
2130      for a symbol name.  Then `unintern' deletes the symbol (if any) in
2131      the obarray which has that name.  If there is no such symbol,
2132      `unintern' does nothing.
2133
2134      If `unintern' does delete a symbol, it returns `t'.  Otherwise it
2135      returns `nil'.
2136
2137 \1f
2138 File: lispref.info,  Node: Symbol Properties,  Prev: Creating Symbols,  Up: Symbols
2139
2140 Symbol Properties
2141 =================
2142
2143 A "property list" ("plist" for short) is a list of paired elements,
2144 often stored in the property list cell of a symbol.  Each of the pairs
2145 associates a property name (usually a symbol) with a property or value.
2146 Property lists are generally used to record information about a
2147 symbol, such as its documentation as a variable, the name of the file
2148 where it was defined, or perhaps even the grammatical class of the
2149 symbol (representing a word) in a language-understanding system.
2150
2151    Some objects which are not symbols also have property lists
2152 associated with them, and XEmacs provides a full complement of
2153 functions for working with property lists.  *Note Property Lists::.
2154
2155    The property names and values in a property list can be any Lisp
2156 objects, but the names are usually symbols.  They are compared using
2157 `eq'.  Here is an example of a property list, found on the symbol
2158 `progn' when the compiler is loaded:
2159
2160      (lisp-indent-function 0 byte-compile byte-compile-progn)
2161
2162 Here `lisp-indent-function' and `byte-compile' are property names, and
2163 the other two elements are the corresponding values.
2164
2165 * Menu:
2166
2167 * Plists and Alists::           Comparison of the advantages of property
2168                                   lists and association lists.
2169 * Object Plists::               Functions to access objects' property lists.
2170 * Other Plists::                Accessing property lists stored elsewhere.
2171
2172 \1f
2173 File: lispref.info,  Node: Plists and Alists,  Next: Object Plists,  Up: Symbol Properties
2174
2175 Property Lists and Association Lists
2176 ------------------------------------
2177
2178 Association lists (*note Association Lists::) are very similar to
2179 property lists.  In contrast to association lists, the order of the
2180 pairs in the property list is not significant since the property names
2181 must be distinct.
2182
2183    Property lists are better than association lists for attaching
2184 information to various Lisp function names or variables.  If all the
2185 associations are recorded in one association list, the program will need
2186 to search that entire list each time a function or variable is to be
2187 operated on.  By contrast, if the information is recorded in the
2188 property lists of the function names or variables themselves, each
2189 search will scan only the length of one property list, which is usually
2190 short.  This is why the documentation for a variable is recorded in a
2191 property named `variable-documentation'.  The byte compiler likewise
2192 uses properties to record those functions needing special treatment.
2193
2194    However, association lists have their own advantages.  Depending on
2195 your application, it may be faster to add an association to the front of
2196 an association list than to update a property.  All properties for a
2197 symbol are stored in the same property list, so there is a possibility
2198 of a conflict between different uses of a property name.  (For this
2199 reason, it is a good idea to choose property names that are probably
2200 unique, such as by including the name of the library in the property
2201 name.)  An association list may be used like a stack where associations
2202 are pushed on the front of the list and later discarded; this is not
2203 possible with a property list.
2204
2205 \1f
2206 File: lispref.info,  Node: Object Plists,  Next: Other Plists,  Prev: Plists and Alists,  Up: Symbol Properties
2207
2208 Property List Functions for Objects
2209 -----------------------------------
2210
2211 Once upon a time, only symbols had property lists.  Now, several other
2212 object types, including strings, extents, faces and glyphs also have
2213 property lists.
2214
2215  - Function: symbol-plist symbol
2216      This function returns the property list of SYMBOL.
2217
2218  - Function: object-plist object
2219      This function returns the property list of OBJECT.  If OBJECT is a
2220      symbol, this is identical to `symbol-plist'.
2221
2222  - Function: setplist symbol plist
2223      This function sets SYMBOL's property list to PLIST.  Normally,
2224      PLIST should be a well-formed property list, but this is not
2225      enforced.
2226
2227           (setplist 'foo '(a 1 b (2 3) c nil))
2228                => (a 1 b (2 3) c nil)
2229           (symbol-plist 'foo)
2230                => (a 1 b (2 3) c nil)
2231
2232      For symbols in special obarrays, which are not used for ordinary
2233      purposes, it may make sense to use the property list cell in a
2234      nonstandard fashion; in fact, the abbrev mechanism does so (*note
2235      Abbrevs::).  But generally, its use is discouraged.  Use `put'
2236      instead.  `setplist' can only be used with symbols, not other
2237      object types.
2238
2239  - Function: get object property &optional default
2240      This function finds the value of the property named PROPERTY in
2241      OBJECT's property list.  If there is no such property, `default'
2242      (which itself defaults to `nil') is returned.
2243
2244      PROPERTY is compared with the existing properties using `eq', so
2245      any object is a legitimate property.
2246
2247      See `put' for an example.
2248
2249  - Function: put object property value
2250      This function puts VALUE onto OBJECT's property list under the
2251      property name PROPERTY, replacing any previous property value.
2252      The `put' function returns VALUE.
2253
2254           (put 'fly 'verb 'transitive)
2255                =>'transitive
2256           (put 'fly 'noun '(a buzzing little bug))
2257                => (a buzzing little bug)
2258           (get 'fly 'verb)
2259                => transitive
2260           (object-plist 'fly)
2261                => (verb transitive noun (a buzzing little bug))
2262
2263  - Function: remprop object property
2264      This function removes the entry for PROPERTY from the property
2265      list of OBJECT.  It returns `t' if the property was indeed found
2266      and removed, or `nil' if there was no such property.  (This
2267      function was probably omitted from Emacs originally because, since
2268      `get' did not allow a DEFAULT, it was very difficult to
2269      distinguish between a missing property and a property whose value
2270      was `nil'; thus, setting a property to `nil' was close enough to
2271      `remprop' for most purposes.)
2272
2273 \1f
2274 File: lispref.info,  Node: Other Plists,  Prev: Object Plists,  Up: Symbol Properties
2275
2276 Property Lists Not Associated with Objects
2277 ------------------------------------------
2278
2279 These functions are useful for manipulating property lists that are
2280 stored in places other than symbols:
2281
2282  - Function: getf plist property &optional default
2283      This returns the value of the PROPERTY property stored in the
2284      property list PLIST.  For example,
2285
2286           (getf '(foo 4) 'foo)
2287                => 4
2288
2289  - Macro: putf plist property value
2290      This stores VALUE as the value of the PROPERTY property in the
2291      property list PLIST.  It may modify PLIST destructively, or it may
2292      construct a new list structure without altering the old.  The
2293      function returns the modified property list, so you can store that
2294      back in the place where you got PLIST.  For example,
2295
2296           (setq my-plist '(bar t foo 4))
2297                => (bar t foo 4)
2298           (setq my-plist (putf my-plist 'foo 69))
2299                => (bar t foo 69)
2300           (setq my-plist (putf my-plist 'quux '(a)))
2301                => (quux (a) bar t foo 5)
2302
2303  - Function: plists-eq a b
2304      This function returns non-`nil' if property lists A and B are
2305      `eq'.  This means that the property lists have the same values for
2306      all the same properties, where comparison between values is done
2307      using `eq'.
2308
2309  - Function: plists-equal a b
2310      This function returns non-`nil' if property lists A and B are
2311      `equal'.
2312
2313    Both of the above functions do order-insensitive comparisons.
2314
2315      (plists-eq '(a 1 b 2 c nil) '(b 2 a 1))
2316           => t
2317      (plists-eq '(foo "hello" bar "goodbye") '(bar "goodbye" foo "hello"))
2318           => nil
2319      (plists-equal '(foo "hello" bar "goodbye") '(bar "goodbye" foo "hello"))
2320           => t
2321
2322 \1f
2323 File: lispref.info,  Node: Evaluation,  Next: Control Structures,  Prev: Symbols,  Up: Top
2324
2325 Evaluation
2326 **********
2327
2328 The "evaluation" of expressions in XEmacs Lisp is performed by the
2329 "Lisp interpreter"--a program that receives a Lisp object as input and
2330 computes its "value as an expression".  How it does this depends on the
2331 data type of the object, according to rules described in this chapter.
2332 The interpreter runs automatically to evaluate portions of your
2333 program, but can also be called explicitly via the Lisp primitive
2334 function `eval'.
2335
2336 * Menu:
2337
2338 * Intro Eval::  Evaluation in the scheme of things.
2339 * Eval::        How to invoke the Lisp interpreter explicitly.
2340 * Forms::       How various sorts of objects are evaluated.
2341 * Quoting::     Avoiding evaluation (to put constants in the program).
2342
2343 \1f
2344 File: lispref.info,  Node: Intro Eval,  Next: Eval,  Up: Evaluation
2345
2346 Introduction to Evaluation
2347 ==========================
2348
2349 The Lisp interpreter, or evaluator, is the program that computes the
2350 value of an expression that is given to it.  When a function written in
2351 Lisp is called, the evaluator computes the value of the function by
2352 evaluating the expressions in the function body.  Thus, running any
2353 Lisp program really means running the Lisp interpreter.
2354
2355    How the evaluator handles an object depends primarily on the data
2356 type of the object.
2357
2358    A Lisp object that is intended for evaluation is called an
2359 "expression" or a "form".  The fact that expressions are data objects
2360 and not merely text is one of the fundamental differences between
2361 Lisp-like languages and typical programming languages.  Any object can
2362 be evaluated, but in practice only numbers, symbols, lists and strings
2363 are evaluated very often.
2364
2365    It is very common to read a Lisp expression and then evaluate the
2366 expression, but reading and evaluation are separate activities, and
2367 either can be performed alone.  Reading per se does not evaluate
2368 anything; it converts the printed representation of a Lisp object to the
2369 object itself.  It is up to the caller of `read' whether this object is
2370 a form to be evaluated, or serves some entirely different purpose.
2371 *Note Input Functions::.
2372
2373    Do not confuse evaluation with command key interpretation.  The
2374 editor command loop translates keyboard input into a command (an
2375 interactively callable function) using the active keymaps, and then
2376 uses `call-interactively' to invoke the command.  The execution of the
2377 command itself involves evaluation if the command is written in Lisp,
2378 but that is not a part of command key interpretation itself.  *Note
2379 Command Loop::.
2380
2381    Evaluation is a recursive process.  That is, evaluation of a form may
2382 call `eval' to evaluate parts of the form.  For example, evaluation of
2383 a function call first evaluates each argument of the function call, and
2384 then evaluates each form in the function body.  Consider evaluation of
2385 the form `(car x)': the subform `x' must first be evaluated
2386 recursively, so that its value can be passed as an argument to the
2387 function `car'.
2388
2389    Evaluation of a function call ultimately calls the function specified
2390 in it.  *Note Functions::.  The execution of the function may itself
2391 work by evaluating the function definition; or the function may be a
2392 Lisp primitive implemented in C, or it may be a byte-compiled function
2393 (*note Byte Compilation::).
2394
2395    The evaluation of forms takes place in a context called the
2396 "environment", which consists of the current values and bindings of all
2397 Lisp variables.(1)  Whenever the form refers to a variable without
2398 creating a new binding for it, the value of the binding in the current
2399 environment is used.  *Note Variables::.
2400
2401    Evaluation of a form may create new environments for recursive
2402 evaluation by binding variables (*note Local Variables::).  These
2403 environments are temporary and vanish by the time evaluation of the form
2404 is complete.  The form may also make changes that persist; these changes
2405 are called "side effects".  An example of a form that produces side
2406 effects is `(setq foo 1)'.
2407
2408    The details of what evaluation means for each kind of form are
2409 described below (*note Forms::).
2410
2411    ---------- Footnotes ----------
2412
2413    (1) This definition of "environment" is specifically not intended to
2414 include all the data that can affect the result of a program.
2415
2416 \1f
2417 File: lispref.info,  Node: Eval,  Next: Forms,  Prev: Intro Eval,  Up: Evaluation
2418
2419 Eval
2420 ====
2421
2422 Most often, forms are evaluated automatically, by virtue of their
2423 occurrence in a program being run.  On rare occasions, you may need to
2424 write code that evaluates a form that is computed at run time, such as
2425 after reading a form from text being edited or getting one from a
2426 property list.  On these occasions, use the `eval' function.
2427
2428    *Please note:* it is generally cleaner and more flexible to call
2429 functions that are stored in data structures, rather than to evaluate
2430 expressions stored in data structures.  Using functions provides the
2431 ability to pass information to them as arguments.
2432
2433    The functions and variables described in this section evaluate forms,
2434 specify limits to the evaluation process, or record recently returned
2435 values.  Loading a file also does evaluation (*note Loading::).
2436
2437  - Function: eval form
2438      This is the basic function for performing evaluation.  It evaluates
2439      FORM in the current environment and returns the result.  How the
2440      evaluation proceeds depends on the type of the object (*note
2441      Forms::).
2442
2443      Since `eval' is a function, the argument expression that appears
2444      in a call to `eval' is evaluated twice: once as preparation before
2445      `eval' is called, and again by the `eval' function itself.  Here
2446      is an example:
2447
2448           (setq foo 'bar)
2449                => bar
2450           (setq bar 'baz)
2451                => baz
2452           ;; `eval' receives argument `bar', which is the value of `foo'
2453           (eval foo)
2454                => baz
2455           (eval 'foo)
2456                => bar
2457
2458      The number of currently active calls to `eval' is limited to
2459      `max-lisp-eval-depth' (see below).
2460
2461  - Command: eval-region start end &optional stream
2462      This function evaluates the forms in the current buffer in the
2463      region defined by the positions START and END.  It reads forms from
2464      the region and calls `eval' on them until the end of the region is
2465      reached, or until an error is signaled and not handled.
2466
2467      If STREAM is supplied, `standard-output' is bound to it during the
2468      evaluation.
2469
2470      You can use the variable `load-read-function' to specify a function
2471      for `eval-region' to use instead of `read' for reading
2472      expressions.  *Note How Programs Do Loading::.
2473
2474      `eval-region' always returns `nil'.
2475
2476  - Command: eval-buffer buffer &optional stream
2477      This is like `eval-region' except that it operates on the whole
2478      contents of BUFFER.
2479
2480  - Variable: max-lisp-eval-depth
2481      This variable defines the maximum depth allowed in calls to `eval',
2482      `apply', and `funcall' before an error is signaled (with error
2483      message `"Lisp nesting exceeds max-lisp-eval-depth"').  This counts
2484      internal uses of those functions, such as for calling the functions
2485      mentioned in Lisp expressions, and recursive evaluation of
2486      function call arguments and function body forms.
2487
2488      This limit, with the associated error when it is exceeded, is one
2489      way that Lisp avoids infinite recursion on an ill-defined function.
2490
2491      The default value of this variable is 1000.  If you set it to a
2492      value less than 100, Lisp will reset it to 100 if the given value
2493      is reached.
2494
2495      `max-specpdl-size' provides another limit on nesting.  *Note Local
2496      Variables::.
2497
2498  - Variable: values
2499      The value of this variable is a list of the values returned by all
2500      the expressions that were read from buffers (including the
2501      minibuffer), evaluated, and printed.  The elements are ordered
2502      most recent first.
2503
2504           (setq x 1)
2505                => 1
2506           (list 'A (1+ 2) auto-save-default)
2507                => (A 3 t)
2508           values
2509                => ((A 3 t) 1 ...)
2510
2511      This variable is useful for referring back to values of forms
2512      recently evaluated.  It is generally a bad idea to print the value
2513      of `values' itself, since this may be very long.  Instead, examine
2514      particular elements, like this:
2515
2516           ;; Refer to the most recent evaluation result.
2517           (nth 0 values)
2518                => (A 3 t)
2519           ;; That put a new element on,
2520           ;;   so all elements move back one.
2521           (nth 1 values)
2522                => (A 3 t)
2523           ;; This gets the element that was next-to-most-recent
2524           ;;   before this example.
2525           (nth 3 values)
2526                => 1
2527
2528 \1f
2529 File: lispref.info,  Node: Forms,  Next: Quoting,  Prev: Eval,  Up: Evaluation
2530
2531 Kinds of Forms
2532 ==============
2533
2534 A Lisp object that is intended to be evaluated is called a "form".  How
2535 XEmacs evaluates a form depends on its data type.  XEmacs has three
2536 different kinds of form that are evaluated differently: symbols, lists,
2537 and "all other types".  This section describes all three kinds,
2538 starting with "all other types" which are self-evaluating forms.
2539
2540 * Menu:
2541
2542 * Self-Evaluating Forms::   Forms that evaluate to themselves.
2543 * Symbol Forms::            Symbols evaluate as variables.
2544 * Classifying Lists::       How to distinguish various sorts of list forms.
2545 * Function Indirection::    When a symbol appears as the car of a list,
2546                               we find the real function via the symbol.
2547 * Function Forms::          Forms that call functions.
2548 * Macro Forms::             Forms that call macros.
2549 * Special Forms::           ``Special forms'' are idiosyncratic primitives,
2550                               most of them extremely important.
2551 * Autoloading::             Functions set up to load files
2552                               containing their real definitions.
2553
2554 \1f
2555 File: lispref.info,  Node: Self-Evaluating Forms,  Next: Symbol Forms,  Up: Forms
2556
2557 Self-Evaluating Forms
2558 ---------------------
2559
2560 A "self-evaluating form" is any form that is not a list or symbol.
2561 Self-evaluating forms evaluate to themselves: the result of evaluation
2562 is the same object that was evaluated.  Thus, the number 25 evaluates to
2563 25, and the string `"foo"' evaluates to the string `"foo"'.  Likewise,
2564 evaluation of a vector does not cause evaluation of the elements of the
2565 vector--it returns the same vector with its contents unchanged.
2566
2567      '123               ; An object, shown without evaluation.
2568           => 123
2569      123                ; Evaluated as usual--result is the same.
2570           => 123
2571      (eval '123)        ; Evaluated "by hand"--result is the same.
2572           => 123
2573      (eval (eval '123)) ; Evaluating twice changes nothing.
2574           => 123
2575
2576    It is common to write numbers, characters, strings, and even vectors
2577 in Lisp code, taking advantage of the fact that they self-evaluate.
2578 However, it is quite unusual to do this for types that lack a read
2579 syntax, because there's no way to write them textually.  It is possible
2580 to construct Lisp expressions containing these types by means of a Lisp
2581 program.  Here is an example:
2582
2583      ;; Build an expression containing a buffer object.
2584      (setq buffer (list 'print (current-buffer)))
2585           => (print #<buffer eval.texi>)
2586      ;; Evaluate it.
2587      (eval buffer)
2588           -| #<buffer eval.texi>
2589           => #<buffer eval.texi>
2590
2591 \1f
2592 File: lispref.info,  Node: Symbol Forms,  Next: Classifying Lists,  Prev: Self-Evaluating Forms,  Up: Forms
2593
2594 Symbol Forms
2595 ------------
2596
2597 When a symbol is evaluated, it is treated as a variable.  The result is
2598 the variable's value, if it has one.  If it has none (if its value cell
2599 is void), an error is signaled.  For more information on the use of
2600 variables, see *Note Variables::.
2601
2602    In the following example, we set the value of a symbol with `setq'.
2603 Then we evaluate the symbol, and get back the value that `setq' stored.
2604
2605      (setq a 123)
2606           => 123
2607      (eval 'a)
2608           => 123
2609      a
2610           => 123
2611
2612    The symbols `nil' and `t' are treated specially, so that the value
2613 of `nil' is always `nil', and the value of `t' is always `t'; you
2614 cannot set or bind them to any other values.  Thus, these two symbols
2615 act like self-evaluating forms, even though `eval' treats them like any
2616 other symbol.
2617
2618 \1f
2619 File: lispref.info,  Node: Classifying Lists,  Next: Function Indirection,  Prev: Symbol Forms,  Up: Forms
2620
2621 Classification of List Forms
2622 ----------------------------
2623
2624 A form that is a nonempty list is either a function call, a macro call,
2625 or a special form, according to its first element.  These three kinds
2626 of forms are evaluated in different ways, described below.  The
2627 remaining list elements constitute the "arguments" for the function,
2628 macro, or special form.
2629
2630    The first step in evaluating a nonempty list is to examine its first
2631 element.  This element alone determines what kind of form the list is
2632 and how the rest of the list is to be processed.  The first element is
2633 _not_ evaluated, as it would be in some Lisp dialects such as Scheme.
2634
2635 \1f
2636 File: lispref.info,  Node: Function Indirection,  Next: Function Forms,  Prev: Classifying Lists,  Up: Forms
2637
2638 Symbol Function Indirection
2639 ---------------------------
2640
2641 If the first element of the list is a symbol then evaluation examines
2642 the symbol's function cell, and uses its contents instead of the
2643 original symbol.  If the contents are another symbol, this process,
2644 called "symbol function indirection", is repeated until it obtains a
2645 non-symbol.  *Note Function Names::, for more information about using a
2646 symbol as a name for a function stored in the function cell of the
2647 symbol.
2648
2649    One possible consequence of this process is an infinite loop, in the
2650 event that a symbol's function cell refers to the same symbol.  Or a
2651 symbol may have a void function cell, in which case the subroutine
2652 `symbol-function' signals a `void-function' error.  But if neither of
2653 these things happens, we eventually obtain a non-symbol, which ought to
2654 be a function or other suitable object.
2655
2656    More precisely, we should now have a Lisp function (a lambda
2657 expression), a byte-code function, a primitive function, a Lisp macro, a
2658 special form, or an autoload object.  Each of these types is a case
2659 described in one of the following sections.  If the object is not one of
2660 these types, the error `invalid-function' is signaled.
2661
2662    The following example illustrates the symbol indirection process.  We
2663 use `fset' to set the function cell of a symbol and `symbol-function'
2664 to get the function cell contents (*note Function Cells::).
2665 Specifically, we store the symbol `car' into the function cell of
2666 `first', and the symbol `first' into the function cell of `erste'.
2667
2668      ;; Build this function cell linkage:
2669      ;;   -------------       -----        -------        -------
2670      ;;  | #<subr car> | <-- | car |  <-- | first |  <-- | erste |
2671      ;;   -------------       -----        -------        -------
2672
2673      (symbol-function 'car)
2674           => #<subr car>
2675      (fset 'first 'car)
2676           => car
2677      (fset 'erste 'first)
2678           => first
2679      (erste '(1 2 3))   ; Call the function referenced by `erste'.
2680           => 1
2681
2682    By contrast, the following example calls a function without any
2683 symbol function indirection, because the first element is an anonymous
2684 Lisp function, not a symbol.
2685
2686      ((lambda (arg) (erste arg))
2687       '(1 2 3))
2688           => 1
2689
2690 Executing the function itself evaluates its body; this does involve
2691 symbol function indirection when calling `erste'.
2692
2693    The built-in function `indirect-function' provides an easy way to
2694 perform symbol function indirection explicitly.
2695
2696  - Function: indirect-function object
2697      This function returns the meaning of OBJECT as a function.  If
2698      OBJECT is a symbol, then it finds OBJECT's function definition and
2699      starts over with that value.  If OBJECT is not a symbol, then it
2700      returns OBJECT itself.
2701
2702      Here is how you could define `indirect-function' in Lisp:
2703
2704           (defun indirect-function (function)
2705             (if (symbolp function)
2706                 (indirect-function (symbol-function function))
2707               function))
2708
2709 \1f
2710 File: lispref.info,  Node: Function Forms,  Next: Macro Forms,  Prev: Function Indirection,  Up: Forms
2711
2712 Evaluation of Function Forms
2713 ----------------------------
2714
2715 If the first element of a list being evaluated is a Lisp function
2716 object, byte-code object or primitive function object, then that list is
2717 a "function call".  For example, here is a call to the function `+':
2718
2719      (+ 1 x)
2720
2721    The first step in evaluating a function call is to evaluate the
2722 remaining elements of the list from left to right.  The results are the
2723 actual argument values, one value for each list element.  The next step
2724 is to call the function with this list of arguments, effectively using
2725 the function `apply' (*note Calling Functions::).  If the function is
2726 written in Lisp, the arguments are used to bind the argument variables
2727 of the function (*note Lambda Expressions::); then the forms in the
2728 function body are evaluated in order, and the value of the last body
2729 form becomes the value of the function call.
2730
2731 \1f
2732 File: lispref.info,  Node: Macro Forms,  Next: Special Forms,  Prev: Function Forms,  Up: Forms
2733
2734 Lisp Macro Evaluation
2735 ---------------------
2736
2737 If the first element of a list being evaluated is a macro object, then
2738 the list is a "macro call".  When a macro call is evaluated, the
2739 elements of the rest of the list are _not_ initially evaluated.
2740 Instead, these elements themselves are used as the arguments of the
2741 macro.  The macro definition computes a replacement form, called the
2742 "expansion" of the macro, to be evaluated in place of the original
2743 form.  The expansion may be any sort of form: a self-evaluating
2744 constant, a symbol, or a list.  If the expansion is itself a macro call,
2745 this process of expansion repeats until some other sort of form results.
2746
2747    Ordinary evaluation of a macro call finishes by evaluating the
2748 expansion.  However, the macro expansion is not necessarily evaluated
2749 right away, or at all, because other programs also expand macro calls,
2750 and they may or may not evaluate the expansions.
2751
2752    Normally, the argument expressions are not evaluated as part of
2753 computing the macro expansion, but instead appear as part of the
2754 expansion, so they are computed when the expansion is computed.
2755
2756    For example, given a macro defined as follows:
2757
2758      (defmacro cadr (x)
2759        (list 'car (list 'cdr x)))
2760
2761 an expression such as `(cadr (assq 'handler list))' is a macro call,
2762 and its expansion is:
2763
2764      (car (cdr (assq 'handler list)))
2765
2766 Note that the argument `(assq 'handler list)' appears in the expansion.
2767
2768    *Note Macros::, for a complete description of XEmacs Lisp macros.
2769
2770 \1f
2771 File: lispref.info,  Node: Special Forms,  Next: Autoloading,  Prev: Macro Forms,  Up: Forms
2772
2773 Special Forms
2774 -------------
2775
2776 A "special form" is a primitive function specially marked so that its
2777 arguments are not all evaluated.  Most special forms define control
2778 structures or perform variable bindings--things which functions cannot
2779 do.
2780
2781    Each special form has its own rules for which arguments are evaluated
2782 and which are used without evaluation.  Whether a particular argument is
2783 evaluated may depend on the results of evaluating other arguments.
2784
2785    Here is a list, in alphabetical order, of all of the special forms in
2786 XEmacs Lisp with a reference to where each is described.
2787
2788 `and'
2789      *note Combining Conditions::
2790
2791 `catch'
2792      *note Catch and Throw::
2793
2794 `cond'
2795      *note Conditionals::
2796
2797 `condition-case'
2798      *note Handling Errors::
2799
2800 `defconst'
2801      *note Defining Variables::
2802
2803 `defmacro'
2804      *note Defining Macros::
2805
2806 `defun'
2807      *note Defining Functions::
2808
2809 `defvar'
2810      *note Defining Variables::
2811
2812 `function'
2813      *note Anonymous Functions::
2814
2815 `if'
2816      *note Conditionals::
2817
2818 `interactive'
2819      *note Interactive Call::
2820
2821 `let'
2822 `let*'
2823      *note Local Variables::
2824
2825 `or'
2826      *note Combining Conditions::
2827
2828 `prog1'
2829 `prog2'
2830 `progn'
2831      *note Sequencing::
2832
2833 `quote'
2834      *note Quoting::
2835
2836 `save-current-buffer'
2837      *note Excursions::
2838
2839 `save-excursion'
2840      *note Excursions::
2841
2842 `save-restriction'
2843      *note Narrowing::
2844
2845 `save-selected-window'
2846      *note Excursions::
2847
2848 `save-window-excursion'
2849      *note Window Configurations::
2850
2851 `setq'
2852      *note Setting Variables::
2853
2854 `setq-default'
2855      *note Creating Buffer-Local::
2856
2857 `unwind-protect'
2858      *note Nonlocal Exits::
2859
2860 `while'
2861      *note Iteration::
2862
2863 `with-output-to-temp-buffer'
2864      *note Temporary Displays::
2865
2866      Common Lisp note: here are some comparisons of special forms in
2867      XEmacs Lisp and Common Lisp.  `setq', `if', and `catch' are
2868      special forms in both XEmacs Lisp and Common Lisp.  `defun' is a
2869      special form in XEmacs Lisp, but a macro in Common Lisp.
2870      `save-excursion' is a special form in XEmacs Lisp, but doesn't
2871      exist in Common Lisp.  `throw' is a special form in Common Lisp
2872      (because it must be able to throw multiple values), but it is a
2873      function in XEmacs Lisp (which doesn't have multiple values).
2874
2875 \1f
2876 File: lispref.info,  Node: Autoloading,  Prev: Special Forms,  Up: Forms
2877
2878 Autoloading
2879 -----------
2880
2881 The "autoload" feature allows you to call a function or macro whose
2882 function definition has not yet been loaded into XEmacs.  It specifies
2883 which file contains the definition.  When an autoload object appears as
2884 a symbol's function definition, calling that symbol as a function
2885 automatically loads the specified file; then it calls the real
2886 definition loaded from that file.  *Note Autoload::.
2887
2888 \1f
2889 File: lispref.info,  Node: Quoting,  Prev: Forms,  Up: Evaluation
2890
2891 Quoting
2892 =======
2893
2894 The special form `quote' returns its single argument, as written,
2895 without evaluating it.  This provides a way to include constant symbols
2896 and lists, which are not self-evaluating objects, in a program.  (It is
2897 not necessary to quote self-evaluating objects such as numbers, strings,
2898 and vectors.)
2899
2900  - Special Form: quote object
2901      This special form returns OBJECT, without evaluating it.
2902
2903    Because `quote' is used so often in programs, Lisp provides a
2904 convenient read syntax for it.  An apostrophe character (`'') followed
2905 by a Lisp object (in read syntax) expands to a list whose first element
2906 is `quote', and whose second element is the object.  Thus, the read
2907 syntax `'x' is an abbreviation for `(quote x)'.
2908
2909    Here are some examples of expressions that use `quote':
2910
2911      (quote (+ 1 2))
2912           => (+ 1 2)
2913      (quote foo)
2914           => foo
2915      'foo
2916           => foo
2917      ''foo
2918           => (quote foo)
2919      '(quote foo)
2920           => (quote foo)
2921      ['foo]
2922           => [(quote foo)]
2923
2924    Other quoting constructs include `function' (*note Anonymous
2925 Functions::), which causes an anonymous lambda expression written in
2926 Lisp to be compiled, and ``' (*note Backquote::), which is used to quote
2927 only part of a list, while computing and substituting other parts.
2928
2929 \1f
2930 File: lispref.info,  Node: Control Structures,  Next: Variables,  Prev: Evaluation,  Up: Top
2931
2932 Control Structures
2933 ******************
2934
2935 A Lisp program consists of expressions or "forms" (*note Forms::).  We
2936 control the order of execution of the forms by enclosing them in
2937 "control structures".  Control structures are special forms which
2938 control when, whether, or how many times to execute the forms they
2939 contain.
2940
2941    The simplest order of execution is sequential execution: first form
2942 A, then form B, and so on.  This is what happens when you write several
2943 forms in succession in the body of a function, or at top level in a
2944 file of Lisp code--the forms are executed in the order written.  We
2945 call this "textual order".  For example, if a function body consists of
2946 two forms A and B, evaluation of the function evaluates first A and
2947 then B, and the function's value is the value of B.
2948
2949    Explicit control structures make possible an order of execution other
2950 than sequential.
2951
2952    XEmacs Lisp provides several kinds of control structure, including
2953 other varieties of sequencing, conditionals, iteration, and (controlled)
2954 jumps--all discussed below.  The built-in control structures are
2955 special forms since their subforms are not necessarily evaluated or not
2956 evaluated sequentially.  You can use macros to define your own control
2957 structure constructs (*note Macros::).
2958
2959 * Menu:
2960
2961 * Sequencing::             Evaluation in textual order.
2962 * Conditionals::           `if', `cond'.
2963 * Combining Conditions::   `and', `or', `not'.
2964 * Iteration::              `while' loops.
2965 * Nonlocal Exits::         Jumping out of a sequence.
2966
2967 \1f
2968 File: lispref.info,  Node: Sequencing,  Next: Conditionals,  Up: Control Structures
2969
2970 Sequencing
2971 ==========
2972
2973 Evaluating forms in the order they appear is the most common way
2974 control passes from one form to another.  In some contexts, such as in a
2975 function body, this happens automatically.  Elsewhere you must use a
2976 control structure construct to do this: `progn', the simplest control
2977 construct of Lisp.
2978
2979    A `progn' special form looks like this:
2980
2981      (progn A B C ...)
2982
2983 and it says to execute the forms A, B, C and so on, in that order.
2984 These forms are called the body of the `progn' form.  The value of the
2985 last form in the body becomes the value of the entire `progn'.
2986
2987    In the early days of Lisp, `progn' was the only way to execute two
2988 or more forms in succession and use the value of the last of them.  But
2989 programmers found they often needed to use a `progn' in the body of a
2990 function, where (at that time) only one form was allowed.  So the body
2991 of a function was made into an "implicit `progn'": several forms are
2992 allowed just as in the body of an actual `progn'.  Many other control
2993 structures likewise contain an implicit `progn'.  As a result, `progn'
2994 is not used as often as it used to be.  It is needed now most often
2995 inside an `unwind-protect', `and', `or', or in the THEN-part of an `if'.
2996
2997  - Special Form: progn forms...
2998      This special form evaluates all of the FORMS, in textual order,
2999      returning the result of the final form.
3000
3001           (progn (print "The first form")
3002                  (print "The second form")
3003                  (print "The third form"))
3004                -| "The first form"
3005                -| "The second form"
3006                -| "The third form"
3007           => "The third form"
3008
3009    Two other control constructs likewise evaluate a series of forms but
3010 return a different value:
3011
3012  - Special Form: prog1 form1 forms...
3013      This special form evaluates FORM1 and all of the FORMS, in textual
3014      order, returning the result of FORM1.
3015
3016           (prog1 (print "The first form")
3017                  (print "The second form")
3018                  (print "The third form"))
3019                -| "The first form"
3020                -| "The second form"
3021                -| "The third form"
3022           => "The first form"
3023
3024      Here is a way to remove the first element from a list in the
3025      variable `x', then return the value of that former element:
3026
3027           (prog1 (car x) (setq x (cdr x)))
3028
3029  - Special Form: prog2 form1 form2 forms...
3030      This special form evaluates FORM1, FORM2, and all of the following
3031      FORMS, in textual order, returning the result of FORM2.
3032
3033           (prog2 (print "The first form")
3034                  (print "The second form")
3035                  (print "The third form"))
3036                -| "The first form"
3037                -| "The second form"
3038                -| "The third form"
3039           => "The second form"
3040
3041 \1f
3042 File: lispref.info,  Node: Conditionals,  Next: Combining Conditions,  Prev: Sequencing,  Up: Control Structures
3043
3044 Conditionals
3045 ============
3046
3047 Conditional control structures choose among alternatives.  XEmacs Lisp
3048 has two conditional forms: `if', which is much the same as in other
3049 languages, and `cond', which is a generalized case statement.
3050
3051  - Special Form: if condition then-form else-forms...
3052      `if' chooses between the THEN-FORM and the ELSE-FORMS based on the
3053      value of CONDITION.  If the evaluated CONDITION is non-`nil',
3054      THEN-FORM is evaluated and the result returned.  Otherwise, the
3055      ELSE-FORMS are evaluated in textual order, and the value of the
3056      last one is returned.  (The ELSE part of `if' is an example of an
3057      implicit `progn'.  *Note Sequencing::.)
3058
3059      If CONDITION has the value `nil', and no ELSE-FORMS are given,
3060      `if' returns `nil'.
3061
3062      `if' is a special form because the branch that is not selected is
3063      never evaluated--it is ignored.  Thus, in the example below,
3064      `true' is not printed because `print' is never called.
3065
3066           (if nil
3067               (print 'true)
3068             'very-false)
3069           => very-false
3070
3071  - Special Form: cond clause...
3072      `cond' chooses among an arbitrary number of alternatives.  Each
3073      CLAUSE in the `cond' must be a list.  The CAR of this list is the
3074      CONDITION; the remaining elements, if any, the BODY-FORMS.  Thus,
3075      a clause looks like this:
3076
3077           (CONDITION BODY-FORMS...)
3078
3079      `cond' tries the clauses in textual order, by evaluating the
3080      CONDITION of each clause.  If the value of CONDITION is non-`nil',
3081      the clause "succeeds"; then `cond' evaluates its BODY-FORMS, and
3082      the value of the last of BODY-FORMS becomes the value of the
3083      `cond'.  The remaining clauses are ignored.
3084
3085      If the value of CONDITION is `nil', the clause "fails", so the
3086      `cond' moves on to the following clause, trying its CONDITION.
3087
3088      If every CONDITION evaluates to `nil', so that every clause fails,
3089      `cond' returns `nil'.
3090
3091      A clause may also look like this:
3092
3093           (CONDITION)
3094
3095      Then, if CONDITION is non-`nil' when tested, the value of
3096      CONDITION becomes the value of the `cond' form.
3097
3098      The following example has four clauses, which test for the cases
3099      where the value of `x' is a number, string, buffer and symbol,
3100      respectively:
3101
3102           (cond ((numberp x) x)
3103                 ((stringp x) x)
3104                 ((bufferp x)
3105                  (setq temporary-hack x) ; multiple body-forms
3106                  (buffer-name x))        ; in one clause
3107                 ((symbolp x) (symbol-value x)))
3108
3109      Often we want to execute the last clause whenever none of the
3110      previous clauses was successful.  To do this, we use `t' as the
3111      CONDITION of the last clause, like this: `(t BODY-FORMS)'.  The
3112      form `t' evaluates to `t', which is never `nil', so this clause
3113      never fails, provided the `cond' gets to it at all.
3114
3115      For example,
3116
3117           (cond ((eq a 'hack) 'foo)
3118                 (t "default"))
3119           => "default"
3120
3121      This expression is a `cond' which returns `foo' if the value of
3122      `a' is 1, and returns the string `"default"' otherwise.
3123
3124    Any conditional construct can be expressed with `cond' or with `if'.
3125 Therefore, the choice between them is a matter of style.  For example:
3126
3127      (if A B C)
3128      ==
3129      (cond (A B) (t C))
3130
3131 \1f
3132 File: lispref.info,  Node: Combining Conditions,  Next: Iteration,  Prev: Conditionals,  Up: Control Structures
3133
3134 Constructs for Combining Conditions
3135 ===================================
3136
3137 This section describes three constructs that are often used together
3138 with `if' and `cond' to express complicated conditions.  The constructs
3139 `and' and `or' can also be used individually as kinds of multiple
3140 conditional constructs.
3141
3142  - Function: not condition
3143      This function tests for the falsehood of CONDITION.  It returns
3144      `t' if CONDITION is `nil', and `nil' otherwise.  The function
3145      `not' is identical to `null', and we recommend using the name
3146      `null' if you are testing for an empty list.
3147
3148  - Special Form: and conditions...
3149      The `and' special form tests whether all the CONDITIONS are true.
3150      It works by evaluating the CONDITIONS one by one in the order
3151      written.
3152
3153      If any of the CONDITIONS evaluates to `nil', then the result of
3154      the `and' must be `nil' regardless of the remaining CONDITIONS; so
3155      `and' returns right away, ignoring the remaining CONDITIONS.
3156
3157      If all the CONDITIONS turn out non-`nil', then the value of the
3158      last of them becomes the value of the `and' form.
3159
3160      Here is an example.  The first condition returns the integer 1,
3161      which is not `nil'.  Similarly, the second condition returns the
3162      integer 2, which is not `nil'.  The third condition is `nil', so
3163      the remaining condition is never evaluated.
3164
3165           (and (print 1) (print 2) nil (print 3))
3166                -| 1
3167                -| 2
3168           => nil
3169
3170      Here is a more realistic example of using `and':
3171
3172           (if (and (consp foo) (eq (car foo) 'x))
3173               (message "foo is a list starting with x"))
3174
3175      Note that `(car foo)' is not executed if `(consp foo)' returns
3176      `nil', thus avoiding an error.
3177
3178      `and' can be expressed in terms of either `if' or `cond'.  For
3179      example:
3180
3181           (and ARG1 ARG2 ARG3)
3182           ==
3183           (if ARG1 (if ARG2 ARG3))
3184           ==
3185           (cond (ARG1 (cond (ARG2 ARG3))))
3186
3187  - Special Form: or conditions...
3188      The `or' special form tests whether at least one of the CONDITIONS
3189      is true.  It works by evaluating all the CONDITIONS one by one in
3190      the order written.
3191
3192      If any of the CONDITIONS evaluates to a non-`nil' value, then the
3193      result of the `or' must be non-`nil'; so `or' returns right away,
3194      ignoring the remaining CONDITIONS.  The value it returns is the
3195      non-`nil' value of the condition just evaluated.
3196
3197      If all the CONDITIONS turn out `nil', then the `or' expression
3198      returns `nil'.
3199
3200      For example, this expression tests whether `x' is either 0 or
3201      `nil':
3202
3203           (or (eq x nil) (eq x 0))
3204
3205      Like the `and' construct, `or' can be written in terms of `cond'.
3206      For example:
3207
3208           (or ARG1 ARG2 ARG3)
3209           ==
3210           (cond (ARG1)
3211                 (ARG2)
3212                 (ARG3))
3213
3214      You could almost write `or' in terms of `if', but not quite:
3215
3216           (if ARG1 ARG1
3217             (if ARG2 ARG2
3218               ARG3))
3219
3220      This is not completely equivalent because it can evaluate ARG1 or
3221      ARG2 twice.  By contrast, `(or ARG1 ARG2 ARG3)' never evaluates
3222      any argument more than once.
3223
3224 \1f
3225 File: lispref.info,  Node: Iteration,  Next: Nonlocal Exits,  Prev: Combining Conditions,  Up: Control Structures
3226
3227 Iteration
3228 =========
3229
3230 Iteration means executing part of a program repetitively.  For example,
3231 you might want to repeat some computation once for each element of a
3232 list, or once for each integer from 0 to N.  You can do this in XEmacs
3233 Lisp with the special form `while':
3234
3235  - Special Form: while condition forms...
3236      `while' first evaluates CONDITION.  If the result is non-`nil', it
3237      evaluates FORMS in textual order.  Then it reevaluates CONDITION,
3238      and if the result is non-`nil', it evaluates FORMS again.  This
3239      process repeats until CONDITION evaluates to `nil'.
3240
3241      There is no limit on the number of iterations that may occur.  The
3242      loop will continue until either CONDITION evaluates to `nil' or
3243      until an error or `throw' jumps out of it (*note Nonlocal Exits::).
3244
3245      The value of a `while' form is always `nil'.
3246
3247           (setq num 0)
3248                => 0
3249           (while (< num 4)
3250             (princ (format "Iteration %d." num))
3251             (setq num (1+ num)))
3252                -| Iteration 0.
3253                -| Iteration 1.
3254                -| Iteration 2.
3255                -| Iteration 3.
3256                => nil
3257
3258      If you would like to execute something on each iteration before the
3259      end-test, put it together with the end-test in a `progn' as the
3260      first argument of `while', as shown here:
3261
3262           (while (progn
3263                    (forward-line 1)
3264                    (not (looking-at "^$"))))
3265
3266      This moves forward one line and continues moving by lines until it
3267      reaches an empty.  It is unusual in that the `while' has no body,
3268      just the end test (which also does the real work of moving point).
3269
3270 \1f
3271 File: lispref.info,  Node: Nonlocal Exits,  Prev: Iteration,  Up: Control Structures
3272
3273 Nonlocal Exits
3274 ==============
3275
3276 A "nonlocal exit" is a transfer of control from one point in a program
3277 to another remote point.  Nonlocal exits can occur in XEmacs Lisp as a
3278 result of errors; you can also use them under explicit control.
3279 Nonlocal exits unbind all variable bindings made by the constructs being
3280 exited.
3281
3282 * Menu:
3283
3284 * Catch and Throw::     Nonlocal exits for the program's own purposes.
3285 * Examples of Catch::   Showing how such nonlocal exits can be written.
3286 * Errors::              How errors are signaled and handled.
3287 * Cleanups::            Arranging to run a cleanup form if an error happens.
3288
3289 \1f
3290 File: lispref.info,  Node: Catch and Throw,  Next: Examples of Catch,  Up: Nonlocal Exits
3291
3292 Explicit Nonlocal Exits: `catch' and `throw'
3293 --------------------------------------------
3294
3295 Most control constructs affect only the flow of control within the
3296 construct itself.  The function `throw' is the exception to this rule
3297 of normal program execution: it performs a nonlocal exit on request.
3298 (There are other exceptions, but they are for error handling only.)
3299 `throw' is used inside a `catch', and jumps back to that `catch'.  For
3300 example:
3301
3302      (catch 'foo
3303        (progn
3304          ...
3305          (throw 'foo t)
3306          ...))
3307
3308 The `throw' transfers control straight back to the corresponding
3309 `catch', which returns immediately.  The code following the `throw' is
3310 not executed.  The second argument of `throw' is used as the return
3311 value of the `catch'.
3312
3313    The `throw' and the `catch' are matched through the first argument:
3314 `throw' searches for a `catch' whose first argument is `eq' to the one
3315 specified.  Thus, in the above example, the `throw' specifies `foo',
3316 and the `catch' specifies the same symbol, so that `catch' is
3317 applicable.  If there is more than one applicable `catch', the
3318 innermost one takes precedence.
3319
3320    Executing `throw' exits all Lisp constructs up to the matching
3321 `catch', including function calls.  When binding constructs such as
3322 `let' or function calls are exited in this way, the bindings are
3323 unbound, just as they are when these constructs exit normally (*note
3324 Local Variables::).  Likewise, `throw' restores the buffer and position
3325 saved by `save-excursion' (*note Excursions::), and the narrowing
3326 status saved by `save-restriction' and the window selection saved by
3327 `save-window-excursion' (*note Window Configurations::).  It also runs
3328 any cleanups established with the `unwind-protect' special form when it
3329 exits that form (*note Cleanups::).
3330
3331    The `throw' need not appear lexically within the `catch' that it
3332 jumps to.  It can equally well be called from another function called
3333 within the `catch'.  As long as the `throw' takes place chronologically
3334 after entry to the `catch', and chronologically before exit from it, it
3335 has access to that `catch'.  This is why `throw' can be used in
3336 commands such as `exit-recursive-edit' that throw back to the editor
3337 command loop (*note Recursive Editing::).
3338
3339      Common Lisp note: Most other versions of Lisp, including Common
3340      Lisp, have several ways of transferring control nonsequentially:
3341      `return', `return-from', and `go', for example.  XEmacs Lisp has
3342      only `throw'.
3343
3344  - Special Form: catch tag body...
3345      `catch' establishes a return point for the `throw' function.  The
3346      return point is distinguished from other such return points by TAG,
3347      which may be any Lisp object.  The argument TAG is evaluated
3348      normally before the return point is established.