1 This is ../info/cl.info, produced by makeinfo version 4.6 from cl.texi.
3 INFO-DIR-SECTION XEmacs Editor
5 * Common Lisp: (cl). GNU Emacs Common Lisp emulation package.
8 This file documents the GNU Emacs Common Lisp emulation package.
10 Copyright (C) 1993 Free Software Foundation, Inc.
12 Permission is granted to make and distribute verbatim copies of this
13 manual provided the copyright notice and this permission notice are
14 preserved on all copies.
16 Permission is granted to copy and distribute modified versions of
17 this manual under the conditions for verbatim copying, provided also
18 that the section entitled "GNU General Public License" is included
19 exactly as in the original, and provided that the entire resulting
20 derived work is distributed under the terms of a permission notice
21 identical to this one.
23 Permission is granted to copy and distribute translations of this
24 manual into another language, under the above conditions for modified
25 versions, except that the section entitled "GNU General Public License"
26 may be included in a translation approved by the author instead of in
30 File: cl.info, Node: Top, Next: Overview, Up: (dir)
32 Common Lisp Extensions
33 **********************
35 This document describes a set of Emacs Lisp facilities borrowed from
36 Common Lisp. All the facilities are described here in detail; for more
37 discussion and examples, Guy L. Steele's `Common Lisp, the Language',
38 second edition, is the definitive book on Common Lisp. While this
39 document does not assume any prior knowledge of Common Lisp, it does
40 assume a basic familiarity with Emacs Lisp.
44 * Overview:: Installation, usage, etc.
45 * Program Structure:: Arglists, `eval-when', `defalias'
46 * Predicates:: `typep', `eql', and `equalp'
47 * Control Structure:: `setf', `when', `do', `loop', etc.
48 * Macros:: Destructuring, `define-compiler-macro'
49 * Declarations:: `proclaim', `declare', etc.
50 * Symbols:: Property lists, `gensym'
51 * Numbers:: Predicates, functions, random numbers
52 * Sequences:: Mapping, functions, searching, sorting
53 * Lists:: `cadr', `sublis', `member*', `assoc*', etc.
54 * Hash Tables:: `make-hash-table', `gethash', etc.
55 * Structures:: `defstruct'
56 * Assertions:: `check-type', `assert', `ignore-errors'.
58 * Efficiency Concerns:: Hints and techniques
59 * Common Lisp Compatibility:: All known differences with Steele
60 * Old CL Compatibility:: All known differences with old cl.el
61 * Porting Common Lisp:: Hints for porting Common Lisp code
67 File: cl.info, Node: Overview, Next: Program Structure, Prev: Top, Up: Top
72 Common Lisp is a huge language, and Common Lisp systems tend to be
73 massive and extremely complex. Emacs Lisp, by contrast, is rather
74 minimalist in the choice of Lisp features it offers the programmer. As
75 Emacs Lisp programmers have grown in number, and the applications they
76 write have grown more ambitious, it has become clear that Emacs Lisp
77 could benefit from many of the conveniences of Common Lisp.
79 The "CL" package adds a number of Common Lisp functions and control
80 structures to Emacs Lisp. While not a 100% complete implementation of
81 Common Lisp, "CL" adds enough functionality to make Emacs Lisp
82 programming significantly more convenient.
84 Some Common Lisp features have been omitted from this package for
87 * Some features are too complex or bulky relative to their benefit
88 to Emacs Lisp programmers. CLOS and Common Lisp streams are fine
89 examples of this group.
91 * Other features cannot be implemented without modification to the
92 Emacs Lisp interpreter itself, such as multiple return values,
93 lexical scoping, case-insensitive symbols, and complex numbers.
94 The "CL" package generally makes no attempt to emulate these
97 * Some features conflict with existing things in Emacs Lisp. For
98 example, Emacs' `assoc' function is incompatible with the Common
99 Lisp `assoc'. In such cases, this package usually adds the suffix
100 `*' to the function name of the Common Lisp version of the
101 function (e.g., `assoc*').
103 The package described here was written by Dave Gillespie,
104 `daveg@synaptics.com'. It is a total rewrite of the original 1986
105 `cl.el' package by Cesar Quiroz. Most features of the Quiroz package
106 have been retained; any incompatibilities are noted in the descriptions
107 below. Care has been taken in this version to ensure that each
108 function is defined efficiently, concisely, and with minimal impact on
109 the rest of the Emacs environment.
113 * Usage:: How to use the CL package
114 * Organization:: The package's five component files
115 * Installation:: Compiling and installing CL
116 * Naming Conventions:: Notes on CL function names
119 File: cl.info, Node: Usage, Next: Organization, Prev: Overview, Up: Overview
124 Lisp code that uses features from the "CL" package should include at
129 If you want to ensure that the new (Gillespie) version of "CL" is the
130 one that is present, add an additional `(require 'cl-19)' call:
135 The second call will fail (with "`cl-19.el' not found") if the old
136 `cl.el' package was in use.
138 It is safe to arrange to load "CL" at all times, e.g., in your
139 `.emacs' file. But it's a good idea, for portability, to `(require
140 'cl)' in your code even if you do this.
143 File: cl.info, Node: Organization, Next: Installation, Prev: Usage, Up: Overview
148 The Common Lisp package is organized into four files:
151 This is the "main" file, which contains basic functions and
152 information about the package. This file is relatively
153 compact--about 700 lines.
156 This file contains the larger, more complex or unusual functions.
157 It is kept separate so that packages which only want to use Common
158 Lisp fundamentals like the `cadr' function won't need to pay the
159 overhead of loading the more advanced functions.
162 This file contains most of the advanced functions for operating on
163 sequences or lists, such as `delete-if' and `assoc*'.
166 This file contains the features of the packages which are macros
167 instead of functions. Macros expand when the caller is compiled,
168 not when it is run, so the macros generally only need to be
169 present when the byte-compiler is running (or when the macros are
170 used in uncompiled code such as a `.emacs' file). Most of the
171 macros of this package are isolated in `cl-macs.el' so that they
172 won't take up memory unless you are compiling.
174 The file `cl.el' includes all necessary `autoload' commands for the
175 functions and macros in the other three files. All you have to do is
176 `(require 'cl)', and `cl.el' will take care of pulling in the other
177 files when they are needed.
179 There is another file, `cl-compat.el', which defines some routines
180 from the older `cl.el' package that are no longer present in the new
181 package. This includes internal routines like `setelt' and
182 `zip-lists', deprecated features like `defkeyword', and an emulation of
183 the old-style multiple-values feature. *Note Old CL Compatibility::.
186 File: cl.info, Node: Installation, Next: Naming Conventions, Prev: Organization, Up: Overview
191 Installation of the "CL" package is simple: Just put the byte-compiled
192 files `cl.elc', `cl-extra.elc', `cl-seq.elc', `cl-macs.elc', and
193 `cl-compat.elc' into a directory on your `load-path'.
195 There are no special requirements to compile this package: The files
196 do not have to be loaded before they are compiled, nor do they need to
197 be compiled in any particular order.
199 You may choose to put the files into your main `lisp/' directory,
200 replacing the original `cl.el' file there. Or, you could put them into
201 a directory that comes before `lisp/' on your `load-path' so that the
202 old `cl.el' is effectively hidden.
204 Also, format the `cl.texinfo' file and put the resulting Info files
205 in the `info/' directory or another suitable place.
207 You may instead wish to leave this package's components all in their
208 own directory, and then add this directory to your `load-path' and
209 (Emacs 19 only) `Info-directory-list'. Add the directory to the front
210 of the list so the old "CL" package and its documentation are hidden.
213 File: cl.info, Node: Naming Conventions, Prev: Installation, Up: Overview
218 Except where noted, all functions defined by this package have the same
219 names and calling conventions as their Common Lisp counterparts.
221 Following is a complete list of functions whose names were changed
222 from Common Lisp, usually to avoid conflicts with Emacs. In each case,
223 a `*' has been appended to the Common Lisp name to obtain the Emacs
226 defun* defsubst* defmacro* function*
227 member* assoc* rassoc* remove*
228 delete* mapcar* sort* floor*
229 ceiling* truncate* round* mod*
232 Internal function and variable names in the package are prefixed by
233 `cl-'. Here is a complete list of functions _not_ prefixed by `cl-'
234 which were not taken from Common Lisp:
236 member delete remove remq
237 rassoc floatp-safe lexical-let lexical-let*
238 callf callf2 letf letf*
239 defsubst* defalias add-hook eval-when-compile
241 (Most of these are Emacs 19 features provided to Emacs 18 users, or
242 introduced, like `remq', for reasons of symmetry with similar features.)
244 The following simple functions and macros are defined in `cl.el';
245 they do not cause other components like `cl-extra' to be loaded.
247 eql floatp-safe abs endp
248 evenp oddp plusp minusp
249 last butlast nbutlast caar .. cddddr
250 list* ldiff rest first .. tenth
251 member [1] copy-list subst mapcar* [2]
252 adjoin [3] acons pairlis when
253 unless pop [4] push [4] pushnew [3,4]
254 incf [4] decf [4] proclaim declaim
257 [1] This is the Emacs 19-compatible function, not `member*'.
259 [2] Only for one sequence argument or two list arguments.
261 [3] Only if `:test' is `eq', `equal', or unspecified, and `:key' is not
264 [4] Only when PLACE is a plain variable name.
267 File: cl.info, Node: Program Structure, Next: Predicates, Prev: Overview, Up: Top
272 This section describes features of the "CL" package which have to do
273 with programs as a whole: advanced argument lists for functions, and
274 the `eval-when' construct.
278 * Argument Lists:: `&key', `&aux', `defun*', `defmacro*'.
279 * Time of Evaluation:: The `eval-when' construct.
280 * Function Aliases:: The `defalias' function.
283 File: cl.info, Node: Argument Lists, Next: Time of Evaluation, Prev: Program Structure, Up: Program Structure
288 Emacs Lisp's notation for argument lists of functions is a subset of
289 the Common Lisp notation. As well as the familiar `&optional' and
290 `&rest' markers, Common Lisp allows you to specify default values for
291 optional arguments, and it provides the additional markers `&key' and
294 Since argument parsing is built-in to Emacs, there is no way for
295 this package to implement Common Lisp argument lists seamlessly.
296 Instead, this package defines alternates for several Lisp forms which
297 you must use if you need Common Lisp argument lists.
299 - Special Form: defun* name arglist body...
300 This form is identical to the regular `defun' form, except that
301 ARGLIST is allowed to be a full Common Lisp argument list. Also,
302 the function body is enclosed in an implicit block called NAME;
303 *note Blocks and Exits::.
305 - Special Form: defsubst* name arglist body...
306 This is just like `defun*', except that the function that is
307 defined is automatically proclaimed `inline', i.e., calls to it
308 may be expanded into in-line code by the byte compiler. This is
309 analogous to the `defsubst' form in Emacs 19; `defsubst*' uses a
310 different method (compiler macros) which works in all version of
311 Emacs, and also generates somewhat more efficient inline
312 expansions. In particular, `defsubst*' arranges for the
313 processing of keyword arguments, default values, etc., to be done
314 at compile-time whenever possible.
316 - Special Form: defmacro* name arglist body...
317 This is identical to the regular `defmacro' form, except that
318 ARGLIST is allowed to be a full Common Lisp argument list. The
319 `&environment' keyword is supported as described in Steele. The
320 `&whole' keyword is supported only within destructured lists (see
321 below); top-level `&whole' cannot be implemented with the current
322 Emacs Lisp interpreter. The macro expander body is enclosed in an
323 implicit block called NAME.
325 - Special Form: function* symbol-or-lambda
326 This is identical to the regular `function' form, except that if
327 the argument is a `lambda' form then that form may use a full
328 Common Lisp argument list.
330 Also, all forms (such as `defsetf' and `flet') defined in this
331 package that include ARGLISTs in their syntax allow full Common Lisp
334 Note that it is _not_ necessary to use `defun*' in order to have
335 access to most "CL" features in your function. These features are
336 always present; `defun*''s only difference from `defun' is its more
337 flexible argument lists and its implicit block.
339 The full form of a Common Lisp argument list is
342 &optional (VAR INITFORM SVAR)...
344 &key ((KEYWORD VAR) INITFORM SVAR)...
345 &aux (VAR INITFORM)...)
347 Each of the five argument list sections is optional. The SVAR,
348 INITFORM, and KEYWORD parts are optional; if they are omitted, then
349 `(VAR)' may be written simply `VAR'.
351 The first section consists of zero or more "required" arguments.
352 These arguments must always be specified in a call to the function;
353 there is no difference between Emacs Lisp and Common Lisp as far as
354 required arguments are concerned.
356 The second section consists of "optional" arguments. These
357 arguments may be specified in the function call; if they are not,
358 INITFORM specifies the default value used for the argument. (No
359 INITFORM means to use `nil' as the default.) The INITFORM is evaluated
360 with the bindings for the preceding arguments already established; `(a
361 &optional (b (1+ a)))' matches one or two arguments, with the second
362 argument defaulting to one plus the first argument. If the SVAR is
363 specified, it is an auxiliary variable which is bound to `t' if the
364 optional argument was specified, or to `nil' if the argument was
365 omitted. If you don't use an SVAR, then there will be no way for your
366 function to tell whether it was called with no argument, or with the
367 default value passed explicitly as an argument.
369 The third section consists of a single "rest" argument. If more
370 arguments were passed to the function than are accounted for by the
371 required and optional arguments, those extra arguments are collected
372 into a list and bound to the "rest" argument variable. Common Lisp's
373 `&rest' is equivalent to that of Emacs Lisp. Common Lisp accepts
374 `&body' as a synonym for `&rest' in macro contexts; this package
375 accepts it all the time.
377 The fourth section consists of "keyword" arguments. These are
378 optional arguments which are specified by name rather than positionally
379 in the argument list. For example,
381 (defun* foo (a &optional b &key c d (e 17)))
383 defines a function which may be called with one, two, or more
384 arguments. The first two arguments are bound to `a' and `b' in the
385 usual way. The remaining arguments must be pairs of the form `:c',
386 `:d', or `:e' followed by the value to be bound to the corresponding
387 argument variable. (Symbols whose names begin with a colon are called
388 "keywords", and they are self-quoting in the same way as `nil' and `t'.)
390 For example, the call `(foo 1 2 :d 3 :c 4)' sets the five arguments
391 to 1, 2, 4, 3, and 17, respectively. If the same keyword appears more
392 than once in the function call, the first occurrence takes precedence
393 over the later ones. Note that it is not possible to specify keyword
394 arguments without specifying the optional argument `b' as well, since
395 `(foo 1 :c 2)' would bind `b' to the keyword `:c', then signal an error
396 because `2' is not a valid keyword.
398 If a KEYWORD symbol is explicitly specified in the argument list as
399 shown in the above diagram, then that keyword will be used instead of
400 just the variable name prefixed with a colon. You can specify a
401 KEYWORD symbol which does not begin with a colon at all, but such
402 symbols will not be self-quoting; you will have to quote them
403 explicitly with an apostrophe in the function call.
405 Ordinarily it is an error to pass an unrecognized keyword to a
406 function, e.g., `(foo 1 2 :c 3 :goober 4)'. You can ask Lisp to ignore
407 unrecognized keywords, either by adding the marker `&allow-other-keys'
408 after the keyword section of the argument list, or by specifying an
409 `:allow-other-keys' argument in the call whose value is non-`nil'. If
410 the function uses both `&rest' and `&key' at the same time, the "rest"
411 argument is bound to the keyword list as it appears in the call. For
414 (defun* find-thing (thing &rest rest &key need &allow-other-keys)
415 (or (apply 'member* thing thing-list :allow-other-keys t rest)
416 (if need (error "Thing not found"))))
418 This function takes a `:need' keyword argument, but also accepts other
419 keyword arguments which are passed on to the `member*' function.
420 `allow-other-keys' is used to keep both `find-thing' and `member*' from
421 complaining about each others' keywords in the arguments.
423 As a (significant) performance optimization, this package implements
424 the scan for keyword arguments by calling `memq' to search for keywords
425 in a "rest" argument. Technically speaking, this is incorrect, since
426 `memq' looks at the odd-numbered values as well as the even-numbered
427 keywords. The net effect is that if you happen to pass a keyword symbol
428 as the _value_ of another keyword argument, where that keyword symbol
429 happens to equal the name of a valid keyword argument of the same
430 function, then the keyword parser will become confused. This minor bug
431 can only affect you if you use keyword symbols as general-purpose data
432 in your program; this practice is strongly discouraged in Emacs Lisp.
434 The fifth section of the argument list consists of "auxiliary
435 variables". These are not really arguments at all, but simply
436 variables which are bound to `nil' or to the specified INITFORMS during
437 execution of the function. There is no difference between the
438 following two functions, except for a matter of stylistic taste:
440 (defun* foo (a b &aux (c (+ a b)) d)
447 Argument lists support "destructuring". In Common Lisp,
448 destructuring is only allowed with `defmacro'; this package allows it
449 with `defun*' and other argument lists as well. In destructuring, any
450 argument variable (VAR in the above diagram) can be replaced by a list
451 of variables, or more generally, a recursive argument list. The
452 corresponding argument value must be a list whose elements match this
453 recursive argument list. For example:
455 (defmacro* dolist ((var listform &optional resultform)
459 This says that the first argument of `dolist' must be a list of two
460 or three items; if there are other arguments as well as this list, they
461 are stored in `body'. All features allowed in regular argument lists
462 are allowed in these recursive argument lists. In addition, the clause
463 `&whole VAR' is allowed at the front of a recursive argument list. It
464 binds VAR to the whole list being matched; thus `(&whole all a b)'
465 matches a list of two things, with `a' bound to the first thing, `b'
466 bound to the second thing, and `all' bound to the list itself. (Common
467 Lisp allows `&whole' in top-level `defmacro' argument lists as well,
468 but Emacs Lisp does not support this usage.)
470 One last feature of destructuring is that the argument list may be
471 dotted, so that the argument list `(a b . c)' is functionally
472 equivalent to `(a b &rest c)'.
474 If the optimization quality `safety' is set to 0 (*note
475 Declarations::), error checking for wrong number of arguments and
476 invalid keyword arguments is disabled. By default, argument lists are
480 File: cl.info, Node: Time of Evaluation, Next: Function Aliases, Prev: Argument Lists, Up: Program Structure
485 Normally, the byte-compiler does not actually execute the forms in a
486 file it compiles. For example, if a file contains `(setq foo t)', the
487 act of compiling it will not actually set `foo' to `t'. This is true
488 even if the `setq' was a top-level form (i.e., not enclosed in a
489 `defun' or other form). Sometimes, though, you would like to have
490 certain top-level forms evaluated at compile-time. For example, the
491 compiler effectively evaluates `defmacro' forms at compile-time so that
492 later parts of the file can refer to the macros that are defined.
494 - Special Form: eval-when (situations...) forms...
495 This form controls when the body FORMS are evaluated. The
496 SITUATIONS list may contain any set of the symbols `compile',
497 `load', and `eval' (or their long-winded ANSI equivalents,
498 `:compile-toplevel', `:load-toplevel', and `:execute').
500 The `eval-when' form is handled differently depending on whether
501 or not it is being compiled as a top-level form. Specifically, it
502 gets special treatment if it is being compiled by a command such
503 as `byte-compile-file' which compiles files or buffers of code,
504 and it appears either literally at the top level of the file or
505 inside a top-level `progn'.
507 For compiled top-level `eval-when's, the body FORMS are executed
508 at compile-time if `compile' is in the SITUATIONS list, and the
509 FORMS are written out to the file (to be executed at load-time) if
510 `load' is in the SITUATIONS list.
512 For non-compiled-top-level forms, only the `eval' situation is
513 relevant. (This includes forms executed by the interpreter, forms
514 compiled with `byte-compile' rather than `byte-compile-file', and
515 non-top-level forms.) The `eval-when' acts like a `progn' if
516 `eval' is specified, and like `nil' (ignoring the body FORMS) if
519 The rules become more subtle when `eval-when's are nested; consult
520 Steele (second edition) for the gruesome details (and some
523 Some simple examples:
525 ;; Top-level forms in foo.el:
526 (eval-when (compile) (setq foo1 'bar))
527 (eval-when (load) (setq foo2 'bar))
528 (eval-when (compile load) (setq foo3 'bar))
529 (eval-when (eval) (setq foo4 'bar))
530 (eval-when (eval compile) (setq foo5 'bar))
531 (eval-when (eval load) (setq foo6 'bar))
532 (eval-when (eval compile load) (setq foo7 'bar))
534 When `foo.el' is compiled, these variables will be set during the
537 foo1 foo3 foo5 foo7 ; `compile'
539 When `foo.elc' is loaded, these variables will be set:
541 foo2 foo3 foo6 foo7 ; `load'
543 And if `foo.el' is loaded uncompiled, these variables will be set:
545 foo4 foo5 foo6 foo7 ; `eval'
547 If these seven `eval-when's had been, say, inside a `defun', then
548 the first three would have been equivalent to `nil' and the last
549 four would have been equivalent to the corresponding `setq's.
551 Note that `(eval-when (load eval) ...)' is equivalent to `(progn
552 ...)' in all contexts. The compiler treats certain top-level
553 forms, like `defmacro' (sort-of) and `require', as if they were
554 wrapped in `(eval-when (compile load eval) ...)'.
556 Emacs 19 includes two special forms related to `eval-when'. One of
557 these, `eval-when-compile', is not quite equivalent to any `eval-when'
558 construct and is described below. This package defines a version of
559 `eval-when-compile' for the benefit of Emacs 18 users.
561 The other form, `(eval-and-compile ...)', is exactly equivalent to
562 `(eval-when (compile load eval) ...)' and so is not itself defined by
565 - Special Form: eval-when-compile forms...
566 The FORMS are evaluated at compile-time; at execution time, this
567 form acts like a quoted constant of the resulting value. Used at
568 top-level, `eval-when-compile' is just like `eval-when (compile
569 eval)'. In other contexts, `eval-when-compile' allows code to be
570 evaluated once at compile-time for efficiency or other reasons.
572 This form is similar to the `#.' syntax of true Common Lisp.
574 - Special Form: load-time-value form
575 The FORM is evaluated at load-time; at execution time, this form
576 acts like a quoted constant of the resulting value.
578 Early Common Lisp had a `#,' syntax that was similar to this, but
579 ANSI Common Lisp replaced it with `load-time-value' and gave it
580 more well-defined semantics.
582 In a compiled file, `load-time-value' arranges for FORM to be
583 evaluated when the `.elc' file is loaded and then used as if it
584 were a quoted constant. In code compiled by `byte-compile' rather
585 than `byte-compile-file', the effect is identical to
586 `eval-when-compile'. In uncompiled code, both `eval-when-compile'
587 and `load-time-value' act exactly like `progn'.
590 (insert "This function was executed on: "
591 (current-time-string)
593 (eval-when-compile (current-time-string))
594 ;; or '#.(current-time-string) in real Common Lisp
596 (load-time-value (current-time-string))))
598 Byte-compiled, the above defun will result in the following code
599 (or its compiled equivalent, of course) in the `.elc' file:
601 (setq --temp-- (current-time-string))
603 (insert "This function was executed on: "
604 (current-time-string)
606 '"Wed Jun 23 18:33:43 1993"
611 File: cl.info, Node: Function Aliases, Prev: Time of Evaluation, Up: Program Structure
616 This section describes a feature from GNU Emacs 19 which this package
617 makes available in other versions of Emacs.
619 - Function: defalias symbol function
620 This function sets SYMBOL's function cell to FUNCTION. It is
621 equivalent to `fset', except that in GNU Emacs 19 it also records
622 the setting in `load-history' so that it can be undone by a later
625 In other versions of Emacs, `defalias' is a synonym for `fset'.
628 File: cl.info, Node: Predicates, Next: Control Structure, Prev: Program Structure, Up: Top
633 This section describes functions for testing whether various facts are
638 * Type Predicates:: `typep', `deftype', and `coerce'
639 * Equality Predicates:: `eql' and `equalp'
642 File: cl.info, Node: Type Predicates, Next: Equality Predicates, Prev: Predicates, Up: Predicates
647 The "CL" package defines a version of the Common Lisp `typep' predicate.
649 - Function: typep object type
650 Check if OBJECT is of type TYPE, where TYPE is a (quoted) type
651 name of the sort used by Common Lisp. For example, `(typep foo
652 'integer)' is equivalent to `(integerp foo)'.
654 The TYPE argument to the above function is either a symbol or a list
655 beginning with a symbol.
657 * If the type name is a symbol, Emacs appends `-p' to the symbol
658 name to form the name of a predicate function for testing the
659 type. (Built-in predicates whose names end in `p' rather than
660 `-p' are used when appropriate.)
662 * The type symbol `t' stands for the union of all types. `(typep
663 OBJECT t)' is always true. Likewise, the type symbol `nil' stands
664 for nothing at all, and `(typep OBJECT nil)' is always false.
666 * The type symbol `null' represents the symbol `nil'. Thus `(typep
667 OBJECT 'null)' is equivalent to `(null OBJECT)'.
669 * The type symbol `real' is a synonym for `number', and `fixnum' is
670 a synonym for `integer'.
672 * The type symbols `character' and `string-char' match characters.
673 In Emacs-19 and XEmacs-19, characters are the same thing as
674 integers in the range 0-255. In XEmacs-20, where characters are a
675 first-class data type, this checks for actual characters, and
676 `(typep 8BIT-INTEGER 'character)' will return `nil'.
678 * The type symbol `float' uses the `floatp-safe' predicate defined
679 by this package rather than `floatp', so it will work correctly
680 even in Emacs versions without floating-point support.
682 * The type list `(integer LOW HIGH)' represents all integers between
683 LOW and HIGH, inclusive. Either bound may be a list of a single
684 integer to specify an exclusive limit, or a `*' to specify no
685 limit. The type `(integer * *)' is thus equivalent to `integer'.
687 * Likewise, lists beginning with `float', `real', or `number'
688 represent numbers of that type falling in a particular range.
690 * Lists beginning with `and', `or', and `not' form combinations of
691 types. For example, `(or integer (float 0 *))' represents all
692 objects that are integers or non-negative floats.
694 * Lists beginning with `member' or `member*' represent objects `eql'
695 to any of the following values. For example, `(member 1 2 3 4)'
696 is equivalent to `(integer 1 4)', and `(member nil)' is equivalent
699 * Lists of the form `(satisfies PREDICATE)' represent all objects
700 for which PREDICATE returns true when called with that object as
703 The following function and macro (not technically predicates) are
706 - Function: coerce object type
707 This function attempts to convert OBJECT to the specified TYPE.
708 If OBJECT is already of that type as determined by `typep', it is
709 simply returned. Otherwise, certain types of conversions will be
710 made: If TYPE is any sequence type (`string', `list', etc.) then
711 OBJECT will be converted to that type if possible. If TYPE is
712 `character', then strings of length one and symbols with
713 one-character names can be coerced. If TYPE is `float', then
714 integers can be coerced in versions of Emacs that support floats.
715 In all other circumstances, `coerce' signals an error.
717 - Special Form: deftype name arglist forms...
718 This macro defines a new type called NAME. It is similar to
719 `defmacro' in many ways; when NAME is encountered as a type name,
720 the body FORMS are evaluated and should return a type specifier
721 that is equivalent to the type. The ARGLIST is a Common Lisp
722 argument list of the sort accepted by `defmacro*'. The type
723 specifier `(NAME ARGS...)' is expanded by calling the expander
724 with those arguments; the type symbol `NAME' is expanded by
725 calling the expander with no arguments. The ARGLIST is processed
726 the same as for `defmacro*' except that optional arguments without
727 explicit defaults use `*' instead of `nil' as the "default"
728 default. Some examples:
730 (deftype null () '(satisfies null)) ; predefined
731 (deftype list () '(or null cons)) ; predefined
732 (deftype unsigned-byte (&optional bits)
733 (list 'integer 0 (if (eq bits '*) bits (1- (lsh 1 bits)))))
734 (unsigned-byte 8) == (integer 0 255)
735 (unsigned-byte) == (integer 0 *)
736 unsigned-byte == (integer 0 *)
738 The last example shows how the Common Lisp `unsigned-byte' type
739 specifier could be implemented if desired; this package does not
740 implement `unsigned-byte' by default.
742 The `typecase' and `check-type' macros also use type names. *Note
743 Conditionals::. *Note Assertions::. The `map', `concatenate', and
744 `merge' functions take type-name arguments to specify the type of
745 sequence to return. *Note Sequences::.
748 File: cl.info, Node: Equality Predicates, Prev: Type Predicates, Up: Predicates
753 This package defines two Common Lisp predicates, `eql' and `equalp'.
756 This function is almost the same as `eq', except that if A and B
757 are numbers of the same type, it compares them for numeric
758 equality (as if by `equal' instead of `eq'). This makes a
759 difference only for versions of Emacs that are compiled with
760 floating-point support, such as Emacs 19. Emacs floats are
761 allocated objects just like cons cells, which means that `(eq 3.0
762 3.0)' will not necessarily be true--if the two `3.0's were
763 allocated separately, the pointers will be different even though
764 the numbers are the same. But `(eql 3.0 3.0)' will always be true.
766 The types of the arguments must match, so `(eql 3 3.0)' is still
769 Note that Emacs integers are "direct" rather than allocated, which
770 basically means `(eq 3 3)' will always be true. Thus `eq' and
771 `eql' behave differently only if floating-point numbers are
772 involved, and are indistinguishable on Emacs versions that don't
775 There is a slight inconsistency with Common Lisp in the treatment
776 of positive and negative zeros. Some machines, notably those with
777 IEEE standard arithmetic, represent `+0' and `-0' as distinct
778 values. Normally this doesn't matter because the standard
779 specifies that `(= 0.0 -0.0)' should always be true, and this is
780 indeed what Emacs Lisp and Common Lisp do. But the Common Lisp
781 standard states that `(eql 0.0 -0.0)' and `(equal 0.0 -0.0)' should
782 be false on IEEE-like machines; Emacs Lisp does not do this, and in
783 fact the only known way to distinguish between the two zeros in
784 Emacs Lisp is to `format' them and check for a minus sign.
786 - Function: equalp a b
787 This function is a more flexible version of `equal'. In
788 particular, it compares strings and characters case-insensitively,
789 and it compares numbers without regard to type (so that `(equalp 3
790 3.0)' is true). Vectors and conses are compared recursively. All
791 other objects are compared as if by `equal'.
793 This function differs from Common Lisp `equalp' in several
794 respects. In keeping with the idea that strings are less
795 vector-like in Emacs Lisp, this package's `equalp' also will not
796 compare strings against vectors of integers.
798 Also note that the Common Lisp functions `member' and `assoc' use
799 `eql' to compare elements, whereas Emacs Lisp follows the MacLisp
800 tradition and uses `equal' for these two functions. In Emacs, use
801 `member*' and `assoc*' to get functions which use `eql' for comparisons.
804 File: cl.info, Node: Control Structure, Next: Macros, Prev: Predicates, Up: Top
809 The features described in the following sections implement various
810 advanced control structures, including the powerful `setf' facility and
811 a number of looping and conditional constructs.
815 * Assignment:: The `psetq' form
816 * Generalized Variables:: `setf', `incf', `push', etc.
817 * Variable Bindings:: `progv', `lexical-let', `flet', `macrolet'
818 * Conditionals:: `when', `unless', `case', `typecase'
819 * Blocks and Exits:: `block', `return', `return-from'
820 * Iteration:: `do', `dotimes', `dolist', `do-symbols'
821 * Loop Facility:: The Common Lisp `loop' macro
822 * Multiple Values:: `values', `multiple-value-bind', etc.
825 File: cl.info, Node: Assignment, Next: Generalized Variables, Prev: Control Structure, Up: Control Structure
830 The `psetq' form is just like `setq', except that multiple assignments
831 are done in parallel rather than sequentially.
833 - Special Form: psetq [symbol form]...
834 This special form (actually a macro) is used to assign to several
835 variables simultaneously. Given only one SYMBOL and FORM, it has
836 the same effect as `setq'. Given several SYMBOL and FORM pairs,
837 it evaluates all the FORMs in advance and then stores the
838 corresponding variables afterwards.
841 (setq x (+ x y) y (* x y))
844 y ; `y' was computed after `x' was set.
847 (psetq x (+ x y) y (* x y))
850 y ; `y' was computed before `x' was set.
853 The simplest use of `psetq' is `(psetq x y y x)', which exchanges
854 the values of two variables. (The `rotatef' form provides an even
855 more convenient way to swap two variables; *note Modify Macros::.)
857 `psetq' always returns `nil'.
860 File: cl.info, Node: Generalized Variables, Next: Variable Bindings, Prev: Assignment, Up: Control Structure
862 Generalized Variables
863 =====================
865 A "generalized variable" or "place form" is one of the many places in
866 Lisp memory where values can be stored. The simplest place form is a
867 regular Lisp variable. But the cars and cdrs of lists, elements of
868 arrays, properties of symbols, and many other locations are also places
869 where Lisp values are stored.
871 The `setf' form is like `setq', except that it accepts arbitrary
872 place forms on the left side rather than just symbols. For example,
873 `(setf (car a) b)' sets the car of `a' to `b', doing the same operation
874 as `(setcar a b)' but without having to remember two separate functions
875 for setting and accessing every type of place.
877 Generalized variables are analogous to "lvalues" in the C language,
878 where `x = a[i]' gets an element from an array and `a[i] = x' stores an
879 element using the same notation. Just as certain forms like `a[i]' can
880 be lvalues in C, there is a set of forms that can be generalized
885 * Basic Setf:: `setf' and place forms
886 * Modify Macros:: `incf', `push', `rotatef', `letf', `callf', etc.
887 * Customizing Setf:: `define-modify-macro', `defsetf', `define-setf-method'
890 File: cl.info, Node: Basic Setf, Next: Modify Macros, Prev: Generalized Variables, Up: Generalized Variables
895 The `setf' macro is the most basic way to operate on generalized
898 - Special Form: setf [place form]...
899 This macro evaluates FORM and stores it in PLACE, which must be a
900 valid generalized variable form. If there are several PLACE and
901 FORM pairs, the assignments are done sequentially just as with
902 `setq'. `setf' returns the value of the last FORM.
904 The following Lisp forms will work as generalized variables, and
905 so may legally appear in the PLACE argument of `setf':
907 * A symbol naming a variable. In other words, `(setf x y)' is
908 exactly equivalent to `(setq x y)', and `setq' itself is
909 strictly speaking redundant now that `setf' exists. Many
910 programmers continue to prefer `setq' for setting simple
911 variables, though, purely for stylistic or historical reasons.
912 The form `(setf x y)' actually expands to `(setq x y)', so
913 there is no performance penalty for using it in compiled code.
915 * A call to any of the following Lisp functions:
917 car cdr caar .. cddddr
918 nth rest first .. tenth
920 symbol-function symbol-value symbol-plist
924 Note that for `nthcdr' and `getf', the list argument of the
925 function must itself be a valid PLACE form. For example,
926 `(setf (nthcdr 0 foo) 7)' will set `foo' itself to 7. Note
927 that `push' and `pop' on an `nthcdr' place can be used to
928 insert or delete at any position in a list. The use of
929 `nthcdr' as a PLACE form is an extension to standard Common
932 * The following Emacs-specific functions are also `setf'-able.
933 (Some of these are defined only in Emacs 19 or only in
936 buffer-file-name marker-position
937 buffer-modified-p match-data
938 buffer-name mouse-position
939 buffer-string overlay-end
940 buffer-substring overlay-get
941 current-buffer overlay-start
942 current-case-table point
943 current-column point-marker
944 current-global-map point-max
945 current-input-mode point-min
946 current-local-map process-buffer
947 current-window-configuration process-filter
948 default-file-modes process-sentinel
949 default-value read-mouse-position
950 documentation-property screen-height
951 extent-data screen-menubar
952 extent-end-position screen-width
953 extent-start-position selected-window
954 face-background selected-screen
955 face-background-pixmap selected-frame
956 face-font standard-case-table
957 face-foreground syntax-table
958 face-underline-p window-buffer
959 file-modes window-dedicated-p
960 frame-height window-display-table
961 frame-parameters window-height
962 frame-visible-p window-hscroll
963 frame-width window-point
964 get-register window-start
966 global-key-binding x-get-cut-buffer
967 keymap-parent x-get-cutbuffer
968 local-key-binding x-get-secondary-selection
972 Most of these have directly corresponding "set" functions,
973 like `use-local-map' for `current-local-map', or `goto-char'
974 for `point'. A few, like `point-min', expand to longer
975 sequences of code when they are `setf''d (`(narrow-to-region
976 x (point-max))' in this case).
978 * A call of the form `(substring SUBPLACE N [M])', where
979 SUBPLACE is itself a legal generalized variable whose current
980 value is a string, and where the value stored is also a
981 string. The new string is spliced into the specified part of
982 the destination string. For example:
984 (setq a (list "hello" "world"))
988 (substring (cadr a) 2 4)
990 (setf (substring (cadr a) 2 4) "o")
997 The generalized variable `buffer-substring', listed above,
998 also works in this way by replacing a portion of the current
1001 * A call of the form `(apply 'FUNC ...)' or `(apply (function
1002 FUNC) ...)', where FUNC is a `setf'-able function whose store
1003 function is "suitable" in the sense described in Steele's
1004 book; since none of the standard Emacs place functions are
1005 suitable in this sense, this feature is only interesting when
1006 used with places you define yourself with
1007 `define-setf-method' or the long form of `defsetf'.
1009 * A macro call, in which case the macro is expanded and `setf'
1010 is applied to the resulting form.
1012 * Any form for which a `defsetf' or `define-setf-method' has
1015 Using any forms other than these in the PLACE argument to `setf'
1016 will signal an error.
1018 The `setf' macro takes care to evaluate all subforms in the proper
1019 left-to-right order; for example,
1021 (setf (aref vec (incf i)) i)
1023 looks like it will evaluate `(incf i)' exactly once, before the
1024 following access to `i'; the `setf' expander will insert temporary
1025 variables as necessary to ensure that it does in fact work this
1026 way no matter what setf-method is defined for `aref'. (In this
1027 case, `aset' would be used and no such steps would be necessary
1028 since `aset' takes its arguments in a convenient order.)
1030 However, if the PLACE form is a macro which explicitly evaluates
1031 its arguments in an unusual order, this unusual order will be
1032 preserved. Adapting an example from Steele, given
1034 (defmacro wrong-order (x y) (list 'aref y x))
1036 the form `(setf (wrong-order A B) 17)' will evaluate B first, then
1037 A, just as in an actual call to `wrong-order'.
1040 File: cl.info, Node: Modify Macros, Next: Customizing Setf, Prev: Basic Setf, Up: Generalized Variables
1045 This package defines a number of other macros besides `setf' that
1046 operate on generalized variables. Many are interesting and useful even
1047 when the PLACE is just a variable name.
1049 - Special Form: psetf [place form]...
1050 This macro is to `setf' what `psetq' is to `setq': When several
1051 PLACEs and FORMs are involved, the assignments take place in
1052 parallel rather than sequentially. Specifically, all subforms are
1053 evaluated from left to right, then all the assignments are done
1054 (in an undefined order).
1056 - Special Form: incf place &optional x
1057 This macro increments the number stored in PLACE by one, or by X
1058 if specified. The incremented value is returned. For example,
1059 `(incf i)' is equivalent to `(setq i (1+ i))', and `(incf (car x)
1060 2)' is equivalent to `(setcar x (+ (car x) 2))'.
1062 Once again, care is taken to preserve the "apparent" order of
1063 evaluation. For example,
1065 (incf (aref vec (incf i)))
1067 appears to increment `i' once, then increment the element of `vec'
1068 addressed by `i'; this is indeed exactly what it does, which means
1069 the above form is _not_ equivalent to the "obvious" expansion,
1071 (setf (aref vec (incf i)) (1+ (aref vec (incf i)))) ; Wrong!
1073 but rather to something more like
1075 (let ((temp (incf i)))
1076 (setf (aref vec temp) (1+ (aref vec temp))))
1078 Again, all of this is taken care of automatically by `incf' and
1079 the other generalized-variable macros.
1081 As a more Emacs-specific example of `incf', the expression `(incf
1082 (point) N)' is essentially equivalent to `(forward-char N)'.
1084 - Special Form: decf place &optional x
1085 This macro decrements the number stored in PLACE by one, or by X
1088 - Special Form: pop place
1089 This macro removes and returns the first element of the list stored
1090 in PLACE. It is analogous to `(prog1 (car PLACE) (setf PLACE (cdr
1091 PLACE)))', except that it takes care to evaluate all subforms only
1094 - Special Form: push x place
1095 This macro inserts X at the front of the list stored in PLACE. It
1096 is analogous to `(setf PLACE (cons X PLACE))', except for
1097 evaluation of the subforms.
1099 - Special Form: pushnew x place &key :test :test-not :key
1100 This macro inserts X at the front of the list stored in PLACE, but
1101 only if X was not `eql' to any existing element of the list. The
1102 optional keyword arguments are interpreted in the same way as for
1103 `adjoin'. *Note Lists as Sets::.
1105 - Special Form: shiftf place... newvalue
1106 This macro shifts the PLACEs left by one, shifting in the value of
1107 NEWVALUE (which may be any Lisp expression, not just a generalized
1108 variable), and returning the value shifted out of the first PLACE.
1109 Thus, `(shiftf A B C D)' is equivalent to
1117 except that the subforms of A, B, and C are actually evaluated
1118 only once each and in the apparent order.
1120 - Special Form: rotatef place...
1121 This macro rotates the PLACEs left by one in circular fashion.
1122 Thus, `(rotatef A B C D)' is equivalent to
1129 except for the evaluation of subforms. `rotatef' always returns
1130 `nil'. Note that `(rotatef A B)' conveniently exchanges A and B.
1132 The following macros were invented for this package; they have no
1133 analogues in Common Lisp.
1135 - Special Form: letf (bindings...) forms...
1136 This macro is analogous to `let', but for generalized variables
1137 rather than just symbols. Each BINDING should be of the form
1138 `(PLACE VALUE)'; the original contents of the PLACEs are saved,
1139 the VALUEs are stored in them, and then the body FORMs are
1140 executed. Afterwards, the PLACES are set back to their original
1141 saved contents. This cleanup happens even if the FORMs exit
1142 irregularly due to a `throw' or an error.
1146 (letf (((point) (point-min))
1150 moves "point" in the current buffer to the beginning of the buffer,
1151 and also binds `a' to 17 (as if by a normal `let', since `a' is
1152 just a regular variable). After the body exits, `a' is set back
1153 to its original value and point is moved back to its original
1156 Note that `letf' on `(point)' is not quite like a
1157 `save-excursion', as the latter effectively saves a marker which
1158 tracks insertions and deletions in the buffer. Actually, a `letf'
1159 of `(point-marker)' is much closer to this behavior. (`point' and
1160 `point-marker' are equivalent as `setf' places; each will accept
1161 either an integer or a marker as the stored value.)
1163 Since generalized variables look like lists, `let''s shorthand of
1164 using `foo' for `(foo nil)' as a BINDING would be ambiguous in
1165 `letf' and is not allowed.
1167 However, a BINDING specifier may be a one-element list `(PLACE)',
1168 which is similar to `(PLACE PLACE)'. In other words, the PLACE is
1169 not disturbed on entry to the body, and the only effect of the
1170 `letf' is to restore the original value of PLACE afterwards. (The
1171 redundant access-and-store suggested by the `(PLACE PLACE)'
1172 example does not actually occur.)
1174 In most cases, the PLACE must have a well-defined value on entry
1175 to the `letf' form. The only exceptions are plain variables and
1176 calls to `symbol-value' and `symbol-function'. If the symbol is
1177 not bound on entry, it is simply made unbound by `makunbound' or
1178 `fmakunbound' on exit.
1180 - Special Form: letf* (bindings...) forms...
1181 This macro is to `letf' what `let*' is to `let': It does the
1182 bindings in sequential rather than parallel order.
1184 - Special Form: callf FUNCTION PLACE ARGS...
1185 This is the "generic" modify macro. It calls FUNCTION, which
1186 should be an unquoted function name, macro name, or lambda. It
1187 passes PLACE and ARGS as arguments, and assigns the result back to
1188 PLACE. For example, `(incf PLACE N)' is the same as `(callf +
1189 PLACE N)'. Some more examples:
1191 (callf abs my-number)
1192 (callf concat (buffer-name) "<" (int-to-string n) ">")
1193 (callf union happy-people (list joe bob) :test 'same-person)
1195 *Note Customizing Setf::, for `define-modify-macro', a way to
1196 create even more concise notations for modify macros. Note again
1197 that `callf' is an extension to standard Common Lisp.
1199 - Special Form: callf2 FUNCTION ARG1 PLACE ARGS...
1200 This macro is like `callf', except that PLACE is the _second_
1201 argument of FUNCTION rather than the first. For example, `(push X
1202 PLACE)' is equivalent to `(callf2 cons X PLACE)'.
1204 The `callf' and `callf2' macros serve as building blocks for other
1205 macros like `incf', `pushnew', and `define-modify-macro'. The `letf'
1206 and `letf*' macros are used in the processing of symbol macros; *note
1210 File: cl.info, Node: Customizing Setf, Prev: Modify Macros, Up: Generalized Variables
1215 Common Lisp defines three macros, `define-modify-macro', `defsetf', and
1216 `define-setf-method', that allow the user to extend generalized
1217 variables in various ways.
1219 - Special Form: define-modify-macro name arglist function [doc-string]
1220 This macro defines a "read-modify-write" macro similar to `incf'
1221 and `decf'. The macro NAME is defined to take a PLACE argument
1222 followed by additional arguments described by ARGLIST. The call
1224 (NAME PLACE ARGS...)
1228 (callf FUNC PLACE ARGS...)
1230 which in turn is roughly equivalent to
1232 (setf PLACE (FUNC PLACE ARGS...))
1236 (define-modify-macro incf (&optional (n 1)) +)
1237 (define-modify-macro concatf (&rest args) concat)
1239 Note that `&key' is not allowed in ARGLIST, but `&rest' is
1240 sufficient to pass keywords on to the function.
1242 Most of the modify macros defined by Common Lisp do not exactly
1243 follow the pattern of `define-modify-macro'. For example, `push'
1244 takes its arguments in the wrong order, and `pop' is completely
1245 irregular. You can define these macros "by hand" using
1246 `get-setf-method', or consult the source file `cl-macs.el' to see
1247 how to use the internal `setf' building blocks.
1249 - Special Form: defsetf access-fn update-fn
1250 This is the simpler of two `defsetf' forms. Where ACCESS-FN is
1251 the name of a function which accesses a place, this declares
1252 UPDATE-FN to be the corresponding store function. From now on,
1254 (setf (ACCESS-FN ARG1 ARG2 ARG3) VALUE)
1258 (UPDATE-FN ARG1 ARG2 ARG3 VALUE)
1260 The UPDATE-FN is required to be either a true function, or a macro
1261 which evaluates its arguments in a function-like way. Also, the
1262 UPDATE-FN is expected to return VALUE as its result. Otherwise,
1263 the above expansion would not obey the rules for the way `setf' is
1266 As a special (non-Common-Lisp) extension, a third argument of `t'
1267 to `defsetf' says that the `update-fn''s return value is not
1268 suitable, so that the above `setf' should be expanded to something
1272 (UPDATE-FN ARG1 ARG2 ARG3 temp)
1275 Some examples of the use of `defsetf', drawn from the standard
1276 suite of setf methods, are:
1278 (defsetf car setcar)
1279 (defsetf symbol-value set)
1280 (defsetf buffer-name rename-buffer t)
1282 - Special Form: defsetf access-fn arglist (store-var) forms...
1283 This is the second, more complex, form of `defsetf'. It is rather
1284 like `defmacro' except for the additional STORE-VAR argument. The
1285 FORMS should return a Lisp form which stores the value of
1286 STORE-VAR into the generalized variable formed by a call to
1287 ACCESS-FN with arguments described by ARGLIST. The FORMS may
1288 begin with a string which documents the `setf' method (analogous
1289 to the doc string that appears at the front of a function).
1291 For example, the simple form of `defsetf' is shorthand for
1293 (defsetf ACCESS-FN (&rest args) (store)
1294 (append '(UPDATE-FN) args (list store)))
1296 The Lisp form that is returned can access the arguments from
1297 ARGLIST and STORE-VAR in an unrestricted fashion; macros like
1298 `setf' and `incf' which invoke this setf-method will insert
1299 temporary variables as needed to make sure the apparent order of
1300 evaluation is preserved.
1302 Another example drawn from the standard package:
1304 (defsetf nth (n x) (store)
1305 (list 'setcar (list 'nthcdr n x) store))
1307 - Special Form: define-setf-method access-fn arglist forms...
1308 This is the most general way to create new place forms. When a
1309 `setf' to ACCESS-FN with arguments described by ARGLIST is
1310 expanded, the FORMS are evaluated and must return a list of five
1313 1. A list of "temporary variables".
1315 2. A list of "value forms" corresponding to the temporary
1316 variables above. The temporary variables will be bound to
1317 these value forms as the first step of any operation on the
1318 generalized variable.
1320 3. A list of exactly one "store variable" (generally obtained
1321 from a call to `gensym').
1323 4. A Lisp form which stores the contents of the store variable
1324 into the generalized variable, assuming the temporaries have
1325 been bound as described above.
1327 5. A Lisp form which accesses the contents of the generalized
1328 variable, assuming the temporaries have been bound.
1330 This is exactly like the Common Lisp macro of the same name,
1331 except that the method returns a list of five values rather than
1332 the five values themselves, since Emacs Lisp does not support
1333 Common Lisp's notion of multiple return values.
1335 Once again, the FORMS may begin with a documentation string.
1337 A setf-method should be maximally conservative with regard to
1338 temporary variables. In the setf-methods generated by `defsetf',
1339 the second return value is simply the list of arguments in the
1340 place form, and the first return value is a list of a
1341 corresponding number of temporary variables generated by `gensym'.
1342 Macros like `setf' and `incf' which use this setf-method will
1343 optimize away most temporaries that turn out to be unnecessary, so
1344 there is little reason for the setf-method itself to optimize.
1346 - Function: get-setf-method place &optional env
1347 This function returns the setf-method for PLACE, by invoking the
1348 definition previously recorded by `defsetf' or
1349 `define-setf-method'. The result is a list of five values as
1350 described above. You can use this function to build your own
1351 `incf'-like modify macros. (Actually, it is better to use the
1352 internal functions `cl-setf-do-modify' and `cl-setf-do-store',
1353 which are a bit easier to use and which also do a number of
1354 optimizations; consult the source code for the `incf' function for
1357 The argument ENV specifies the "environment" to be passed on to
1358 `macroexpand' if `get-setf-method' should need to expand a macro
1359 in PLACE. It should come from an `&environment' argument to the
1360 macro or setf-method that called `get-setf-method'.
1362 See also the source code for the setf-methods for `apply' and
1363 `substring', each of which works by calling `get-setf-method' on a
1364 simpler case, then massaging the result in various ways.
1366 Modern Common Lisp defines a second, independent way to specify the
1367 `setf' behavior of a function, namely "`setf' functions" whose names
1368 are lists `(setf NAME)' rather than symbols. For example, `(defun
1369 (setf foo) ...)' defines the function that is used when `setf' is
1370 applied to `foo'. This package does not currently support `setf'
1371 functions. In particular, it is a compile-time error to use `setf' on
1372 a form which has not already been `defsetf''d or otherwise declared; in
1373 newer Common Lisps, this would not be an error since the function
1374 `(setf FUNC)' might be defined later.
1377 File: cl.info, Node: Variable Bindings, Next: Conditionals, Prev: Generalized Variables, Up: Control Structure
1382 These Lisp forms make bindings to variables and function names,
1383 analogous to Lisp's built-in `let' form.
1385 *Note Modify Macros::, for the `letf' and `letf*' forms which are
1386 also related to variable bindings.
1390 * Dynamic Bindings:: The `progv' form
1391 * Lexical Bindings:: `lexical-let' and lexical closures
1392 * Function Bindings:: `flet' and `labels'
1393 * Macro Bindings:: `macrolet' and `symbol-macrolet'
1396 File: cl.info, Node: Dynamic Bindings, Next: Lexical Bindings, Prev: Variable Bindings, Up: Variable Bindings
1401 The standard `let' form binds variables whose names are known at
1402 compile-time. The `progv' form provides an easy way to bind variables
1403 whose names are computed at run-time.
1405 - Special Form: progv symbols values forms...
1406 This form establishes `let'-style variable bindings on a set of
1407 variables computed at run-time. The expressions SYMBOLS and
1408 VALUES are evaluated, and must return lists of symbols and values,
1409 respectively. The symbols are bound to the corresponding values
1410 for the duration of the body FORMs. If VALUES is shorter than
1411 SYMBOLS, the last few symbols are made unbound (as if by
1412 `makunbound') inside the body. If SYMBOLS is shorter than VALUES,
1413 the excess values are ignored.
1416 File: cl.info, Node: Lexical Bindings, Next: Function Bindings, Prev: Dynamic Bindings, Up: Variable Bindings
1421 The "CL" package defines the following macro which more closely follows
1422 the Common Lisp `let' form:
1424 - Special Form: lexical-let (bindings...) forms...
1425 This form is exactly like `let' except that the bindings it
1426 establishes are purely lexical. Lexical bindings are similar to
1427 local variables in a language like C: Only the code physically
1428 within the body of the `lexical-let' (after macro expansion) may
1429 refer to the bound variables.
1432 (defun foo (b) (+ a b))
1433 (let ((a 2)) (foo a))
1435 (lexical-let ((a 2)) (foo a))
1438 In this example, a regular `let' binding of `a' actually makes a
1439 temporary change to the global variable `a', so `foo' is able to
1440 see the binding of `a' to 2. But `lexical-let' actually creates a
1441 distinct local variable `a' for use within its body, without any
1442 effect on the global variable of the same name.
1444 The most important use of lexical bindings is to create "closures".
1445 A closure is a function object that refers to an outside lexical
1446 variable. For example:
1448 (defun make-adder (n)
1449 (lexical-let ((n n))
1450 (function (lambda (m) (+ n m)))))
1451 (setq add17 (make-adder 17))
1455 The call `(make-adder 17)' returns a function object which adds 17
1456 to its argument. If `let' had been used instead of `lexical-let',
1457 the function object would have referred to the global `n', which
1458 would have been bound to 17 only during the call to `make-adder'
1461 (defun make-counter ()
1462 (lexical-let ((n 0))
1463 (function* (lambda (&optional (m 1)) (incf n m)))))
1464 (setq count-1 (make-counter))
1467 (funcall count-1 14)
1469 (setq count-2 (make-counter))
1477 Here we see that each call to `make-counter' creates a distinct
1478 local variable `n', which serves as a private counter for the
1479 function object that is returned.
1481 Closed-over lexical variables persist until the last reference to
1482 them goes away, just like all other Lisp objects. For example,
1483 `count-2' refers to a function object which refers to an instance
1484 of the variable `n'; this is the only reference to that variable,
1485 so after `(setq count-2 nil)' the garbage collector would be able
1486 to delete this instance of `n'. Of course, if a `lexical-let'
1487 does not actually create any closures, then the lexical variables
1488 are free as soon as the `lexical-let' returns.
1490 Many closures are used only during the extent of the bindings they
1491 refer to; these are known as "downward funargs" in Lisp parlance.
1492 When a closure is used in this way, regular Emacs Lisp dynamic
1493 bindings suffice and will be more efficient than `lexical-let'
1496 (defun add-to-list (x list)
1497 (mapcar (function (lambda (y) (+ x y))) list))
1498 (add-to-list 7 '(1 2 5))
1501 Since this lambda is only used while `x' is still bound, it is not
1502 necessary to make a true closure out of it.
1504 You can use `defun' or `flet' inside a `lexical-let' to create a
1505 named closure. If several closures are created in the body of a
1506 single `lexical-let', they all close over the same instance of the
1509 The `lexical-let' form is an extension to Common Lisp. In true
1510 Common Lisp, all bindings are lexical unless declared otherwise.
1512 - Special Form: lexical-let* (bindings...) forms...
1513 This form is just like `lexical-let', except that the bindings are
1514 made sequentially in the manner of `let*'.
1517 File: cl.info, Node: Function Bindings, Next: Macro Bindings, Prev: Lexical Bindings, Up: Variable Bindings
1522 These forms make `let'-like bindings to functions instead of variables.
1524 - Special Form: flet (bindings...) forms...
1525 This form establishes `let'-style bindings on the function cells
1526 of symbols rather than on the value cells. Each BINDING must be a
1527 list of the form `(NAME ARGLIST FORMS...)', which defines a
1528 function exactly as if it were a `defun*' form. The function NAME
1529 is defined accordingly for the duration of the body of the `flet';
1530 then the old function definition, or lack thereof, is restored.
1532 While `flet' in Common Lisp establishes a lexical binding of NAME,
1533 Emacs Lisp `flet' makes a dynamic binding. The result is that
1534 `flet' affects indirect calls to a function as well as calls
1535 directly inside the `flet' form itself.
1537 You can use `flet' to disable or modify the behavior of a function
1538 in a temporary fashion. This will even work on Emacs primitives,
1539 although note that some calls to primitive functions internal to
1540 Emacs are made without going through the symbol's function cell,
1541 and so will not be affected by `flet'. For example,
1543 (flet ((message (&rest args) (push args saved-msgs)))
1546 This code attempts to replace the built-in function `message' with
1547 a function that simply saves the messages in a list rather than
1548 displaying them. The original definition of `message' will be
1549 restored after `do-something' exits. This code will work fine on
1550 messages generated by other Lisp code, but messages generated
1551 directly inside Emacs will not be caught since they make direct
1552 C-language calls to the message routines rather than going through
1553 the Lisp `message' function.
1555 Functions defined by `flet' may use the full Common Lisp argument
1556 notation supported by `defun*'; also, the function body is
1557 enclosed in an implicit block as if by `defun*'. *Note Program
1560 - Special Form: labels (bindings...) forms...
1561 The `labels' form is a synonym for `flet'. (In Common Lisp,
1562 `labels' and `flet' differ in ways that depend on their lexical
1563 scoping; these distinctions vanish in dynamically scoped Emacs
1567 File: cl.info, Node: Macro Bindings, Prev: Function Bindings, Up: Variable Bindings
1572 These forms create local macros and "symbol macros."
1574 - Special Form: macrolet (bindings...) forms...
1575 This form is analogous to `flet', but for macros instead of
1576 functions. Each BINDING is a list of the same form as the
1577 arguments to `defmacro*' (i.e., a macro name, argument list, and
1578 macro-expander forms). The macro is defined accordingly for use
1579 within the body of the `macrolet'.
1581 Because of the nature of macros, `macrolet' is lexically scoped
1582 even in Emacs Lisp: The `macrolet' binding will affect only calls
1583 that appear physically within the body FORMS, possibly after
1584 expansion of other macros in the body.
1586 - Special Form: symbol-macrolet (bindings...) forms...
1587 This form creates "symbol macros", which are macros that look like
1588 variable references rather than function calls. Each BINDING is a
1589 list `(VAR EXPANSION)'; any reference to VAR within the body FORMS
1590 is replaced by EXPANSION.
1593 (symbol-macrolet ((foo (car bar)))
1598 A `setq' of a symbol macro is treated the same as a `setf'. I.e.,
1599 `(setq foo 4)' in the above would be equivalent to `(setf foo 4)',
1600 which in turn expands to `(setf (car bar) 4)'.
1602 Likewise, a `let' or `let*' binding a symbol macro is treated like
1603 a `letf' or `letf*'. This differs from true Common Lisp, where
1604 the rules of lexical scoping cause a `let' binding to shadow a
1605 `symbol-macrolet' binding. In this package, only `lexical-let'
1606 and `lexical-let*' will shadow a symbol macro.
1608 There is no analogue of `defmacro' for symbol macros; all symbol
1609 macros are local. A typical use of `symbol-macrolet' is in the
1610 expansion of another macro:
1612 (defmacro* my-dolist ((x list) &rest body)
1613 (let ((var (gensym)))
1614 (list 'loop 'for var 'on list 'do
1615 (list* 'symbol-macrolet (list (list x (list 'car var)))
1618 (setq mylist '(1 2 3 4))
1619 (my-dolist (x mylist) (incf x))
1623 In this example, the `my-dolist' macro is similar to `dolist'
1624 (*note Iteration::) except that the variable `x' becomes a true
1625 reference onto the elements of the list. The `my-dolist' call
1626 shown here expands to
1628 (loop for G1234 on mylist do
1629 (symbol-macrolet ((x (car G1234)))
1632 which in turn expands to
1634 (loop for G1234 on mylist do (incf (car G1234)))
1636 *Note Loop Facility::, for a description of the `loop' macro.
1637 This package defines a nonstandard `in-ref' loop clause that works
1638 much like `my-dolist'.
1641 File: cl.info, Node: Conditionals, Next: Blocks and Exits, Prev: Variable Bindings, Up: Control Structure
1646 These conditional forms augment Emacs Lisp's simple `if', `and', `or',
1649 - Special Form: when test forms...
1650 This is a variant of `if' where there are no "else" forms, and
1651 possibly several "then" forms. In particular,
1655 is entirely equivalent to
1657 (if TEST (progn A B C) nil)
1659 - Special Form: unless test forms...
1660 This is a variant of `if' where there are no "then" forms, and
1661 possibly several "else" forms:
1665 is entirely equivalent to
1667 (when (not TEST) A B C)
1669 - Special Form: case keyform clause...
1670 This macro evaluates KEYFORM, then compares it with the key values
1671 listed in the various CLAUSEs. Whichever clause matches the key
1672 is executed; comparison is done by `eql'. If no clause matches,
1673 the `case' form returns `nil'. The clauses are of the form
1675 (KEYLIST BODY-FORMS...)
1677 where KEYLIST is a list of key values. If there is exactly one
1678 value, and it is not a cons cell or the symbol `nil' or `t', then
1679 it can be used by itself as a KEYLIST without being enclosed in a
1680 list. All key values in the `case' form must be distinct. The
1681 final clauses may use `t' in place of a KEYLIST to indicate a
1682 default clause that should be taken if none of the other clauses
1683 match. (The symbol `otherwise' is also recognized in place of
1684 `t'. To make a clause that matches the actual symbol `t', `nil',
1685 or `otherwise', enclose the symbol in a list.)
1687 For example, this expression reads a keystroke, then does one of
1688 four things depending on whether it is an `a', a `b', a <RET> or
1689 <LFD>, or anything else.
1694 ((?\r ?\n) (do-ret-thing))
1695 (t (do-other-thing)))
1697 - Special Form: ecase keyform clause...
1698 This macro is just like `case', except that if the key does not
1699 match any of the clauses, an error is signalled rather than simply
1702 - Special Form: typecase keyform clause...
1703 This macro is a version of `case' that checks for types rather
1704 than values. Each CLAUSE is of the form `(TYPE BODY...)'. *Note
1705 Type Predicates::, for a description of type specifiers. For
1709 (integer (munch-integer x))
1710 (float (munch-float x))
1711 (string (munch-integer (string-to-int x)))
1712 (t (munch-anything x)))
1714 The type specifier `t' matches any type of object; the word
1715 `otherwise' is also allowed. To make one clause match any of
1716 several types, use an `(or ...)' type specifier.
1718 - Special Form: etypecase keyform clause...
1719 This macro is just like `typecase', except that if the key does
1720 not match any of the clauses, an error is signalled rather than
1721 simply returning `nil'.
1724 File: cl.info, Node: Blocks and Exits, Next: Iteration, Prev: Conditionals, Up: Control Structure
1729 Common Lisp "blocks" provide a non-local exit mechanism very similar to
1730 `catch' and `throw', but lexically rather than dynamically scoped.
1731 This package actually implements `block' in terms of `catch'; however,
1732 the lexical scoping allows the optimizing byte-compiler to omit the
1733 costly `catch' step if the body of the block does not actually
1734 `return-from' the block.
1736 - Special Form: block name forms...
1737 The FORMS are evaluated as if by a `progn'. However, if any of
1738 the FORMS execute `(return-from NAME)', they will jump out and
1739 return directly from the `block' form. The `block' returns the
1740 result of the last FORM unless a `return-from' occurs.
1742 The `block'/`return-from' mechanism is quite similar to the
1743 `catch'/`throw' mechanism. The main differences are that block
1744 NAMEs are unevaluated symbols, rather than forms (such as quoted
1745 symbols) which evaluate to a tag at run-time; and also that blocks
1746 are lexically scoped whereas `catch'/`throw' are dynamically
1747 scoped. This means that functions called from the body of a
1748 `catch' can also `throw' to the `catch', but the `return-from'
1749 referring to a block name must appear physically within the FORMS
1750 that make up the body of the block. They may not appear within
1751 other called functions, although they may appear within macro
1752 expansions or `lambda's in the body. Block names and `catch'
1753 names form independent name-spaces.
1755 In true Common Lisp, `defun' and `defmacro' surround the function
1756 or expander bodies with implicit blocks with the same name as the
1757 function or macro. This does not occur in Emacs Lisp, but this
1758 package provides `defun*' and `defmacro*' forms which do create
1761 The Common Lisp looping constructs defined by this package, such
1762 as `loop' and `dolist', also create implicit blocks just as in
1765 Because they are implemented in terms of Emacs Lisp `catch' and
1766 `throw', blocks have the same overhead as actual `catch'
1767 constructs (roughly two function calls). However, Zawinski and
1768 Furuseth's optimizing byte compiler (standard in Emacs 19) will
1769 optimize away the `catch' if the block does not in fact contain
1770 any `return' or `return-from' calls that jump to it. This means
1771 that `do' loops and `defun*' functions which don't use `return'
1772 don't pay the overhead to support it.
1774 - Special Form: return-from name [result]
1775 This macro returns from the block named NAME, which must be an
1776 (unevaluated) symbol. If a RESULT form is specified, it is
1777 evaluated to produce the result returned from the `block'.
1778 Otherwise, `nil' is returned.
1780 - Special Form: return [result]
1781 This macro is exactly like `(return-from nil RESULT)'. Common
1782 Lisp loops like `do' and `dolist' implicitly enclose themselves in
1786 File: cl.info, Node: Iteration, Next: Loop Facility, Prev: Blocks and Exits, Up: Control Structure
1791 The macros described here provide more sophisticated, high-level
1792 looping constructs to complement Emacs Lisp's basic `while' loop.
1794 - Special Form: loop forms...
1795 The "CL" package supports both the simple, old-style meaning of
1796 `loop' and the extremely powerful and flexible feature known as
1797 the "Loop Facility" or "Loop Macro". This more advanced facility
1798 is discussed in the following section; *note Loop Facility::. The
1799 simple form of `loop' is described here.
1801 If `loop' is followed by zero or more Lisp expressions, then
1802 `(loop EXPRS...)' simply creates an infinite loop executing the
1803 expressions over and over. The loop is enclosed in an implicit
1806 (loop (foo) (if (no-more) (return 72)) (bar))
1808 is exactly equivalent to
1810 (block nil (while t (foo) (if (no-more) (return 72)) (bar)))
1812 If any of the expressions are plain symbols, the loop is instead
1813 interpreted as a Loop Macro specification as described later.
1814 (This is not a restriction in practice, since a plain symbol in
1815 the above notation would simply access and throw away the value of
1818 - Special Form: do (spec...) (end-test [result...]) forms...
1819 This macro creates a general iterative loop. Each SPEC is of the
1824 The loop works as follows: First, each VAR is bound to the
1825 associated INIT value as if by a `let' form. Then, in each
1826 iteration of the loop, the END-TEST is evaluated; if true, the
1827 loop is finished. Otherwise, the body FORMS are evaluated, then
1828 each VAR is set to the associated STEP expression (as if by a
1829 `psetq' form) and the next iteration begins. Once the END-TEST
1830 becomes true, the RESULT forms are evaluated (with the VARs still
1831 bound to their values) to produce the result returned by `do'.
1833 The entire `do' loop is enclosed in an implicit `nil' block, so
1834 that you can use `(return)' to break out of the loop at any time.
1836 If there are no RESULT forms, the loop returns `nil'. If a given
1837 VAR has no STEP form, it is bound to its INIT value but not
1838 otherwise modified during the `do' loop (unless the code
1839 explicitly modifies it); this case is just a shorthand for putting
1840 a `(let ((VAR INIT)) ...)' around the loop. If INIT is also
1841 omitted it defaults to `nil', and in this case a plain `VAR' can
1842 be used in place of `(VAR)', again following the analogy with
1845 This example (from Steele) illustrates a loop which applies the
1846 function `f' to successive pairs of values from the lists `foo'
1847 and `bar'; it is equivalent to the call `(mapcar* 'f foo bar)'.
1848 Note that this loop has no body FORMS at all, performing all its
1849 work as side effects of the rest of the loop.
1851 (do ((x foo (cdr x))
1853 (z nil (cons (f (car x) (car y)) z)))
1854 ((or (null x) (null y))
1857 - Special Form: do* (spec...) (end-test [result...]) forms...
1858 This is to `do' what `let*' is to `let'. In particular, the
1859 initial values are bound as if by `let*' rather than `let', and
1860 the steps are assigned as if by `setq' rather than `psetq'.
1862 Here is another way to write the above loop:
1864 (do* ((xp foo (cdr xp))
1866 (x (car xp) (car xp))
1867 (y (car yp) (car yp))
1869 ((or (null xp) (null yp))
1873 - Special Form: dolist (var list [result]) forms...
1874 This is a more specialized loop which iterates across the elements
1875 of a list. LIST should evaluate to a list; the body FORMS are
1876 executed with VAR bound to each element of the list in turn.
1877 Finally, the RESULT form (or `nil') is evaluated with VAR bound to
1878 `nil' to produce the result returned by the loop. The loop is
1879 surrounded by an implicit `nil' block.
1881 - Special Form: dotimes (var count [result]) forms...
1882 This is a more specialized loop which iterates a specified number
1883 of times. The body is executed with VAR bound to the integers
1884 from zero (inclusive) to COUNT (exclusive), in turn. Then the
1885 `result' form is evaluated with VAR bound to the total number of
1886 iterations that were done (i.e., `(max 0 COUNT)') to get the
1887 return value for the loop form. The loop is surrounded by an
1888 implicit `nil' block.
1890 - Special Form: do-symbols (var [obarray [result]]) forms...
1891 This loop iterates over all interned symbols. If OBARRAY is
1892 specified and is not `nil', it loops over all symbols in that
1893 obarray. For each symbol, the body FORMS are evaluated with VAR
1894 bound to that symbol. The symbols are visited in an unspecified
1895 order. Afterward the RESULT form, if any, is evaluated (with VAR
1896 bound to `nil') to get the return value. The loop is surrounded
1897 by an implicit `nil' block.
1899 - Special Form: do-all-symbols (var [result]) forms...
1900 This is identical to `do-symbols' except that the OBARRAY argument
1901 is omitted; it always iterates over the default obarray.
1903 *Note Mapping over Sequences::, for some more functions for
1904 iterating over vectors or lists.
1907 File: cl.info, Node: Loop Facility, Next: Multiple Values, Prev: Iteration, Up: Control Structure
1912 A common complaint with Lisp's traditional looping constructs is that
1913 they are either too simple and limited, such as Common Lisp's `dotimes'
1914 or Emacs Lisp's `while', or too unreadable and obscure, like Common
1917 To remedy this, recent versions of Common Lisp have added a new
1918 construct called the "Loop Facility" or "`loop' macro," with an
1919 easy-to-use but very powerful and expressive syntax.
1923 * Loop Basics:: `loop' macro, basic clause structure
1924 * Loop Examples:: Working examples of `loop' macro
1925 * For Clauses:: Clauses introduced by `for' or `as'
1926 * Iteration Clauses:: `repeat', `while', `thereis', etc.
1927 * Accumulation Clauses:: `collect', `sum', `maximize', etc.
1928 * Other Clauses:: `with', `if', `initially', `finally'
1931 File: cl.info, Node: Loop Basics, Next: Loop Examples, Prev: Loop Facility, Up: Loop Facility
1936 The `loop' macro essentially creates a mini-language within Lisp that
1937 is specially tailored for describing loops. While this language is a
1938 little strange-looking by the standards of regular Lisp, it turns out
1939 to be very easy to learn and well-suited to its purpose.
1941 Since `loop' is a macro, all parsing of the loop language takes
1942 place at byte-compile time; compiled `loop's are just as efficient as
1943 the equivalent `while' loops written longhand.
1945 - Special Form: loop clauses...
1946 A loop construct consists of a series of CLAUSEs, each introduced
1947 by a symbol like `for' or `do'. Clauses are simply strung
1948 together in the argument list of `loop', with minimal extra
1949 parentheses. The various types of clauses specify
1950 initializations, such as the binding of temporary variables,
1951 actions to be taken in the loop, stepping actions, and final
1954 Common Lisp specifies a certain general order of clauses in a loop:
1960 The NAME-CLAUSE optionally gives a name to the implicit block that
1961 surrounds the loop. By default, the implicit block is named
1962 `nil'. The VAR-CLAUSES specify what variables should be bound
1963 during the loop, and how they should be modified or iterated
1964 throughout the course of the loop. The ACTION-CLAUSES are things
1965 to be done during the loop, such as computing, collecting, and
1968 The Emacs version of the `loop' macro is less restrictive about
1969 the order of clauses, but things will behave most predictably if
1970 you put the variable-binding clauses `with', `for', and `repeat'
1971 before the action clauses. As in Common Lisp, `initially' and
1972 `finally' clauses can go anywhere.
1974 Loops generally return `nil' by default, but you can cause them to
1975 return a value by using an accumulation clause like `collect', an
1976 end-test clause like `always', or an explicit `return' clause to
1977 jump out of the implicit block. (Because the loop body is
1978 enclosed in an implicit block, you can also use regular Lisp
1979 `return' or `return-from' to break out of the loop.)
1981 The following sections give some examples of the Loop Macro in
1982 action, and describe the particular loop clauses in great detail.
1983 Consult the second edition of Steele's "Common Lisp, the Language", for
1984 additional discussion and examples of the `loop' macro.
1987 File: cl.info, Node: Loop Examples, Next: For Clauses, Prev: Loop Basics, Up: Loop Facility
1992 Before listing the full set of clauses that are allowed, let's look at
1993 a few example loops just to get a feel for the `loop' language.
1995 (loop for buf in (buffer-list)
1996 collect (buffer-file-name buf))
1998 This loop iterates over all Emacs buffers, using the list returned by
1999 `buffer-list'. For each buffer `buf', it calls `buffer-file-name' and
2000 collects the results into a list, which is then returned from the
2001 `loop' construct. The result is a list of the file names of all the
2002 buffers in Emacs' memory. The words `for', `in', and `collect' are
2003 reserved words in the `loop' language.
2005 (loop repeat 20 do (insert "Yowsa\n"))
2007 This loop inserts the phrase "Yowsa" twenty times in the current buffer.
2009 (loop until (eobp) do (munch-line) (forward-line 1))
2011 This loop calls `munch-line' on every line until the end of the buffer.
2012 If point is already at the end of the buffer, the loop exits
2015 (loop do (munch-line) until (eobp) do (forward-line 1))
2017 This loop is similar to the above one, except that `munch-line' is
2018 always called at least once.
2020 (loop for x from 1 to 100
2023 finally return (list x (= y 729)))
2025 This more complicated loop searches for a number `x' whose square is
2026 729. For safety's sake it only examines `x' values up to 100; dropping
2027 the phrase `to 100' would cause the loop to count upwards with no
2028 limit. The second `for' clause defines `y' to be the square of `x'
2029 within the loop; the expression after the `=' sign is reevaluated each
2030 time through the loop. The `until' clause gives a condition for
2031 terminating the loop, and the `finally' clause says what to do when the
2032 loop finishes. (This particular example was written less concisely
2033 than it could have been, just for the sake of illustration.)
2035 Note that even though this loop contains three clauses (two `for's
2036 and an `until') that would have been enough to define loops all by
2037 themselves, it still creates a single loop rather than some sort of
2038 triple-nested loop. You must explicitly nest your `loop' constructs if
2039 you want nested loops.
2042 File: cl.info, Node: For Clauses, Next: Iteration Clauses, Prev: Loop Examples, Up: Loop Facility
2047 Most loops are governed by one or more `for' clauses. A `for' clause
2048 simultaneously describes variables to be bound, how those variables are
2049 to be stepped during the loop, and usually an end condition based on
2052 The word `as' is a synonym for the word `for'. This word is
2053 followed by a variable name, then a word like `from' or `across' that
2054 describes the kind of iteration desired. In Common Lisp, the phrase
2055 `being the' sometimes precedes the type of iteration; in this package
2056 both `being' and `the' are optional. The word `each' is a synonym for
2057 `the', and the word that follows it may be singular or plural: `for x
2058 being the elements of y' or `for x being each element of y'. Which
2059 form you use is purely a matter of style.
2061 The variable is bound around the loop as if by `let':
2064 (loop for i from 1 to 10 do (do-something-with i))
2068 `for VAR from EXPR1 to EXPR2 by EXPR3'
2069 This type of `for' clause creates a counting loop. Each of the
2070 three sub-terms is optional, though there must be at least one
2071 term so that the clause is marked as a counting clause.
2073 The three expressions are the starting value, the ending value, and
2074 the step value, respectively, of the variable. The loop counts
2075 upwards by default (EXPR3 must be positive), from EXPR1 to EXPR2
2076 inclusively. If you omit the `from' term, the loop counts from
2077 zero; if you omit the `to' term, the loop counts forever without
2078 stopping (unless stopped by some other loop clause, of course); if
2079 you omit the `by' term, the loop counts in steps of one.
2081 You can replace the word `from' with `upfrom' or `downfrom' to
2082 indicate the direction of the loop. Likewise, you can replace
2083 `to' with `upto' or `downto'. For example, `for x from 5 downto
2084 1' executes five times with `x' taking on the integers from 5 down
2085 to 1 in turn. Also, you can replace `to' with `below' or `above',
2086 which are like `upto' and `downto' respectively except that they
2087 are exclusive rather than inclusive limits:
2089 (loop for x to 10 collect x)
2090 => (0 1 2 3 4 5 6 7 8 9 10)
2091 (loop for x below 10 collect x)
2092 => (0 1 2 3 4 5 6 7 8 9)
2094 The `by' value is always positive, even for downward-counting
2095 loops. Some sort of `from' value is required for downward loops;
2096 `for x downto 5' is not a legal loop clause all by itself.
2098 `for VAR in LIST by FUNCTION'
2099 This clause iterates VAR over all the elements of LIST, in turn.
2100 If you specify the `by' term, then FUNCTION is used to traverse
2101 the list instead of `cdr'; it must be a function taking one
2102 argument. For example:
2104 (loop for x in '(1 2 3 4 5 6) collect (* x x))
2106 (loop for x in '(1 2 3 4 5 6) by 'cddr collect (* x x))
2109 `for VAR on LIST by FUNCTION'
2110 This clause iterates VAR over all the cons cells of LIST.
2112 (loop for x on '(1 2 3 4) collect x)
2113 => ((1 2 3 4) (2 3 4) (3 4) (4))
2115 With `by', there is no real reason that the `on' expression must
2116 be a list. For example:
2118 (loop for x on first-animal by 'next-animal collect x)
2120 where `(next-animal x)' takes an "animal" X and returns the next
2121 in the (assumed) sequence of animals, or `nil' if X was the last
2122 animal in the sequence.
2124 `for VAR in-ref LIST by FUNCTION'
2125 This is like a regular `in' clause, but VAR becomes a `setf'-able
2126 "reference" onto the elements of the list rather than just a
2127 temporary variable. For example,
2129 (loop for x in-ref my-list do (incf x))
2131 increments every element of `my-list' in place. This clause is an
2132 extension to standard Common Lisp.
2134 `for VAR across ARRAY'
2135 This clause iterates VAR over all the elements of ARRAY, which may
2136 be a vector or a string.
2138 (loop for x across "aeiou"
2139 do (use-vowel (char-to-string x)))
2141 `for VAR across-ref ARRAY'
2142 This clause iterates over an array, with VAR a `setf'-able
2143 reference onto the elements; see `in-ref' above.
2145 `for VAR being the elements of SEQUENCE'
2146 This clause iterates over the elements of SEQUENCE, which may be a
2147 list, vector, or string. Since the type must be determined at
2148 run-time, this is somewhat less efficient than `in' or `across'.
2149 The clause may be followed by the additional term `using (index
2150 VAR2)' to cause VAR2 to be bound to the successive indices
2151 (starting at 0) of the elements.
2153 This clause type is taken from older versions of the `loop' macro,
2154 and is not present in modern Common Lisp. The `using (sequence
2155 ...)' term of the older macros is not supported.
2157 `for VAR being the elements of-ref SEQUENCE'
2158 This clause iterates over a sequence, with VAR a `setf'-able
2159 reference onto the elements; see `in-ref' above.
2161 `for VAR being the symbols [of OBARRAY]'
2162 This clause iterates over symbols, either over all interned symbols
2163 or over all symbols in OBARRAY. The loop is executed with VAR
2164 bound to each symbol in turn. The symbols are visited in an
2169 (loop for sym being the symbols
2171 when (string-match "^map" (symbol-name sym))
2174 returns a list of all the functions whose names begin with `map'.
2176 The Common Lisp words `external-symbols' and `present-symbols' are
2177 also recognized but are equivalent to `symbols' in Emacs Lisp.
2179 Due to a minor implementation restriction, it will not work to have
2180 more than one `for' clause iterating over symbols, hash tables,
2181 keymaps, overlays, or intervals in a given `loop'. Fortunately,
2182 it would rarely if ever be useful to do so. It _is_ legal to mix
2183 one of these types of clauses with other clauses like `for ... to'
2186 `for VAR being the hash-keys of HASH-TABLE'
2187 This clause iterates over the entries in HASH-TABLE. For each
2188 hash table entry, VAR is bound to the entry's key. If you write
2189 `the hash-values' instead, VAR is bound to the values of the
2190 entries. The clause may be followed by the additional term `using
2191 (hash-values VAR2)' (where `hash-values' is the opposite word of
2192 the word following `the') to cause VAR and VAR2 to be bound to the
2193 two parts of each hash table entry.
2195 `for VAR being the key-codes of KEYMAP'
2196 This clause iterates over the entries in KEYMAP. In GNU Emacs 18
2197 and 19, keymaps are either alists or vectors, and key-codes are
2198 integers or symbols. In XEmacs, keymaps are a special new data
2199 type, and key-codes are symbols or lists of symbols. The
2200 iteration does not enter nested keymaps or inherited (parent)
2201 keymaps. You can use `the key-bindings' to access the commands
2202 bound to the keys rather than the key codes, and you can add a
2203 `using' clause to access both the codes and the bindings together.
2205 `for VAR being the key-seqs of KEYMAP'
2206 This clause iterates over all key sequences defined by KEYMAP and
2207 its nested keymaps, where VAR takes on values which are strings in
2208 Emacs 18 or vectors in Emacs 19. The strings or vectors are
2209 reused for each iteration, so you must copy them if you wish to
2210 keep them permanently. You can add a `using (key-bindings ...)'
2211 clause to get the command bindings as well.
2213 `for VAR being the overlays [of BUFFER] ...'
2214 This clause iterates over the Emacs 19 "overlays" or XEmacs
2215 "extents" of a buffer (the clause `extents' is synonymous with
2216 `overlays'). Under Emacs 18, this clause iterates zero times. If
2217 the `of' term is omitted, the current buffer is used. This clause
2218 also accepts optional `from POS' and `to POS' terms, limiting the
2219 clause to overlays which overlap the specified region.
2221 `for VAR being the intervals [of BUFFER] ...'
2222 This clause iterates over all intervals of a buffer with constant
2223 text properties. The variable VAR will be bound to conses of
2224 start and end positions, where one start position is always equal
2225 to the previous end position. The clause allows `of', `from',
2226 `to', and `property' terms, where the latter term restricts the
2227 search to just the specified property. The `of' term may specify
2228 either a buffer or a string. This clause is useful only in GNU
2229 Emacs 19; in other versions, all buffers and strings consist of a
2232 `for VAR being the frames'
2233 This clause iterates over all frames, i.e., X window system windows
2234 open on Emacs files. This clause works only under Emacs 19. The
2235 clause `screens' is a synonym for `frames'. The frames are
2236 visited in `next-frame' order starting from `selected-frame'.
2238 `for VAR being the windows [of FRAME]'
2239 This clause iterates over the windows (in the Emacs sense) of the
2240 current frame, or of the specified FRAME. (In Emacs 18 there is
2241 only ever one frame, and the `of' term is not allowed there.)
2243 `for VAR being the buffers'
2244 This clause iterates over all buffers in Emacs. It is equivalent
2245 to `for VAR in (buffer-list)'.
2247 `for VAR = EXPR1 then EXPR2'
2248 This clause does a general iteration. The first time through the
2249 loop, VAR will be bound to EXPR1. On the second and successive
2250 iterations it will be set by evaluating EXPR2 (which may refer to
2251 the old value of VAR). For example, these two loops are
2252 effectively the same:
2254 (loop for x on my-list by 'cddr do ...)
2255 (loop for x = my-list then (cddr x) while x do ...)
2257 Note that this type of `for' clause does not imply any sort of
2258 terminating condition; the above example combines it with a
2259 `while' clause to tell when to end the loop.
2261 If you omit the `then' term, EXPR1 is used both for the initial
2262 setting and for successive settings:
2264 (loop for x = (random) when (> x 0) return x)
2266 This loop keeps taking random numbers from the `(random)' function
2267 until it gets a positive one, which it then returns.
2269 If you include several `for' clauses in a row, they are treated
2270 sequentially (as if by `let*' and `setq'). You can instead use the
2271 word `and' to link the clauses, in which case they are processed in
2272 parallel (as if by `let' and `psetq').
2274 (loop for x below 5 for y = nil then x collect (list x y))
2275 => ((0 nil) (1 1) (2 2) (3 3) (4 4))
2276 (loop for x below 5 and y = nil then x collect (list x y))
2277 => ((0 nil) (1 0) (2 1) (3 2) (4 3))
2279 In the first loop, `y' is set based on the value of `x' that was just
2280 set by the previous clause; in the second loop, `x' and `y' are set
2281 simultaneously so `y' is set based on the value of `x' left over from
2282 the previous time through the loop.
2284 Another feature of the `loop' macro is "destructuring", similar in
2285 concept to the destructuring provided by `defmacro'. The VAR part of
2286 any `for' clause can be given as a list of variables instead of a
2287 single variable. The values produced during loop execution must be
2288 lists; the values in the lists are stored in the corresponding
2291 (loop for (x y) in '((2 3) (4 5) (6 7)) collect (+ x y))
2294 In loop destructuring, if there are more values than variables the
2295 trailing values are ignored, and if there are more variables than
2296 values the trailing variables get the value `nil'. If `nil' is used as
2297 a variable name, the corresponding values are ignored. Destructuring
2298 may be nested, and dotted lists of variables like `(x . y)' are allowed.
2301 File: cl.info, Node: Iteration Clauses, Next: Accumulation Clauses, Prev: For Clauses, Up: Loop Facility
2306 Aside from `for' clauses, there are several other loop clauses that
2307 control the way the loop operates. They might be used by themselves,
2308 or in conjunction with one or more `for' clauses.
2311 This clause simply counts up to the specified number using an
2312 internal temporary variable. The loops
2314 (loop repeat n do ...)
2315 (loop for temp to n do ...)
2317 are identical except that the second one forces you to choose a
2318 name for a variable you aren't actually going to use.
2321 This clause stops the loop when the specified condition (any Lisp
2322 expression) becomes `nil'. For example, the following two loops
2323 are equivalent, except for the implicit `nil' block that surrounds
2326 (while COND FORMS...)
2327 (loop while COND do FORMS...)
2330 This clause stops the loop when the specified condition is true,
2334 This clause stops the loop when the specified condition is `nil'.
2335 Unlike `while', it stops the loop using `return nil' so that the
2336 `finally' clauses are not executed. If all the conditions were
2337 non-`nil', the loop returns `t':
2339 (if (loop for size in size-list always (> size 10))
2344 This clause is like `always', except that the loop returns `t' if
2345 any conditions were false, or `nil' otherwise.
2348 This clause stops the loop when the specified form is non-`nil';
2349 in this case, it returns that non-`nil' value. If all the values
2350 were `nil', the loop returns `nil'.
2353 File: cl.info, Node: Accumulation Clauses, Next: Other Clauses, Prev: Iteration Clauses, Up: Loop Facility
2355 Accumulation Clauses
2356 --------------------
2358 These clauses cause the loop to accumulate information about the
2359 specified Lisp FORM. The accumulated result is returned from the loop
2360 unless overridden, say, by a `return' clause.
2363 This clause collects the values of FORM into a list. Several
2364 examples of `collect' appear elsewhere in this manual.
2366 The word `collecting' is a synonym for `collect', and likewise for
2367 the other accumulation clauses.
2370 This clause collects lists of values into a result list using
2374 This clause collects lists of values into a result list by
2375 destructively modifying the lists rather than copying them.
2378 This clause concatenates the values of the specified FORM into a
2379 string. (It and the following clause are extensions to standard
2383 This clause concatenates the values of the specified FORM into a
2387 This clause counts the number of times the specified FORM
2388 evaluates to a non-`nil' value.
2391 This clause accumulates the sum of the values of the specified
2392 FORM, which must evaluate to a number.
2395 This clause accumulates the maximum value of the specified FORM,
2396 which must evaluate to a number. The return value is undefined if
2397 `maximize' is executed zero times.
2400 This clause accumulates the minimum value of the specified FORM.
2402 Accumulation clauses can be followed by `into VAR' to cause the data
2403 to be collected into variable VAR (which is automatically `let'-bound
2404 during the loop) rather than an unnamed temporary variable. Also,
2405 `into' accumulations do not automatically imply a return value. The
2406 loop must use some explicit mechanism, such as `finally return', to
2407 return the accumulated result.
2409 It is legal for several accumulation clauses of the same type to
2410 accumulate into the same place. From Steele:
2412 (loop for name in '(fred sue alice joe june)
2413 for kids in '((bob ken) () () (kris sunshine) ())
2416 => (fred bob ken sue alice joe kris sunshine june)
2419 File: cl.info, Node: Other Clauses, Prev: Accumulation Clauses, Up: Loop Facility
2424 This section describes the remaining loop clauses.
2427 This clause binds a variable to a value around the loop, but
2428 otherwise leaves the variable alone during the loop. The following
2429 loops are basically equivalent:
2431 (loop with x = 17 do ...)
2432 (let ((x 17)) (loop do ...))
2433 (loop for x = 17 then x do ...)
2435 Naturally, the variable VAR might be used for some purpose in the
2436 rest of the loop. For example:
2438 (loop for x in my-list with res = nil do (push x res)
2441 This loop inserts the elements of `my-list' at the front of a new
2442 list being accumulated in `res', then returns the list `res' at
2443 the end of the loop. The effect is similar to that of a `collect'
2444 clause, but the list gets reversed by virtue of the fact that
2445 elements are being pushed onto the front of `res' rather than the
2448 If you omit the `=' term, the variable is initialized to `nil'.
2449 (Thus the `= nil' in the above example is unnecessary.)
2451 Bindings made by `with' are sequential by default, as if by
2452 `let*'. Just like `for' clauses, `with' clauses can be linked
2453 with `and' to cause the bindings to be made by `let' instead.
2455 `if CONDITION CLAUSE'
2456 This clause executes the following loop clause only if the
2457 specified condition is true. The following CLAUSE should be an
2458 accumulation, `do', `return', `if', or `unless' clause. Several
2459 clauses may be linked by separating them with `and'. These
2460 clauses may be followed by `else' and a clause or clauses to
2461 execute if the condition was false. The whole construct may
2462 optionally be followed by the word `end' (which may be used to
2463 disambiguate an `else' or `and' in a nested `if').
2465 The actual non-`nil' value of the condition form is available by
2466 the name `it' in the "then" part. For example:
2468 (setq funny-numbers '(6 13 -1))
2470 (loop for x below 10
2473 and if (memq x funny-numbers) return (cdr it) end
2475 collect x into evens
2476 finally return (vector odds evens))
2477 => [(1 3 5 7 9) (0 2 4 6 8)]
2478 (setq funny-numbers '(6 7 13 -1))
2480 (loop <same thing again>)
2483 Note the use of `and' to put two clauses into the "then" part, one
2484 of which is itself an `if' clause. Note also that `end', while
2485 normally optional, was necessary here to make it clear that the
2486 `else' refers to the outermost `if' clause. In the first case,
2487 the loop returns a vector of lists of the odd and even values of
2488 X. In the second case, the odd number 7 is one of the
2489 `funny-numbers' so the loop returns early; the actual returned
2490 value is based on the result of the `memq' call.
2492 `when CONDITION CLAUSE'
2493 This clause is just a synonym for `if'.
2495 `unless CONDITION CLAUSE'
2496 The `unless' clause is just like `if' except that the sense of the
2497 condition is reversed.
2500 This clause gives a name other than `nil' to the implicit block
2501 surrounding the loop. The NAME is the symbol to be used as the
2504 `initially [do] FORMS...'
2505 This keyword introduces one or more Lisp forms which will be
2506 executed before the loop itself begins (but after any variables
2507 requested by `for' or `with' have been bound to their initial
2508 values). `initially' clauses can appear anywhere; if there are
2509 several, they are executed in the order they appear in the loop.
2510 The keyword `do' is optional.
2512 `finally [do] FORMS...'
2513 This introduces Lisp forms which will be executed after the loop
2514 finishes (say, on request of a `for' or `while'). `initially' and
2515 `finally' clauses may appear anywhere in the loop construct, but
2516 they are executed (in the specified order) at the beginning or
2517 end, respectively, of the loop.
2519 `finally return FORM'
2520 This says that FORM should be executed after the loop is done to
2521 obtain a return value. (Without this, or some other clause like
2522 `collect' or `return', the loop will simply return `nil'.)
2523 Variables bound by `for', `with', or `into' will still contain
2524 their final values when FORM is executed.
2527 The word `do' may be followed by any number of Lisp expressions
2528 which are executed as an implicit `progn' in the body of the loop.
2529 Many of the examples in this section illustrate the use of `do'.
2532 This clause causes the loop to return immediately. The following
2533 Lisp form is evaluated to give the return value of the `loop'
2534 form. The `finally' clauses, if any, are not executed. Of
2535 course, `return' is generally used inside an `if' or `unless', as
2536 its use in a top-level loop clause would mean the loop would never
2537 get to "loop" more than once.
2539 The clause `return FORM' is equivalent to `do (return FORM)' (or
2540 `return-from' if the loop was named). The `return' clause is
2541 implemented a bit more efficiently, though.
2543 While there is no high-level way to add user extensions to `loop'
2544 (comparable to `defsetf' for `setf', say), this package does offer two
2545 properties called `cl-loop-handler' and `cl-loop-for-handler' which are
2546 functions to be called when a given symbol is encountered as a
2547 top-level loop clause or `for' clause, respectively. Consult the
2548 source code in file `cl-macs.el' for details.
2550 This package's `loop' macro is compatible with that of Common Lisp,
2551 except that a few features are not implemented: `loop-finish' and
2552 data-type specifiers. Naturally, the `for' clauses which iterate over
2553 keymaps, overlays, intervals, frames, windows, and buffers are
2554 Emacs-specific extensions.
2557 File: cl.info, Node: Multiple Values, Prev: Loop Facility, Up: Control Structure
2562 Common Lisp functions can return zero or more results. Emacs Lisp
2563 functions, by contrast, always return exactly one result. This package
2564 makes no attempt to emulate Common Lisp multiple return values; Emacs
2565 versions of Common Lisp functions that return more than one value
2566 either return just the first value (as in `compiler-macroexpand') or
2567 return a list of values (as in `get-setf-method'). This package _does_
2568 define placeholders for the Common Lisp functions that work with
2569 multiple values, but in Emacs Lisp these functions simply operate on
2570 lists instead. The `values' form, for example, is a synonym for `list'
2573 - Special Form: multiple-value-bind (var...) values-form forms...
2574 This form evaluates VALUES-FORM, which must return a list of
2575 values. It then binds the VARs to these respective values, as if
2576 by `let', and then executes the body FORMS. If there are more
2577 VARs than values, the extra VARs are bound to `nil'. If there are
2578 fewer VARs than values, the excess values are ignored.
2580 - Special Form: multiple-value-setq (var...) form
2581 This form evaluates FORM, which must return a list of values. It
2582 then sets the VARs to these respective values, as if by `setq'.
2583 Extra VARs or values are treated the same as in
2584 `multiple-value-bind'.
2586 The older Quiroz package attempted a more faithful (but still
2587 imperfect) emulation of Common Lisp multiple values. The old method
2588 "usually" simulated true multiple values quite well, but under certain
2589 circumstances would leave spurious return values in memory where a
2590 later, unrelated `multiple-value-bind' form would see them.
2592 Since a perfect emulation is not feasible in Emacs Lisp, this
2593 package opts to keep it as simple and predictable as possible.
2596 File: cl.info, Node: Macros, Next: Declarations, Prev: Control Structure, Up: Top
2601 This package implements the various Common Lisp features of `defmacro',
2602 such as destructuring, `&environment', and `&body'. Top-level `&whole'
2603 is not implemented for `defmacro' due to technical difficulties. *Note
2606 Destructuring is made available to the user by way of the following
2609 - Special Form: destructuring-bind arglist expr forms...
2610 This macro expands to code which executes FORMS, with the
2611 variables in ARGLIST bound to the list of values returned by EXPR.
2612 The ARGLIST can include all the features allowed for `defmacro'
2613 argument lists, including destructuring. (The `&environment'
2614 keyword is not allowed.) The macro expansion will signal an error
2615 if EXPR returns a list of the wrong number of arguments or with
2616 incorrect keyword arguments.
2618 This package also includes the Common Lisp `define-compiler-macro'
2619 facility, which allows you to define compile-time expansions and
2620 optimizations for your functions.
2622 - Special Form: define-compiler-macro name arglist forms...
2623 This form is similar to `defmacro', except that it only expands
2624 calls to NAME at compile-time; calls processed by the Lisp
2625 interpreter are not expanded, nor are they expanded by the
2626 `macroexpand' function.
2628 The argument list may begin with a `&whole' keyword and a
2629 variable. This variable is bound to the macro-call form itself,
2630 i.e., to a list of the form `(NAME ARGS...)'. If the macro
2631 expander returns this form unchanged, then the compiler treats it
2632 as a normal function call. This allows compiler macros to work as
2633 optimizers for special cases of a function, leaving complicated
2636 For example, here is a simplified version of a definition that
2637 appears as a standard part of this package:
2639 (define-compiler-macro member* (&whole form a list &rest keys)
2640 (if (and (null keys)
2641 (eq (car-safe a) 'quote)
2642 (not (floatp-safe (cadr a))))
2646 This definition causes `(member* A LIST)' to change to a call to
2647 the faster `memq' in the common case where A is a
2648 non-floating-point constant; if A is anything else, or if there
2649 are any keyword arguments in the call, then the original `member*'
2650 call is left intact. (The actual compiler macro for `member*'
2651 optimizes a number of other cases, including common `:test'
2654 - Function: compiler-macroexpand form
2655 This function is analogous to `macroexpand', except that it
2656 expands compiler macros rather than regular macros. It returns
2657 FORM unchanged if it is not a call to a function for which a
2658 compiler macro has been defined, or if that compiler macro decided
2659 to punt by returning its `&whole' argument. Like `macroexpand',
2660 it expands repeatedly until it reaches a form for which no further
2661 expansion is possible.
2663 *Note Macro Bindings::, for descriptions of the `macrolet' and
2664 `symbol-macrolet' forms for making "local" macro definitions.
2667 File: cl.info, Node: Declarations, Next: Symbols, Prev: Macros, Up: Top
2672 Common Lisp includes a complex and powerful "declaration" mechanism
2673 that allows you to give the compiler special hints about the types of
2674 data that will be stored in particular variables, and about the ways
2675 those variables and functions will be used. This package defines
2676 versions of all the Common Lisp declaration forms: `declare',
2677 `locally', `proclaim', `declaim', and `the'.
2679 Most of the Common Lisp declarations are not currently useful in
2680 Emacs Lisp, as the byte-code system provides little opportunity to
2681 benefit from type information, and `special' declarations are redundant
2682 in a fully dynamically-scoped Lisp. A few declarations are meaningful
2683 when the optimizing Emacs 19 byte compiler is being used, however.
2684 Under the earlier non-optimizing compiler, these declarations will
2685 effectively be ignored.
2687 - Function: proclaim decl-spec
2688 This function records a "global" declaration specified by
2689 DECL-SPEC. Since `proclaim' is a function, DECL-SPEC is evaluated
2690 and thus should normally be quoted.
2692 - Special Form: declaim decl-specs...
2693 This macro is like `proclaim', except that it takes any number of
2694 DECL-SPEC arguments, and the arguments are unevaluated and
2695 unquoted. The `declaim' macro also puts an `(eval-when (compile
2696 load eval) ...)' around the declarations so that they will be
2697 registered at compile-time as well as at run-time. (This is vital,
2698 since normally the declarations are meant to influence the way the
2699 compiler treats the rest of the file that contains the `declaim'
2702 - Special Form: declare decl-specs...
2703 This macro is used to make declarations within functions and other
2704 code. Common Lisp allows declarations in various locations,
2705 generally at the beginning of any of the many "implicit `progn's"
2706 throughout Lisp syntax, such as function bodies, `let' bodies,
2707 etc. Currently the only declaration understood by `declare' is
2710 - Special Form: locally declarations... forms...
2711 In this package, `locally' is no different from `progn'.
2713 - Special Form: the type form
2714 Type information provided by `the' is ignored in this package; in
2715 other words, `(the TYPE FORM)' is equivalent to FORM. Future
2716 versions of the optimizing byte-compiler may make use of this
2719 For example, `mapcar' can map over both lists and arrays. It is
2720 hard for the compiler to expand `mapcar' into an in-line loop
2721 unless it knows whether the sequence will be a list or an array
2722 ahead of time. With `(mapcar 'car (the vector foo))', a future
2723 compiler would have enough information to expand the loop in-line.
2724 For now, Emacs Lisp will treat the above code as exactly equivalent
2725 to `(mapcar 'car foo)'.
2727 Each DECL-SPEC in a `proclaim', `declaim', or `declare' should be a
2728 list beginning with a symbol that says what kind of declaration it is.
2729 This package currently understands `special', `inline', `notinline',
2730 `optimize', and `warn' declarations. (The `warn' declaration is an
2731 extension of standard Common Lisp.) Other Common Lisp declarations,
2732 such as `type' and `ftype', are silently ignored.
2735 Since all variables in Emacs Lisp are "special" (in the Common
2736 Lisp sense), `special' declarations are only advisory. They
2737 simply tell the optimizing byte compiler that the specified
2738 variables are intentionally being referred to without being bound
2739 in the body of the function. The compiler normally emits warnings
2740 for such references, since they could be typographical errors for
2741 references to local variables.
2743 The declaration `(declare (special VAR1 VAR2))' is equivalent to
2744 `(defvar VAR1) (defvar VAR2)' in the optimizing compiler, or to
2745 nothing at all in older compilers (which do not warn for non-local
2748 In top-level contexts, it is generally better to write `(defvar
2749 VAR)' than `(declaim (special VAR))', since `defvar' makes your
2750 intentions clearer. But the older byte compilers can not handle
2751 `defvar's appearing inside of functions, while `(declare (special
2752 VAR))' takes care to work correctly with all compilers.
2755 The `inline' DECL-SPEC lists one or more functions whose bodies
2756 should be expanded "in-line" into calling functions whenever the
2757 compiler is able to arrange for it. For example, the Common Lisp
2758 function `cadr' is declared `inline' by this package so that the
2759 form `(cadr X)' will expand directly into `(car (cdr X))' when it
2760 is called in user functions, for a savings of one (relatively
2761 expensive) function call.
2763 The following declarations are all equivalent. Note that the
2764 `defsubst' form is a convenient way to define a function and
2765 declare it inline all at once, but it is available only in Emacs
2768 (declaim (inline foo bar))
2769 (eval-when (compile load eval) (proclaim '(inline foo bar)))
2770 (proclaim-inline foo bar) ; XEmacs only
2771 (defsubst foo (...) ...) ; instead of defun; Emacs 19 only
2773 *Please note:* This declaration remains in effect after the
2774 containing source file is done. It is correct to use it to
2775 request that a function you have defined should be inlined, but it
2776 is impolite to use it to request inlining of an external function.
2778 In Common Lisp, it is possible to use `(declare (inline ...))'
2779 before a particular call to a function to cause just that call to
2780 be inlined; the current byte compilers provide no way to implement
2781 this, so `(declare (inline ...))' is currently ignored by this
2785 The `notinline' declaration lists functions which should not be
2786 inlined after all; it cancels a previous `inline' declaration.
2789 This declaration controls how much optimization is performed by
2790 the compiler. Naturally, it is ignored by the earlier
2791 non-optimizing compilers.
2793 The word `optimize' is followed by any number of lists like
2794 `(speed 3)' or `(safety 2)'. Common Lisp defines several
2795 optimization "qualities"; this package ignores all but `speed' and
2796 `safety'. The value of a quality should be an integer from 0 to
2797 3, with 0 meaning "unimportant" and 3 meaning "very important."
2798 The default level for both qualities is 1.
2800 In this package, with the Emacs 19 optimizing compiler, the
2801 `speed' quality is tied to the `byte-compile-optimize' flag, which
2802 is set to `nil' for `(speed 0)' and to `t' for higher settings;
2803 and the `safety' quality is tied to the
2804 `byte-compile-delete-errors' flag, which is set to `t' for
2805 `(safety 3)' and to `nil' for all lower settings. (The latter
2806 flag controls whether the compiler is allowed to optimize out code
2807 whose only side-effect could be to signal an error, e.g.,
2808 rewriting `(progn foo bar)' to `bar' when it is not known whether
2809 `foo' will be bound at run-time.)
2811 Note that even compiling with `(safety 0)', the Emacs byte-code
2812 system provides sufficient checking to prevent real harm from
2813 being done. For example, barring serious bugs in Emacs itself,
2814 Emacs will not crash with a segmentation fault just because of an
2815 error in a fully-optimized Lisp program.
2817 The `optimize' declaration is normally used in a top-level
2818 `proclaim' or `declaim' in a file; Common Lisp allows it to be
2819 used with `declare' to set the level of optimization locally for a
2820 given form, but this will not work correctly with the current
2821 version of the optimizing compiler. (The `declare' will set the
2822 new optimization level, but that level will not automatically be
2823 unset after the enclosing form is done.)
2826 This declaration controls what sorts of warnings are generated by
2827 the byte compiler. Again, only the optimizing compiler generates
2828 warnings. The word `warn' is followed by any number of "warning
2829 qualities," similar in form to optimization qualities. The
2830 currently supported warning types are `redefine', `callargs',
2831 `unresolved', and `free-vars'; in the current system, a value of 0
2832 will disable these warnings and any higher value will enable them.
2833 See the documentation for the optimizing byte compiler for details.
2836 File: cl.info, Node: Symbols, Next: Numbers, Prev: Declarations, Up: Top
2841 This package defines several symbol-related features that were missing
2846 * Property Lists:: `getf', `remf'
2847 * Creating Symbols:: `gensym', `gentemp'
2850 File: cl.info, Node: Property Lists, Next: Creating Symbols, Prev: Symbols, Up: Symbols
2855 These functions augment the standard Emacs Lisp functions `get' and
2856 `put' for operating on properties attached to objects. There are also
2857 functions for working with property lists as first-class data
2858 structures not attached to particular objects.
2860 - Function: getf place property &optional default
2861 This function scans the list PLACE as if it were a property list,
2862 i.e., a list of alternating property names and values. If an
2863 even-numbered element of PLACE is found which is `eq' to PROPERTY,
2864 the following odd-numbered element is returned. Otherwise,
2865 DEFAULT is returned (or `nil' if no default is given).
2869 (get sym prop) == (getf (symbol-plist sym) prop)
2871 It is legal to use `getf' as a `setf' place, in which case its
2872 PLACE argument must itself be a legal `setf' place. The DEFAULT
2873 argument, if any, is ignored in this context. The effect is to
2874 change (via `setcar') the value cell in the list that corresponds
2875 to PROPERTY, or to cons a new property-value pair onto the list if
2876 the property is not yet present.
2878 (put sym prop val) == (setf (getf (symbol-plist sym) prop) val)
2880 The `get' function is also `setf'-able. The fact that `default'
2881 is ignored can sometimes be useful:
2883 (incf (get 'foo 'usage-count 0))
2885 Here, symbol `foo''s `usage-count' property is incremented if it
2886 exists, or set to 1 (an incremented 0) otherwise.
2888 When not used as a `setf' form, `getf' is just a regular function
2889 and its PLACE argument can actually be any Lisp expression.
2891 - Special Form: remf place property
2892 This macro removes the property-value pair for PROPERTY from the
2893 property list stored at PLACE, which is any `setf'-able place
2894 expression. It returns true if the property was found. Note that
2895 if PROPERTY happens to be first on the list, this will effectively
2896 do a `(setf PLACE (cddr PLACE))', whereas if it occurs later, this
2897 simply uses `setcdr' to splice out the property and value cells.
2900 File: cl.info, Node: Creating Symbols, Prev: Property Lists, Up: Symbols
2905 These functions create unique symbols, typically for use as temporary
2908 - Function: gensym &optional x
2909 This function creates a new, uninterned symbol (using
2910 `make-symbol') with a unique name. (The name of an uninterned
2911 symbol is relevant only if the symbol is printed.) By default,
2912 the name is generated from an increasing sequence of numbers,
2913 `G1000', `G1001', `G1002', etc. If the optional argument X is a
2914 string, that string is used as a prefix instead of `G'.
2915 Uninterned symbols are used in macro expansions for temporary
2916 variables, to ensure that their names will not conflict with
2917 "real" variables in the user's code.
2919 - Variable: *gensym-counter*
2920 This variable holds the counter used to generate `gensym' names.
2921 It is incremented after each use by `gensym'. In Common Lisp this
2922 is initialized with 0, but this package initializes it with a
2923 random (time-dependent) value to avoid trouble when two files that
2924 each used `gensym' in their compilation are loaded together.
2926 *XEmacs note:* As of XEmacs 21.0, an uninterned symbol remains
2927 uninterned even after being dumped to bytecode. Older versions of
2928 Emacs didn't distinguish the printed representation of interned
2929 and uninterned symbols, so their names had to be treated more
2932 - Function: gentemp &optional x
2933 This function is like `gensym', except that it produces a new
2934 _interned_ symbol. If the symbol that is generated already
2935 exists, the function keeps incrementing the counter and trying
2936 again until a new symbol is generated.
2938 The Quiroz `cl.el' package also defined a `defkeyword' form for
2939 creating self-quoting keyword symbols. This package automatically
2940 creates all keywords that are called for by `&key' argument specifiers,
2941 and discourages the use of keywords as data unrelated to keyword
2942 arguments, so the `defkeyword' form has been discontinued.
2945 File: cl.info, Node: Numbers, Next: Sequences, Prev: Symbols, Up: Top
2950 This section defines a few simple Common Lisp operations on numbers
2951 which were left out of Emacs Lisp.
2955 * Predicates on Numbers:: `plusp', `oddp', `floatp-safe', etc.
2956 * Numerical Functions:: `abs', `expt', `floor*', etc.
2957 * Random Numbers:: `random*', `make-random-state'
2958 * Implementation Parameters:: `most-positive-fixnum', `most-positive-float'
2961 File: cl.info, Node: Predicates on Numbers, Next: Numerical Functions, Prev: Numbers, Up: Numbers
2963 Predicates on Numbers
2964 =====================
2966 These functions return `t' if the specified condition is true of the
2967 numerical argument, or `nil' otherwise.
2969 - Function: plusp number
2970 This predicate tests whether NUMBER is positive. It is an error
2971 if the argument is not a number.
2973 - Function: minusp number
2974 This predicate tests whether NUMBER is negative. It is an error
2975 if the argument is not a number.
2977 - Function: oddp integer
2978 This predicate tests whether INTEGER is odd. It is an error if
2979 the argument is not an integer.
2981 - Function: evenp integer
2982 This predicate tests whether INTEGER is even. It is an error if
2983 the argument is not an integer.
2985 - Function: floatp-safe object
2986 This predicate tests whether OBJECT is a floating-point number.
2987 On systems that support floating-point, this is equivalent to
2988 `floatp'. On other systems, this always returns `nil'.
2991 File: cl.info, Node: Numerical Functions, Next: Random Numbers, Prev: Predicates on Numbers, Up: Numbers
2996 These functions perform various arithmetic operations on numbers.
2998 - Function: abs number
2999 This function returns the absolute value of NUMBER. (Newer
3000 versions of Emacs provide this as a built-in function; this package
3001 defines `abs' only for Emacs 18 versions which don't provide it as
3004 - Function: expt base power
3005 This function returns BASE raised to the power of NUMBER. (Newer
3006 versions of Emacs provide this as a built-in function; this
3007 package defines `expt' only for Emacs 18 versions which don't
3008 provide it as a primitive.)
3010 - Function: gcd &rest integers
3011 This function returns the Greatest Common Divisor of the arguments.
3012 For one argument, it returns the absolute value of that argument.
3013 For zero arguments, it returns zero.
3015 - Function: lcm &rest integers
3016 This function returns the Least Common Multiple of the arguments.
3017 For one argument, it returns the absolute value of that argument.
3018 For zero arguments, it returns one.
3020 - Function: isqrt integer
3021 This function computes the "integer square root" of its integer
3022 argument, i.e., the greatest integer less than or equal to the true
3023 square root of the argument.
3025 - Function: floor* number &optional divisor
3026 This function implements the Common Lisp `floor' function. It is
3027 called `floor*' to avoid name conflicts with the simpler `floor'
3028 function built-in to Emacs 19.
3030 With one argument, `floor*' returns a list of two numbers: The
3031 argument rounded down (toward minus infinity) to an integer, and
3032 the "remainder" which would have to be added back to the first
3033 return value to yield the argument again. If the argument is an
3034 integer X, the result is always the list `(X 0)'. If the argument
3035 is an Emacs 19 floating-point number, the first result is a Lisp
3036 integer and the second is a Lisp float between 0 (inclusive) and 1
3039 With two arguments, `floor*' divides NUMBER by DIVISOR, and
3040 returns the floor of the quotient and the corresponding remainder
3041 as a list of two numbers. If `(floor* X Y)' returns `(Q R)', then
3042 `Q*Y + R = X', with R between 0 (inclusive) and R (exclusive).
3043 Also, note that `(floor* X)' is exactly equivalent to `(floor* X
3046 This function is entirely compatible with Common Lisp's `floor'
3047 function, except that it returns the two results in a list since
3048 Emacs Lisp does not support multiple-valued functions.
3050 - Function: ceiling* number &optional divisor
3051 This function implements the Common Lisp `ceiling' function, which
3052 is analogous to `floor' except that it rounds the argument or
3053 quotient of the arguments up toward plus infinity. The remainder
3054 will be between 0 and minus R.
3056 - Function: truncate* number &optional divisor
3057 This function implements the Common Lisp `truncate' function,
3058 which is analogous to `floor' except that it rounds the argument
3059 or quotient of the arguments toward zero. Thus it is equivalent
3060 to `floor*' if the argument or quotient is positive, or to
3061 `ceiling*' otherwise. The remainder has the same sign as NUMBER.
3063 - Function: round* number &optional divisor
3064 This function implements the Common Lisp `round' function, which
3065 is analogous to `floor' except that it rounds the argument or
3066 quotient of the arguments to the nearest integer. In the case of
3067 a tie (the argument or quotient is exactly halfway between two
3068 integers), it rounds to the even integer.
3070 - Function: mod* number divisor
3071 This function returns the same value as the second return value of
3074 - Function: rem* number divisor
3075 This function returns the same value as the second return value of
3078 These definitions are compatible with those in the Quiroz `cl.el'
3079 package, except that this package appends `*' to certain function names
3080 to avoid conflicts with existing Emacs 19 functions, and that the
3081 mechanism for returning multiple values is different.
3084 File: cl.info, Node: Random Numbers, Next: Implementation Parameters, Prev: Numerical Functions, Up: Numbers
3089 This package also provides an implementation of the Common Lisp random
3090 number generator. It uses its own additive-congruential algorithm,
3091 which is much more likely to give statistically clean random numbers
3092 than the simple generators supplied by many operating systems.
3094 - Function: random* number &optional state
3095 This function returns a random nonnegative number less than
3096 NUMBER, and of the same type (either integer or floating-point).
3097 The STATE argument should be a `random-state' object which holds
3098 the state of the random number generator. The function modifies
3099 this state object as a side effect. If STATE is omitted, it
3100 defaults to the variable `*random-state*', which contains a
3101 pre-initialized `random-state' object.
3103 - Variable: *random-state*
3104 This variable contains the system "default" `random-state' object,
3105 used for calls to `random*' that do not specify an alternative
3106 state object. Since any number of programs in the Emacs process
3107 may be accessing `*random-state*' in interleaved fashion, the
3108 sequence generated from this variable will be irreproducible for
3109 all intents and purposes.
3111 - Function: make-random-state &optional state
3112 This function creates or copies a `random-state' object. If STATE
3113 is omitted or `nil', it returns a new copy of `*random-state*'.
3114 This is a copy in the sense that future sequences of calls to
3115 `(random* N)' and `(random* N S)' (where S is the new random-state
3116 object) will return identical sequences of random numbers.
3118 If STATE is a `random-state' object, this function returns a copy
3119 of that object. If STATE is `t', this function returns a new
3120 `random-state' object seeded from the date and time. As an
3121 extension to Common Lisp, STATE may also be an integer in which
3122 case the new object is seeded from that integer; each different
3123 integer seed will result in a completely different sequence of
3126 It is legal to print a `random-state' object to a buffer or file
3127 and later read it back with `read'. If a program wishes to use a
3128 sequence of pseudo-random numbers which can be reproduced later
3129 for debugging, it can call `(make-random-state t)' to get a new
3130 sequence, then print this sequence to a file. When the program is
3131 later rerun, it can read the original run's random-state from the
3134 - Function: random-state-p object
3135 This predicate returns `t' if OBJECT is a `random-state' object,
3139 File: cl.info, Node: Implementation Parameters, Prev: Random Numbers, Up: Numbers
3141 Implementation Parameters
3142 =========================
3144 This package defines several useful constants having to with numbers.
3146 - Variable: most-positive-fixnum
3147 This constant equals the largest value a Lisp integer can hold.
3148 It is typically `2^23-1' or `2^25-1'.
3150 - Variable: most-negative-fixnum
3151 This constant equals the smallest (most negative) value a Lisp
3154 The following parameters have to do with floating-point numbers.
3155 This package determines their values by exercising the computer's
3156 floating-point arithmetic in various ways. Because this operation
3157 might be slow, the code for initializing them is kept in a separate
3158 function that must be called before the parameters can be used.
3160 - Function: cl-float-limits
3161 This function makes sure that the Common Lisp floating-point
3162 parameters like `most-positive-float' have been initialized.
3163 Until it is called, these parameters will be `nil'. If this
3164 version of Emacs does not support floats (e.g., most versions of
3165 Emacs 18), the parameters will remain `nil'. If the parameters
3166 have already been initialized, the function returns immediately.
3168 The algorithm makes assumptions that will be valid for most modern
3169 machines, but will fail if the machine's arithmetic is extremely
3170 unusual, e.g., decimal.
3172 Since true Common Lisp supports up to four different floating-point
3173 precisions, it has families of constants like
3174 `most-positive-single-float', `most-positive-double-float',
3175 `most-positive-long-float', and so on. Emacs has only one
3176 floating-point precision, so this package omits the precision word from
3177 the constants' names.
3179 - Variable: most-positive-float
3180 This constant equals the largest value a Lisp float can hold. For
3181 those systems whose arithmetic supports infinities, this is the
3182 largest _finite_ value. For IEEE machines, the value is
3183 approximately `1.79e+308'.
3185 - Variable: most-negative-float
3186 This constant equals the most-negative value a Lisp float can hold.
3187 (It is assumed to be equal to `(- most-positive-float)'.)
3189 - Variable: least-positive-float
3190 This constant equals the smallest Lisp float value greater than
3191 zero. For IEEE machines, it is about `4.94e-324' if denormals are
3192 supported or `2.22e-308' if not.
3194 - Variable: least-positive-normalized-float
3195 This constant equals the smallest _normalized_ Lisp float greater
3196 than zero, i.e., the smallest value for which IEEE denormalization
3197 will not result in a loss of precision. For IEEE machines, this
3198 value is about `2.22e-308'. For machines that do not support the
3199 concept of denormalization and gradual underflow, this constant
3200 will always equal `least-positive-float'.
3202 - Variable: least-negative-float
3203 This constant is the negative counterpart of
3204 `least-positive-float'.
3206 - Variable: least-negative-normalized-float
3207 This constant is the negative counterpart of
3208 `least-positive-normalized-float'.
3210 - Variable: float-epsilon
3211 This constant is the smallest positive Lisp float that can be added
3212 to 1.0 to produce a distinct value. Adding a smaller number to 1.0
3213 will yield 1.0 again due to roundoff. For IEEE machines, epsilon
3214 is about `2.22e-16'.
3216 - Variable: float-negative-epsilon
3217 This is the smallest positive value that can be subtracted from
3218 1.0 to produce a distinct value. For IEEE machines, it is about
3222 File: cl.info, Node: Sequences, Next: Lists, Prev: Numbers, Up: Top
3227 Common Lisp defines a number of functions that operate on "sequences",
3228 which are either lists, strings, or vectors. Emacs Lisp includes a few
3229 of these, notably `elt' and `length'; this package defines most of the
3234 * Sequence Basics:: Arguments shared by all sequence functions
3235 * Mapping over Sequences:: `mapcar*', `mapcan', `map', `every', etc.
3236 * Sequence Functions:: `subseq', `remove*', `substitute', etc.
3237 * Searching Sequences:: `find', `position', `count', `search', etc.
3238 * Sorting Sequences:: `sort*', `stable-sort', `merge'
3241 File: cl.info, Node: Sequence Basics, Next: Mapping over Sequences, Prev: Sequences, Up: Sequences
3246 Many of the sequence functions take keyword arguments; *note Argument
3247 Lists::. All keyword arguments are optional and, if specified, may
3248 appear in any order.
3250 The `:key' argument should be passed either `nil', or a function of
3251 one argument. This key function is used as a filter through which the
3252 elements of the sequence are seen; for example, `(find x y :key 'car)'
3253 is similar to `(assoc* x y)': It searches for an element of the list
3254 whose `car' equals `x', rather than for an element which equals `x'
3255 itself. If `:key' is omitted or `nil', the filter is effectively the
3258 The `:test' and `:test-not' arguments should be either `nil', or
3259 functions of two arguments. The test function is used to compare two
3260 sequence elements, or to compare a search value with sequence elements.
3261 (The two values are passed to the test function in the same order as
3262 the original sequence function arguments from which they are derived,
3263 or, if they both come from the same sequence, in the same order as they
3264 appear in that sequence.) The `:test' argument specifies a function
3265 which must return true (non-`nil') to indicate a match; instead, you
3266 may use `:test-not' to give a function which returns _false_ to
3267 indicate a match. The default test function is `:test 'eql'.
3269 Many functions which take ITEM and `:test' or `:test-not' arguments
3270 also come in `-if' and `-if-not' varieties, where a PREDICATE function
3271 is passed instead of ITEM, and sequence elements match if the predicate
3272 returns true on them (or false in the case of `-if-not'). For example:
3274 (remove* 0 seq :test '=) == (remove-if 'zerop seq)
3276 to remove all zeros from sequence `seq'.
3278 Some operations can work on a subsequence of the argument sequence;
3279 these function take `:start' and `:end' arguments which default to zero
3280 and the length of the sequence, respectively. Only elements between
3281 START (inclusive) and END (exclusive) are affected by the operation.
3282 The END argument may be passed `nil' to signify the length of the
3283 sequence; otherwise, both START and END must be integers, with `0 <=
3284 START <= END <= (length SEQ)'. If the function takes two sequence
3285 arguments, the limits are defined by keywords `:start1' and `:end1' for
3286 the first, and `:start2' and `:end2' for the second.
3288 A few functions accept a `:from-end' argument, which, if non-`nil',
3289 causes the operation to go from right-to-left through the sequence
3290 instead of left-to-right, and a `:count' argument, which specifies an
3291 integer maximum number of elements to be removed or otherwise processed.
3293 The sequence functions make no guarantees about the order in which
3294 the `:test', `:test-not', and `:key' functions are called on various
3295 elements. Therefore, it is a bad idea to depend on side effects of
3296 these functions. For example, `:from-end' may cause the sequence to be
3297 scanned actually in reverse, or it may be scanned forwards but
3298 computing a result "as if" it were scanned backwards. (Some functions,
3299 like `mapcar*' and `every', _do_ specify exactly the order in which the
3300 function is called so side effects are perfectly acceptable in those
3303 Strings in GNU Emacs 19 may contain "text properties" as well as
3304 character data. Except as noted, it is undefined whether or not text
3305 properties are preserved by sequence functions. For example, `(remove*
3306 ?A STR)' may or may not preserve the properties of the characters
3307 copied from STR into the result.
3310 File: cl.info, Node: Mapping over Sequences, Next: Sequence Functions, Prev: Sequence Basics, Up: Sequences
3312 Mapping over Sequences
3313 ======================
3315 These functions "map" the function you specify over the elements of
3316 lists or arrays. They are all variations on the theme of the built-in
3319 - Function: mapcar* function seq &rest more-seqs
3320 This function calls FUNCTION on successive parallel sets of
3321 elements from its argument sequences. Given a single SEQ argument
3322 it is equivalent to `mapcar'; given N sequences, it calls the
3323 function with the first elements of each of the sequences as the N
3324 arguments to yield the first element of the result list, then with
3325 the second elements, and so on. The mapping stops as soon as the
3326 shortest sequence runs out. The argument sequences may be any
3327 mixture of lists, strings, and vectors; the return sequence is
3330 Common Lisp's `mapcar' accepts multiple arguments but works only
3331 on lists; Emacs Lisp's `mapcar' accepts a single sequence
3332 argument. This package's `mapcar*' works as a compatible superset
3335 - Function: map result-type function seq &rest more-seqs
3336 This function maps FUNCTION over the argument sequences, just like
3337 `mapcar*', but it returns a sequence of type RESULT-TYPE rather
3338 than a list. RESULT-TYPE must be one of the following symbols:
3339 `vector', `string', `list' (in which case the effect is the same
3340 as for `mapcar*'), or `nil' (in which case the results are thrown
3341 away and `map' returns `nil').
3343 - Function: maplist function list &rest more-lists
3344 This function calls FUNCTION on each of its argument lists, then
3345 on the `cdr's of those lists, and so on, until the shortest list
3346 runs out. The results are returned in the form of a list. Thus,
3347 `maplist' is like `mapcar*' except that it passes in the list
3348 pointers themselves rather than the `car's of the advancing
3351 - Function: mapc function seq &rest more-seqs
3352 This function is like `mapcar*', except that the values returned
3353 by FUNCTION are ignored and thrown away rather than being
3354 collected into a list. The return value of `mapc' is SEQ, the
3357 - Function: mapl function list &rest more-lists
3358 This function is like `maplist', except that it throws away the
3359 values returned by FUNCTION.
3361 - Function: mapcan function seq &rest more-seqs
3362 This function is like `mapcar*', except that it concatenates the
3363 return values (which must be lists) using `nconc', rather than
3364 simply collecting them into a list.
3366 - Function: mapcon function list &rest more-lists
3367 This function is like `maplist', except that it concatenates the
3368 return values using `nconc'.
3370 - Function: some predicate seq &rest more-seqs
3371 This function calls PREDICATE on each element of SEQ in turn; if
3372 PREDICATE returns a non-`nil' value, `some' returns that value,
3373 otherwise it returns `nil'. Given several sequence arguments, it
3374 steps through the sequences in parallel until the shortest one
3375 runs out, just as in `mapcar*'. You can rely on the left-to-right
3376 order in which the elements are visited, and on the fact that
3377 mapping stops immediately as soon as PREDICATE returns non-`nil'.
3379 - Function: every predicate seq &rest more-seqs
3380 This function calls PREDICATE on each element of the sequence(s)
3381 in turn; it returns `nil' as soon as PREDICATE returns `nil' for
3382 any element, or `t' if the predicate was true for all elements.
3384 - Function: notany predicate seq &rest more-seqs
3385 This function calls PREDICATE on each element of the sequence(s)
3386 in turn; it returns `nil' as soon as PREDICATE returns a non-`nil'
3387 value for any element, or `t' if the predicate was `nil' for all
3390 - Function: notevery predicate seq &rest more-seqs
3391 This function calls PREDICATE on each element of the sequence(s)
3392 in turn; it returns a non-`nil' value as soon as PREDICATE returns
3393 `nil' for any element, or `t' if the predicate was true for all
3396 - Function: reduce function seq &key :from-end :start :end
3398 This function combines the elements of SEQ using an associative
3399 binary operation. Suppose FUNCTION is `*' and SEQ is the list `(2
3400 3 4 5)'. The first two elements of the list are combined with `(*
3401 2 3) = 6'; this is combined with the next element, `(* 6 4) = 24',
3402 and that is combined with the final element: `(* 24 5) = 120'.
3403 Note that the `*' function happens to be self-reducing, so that
3404 `(* 2 3 4 5)' has the same effect as an explicit call to `reduce'.
3406 If `:from-end' is true, the reduction is right-associative instead
3407 of left-associative:
3409 (reduce '- '(1 2 3 4))
3410 == (- (- (- 1 2) 3) 4) => -8
3411 (reduce '- '(1 2 3 4) :from-end t)
3412 == (- 1 (- 2 (- 3 4))) => -2
3414 If `:key' is specified, it is a function of one argument which is
3415 called on each of the sequence elements in turn.
3417 If `:initial-value' is specified, it is effectively added to the
3418 front (or rear in the case of `:from-end') of the sequence. The
3419 `:key' function is _not_ applied to the initial value.
3421 If the sequence, including the initial value, has exactly one
3422 element then that element is returned without ever calling
3423 FUNCTION. If the sequence is empty (and there is no initial
3424 value), then FUNCTION is called with no arguments to obtain the
3427 All of these mapping operations can be expressed conveniently in
3428 terms of the `loop' macro. In compiled code, `loop' will be faster
3429 since it generates the loop as in-line code with no function calls.
3432 File: cl.info, Node: Sequence Functions, Next: Searching Sequences, Prev: Mapping over Sequences, Up: Sequences
3437 This section describes a number of Common Lisp functions for operating
3440 - Function: subseq sequence start &optional end
3441 This function returns a given subsequence of the argument
3442 SEQUENCE, which may be a list, string, or vector. The indices
3443 START and END must be in range, and START must be no greater than
3444 END. If END is omitted, it defaults to the length of the
3445 sequence. The return value is always a copy; it does not share
3446 structure with SEQUENCE.
3448 As an extension to Common Lisp, START and/or END may be negative,
3449 in which case they represent a distance back from the end of the
3450 sequence. This is for compatibility with Emacs' `substring'
3451 function. Note that `subseq' is the _only_ sequence function that
3452 allows negative START and END.
3454 You can use `setf' on a `subseq' form to replace a specified range
3455 of elements with elements from another sequence. The replacement
3456 is done as if by `replace', described below.
3458 - Function: concatenate result-type &rest seqs
3459 This function concatenates the argument sequences together to form
3460 a result sequence of type RESULT-TYPE, one of the symbols
3461 `vector', `string', or `list'. The arguments are always copied,
3462 even in cases such as `(concatenate 'list '(1 2 3))' where the
3463 result is identical to an argument.
3465 - Function: fill seq item &key :start :end
3466 This function fills the elements of the sequence (or the specified
3467 part of the sequence) with the value ITEM.
3469 - Function: replace seq1 seq2 &key :start1 :end1 :start2 :end2
3470 This function copies part of SEQ2 into part of SEQ1. The sequence
3471 SEQ1 is not stretched or resized; the amount of data copied is
3472 simply the shorter of the source and destination (sub)sequences.
3473 The function returns SEQ1.
3475 If SEQ1 and SEQ2 are `eq', then the replacement will work
3476 correctly even if the regions indicated by the start and end
3477 arguments overlap. However, if SEQ1 and SEQ2 are lists which
3478 share storage but are not `eq', and the start and end arguments
3479 specify overlapping regions, the effect is undefined.
3481 - Function: remove* item seq &key :test :test-not :key :count :start
3483 This returns a copy of SEQ with all elements matching ITEM
3484 removed. The result may share storage with or be `eq' to SEQ in
3485 some circumstances, but the original SEQ will not be modified.
3486 The `:test', `:test-not', and `:key' arguments define the matching
3487 test that is used; by default, elements `eql' to ITEM are removed.
3488 The `:count' argument specifies the maximum number of matching
3489 elements that can be removed (only the leftmost COUNT matches are
3490 removed). The `:start' and `:end' arguments specify a region in
3491 SEQ in which elements will be removed; elements outside that
3492 region are not matched or removed. The `:from-end' argument, if
3493 true, says that elements should be deleted from the end of the
3494 sequence rather than the beginning (this matters only if COUNT was
3497 - Function: delete* item seq &key :test :test-not :key :count :start
3499 This deletes all elements of SEQ which match ITEM. It is a
3500 destructive operation. Since Emacs Lisp does not support
3501 stretchable strings or vectors, this is the same as `remove*' for
3502 those sequence types. On lists, `remove*' will copy the list if
3503 necessary to preserve the original list, whereas `delete*' will
3504 splice out parts of the argument list. Compare `append' and
3505 `nconc', which are analogous non-destructive and destructive list
3506 operations in Emacs Lisp.
3508 The predicate-oriented functions `remove-if', `remove-if-not',
3509 `delete-if', and `delete-if-not' are defined similarly.
3511 - Function: delete item list
3512 This MacLisp-compatible function deletes from LIST all elements
3513 which are `equal' to ITEM. The `delete' function is built-in to
3514 Emacs 19; this package defines it equivalently in Emacs 18.
3516 - Function: remove item list
3517 This function removes from LIST all elements which are `equal' to
3518 ITEM. This package defines it for symmetry with `delete', even
3519 though `remove' is not built-in to Emacs 19.
3521 - Function: remq item list
3522 This function removes from LIST all elements which are `eq' to
3523 ITEM. This package defines it for symmetry with `delq', even
3524 though `remq' is not built-in to Emacs 19.
3526 - Function: remove-duplicates seq &key :test :test-not :key :start
3528 This function returns a copy of SEQ with duplicate elements
3529 removed. Specifically, if two elements from the sequence match
3530 according to the `:test', `:test-not', and `:key' arguments, only
3531 the rightmost one is retained. If `:from-end' is true, the
3532 leftmost one is retained instead. If `:start' or `:end' is
3533 specified, only elements within that subsequence are examined or
3536 - Function: delete-duplicates seq &key :test :test-not :key :start
3538 This function deletes duplicate elements from SEQ. It is a
3539 destructive version of `remove-duplicates'.
3541 - Function: substitute new old seq &key :test :test-not :key :count
3542 :start :end :from-end
3543 This function returns a copy of SEQ, with all elements matching
3544 OLD replaced with NEW. The `:count', `:start', `:end', and
3545 `:from-end' arguments may be used to limit the number of
3548 - Function: nsubstitute new old seq &key :test :test-not :key :count
3549 :start :end :from-end
3550 This is a destructive version of `substitute'; it performs the
3551 substitution using `setcar' or `aset' rather than by returning a
3552 changed copy of the sequence.
3554 The `substitute-if', `substitute-if-not', `nsubstitute-if', and
3555 `nsubstitute-if-not' functions are defined similarly. For these, a
3556 PREDICATE is given in place of the OLD argument.
3559 File: cl.info, Node: Searching Sequences, Next: Sorting Sequences, Prev: Sequence Functions, Up: Sequences
3564 These functions search for elements or subsequences in a sequence.
3565 (See also `member*' and `assoc*'; *note Lists::.)
3567 - Function: find item seq &key :test :test-not :key :start :end
3569 This function searches SEQ for an element matching ITEM. If it
3570 finds a match, it returns the matching element. Otherwise, it
3571 returns `nil'. It returns the leftmost match, unless `:from-end'
3572 is true, in which case it returns the rightmost match. The
3573 `:start' and `:end' arguments may be used to limit the range of
3574 elements that are searched.
3576 - Function: position item seq &key :test :test-not :key :start :end
3578 This function is like `find', except that it returns the integer
3579 position in the sequence of the matching item rather than the item
3580 itself. The position is relative to the start of the sequence as
3581 a whole, even if `:start' is non-zero. The function returns `nil'
3582 if no matching element was found.
3584 - Function: count item seq &key :test :test-not :key :start :end
3585 This function returns the number of elements of SEQ which match
3586 ITEM. The result is always a nonnegative integer.
3588 The `find-if', `find-if-not', `position-if', `position-if-not',
3589 `count-if', and `count-if-not' functions are defined similarly.
3591 - Function: mismatch seq1 seq2 &key :test :test-not :key :start1 :end1
3592 :start2 :end2 :from-end
3593 This function compares the specified parts of SEQ1 and SEQ2. If
3594 they are the same length and the corresponding elements match
3595 (according to `:test', `:test-not', and `:key'), the function
3596 returns `nil'. If there is a mismatch, the function returns the
3597 index (relative to SEQ1) of the first mismatching element. This
3598 will be the leftmost pair of elements which do not match, or the
3599 position at which the shorter of the two otherwise-matching
3602 If `:from-end' is true, then the elements are compared from right
3603 to left starting at `(1- END1)' and `(1- END2)'. If the sequences
3604 differ, then one plus the index of the rightmost difference
3605 (relative to SEQ1) is returned.
3607 An interesting example is `(mismatch str1 str2 :key 'upcase)',
3608 which compares two strings case-insensitively.
3610 - Function: search seq1 seq2 &key :test :test-not :key :from-end
3611 :start1 :end1 :start2 :end2
3612 This function searches SEQ2 for a subsequence that matches SEQ1
3613 (or part of it specified by `:start1' and `:end1'.) Only matches
3614 which fall entirely within the region defined by `:start2' and
3615 `:end2' will be considered. The return value is the index of the
3616 leftmost element of the leftmost match, relative to the start of
3617 SEQ2, or `nil' if no matches were found. If `:from-end' is true,
3618 the function finds the _rightmost_ matching subsequence.
3621 File: cl.info, Node: Sorting Sequences, Prev: Searching Sequences, Up: Sequences
3626 - Function: sort* seq predicate &key :key
3627 This function sorts SEQ into increasing order as determined by
3628 using PREDICATE to compare pairs of elements. PREDICATE should
3629 return true (non-`nil') if and only if its first argument is less
3630 than (not equal to) its second argument. For example, `<' and
3631 `string-lessp' are suitable predicate functions for sorting
3632 numbers and strings, respectively; `>' would sort numbers into
3633 decreasing rather than increasing order.
3635 This function differs from Emacs' built-in `sort' in that it can
3636 operate on any type of sequence, not just lists. Also, it accepts
3637 a `:key' argument which is used to preprocess data fed to the
3638 PREDICATE function. For example,
3640 (setq data (sort data 'string-lessp :key 'downcase))
3642 sorts DATA, a sequence of strings, into increasing alphabetical
3643 order without regard to case. A `:key' function of `car' would be
3644 useful for sorting association lists.
3646 The `sort*' function is destructive; it sorts lists by actually
3647 rearranging the `cdr' pointers in suitable fashion.
3649 - Function: stable-sort seq predicate &key :key
3650 This function sorts SEQ "stably", meaning two elements which are
3651 equal in terms of PREDICATE are guaranteed not to be rearranged
3652 out of their original order by the sort.
3654 In practice, `sort*' and `stable-sort' are equivalent in Emacs
3655 Lisp because the underlying `sort' function is stable by default.
3656 However, this package reserves the right to use non-stable methods
3657 for `sort*' in the future.
3659 - Function: merge type seq1 seq2 predicate &key :key
3660 This function merges two sequences SEQ1 and SEQ2 by interleaving
3661 their elements. The result sequence, of type TYPE (in the sense
3662 of `concatenate'), has length equal to the sum of the lengths of
3663 the two input sequences. The sequences may be modified
3664 destructively. Order of elements within SEQ1 and SEQ2 is
3665 preserved in the interleaving; elements of the two sequences are
3666 compared by PREDICATE (in the sense of `sort') and the lesser
3667 element goes first in the result. When elements are equal, those
3668 from SEQ1 precede those from SEQ2 in the result. Thus, if SEQ1
3669 and SEQ2 are both sorted according to PREDICATE, then the result
3670 will be a merged sequence which is (stably) sorted according to
3674 File: cl.info, Node: Lists, Next: Hash Tables, Prev: Sequences, Up: Top
3679 The functions described here operate on lists.
3683 * List Functions:: `caddr', `first', `last', `list*', etc.
3684 * Substitution of Expressions:: `subst', `sublis', etc.
3685 * Lists as Sets:: `member*', `adjoin', `union', etc.
3686 * Association Lists:: `assoc*', `rassoc*', `acons', `pairlis'
3689 File: cl.info, Node: List Functions, Next: Substitution of Expressions, Prev: Lists, Up: Lists
3694 This section describes a number of simple operations on lists, i.e.,
3695 chains of cons cells.
3698 This function is equivalent to `(car (cdr (cdr X)))'. Likewise,
3699 this package defines all 28 `cXXXr' functions where XXX is up to
3700 four `a's and/or `d's. All of these functions are `setf'-able,
3701 and calls to them are expanded inline by the byte-compiler for
3705 This function is a synonym for `(car X)'. Likewise, the functions
3706 `second', `third', ..., through `tenth' return the given element
3710 This function is a synonym for `(cdr X)'.
3713 Common Lisp defines this function to act like `null', but
3714 signalling an error if `x' is neither a `nil' nor a cons cell.
3715 This package simply defines `endp' as a synonym for `null'.
3717 - Function: list-length x
3718 This function returns the length of list X, exactly like `(length
3719 X)', except that if X is a circular list (where the cdr-chain
3720 forms a loop rather than terminating with `nil'), this function
3721 returns `nil'. (The regular `length' function would get stuck if
3722 given a circular list.)
3724 - Function: last x &optional n
3725 This function returns the last cons, or the Nth-to-last cons, of
3726 the list X. If N is omitted it defaults to 1. The "last cons"
3727 means the first cons cell of the list whose `cdr' is not another
3728 cons cell. (For normal lists, the `cdr' of the last cons will be
3729 `nil'.) This function returns `nil' if X is `nil' or shorter than
3730 N. Note that the last _element_ of the list is `(car (last X))'.
3732 - Function: butlast x &optional n
3733 This function returns the list X with the last element, or the
3734 last N elements, removed. If N is greater than zero it makes a
3735 copy of the list so as not to damage the original list. In
3736 general, `(append (butlast X N) (last X N))' will return a list
3739 - Function: nbutlast x &optional n
3740 This is a version of `butlast' that works by destructively
3741 modifying the `cdr' of the appropriate element, rather than making
3744 - Function: list* arg &rest others
3745 This function constructs a list of its arguments. The final
3746 argument becomes the `cdr' of the last cell constructed. Thus,
3747 `(list* A B C)' is equivalent to `(cons A (cons B C))', and
3748 `(list* A B nil)' is equivalent to `(list A B)'.
3750 (Note that this function really is called `list*' in Common Lisp;
3751 it is not a name invented for this package like `member*' or
3754 - Function: ldiff list sublist
3755 If SUBLIST is a sublist of LIST, i.e., is `eq' to one of the cons
3756 cells of LIST, then this function returns a copy of the part of
3757 LIST up to but not including SUBLIST. For example, `(ldiff x
3758 (cddr x))' returns the first two elements of the list `x'. The
3759 result is a copy; the original LIST is not modified. If SUBLIST
3760 is not a sublist of LIST, a copy of the entire LIST is returned.
3762 - Function: copy-list list
3763 This function returns a copy of the list LIST. It copies dotted
3764 lists like `(1 2 . 3)' correctly.
3766 - Function: copy-tree x &optional vecp
3767 This function returns a copy of the tree of cons cells X. Unlike
3768 `copy-sequence' (and its alias `copy-list'), which copies only
3769 along the `cdr' direction, this function copies (recursively)
3770 along both the `car' and the `cdr' directions. If X is not a cons
3771 cell, the function simply returns X unchanged. If the optional
3772 VECP argument is true, this function copies vectors (recursively)
3773 as well as cons cells.
3775 - Function: tree-equal x y &key :test :test-not :key
3776 This function compares two trees of cons cells. If X and Y are
3777 both cons cells, their `car's and `cdr's are compared recursively.
3778 If neither X nor Y is a cons cell, they are compared by `eql', or
3779 according to the specified test. The `:key' function, if
3780 specified, is applied to the elements of both trees. *Note
3784 File: cl.info, Node: Substitution of Expressions, Next: Lists as Sets, Prev: List Functions, Up: Lists
3786 Substitution of Expressions
3787 ===========================
3789 These functions substitute elements throughout a tree of cons cells.
3790 (*Note Sequence Functions::, for the `substitute' function, which works
3791 on just the top-level elements of a list.)
3793 - Function: subst new old tree &key :test :test-not :key
3794 This function substitutes occurrences of OLD with NEW in TREE, a
3795 tree of cons cells. It returns a substituted tree, which will be
3796 a copy except that it may share storage with the argument TREE in
3797 parts where no substitutions occurred. The original TREE is not
3798 modified. This function recurses on, and compares against OLD,
3799 both `car's and `cdr's of the component cons cells. If OLD is
3800 itself a cons cell, then matching cells in the tree are
3801 substituted as usual without recursively substituting in that
3802 cell. Comparisons with OLD are done according to the specified
3803 test (`eql' by default). The `:key' function is applied to the
3804 elements of the tree but not to OLD.
3806 - Function: nsubst new old tree &key :test :test-not :key
3807 This function is like `subst', except that it works by destructive
3808 modification (by `setcar' or `setcdr') rather than copying.
3810 The `subst-if', `subst-if-not', `nsubst-if', and `nsubst-if-not'
3811 functions are defined similarly.
3813 - Function: sublis alist tree &key :test :test-not :key
3814 This function is like `subst', except that it takes an association
3815 list ALIST of OLD-NEW pairs. Each element of the tree (after
3816 applying the `:key' function, if any), is compared with the `car's
3817 of ALIST; if it matches, it is replaced by the corresponding `cdr'.
3819 - Function: nsublis alist tree &key :test :test-not :key
3820 This is a destructive version of `sublis'.
3823 File: cl.info, Node: Lists as Sets, Next: Association Lists, Prev: Substitution of Expressions, Up: Lists
3828 These functions perform operations on lists which represent sets of
3831 - Function: member item list
3832 This MacLisp-compatible function searches LIST for an element
3833 which is `equal' to ITEM. The `member' function is built-in to
3834 Emacs 19; this package defines it equivalently in Emacs 18. See
3835 the following function for a Common-Lisp compatible version.
3837 - Function: member* item list &key :test :test-not :key
3838 This function searches LIST for an element matching ITEM. If a
3839 match is found, it returns the cons cell whose `car' was the
3840 matching element. Otherwise, it returns `nil'. Elements are
3841 compared by `eql' by default; you can use the `:test',
3842 `:test-not', and `:key' arguments to modify this behavior. *Note
3845 Note that this function's name is suffixed by `*' to avoid the
3846 incompatible `member' function defined in Emacs 19. (That
3847 function uses `equal' for comparisons; it is equivalent to
3848 `(member* ITEM LIST :test 'equal)'.)
3850 The `member-if' and `member-if-not' functions analogously search for
3851 elements which satisfy a given predicate.
3853 - Function: tailp sublist list
3854 This function returns `t' if SUBLIST is a sublist of LIST, i.e.,
3855 if SUBLIST is `eql' to LIST or to any of its `cdr's.
3857 - Function: adjoin item list &key :test :test-not :key
3858 This function conses ITEM onto the front of LIST, like `(cons ITEM
3859 LIST)', but only if ITEM is not already present on the list (as
3860 determined by `member*'). If a `:key' argument is specified, it
3861 is applied to ITEM as well as to the elements of LIST during the
3862 search, on the reasoning that ITEM is "about" to become part of
3865 - Function: union list1 list2 &key :test :test-not :key
3866 This function combines two lists which represent sets of items,
3867 returning a list that represents the union of those two sets. The
3868 result list will contain all items which appear in LIST1 or LIST2,
3869 and no others. If an item appears in both LIST1 and LIST2 it will
3870 be copied only once. If an item is duplicated in LIST1 or LIST2,
3871 it is undefined whether or not that duplication will survive in the
3872 result list. The order of elements in the result list is also
3875 - Function: nunion list1 list2 &key :test :test-not :key
3876 This is a destructive version of `union'; rather than copying, it
3877 tries to reuse the storage of the argument lists if possible.
3879 - Function: intersection list1 list2 &key :test :test-not :key
3880 This function computes the intersection of the sets represented by
3881 LIST1 and LIST2. It returns the list of items which appear in
3882 both LIST1 and LIST2.
3884 - Function: nintersection list1 list2 &key :test :test-not :key
3885 This is a destructive version of `intersection'. It tries to
3886 reuse storage of LIST1 rather than copying. It does _not_ reuse
3887 the storage of LIST2.
3889 - Function: set-difference list1 list2 &key :test :test-not :key
3890 This function computes the "set difference" of LIST1 and LIST2,
3891 i.e., the set of elements that appear in LIST1 but _not_ in LIST2.
3893 - Function: nset-difference list1 list2 &key :test :test-not :key
3894 This is a destructive `set-difference', which will try to reuse
3897 - Function: set-exclusive-or list1 list2 &key :test :test-not :key
3898 This function computes the "set exclusive or" of LIST1 and LIST2,
3899 i.e., the set of elements that appear in exactly one of LIST1 and
3902 - Function: nset-exclusive-or list1 list2 &key :test :test-not :key
3903 This is a destructive `set-exclusive-or', which will try to reuse
3904 LIST1 and LIST2 if possible.
3906 - Function: subsetp list1 list2 &key :test :test-not :key
3907 This function checks whether LIST1 represents a subset of LIST2,
3908 i.e., whether every element of LIST1 also appears in LIST2.
3911 File: cl.info, Node: Association Lists, Prev: Lists as Sets, Up: Lists
3916 An "association list" is a list representing a mapping from one set of
3917 values to another; any list whose elements are cons cells is an
3920 - Function: assoc* item a-list &key :test :test-not :key
3921 This function searches the association list A-LIST for an element
3922 whose `car' matches (in the sense of `:test', `:test-not', and
3923 `:key', or by comparison with `eql') a given ITEM. It returns the
3924 matching element, if any, otherwise `nil'. It ignores elements of
3925 A-LIST which are not cons cells. (This corresponds to the
3926 behavior of `assq' and `assoc' in Emacs Lisp; Common Lisp's
3927 `assoc' ignores `nil's but considers any other non-cons elements
3928 of A-LIST to be an error.)
3930 - Function: rassoc* item a-list &key :test :test-not :key
3931 This function searches for an element whose `cdr' matches ITEM.
3932 If A-LIST represents a mapping, this applies the inverse of the
3935 - Function: rassoc item a-list
3936 This function searches like `rassoc*' with a `:test' argument of
3937 `equal'. It is analogous to Emacs Lisp's standard `assoc'
3938 function, which derives from the MacLisp rather than the Common
3941 The `assoc-if', `assoc-if-not', `rassoc-if', and `rassoc-if-not'
3942 functions are defined similarly.
3944 Two simple functions for constructing association lists are:
3946 - Function: acons key value alist
3947 This is equivalent to `(cons (cons KEY VALUE) ALIST)'.
3949 - Function: pairlis keys values &optional alist
3950 This is equivalent to `(nconc (mapcar* 'cons KEYS VALUES) ALIST)'.
3953 File: cl.info, Node: Hash Tables, Next: Structures, Prev: Lists, Up: Top
3958 Hash tables are now implemented directly in the C code and documented in
3959 *Note Hash Tables: (lispref)Hash Tables.
3962 File: cl.info, Node: Structures, Next: Assertions, Prev: Hash Tables, Up: Top
3967 The Common Lisp "structure" mechanism provides a general way to define
3968 data types similar to C's `struct' types. A structure is a Lisp object
3969 containing some number of "slots", each of which can hold any Lisp data
3970 object. Functions are provided for accessing and setting the slots,
3971 creating or copying structure objects, and recognizing objects of a
3972 particular structure type.
3974 In true Common Lisp, each structure type is a new type distinct from
3975 all existing Lisp types. Since the underlying Emacs Lisp system
3976 provides no way to create new distinct types, this package implements
3977 structures as vectors (or lists upon request) with a special "tag"
3978 symbol to identify them.
3980 - Special Form: defstruct name slots...
3981 The `defstruct' form defines a new structure type called NAME,
3982 with the specified SLOTS. (The SLOTS may begin with a string
3983 which documents the structure type.) In the simplest case, NAME
3984 and each of the SLOTS are symbols. For example,
3986 (defstruct person name age sex)
3988 defines a struct type called `person' which contains three slots.
3989 Given a `person' object P, you can access those slots by calling
3990 `(person-name P)', `(person-age P)', and `(person-sex P)'. You
3991 can also change these slots by using `setf' on any of these place
3994 (incf (person-age birthday-boy))
3996 You can create a new `person' by calling `make-person', which
3997 takes keyword arguments `:name', `:age', and `:sex' to specify the
3998 initial values of these slots in the new object. (Omitting any of
3999 these arguments leaves the corresponding slot "undefined,"
4000 according to the Common Lisp standard; in Emacs Lisp, such
4001 uninitialized slots are filled with `nil'.)
4003 Given a `person', `(copy-person P)' makes a new object of the same
4004 type whose slots are `eq' to those of P.
4006 Given any Lisp object X, `(person-p X)' returns true if X looks
4007 like a `person', false otherwise. (Again, in Common Lisp this
4008 predicate would be exact; in Emacs Lisp the best it can do is
4009 verify that X is a vector of the correct length which starts with
4010 the correct tag symbol.)
4012 Accessors like `person-name' normally check their arguments
4013 (effectively using `person-p') and signal an error if the argument
4014 is the wrong type. This check is affected by `(optimize (safety
4015 ...))' declarations. Safety level 1, the default, uses a somewhat
4016 optimized check that will detect all incorrect arguments, but may
4017 use an uninformative error message (e.g., "expected a vector"
4018 instead of "expected a `person'"). Safety level 0 omits all
4019 checks except as provided by the underlying `aref' call; safety
4020 levels 2 and 3 do rigorous checking that will always print a
4021 descriptive error message for incorrect inputs. *Note
4024 (setq dave (make-person :name "Dave" :sex 'male))
4025 => [cl-struct-person "Dave" nil male]
4026 (setq other (copy-person dave))
4027 => [cl-struct-person "Dave" nil male]
4030 (eq (person-name dave) (person-name other))
4034 (person-p [1 2 3 4])
4038 (person-p '[cl-struct-person counterfeit person object])
4041 In general, NAME is either a name symbol or a list of a name
4042 symbol followed by any number of "struct options"; each SLOT is
4043 either a slot symbol or a list of the form `(SLOT-NAME
4044 DEFAULT-VALUE SLOT-OPTIONS...)'. The DEFAULT-VALUE is a Lisp form
4045 which is evaluated any time an instance of the structure type is
4046 created without specifying that slot's value.
4048 Common Lisp defines several slot options, but the only one
4049 implemented in this package is `:read-only'. A non-`nil' value
4050 for this option means the slot should not be `setf'-able; the
4051 slot's value is determined when the object is created and does not
4055 (name nil :read-only t)
4059 Any slot options other than `:read-only' are ignored.
4061 For obscure historical reasons, structure options take a different
4062 form than slot options. A structure option is either a keyword
4063 symbol, or a list beginning with a keyword symbol possibly followed
4064 by arguments. (By contrast, slot options are key-value pairs not
4067 (defstruct (person (:constructor create-person)
4072 The following structure options are recognized.
4075 The argument is a symbol whose print name is used as the
4076 prefix for the names of slot accessor functions. The default
4077 is the name of the struct type followed by a hyphen. The
4078 option `(:conc-name p-)' would change this prefix to `p-'.
4079 Specifying `nil' as an argument means no prefix, so that the
4080 slot names themselves are used to name the accessor functions.
4083 In the simple case, this option takes one argument which is an
4084 alternate name to use for the constructor function. The
4085 default is `make-NAME', e.g., `make-person'. The above
4086 example changes this to `create-person'. Specifying `nil' as
4087 an argument means that no standard constructor should be
4090 In the full form of this option, the constructor name is
4091 followed by an arbitrary argument list. *Note Program
4092 Structure::, for a description of the format of Common Lisp
4093 argument lists. All options, such as `&rest' and `&key', are
4094 supported. The argument names should match the slot names;
4095 each slot is initialized from the corresponding argument.
4096 Slots whose names do not appear in the argument list are
4097 initialized based on the DEFAULT-VALUE in their slot
4098 descriptor. Also, `&optional' and `&key' arguments which
4099 don't specify defaults take their defaults from the slot
4100 descriptor. It is legal to include arguments which don't
4101 correspond to slot names; these are useful if they are
4102 referred to in the defaults for optional, keyword, or `&aux'
4103 arguments which _do_ correspond to slots.
4105 You can specify any number of full-format `:constructor'
4106 options on a structure. The default constructor is still
4107 generated as well unless you disable it with a simple-format
4108 `:constructor' option.
4112 (:constructor nil) ; no default constructor
4113 (:constructor new-person (name sex &optional (age 0)))
4114 (:constructor new-hound (&key (name "Rover")
4116 &aux (age (* 7 dog-years))
4120 The first constructor here takes its arguments positionally
4121 rather than by keyword. (In official Common Lisp
4122 terminology, constructors that work By Order of Arguments
4123 instead of by keyword are called "BOA constructors." No, I'm
4124 not making this up.) For example, `(new-person "Jane"
4125 'female)' generates a person whose slots are `"Jane"', 0, and
4126 `female', respectively.
4128 The second constructor takes two keyword arguments, `:name',
4129 which initializes the `name' slot and defaults to `"Rover"',
4130 and `:dog-years', which does not itself correspond to a slot
4131 but which is used to initialize the `age' slot. The `sex'
4132 slot is forced to the symbol `canine' with no syntax for
4136 The argument is an alternate name for the copier function for
4137 this type. The default is `copy-NAME'. `nil' means not to
4138 generate a copier function. (In this implementation, all
4139 copier functions are simply synonyms for `copy-sequence'.)
4142 The argument is an alternate name for the predicate which
4143 recognizes objects of this type. The default is `NAME-p'.
4144 `nil' means not to generate a predicate function. (If the
4145 `:type' option is used without the `:named' option, no
4146 predicate is ever generated.)
4148 In true Common Lisp, `typep' is always able to recognize a
4149 structure object even if `:predicate' was used. In this
4150 package, `typep' simply looks for a function called
4151 `TYPENAME-p', so it will work for structure types only if
4152 they used the default predicate name.
4155 This option implements a very limited form of C++-style
4156 inheritance. The argument is the name of another structure
4157 type previously created with `defstruct'. The effect is to
4158 cause the new structure type to inherit all of the included
4159 structure's slots (plus, of course, any new slots described
4160 by this struct's slot descriptors). The new structure is
4161 considered a "specialization" of the included one. In fact,
4162 the predicate and slot accessors for the included type will
4163 also accept objects of the new type.
4165 If there are extra arguments to the `:include' option after
4166 the included-structure name, these options are treated as
4167 replacement slot descriptors for slots in the included
4168 structure, possibly with modified default values. Borrowing
4169 an example from Steele:
4171 (defstruct person name (age 0) sex)
4173 (defstruct (astronaut (:include person (age 45)))
4175 (favorite-beverage 'tang))
4178 (setq joe (make-person :name "Joe"))
4179 => [cl-struct-person "Joe" 0 nil]
4180 (setq buzz (make-astronaut :name "Buzz"))
4181 => [cl-struct-astronaut "Buzz" 45 nil nil tang]
4183 (list (person-p joe) (person-p buzz))
4185 (list (astronaut-p joe) (astronaut-p buzz))
4190 (astronaut-name joe)
4191 => error: "astronaut-name accessing a non-astronaut"
4193 Thus, if `astronaut' is a specialization of `person', then
4194 every `astronaut' is also a `person' (but not the other way
4195 around). Every `astronaut' includes all the slots of a
4196 `person', plus extra slots that are specific to astronauts.
4197 Operations that work on people (like `person-name') work on
4198 astronauts just like other people.
4201 In full Common Lisp, this option allows you to specify a
4202 function which is called to print an instance of the
4203 structure type. The Emacs Lisp system offers no hooks into
4204 the Lisp printer which would allow for such a feature, so
4205 this package simply ignores `:print-function'.
4208 The argument should be one of the symbols `vector' or `list'.
4209 This tells which underlying Lisp data type should be used to
4210 implement the new structure type. Vectors are used by
4211 default, but `(:type list)' will cause structure objects to
4212 be stored as lists instead.
4214 The vector representation for structure objects has the
4215 advantage that all structure slots can be accessed quickly,
4216 although creating vectors is a bit slower in Emacs Lisp.
4217 Lists are easier to create, but take a relatively long time
4218 accessing the later slots.
4221 This option, which takes no arguments, causes a
4222 characteristic "tag" symbol to be stored at the front of the
4223 structure object. Using `:type' without also using `:named'
4224 will result in a structure type stored as plain vectors or
4225 lists with no identifying features.
4227 The default, if you don't specify `:type' explicitly, is to
4228 use named vectors. Therefore, `:named' is only useful in
4229 conjunction with `:type'.
4231 (defstruct (person1) name age sex)
4232 (defstruct (person2 (:type list) :named) name age sex)
4233 (defstruct (person3 (:type list)) name age sex)
4235 (setq p1 (make-person1))
4236 => [cl-struct-person1 nil nil nil]
4237 (setq p2 (make-person2))
4238 => (person2 nil nil nil)
4239 (setq p3 (make-person3))
4247 => error: function person3-p undefined
4249 Since unnamed structures don't have tags, `defstruct' is not
4250 able to make a useful predicate for recognizing them. Also,
4251 accessors like `person3-name' will be generated but they will
4252 not be able to do any type checking. The `person3-name'
4253 function, for example, will simply be a synonym for `car' in
4254 this case. By contrast, `person2-name' is able to verify
4255 that its argument is indeed a `person2' object before
4259 The argument must be a nonnegative integer. It specifies a
4260 number of slots to be left "empty" at the front of the
4261 structure. If the structure is named, the tag appears at the
4262 specified position in the list or vector; otherwise, the first
4263 slot appears at that position. Earlier positions are filled
4264 with `nil' by the constructors and ignored otherwise. If the
4265 type `:include's another type, then `:initial-offset'
4266 specifies a number of slots to be skipped between the last
4267 slot of the included type and the first new slot.
4269 Except as noted, the `defstruct' facility of this package is
4270 entirely compatible with that of Common Lisp.
4273 File: cl.info, Node: Assertions, Next: Efficiency Concerns, Prev: Structures, Up: Top
4275 Assertions and Errors
4276 *********************
4278 This section describes two macros that test "assertions", i.e.,
4279 conditions which must be true if the program is operating correctly.
4280 Assertions never add to the behavior of a Lisp program; they simply
4281 make "sanity checks" to make sure everything is as it should be.
4283 If the optimization property `speed' has been set to 3, and `safety'
4284 is less than 3, then the byte-compiler will optimize away the following
4285 assertions. Because assertions might be optimized away, it is a bad
4286 idea for them to include side-effects.
4288 - Special Form: assert test-form [show-args string args...]
4289 This form verifies that TEST-FORM is true (i.e., evaluates to a
4290 non-`nil' value). If so, it returns `nil'. If the test is not
4291 satisfied, `assert' signals an error.
4293 A default error message will be supplied which includes TEST-FORM.
4294 You can specify a different error message by including a STRING
4295 argument plus optional extra arguments. Those arguments are simply
4296 passed to `error' to signal the error.
4298 If the optional second argument SHOW-ARGS is `t' instead of `nil',
4299 then the error message (with or without STRING) will also include
4300 all non-constant arguments of the top-level FORM. For example:
4302 (assert (> x 10) t "x is too small: %d")
4304 This usage of SHOW-ARGS is a change to Common Lisp. In true
4305 Common Lisp, the second argument gives a list of PLACES which can
4306 be `setf''d by the user before continuing from the error.
4308 - Special Form: check-type place type &optional string
4309 This form verifies that PLACE evaluates to a value of type TYPE.
4310 If so, it returns `nil'. If not, `check-type' signals a
4311 continuable `wrong-type-argument' error. The default error
4312 message lists the erroneous value along with TYPE and PLACE
4313 themselves. If STRING is specified, it is included in the error
4314 message in place of TYPE. For example:
4316 (check-type x (integer 1 *) "a positive integer")
4318 *Note Type Predicates::, for a description of the type specifiers
4319 that may be used for TYPE.
4321 Note that as in Common Lisp, the first argument to `check-type'
4322 should be a PLACE suitable for use by `setf', because `check-type'
4323 signals a continuable error that allows the user to modify PLACE,
4324 most simply by returning a value from the debugger.
4326 The following error-related macro is also defined:
4328 - Special Form: ignore-errors forms...
4329 This executes FORMS exactly like a `progn', except that errors are
4330 ignored during the FORMS. More precisely, if an error is
4331 signalled then `ignore-errors' immediately aborts execution of the
4332 FORMS and returns `nil'. If the FORMS complete successfully,
4333 `ignore-errors' returns the result of the last FORM.
4336 File: cl.info, Node: Efficiency Concerns, Next: Common Lisp Compatibility, Prev: Assertions, Up: Top
4344 Many of the advanced features of this package, such as `defun*',
4345 `loop', and `setf', are implemented as Lisp macros. In byte-compiled
4346 code, these complex notations will be expanded into equivalent Lisp
4347 code which is simple and efficient. For example, the forms
4352 are expanded at compile-time to the Lisp forms
4355 (setcar p (cons x (car p)))
4357 which are the most efficient ways of doing these respective operations
4358 in Lisp. Thus, there is no performance penalty for using the more
4359 readable `incf' and `push' forms in your compiled code.
4361 _Interpreted_ code, on the other hand, must expand these macros
4362 every time they are executed. For this reason it is strongly
4363 recommended that code making heavy use of macros be compiled. (The
4364 features labelled "Special Form" instead of "Function" in this manual
4365 are macros.) A loop using `incf' a hundred times will execute
4366 considerably faster if compiled, and will also garbage-collect less
4367 because the macro expansion will not have to be generated, used, and
4368 thrown away a hundred times.
4370 You can find out how a macro expands by using the `cl-prettyexpand'
4373 - Function: cl-prettyexpand form &optional full
4374 This function takes a single Lisp form as an argument and inserts
4375 a nicely formatted copy of it in the current buffer (which must be
4376 in Lisp mode so that indentation works properly). It also expands
4377 all Lisp macros which appear in the form. The easiest way to use
4378 this function is to go to the `*scratch*' buffer and type, say,
4380 (cl-prettyexpand '(loop for x below 10 collect x))
4382 and type `C-x C-e' immediately after the closing parenthesis; the
4389 (setq G1004 (cons x G1004))
4393 will be inserted into the buffer. (The `block' macro is expanded
4394 differently in the interpreter and compiler, so `cl-prettyexpand'
4395 just leaves it alone. The temporary variable `G1004' was created
4398 If the optional argument FULL is true, then _all_ macros are
4399 expanded, including `block', `eval-when', and compiler macros.
4400 Expansion is done as if FORM were a top-level form in a file being
4401 compiled. For example,
4403 (cl-prettyexpand '(pushnew 'x list))
4404 -| (setq list (adjoin 'x list))
4405 (cl-prettyexpand '(pushnew 'x list) t)
4406 -| (setq list (if (memq 'x list) list (cons 'x list)))
4407 (cl-prettyexpand '(caddr (member* 'a list)) t)
4408 -| (car (cdr (cdr (memq 'a list))))
4410 Note that `adjoin', `caddr', and `member*' all have built-in
4411 compiler macros to optimize them in common cases.
4417 Common Lisp compliance has in general not been sacrificed for the sake
4418 of efficiency. A few exceptions have been made for cases where
4419 substantial gains were possible at the expense of marginal
4420 incompatibility. One example is the use of `memq' (which is treated
4421 very efficiently by the byte-compiler) to scan for keyword arguments;
4422 this can become confused in rare cases when keyword symbols are used as
4423 both keywords and data values at once. This is extremely unlikely to
4424 occur in practical code, and the use of `memq' allows functions with
4425 keyword arguments to be nearly as fast as functions that use
4426 `&optional' arguments.
4428 The Common Lisp standard (as embodied in Steele's book) uses the
4429 phrase "it is an error if" to indicate a situation which is not
4430 supposed to arise in complying programs; implementations are strongly
4431 encouraged but not required to signal an error in these situations.
4432 This package sometimes omits such error checking in the interest of
4433 compactness and efficiency. For example, `do' variable specifiers are
4434 supposed to be lists of one, two, or three forms; extra forms are
4435 ignored by this package rather than signalling a syntax error. The
4436 `endp' function is simply a synonym for `null' in this package.
4437 Functions taking keyword arguments will accept an odd number of
4438 arguments, treating the trailing keyword as if it were followed by the
4441 Argument lists (as processed by `defun*' and friends) _are_ checked
4442 rigorously except for the minor point just mentioned; in particular,
4443 keyword arguments are checked for validity, and `&allow-other-keys' and
4444 `:allow-other-keys' are fully implemented. Keyword validity checking
4445 is slightly time consuming (though not too bad in byte-compiled code);
4446 you can use `&allow-other-keys' to omit this check. Functions defined
4447 in this package such as `find' and `member*' do check their keyword
4448 arguments for validity.
4454 The byte-compiler that comes with Emacs 18 normally fails to expand
4455 macros that appear in top-level positions in the file (i.e., outside of
4456 `defun's or other enclosing forms). This would have disastrous
4457 consequences to programs that used such top-level macros as `defun*',
4458 `eval-when', and `defstruct'. To work around this problem, the "CL"
4459 package patches the Emacs 18 compiler to expand top-level macros. This
4460 patch will apply to your own macros, too, if they are used in a
4461 top-level context. The patch will not harm versions of the Emacs 18
4462 compiler which have already had a similar patch applied, nor will it
4463 affect the optimizing Emacs 19 byte-compiler written by Jamie Zawinski
4464 and Hallvard Furuseth. The patch is applied to the byte compiler's
4465 code in Emacs' memory, _not_ to the `bytecomp.elc' file stored on disk.
4467 The Emacs 19 compiler (for Emacs 18) is available from various Emacs
4468 Lisp archive sites such as `archive.cis.ohio-state.edu'. Its use is
4469 highly recommended; many of the Common Lisp macros emit code which can
4470 be improved by optimization. In particular, `block's (whether explicit
4471 or implicit in constructs like `defun*' and `loop') carry a fair
4472 run-time penalty; the optimizing compiler removes `block's which are
4473 not actually referenced by `return' or `return-from' inside the block.
4476 File: cl.info, Node: Common Lisp Compatibility, Next: Old CL Compatibility, Prev: Efficiency Concerns, Up: Top
4478 Common Lisp Compatibility
4479 *************************
4481 Following is a list of all known incompatibilities between this package
4482 and Common Lisp as documented in Steele (2nd edition).
4484 Certain function names, such as `member', `assoc', and `floor', were
4485 already taken by (incompatible) Emacs Lisp functions; this package
4486 appends `*' to the names of its Common Lisp versions of these functions.
4488 The word `defun*' is required instead of `defun' in order to use
4489 extended Common Lisp argument lists in a function. Likewise,
4490 `defmacro*' and `function*' are versions of those forms which
4491 understand full-featured argument lists. The `&whole' keyword does not
4492 work in `defmacro' argument lists (except inside recursive argument
4495 In order to allow an efficient implementation, keyword arguments use
4496 a slightly cheesy parser which may be confused if a keyword symbol is
4497 passed as the _value_ of another keyword argument. (Specifically,
4498 `(memq :KEYWORD REST-OF-ARGUMENTS)' is used to scan for `:KEYWORD'
4499 among the supplied keyword arguments.)
4501 The `eql' and `equal' predicates do not distinguish between IEEE
4502 floating-point plus and minus zero. The `equalp' predicate has several
4503 differences with Common Lisp; *note Predicates::.
4505 The `setf' mechanism is entirely compatible, except that
4506 setf-methods return a list of five values rather than five values
4507 directly. Also, the new "`setf' function" concept (typified by `(defun
4508 (setf foo) ...)') is not implemented.
4510 The `do-all-symbols' form is the same as `do-symbols' with no
4511 OBARRAY argument. In Common Lisp, this form would iterate over all
4512 symbols in all packages. Since Emacs obarrays are not a first-class
4513 package mechanism, there is no way for `do-all-symbols' to locate any
4514 but the default obarray.
4516 The `loop' macro is complete except that `loop-finish' and type
4517 specifiers are unimplemented.
4519 The multiple-value return facility treats lists as multiple values,
4520 since Emacs Lisp cannot support multiple return values directly. The
4521 macros will be compatible with Common Lisp if `values' or `values-list'
4522 is always used to return to a `multiple-value-bind' or other
4523 multiple-value receiver; if `values' is used without
4524 `multiple-value-...' or vice-versa the effect will be different from
4527 Many Common Lisp declarations are ignored, and others match the
4528 Common Lisp standard in concept but not in detail. For example, local
4529 `special' declarations, which are purely advisory in Emacs Lisp, do not
4530 rigorously obey the scoping rules set down in Steele's book.
4532 The variable `*gensym-counter*' starts out with a pseudo-random
4533 value rather than with zero. This is to cope with the fact that
4534 generated symbols become interned when they are written to and loaded
4537 The `defstruct' facility is compatible, except that structures are
4538 of type `:type vector :named' by default rather than some special,
4539 distinct type. Also, the `:type' slot option is ignored.
4541 The second argument of `check-type' is treated differently.
4544 File: cl.info, Node: Old CL Compatibility, Next: Porting Common Lisp, Prev: Common Lisp Compatibility, Up: Top
4546 Old CL Compatibility
4547 ********************
4549 Following is a list of all known incompatibilities between this package
4550 and the older Quiroz `cl.el' package.
4552 This package's emulation of multiple return values in functions is
4553 incompatible with that of the older package. That package attempted to
4554 come as close as possible to true Common Lisp multiple return values;
4555 unfortunately, it could not be 100% reliable and so was prone to
4556 occasional surprises if used freely. This package uses a simpler
4557 method, namely replacing multiple values with lists of values, which is
4558 more predictable though more noticeably different from Common Lisp.
4560 The `defkeyword' form and `keywordp' function are not implemented in
4563 The `member', `floor', `ceiling', `truncate', `round', `mod', and
4564 `rem' functions are suffixed by `*' in this package to avoid collision
4565 with existing functions in Emacs 18 or Emacs 19. The older package
4566 simply redefined these functions, overwriting the built-in meanings and
4567 causing serious portability problems with Emacs 19. (Some more recent
4568 versions of the Quiroz package changed the names to `cl-member', etc.;
4569 this package defines the latter names as aliases for `member*', etc.)
4571 Certain functions in the old package which were buggy or inconsistent
4572 with the Common Lisp standard are incompatible with the conforming
4573 versions in this package. For example, `eql' and `member' were
4574 synonyms for `eq' and `memq' in that package, `setf' failed to preserve
4575 correct order of evaluation of its arguments, etc.
4577 Finally, unlike the older package, this package is careful to prefix
4578 all of its internal names with `cl-'. Except for a few functions which
4579 are explicitly defined as additional features (such as `floatp-safe'
4580 and `letf'), this package does not export any non-`cl-' symbols which
4581 are not also part of Common Lisp.
4584 The `cl-compat' package
4585 =======================
4587 The "CL" package includes emulations of some features of the old
4588 `cl.el', in the form of a compatibility package `cl-compat'. To use
4589 it, put `(require 'cl-compat)' in your program.
4591 The old package defined a number of internal routines without `cl-'
4592 prefixes or other annotations. Call to these routines may have crept
4593 into existing Lisp code. `cl-compat' provides emulations of the
4594 following internal routines: `pair-with-newsyms', `zip-lists',
4595 `unzip-lists', `reassemble-arglists', `duplicate-symbols-p',
4598 Some `setf' forms translated into calls to internal functions that
4599 user code might call directly. The functions `setnth', `setnthcdr',
4600 and `setelt' fall in this category; they are defined by `cl-compat',
4601 but the best fix is to change to use `setf' properly.
4603 The `cl-compat' file defines the keyword functions `keywordp',
4604 `keyword-of', and `defkeyword', which are not defined by the new "CL"
4605 package because the use of keywords as data is discouraged.
4607 The `build-klist' mechanism for parsing keyword arguments is
4608 emulated by `cl-compat'; the `with-keyword-args' macro is not, however,
4609 and in any case it's best to change to use the more natural keyword
4610 argument processing offered by `defun*'.
4612 Multiple return values are treated differently by the two Common
4613 Lisp packages. The old package's method was more compatible with true
4614 Common Lisp, though it used heuristics that caused it to report
4615 spurious multiple return values in certain cases. The `cl-compat'
4616 package defines a set of multiple-value macros that are compatible with
4617 the old CL package; again, they are heuristic in nature, but they are
4618 guaranteed to work in any case where the old package's macros worked.
4619 To avoid name collision with the "official" multiple-value facilities,
4620 the ones in `cl-compat' have capitalized names: `Values',
4621 `Values-list', `Multiple-value-bind', etc.
4623 The functions `cl-floor', `cl-ceiling', `cl-truncate', and
4624 `cl-round' are defined by `cl-compat' to use the old-style
4625 multiple-value mechanism, just as they did in the old package. The
4626 newer `floor*' and friends return their two results in a list rather
4627 than as multiple values. Note that older versions of the old package
4628 used the unadorned names `floor', `ceiling', etc.; `cl-compat' cannot
4629 use these names because they conflict with Emacs 19 built-ins.
4632 File: cl.info, Node: Porting Common Lisp, Next: Function Index, Prev: Old CL Compatibility, Up: Top
4637 This package is meant to be used as an extension to Emacs Lisp, not as
4638 an Emacs implementation of true Common Lisp. Some of the remaining
4639 differences between Emacs Lisp and Common Lisp make it difficult to
4640 port large Common Lisp applications to Emacs. For one, some of the
4641 features in this package are not fully compliant with ANSI or Steele;
4642 *note Common Lisp Compatibility::. But there are also quite a few
4643 features that this package does not provide at all. Here are some
4644 major omissions that you will want watch out for when bringing Common
4645 Lisp code into Emacs.
4647 * Case-insensitivity. Symbols in Common Lisp are case-insensitive
4648 by default. Some programs refer to a function or variable as
4649 `foo' in one place and `Foo' or `FOO' in another. Emacs Lisp will
4650 treat these as three distinct symbols.
4652 Some Common Lisp code is written in all upper-case. While Emacs
4653 is happy to let the program's own functions and variables use this
4654 convention, calls to Lisp builtins like `if' and `defun' will have
4655 to be changed to lower-case.
4657 * Lexical scoping. In Common Lisp, function arguments and `let'
4658 bindings apply only to references physically within their bodies
4659 (or within macro expansions in their bodies). Emacs Lisp, by
4660 contrast, uses "dynamic scoping" wherein a binding to a variable
4661 is visible even inside functions called from the body.
4663 Variables in Common Lisp can be made dynamically scoped by
4664 declaring them `special' or using `defvar'. In Emacs Lisp it is
4665 as if all variables were declared `special'.
4667 Often you can use code that was written for lexical scoping even
4668 in a dynamically scoped Lisp, but not always. Here is an example
4669 of a Common Lisp code fragment that would fail in Emacs Lisp:
4671 (defun map-odd-elements (func list)
4673 for flag = t then (not flag)
4674 collect (if flag x (funcall func x))))
4676 (defun add-odd-elements (list x)
4677 (map-odd-elements (function (lambda (a) (+ a x))) list))
4679 In Common Lisp, the two functions' usages of `x' are completely
4680 independent. In Emacs Lisp, the binding to `x' made by
4681 `add-odd-elements' will have been hidden by the binding in
4682 `map-odd-elements' by the time the `(+ a x)' function is called.
4684 (This package avoids such problems in its own mapping functions by
4685 using names like `cl-x' instead of `x' internally; as long as you
4686 don't use the `cl-' prefix for your own variables no collision can
4689 *Note Lexical Bindings::, for a description of the `lexical-let'
4690 form which establishes a Common Lisp-style lexical binding, and
4691 some examples of how it differs from Emacs' regular `let'.
4693 * Common Lisp allows the shorthand `#'x' to stand for `(function
4694 x)', just as `'x' stands for `(quote x)'. In Common Lisp, one
4695 traditionally uses `#'' notation when referring to the name of a
4696 function. In Emacs Lisp, it works just as well to use a regular
4699 (loop for x in y by #'cddr collect (mapcar #'plusp x)) ; Common Lisp
4700 (loop for x in y by 'cddr collect (mapcar 'plusp x)) ; Emacs Lisp
4702 When `#'' introduces a `lambda' form, it is best to write out
4703 `(function ...)' longhand in Emacs Lisp. You can use a regular
4704 quote, but then the byte-compiler won't know that the `lambda'
4705 expression is code that can be compiled.
4707 (mapcar #'(lambda (x) (* x 2)) list) ; Common Lisp
4708 (mapcar (function (lambda (x) (* x 2))) list) ; Emacs Lisp
4710 XEmacs supports `#'' notation starting with version 19.8.
4712 * Reader macros. Common Lisp includes a second type of macro that
4713 works at the level of individual characters. For example, Common
4714 Lisp implements the quote notation by a reader macro called `'',
4715 whereas Emacs Lisp's parser just treats quote as a special case.
4716 Some Lisp packages use reader macros to create special syntaxes
4717 for themselves, which the Emacs parser is incapable of reading.
4719 * Other syntactic features. Common Lisp provides a number of
4720 notations beginning with `#' that the Emacs Lisp parser won't
4721 understand. For example, `#| ... |#' is an alternate comment
4722 notation, and `#+lucid (foo)' tells the parser to ignore the
4723 `(foo)' except in Lucid Common Lisp.
4725 The number prefixes `#b', `#o', and `#x', however, are supported
4726 by the Emacs Lisp parser to represent numbers in binary, octal,
4727 and hexadecimal notation (or radix), just like in Common Lisp.
4729 * Packages. In Common Lisp, symbols are divided into "packages".
4730 Symbols that are Lisp built-ins are typically stored in one
4731 package; symbols that are vendor extensions are put in another,
4732 and each application program would have a package for its own
4733 symbols. Certain symbols are "exported" by a package and others
4734 are internal; certain packages "use" or import the exported symbols
4735 of other packages. To access symbols that would not normally be
4736 visible due to this importing and exporting, Common Lisp provides
4737 a syntax like `package:symbol' or `package::symbol'.
4739 Emacs Lisp has a single namespace for all interned symbols, and
4740 then uses a naming convention of putting a prefix like `cl-' in
4741 front of the name. Some Emacs packages adopt the Common Lisp-like
4742 convention of using `cl:' or `cl::' as the prefix. However, the
4743 Emacs parser does not understand colons and just treats them as
4744 part of the symbol name. Thus, while `mapcar' and `lisp:mapcar'
4745 may refer to the same symbol in Common Lisp, they are totally
4746 distinct in Emacs Lisp. Common Lisp programs which refer to a
4747 symbol by the full name sometimes and the short name other times
4748 will not port cleanly to Emacs.
4750 Emacs Lisp does have a concept of "obarrays," which are
4751 package-like collections of symbols, but this feature is not
4752 strong enough to be used as a true package mechanism.
4754 * Keywords. The notation `:test-not' in Common Lisp really is a
4755 shorthand for `keyword:test-not'; keywords are just symbols in a
4756 built-in `keyword' package with the special property that all its
4757 symbols are automatically self-evaluating. Common Lisp programs
4758 often use keywords liberally to avoid having to use quotes.
4760 In Emacs Lisp a keyword is just a symbol whose name begins with a
4761 colon; since the Emacs parser does not treat them specially, they
4762 have to be explicitly made self-evaluating by a statement like
4763 `(setq :test-not ':test-not)'. This package arranges to execute
4764 such a statement whenever `defun*' or some other form sees a
4765 keyword being used as an argument. Common Lisp code that assumes
4766 that a symbol `:mumble' will be self-evaluating even though it was
4767 never introduced by a `defun*' will have to be fixed.
4769 * The `format' function is quite different between Common Lisp and
4770 Emacs Lisp. It takes an additional "destination" argument before
4771 the format string. A destination of `nil' means to format to a
4772 string as in Emacs Lisp; a destination of `t' means to write to
4773 the terminal (similar to `message' in Emacs). Also, format
4774 control strings are utterly different; `~' is used instead of `%'
4775 to introduce format codes, and the set of available codes is much
4776 richer. There are no notations like `\n' for string literals;
4777 instead, `format' is used with the "newline" format code, `~%'.
4778 More advanced formatting codes provide such features as paragraph
4779 filling, case conversion, and even loops and conditionals.
4781 While it would have been possible to implement most of Common Lisp
4782 `format' in this package (under the name `format*', of course), it
4783 was not deemed worthwhile. It would have required a huge amount
4784 of code to implement even a decent subset of `format*', yet the
4785 functionality it would provide over Emacs Lisp's `format' would
4788 * Vector constants use square brackets in Emacs Lisp, but `#(a b c)'
4789 notation in Common Lisp. To further complicate matters, Emacs 19
4790 introduces its own `#(' notation for something entirely
4791 different--strings with properties.
4793 * Characters are distinct from integers in Common Lisp. The
4794 notation for character constants is also different: `#\A' instead
4795 of `?A'. Also, `string=' and `string-equal' are synonyms in Emacs
4796 Lisp whereas the latter is case-insensitive in Common Lisp.
4798 * Data types. Some Common Lisp data types do not exist in Emacs
4799 Lisp. Rational numbers and complex numbers are not present, nor
4800 are large integers (all integers are "fixnums"). All arrays are
4801 one-dimensional. There are no readtables or pathnames; streams
4802 are a set of existing data types rather than a new data type of
4803 their own. Hash tables, random-states, structures, and packages
4804 (obarrays) are built from Lisp vectors or lists rather than being
4807 * The Common Lisp Object System (CLOS) is not implemented, nor is
4808 the Common Lisp Condition System.
4810 * Common Lisp features that are completely redundant with Emacs Lisp
4811 features of a different name generally have not been implemented.
4812 For example, Common Lisp writes `defconstant' where Emacs Lisp
4813 uses `defconst'. Similarly, `make-list' takes its arguments in
4814 different ways in the two Lisps but does exactly the same thing,
4815 so this package has not bothered to implement a Common Lisp-style
4818 * A few more notable Common Lisp features not included in this
4819 package: `compiler-let', `tagbody', `prog', `ldb/dpb',
4820 `parse-integer', `cerror'.
4822 * Recursion. While recursion works in Emacs Lisp just like it does
4823 in Common Lisp, various details of the Emacs Lisp system and
4824 compiler make recursion much less efficient than it is in most
4825 Lisps. Some schools of thought prefer to use recursion in Lisp
4826 over other techniques; they would sum a list of numbers using
4829 (defun sum-list (list)
4831 (+ (car list) (sum-list (cdr list)))
4834 where a more iteratively-minded programmer might write one of
4837 (let ((total 0)) (dolist (x my-list) (incf total x)) total)
4838 (loop for x in my-list sum x)
4840 While this would be mainly a stylistic choice in most Common Lisps,
4841 in Emacs Lisp you should be aware that the iterative forms are
4842 much faster than recursion. Also, Lisp programmers will want to
4843 note that the current Emacs Lisp compiler does not optimize tail
4847 File: cl.info, Node: Function Index, Next: Variable Index, Prev: Porting Common Lisp, Up: Top
4854 * abs: Numerical Functions.
4855 * acons: Association Lists.
4856 * adjoin: Lists as Sets.
4857 * assert: Assertions.
4858 * assoc*: Association Lists.
4859 * assoc-if: Association Lists.
4860 * assoc-if-not: Association Lists.
4861 * block: Blocks and Exits.
4862 * butlast: List Functions.
4863 * caddr: List Functions.
4864 * callf: Modify Macros.
4865 * callf2: Modify Macros.
4866 * case: Conditionals.
4867 * ceiling*: Numerical Functions.
4868 * check-type: Assertions.
4869 * cl-float-limits: Implementation Parameters.
4870 * cl-prettyexpand: Efficiency Concerns.
4871 * coerce: Type Predicates.
4872 * compiler-macroexpand: Macros.
4873 * concatenate: Sequence Functions.
4874 * copy-list: List Functions.
4875 * copy-tree: List Functions.
4876 * count: Searching Sequences.
4877 * count-if: Searching Sequences.
4878 * count-if-not: Searching Sequences.
4879 * decf: Modify Macros.
4880 * declaim: Declarations.
4881 * declare: Declarations.
4882 * defalias: Function Aliases.
4883 * define-compiler-macro: Macros.
4884 * define-modify-macro: Customizing Setf.
4885 * define-setf-method: Customizing Setf.
4886 * defmacro*: Argument Lists.
4887 * defsetf: Customizing Setf.
4888 * defstruct: Structures.
4889 * defsubst*: Argument Lists.
4890 * deftype: Type Predicates.
4891 * defun*: Argument Lists.
4892 * delete: Sequence Functions.
4893 * delete*: Sequence Functions.
4894 * delete-duplicates: Sequence Functions.
4895 * delete-if: Sequence Functions.
4896 * delete-if-not: Sequence Functions.
4897 * destructuring-bind: Macros.
4900 * do-all-symbols: Iteration.
4901 * do-symbols: Iteration.
4902 * dolist: Iteration.
4903 * dotimes: Iteration.
4904 * ecase: Conditionals.
4905 * endp: List Functions.
4906 * eql: Equality Predicates.
4907 * equalp: Equality Predicates.
4908 * etypecase: Conditionals.
4909 * eval-when: Time of Evaluation.
4910 * eval-when-compile: Time of Evaluation.
4911 * evenp: Predicates on Numbers.
4912 * every: Mapping over Sequences.
4913 * expt: Numerical Functions.
4914 * fill: Sequence Functions.
4915 * find: Searching Sequences.
4916 * find-if: Searching Sequences.
4917 * find-if-not: Searching Sequences.
4918 * first: List Functions.
4919 * flet: Function Bindings.
4920 * floatp-safe: Predicates on Numbers.
4921 * floor*: Numerical Functions.
4922 * function*: Argument Lists.
4923 * gcd: Numerical Functions.
4924 * gensym: Creating Symbols.
4925 * gentemp: Creating Symbols.
4926 * get-setf-method: Customizing Setf.
4927 * getf: Property Lists.
4928 * ignore-errors: Assertions.
4929 * incf: Modify Macros.
4930 * intersection: Lists as Sets.
4931 * isqrt: Numerical Functions.
4932 * labels: Function Bindings.
4933 * last: List Functions.
4934 * lcm: Numerical Functions.
4935 * ldiff: List Functions.
4936 * letf: Modify Macros.
4937 * letf*: Modify Macros.
4938 * lexical-let: Lexical Bindings.
4939 * lexical-let*: Lexical Bindings.
4940 * list*: List Functions.
4941 * list-length: List Functions.
4942 * load-time-value: Time of Evaluation.
4943 * locally: Declarations.
4944 * loop <1>: Loop Basics.
4946 * macrolet: Macro Bindings.
4947 * make-random-state: Random Numbers.
4948 * map: Mapping over Sequences.
4949 * mapc: Mapping over Sequences.
4950 * mapcan: Mapping over Sequences.
4951 * mapcar*: Mapping over Sequences.
4952 * mapcon: Mapping over Sequences.
4953 * mapl: Mapping over Sequences.
4954 * maplist: Mapping over Sequences.
4955 * member: Lists as Sets.
4956 * member*: Lists as Sets.
4957 * member-if: Lists as Sets.
4958 * member-if-not: Lists as Sets.
4959 * merge: Sorting Sequences.
4960 * minusp: Predicates on Numbers.
4961 * mismatch: Searching Sequences.
4962 * mod*: Numerical Functions.
4963 * multiple-value-bind: Multiple Values.
4964 * multiple-value-setq: Multiple Values.
4965 * nbutlast: List Functions.
4966 * nintersection: Lists as Sets.
4967 * notany: Mapping over Sequences.
4968 * notevery: Mapping over Sequences.
4969 * nset-difference: Lists as Sets.
4970 * nset-exclusive-or: Lists as Sets.
4971 * nsublis: Substitution of Expressions.
4972 * nsubst: Substitution of Expressions.
4973 * nsubst-if: Substitution of Expressions.
4974 * nsubst-if-not: Substitution of Expressions.
4975 * nsubstitute: Sequence Functions.
4976 * nsubstitute-if: Sequence Functions.
4977 * nsubstitute-if-not: Sequence Functions.
4978 * nunion: Lists as Sets.
4979 * oddp: Predicates on Numbers.
4980 * pairlis: Association Lists.
4981 * plusp: Predicates on Numbers.
4982 * pop: Modify Macros.
4983 * position: Searching Sequences.
4984 * position-if: Searching Sequences.
4985 * position-if-not: Searching Sequences.
4986 * proclaim: Declarations.
4987 * progv: Dynamic Bindings.
4988 * psetf: Modify Macros.
4989 * psetq: Assignment.
4990 * push: Modify Macros.
4991 * pushnew: Modify Macros.
4992 * random*: Random Numbers.
4993 * random-state-p: Random Numbers.
4994 * rassoc: Association Lists.
4995 * rassoc*: Association Lists.
4996 * rassoc-if: Association Lists.
4997 * rassoc-if-not: Association Lists.
4998 * reduce: Mapping over Sequences.
4999 * rem*: Numerical Functions.
5000 * remf: Property Lists.
5001 * remove: Sequence Functions.
5002 * remove*: Sequence Functions.
5003 * remove-duplicates: Sequence Functions.
5004 * remove-if: Sequence Functions.
5005 * remove-if-not: Sequence Functions.
5006 * remq: Sequence Functions.
5007 * replace: Sequence Functions.
5008 * rest: List Functions.
5009 * return: Blocks and Exits.
5010 * return-from: Blocks and Exits.
5011 * rotatef: Modify Macros.
5012 * round*: Numerical Functions.
5013 * search: Searching Sequences.
5014 * set-difference: Lists as Sets.
5015 * set-exclusive-or: Lists as Sets.
5017 * shiftf: Modify Macros.
5018 * some: Mapping over Sequences.
5019 * sort*: Sorting Sequences.
5020 * stable-sort: Sorting Sequences.
5021 * sublis: Substitution of Expressions.
5022 * subseq: Sequence Functions.
5023 * subsetp: Lists as Sets.
5024 * subst: Substitution of Expressions.
5025 * subst-if: Substitution of Expressions.
5026 * subst-if-not: Substitution of Expressions.
5027 * substitute: Sequence Functions.
5028 * substitute-if: Sequence Functions.
5029 * substitute-if-not: Sequence Functions.
5030 * symbol-macrolet: Macro Bindings.
5031 * tailp: Lists as Sets.
5032 * the: Declarations.
5033 * tree-equal: List Functions.
5034 * truncate*: Numerical Functions.
5035 * typecase: Conditionals.
5036 * typep: Type Predicates.
5037 * union: Lists as Sets.
5038 * unless: Conditionals.
5039 * when: Conditionals.
5042 File: cl.info, Node: Variable Index, Prev: Function Index, Up: Top
5049 * *gensym-counter*: Creating Symbols.
5050 * *random-state*: Random Numbers.
5051 * float-epsilon: Implementation Parameters.
5052 * float-negative-epsilon: Implementation Parameters.
5053 * least-negative-float: Implementation Parameters.
5054 * least-negative-normalized-float: Implementation Parameters.
5055 * least-positive-float: Implementation Parameters.
5056 * least-positive-normalized-float: Implementation Parameters.
5057 * most-negative-fixnum: Implementation Parameters.
5058 * most-negative-float: Implementation Parameters.
5059 * most-positive-fixnum: Implementation Parameters.
5060 * most-positive-float: Implementation Parameters.
5066 Node: Overview
\7f2716
5068 Node: Organization
\7f5645
5069 Node: Installation
\7f7468
5070 Node: Naming Conventions
\7f8621
5071 Node: Program Structure
\7f10748
5072 Node: Argument Lists
\7f11216
5073 Node: Time of Evaluation
\7f20999
5074 Node: Function Aliases
\7f26979
5075 Node: Predicates
\7f27563
5076 Node: Type Predicates
\7f27883
5077 Node: Equality Predicates
\7f32925
5078 Node: Control Structure
\7f35701
5079 Node: Assignment
\7f36505
5080 Node: Generalized Variables
\7f37746
5081 Node: Basic Setf
\7f39053
5082 Node: Modify Macros
\7f46305
5083 Node: Customizing Setf
\7f53514
5084 Node: Variable Bindings
\7f60803
5085 Node: Dynamic Bindings
\7f61384
5086 Node: Lexical Bindings
\7f62274
5087 Node: Function Bindings
\7f66378
5088 Node: Macro Bindings
\7f68765
5089 Node: Conditionals
\7f71688
5090 Node: Blocks and Exits
\7f74771
5091 Node: Iteration
\7f77827
5092 Node: Loop Facility
\7f83300
5093 Node: Loop Basics
\7f84227
5094 Node: Loop Examples
\7f86827
5095 Node: For Clauses
\7f89086
5096 Node: Iteration Clauses
\7f100963
5097 Node: Accumulation Clauses
\7f102804
5098 Node: Other Clauses
\7f105148
5099 Node: Multiple Values
\7f111217
5100 Node: Macros
\7f113110
5101 Node: Declarations
\7f116328
5102 Node: Symbols
\7f124814
5103 Node: Property Lists
\7f125095
5104 Node: Creating Symbols
\7f127286
5105 Node: Numbers
\7f129364
5106 Node: Predicates on Numbers
\7f129844
5107 Node: Numerical Functions
\7f130873
5108 Node: Random Numbers
\7f135100
5109 Node: Implementation Parameters
\7f137809
5110 Node: Sequences
\7f141381
5111 Node: Sequence Basics
\7f142054
5112 Node: Mapping over Sequences
\7f145632
5113 Node: Sequence Functions
\7f151486
5114 Node: Searching Sequences
\7f157661
5115 Node: Sorting Sequences
\7f160698
5116 Node: Lists
\7f163246
5117 Node: List Functions
\7f163671
5118 Node: Substitution of Expressions
\7f167934
5119 Node: Lists as Sets
\7f169820
5120 Node: Association Lists
\7f173882
5121 Node: Hash Tables
\7f175585
5122 Node: Structures
\7f175805
5123 Node: Assertions
\7f190588
5124 Node: Efficiency Concerns
\7f193511
5125 Node: Common Lisp Compatibility
\7f199838
5126 Node: Old CL Compatibility
\7f202994
5127 Node: Porting Common Lisp
\7f207377
5128 Node: Function Index
\7f218388
5129 Node: Variable Index
\7f229537
projects / chise / xemacs-chise.git.1 / blob