1 \input texinfo @c -*-texinfo-*-
2 @setfilename ../../info/cl
3 @settitle Common Lisp Extensions
6 This file documents the GNU Emacs Common Lisp emulation package.
8 Copyright @copyright{} 1993, 2001-2011 Free Software Foundation, Inc.
11 Permission is granted to copy, distribute and/or modify this document
12 under the terms of the GNU Free Documentation License, Version 1.3 or
13 any later version published by the Free Software Foundation; with no
14 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
15 and with the Back-Cover Texts as in (a) below. A copy of the license
16 is included in the section entitled ``GNU Free Documentation License''.
18 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
19 modify this GNU manual. Buying copies from the FSF supports it in
20 developing GNU and promoting software freedom.''
24 @dircategory Emacs lisp libraries
26 * CL: (cl). Partial Common Lisp support for Emacs Lisp.
33 @center @titlefont{Common Lisp Extensions}
35 @center For GNU Emacs Lisp
39 @center Dave Gillespie
40 @center daveg@@synaptics.com
42 @vskip 0pt plus 1filll
48 @node Top, Overview, (dir), (dir)
52 This document describes a set of Emacs Lisp facilities borrowed from
53 Common Lisp. All the facilities are described here in detail. While
54 this document does not assume any prior knowledge of Common Lisp, it
55 does assume a basic familiarity with Emacs Lisp.
62 * Overview:: Installation, usage, etc.
63 * Program Structure:: Arglists, `eval-when', `defalias'
64 * Predicates:: `typep' and `equalp'
65 * Control Structure:: `setf', `do', `loop', etc.
66 * Macros:: Destructuring, `define-compiler-macro'
67 * Declarations:: `proclaim', `declare', etc.
68 * Symbols:: Property lists, `gensym'
69 * Numbers:: Predicates, functions, random numbers
70 * Sequences:: Mapping, functions, searching, sorting
71 * Lists:: `caddr', `sublis', `member*', `assoc*', etc.
72 * Structures:: `defstruct'
73 * Assertions:: `check-type', `assert', `ignore-errors'.
75 * Efficiency Concerns:: Hints and techniques
76 * Common Lisp Compatibility:: All known differences with Steele
77 * Old CL Compatibility:: All known differences with old cl.el
78 * Porting Common Lisp:: Hints for porting Common Lisp code
80 * GNU Free Documentation License:: The license for this documentation.
85 @node Overview, Program Structure, Top, Top
91 Common Lisp is a huge language, and Common Lisp systems tend to be
92 massive and extremely complex. Emacs Lisp, by contrast, is rather
93 minimalist in the choice of Lisp features it offers the programmer.
94 As Emacs Lisp programmers have grown in number, and the applications
95 they write have grown more ambitious, it has become clear that Emacs
96 Lisp could benefit from many of the conveniences of Common Lisp.
98 The @dfn{CL} package adds a number of Common Lisp functions and
99 control structures to Emacs Lisp. While not a 100% complete
100 implementation of Common Lisp, @dfn{CL} adds enough functionality
101 to make Emacs Lisp programming significantly more convenient.
103 @strong{Please note:} the @dfn{CL} functions are not standard parts of
104 the Emacs Lisp name space, so it is legitimate for users to define
105 them with other, conflicting meanings. To avoid conflicting with
106 those user activities, we have a policy that packages installed in
107 Emacs must not load @dfn{CL} at run time. (It is ok for them to load
108 @dfn{CL} at compile time only, with @code{eval-when-compile}, and use
109 the macros it provides.) If you are writing packages that you plan to
110 distribute and invite widespread use for, you might want to observe
113 Some Common Lisp features have been omitted from this package
118 Some features are too complex or bulky relative to their benefit
119 to Emacs Lisp programmers. CLOS and Common Lisp streams are fine
120 examples of this group.
123 Other features cannot be implemented without modification to the
124 Emacs Lisp interpreter itself, such as multiple return values,
125 lexical scoping, case-insensitive symbols, and complex numbers.
126 The @dfn{CL} package generally makes no attempt to emulate these
130 Some features conflict with existing things in Emacs Lisp. For
131 example, Emacs' @code{assoc} function is incompatible with the
132 Common Lisp @code{assoc}. In such cases, this package usually
133 adds the suffix @samp{*} to the function name of the Common
134 Lisp version of the function (e.g., @code{assoc*}).
137 The package described here was written by Dave Gillespie,
138 @file{daveg@@synaptics.com}. It is a total rewrite of the original
139 1986 @file{cl.el} package by Cesar Quiroz. Most features of the
140 Quiroz package have been retained; any incompatibilities are
141 noted in the descriptions below. Care has been taken in this
142 version to ensure that each function is defined efficiently,
143 concisely, and with minimal impact on the rest of the Emacs
147 * Usage:: How to use the CL package
148 * Organization:: The package's five component files
149 * Installation:: Compiling and installing CL
150 * Naming Conventions:: Notes on CL function names
153 @node Usage, Organization, Overview, Overview
157 Lisp code that uses features from the @dfn{CL} package should
158 include at the beginning:
165 It is safe to arrange to load @dfn{CL} at all times, e.g.,
166 in your @file{.emacs} file. But it's a good idea, for portability,
167 to @code{(require 'cl)} in your code even if you do this.
169 @node Organization, Installation, Usage, Overview
170 @section Organization
173 The Common Lisp package is organized into four files:
177 This is the ``main'' file, which contains basic functions
178 and information about the package. This file is relatively
179 compact---about 700 lines.
182 This file contains the larger, more complex or unusual functions.
183 It is kept separate so that packages which only want to use Common
184 Lisp fundamentals like the @code{cadr} function won't need to pay
185 the overhead of loading the more advanced functions.
188 This file contains most of the advanced functions for operating
189 on sequences or lists, such as @code{delete-if} and @code{assoc*}.
192 This file contains the features of the packages which are macros
193 instead of functions. Macros expand when the caller is compiled,
194 not when it is run, so the macros generally only need to be
195 present when the byte-compiler is running (or when the macros are
196 used in uncompiled code such as a @file{.emacs} file). Most of
197 the macros of this package are isolated in @file{cl-macs.el} so
198 that they won't take up memory unless you are compiling.
201 The file @file{cl.el} includes all necessary @code{autoload}
202 commands for the functions and macros in the other three files.
203 All you have to do is @code{(require 'cl)}, and @file{cl.el}
204 will take care of pulling in the other files when they are
207 There is another file, @file{cl-compat.el}, which defines some
208 routines from the older @file{cl.el} package that are not otherwise
209 present in the new package. This includes internal routines
210 like @code{setelt} and @code{zip-lists}, deprecated features
211 like @code{defkeyword}, and an emulation of the old-style
212 multiple-values feature. This file is obsolete and should not be used
213 in new code. @xref{Old CL Compatibility}.
215 @node Installation, Naming Conventions, Organization, Overview
216 @section Installation
219 The @dfn{CL} package is distributed with Emacs, so there is no need
222 If you do need to install it, just put the byte-compiled files
223 @file{cl.elc}, @file{cl-extra.elc}, @file{cl-seq.elc},
224 @file{cl-macs.elc}, and (if necessary) @file{cl-compat.elc} into a
225 directory on your @code{load-path}. Also, format the @file{cl.texi}
226 file and put the resulting Info files into a directory in your
227 @code{Info-directory-list}.
229 @node Naming Conventions, , Installation, Overview
230 @section Naming Conventions
233 Except where noted, all functions defined by this package have the
234 same names and calling conventions as their Common Lisp counterparts.
236 Following is a complete list of functions whose names were changed
237 from Common Lisp, usually to avoid conflicts with Emacs. In each
238 case, a @samp{*} has been appended to the Common Lisp name to obtain
242 defun* defsubst* defmacro* function*
243 member* assoc* rassoc* get*
244 remove* delete* mapcar* sort*
245 floor* ceiling* truncate* round*
249 Internal function and variable names in the package are prefixed
250 by @code{cl-}. Here is a complete list of functions @emph{not}
251 prefixed by @code{cl-} which were not taken from Common Lisp:
254 floatp-safe lexical-let lexical-let*
255 callf callf2 letf letf*
259 The following simple functions and macros are defined in @file{cl.el};
260 they do not cause other components like @file{cl-extra} to be loaded.
264 evenp oddp plusp minusp
266 list* ldiff rest first .. tenth
267 copy-list subst mapcar* [2]
268 adjoin [3] acons pairlis pop [4]
269 push [4] pushnew [3,4] incf [4] decf [4]
274 [2] Only for one sequence argument or two list arguments.
277 [3] Only if @code{:test} is @code{eq}, @code{equal}, or unspecified,
278 and @code{:key} is not used.
281 [4] Only when @var{place} is a plain variable name.
287 @node Program Structure, Predicates, Overview, Top
288 @chapter Program Structure
291 This section describes features of the @dfn{CL} package which have to
292 do with programs as a whole: advanced argument lists for functions,
293 and the @code{eval-when} construct.
296 * Argument Lists:: `&key', `&aux', `defun*', `defmacro*'.
297 * Time of Evaluation:: The `eval-when' construct.
304 @node Argument Lists, Time of Evaluation, Program Structure, Program Structure
305 @section Argument Lists
308 Emacs Lisp's notation for argument lists of functions is a subset of
309 the Common Lisp notation. As well as the familiar @code{&optional}
310 and @code{&rest} markers, Common Lisp allows you to specify default
311 values for optional arguments, and it provides the additional markers
312 @code{&key} and @code{&aux}.
314 Since argument parsing is built-in to Emacs, there is no way for
315 this package to implement Common Lisp argument lists seamlessly.
316 Instead, this package defines alternates for several Lisp forms
317 which you must use if you need Common Lisp argument lists.
319 @defspec defun* name arglist body...
320 This form is identical to the regular @code{defun} form, except
321 that @var{arglist} is allowed to be a full Common Lisp argument
322 list. Also, the function body is enclosed in an implicit block
323 called @var{name}; @pxref{Blocks and Exits}.
326 @defspec defsubst* name arglist body...
327 This is just like @code{defun*}, except that the function that
328 is defined is automatically proclaimed @code{inline}, i.e.,
329 calls to it may be expanded into in-line code by the byte compiler.
330 This is analogous to the @code{defsubst} form;
331 @code{defsubst*} uses a different method (compiler macros) which
332 works in all versions of Emacs, and also generates somewhat more
333 efficient inline expansions. In particular, @code{defsubst*}
334 arranges for the processing of keyword arguments, default values,
335 etc., to be done at compile-time whenever possible.
338 @defspec defmacro* name arglist body...
339 This is identical to the regular @code{defmacro} form,
340 except that @var{arglist} is allowed to be a full Common Lisp
341 argument list. The @code{&environment} keyword is supported as
342 described in Steele. The @code{&whole} keyword is supported only
343 within destructured lists (see below); top-level @code{&whole}
344 cannot be implemented with the current Emacs Lisp interpreter.
345 The macro expander body is enclosed in an implicit block called
349 @defspec function* symbol-or-lambda
350 This is identical to the regular @code{function} form,
351 except that if the argument is a @code{lambda} form then that
352 form may use a full Common Lisp argument list.
355 Also, all forms (such as @code{defsetf} and @code{flet}) defined
356 in this package that include @var{arglist}s in their syntax allow
357 full Common Lisp argument lists.
359 Note that it is @emph{not} necessary to use @code{defun*} in
360 order to have access to most @dfn{CL} features in your function.
361 These features are always present; @code{defun*}'s only
362 difference from @code{defun} is its more flexible argument
363 lists and its implicit block.
365 The full form of a Common Lisp argument list is
369 &optional (@var{var} @var{initform} @var{svar})...
371 &key ((@var{keyword} @var{var}) @var{initform} @var{svar})...
372 &aux (@var{var} @var{initform})...)
375 Each of the five argument list sections is optional. The @var{svar},
376 @var{initform}, and @var{keyword} parts are optional; if they are
377 omitted, then @samp{(@var{var})} may be written simply @samp{@var{var}}.
379 The first section consists of zero or more @dfn{required} arguments.
380 These arguments must always be specified in a call to the function;
381 there is no difference between Emacs Lisp and Common Lisp as far as
382 required arguments are concerned.
384 The second section consists of @dfn{optional} arguments. These
385 arguments may be specified in the function call; if they are not,
386 @var{initform} specifies the default value used for the argument.
387 (No @var{initform} means to use @code{nil} as the default.) The
388 @var{initform} is evaluated with the bindings for the preceding
389 arguments already established; @code{(a &optional (b (1+ a)))}
390 matches one or two arguments, with the second argument defaulting
391 to one plus the first argument. If the @var{svar} is specified,
392 it is an auxiliary variable which is bound to @code{t} if the optional
393 argument was specified, or to @code{nil} if the argument was omitted.
394 If you don't use an @var{svar}, then there will be no way for your
395 function to tell whether it was called with no argument, or with
396 the default value passed explicitly as an argument.
398 The third section consists of a single @dfn{rest} argument. If
399 more arguments were passed to the function than are accounted for
400 by the required and optional arguments, those extra arguments are
401 collected into a list and bound to the ``rest'' argument variable.
402 Common Lisp's @code{&rest} is equivalent to that of Emacs Lisp.
403 Common Lisp accepts @code{&body} as a synonym for @code{&rest} in
404 macro contexts; this package accepts it all the time.
406 The fourth section consists of @dfn{keyword} arguments. These
407 are optional arguments which are specified by name rather than
408 positionally in the argument list. For example,
411 (defun* foo (a &optional b &key c d (e 17)))
415 defines a function which may be called with one, two, or more
416 arguments. The first two arguments are bound to @code{a} and
417 @code{b} in the usual way. The remaining arguments must be
418 pairs of the form @code{:c}, @code{:d}, or @code{:e} followed
419 by the value to be bound to the corresponding argument variable.
420 (Symbols whose names begin with a colon are called @dfn{keywords},
421 and they are self-quoting in the same way as @code{nil} and
424 For example, the call @code{(foo 1 2 :d 3 :c 4)} sets the five
425 arguments to 1, 2, 4, 3, and 17, respectively. If the same keyword
426 appears more than once in the function call, the first occurrence
427 takes precedence over the later ones. Note that it is not possible
428 to specify keyword arguments without specifying the optional
429 argument @code{b} as well, since @code{(foo 1 :c 2)} would bind
430 @code{b} to the keyword @code{:c}, then signal an error because
431 @code{2} is not a valid keyword.
433 You can also explicitly specify the keyword argument; it need not be
434 simply the variable name prefixed with a colon. For example,
437 (defun* bar (&key (a 1) ((baz b) 4)))
442 specifies a keyword @code{:a} that sets the variable @code{a} with
443 default value 1, as well as a keyword @code{baz} that sets the
444 variable @code{b} with default value 4. In this case, because
445 @code{baz} is not self-quoting, you must quote it explicitly in the
446 function call, like this:
452 Ordinarily, it is an error to pass an unrecognized keyword to
453 a function, e.g., @code{(foo 1 2 :c 3 :goober 4)}. You can ask
454 Lisp to ignore unrecognized keywords, either by adding the
455 marker @code{&allow-other-keys} after the keyword section
456 of the argument list, or by specifying an @code{:allow-other-keys}
457 argument in the call whose value is non-@code{nil}. If the
458 function uses both @code{&rest} and @code{&key} at the same time,
459 the ``rest'' argument is bound to the keyword list as it appears
460 in the call. For example:
463 (defun* find-thing (thing &rest rest &key need &allow-other-keys)
464 (or (apply 'member* thing thing-list :allow-other-keys t rest)
465 (if need (error "Thing not found"))))
469 This function takes a @code{:need} keyword argument, but also
470 accepts other keyword arguments which are passed on to the
471 @code{member*} function. @code{allow-other-keys} is used to
472 keep both @code{find-thing} and @code{member*} from complaining
473 about each others' keywords in the arguments.
475 The fifth section of the argument list consists of @dfn{auxiliary
476 variables}. These are not really arguments at all, but simply
477 variables which are bound to @code{nil} or to the specified
478 @var{initforms} during execution of the function. There is no
479 difference between the following two functions, except for a
480 matter of stylistic taste:
483 (defun* foo (a b &aux (c (+ a b)) d)
491 Argument lists support @dfn{destructuring}. In Common Lisp,
492 destructuring is only allowed with @code{defmacro}; this package
493 allows it with @code{defun*} and other argument lists as well.
494 In destructuring, any argument variable (@var{var} in the above
495 diagram) can be replaced by a list of variables, or more generally,
496 a recursive argument list. The corresponding argument value must
497 be a list whose elements match this recursive argument list.
501 (defmacro* dolist ((var listform &optional resultform)
506 This says that the first argument of @code{dolist} must be a list
507 of two or three items; if there are other arguments as well as this
508 list, they are stored in @code{body}. All features allowed in
509 regular argument lists are allowed in these recursive argument lists.
510 In addition, the clause @samp{&whole @var{var}} is allowed at the
511 front of a recursive argument list. It binds @var{var} to the
512 whole list being matched; thus @code{(&whole all a b)} matches
513 a list of two things, with @code{a} bound to the first thing,
514 @code{b} bound to the second thing, and @code{all} bound to the
515 list itself. (Common Lisp allows @code{&whole} in top-level
516 @code{defmacro} argument lists as well, but Emacs Lisp does not
519 One last feature of destructuring is that the argument list may be
520 dotted, so that the argument list @code{(a b . c)} is functionally
521 equivalent to @code{(a b &rest c)}.
523 If the optimization quality @code{safety} is set to 0
524 (@pxref{Declarations}), error checking for wrong number of
525 arguments and invalid keyword arguments is disabled. By default,
526 argument lists are rigorously checked.
528 @node Time of Evaluation, , Argument Lists, Program Structure
529 @section Time of Evaluation
532 Normally, the byte-compiler does not actually execute the forms in
533 a file it compiles. For example, if a file contains @code{(setq foo t)},
534 the act of compiling it will not actually set @code{foo} to @code{t}.
535 This is true even if the @code{setq} was a top-level form (i.e., not
536 enclosed in a @code{defun} or other form). Sometimes, though, you
537 would like to have certain top-level forms evaluated at compile-time.
538 For example, the compiler effectively evaluates @code{defmacro} forms
539 at compile-time so that later parts of the file can refer to the
540 macros that are defined.
542 @defspec eval-when (situations...) forms...
543 This form controls when the body @var{forms} are evaluated.
544 The @var{situations} list may contain any set of the symbols
545 @code{compile}, @code{load}, and @code{eval} (or their long-winded
546 ANSI equivalents, @code{:compile-toplevel}, @code{:load-toplevel},
547 and @code{:execute}).
549 The @code{eval-when} form is handled differently depending on
550 whether or not it is being compiled as a top-level form.
551 Specifically, it gets special treatment if it is being compiled
552 by a command such as @code{byte-compile-file} which compiles files
553 or buffers of code, and it appears either literally at the
554 top level of the file or inside a top-level @code{progn}.
556 For compiled top-level @code{eval-when}s, the body @var{forms} are
557 executed at compile-time if @code{compile} is in the @var{situations}
558 list, and the @var{forms} are written out to the file (to be executed
559 at load-time) if @code{load} is in the @var{situations} list.
561 For non-compiled-top-level forms, only the @code{eval} situation is
562 relevant. (This includes forms executed by the interpreter, forms
563 compiled with @code{byte-compile} rather than @code{byte-compile-file},
564 and non-top-level forms.) The @code{eval-when} acts like a
565 @code{progn} if @code{eval} is specified, and like @code{nil}
566 (ignoring the body @var{forms}) if not.
568 The rules become more subtle when @code{eval-when}s are nested;
569 consult Steele (second edition) for the gruesome details (and
570 some gruesome examples).
572 Some simple examples:
575 ;; Top-level forms in foo.el:
576 (eval-when (compile) (setq foo1 'bar))
577 (eval-when (load) (setq foo2 'bar))
578 (eval-when (compile load) (setq foo3 'bar))
579 (eval-when (eval) (setq foo4 'bar))
580 (eval-when (eval compile) (setq foo5 'bar))
581 (eval-when (eval load) (setq foo6 'bar))
582 (eval-when (eval compile load) (setq foo7 'bar))
585 When @file{foo.el} is compiled, these variables will be set during
586 the compilation itself:
589 foo1 foo3 foo5 foo7 ; `compile'
592 When @file{foo.elc} is loaded, these variables will be set:
595 foo2 foo3 foo6 foo7 ; `load'
598 And if @file{foo.el} is loaded uncompiled, these variables will
602 foo4 foo5 foo6 foo7 ; `eval'
605 If these seven @code{eval-when}s had been, say, inside a @code{defun},
606 then the first three would have been equivalent to @code{nil} and the
607 last four would have been equivalent to the corresponding @code{setq}s.
609 Note that @code{(eval-when (load eval) @dots{})} is equivalent
610 to @code{(progn @dots{})} in all contexts. The compiler treats
611 certain top-level forms, like @code{defmacro} (sort-of) and
612 @code{require}, as if they were wrapped in @code{(eval-when
613 (compile load eval) @dots{})}.
616 Emacs includes two special forms related to @code{eval-when}.
617 One of these, @code{eval-when-compile}, is not quite equivalent to
618 any @code{eval-when} construct and is described below.
620 The other form, @code{(eval-and-compile @dots{})}, is exactly
621 equivalent to @samp{(eval-when (compile load eval) @dots{})} and
622 so is not itself defined by this package.
624 @defspec eval-when-compile forms...
625 The @var{forms} are evaluated at compile-time; at execution time,
626 this form acts like a quoted constant of the resulting value. Used
627 at top-level, @code{eval-when-compile} is just like @samp{eval-when
628 (compile eval)}. In other contexts, @code{eval-when-compile}
629 allows code to be evaluated once at compile-time for efficiency
632 This form is similar to the @samp{#.} syntax of true Common Lisp.
635 @defspec load-time-value form
636 The @var{form} is evaluated at load-time; at execution time,
637 this form acts like a quoted constant of the resulting value.
639 Early Common Lisp had a @samp{#,} syntax that was similar to
640 this, but ANSI Common Lisp replaced it with @code{load-time-value}
641 and gave it more well-defined semantics.
643 In a compiled file, @code{load-time-value} arranges for @var{form}
644 to be evaluated when the @file{.elc} file is loaded and then used
645 as if it were a quoted constant. In code compiled by
646 @code{byte-compile} rather than @code{byte-compile-file}, the
647 effect is identical to @code{eval-when-compile}. In uncompiled
648 code, both @code{eval-when-compile} and @code{load-time-value}
649 act exactly like @code{progn}.
653 (insert "This function was executed on: "
654 (current-time-string)
656 (eval-when-compile (current-time-string))
657 ;; or '#.(current-time-string) in real Common Lisp
659 (load-time-value (current-time-string))))
663 Byte-compiled, the above defun will result in the following code
664 (or its compiled equivalent, of course) in the @file{.elc} file:
667 (setq --temp-- (current-time-string))
669 (insert "This function was executed on: "
670 (current-time-string)
672 '"Wed Jun 23 18:33:43 1993"
678 @node Predicates, Control Structure, Program Structure, Top
682 This section describes functions for testing whether various
683 facts are true or false.
686 * Type Predicates:: `typep', `deftype', and `coerce'
687 * Equality Predicates:: `equalp'
690 @node Type Predicates, Equality Predicates, Predicates, Predicates
691 @section Type Predicates
694 The @dfn{CL} package defines a version of the Common Lisp @code{typep}
697 @defun typep object type
698 Check if @var{object} is of type @var{type}, where @var{type} is a
699 (quoted) type name of the sort used by Common Lisp. For example,
700 @code{(typep foo 'integer)} is equivalent to @code{(integerp foo)}.
703 The @var{type} argument to the above function is either a symbol
704 or a list beginning with a symbol.
708 If the type name is a symbol, Emacs appends @samp{-p} to the
709 symbol name to form the name of a predicate function for testing
710 the type. (Built-in predicates whose names end in @samp{p} rather
711 than @samp{-p} are used when appropriate.)
714 The type symbol @code{t} stands for the union of all types.
715 @code{(typep @var{object} t)} is always true. Likewise, the
716 type symbol @code{nil} stands for nothing at all, and
717 @code{(typep @var{object} nil)} is always false.
720 The type symbol @code{null} represents the symbol @code{nil}.
721 Thus @code{(typep @var{object} 'null)} is equivalent to
722 @code{(null @var{object})}.
725 The type symbol @code{atom} represents all objects that are not cons
726 cells. Thus @code{(typep @var{object} 'atom)} is equivalent to
727 @code{(atom @var{object})}.
730 The type symbol @code{real} is a synonym for @code{number}, and
731 @code{fixnum} is a synonym for @code{integer}.
734 The type symbols @code{character} and @code{string-char} match
735 integers in the range from 0 to 255.
738 The type symbol @code{float} uses the @code{floatp-safe} predicate
739 defined by this package rather than @code{floatp}, so it will work
740 correctly even in Emacs versions without floating-point support.
743 The type list @code{(integer @var{low} @var{high})} represents all
744 integers between @var{low} and @var{high}, inclusive. Either bound
745 may be a list of a single integer to specify an exclusive limit,
746 or a @code{*} to specify no limit. The type @code{(integer * *)}
747 is thus equivalent to @code{integer}.
750 Likewise, lists beginning with @code{float}, @code{real}, or
751 @code{number} represent numbers of that type falling in a particular
755 Lists beginning with @code{and}, @code{or}, and @code{not} form
756 combinations of types. For example, @code{(or integer (float 0 *))}
757 represents all objects that are integers or non-negative floats.
760 Lists beginning with @code{member} or @code{member*} represent
761 objects @code{eql} to any of the following values. For example,
762 @code{(member 1 2 3 4)} is equivalent to @code{(integer 1 4)},
763 and @code{(member nil)} is equivalent to @code{null}.
766 Lists of the form @code{(satisfies @var{predicate})} represent
767 all objects for which @var{predicate} returns true when called
768 with that object as an argument.
771 The following function and macro (not technically predicates) are
772 related to @code{typep}.
774 @defun coerce object type
775 This function attempts to convert @var{object} to the specified
776 @var{type}. If @var{object} is already of that type as determined by
777 @code{typep}, it is simply returned. Otherwise, certain types of
778 conversions will be made: If @var{type} is any sequence type
779 (@code{string}, @code{list}, etc.) then @var{object} will be
780 converted to that type if possible. If @var{type} is
781 @code{character}, then strings of length one and symbols with
782 one-character names can be coerced. If @var{type} is @code{float},
783 then integers can be coerced in versions of Emacs that support
784 floats. In all other circumstances, @code{coerce} signals an
788 @defspec deftype name arglist forms...
789 This macro defines a new type called @var{name}. It is similar
790 to @code{defmacro} in many ways; when @var{name} is encountered
791 as a type name, the body @var{forms} are evaluated and should
792 return a type specifier that is equivalent to the type. The
793 @var{arglist} is a Common Lisp argument list of the sort accepted
794 by @code{defmacro*}. The type specifier @samp{(@var{name} @var{args}...)}
795 is expanded by calling the expander with those arguments; the type
796 symbol @samp{@var{name}} is expanded by calling the expander with
797 no arguments. The @var{arglist} is processed the same as for
798 @code{defmacro*} except that optional arguments without explicit
799 defaults use @code{*} instead of @code{nil} as the ``default''
800 default. Some examples:
803 (deftype null () '(satisfies null)) ; predefined
804 (deftype list () '(or null cons)) ; predefined
805 (deftype unsigned-byte (&optional bits)
806 (list 'integer 0 (if (eq bits '*) bits (1- (lsh 1 bits)))))
807 (unsigned-byte 8) @equiv{} (integer 0 255)
808 (unsigned-byte) @equiv{} (integer 0 *)
809 unsigned-byte @equiv{} (integer 0 *)
813 The last example shows how the Common Lisp @code{unsigned-byte}
814 type specifier could be implemented if desired; this package does
815 not implement @code{unsigned-byte} by default.
818 The @code{typecase} and @code{check-type} macros also use type
819 names. @xref{Conditionals}. @xref{Assertions}. The @code{map},
820 @code{concatenate}, and @code{merge} functions take type-name
821 arguments to specify the type of sequence to return. @xref{Sequences}.
823 @node Equality Predicates, , Type Predicates, Predicates
824 @section Equality Predicates
827 This package defines the Common Lisp predicate @code{equalp}.
830 This function is a more flexible version of @code{equal}. In
831 particular, it compares strings case-insensitively, and it compares
832 numbers without regard to type (so that @code{(equalp 3 3.0)} is
833 true). Vectors and conses are compared recursively. All other
834 objects are compared as if by @code{equal}.
836 This function differs from Common Lisp @code{equalp} in several
837 respects. First, Common Lisp's @code{equalp} also compares
838 @emph{characters} case-insensitively, which would be impractical
839 in this package since Emacs does not distinguish between integers
840 and characters. In keeping with the idea that strings are less
841 vector-like in Emacs Lisp, this package's @code{equalp} also will
842 not compare strings against vectors of integers.
845 Also note that the Common Lisp functions @code{member} and @code{assoc}
846 use @code{eql} to compare elements, whereas Emacs Lisp follows the
847 MacLisp tradition and uses @code{equal} for these two functions.
848 In Emacs, use @code{member*} and @code{assoc*} to get functions
849 which use @code{eql} for comparisons.
851 @node Control Structure, Macros, Predicates, Top
852 @chapter Control Structure
855 The features described in the following sections implement
856 various advanced control structures, including the powerful
857 @code{setf} facility and a number of looping and conditional
861 * Assignment:: The `psetq' form
862 * Generalized Variables:: `setf', `incf', `push', etc.
863 * Variable Bindings:: `progv', `lexical-let', `flet', `macrolet'
864 * Conditionals:: `case', `typecase'
865 * Blocks and Exits:: `block', `return', `return-from'
866 * Iteration:: `do', `dotimes', `dolist', `do-symbols'
867 * Loop Facility:: The Common Lisp `loop' macro
868 * Multiple Values:: `values', `multiple-value-bind', etc.
871 @node Assignment, Generalized Variables, Control Structure, Control Structure
875 The @code{psetq} form is just like @code{setq}, except that multiple
876 assignments are done in parallel rather than sequentially.
878 @defspec psetq [symbol form]@dots{}
879 This special form (actually a macro) is used to assign to several
880 variables simultaneously. Given only one @var{symbol} and @var{form},
881 it has the same effect as @code{setq}. Given several @var{symbol}
882 and @var{form} pairs, it evaluates all the @var{form}s in advance
883 and then stores the corresponding variables afterwards.
887 (setq x (+ x y) y (* x y))
890 y ; @r{@code{y} was computed after @code{x} was set.}
893 (psetq x (+ x y) y (* x y))
896 y ; @r{@code{y} was computed before @code{x} was set.}
900 The simplest use of @code{psetq} is @code{(psetq x y y x)}, which
901 exchanges the values of two variables. (The @code{rotatef} form
902 provides an even more convenient way to swap two variables;
903 @pxref{Modify Macros}.)
905 @code{psetq} always returns @code{nil}.
908 @node Generalized Variables, Variable Bindings, Assignment, Control Structure
909 @section Generalized Variables
912 A ``generalized variable'' or ``place form'' is one of the many places
913 in Lisp memory where values can be stored. The simplest place form is
914 a regular Lisp variable. But the cars and cdrs of lists, elements
915 of arrays, properties of symbols, and many other locations are also
916 places where Lisp values are stored.
918 The @code{setf} form is like @code{setq}, except that it accepts
919 arbitrary place forms on the left side rather than just
920 symbols. For example, @code{(setf (car a) b)} sets the car of
921 @code{a} to @code{b}, doing the same operation as @code{(setcar a b)}
922 but without having to remember two separate functions for setting
923 and accessing every type of place.
925 Generalized variables are analogous to ``lvalues'' in the C
926 language, where @samp{x = a[i]} gets an element from an array
927 and @samp{a[i] = x} stores an element using the same notation.
928 Just as certain forms like @code{a[i]} can be lvalues in C, there
929 is a set of forms that can be generalized variables in Lisp.
932 * Basic Setf:: `setf' and place forms
933 * Modify Macros:: `incf', `push', `rotatef', `letf', `callf', etc.
934 * Customizing Setf:: `define-modify-macro', `defsetf', `define-setf-method'
937 @node Basic Setf, Modify Macros, Generalized Variables, Generalized Variables
938 @subsection Basic Setf
941 The @code{setf} macro is the most basic way to operate on generalized
944 @defspec setf [place form]@dots{}
945 This macro evaluates @var{form} and stores it in @var{place}, which
946 must be a valid generalized variable form. If there are several
947 @var{place} and @var{form} pairs, the assignments are done sequentially
948 just as with @code{setq}. @code{setf} returns the value of the last
951 The following Lisp forms will work as generalized variables, and
952 so may appear in the @var{place} argument of @code{setf}:
956 A symbol naming a variable. In other words, @code{(setf x y)} is
957 exactly equivalent to @code{(setq x y)}, and @code{setq} itself is
958 strictly speaking redundant now that @code{setf} exists. Many
959 programmers continue to prefer @code{setq} for setting simple
960 variables, though, purely for stylistic or historical reasons.
961 The macro @code{(setf x y)} actually expands to @code{(setq x y)},
962 so there is no performance penalty for using it in compiled code.
965 A call to any of the following Lisp functions:
968 car cdr caar .. cddddr
969 nth rest first .. tenth
971 symbol-function symbol-value symbol-plist
977 Note that for @code{nthcdr} and @code{getf}, the list argument
978 of the function must itself be a valid @var{place} form. For
979 example, @code{(setf (nthcdr 0 foo) 7)} will set @code{foo} itself
980 to 7. Note that @code{push} and @code{pop} on an @code{nthcdr}
981 place can be used to insert or delete at any position in a list.
982 The use of @code{nthcdr} as a @var{place} form is an extension
983 to standard Common Lisp.
986 The following Emacs-specific functions are also @code{setf}-able.
989 buffer-file-name marker-position
990 buffer-modified-p match-data
991 buffer-name mouse-position
992 buffer-string overlay-end
993 buffer-substring overlay-get
994 current-buffer overlay-start
995 current-case-table point
996 current-column point-marker
997 current-global-map point-max
998 current-input-mode point-min
999 current-local-map process-buffer
1000 current-window-configuration process-filter
1001 default-file-modes process-sentinel
1002 default-value read-mouse-position
1003 documentation-property screen-height
1004 extent-data screen-menubar
1005 extent-end-position screen-width
1006 extent-start-position selected-window
1007 face-background selected-screen
1008 face-background-pixmap selected-frame
1009 face-font standard-case-table
1010 face-foreground syntax-table
1011 face-underline-p window-buffer
1012 file-modes window-dedicated-p
1013 frame-height window-display-table
1014 frame-parameters window-height
1015 frame-visible-p window-hscroll
1016 frame-width window-point
1017 get-register window-start
1019 global-key-binding x-get-secondary-selection
1020 keymap-parent x-get-selection
1026 Most of these have directly corresponding ``set'' functions, like
1027 @code{use-local-map} for @code{current-local-map}, or @code{goto-char}
1028 for @code{point}. A few, like @code{point-min}, expand to longer
1029 sequences of code when they are @code{setf}'d (@code{(narrow-to-region
1030 x (point-max))} in this case).
1033 A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])},
1034 where @var{subplace} is itself a valid generalized variable whose
1035 current value is a string, and where the value stored is also a
1036 string. The new string is spliced into the specified part of the
1037 destination string. For example:
1040 (setq a (list "hello" "world"))
1041 @result{} ("hello" "world")
1044 (substring (cadr a) 2 4)
1046 (setf (substring (cadr a) 2 4) "o")
1051 @result{} ("hello" "wood")
1054 The generalized variable @code{buffer-substring}, listed above,
1055 also works in this way by replacing a portion of the current buffer.
1058 A call of the form @code{(apply '@var{func} @dots{})} or
1059 @code{(apply (function @var{func}) @dots{})}, where @var{func}
1060 is a @code{setf}-able function whose store function is ``suitable''
1061 in the sense described in Steele's book; since none of the standard
1062 Emacs place functions are suitable in this sense, this feature is
1063 only interesting when used with places you define yourself with
1064 @code{define-setf-method} or the long form of @code{defsetf}.
1067 A macro call, in which case the macro is expanded and @code{setf}
1068 is applied to the resulting form.
1071 Any form for which a @code{defsetf} or @code{define-setf-method}
1075 Using any forms other than these in the @var{place} argument to
1076 @code{setf} will signal an error.
1078 The @code{setf} macro takes care to evaluate all subforms in
1079 the proper left-to-right order; for example,
1082 (setf (aref vec (incf i)) i)
1086 looks like it will evaluate @code{(incf i)} exactly once, before the
1087 following access to @code{i}; the @code{setf} expander will insert
1088 temporary variables as necessary to ensure that it does in fact work
1089 this way no matter what setf-method is defined for @code{aref}.
1090 (In this case, @code{aset} would be used and no such steps would
1091 be necessary since @code{aset} takes its arguments in a convenient
1094 However, if the @var{place} form is a macro which explicitly
1095 evaluates its arguments in an unusual order, this unusual order
1096 will be preserved. Adapting an example from Steele, given
1099 (defmacro wrong-order (x y) (list 'aref y x))
1103 the form @code{(setf (wrong-order @var{a} @var{b}) 17)} will
1104 evaluate @var{b} first, then @var{a}, just as in an actual call
1105 to @code{wrong-order}.
1108 @node Modify Macros, Customizing Setf, Basic Setf, Generalized Variables
1109 @subsection Modify Macros
1112 This package defines a number of other macros besides @code{setf}
1113 that operate on generalized variables. Many are interesting and
1114 useful even when the @var{place} is just a variable name.
1116 @defspec psetf [place form]@dots{}
1117 This macro is to @code{setf} what @code{psetq} is to @code{setq}:
1118 When several @var{place}s and @var{form}s are involved, the
1119 assignments take place in parallel rather than sequentially.
1120 Specifically, all subforms are evaluated from left to right, then
1121 all the assignments are done (in an undefined order).
1124 @defspec incf place &optional x
1125 This macro increments the number stored in @var{place} by one, or
1126 by @var{x} if specified. The incremented value is returned. For
1127 example, @code{(incf i)} is equivalent to @code{(setq i (1+ i))}, and
1128 @code{(incf (car x) 2)} is equivalent to @code{(setcar x (+ (car x) 2))}.
1130 Once again, care is taken to preserve the ``apparent'' order of
1131 evaluation. For example,
1134 (incf (aref vec (incf i)))
1138 appears to increment @code{i} once, then increment the element of
1139 @code{vec} addressed by @code{i}; this is indeed exactly what it
1140 does, which means the above form is @emph{not} equivalent to the
1141 ``obvious'' expansion,
1144 (setf (aref vec (incf i)) (1+ (aref vec (incf i)))) ; Wrong!
1148 but rather to something more like
1151 (let ((temp (incf i)))
1152 (setf (aref vec temp) (1+ (aref vec temp))))
1156 Again, all of this is taken care of automatically by @code{incf} and
1157 the other generalized-variable macros.
1159 As a more Emacs-specific example of @code{incf}, the expression
1160 @code{(incf (point) @var{n})} is essentially equivalent to
1161 @code{(forward-char @var{n})}.
1164 @defspec decf place &optional x
1165 This macro decrements the number stored in @var{place} by one, or
1166 by @var{x} if specified.
1170 This macro removes and returns the first element of the list stored
1171 in @var{place}. It is analogous to @code{(prog1 (car @var{place})
1172 (setf @var{place} (cdr @var{place})))}, except that it takes care
1173 to evaluate all subforms only once.
1176 @defspec push x place
1177 This macro inserts @var{x} at the front of the list stored in
1178 @var{place}. It is analogous to @code{(setf @var{place} (cons
1179 @var{x} @var{place}))}, except for evaluation of the subforms.
1182 @defspec pushnew x place @t{&key :test :test-not :key}
1183 This macro inserts @var{x} at the front of the list stored in
1184 @var{place}, but only if @var{x} was not @code{eql} to any
1185 existing element of the list. The optional keyword arguments
1186 are interpreted in the same way as for @code{adjoin}.
1187 @xref{Lists as Sets}.
1190 @defspec shiftf place@dots{} newvalue
1191 This macro shifts the @var{place}s left by one, shifting in the
1192 value of @var{newvalue} (which may be any Lisp expression, not just
1193 a generalized variable), and returning the value shifted out of
1194 the first @var{place}. Thus, @code{(shiftf @var{a} @var{b} @var{c}
1195 @var{d})} is equivalent to
1200 (psetf @var{a} @var{b}
1206 except that the subforms of @var{a}, @var{b}, and @var{c} are actually
1207 evaluated only once each and in the apparent order.
1210 @defspec rotatef place@dots{}
1211 This macro rotates the @var{place}s left by one in circular fashion.
1212 Thus, @code{(rotatef @var{a} @var{b} @var{c} @var{d})} is equivalent to
1215 (psetf @var{a} @var{b}
1222 except for the evaluation of subforms. @code{rotatef} always
1223 returns @code{nil}. Note that @code{(rotatef @var{a} @var{b})}
1224 conveniently exchanges @var{a} and @var{b}.
1227 The following macros were invented for this package; they have no
1228 analogues in Common Lisp.
1230 @defspec letf (bindings@dots{}) forms@dots{}
1231 This macro is analogous to @code{let}, but for generalized variables
1232 rather than just symbols. Each @var{binding} should be of the form
1233 @code{(@var{place} @var{value})}; the original contents of the
1234 @var{place}s are saved, the @var{value}s are stored in them, and
1235 then the body @var{form}s are executed. Afterwards, the @var{places}
1236 are set back to their original saved contents. This cleanup happens
1237 even if the @var{form}s exit irregularly due to a @code{throw} or an
1243 (letf (((point) (point-min))
1249 moves ``point'' in the current buffer to the beginning of the buffer,
1250 and also binds @code{a} to 17 (as if by a normal @code{let}, since
1251 @code{a} is just a regular variable). After the body exits, @code{a}
1252 is set back to its original value and point is moved back to its
1255 Note that @code{letf} on @code{(point)} is not quite like a
1256 @code{save-excursion}, as the latter effectively saves a marker
1257 which tracks insertions and deletions in the buffer. Actually,
1258 a @code{letf} of @code{(point-marker)} is much closer to this
1259 behavior. (@code{point} and @code{point-marker} are equivalent
1260 as @code{setf} places; each will accept either an integer or a
1261 marker as the stored value.)
1263 Since generalized variables look like lists, @code{let}'s shorthand
1264 of using @samp{foo} for @samp{(foo nil)} as a @var{binding} would
1265 be ambiguous in @code{letf} and is not allowed.
1267 However, a @var{binding} specifier may be a one-element list
1268 @samp{(@var{place})}, which is similar to @samp{(@var{place}
1269 @var{place})}. In other words, the @var{place} is not disturbed
1270 on entry to the body, and the only effect of the @code{letf} is
1271 to restore the original value of @var{place} afterwards. (The
1272 redundant access-and-store suggested by the @code{(@var{place}
1273 @var{place})} example does not actually occur.)
1275 In most cases, the @var{place} must have a well-defined value on
1276 entry to the @code{letf} form. The only exceptions are plain
1277 variables and calls to @code{symbol-value} and @code{symbol-function}.
1278 If the symbol is not bound on entry, it is simply made unbound by
1279 @code{makunbound} or @code{fmakunbound} on exit.
1282 @defspec letf* (bindings@dots{}) forms@dots{}
1283 This macro is to @code{letf} what @code{let*} is to @code{let}:
1284 It does the bindings in sequential rather than parallel order.
1287 @defspec callf @var{function} @var{place} @var{args}@dots{}
1288 This is the ``generic'' modify macro. It calls @var{function},
1289 which should be an unquoted function name, macro name, or lambda.
1290 It passes @var{place} and @var{args} as arguments, and assigns the
1291 result back to @var{place}. For example, @code{(incf @var{place}
1292 @var{n})} is the same as @code{(callf + @var{place} @var{n})}.
1296 (callf abs my-number)
1297 (callf concat (buffer-name) "<" (int-to-string n) ">")
1298 (callf union happy-people (list joe bob) :test 'same-person)
1301 @xref{Customizing Setf}, for @code{define-modify-macro}, a way
1302 to create even more concise notations for modify macros. Note
1303 again that @code{callf} is an extension to standard Common Lisp.
1306 @defspec callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{}
1307 This macro is like @code{callf}, except that @var{place} is
1308 the @emph{second} argument of @var{function} rather than the
1309 first. For example, @code{(push @var{x} @var{place})} is
1310 equivalent to @code{(callf2 cons @var{x} @var{place})}.
1313 The @code{callf} and @code{callf2} macros serve as building
1314 blocks for other macros like @code{incf}, @code{pushnew}, and
1315 @code{define-modify-macro}. The @code{letf} and @code{letf*}
1316 macros are used in the processing of symbol macros;
1317 @pxref{Macro Bindings}.
1319 @node Customizing Setf, , Modify Macros, Generalized Variables
1320 @subsection Customizing Setf
1323 Common Lisp defines three macros, @code{define-modify-macro},
1324 @code{defsetf}, and @code{define-setf-method}, that allow the
1325 user to extend generalized variables in various ways.
1327 @defspec define-modify-macro name arglist function [doc-string]
1328 This macro defines a ``read-modify-write'' macro similar to
1329 @code{incf} and @code{decf}. The macro @var{name} is defined
1330 to take a @var{place} argument followed by additional arguments
1331 described by @var{arglist}. The call
1334 (@var{name} @var{place} @var{args}...)
1341 (callf @var{func} @var{place} @var{args}...)
1345 which in turn is roughly equivalent to
1348 (setf @var{place} (@var{func} @var{place} @var{args}...))
1354 (define-modify-macro incf (&optional (n 1)) +)
1355 (define-modify-macro concatf (&rest args) concat)
1358 Note that @code{&key} is not allowed in @var{arglist}, but
1359 @code{&rest} is sufficient to pass keywords on to the function.
1361 Most of the modify macros defined by Common Lisp do not exactly
1362 follow the pattern of @code{define-modify-macro}. For example,
1363 @code{push} takes its arguments in the wrong order, and @code{pop}
1364 is completely irregular. You can define these macros ``by hand''
1365 using @code{get-setf-method}, or consult the source file
1366 @file{cl-macs.el} to see how to use the internal @code{setf}
1370 @defspec defsetf access-fn update-fn
1371 This is the simpler of two @code{defsetf} forms. Where
1372 @var{access-fn} is the name of a function which accesses a place,
1373 this declares @var{update-fn} to be the corresponding store
1374 function. From now on,
1377 (setf (@var{access-fn} @var{arg1} @var{arg2} @var{arg3}) @var{value})
1384 (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} @var{value})
1388 The @var{update-fn} is required to be either a true function, or
1389 a macro which evaluates its arguments in a function-like way. Also,
1390 the @var{update-fn} is expected to return @var{value} as its result.
1391 Otherwise, the above expansion would not obey the rules for the way
1392 @code{setf} is supposed to behave.
1394 As a special (non-Common-Lisp) extension, a third argument of @code{t}
1395 to @code{defsetf} says that the @code{update-fn}'s return value is
1396 not suitable, so that the above @code{setf} should be expanded to
1400 (let ((temp @var{value}))
1401 (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} temp)
1405 Some examples of the use of @code{defsetf}, drawn from the standard
1406 suite of setf methods, are:
1409 (defsetf car setcar)
1410 (defsetf symbol-value set)
1411 (defsetf buffer-name rename-buffer t)
1415 @defspec defsetf access-fn arglist (store-var) forms@dots{}
1416 This is the second, more complex, form of @code{defsetf}. It is
1417 rather like @code{defmacro} except for the additional @var{store-var}
1418 argument. The @var{forms} should return a Lisp form which stores
1419 the value of @var{store-var} into the generalized variable formed
1420 by a call to @var{access-fn} with arguments described by @var{arglist}.
1421 The @var{forms} may begin with a string which documents the @code{setf}
1422 method (analogous to the doc string that appears at the front of a
1425 For example, the simple form of @code{defsetf} is shorthand for
1428 (defsetf @var{access-fn} (&rest args) (store)
1429 (append '(@var{update-fn}) args (list store)))
1432 The Lisp form that is returned can access the arguments from
1433 @var{arglist} and @var{store-var} in an unrestricted fashion;
1434 macros like @code{setf} and @code{incf} which invoke this
1435 setf-method will insert temporary variables as needed to make
1436 sure the apparent order of evaluation is preserved.
1438 Another example drawn from the standard package:
1441 (defsetf nth (n x) (store)
1442 (list 'setcar (list 'nthcdr n x) store))
1446 @defspec define-setf-method access-fn arglist forms@dots{}
1447 This is the most general way to create new place forms. When
1448 a @code{setf} to @var{access-fn} with arguments described by
1449 @var{arglist} is expanded, the @var{forms} are evaluated and
1450 must return a list of five items:
1454 A list of @dfn{temporary variables}.
1457 A list of @dfn{value forms} corresponding to the temporary variables
1458 above. The temporary variables will be bound to these value forms
1459 as the first step of any operation on the generalized variable.
1462 A list of exactly one @dfn{store variable} (generally obtained
1463 from a call to @code{gensym}).
1466 A Lisp form which stores the contents of the store variable into
1467 the generalized variable, assuming the temporaries have been
1468 bound as described above.
1471 A Lisp form which accesses the contents of the generalized variable,
1472 assuming the temporaries have been bound.
1475 This is exactly like the Common Lisp macro of the same name,
1476 except that the method returns a list of five values rather
1477 than the five values themselves, since Emacs Lisp does not
1478 support Common Lisp's notion of multiple return values.
1480 Once again, the @var{forms} may begin with a documentation string.
1482 A setf-method should be maximally conservative with regard to
1483 temporary variables. In the setf-methods generated by
1484 @code{defsetf}, the second return value is simply the list of
1485 arguments in the place form, and the first return value is a
1486 list of a corresponding number of temporary variables generated
1487 by @code{gensym}. Macros like @code{setf} and @code{incf} which
1488 use this setf-method will optimize away most temporaries that
1489 turn out to be unnecessary, so there is little reason for the
1490 setf-method itself to optimize.
1493 @defun get-setf-method place &optional env
1494 This function returns the setf-method for @var{place}, by
1495 invoking the definition previously recorded by @code{defsetf}
1496 or @code{define-setf-method}. The result is a list of five
1497 values as described above. You can use this function to build
1498 your own @code{incf}-like modify macros. (Actually, it is
1499 better to use the internal functions @code{cl-setf-do-modify}
1500 and @code{cl-setf-do-store}, which are a bit easier to use and
1501 which also do a number of optimizations; consult the source
1502 code for the @code{incf} function for a simple example.)
1504 The argument @var{env} specifies the ``environment'' to be
1505 passed on to @code{macroexpand} if @code{get-setf-method} should
1506 need to expand a macro in @var{place}. It should come from
1507 an @code{&environment} argument to the macro or setf-method
1508 that called @code{get-setf-method}.
1510 See also the source code for the setf-methods for @code{apply}
1511 and @code{substring}, each of which works by calling
1512 @code{get-setf-method} on a simpler case, then massaging
1513 the result in various ways.
1516 Modern Common Lisp defines a second, independent way to specify
1517 the @code{setf} behavior of a function, namely ``@code{setf}
1518 functions'' whose names are lists @code{(setf @var{name})}
1519 rather than symbols. For example, @code{(defun (setf foo) @dots{})}
1520 defines the function that is used when @code{setf} is applied to
1521 @code{foo}. This package does not currently support @code{setf}
1522 functions. In particular, it is a compile-time error to use
1523 @code{setf} on a form which has not already been @code{defsetf}'d
1524 or otherwise declared; in newer Common Lisps, this would not be
1525 an error since the function @code{(setf @var{func})} might be
1532 @node Variable Bindings, Conditionals, Generalized Variables, Control Structure
1533 @section Variable Bindings
1536 These Lisp forms make bindings to variables and function names,
1537 analogous to Lisp's built-in @code{let} form.
1539 @xref{Modify Macros}, for the @code{letf} and @code{letf*} forms which
1540 are also related to variable bindings.
1543 * Dynamic Bindings:: The `progv' form
1544 * Lexical Bindings:: `lexical-let' and lexical closures
1545 * Function Bindings:: `flet' and `labels'
1546 * Macro Bindings:: `macrolet' and `symbol-macrolet'
1549 @node Dynamic Bindings, Lexical Bindings, Variable Bindings, Variable Bindings
1550 @subsection Dynamic Bindings
1553 The standard @code{let} form binds variables whose names are known
1554 at compile-time. The @code{progv} form provides an easy way to
1555 bind variables whose names are computed at run-time.
1557 @defspec progv symbols values forms@dots{}
1558 This form establishes @code{let}-style variable bindings on a
1559 set of variables computed at run-time. The expressions
1560 @var{symbols} and @var{values} are evaluated, and must return lists
1561 of symbols and values, respectively. The symbols are bound to the
1562 corresponding values for the duration of the body @var{form}s.
1563 If @var{values} is shorter than @var{symbols}, the last few symbols
1564 are made unbound (as if by @code{makunbound}) inside the body.
1565 If @var{symbols} is shorter than @var{values}, the excess values
1569 @node Lexical Bindings, Function Bindings, Dynamic Bindings, Variable Bindings
1570 @subsection Lexical Bindings
1573 The @dfn{CL} package defines the following macro which
1574 more closely follows the Common Lisp @code{let} form:
1576 @defspec lexical-let (bindings@dots{}) forms@dots{}
1577 This form is exactly like @code{let} except that the bindings it
1578 establishes are purely lexical. Lexical bindings are similar to
1579 local variables in a language like C: Only the code physically
1580 within the body of the @code{lexical-let} (after macro expansion)
1581 may refer to the bound variables.
1585 (defun foo (b) (+ a b))
1586 (let ((a 2)) (foo a))
1588 (lexical-let ((a 2)) (foo a))
1593 In this example, a regular @code{let} binding of @code{a} actually
1594 makes a temporary change to the global variable @code{a}, so @code{foo}
1595 is able to see the binding of @code{a} to 2. But @code{lexical-let}
1596 actually creates a distinct local variable @code{a} for use within its
1597 body, without any effect on the global variable of the same name.
1599 The most important use of lexical bindings is to create @dfn{closures}.
1600 A closure is a function object that refers to an outside lexical
1601 variable. For example:
1604 (defun make-adder (n)
1605 (lexical-let ((n n))
1606 (function (lambda (m) (+ n m)))))
1607 (setq add17 (make-adder 17))
1613 The call @code{(make-adder 17)} returns a function object which adds
1614 17 to its argument. If @code{let} had been used instead of
1615 @code{lexical-let}, the function object would have referred to the
1616 global @code{n}, which would have been bound to 17 only during the
1617 call to @code{make-adder} itself.
1620 (defun make-counter ()
1621 (lexical-let ((n 0))
1622 (function* (lambda (&optional (m 1)) (incf n m)))))
1623 (setq count-1 (make-counter))
1626 (funcall count-1 14)
1628 (setq count-2 (make-counter))
1638 Here we see that each call to @code{make-counter} creates a distinct
1639 local variable @code{n}, which serves as a private counter for the
1640 function object that is returned.
1642 Closed-over lexical variables persist until the last reference to
1643 them goes away, just like all other Lisp objects. For example,
1644 @code{count-2} refers to a function object which refers to an
1645 instance of the variable @code{n}; this is the only reference
1646 to that variable, so after @code{(setq count-2 nil)} the garbage
1647 collector would be able to delete this instance of @code{n}.
1648 Of course, if a @code{lexical-let} does not actually create any
1649 closures, then the lexical variables are free as soon as the
1650 @code{lexical-let} returns.
1652 Many closures are used only during the extent of the bindings they
1653 refer to; these are known as ``downward funargs'' in Lisp parlance.
1654 When a closure is used in this way, regular Emacs Lisp dynamic
1655 bindings suffice and will be more efficient than @code{lexical-let}
1659 (defun add-to-list (x list)
1660 (mapcar (lambda (y) (+ x y))) list)
1661 (add-to-list 7 '(1 2 5))
1666 Since this lambda is only used while @code{x} is still bound,
1667 it is not necessary to make a true closure out of it.
1669 You can use @code{defun} or @code{flet} inside a @code{lexical-let}
1670 to create a named closure. If several closures are created in the
1671 body of a single @code{lexical-let}, they all close over the same
1672 instance of the lexical variable.
1674 The @code{lexical-let} form is an extension to Common Lisp. In
1675 true Common Lisp, all bindings are lexical unless declared otherwise.
1678 @defspec lexical-let* (bindings@dots{}) forms@dots{}
1679 This form is just like @code{lexical-let}, except that the bindings
1680 are made sequentially in the manner of @code{let*}.
1683 @node Function Bindings, Macro Bindings, Lexical Bindings, Variable Bindings
1684 @subsection Function Bindings
1687 These forms make @code{let}-like bindings to functions instead
1690 @defspec flet (bindings@dots{}) forms@dots{}
1691 This form establishes @code{let}-style bindings on the function
1692 cells of symbols rather than on the value cells. Each @var{binding}
1693 must be a list of the form @samp{(@var{name} @var{arglist}
1694 @var{forms}@dots{})}, which defines a function exactly as if
1695 it were a @code{defun*} form. The function @var{name} is defined
1696 accordingly for the duration of the body of the @code{flet}; then
1697 the old function definition, or lack thereof, is restored.
1699 While @code{flet} in Common Lisp establishes a lexical binding of
1700 @var{name}, Emacs Lisp @code{flet} makes a dynamic binding. The
1701 result is that @code{flet} affects indirect calls to a function as
1702 well as calls directly inside the @code{flet} form itself.
1704 You can use @code{flet} to disable or modify the behavior of a
1705 function in a temporary fashion. This will even work on Emacs
1706 primitives, although note that some calls to primitive functions
1707 internal to Emacs are made without going through the symbol's
1708 function cell, and so will not be affected by @code{flet}. For
1712 (flet ((message (&rest args) (push args saved-msgs)))
1716 This code attempts to replace the built-in function @code{message}
1717 with a function that simply saves the messages in a list rather
1718 than displaying them. The original definition of @code{message}
1719 will be restored after @code{do-something} exits. This code will
1720 work fine on messages generated by other Lisp code, but messages
1721 generated directly inside Emacs will not be caught since they make
1722 direct C-language calls to the message routines rather than going
1723 through the Lisp @code{message} function.
1726 Also note that many primitives (e.g. @code{+}) have special byte-compile
1727 handling. Attempts to redefine such functions using @code{flet} will
1728 fail if byte-compiled. In such cases, use @code{labels} instead.
1730 Functions defined by @code{flet} may use the full Common Lisp
1731 argument notation supported by @code{defun*}; also, the function
1732 body is enclosed in an implicit block as if by @code{defun*}.
1733 @xref{Program Structure}.
1736 @defspec labels (bindings@dots{}) forms@dots{}
1737 The @code{labels} form is like @code{flet}, except that it
1738 makes lexical bindings of the function names rather than
1739 dynamic bindings. (In true Common Lisp, both @code{flet} and
1740 @code{labels} make lexical bindings of slightly different sorts;
1741 since Emacs Lisp is dynamically bound by default, it seemed
1742 more appropriate for @code{flet} also to use dynamic binding.
1743 The @code{labels} form, with its lexical binding, is fully
1744 compatible with Common Lisp.)
1746 Lexical scoping means that all references to the named
1747 functions must appear physically within the body of the
1748 @code{labels} form. References may appear both in the body
1749 @var{forms} of @code{labels} itself, and in the bodies of
1750 the functions themselves. Thus, @code{labels} can define
1751 local recursive functions, or mutually-recursive sets of
1754 A ``reference'' to a function name is either a call to that
1755 function, or a use of its name quoted by @code{quote} or
1756 @code{function} to be passed on to, say, @code{mapcar}.
1759 @node Macro Bindings, , Function Bindings, Variable Bindings
1760 @subsection Macro Bindings
1763 These forms create local macros and ``symbol macros.''
1765 @defspec macrolet (bindings@dots{}) forms@dots{}
1766 This form is analogous to @code{flet}, but for macros instead of
1767 functions. Each @var{binding} is a list of the same form as the
1768 arguments to @code{defmacro*} (i.e., a macro name, argument list,
1769 and macro-expander forms). The macro is defined accordingly for
1770 use within the body of the @code{macrolet}.
1772 Because of the nature of macros, @code{macrolet} is lexically
1773 scoped even in Emacs Lisp: The @code{macrolet} binding will
1774 affect only calls that appear physically within the body
1775 @var{forms}, possibly after expansion of other macros in the
1779 @defspec symbol-macrolet (bindings@dots{}) forms@dots{}
1780 This form creates @dfn{symbol macros}, which are macros that look
1781 like variable references rather than function calls. Each
1782 @var{binding} is a list @samp{(@var{var} @var{expansion})};
1783 any reference to @var{var} within the body @var{forms} is
1784 replaced by @var{expansion}.
1788 (symbol-macrolet ((foo (car bar)))
1794 A @code{setq} of a symbol macro is treated the same as a @code{setf}.
1795 I.e., @code{(setq foo 4)} in the above would be equivalent to
1796 @code{(setf foo 4)}, which in turn expands to @code{(setf (car bar) 4)}.
1798 Likewise, a @code{let} or @code{let*} binding a symbol macro is
1799 treated like a @code{letf} or @code{letf*}. This differs from true
1800 Common Lisp, where the rules of lexical scoping cause a @code{let}
1801 binding to shadow a @code{symbol-macrolet} binding. In this package,
1802 only @code{lexical-let} and @code{lexical-let*} will shadow a symbol
1805 There is no analogue of @code{defmacro} for symbol macros; all symbol
1806 macros are local. A typical use of @code{symbol-macrolet} is in the
1807 expansion of another macro:
1810 (defmacro* my-dolist ((x list) &rest body)
1811 (let ((var (gensym)))
1812 (list 'loop 'for var 'on list 'do
1813 (list* 'symbol-macrolet (list (list x (list 'car var)))
1816 (setq mylist '(1 2 3 4))
1817 (my-dolist (x mylist) (incf x))
1823 In this example, the @code{my-dolist} macro is similar to @code{dolist}
1824 (@pxref{Iteration}) except that the variable @code{x} becomes a true
1825 reference onto the elements of the list. The @code{my-dolist} call
1826 shown here expands to
1829 (loop for G1234 on mylist do
1830 (symbol-macrolet ((x (car G1234)))
1835 which in turn expands to
1838 (loop for G1234 on mylist do (incf (car G1234)))
1841 @xref{Loop Facility}, for a description of the @code{loop} macro.
1842 This package defines a nonstandard @code{in-ref} loop clause that
1843 works much like @code{my-dolist}.
1846 @node Conditionals, Blocks and Exits, Variable Bindings, Control Structure
1847 @section Conditionals
1850 These conditional forms augment Emacs Lisp's simple @code{if},
1851 @code{and}, @code{or}, and @code{cond} forms.
1853 @defspec case keyform clause@dots{}
1854 This macro evaluates @var{keyform}, then compares it with the key
1855 values listed in the various @var{clause}s. Whichever clause matches
1856 the key is executed; comparison is done by @code{eql}. If no clause
1857 matches, the @code{case} form returns @code{nil}. The clauses are
1861 (@var{keylist} @var{body-forms}@dots{})
1865 where @var{keylist} is a list of key values. If there is exactly
1866 one value, and it is not a cons cell or the symbol @code{nil} or
1867 @code{t}, then it can be used by itself as a @var{keylist} without
1868 being enclosed in a list. All key values in the @code{case} form
1869 must be distinct. The final clauses may use @code{t} in place of
1870 a @var{keylist} to indicate a default clause that should be taken
1871 if none of the other clauses match. (The symbol @code{otherwise}
1872 is also recognized in place of @code{t}. To make a clause that
1873 matches the actual symbol @code{t}, @code{nil}, or @code{otherwise},
1874 enclose the symbol in a list.)
1876 For example, this expression reads a keystroke, then does one of
1877 four things depending on whether it is an @samp{a}, a @samp{b},
1878 a @key{RET} or @kbd{C-j}, or anything else.
1884 ((?\r ?\n) (do-ret-thing))
1885 (t (do-other-thing)))
1889 @defspec ecase keyform clause@dots{}
1890 This macro is just like @code{case}, except that if the key does
1891 not match any of the clauses, an error is signaled rather than
1892 simply returning @code{nil}.
1895 @defspec typecase keyform clause@dots{}
1896 This macro is a version of @code{case} that checks for types
1897 rather than values. Each @var{clause} is of the form
1898 @samp{(@var{type} @var{body}...)}. @xref{Type Predicates},
1899 for a description of type specifiers. For example,
1903 (integer (munch-integer x))
1904 (float (munch-float x))
1905 (string (munch-integer (string-to-int x)))
1906 (t (munch-anything x)))
1909 The type specifier @code{t} matches any type of object; the word
1910 @code{otherwise} is also allowed. To make one clause match any of
1911 several types, use an @code{(or ...)} type specifier.
1914 @defspec etypecase keyform clause@dots{}
1915 This macro is just like @code{typecase}, except that if the key does
1916 not match any of the clauses, an error is signaled rather than
1917 simply returning @code{nil}.
1920 @node Blocks and Exits, Iteration, Conditionals, Control Structure
1921 @section Blocks and Exits
1924 Common Lisp @dfn{blocks} provide a non-local exit mechanism very
1925 similar to @code{catch} and @code{throw}, but lexically rather than
1926 dynamically scoped. This package actually implements @code{block}
1927 in terms of @code{catch}; however, the lexical scoping allows the
1928 optimizing byte-compiler to omit the costly @code{catch} step if the
1929 body of the block does not actually @code{return-from} the block.
1931 @defspec block name forms@dots{}
1932 The @var{forms} are evaluated as if by a @code{progn}. However,
1933 if any of the @var{forms} execute @code{(return-from @var{name})},
1934 they will jump out and return directly from the @code{block} form.
1935 The @code{block} returns the result of the last @var{form} unless
1936 a @code{return-from} occurs.
1938 The @code{block}/@code{return-from} mechanism is quite similar to
1939 the @code{catch}/@code{throw} mechanism. The main differences are
1940 that block @var{name}s are unevaluated symbols, rather than forms
1941 (such as quoted symbols) which evaluate to a tag at run-time; and
1942 also that blocks are lexically scoped whereas @code{catch}/@code{throw}
1943 are dynamically scoped. This means that functions called from the
1944 body of a @code{catch} can also @code{throw} to the @code{catch},
1945 but the @code{return-from} referring to a block name must appear
1946 physically within the @var{forms} that make up the body of the block.
1947 They may not appear within other called functions, although they may
1948 appear within macro expansions or @code{lambda}s in the body. Block
1949 names and @code{catch} names form independent name-spaces.
1951 In true Common Lisp, @code{defun} and @code{defmacro} surround
1952 the function or expander bodies with implicit blocks with the
1953 same name as the function or macro. This does not occur in Emacs
1954 Lisp, but this package provides @code{defun*} and @code{defmacro*}
1955 forms which do create the implicit block.
1957 The Common Lisp looping constructs defined by this package,
1958 such as @code{loop} and @code{dolist}, also create implicit blocks
1959 just as in Common Lisp.
1961 Because they are implemented in terms of Emacs Lisp @code{catch}
1962 and @code{throw}, blocks have the same overhead as actual
1963 @code{catch} constructs (roughly two function calls). However,
1964 the optimizing byte compiler will optimize away the @code{catch}
1966 not in fact contain any @code{return} or @code{return-from} calls
1967 that jump to it. This means that @code{do} loops and @code{defun*}
1968 functions which don't use @code{return} don't pay the overhead to
1972 @defspec return-from name [result]
1973 This macro returns from the block named @var{name}, which must be
1974 an (unevaluated) symbol. If a @var{result} form is specified, it
1975 is evaluated to produce the result returned from the @code{block}.
1976 Otherwise, @code{nil} is returned.
1979 @defspec return [result]
1980 This macro is exactly like @code{(return-from nil @var{result})}.
1981 Common Lisp loops like @code{do} and @code{dolist} implicitly enclose
1982 themselves in @code{nil} blocks.
1985 @node Iteration, Loop Facility, Blocks and Exits, Control Structure
1989 The macros described here provide more sophisticated, high-level
1990 looping constructs to complement Emacs Lisp's basic @code{while}
1993 @defspec loop forms@dots{}
1994 The @dfn{CL} package supports both the simple, old-style meaning of
1995 @code{loop} and the extremely powerful and flexible feature known as
1996 the @dfn{Loop Facility} or @dfn{Loop Macro}. This more advanced
1997 facility is discussed in the following section; @pxref{Loop Facility}.
1998 The simple form of @code{loop} is described here.
2000 If @code{loop} is followed by zero or more Lisp expressions,
2001 then @code{(loop @var{exprs}@dots{})} simply creates an infinite
2002 loop executing the expressions over and over. The loop is
2003 enclosed in an implicit @code{nil} block. Thus,
2006 (loop (foo) (if (no-more) (return 72)) (bar))
2010 is exactly equivalent to
2013 (block nil (while t (foo) (if (no-more) (return 72)) (bar)))
2016 If any of the expressions are plain symbols, the loop is instead
2017 interpreted as a Loop Macro specification as described later.
2018 (This is not a restriction in practice, since a plain symbol
2019 in the above notation would simply access and throw away the
2020 value of a variable.)
2023 @defspec do (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
2024 This macro creates a general iterative loop. Each @var{spec} is
2028 (@var{var} [@var{init} [@var{step}]])
2031 The loop works as follows: First, each @var{var} is bound to the
2032 associated @var{init} value as if by a @code{let} form. Then, in
2033 each iteration of the loop, the @var{end-test} is evaluated; if
2034 true, the loop is finished. Otherwise, the body @var{forms} are
2035 evaluated, then each @var{var} is set to the associated @var{step}
2036 expression (as if by a @code{psetq} form) and the next iteration
2037 begins. Once the @var{end-test} becomes true, the @var{result}
2038 forms are evaluated (with the @var{var}s still bound to their
2039 values) to produce the result returned by @code{do}.
2041 The entire @code{do} loop is enclosed in an implicit @code{nil}
2042 block, so that you can use @code{(return)} to break out of the
2045 If there are no @var{result} forms, the loop returns @code{nil}.
2046 If a given @var{var} has no @var{step} form, it is bound to its
2047 @var{init} value but not otherwise modified during the @code{do}
2048 loop (unless the code explicitly modifies it); this case is just
2049 a shorthand for putting a @code{(let ((@var{var} @var{init})) @dots{})}
2050 around the loop. If @var{init} is also omitted it defaults to
2051 @code{nil}, and in this case a plain @samp{@var{var}} can be used
2052 in place of @samp{(@var{var})}, again following the analogy with
2055 This example (from Steele) illustrates a loop which applies the
2056 function @code{f} to successive pairs of values from the lists
2057 @code{foo} and @code{bar}; it is equivalent to the call
2058 @code{(mapcar* 'f foo bar)}. Note that this loop has no body
2059 @var{forms} at all, performing all its work as side effects of
2060 the rest of the loop.
2063 (do ((x foo (cdr x))
2065 (z nil (cons (f (car x) (car y)) z)))
2066 ((or (null x) (null y))
2071 @defspec do* (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
2072 This is to @code{do} what @code{let*} is to @code{let}. In
2073 particular, the initial values are bound as if by @code{let*}
2074 rather than @code{let}, and the steps are assigned as if by
2075 @code{setq} rather than @code{psetq}.
2077 Here is another way to write the above loop:
2080 (do* ((xp foo (cdr xp))
2082 (x (car xp) (car xp))
2083 (y (car yp) (car yp))
2085 ((or (null xp) (null yp))
2091 @defspec dolist (var list [result]) forms@dots{}
2092 This is a more specialized loop which iterates across the elements
2093 of a list. @var{list} should evaluate to a list; the body @var{forms}
2094 are executed with @var{var} bound to each element of the list in
2095 turn. Finally, the @var{result} form (or @code{nil}) is evaluated
2096 with @var{var} bound to @code{nil} to produce the result returned by
2097 the loop. Unlike with Emacs's built in @code{dolist}, the loop is
2098 surrounded by an implicit @code{nil} block.
2101 @defspec dotimes (var count [result]) forms@dots{}
2102 This is a more specialized loop which iterates a specified number
2103 of times. The body is executed with @var{var} bound to the integers
2104 from zero (inclusive) to @var{count} (exclusive), in turn. Then
2105 the @code{result} form is evaluated with @var{var} bound to the total
2106 number of iterations that were done (i.e., @code{(max 0 @var{count})})
2107 to get the return value for the loop form. Unlike with Emacs's built in
2108 @code{dolist}, the loop is surrounded by an implicit @code{nil} block.
2111 @defspec do-symbols (var [obarray [result]]) forms@dots{}
2112 This loop iterates over all interned symbols. If @var{obarray}
2113 is specified and is not @code{nil}, it loops over all symbols in
2114 that obarray. For each symbol, the body @var{forms} are evaluated
2115 with @var{var} bound to that symbol. The symbols are visited in
2116 an unspecified order. Afterward the @var{result} form, if any,
2117 is evaluated (with @var{var} bound to @code{nil}) to get the return
2118 value. The loop is surrounded by an implicit @code{nil} block.
2121 @defspec do-all-symbols (var [result]) forms@dots{}
2122 This is identical to @code{do-symbols} except that the @var{obarray}
2123 argument is omitted; it always iterates over the default obarray.
2126 @xref{Mapping over Sequences}, for some more functions for
2127 iterating over vectors or lists.
2129 @node Loop Facility, Multiple Values, Iteration, Control Structure
2130 @section Loop Facility
2133 A common complaint with Lisp's traditional looping constructs is
2134 that they are either too simple and limited, such as Common Lisp's
2135 @code{dotimes} or Emacs Lisp's @code{while}, or too unreadable and
2136 obscure, like Common Lisp's @code{do} loop.
2138 To remedy this, recent versions of Common Lisp have added a new
2139 construct called the ``Loop Facility'' or ``@code{loop} macro,''
2140 with an easy-to-use but very powerful and expressive syntax.
2143 * Loop Basics:: `loop' macro, basic clause structure
2144 * Loop Examples:: Working examples of `loop' macro
2145 * For Clauses:: Clauses introduced by `for' or `as'
2146 * Iteration Clauses:: `repeat', `while', `thereis', etc.
2147 * Accumulation Clauses:: `collect', `sum', `maximize', etc.
2148 * Other Clauses:: `with', `if', `initially', `finally'
2151 @node Loop Basics, Loop Examples, Loop Facility, Loop Facility
2152 @subsection Loop Basics
2155 The @code{loop} macro essentially creates a mini-language within
2156 Lisp that is specially tailored for describing loops. While this
2157 language is a little strange-looking by the standards of regular Lisp,
2158 it turns out to be very easy to learn and well-suited to its purpose.
2160 Since @code{loop} is a macro, all parsing of the loop language
2161 takes place at byte-compile time; compiled @code{loop}s are just
2162 as efficient as the equivalent @code{while} loops written longhand.
2164 @defspec loop clauses@dots{}
2165 A loop construct consists of a series of @var{clause}s, each
2166 introduced by a symbol like @code{for} or @code{do}. Clauses
2167 are simply strung together in the argument list of @code{loop},
2168 with minimal extra parentheses. The various types of clauses
2169 specify initializations, such as the binding of temporary
2170 variables, actions to be taken in the loop, stepping actions,
2173 Common Lisp specifies a certain general order of clauses in a
2177 (loop @var{name-clause}
2178 @var{var-clauses}@dots{}
2179 @var{action-clauses}@dots{})
2182 The @var{name-clause} optionally gives a name to the implicit
2183 block that surrounds the loop. By default, the implicit block
2184 is named @code{nil}. The @var{var-clauses} specify what
2185 variables should be bound during the loop, and how they should
2186 be modified or iterated throughout the course of the loop. The
2187 @var{action-clauses} are things to be done during the loop, such
2188 as computing, collecting, and returning values.
2190 The Emacs version of the @code{loop} macro is less restrictive about
2191 the order of clauses, but things will behave most predictably if
2192 you put the variable-binding clauses @code{with}, @code{for}, and
2193 @code{repeat} before the action clauses. As in Common Lisp,
2194 @code{initially} and @code{finally} clauses can go anywhere.
2196 Loops generally return @code{nil} by default, but you can cause
2197 them to return a value by using an accumulation clause like
2198 @code{collect}, an end-test clause like @code{always}, or an
2199 explicit @code{return} clause to jump out of the implicit block.
2200 (Because the loop body is enclosed in an implicit block, you can
2201 also use regular Lisp @code{return} or @code{return-from} to
2202 break out of the loop.)
2205 The following sections give some examples of the Loop Macro in
2206 action, and describe the particular loop clauses in great detail.
2207 Consult the second edition of Steele's @dfn{Common Lisp, the Language},
2208 for additional discussion and examples of the @code{loop} macro.
2210 @node Loop Examples, For Clauses, Loop Basics, Loop Facility
2211 @subsection Loop Examples
2214 Before listing the full set of clauses that are allowed, let's
2215 look at a few example loops just to get a feel for the @code{loop}
2219 (loop for buf in (buffer-list)
2220 collect (buffer-file-name buf))
2224 This loop iterates over all Emacs buffers, using the list
2225 returned by @code{buffer-list}. For each buffer @code{buf},
2226 it calls @code{buffer-file-name} and collects the results into
2227 a list, which is then returned from the @code{loop} construct.
2228 The result is a list of the file names of all the buffers in
2229 Emacs' memory. The words @code{for}, @code{in}, and @code{collect}
2230 are reserved words in the @code{loop} language.
2233 (loop repeat 20 do (insert "Yowsa\n"))
2237 This loop inserts the phrase ``Yowsa'' twenty times in the
2241 (loop until (eobp) do (munch-line) (forward-line 1))
2245 This loop calls @code{munch-line} on every line until the end
2246 of the buffer. If point is already at the end of the buffer,
2247 the loop exits immediately.
2250 (loop do (munch-line) until (eobp) do (forward-line 1))
2254 This loop is similar to the above one, except that @code{munch-line}
2255 is always called at least once.
2258 (loop for x from 1 to 100
2261 finally return (list x (= y 729)))
2265 This more complicated loop searches for a number @code{x} whose
2266 square is 729. For safety's sake it only examines @code{x}
2267 values up to 100; dropping the phrase @samp{to 100} would
2268 cause the loop to count upwards with no limit. The second
2269 @code{for} clause defines @code{y} to be the square of @code{x}
2270 within the loop; the expression after the @code{=} sign is
2271 reevaluated each time through the loop. The @code{until}
2272 clause gives a condition for terminating the loop, and the
2273 @code{finally} clause says what to do when the loop finishes.
2274 (This particular example was written less concisely than it
2275 could have been, just for the sake of illustration.)
2277 Note that even though this loop contains three clauses (two
2278 @code{for}s and an @code{until}) that would have been enough to
2279 define loops all by themselves, it still creates a single loop
2280 rather than some sort of triple-nested loop. You must explicitly
2281 nest your @code{loop} constructs if you want nested loops.
2283 @node For Clauses, Iteration Clauses, Loop Examples, Loop Facility
2284 @subsection For Clauses
2287 Most loops are governed by one or more @code{for} clauses.
2288 A @code{for} clause simultaneously describes variables to be
2289 bound, how those variables are to be stepped during the loop,
2290 and usually an end condition based on those variables.
2292 The word @code{as} is a synonym for the word @code{for}. This
2293 word is followed by a variable name, then a word like @code{from}
2294 or @code{across} that describes the kind of iteration desired.
2295 In Common Lisp, the phrase @code{being the} sometimes precedes
2296 the type of iteration; in this package both @code{being} and
2297 @code{the} are optional. The word @code{each} is a synonym
2298 for @code{the}, and the word that follows it may be singular
2299 or plural: @samp{for x being the elements of y} or
2300 @samp{for x being each element of y}. Which form you use
2301 is purely a matter of style.
2303 The variable is bound around the loop as if by @code{let}:
2307 (loop for i from 1 to 10 do (do-something-with i))
2313 @item for @var{var} from @var{expr1} to @var{expr2} by @var{expr3}
2314 This type of @code{for} clause creates a counting loop. Each of
2315 the three sub-terms is optional, though there must be at least one
2316 term so that the clause is marked as a counting clause.
2318 The three expressions are the starting value, the ending value, and
2319 the step value, respectively, of the variable. The loop counts
2320 upwards by default (@var{expr3} must be positive), from @var{expr1}
2321 to @var{expr2} inclusively. If you omit the @code{from} term, the
2322 loop counts from zero; if you omit the @code{to} term, the loop
2323 counts forever without stopping (unless stopped by some other
2324 loop clause, of course); if you omit the @code{by} term, the loop
2325 counts in steps of one.
2327 You can replace the word @code{from} with @code{upfrom} or
2328 @code{downfrom} to indicate the direction of the loop. Likewise,
2329 you can replace @code{to} with @code{upto} or @code{downto}.
2330 For example, @samp{for x from 5 downto 1} executes five times
2331 with @code{x} taking on the integers from 5 down to 1 in turn.
2332 Also, you can replace @code{to} with @code{below} or @code{above},
2333 which are like @code{upto} and @code{downto} respectively except
2334 that they are exclusive rather than inclusive limits:
2337 (loop for x to 10 collect x)
2338 @result{} (0 1 2 3 4 5 6 7 8 9 10)
2339 (loop for x below 10 collect x)
2340 @result{} (0 1 2 3 4 5 6 7 8 9)
2343 The @code{by} value is always positive, even for downward-counting
2344 loops. Some sort of @code{from} value is required for downward
2345 loops; @samp{for x downto 5} is not a valid loop clause all by
2348 @item for @var{var} in @var{list} by @var{function}
2349 This clause iterates @var{var} over all the elements of @var{list},
2350 in turn. If you specify the @code{by} term, then @var{function}
2351 is used to traverse the list instead of @code{cdr}; it must be a
2352 function taking one argument. For example:
2355 (loop for x in '(1 2 3 4 5 6) collect (* x x))
2356 @result{} (1 4 9 16 25 36)
2357 (loop for x in '(1 2 3 4 5 6) by 'cddr collect (* x x))
2361 @item for @var{var} on @var{list} by @var{function}
2362 This clause iterates @var{var} over all the cons cells of @var{list}.
2365 (loop for x on '(1 2 3 4) collect x)
2366 @result{} ((1 2 3 4) (2 3 4) (3 4) (4))
2369 With @code{by}, there is no real reason that the @code{on} expression
2370 must be a list. For example:
2373 (loop for x on first-animal by 'next-animal collect x)
2377 where @code{(next-animal x)} takes an ``animal'' @var{x} and returns
2378 the next in the (assumed) sequence of animals, or @code{nil} if
2379 @var{x} was the last animal in the sequence.
2381 @item for @var{var} in-ref @var{list} by @var{function}
2382 This is like a regular @code{in} clause, but @var{var} becomes
2383 a @code{setf}-able ``reference'' onto the elements of the list
2384 rather than just a temporary variable. For example,
2387 (loop for x in-ref my-list do (incf x))
2391 increments every element of @code{my-list} in place. This clause
2392 is an extension to standard Common Lisp.
2394 @item for @var{var} across @var{array}
2395 This clause iterates @var{var} over all the elements of @var{array},
2396 which may be a vector or a string.
2399 (loop for x across "aeiou"
2400 do (use-vowel (char-to-string x)))
2403 @item for @var{var} across-ref @var{array}
2404 This clause iterates over an array, with @var{var} a @code{setf}-able
2405 reference onto the elements; see @code{in-ref} above.
2407 @item for @var{var} being the elements of @var{sequence}
2408 This clause iterates over the elements of @var{sequence}, which may
2409 be a list, vector, or string. Since the type must be determined
2410 at run-time, this is somewhat less efficient than @code{in} or
2411 @code{across}. The clause may be followed by the additional term
2412 @samp{using (index @var{var2})} to cause @var{var2} to be bound to
2413 the successive indices (starting at 0) of the elements.
2415 This clause type is taken from older versions of the @code{loop} macro,
2416 and is not present in modern Common Lisp. The @samp{using (sequence ...)}
2417 term of the older macros is not supported.
2419 @item for @var{var} being the elements of-ref @var{sequence}
2420 This clause iterates over a sequence, with @var{var} a @code{setf}-able
2421 reference onto the elements; see @code{in-ref} above.
2423 @item for @var{var} being the symbols [of @var{obarray}]
2424 This clause iterates over symbols, either over all interned symbols
2425 or over all symbols in @var{obarray}. The loop is executed with
2426 @var{var} bound to each symbol in turn. The symbols are visited in
2427 an unspecified order.
2432 (loop for sym being the symbols
2434 when (string-match "^map" (symbol-name sym))
2439 returns a list of all the functions whose names begin with @samp{map}.
2441 The Common Lisp words @code{external-symbols} and @code{present-symbols}
2442 are also recognized but are equivalent to @code{symbols} in Emacs Lisp.
2444 Due to a minor implementation restriction, it will not work to have
2445 more than one @code{for} clause iterating over symbols, hash tables,
2446 keymaps, overlays, or intervals in a given @code{loop}. Fortunately,
2447 it would rarely if ever be useful to do so. It @emph{is} valid to mix
2448 one of these types of clauses with other clauses like @code{for ... to}
2451 @item for @var{var} being the hash-keys of @var{hash-table}
2452 @itemx for @var{var} being the hash-values of @var{hash-table}
2453 This clause iterates over the entries in @var{hash-table} with
2454 @var{var} bound to each key, or value. A @samp{using} clause can bind
2455 a second variable to the opposite part.
2458 (loop for k being the hash-keys of h
2459 using (hash-values v)
2461 (message "key %S -> value %S" k v))
2464 @item for @var{var} being the key-codes of @var{keymap}
2465 @itemx for @var{var} being the key-bindings of @var{keymap}
2466 This clause iterates over the entries in @var{keymap}.
2467 The iteration does not enter nested keymaps but does enter inherited
2469 A @code{using} clause can access both the codes and the bindings
2473 (loop for c being the key-codes of (current-local-map)
2474 using (key-bindings b)
2476 (message "key %S -> binding %S" c b))
2480 @item for @var{var} being the key-seqs of @var{keymap}
2481 This clause iterates over all key sequences defined by @var{keymap}
2482 and its nested keymaps, where @var{var} takes on values which are
2483 vectors. The strings or vectors
2484 are reused for each iteration, so you must copy them if you wish to keep
2485 them permanently. You can add a @samp{using (key-bindings ...)}
2486 clause to get the command bindings as well.
2488 @item for @var{var} being the overlays [of @var{buffer}] @dots{}
2489 This clause iterates over the ``overlays'' of a buffer
2490 (the clause @code{extents} is synonymous
2491 with @code{overlays}). If the @code{of} term is omitted, the current
2493 This clause also accepts optional @samp{from @var{pos}} and
2494 @samp{to @var{pos}} terms, limiting the clause to overlays which
2495 overlap the specified region.
2497 @item for @var{var} being the intervals [of @var{buffer}] @dots{}
2498 This clause iterates over all intervals of a buffer with constant
2499 text properties. The variable @var{var} will be bound to conses
2500 of start and end positions, where one start position is always equal
2501 to the previous end position. The clause allows @code{of},
2502 @code{from}, @code{to}, and @code{property} terms, where the latter
2503 term restricts the search to just the specified property. The
2504 @code{of} term may specify either a buffer or a string.
2506 @item for @var{var} being the frames
2507 This clause iterates over all Emacs frames. The clause @code{screens} is
2508 a synonym for @code{frames}. The frames are visited in
2509 @code{next-frame} order starting from @code{selected-frame}.
2511 @item for @var{var} being the windows [of @var{frame}]
2512 This clause iterates over the windows (in the Emacs sense) of
2513 the current frame, or of the specified @var{frame}. It visits windows
2514 in @code{next-window} order starting from @code{selected-window}
2515 (or @code{frame-selected-window} if you specify @var{frame}).
2516 This clause treats the minibuffer window in the same way as
2517 @code{next-window} does. For greater flexibility, consider using
2518 @code{walk-windows} instead.
2520 @item for @var{var} being the buffers
2521 This clause iterates over all buffers in Emacs. It is equivalent
2522 to @samp{for @var{var} in (buffer-list)}.
2524 @item for @var{var} = @var{expr1} then @var{expr2}
2525 This clause does a general iteration. The first time through
2526 the loop, @var{var} will be bound to @var{expr1}. On the second
2527 and successive iterations it will be set by evaluating @var{expr2}
2528 (which may refer to the old value of @var{var}). For example,
2529 these two loops are effectively the same:
2532 (loop for x on my-list by 'cddr do ...)
2533 (loop for x = my-list then (cddr x) while x do ...)
2536 Note that this type of @code{for} clause does not imply any sort
2537 of terminating condition; the above example combines it with a
2538 @code{while} clause to tell when to end the loop.
2540 If you omit the @code{then} term, @var{expr1} is used both for
2541 the initial setting and for successive settings:
2544 (loop for x = (random) when (> x 0) return x)
2548 This loop keeps taking random numbers from the @code{(random)}
2549 function until it gets a positive one, which it then returns.
2552 If you include several @code{for} clauses in a row, they are
2553 treated sequentially (as if by @code{let*} and @code{setq}).
2554 You can instead use the word @code{and} to link the clauses,
2555 in which case they are processed in parallel (as if by @code{let}
2559 (loop for x below 5 for y = nil then x collect (list x y))
2560 @result{} ((0 nil) (1 1) (2 2) (3 3) (4 4))
2561 (loop for x below 5 and y = nil then x collect (list x y))
2562 @result{} ((0 nil) (1 0) (2 1) (3 2) (4 3))
2566 In the first loop, @code{y} is set based on the value of @code{x}
2567 that was just set by the previous clause; in the second loop,
2568 @code{x} and @code{y} are set simultaneously so @code{y} is set
2569 based on the value of @code{x} left over from the previous time
2572 Another feature of the @code{loop} macro is @dfn{destructuring},
2573 similar in concept to the destructuring provided by @code{defmacro}.
2574 The @var{var} part of any @code{for} clause can be given as a list
2575 of variables instead of a single variable. The values produced
2576 during loop execution must be lists; the values in the lists are
2577 stored in the corresponding variables.
2580 (loop for (x y) in '((2 3) (4 5) (6 7)) collect (+ x y))
2584 In loop destructuring, if there are more values than variables
2585 the trailing values are ignored, and if there are more variables
2586 than values the trailing variables get the value @code{nil}.
2587 If @code{nil} is used as a variable name, the corresponding
2588 values are ignored. Destructuring may be nested, and dotted
2589 lists of variables like @code{(x . y)} are allowed.
2591 @node Iteration Clauses, Accumulation Clauses, For Clauses, Loop Facility
2592 @subsection Iteration Clauses
2595 Aside from @code{for} clauses, there are several other loop clauses
2596 that control the way the loop operates. They might be used by
2597 themselves, or in conjunction with one or more @code{for} clauses.
2600 @item repeat @var{integer}
2601 This clause simply counts up to the specified number using an
2602 internal temporary variable. The loops
2605 (loop repeat (1+ n) do ...)
2606 (loop for temp to n do ...)
2610 are identical except that the second one forces you to choose
2611 a name for a variable you aren't actually going to use.
2613 @item while @var{condition}
2614 This clause stops the loop when the specified condition (any Lisp
2615 expression) becomes @code{nil}. For example, the following two
2616 loops are equivalent, except for the implicit @code{nil} block
2617 that surrounds the second one:
2620 (while @var{cond} @var{forms}@dots{})
2621 (loop while @var{cond} do @var{forms}@dots{})
2624 @item until @var{condition}
2625 This clause stops the loop when the specified condition is true,
2626 i.e., non-@code{nil}.
2628 @item always @var{condition}
2629 This clause stops the loop when the specified condition is @code{nil}.
2630 Unlike @code{while}, it stops the loop using @code{return nil} so that
2631 the @code{finally} clauses are not executed. If all the conditions
2632 were non-@code{nil}, the loop returns @code{t}:
2635 (if (loop for size in size-list always (> size 10))
2640 @item never @var{condition}
2641 This clause is like @code{always}, except that the loop returns
2642 @code{t} if any conditions were false, or @code{nil} otherwise.
2644 @item thereis @var{condition}
2645 This clause stops the loop when the specified form is non-@code{nil};
2646 in this case, it returns that non-@code{nil} value. If all the
2647 values were @code{nil}, the loop returns @code{nil}.
2650 @node Accumulation Clauses, Other Clauses, Iteration Clauses, Loop Facility
2651 @subsection Accumulation Clauses
2654 These clauses cause the loop to accumulate information about the
2655 specified Lisp @var{form}. The accumulated result is returned
2656 from the loop unless overridden, say, by a @code{return} clause.
2659 @item collect @var{form}
2660 This clause collects the values of @var{form} into a list. Several
2661 examples of @code{collect} appear elsewhere in this manual.
2663 The word @code{collecting} is a synonym for @code{collect}, and
2664 likewise for the other accumulation clauses.
2666 @item append @var{form}
2667 This clause collects lists of values into a result list using
2670 @item nconc @var{form}
2671 This clause collects lists of values into a result list by
2672 destructively modifying the lists rather than copying them.
2674 @item concat @var{form}
2675 This clause concatenates the values of the specified @var{form}
2676 into a string. (It and the following clause are extensions to
2677 standard Common Lisp.)
2679 @item vconcat @var{form}
2680 This clause concatenates the values of the specified @var{form}
2683 @item count @var{form}
2684 This clause counts the number of times the specified @var{form}
2685 evaluates to a non-@code{nil} value.
2687 @item sum @var{form}
2688 This clause accumulates the sum of the values of the specified
2689 @var{form}, which must evaluate to a number.
2691 @item maximize @var{form}
2692 This clause accumulates the maximum value of the specified @var{form},
2693 which must evaluate to a number. The return value is undefined if
2694 @code{maximize} is executed zero times.
2696 @item minimize @var{form}
2697 This clause accumulates the minimum value of the specified @var{form}.
2700 Accumulation clauses can be followed by @samp{into @var{var}} to
2701 cause the data to be collected into variable @var{var} (which is
2702 automatically @code{let}-bound during the loop) rather than an
2703 unnamed temporary variable. Also, @code{into} accumulations do
2704 not automatically imply a return value. The loop must use some
2705 explicit mechanism, such as @code{finally return}, to return
2706 the accumulated result.
2708 It is valid for several accumulation clauses of the same type to
2709 accumulate into the same place. From Steele:
2712 (loop for name in '(fred sue alice joe june)
2713 for kids in '((bob ken) () () (kris sunshine) ())
2716 @result{} (fred bob ken sue alice joe kris sunshine june)
2719 @node Other Clauses, , Accumulation Clauses, Loop Facility
2720 @subsection Other Clauses
2723 This section describes the remaining loop clauses.
2726 @item with @var{var} = @var{value}
2727 This clause binds a variable to a value around the loop, but
2728 otherwise leaves the variable alone during the loop. The following
2729 loops are basically equivalent:
2732 (loop with x = 17 do ...)
2733 (let ((x 17)) (loop do ...))
2734 (loop for x = 17 then x do ...)
2737 Naturally, the variable @var{var} might be used for some purpose
2738 in the rest of the loop. For example:
2741 (loop for x in my-list with res = nil do (push x res)
2745 This loop inserts the elements of @code{my-list} at the front of
2746 a new list being accumulated in @code{res}, then returns the
2747 list @code{res} at the end of the loop. The effect is similar
2748 to that of a @code{collect} clause, but the list gets reversed
2749 by virtue of the fact that elements are being pushed onto the
2750 front of @code{res} rather than the end.
2752 If you omit the @code{=} term, the variable is initialized to
2753 @code{nil}. (Thus the @samp{= nil} in the above example is
2756 Bindings made by @code{with} are sequential by default, as if
2757 by @code{let*}. Just like @code{for} clauses, @code{with} clauses
2758 can be linked with @code{and} to cause the bindings to be made by
2761 @item if @var{condition} @var{clause}
2762 This clause executes the following loop clause only if the specified
2763 condition is true. The following @var{clause} should be an accumulation,
2764 @code{do}, @code{return}, @code{if}, or @code{unless} clause.
2765 Several clauses may be linked by separating them with @code{and}.
2766 These clauses may be followed by @code{else} and a clause or clauses
2767 to execute if the condition was false. The whole construct may
2768 optionally be followed by the word @code{end} (which may be used to
2769 disambiguate an @code{else} or @code{and} in a nested @code{if}).
2771 The actual non-@code{nil} value of the condition form is available
2772 by the name @code{it} in the ``then'' part. For example:
2775 (setq funny-numbers '(6 13 -1))
2777 (loop for x below 10
2780 and if (memq x funny-numbers) return (cdr it) end
2782 collect x into evens
2783 finally return (vector odds evens))
2784 @result{} [(1 3 5 7 9) (0 2 4 6 8)]
2785 (setq funny-numbers '(6 7 13 -1))
2786 @result{} (6 7 13 -1)
2787 (loop <@r{same thing again}>)
2791 Note the use of @code{and} to put two clauses into the ``then''
2792 part, one of which is itself an @code{if} clause. Note also that
2793 @code{end}, while normally optional, was necessary here to make
2794 it clear that the @code{else} refers to the outermost @code{if}
2795 clause. In the first case, the loop returns a vector of lists
2796 of the odd and even values of @var{x}. In the second case, the
2797 odd number 7 is one of the @code{funny-numbers} so the loop
2798 returns early; the actual returned value is based on the result
2799 of the @code{memq} call.
2801 @item when @var{condition} @var{clause}
2802 This clause is just a synonym for @code{if}.
2804 @item unless @var{condition} @var{clause}
2805 The @code{unless} clause is just like @code{if} except that the
2806 sense of the condition is reversed.
2808 @item named @var{name}
2809 This clause gives a name other than @code{nil} to the implicit
2810 block surrounding the loop. The @var{name} is the symbol to be
2811 used as the block name.
2813 @item initially [do] @var{forms}...
2814 This keyword introduces one or more Lisp forms which will be
2815 executed before the loop itself begins (but after any variables
2816 requested by @code{for} or @code{with} have been bound to their
2817 initial values). @code{initially} clauses can appear anywhere;
2818 if there are several, they are executed in the order they appear
2819 in the loop. The keyword @code{do} is optional.
2821 @item finally [do] @var{forms}...
2822 This introduces Lisp forms which will be executed after the loop
2823 finishes (say, on request of a @code{for} or @code{while}).
2824 @code{initially} and @code{finally} clauses may appear anywhere
2825 in the loop construct, but they are executed (in the specified
2826 order) at the beginning or end, respectively, of the loop.
2828 @item finally return @var{form}
2829 This says that @var{form} should be executed after the loop
2830 is done to obtain a return value. (Without this, or some other
2831 clause like @code{collect} or @code{return}, the loop will simply
2832 return @code{nil}.) Variables bound by @code{for}, @code{with},
2833 or @code{into} will still contain their final values when @var{form}
2836 @item do @var{forms}...
2837 The word @code{do} may be followed by any number of Lisp expressions
2838 which are executed as an implicit @code{progn} in the body of the
2839 loop. Many of the examples in this section illustrate the use of
2842 @item return @var{form}
2843 This clause causes the loop to return immediately. The following
2844 Lisp form is evaluated to give the return value of the @code{loop}
2845 form. The @code{finally} clauses, if any, are not executed.
2846 Of course, @code{return} is generally used inside an @code{if} or
2847 @code{unless}, as its use in a top-level loop clause would mean
2848 the loop would never get to ``loop'' more than once.
2850 The clause @samp{return @var{form}} is equivalent to
2851 @samp{do (return @var{form})} (or @code{return-from} if the loop
2852 was named). The @code{return} clause is implemented a bit more
2853 efficiently, though.
2856 While there is no high-level way to add user extensions to @code{loop}
2857 (comparable to @code{defsetf} for @code{setf}, say), this package
2858 does offer two properties called @code{cl-loop-handler} and
2859 @code{cl-loop-for-handler} which are functions to be called when
2860 a given symbol is encountered as a top-level loop clause or
2861 @code{for} clause, respectively. Consult the source code in
2862 file @file{cl-macs.el} for details.
2864 This package's @code{loop} macro is compatible with that of Common
2865 Lisp, except that a few features are not implemented: @code{loop-finish}
2866 and data-type specifiers. Naturally, the @code{for} clauses which
2867 iterate over keymaps, overlays, intervals, frames, windows, and
2868 buffers are Emacs-specific extensions.
2870 @node Multiple Values, , Loop Facility, Control Structure
2871 @section Multiple Values
2874 Common Lisp functions can return zero or more results. Emacs Lisp
2875 functions, by contrast, always return exactly one result. This
2876 package makes no attempt to emulate Common Lisp multiple return
2877 values; Emacs versions of Common Lisp functions that return more
2878 than one value either return just the first value (as in
2879 @code{compiler-macroexpand}) or return a list of values (as in
2880 @code{get-setf-method}). This package @emph{does} define placeholders
2881 for the Common Lisp functions that work with multiple values, but
2882 in Emacs Lisp these functions simply operate on lists instead.
2883 The @code{values} form, for example, is a synonym for @code{list}
2886 @defspec multiple-value-bind (var@dots{}) values-form forms@dots{}
2887 This form evaluates @var{values-form}, which must return a list of
2888 values. It then binds the @var{var}s to these respective values,
2889 as if by @code{let}, and then executes the body @var{forms}.
2890 If there are more @var{var}s than values, the extra @var{var}s
2891 are bound to @code{nil}. If there are fewer @var{var}s than
2892 values, the excess values are ignored.
2895 @defspec multiple-value-setq (var@dots{}) form
2896 This form evaluates @var{form}, which must return a list of values.
2897 It then sets the @var{var}s to these respective values, as if by
2898 @code{setq}. Extra @var{var}s or values are treated the same as
2899 in @code{multiple-value-bind}.
2902 The older Quiroz package attempted a more faithful (but still
2903 imperfect) emulation of Common Lisp multiple values. The old
2904 method ``usually'' simulated true multiple values quite well,
2905 but under certain circumstances would leave spurious return
2906 values in memory where a later, unrelated @code{multiple-value-bind}
2907 form would see them.
2909 Since a perfect emulation is not feasible in Emacs Lisp, this
2910 package opts to keep it as simple and predictable as possible.
2912 @node Macros, Declarations, Control Structure, Top
2916 This package implements the various Common Lisp features of
2917 @code{defmacro}, such as destructuring, @code{&environment},
2918 and @code{&body}. Top-level @code{&whole} is not implemented
2919 for @code{defmacro} due to technical difficulties.
2920 @xref{Argument Lists}.
2922 Destructuring is made available to the user by way of the
2925 @defspec destructuring-bind arglist expr forms@dots{}
2926 This macro expands to code which executes @var{forms}, with
2927 the variables in @var{arglist} bound to the list of values
2928 returned by @var{expr}. The @var{arglist} can include all
2929 the features allowed for @code{defmacro} argument lists,
2930 including destructuring. (The @code{&environment} keyword
2931 is not allowed.) The macro expansion will signal an error
2932 if @var{expr} returns a list of the wrong number of arguments
2933 or with incorrect keyword arguments.
2936 This package also includes the Common Lisp @code{define-compiler-macro}
2937 facility, which allows you to define compile-time expansions and
2938 optimizations for your functions.
2940 @defspec define-compiler-macro name arglist forms@dots{}
2941 This form is similar to @code{defmacro}, except that it only expands
2942 calls to @var{name} at compile-time; calls processed by the Lisp
2943 interpreter are not expanded, nor are they expanded by the
2944 @code{macroexpand} function.
2946 The argument list may begin with a @code{&whole} keyword and a
2947 variable. This variable is bound to the macro-call form itself,
2948 i.e., to a list of the form @samp{(@var{name} @var{args}@dots{})}.
2949 If the macro expander returns this form unchanged, then the
2950 compiler treats it as a normal function call. This allows
2951 compiler macros to work as optimizers for special cases of a
2952 function, leaving complicated cases alone.
2954 For example, here is a simplified version of a definition that
2955 appears as a standard part of this package:
2958 (define-compiler-macro member* (&whole form a list &rest keys)
2959 (if (and (null keys)
2960 (eq (car-safe a) 'quote)
2961 (not (floatp-safe (cadr a))))
2967 This definition causes @code{(member* @var{a} @var{list})} to change
2968 to a call to the faster @code{memq} in the common case where @var{a}
2969 is a non-floating-point constant; if @var{a} is anything else, or
2970 if there are any keyword arguments in the call, then the original
2971 @code{member*} call is left intact. (The actual compiler macro
2972 for @code{member*} optimizes a number of other cases, including
2973 common @code{:test} predicates.)
2976 @defun compiler-macroexpand form
2977 This function is analogous to @code{macroexpand}, except that it
2978 expands compiler macros rather than regular macros. It returns
2979 @var{form} unchanged if it is not a call to a function for which
2980 a compiler macro has been defined, or if that compiler macro
2981 decided to punt by returning its @code{&whole} argument. Like
2982 @code{macroexpand}, it expands repeatedly until it reaches a form
2983 for which no further expansion is possible.
2986 @xref{Macro Bindings}, for descriptions of the @code{macrolet}
2987 and @code{symbol-macrolet} forms for making ``local'' macro
2990 @node Declarations, Symbols, Macros, Top
2991 @chapter Declarations
2994 Common Lisp includes a complex and powerful ``declaration''
2995 mechanism that allows you to give the compiler special hints
2996 about the types of data that will be stored in particular variables,
2997 and about the ways those variables and functions will be used. This
2998 package defines versions of all the Common Lisp declaration forms:
2999 @code{declare}, @code{locally}, @code{proclaim}, @code{declaim},
3002 Most of the Common Lisp declarations are not currently useful in
3003 Emacs Lisp, as the byte-code system provides little opportunity
3004 to benefit from type information, and @code{special} declarations
3005 are redundant in a fully dynamically-scoped Lisp. A few
3006 declarations are meaningful when the optimizing byte
3007 compiler is being used, however. Under the earlier non-optimizing
3008 compiler, these declarations will effectively be ignored.
3010 @defun proclaim decl-spec
3011 This function records a ``global'' declaration specified by
3012 @var{decl-spec}. Since @code{proclaim} is a function, @var{decl-spec}
3013 is evaluated and thus should normally be quoted.
3016 @defspec declaim decl-specs@dots{}
3017 This macro is like @code{proclaim}, except that it takes any number
3018 of @var{decl-spec} arguments, and the arguments are unevaluated and
3019 unquoted. The @code{declaim} macro also puts an @code{(eval-when
3020 (compile load eval) ...)} around the declarations so that they will
3021 be registered at compile-time as well as at run-time. (This is vital,
3022 since normally the declarations are meant to influence the way the
3023 compiler treats the rest of the file that contains the @code{declaim}
3027 @defspec declare decl-specs@dots{}
3028 This macro is used to make declarations within functions and other
3029 code. Common Lisp allows declarations in various locations, generally
3030 at the beginning of any of the many ``implicit @code{progn}s''
3031 throughout Lisp syntax, such as function bodies, @code{let} bodies,
3032 etc. Currently the only declaration understood by @code{declare}
3036 @defspec locally declarations@dots{} forms@dots{}
3037 In this package, @code{locally} is no different from @code{progn}.
3040 @defspec the type form
3041 Type information provided by @code{the} is ignored in this package;
3042 in other words, @code{(the @var{type} @var{form})} is equivalent
3043 to @var{form}. Future versions of the optimizing byte-compiler may
3044 make use of this information.
3046 For example, @code{mapcar} can map over both lists and arrays. It is
3047 hard for the compiler to expand @code{mapcar} into an in-line loop
3048 unless it knows whether the sequence will be a list or an array ahead
3049 of time. With @code{(mapcar 'car (the vector foo))}, a future
3050 compiler would have enough information to expand the loop in-line.
3051 For now, Emacs Lisp will treat the above code as exactly equivalent
3052 to @code{(mapcar 'car foo)}.
3055 Each @var{decl-spec} in a @code{proclaim}, @code{declaim}, or
3056 @code{declare} should be a list beginning with a symbol that says
3057 what kind of declaration it is. This package currently understands
3058 @code{special}, @code{inline}, @code{notinline}, @code{optimize},
3059 and @code{warn} declarations. (The @code{warn} declaration is an
3060 extension of standard Common Lisp.) Other Common Lisp declarations,
3061 such as @code{type} and @code{ftype}, are silently ignored.
3065 Since all variables in Emacs Lisp are ``special'' (in the Common
3066 Lisp sense), @code{special} declarations are only advisory. They
3067 simply tell the optimizing byte compiler that the specified
3068 variables are intentionally being referred to without being
3069 bound in the body of the function. The compiler normally emits
3070 warnings for such references, since they could be typographical
3071 errors for references to local variables.
3073 The declaration @code{(declare (special @var{var1} @var{var2}))} is
3074 equivalent to @code{(defvar @var{var1}) (defvar @var{var2})} in the
3075 optimizing compiler, or to nothing at all in older compilers (which
3076 do not warn for non-local references).
3078 In top-level contexts, it is generally better to write
3079 @code{(defvar @var{var})} than @code{(declaim (special @var{var}))},
3080 since @code{defvar} makes your intentions clearer. But the older
3081 byte compilers can not handle @code{defvar}s appearing inside of
3082 functions, while @code{(declare (special @var{var}))} takes care
3083 to work correctly with all compilers.
3086 The @code{inline} @var{decl-spec} lists one or more functions
3087 whose bodies should be expanded ``in-line'' into calling functions
3088 whenever the compiler is able to arrange for it. For example,
3089 the Common Lisp function @code{cadr} is declared @code{inline}
3090 by this package so that the form @code{(cadr @var{x})} will
3091 expand directly into @code{(car (cdr @var{x}))} when it is called
3092 in user functions, for a savings of one (relatively expensive)
3095 The following declarations are all equivalent. Note that the
3096 @code{defsubst} form is a convenient way to define a function
3097 and declare it inline all at once.
3100 (declaim (inline foo bar))
3101 (eval-when (compile load eval) (proclaim '(inline foo bar)))
3102 (defsubst foo (...) ...) ; instead of defun
3105 @strong{Please note:} this declaration remains in effect after the
3106 containing source file is done. It is correct to use it to
3107 request that a function you have defined should be inlined,
3108 but it is impolite to use it to request inlining of an external
3111 In Common Lisp, it is possible to use @code{(declare (inline @dots{}))}
3112 before a particular call to a function to cause just that call to
3113 be inlined; the current byte compilers provide no way to implement
3114 this, so @code{(declare (inline @dots{}))} is currently ignored by
3118 The @code{notinline} declaration lists functions which should
3119 not be inlined after all; it cancels a previous @code{inline}
3123 This declaration controls how much optimization is performed by
3124 the compiler. Naturally, it is ignored by the earlier non-optimizing
3127 The word @code{optimize} is followed by any number of lists like
3128 @code{(speed 3)} or @code{(safety 2)}. Common Lisp defines several
3129 optimization ``qualities''; this package ignores all but @code{speed}
3130 and @code{safety}. The value of a quality should be an integer from
3131 0 to 3, with 0 meaning ``unimportant'' and 3 meaning ``very important.''
3132 The default level for both qualities is 1.
3134 In this package, with the optimizing compiler, the
3135 @code{speed} quality is tied to the @code{byte-compile-optimize}
3136 flag, which is set to @code{nil} for @code{(speed 0)} and to
3137 @code{t} for higher settings; and the @code{safety} quality is
3138 tied to the @code{byte-compile-delete-errors} flag, which is
3139 set to @code{t} for @code{(safety 3)} and to @code{nil} for all
3140 lower settings. (The latter flag controls whether the compiler
3141 is allowed to optimize out code whose only side-effect could
3142 be to signal an error, e.g., rewriting @code{(progn foo bar)} to
3143 @code{bar} when it is not known whether @code{foo} will be bound
3146 Note that even compiling with @code{(safety 0)}, the Emacs
3147 byte-code system provides sufficient checking to prevent real
3148 harm from being done. For example, barring serious bugs in
3149 Emacs itself, Emacs will not crash with a segmentation fault
3150 just because of an error in a fully-optimized Lisp program.
3152 The @code{optimize} declaration is normally used in a top-level
3153 @code{proclaim} or @code{declaim} in a file; Common Lisp allows
3154 it to be used with @code{declare} to set the level of optimization
3155 locally for a given form, but this will not work correctly with the
3156 current version of the optimizing compiler. (The @code{declare}
3157 will set the new optimization level, but that level will not
3158 automatically be unset after the enclosing form is done.)
3161 This declaration controls what sorts of warnings are generated
3162 by the byte compiler. Again, only the optimizing compiler
3163 generates warnings. The word @code{warn} is followed by any
3164 number of ``warning qualities,'' similar in form to optimization
3165 qualities. The currently supported warning types are
3166 @code{redefine}, @code{callargs}, @code{unresolved}, and
3167 @code{free-vars}; in the current system, a value of 0 will
3168 disable these warnings and any higher value will enable them.
3169 See the documentation for the optimizing byte compiler for details.
3172 @node Symbols, Numbers, Declarations, Top
3176 This package defines several symbol-related features that were
3177 missing from Emacs Lisp.
3180 * Property Lists:: `get*', `remprop', `getf', `remf'
3181 * Creating Symbols:: `gensym', `gentemp'
3184 @node Property Lists, Creating Symbols, Symbols, Symbols
3185 @section Property Lists
3188 These functions augment the standard Emacs Lisp functions @code{get}
3189 and @code{put} for operating on properties attached to symbols.
3190 There are also functions for working with property lists as
3191 first-class data structures not attached to particular symbols.
3193 @defun get* symbol property &optional default
3194 This function is like @code{get}, except that if the property is
3195 not found, the @var{default} argument provides the return value.
3196 (The Emacs Lisp @code{get} function always uses @code{nil} as
3197 the default; this package's @code{get*} is equivalent to Common
3200 The @code{get*} function is @code{setf}-able; when used in this
3201 fashion, the @var{default} argument is allowed but ignored.
3204 @defun remprop symbol property
3205 This function removes the entry for @var{property} from the property
3206 list of @var{symbol}. It returns a true value if the property was
3207 indeed found and removed, or @code{nil} if there was no such property.
3208 (This function was probably omitted from Emacs originally because,
3209 since @code{get} did not allow a @var{default}, it was very difficult
3210 to distinguish between a missing property and a property whose value
3211 was @code{nil}; thus, setting a property to @code{nil} was close
3212 enough to @code{remprop} for most purposes.)
3215 @defun getf place property &optional default
3216 This function scans the list @var{place} as if it were a property
3217 list, i.e., a list of alternating property names and values. If
3218 an even-numbered element of @var{place} is found which is @code{eq}
3219 to @var{property}, the following odd-numbered element is returned.
3220 Otherwise, @var{default} is returned (or @code{nil} if no default
3226 (get sym prop) @equiv{} (getf (symbol-plist sym) prop)
3229 It is valid to use @code{getf} as a @code{setf} place, in which case
3230 its @var{place} argument must itself be a valid @code{setf} place.
3231 The @var{default} argument, if any, is ignored in this context.
3232 The effect is to change (via @code{setcar}) the value cell in the
3233 list that corresponds to @var{property}, or to cons a new property-value
3234 pair onto the list if the property is not yet present.
3237 (put sym prop val) @equiv{} (setf (getf (symbol-plist sym) prop) val)
3240 The @code{get} and @code{get*} functions are also @code{setf}-able.
3241 The fact that @code{default} is ignored can sometimes be useful:
3244 (incf (get* 'foo 'usage-count 0))
3247 Here, symbol @code{foo}'s @code{usage-count} property is incremented
3248 if it exists, or set to 1 (an incremented 0) otherwise.
3250 When not used as a @code{setf} form, @code{getf} is just a regular
3251 function and its @var{place} argument can actually be any Lisp
3255 @defspec remf place property
3256 This macro removes the property-value pair for @var{property} from
3257 the property list stored at @var{place}, which is any @code{setf}-able
3258 place expression. It returns true if the property was found. Note
3259 that if @var{property} happens to be first on the list, this will
3260 effectively do a @code{(setf @var{place} (cddr @var{place}))},
3261 whereas if it occurs later, this simply uses @code{setcdr} to splice
3262 out the property and value cells.
3269 @node Creating Symbols, , Property Lists, Symbols
3270 @section Creating Symbols
3273 These functions create unique symbols, typically for use as
3274 temporary variables.
3276 @defun gensym &optional x
3277 This function creates a new, uninterned symbol (using @code{make-symbol})
3278 with a unique name. (The name of an uninterned symbol is relevant
3279 only if the symbol is printed.) By default, the name is generated
3280 from an increasing sequence of numbers, @samp{G1000}, @samp{G1001},
3281 @samp{G1002}, etc. If the optional argument @var{x} is a string, that
3282 string is used as a prefix instead of @samp{G}. Uninterned symbols
3283 are used in macro expansions for temporary variables, to ensure that
3284 their names will not conflict with ``real'' variables in the user's
3288 @defvar *gensym-counter*
3289 This variable holds the counter used to generate @code{gensym} names.
3290 It is incremented after each use by @code{gensym}. In Common Lisp
3291 this is initialized with 0, but this package initializes it with a
3292 random (time-dependent) value to avoid trouble when two files that
3293 each used @code{gensym} in their compilation are loaded together.
3294 (Uninterned symbols become interned when the compiler writes them
3295 out to a file and the Emacs loader loads them, so their names have to
3296 be treated a bit more carefully than in Common Lisp where uninterned
3297 symbols remain uninterned after loading.)
3300 @defun gentemp &optional x
3301 This function is like @code{gensym}, except that it produces a new
3302 @emph{interned} symbol. If the symbol that is generated already
3303 exists, the function keeps incrementing the counter and trying
3304 again until a new symbol is generated.
3307 The Quiroz @file{cl.el} package also defined a @code{defkeyword}
3308 form for creating self-quoting keyword symbols. This package
3309 automatically creates all keywords that are called for by
3310 @code{&key} argument specifiers, and discourages the use of
3311 keywords as data unrelated to keyword arguments, so the
3312 @code{defkeyword} form has been discontinued.
3318 @node Numbers, Sequences, Symbols, Top
3322 This section defines a few simple Common Lisp operations on numbers
3323 which were left out of Emacs Lisp.
3326 * Predicates on Numbers:: `plusp', `oddp', `floatp-safe', etc.
3327 * Numerical Functions:: `abs', `floor*', etc.
3328 * Random Numbers:: `random*', `make-random-state'
3329 * Implementation Parameters:: `most-positive-float'
3336 @node Predicates on Numbers, Numerical Functions, Numbers, Numbers
3337 @section Predicates on Numbers
3340 These functions return @code{t} if the specified condition is
3341 true of the numerical argument, or @code{nil} otherwise.
3344 This predicate tests whether @var{number} is positive. It is an
3345 error if the argument is not a number.
3348 @defun minusp number
3349 This predicate tests whether @var{number} is negative. It is an
3350 error if the argument is not a number.
3354 This predicate tests whether @var{integer} is odd. It is an
3355 error if the argument is not an integer.
3358 @defun evenp integer
3359 This predicate tests whether @var{integer} is even. It is an
3360 error if the argument is not an integer.
3363 @defun floatp-safe object
3364 This predicate tests whether @var{object} is a floating-point
3365 number. On systems that support floating-point, this is equivalent
3366 to @code{floatp}. On other systems, this always returns @code{nil}.
3373 @node Numerical Functions, Random Numbers, Predicates on Numbers, Numbers
3374 @section Numerical Functions
3377 These functions perform various arithmetic operations on numbers.
3379 @defun gcd &rest integers
3380 This function returns the Greatest Common Divisor of the arguments.
3381 For one argument, it returns the absolute value of that argument.
3382 For zero arguments, it returns zero.
3385 @defun lcm &rest integers
3386 This function returns the Least Common Multiple of the arguments.
3387 For one argument, it returns the absolute value of that argument.
3388 For zero arguments, it returns one.
3391 @defun isqrt integer
3392 This function computes the ``integer square root'' of its integer
3393 argument, i.e., the greatest integer less than or equal to the true
3394 square root of the argument.
3397 @defun floor* number &optional divisor
3398 This function implements the Common Lisp @code{floor} function.
3399 It is called @code{floor*} to avoid name conflicts with the
3400 simpler @code{floor} function built-in to Emacs.
3402 With one argument, @code{floor*} returns a list of two numbers:
3403 The argument rounded down (toward minus infinity) to an integer,
3404 and the ``remainder'' which would have to be added back to the
3405 first return value to yield the argument again. If the argument
3406 is an integer @var{x}, the result is always the list @code{(@var{x} 0)}.
3407 If the argument is a floating-point number, the first
3408 result is a Lisp integer and the second is a Lisp float between
3409 0 (inclusive) and 1 (exclusive).
3411 With two arguments, @code{floor*} divides @var{number} by
3412 @var{divisor}, and returns the floor of the quotient and the
3413 corresponding remainder as a list of two numbers. If
3414 @code{(floor* @var{x} @var{y})} returns @code{(@var{q} @var{r})},
3415 then @code{@var{q}*@var{y} + @var{r} = @var{x}}, with @var{r}
3416 between 0 (inclusive) and @var{r} (exclusive). Also, note
3417 that @code{(floor* @var{x})} is exactly equivalent to
3418 @code{(floor* @var{x} 1)}.
3420 This function is entirely compatible with Common Lisp's @code{floor}
3421 function, except that it returns the two results in a list since
3422 Emacs Lisp does not support multiple-valued functions.
3425 @defun ceiling* number &optional divisor
3426 This function implements the Common Lisp @code{ceiling} function,
3427 which is analogous to @code{floor} except that it rounds the
3428 argument or quotient of the arguments up toward plus infinity.
3429 The remainder will be between 0 and minus @var{r}.
3432 @defun truncate* number &optional divisor
3433 This function implements the Common Lisp @code{truncate} function,
3434 which is analogous to @code{floor} except that it rounds the
3435 argument or quotient of the arguments toward zero. Thus it is
3436 equivalent to @code{floor*} if the argument or quotient is
3437 positive, or to @code{ceiling*} otherwise. The remainder has
3438 the same sign as @var{number}.
3441 @defun round* number &optional divisor
3442 This function implements the Common Lisp @code{round} function,
3443 which is analogous to @code{floor} except that it rounds the
3444 argument or quotient of the arguments to the nearest integer.
3445 In the case of a tie (the argument or quotient is exactly
3446 halfway between two integers), it rounds to the even integer.
3449 @defun mod* number divisor
3450 This function returns the same value as the second return value
3454 @defun rem* number divisor
3455 This function returns the same value as the second return value
3459 These definitions are compatible with those in the Quiroz
3460 @file{cl.el} package, except that this package appends @samp{*}
3461 to certain function names to avoid conflicts with existing
3462 Emacs functions, and that the mechanism for returning
3463 multiple values is different.
3469 @node Random Numbers, Implementation Parameters, Numerical Functions, Numbers
3470 @section Random Numbers
3473 This package also provides an implementation of the Common Lisp
3474 random number generator. It uses its own additive-congruential
3475 algorithm, which is much more likely to give statistically clean
3476 random numbers than the simple generators supplied by many
3479 @defun random* number &optional state
3480 This function returns a random nonnegative number less than
3481 @var{number}, and of the same type (either integer or floating-point).
3482 The @var{state} argument should be a @code{random-state} object
3483 which holds the state of the random number generator. The
3484 function modifies this state object as a side effect. If
3485 @var{state} is omitted, it defaults to the variable
3486 @code{*random-state*}, which contains a pre-initialized
3487 @code{random-state} object.
3490 @defvar *random-state*
3491 This variable contains the system ``default'' @code{random-state}
3492 object, used for calls to @code{random*} that do not specify an
3493 alternative state object. Since any number of programs in the
3494 Emacs process may be accessing @code{*random-state*} in interleaved
3495 fashion, the sequence generated from this variable will be
3496 irreproducible for all intents and purposes.
3499 @defun make-random-state &optional state
3500 This function creates or copies a @code{random-state} object.
3501 If @var{state} is omitted or @code{nil}, it returns a new copy of
3502 @code{*random-state*}. This is a copy in the sense that future
3503 sequences of calls to @code{(random* @var{n})} and
3504 @code{(random* @var{n} @var{s})} (where @var{s} is the new
3505 random-state object) will return identical sequences of random
3508 If @var{state} is a @code{random-state} object, this function
3509 returns a copy of that object. If @var{state} is @code{t}, this
3510 function returns a new @code{random-state} object seeded from the
3511 date and time. As an extension to Common Lisp, @var{state} may also
3512 be an integer in which case the new object is seeded from that
3513 integer; each different integer seed will result in a completely
3514 different sequence of random numbers.
3516 It is valid to print a @code{random-state} object to a buffer or
3517 file and later read it back with @code{read}. If a program wishes
3518 to use a sequence of pseudo-random numbers which can be reproduced
3519 later for debugging, it can call @code{(make-random-state t)} to
3520 get a new sequence, then print this sequence to a file. When the
3521 program is later rerun, it can read the original run's random-state
3525 @defun random-state-p object
3526 This predicate returns @code{t} if @var{object} is a
3527 @code{random-state} object, or @code{nil} otherwise.
3530 @node Implementation Parameters, , Random Numbers, Numbers
3531 @section Implementation Parameters
3534 This package defines several useful constants having to with numbers.
3536 The following parameters have to do with floating-point numbers.
3537 This package determines their values by exercising the computer's
3538 floating-point arithmetic in various ways. Because this operation
3539 might be slow, the code for initializing them is kept in a separate
3540 function that must be called before the parameters can be used.
3542 @defun cl-float-limits
3543 This function makes sure that the Common Lisp floating-point parameters
3544 like @code{most-positive-float} have been initialized. Until it is
3545 called, these parameters will be @code{nil}. If this version of Emacs
3546 does not support floats, the parameters will remain @code{nil}. If the
3547 parameters have already been initialized, the function returns
3550 The algorithm makes assumptions that will be valid for most modern
3551 machines, but will fail if the machine's arithmetic is extremely
3552 unusual, e.g., decimal.
3555 Since true Common Lisp supports up to four different floating-point
3556 precisions, it has families of constants like
3557 @code{most-positive-single-float}, @code{most-positive-double-float},
3558 @code{most-positive-long-float}, and so on. Emacs has only one
3559 floating-point precision, so this package omits the precision word
3560 from the constants' names.
3562 @defvar most-positive-float
3563 This constant equals the largest value a Lisp float can hold.
3564 For those systems whose arithmetic supports infinities, this is
3565 the largest @emph{finite} value. For IEEE machines, the value
3566 is approximately @code{1.79e+308}.
3569 @defvar most-negative-float
3570 This constant equals the most-negative value a Lisp float can hold.
3571 (It is assumed to be equal to @code{(- most-positive-float)}.)
3574 @defvar least-positive-float
3575 This constant equals the smallest Lisp float value greater than zero.
3576 For IEEE machines, it is about @code{4.94e-324} if denormals are
3577 supported or @code{2.22e-308} if not.
3580 @defvar least-positive-normalized-float
3581 This constant equals the smallest @emph{normalized} Lisp float greater
3582 than zero, i.e., the smallest value for which IEEE denormalization
3583 will not result in a loss of precision. For IEEE machines, this
3584 value is about @code{2.22e-308}. For machines that do not support
3585 the concept of denormalization and gradual underflow, this constant
3586 will always equal @code{least-positive-float}.
3589 @defvar least-negative-float
3590 This constant is the negative counterpart of @code{least-positive-float}.
3593 @defvar least-negative-normalized-float
3594 This constant is the negative counterpart of
3595 @code{least-positive-normalized-float}.
3598 @defvar float-epsilon
3599 This constant is the smallest positive Lisp float that can be added
3600 to 1.0 to produce a distinct value. Adding a smaller number to 1.0
3601 will yield 1.0 again due to roundoff. For IEEE machines, epsilon
3602 is about @code{2.22e-16}.
3605 @defvar float-negative-epsilon
3606 This is the smallest positive value that can be subtracted from
3607 1.0 to produce a distinct value. For IEEE machines, it is about
3615 @node Sequences, Lists, Numbers, Top
3619 Common Lisp defines a number of functions that operate on
3620 @dfn{sequences}, which are either lists, strings, or vectors.
3621 Emacs Lisp includes a few of these, notably @code{elt} and
3622 @code{length}; this package defines most of the rest.
3625 * Sequence Basics:: Arguments shared by all sequence functions
3626 * Mapping over Sequences:: `mapcar*', `mapcan', `map', `every', etc.
3627 * Sequence Functions:: `subseq', `remove*', `substitute', etc.
3628 * Searching Sequences:: `find', `position', `count', `search', etc.
3629 * Sorting Sequences:: `sort*', `stable-sort', `merge'
3632 @node Sequence Basics, Mapping over Sequences, Sequences, Sequences
3633 @section Sequence Basics
3636 Many of the sequence functions take keyword arguments; @pxref{Argument
3637 Lists}. All keyword arguments are optional and, if specified,
3638 may appear in any order.
3640 The @code{:key} argument should be passed either @code{nil}, or a
3641 function of one argument. This key function is used as a filter
3642 through which the elements of the sequence are seen; for example,
3643 @code{(find x y :key 'car)} is similar to @code{(assoc* x y)}:
3644 It searches for an element of the list whose @code{car} equals
3645 @code{x}, rather than for an element which equals @code{x} itself.
3646 If @code{:key} is omitted or @code{nil}, the filter is effectively
3647 the identity function.
3649 The @code{:test} and @code{:test-not} arguments should be either
3650 @code{nil}, or functions of two arguments. The test function is
3651 used to compare two sequence elements, or to compare a search value
3652 with sequence elements. (The two values are passed to the test
3653 function in the same order as the original sequence function
3654 arguments from which they are derived, or, if they both come from
3655 the same sequence, in the same order as they appear in that sequence.)
3656 The @code{:test} argument specifies a function which must return
3657 true (non-@code{nil}) to indicate a match; instead, you may use
3658 @code{:test-not} to give a function which returns @emph{false} to
3659 indicate a match. The default test function is @code{eql}.
3661 Many functions which take @var{item} and @code{:test} or @code{:test-not}
3662 arguments also come in @code{-if} and @code{-if-not} varieties,
3663 where a @var{predicate} function is passed instead of @var{item},
3664 and sequence elements match if the predicate returns true on them
3665 (or false in the case of @code{-if-not}). For example:
3668 (remove* 0 seq :test '=) @equiv{} (remove-if 'zerop seq)
3672 to remove all zeros from sequence @code{seq}.
3674 Some operations can work on a subsequence of the argument sequence;
3675 these function take @code{:start} and @code{:end} arguments which
3676 default to zero and the length of the sequence, respectively.
3677 Only elements between @var{start} (inclusive) and @var{end}
3678 (exclusive) are affected by the operation. The @var{end} argument
3679 may be passed @code{nil} to signify the length of the sequence;
3680 otherwise, both @var{start} and @var{end} must be integers, with
3681 @code{0 <= @var{start} <= @var{end} <= (length @var{seq})}.
3682 If the function takes two sequence arguments, the limits are
3683 defined by keywords @code{:start1} and @code{:end1} for the first,
3684 and @code{:start2} and @code{:end2} for the second.
3686 A few functions accept a @code{:from-end} argument, which, if
3687 non-@code{nil}, causes the operation to go from right-to-left
3688 through the sequence instead of left-to-right, and a @code{:count}
3689 argument, which specifies an integer maximum number of elements
3690 to be removed or otherwise processed.
3692 The sequence functions make no guarantees about the order in
3693 which the @code{:test}, @code{:test-not}, and @code{:key} functions
3694 are called on various elements. Therefore, it is a bad idea to depend
3695 on side effects of these functions. For example, @code{:from-end}
3696 may cause the sequence to be scanned actually in reverse, or it may
3697 be scanned forwards but computing a result ``as if'' it were scanned
3698 backwards. (Some functions, like @code{mapcar*} and @code{every},
3699 @emph{do} specify exactly the order in which the function is called
3700 so side effects are perfectly acceptable in those cases.)
3702 Strings may contain ``text properties'' as well
3703 as character data. Except as noted, it is undefined whether or
3704 not text properties are preserved by sequence functions. For
3705 example, @code{(remove* ?A @var{str})} may or may not preserve
3706 the properties of the characters copied from @var{str} into the
3709 @node Mapping over Sequences, Sequence Functions, Sequence Basics, Sequences
3710 @section Mapping over Sequences
3713 These functions ``map'' the function you specify over the elements
3714 of lists or arrays. They are all variations on the theme of the
3715 built-in function @code{mapcar}.
3717 @defun mapcar* function seq &rest more-seqs
3718 This function calls @var{function} on successive parallel sets of
3719 elements from its argument sequences. Given a single @var{seq}
3720 argument it is equivalent to @code{mapcar}; given @var{n} sequences,
3721 it calls the function with the first elements of each of the sequences
3722 as the @var{n} arguments to yield the first element of the result
3723 list, then with the second elements, and so on. The mapping stops as
3724 soon as the shortest sequence runs out. The argument sequences may
3725 be any mixture of lists, strings, and vectors; the return sequence
3728 Common Lisp's @code{mapcar} accepts multiple arguments but works
3729 only on lists; Emacs Lisp's @code{mapcar} accepts a single sequence
3730 argument. This package's @code{mapcar*} works as a compatible
3734 @defun map result-type function seq &rest more-seqs
3735 This function maps @var{function} over the argument sequences,
3736 just like @code{mapcar*}, but it returns a sequence of type
3737 @var{result-type} rather than a list. @var{result-type} must
3738 be one of the following symbols: @code{vector}, @code{string},
3739 @code{list} (in which case the effect is the same as for
3740 @code{mapcar*}), or @code{nil} (in which case the results are
3741 thrown away and @code{map} returns @code{nil}).
3744 @defun maplist function list &rest more-lists
3745 This function calls @var{function} on each of its argument lists,
3746 then on the @code{cdr}s of those lists, and so on, until the
3747 shortest list runs out. The results are returned in the form
3748 of a list. Thus, @code{maplist} is like @code{mapcar*} except
3749 that it passes in the list pointers themselves rather than the
3750 @code{car}s of the advancing pointers.
3753 @defun cl-mapc function seq &rest more-seqs
3754 This function is like @code{mapcar*}, except that the values returned
3755 by @var{function} are ignored and thrown away rather than being
3756 collected into a list. The return value of @code{cl-mapc} is @var{seq},
3757 the first sequence. This function is more general than the Emacs
3758 primitive @code{mapc}.
3761 @defun mapl function list &rest more-lists
3762 This function is like @code{maplist}, except that it throws away
3763 the values returned by @var{function}.
3766 @defun mapcan function seq &rest more-seqs
3767 This function is like @code{mapcar*}, except that it concatenates
3768 the return values (which must be lists) using @code{nconc},
3769 rather than simply collecting them into a list.
3772 @defun mapcon function list &rest more-lists
3773 This function is like @code{maplist}, except that it concatenates
3774 the return values using @code{nconc}.
3777 @defun some predicate seq &rest more-seqs
3778 This function calls @var{predicate} on each element of @var{seq}
3779 in turn; if @var{predicate} returns a non-@code{nil} value,
3780 @code{some} returns that value, otherwise it returns @code{nil}.
3781 Given several sequence arguments, it steps through the sequences
3782 in parallel until the shortest one runs out, just as in
3783 @code{mapcar*}. You can rely on the left-to-right order in which
3784 the elements are visited, and on the fact that mapping stops
3785 immediately as soon as @var{predicate} returns non-@code{nil}.
3788 @defun every predicate seq &rest more-seqs
3789 This function calls @var{predicate} on each element of the sequence(s)
3790 in turn; it returns @code{nil} as soon as @var{predicate} returns
3791 @code{nil} for any element, or @code{t} if the predicate was true
3795 @defun notany predicate seq &rest more-seqs
3796 This function calls @var{predicate} on each element of the sequence(s)
3797 in turn; it returns @code{nil} as soon as @var{predicate} returns
3798 a non-@code{nil} value for any element, or @code{t} if the predicate
3799 was @code{nil} for all elements.
3802 @defun notevery predicate seq &rest more-seqs
3803 This function calls @var{predicate} on each element of the sequence(s)
3804 in turn; it returns a non-@code{nil} value as soon as @var{predicate}
3805 returns @code{nil} for any element, or @code{t} if the predicate was
3806 true for all elements.
3809 @defun reduce function seq @t{&key :from-end :start :end :initial-value :key}
3810 This function combines the elements of @var{seq} using an associative
3811 binary operation. Suppose @var{function} is @code{*} and @var{seq} is
3812 the list @code{(2 3 4 5)}. The first two elements of the list are
3813 combined with @code{(* 2 3) = 6}; this is combined with the next
3814 element, @code{(* 6 4) = 24}, and that is combined with the final
3815 element: @code{(* 24 5) = 120}. Note that the @code{*} function happens
3816 to be self-reducing, so that @code{(* 2 3 4 5)} has the same effect as
3817 an explicit call to @code{reduce}.
3819 If @code{:from-end} is true, the reduction is right-associative instead
3820 of left-associative:
3823 (reduce '- '(1 2 3 4))
3824 @equiv{} (- (- (- 1 2) 3) 4) @result{} -8
3825 (reduce '- '(1 2 3 4) :from-end t)
3826 @equiv{} (- 1 (- 2 (- 3 4))) @result{} -2
3829 If @code{:key} is specified, it is a function of one argument which
3830 is called on each of the sequence elements in turn.
3832 If @code{:initial-value} is specified, it is effectively added to the
3833 front (or rear in the case of @code{:from-end}) of the sequence.
3834 The @code{:key} function is @emph{not} applied to the initial value.
3836 If the sequence, including the initial value, has exactly one element
3837 then that element is returned without ever calling @var{function}.
3838 If the sequence is empty (and there is no initial value), then
3839 @var{function} is called with no arguments to obtain the return value.
3842 All of these mapping operations can be expressed conveniently in
3843 terms of the @code{loop} macro. In compiled code, @code{loop} will
3844 be faster since it generates the loop as in-line code with no
3847 @node Sequence Functions, Searching Sequences, Mapping over Sequences, Sequences
3848 @section Sequence Functions
3851 This section describes a number of Common Lisp functions for
3852 operating on sequences.
3854 @defun subseq sequence start &optional end
3855 This function returns a given subsequence of the argument
3856 @var{sequence}, which may be a list, string, or vector.
3857 The indices @var{start} and @var{end} must be in range, and
3858 @var{start} must be no greater than @var{end}. If @var{end}
3859 is omitted, it defaults to the length of the sequence. The
3860 return value is always a copy; it does not share structure
3861 with @var{sequence}.
3863 As an extension to Common Lisp, @var{start} and/or @var{end}
3864 may be negative, in which case they represent a distance back
3865 from the end of the sequence. This is for compatibility with
3866 Emacs' @code{substring} function. Note that @code{subseq} is
3867 the @emph{only} sequence function that allows negative
3868 @var{start} and @var{end}.
3870 You can use @code{setf} on a @code{subseq} form to replace a
3871 specified range of elements with elements from another sequence.
3872 The replacement is done as if by @code{replace}, described below.
3875 @defun concatenate result-type &rest seqs
3876 This function concatenates the argument sequences together to
3877 form a result sequence of type @var{result-type}, one of the
3878 symbols @code{vector}, @code{string}, or @code{list}. The
3879 arguments are always copied, even in cases such as
3880 @code{(concatenate 'list '(1 2 3))} where the result is
3881 identical to an argument.
3884 @defun fill seq item @t{&key :start :end}
3885 This function fills the elements of the sequence (or the specified
3886 part of the sequence) with the value @var{item}.
3889 @defun replace seq1 seq2 @t{&key :start1 :end1 :start2 :end2}
3890 This function copies part of @var{seq2} into part of @var{seq1}.
3891 The sequence @var{seq1} is not stretched or resized; the amount
3892 of data copied is simply the shorter of the source and destination
3893 (sub)sequences. The function returns @var{seq1}.
3895 If @var{seq1} and @var{seq2} are @code{eq}, then the replacement
3896 will work correctly even if the regions indicated by the start
3897 and end arguments overlap. However, if @var{seq1} and @var{seq2}
3898 are lists which share storage but are not @code{eq}, and the
3899 start and end arguments specify overlapping regions, the effect
3903 @defun remove* item seq @t{&key :test :test-not :key :count :start :end :from-end}
3904 This returns a copy of @var{seq} with all elements matching
3905 @var{item} removed. The result may share storage with or be
3906 @code{eq} to @var{seq} in some circumstances, but the original
3907 @var{seq} will not be modified. The @code{:test}, @code{:test-not},
3908 and @code{:key} arguments define the matching test that is used;
3909 by default, elements @code{eql} to @var{item} are removed. The
3910 @code{:count} argument specifies the maximum number of matching
3911 elements that can be removed (only the leftmost @var{count} matches
3912 are removed). The @code{:start} and @code{:end} arguments specify
3913 a region in @var{seq} in which elements will be removed; elements
3914 outside that region are not matched or removed. The @code{:from-end}
3915 argument, if true, says that elements should be deleted from the
3916 end of the sequence rather than the beginning (this matters only
3917 if @var{count} was also specified).
3920 @defun delete* item seq @t{&key :test :test-not :key :count :start :end :from-end}
3921 This deletes all elements of @var{seq} which match @var{item}.
3922 It is a destructive operation. Since Emacs Lisp does not support
3923 stretchable strings or vectors, this is the same as @code{remove*}
3924 for those sequence types. On lists, @code{remove*} will copy the
3925 list if necessary to preserve the original list, whereas
3926 @code{delete*} will splice out parts of the argument list.
3927 Compare @code{append} and @code{nconc}, which are analogous
3928 non-destructive and destructive list operations in Emacs Lisp.
3932 @findex remove-if-not
3934 @findex delete-if-not
3935 The predicate-oriented functions @code{remove-if}, @code{remove-if-not},
3936 @code{delete-if}, and @code{delete-if-not} are defined similarly.
3938 @defun remove-duplicates seq @t{&key :test :test-not :key :start :end :from-end}
3939 This function returns a copy of @var{seq} with duplicate elements
3940 removed. Specifically, if two elements from the sequence match
3941 according to the @code{:test}, @code{:test-not}, and @code{:key}
3942 arguments, only the rightmost one is retained. If @code{:from-end}
3943 is true, the leftmost one is retained instead. If @code{:start} or
3944 @code{:end} is specified, only elements within that subsequence are
3945 examined or removed.
3948 @defun delete-duplicates seq @t{&key :test :test-not :key :start :end :from-end}
3949 This function deletes duplicate elements from @var{seq}. It is
3950 a destructive version of @code{remove-duplicates}.
3953 @defun substitute new old seq @t{&key :test :test-not :key :count :start :end :from-end}
3954 This function returns a copy of @var{seq}, with all elements
3955 matching @var{old} replaced with @var{new}. The @code{:count},
3956 @code{:start}, @code{:end}, and @code{:from-end} arguments may be
3957 used to limit the number of substitutions made.
3960 @defun nsubstitute new old seq @t{&key :test :test-not :key :count :start :end :from-end}
3961 This is a destructive version of @code{substitute}; it performs
3962 the substitution using @code{setcar} or @code{aset} rather than
3963 by returning a changed copy of the sequence.
3966 @findex substitute-if
3967 @findex substitute-if-not
3968 @findex nsubstitute-if
3969 @findex nsubstitute-if-not
3970 The @code{substitute-if}, @code{substitute-if-not}, @code{nsubstitute-if},
3971 and @code{nsubstitute-if-not} functions are defined similarly. For
3972 these, a @var{predicate} is given in place of the @var{old} argument.
3974 @node Searching Sequences, Sorting Sequences, Sequence Functions, Sequences
3975 @section Searching Sequences
3978 These functions search for elements or subsequences in a sequence.
3979 (See also @code{member*} and @code{assoc*}; @pxref{Lists}.)
3981 @defun find item seq @t{&key :test :test-not :key :start :end :from-end}
3982 This function searches @var{seq} for an element matching @var{item}.
3983 If it finds a match, it returns the matching element. Otherwise,
3984 it returns @code{nil}. It returns the leftmost match, unless
3985 @code{:from-end} is true, in which case it returns the rightmost
3986 match. The @code{:start} and @code{:end} arguments may be used to
3987 limit the range of elements that are searched.
3990 @defun position item seq @t{&key :test :test-not :key :start :end :from-end}
3991 This function is like @code{find}, except that it returns the
3992 integer position in the sequence of the matching item rather than
3993 the item itself. The position is relative to the start of the
3994 sequence as a whole, even if @code{:start} is non-zero. The function
3995 returns @code{nil} if no matching element was found.
3998 @defun count item seq @t{&key :test :test-not :key :start :end}
3999 This function returns the number of elements of @var{seq} which
4000 match @var{item}. The result is always a nonnegative integer.
4006 @findex position-if-not
4008 @findex count-if-not
4009 The @code{find-if}, @code{find-if-not}, @code{position-if},
4010 @code{position-if-not}, @code{count-if}, and @code{count-if-not}
4011 functions are defined similarly.
4013 @defun mismatch seq1 seq2 @t{&key :test :test-not :key :start1 :end1 :start2 :end2 :from-end}
4014 This function compares the specified parts of @var{seq1} and
4015 @var{seq2}. If they are the same length and the corresponding
4016 elements match (according to @code{:test}, @code{:test-not},
4017 and @code{:key}), the function returns @code{nil}. If there is
4018 a mismatch, the function returns the index (relative to @var{seq1})
4019 of the first mismatching element. This will be the leftmost pair of
4020 elements which do not match, or the position at which the shorter of
4021 the two otherwise-matching sequences runs out.
4023 If @code{:from-end} is true, then the elements are compared from right
4024 to left starting at @code{(1- @var{end1})} and @code{(1- @var{end2})}.
4025 If the sequences differ, then one plus the index of the rightmost
4026 difference (relative to @var{seq1}) is returned.
4028 An interesting example is @code{(mismatch str1 str2 :key 'upcase)},
4029 which compares two strings case-insensitively.
4032 @defun search seq1 seq2 @t{&key :test :test-not :key :from-end :start1 :end1 :start2 :end2}
4033 This function searches @var{seq2} for a subsequence that matches
4034 @var{seq1} (or part of it specified by @code{:start1} and
4035 @code{:end1}.) Only matches which fall entirely within the region
4036 defined by @code{:start2} and @code{:end2} will be considered.
4037 The return value is the index of the leftmost element of the
4038 leftmost match, relative to the start of @var{seq2}, or @code{nil}
4039 if no matches were found. If @code{:from-end} is true, the
4040 function finds the @emph{rightmost} matching subsequence.
4043 @node Sorting Sequences, , Searching Sequences, Sequences
4044 @section Sorting Sequences
4046 @defun sort* seq predicate @t{&key :key}
4047 This function sorts @var{seq} into increasing order as determined
4048 by using @var{predicate} to compare pairs of elements. @var{predicate}
4049 should return true (non-@code{nil}) if and only if its first argument
4050 is less than (not equal to) its second argument. For example,
4051 @code{<} and @code{string-lessp} are suitable predicate functions
4052 for sorting numbers and strings, respectively; @code{>} would sort
4053 numbers into decreasing rather than increasing order.
4055 This function differs from Emacs' built-in @code{sort} in that it
4056 can operate on any type of sequence, not just lists. Also, it
4057 accepts a @code{:key} argument which is used to preprocess data
4058 fed to the @var{predicate} function. For example,
4061 (setq data (sort* data 'string-lessp :key 'downcase))
4065 sorts @var{data}, a sequence of strings, into increasing alphabetical
4066 order without regard to case. A @code{:key} function of @code{car}
4067 would be useful for sorting association lists. It should only be a
4068 simple accessor though, it's used heavily in the current
4071 The @code{sort*} function is destructive; it sorts lists by actually
4072 rearranging the @code{cdr} pointers in suitable fashion.
4075 @defun stable-sort seq predicate @t{&key :key}
4076 This function sorts @var{seq} @dfn{stably}, meaning two elements
4077 which are equal in terms of @var{predicate} are guaranteed not to
4078 be rearranged out of their original order by the sort.
4080 In practice, @code{sort*} and @code{stable-sort} are equivalent
4081 in Emacs Lisp because the underlying @code{sort} function is
4082 stable by default. However, this package reserves the right to
4083 use non-stable methods for @code{sort*} in the future.
4086 @defun merge type seq1 seq2 predicate @t{&key :key}
4087 This function merges two sequences @var{seq1} and @var{seq2} by
4088 interleaving their elements. The result sequence, of type @var{type}
4089 (in the sense of @code{concatenate}), has length equal to the sum
4090 of the lengths of the two input sequences. The sequences may be
4091 modified destructively. Order of elements within @var{seq1} and
4092 @var{seq2} is preserved in the interleaving; elements of the two
4093 sequences are compared by @var{predicate} (in the sense of
4094 @code{sort}) and the lesser element goes first in the result.
4095 When elements are equal, those from @var{seq1} precede those from
4096 @var{seq2} in the result. Thus, if @var{seq1} and @var{seq2} are
4097 both sorted according to @var{predicate}, then the result will be
4098 a merged sequence which is (stably) sorted according to
4102 @node Lists, Structures, Sequences, Top
4106 The functions described here operate on lists.
4109 * List Functions:: `caddr', `first', `list*', etc.
4110 * Substitution of Expressions:: `subst', `sublis', etc.
4111 * Lists as Sets:: `member*', `adjoin', `union', etc.
4112 * Association Lists:: `assoc*', `rassoc*', `acons', `pairlis'
4115 @node List Functions, Substitution of Expressions, Lists, Lists
4116 @section List Functions
4119 This section describes a number of simple operations on lists,
4120 i.e., chains of cons cells.
4123 This function is equivalent to @code{(car (cdr (cdr @var{x})))}.
4124 Likewise, this package defines all 28 @code{c@var{xxx}r} functions
4125 where @var{xxx} is up to four @samp{a}s and/or @samp{d}s.
4126 All of these functions are @code{setf}-able, and calls to them
4127 are expanded inline by the byte-compiler for maximum efficiency.
4131 This function is a synonym for @code{(car @var{x})}. Likewise,
4132 the functions @code{second}, @code{third}, @dots{}, through
4133 @code{tenth} return the given element of the list @var{x}.
4137 This function is a synonym for @code{(cdr @var{x})}.
4141 Common Lisp defines this function to act like @code{null}, but
4142 signaling an error if @code{x} is neither a @code{nil} nor a
4143 cons cell. This package simply defines @code{endp} as a synonym
4147 @defun list-length x
4148 This function returns the length of list @var{x}, exactly like
4149 @code{(length @var{x})}, except that if @var{x} is a circular
4150 list (where the cdr-chain forms a loop rather than terminating
4151 with @code{nil}), this function returns @code{nil}. (The regular
4152 @code{length} function would get stuck if given a circular list.)
4155 @defun list* arg &rest others
4156 This function constructs a list of its arguments. The final
4157 argument becomes the @code{cdr} of the last cell constructed.
4158 Thus, @code{(list* @var{a} @var{b} @var{c})} is equivalent to
4159 @code{(cons @var{a} (cons @var{b} @var{c}))}, and
4160 @code{(list* @var{a} @var{b} nil)} is equivalent to
4161 @code{(list @var{a} @var{b})}.
4163 (Note that this function really is called @code{list*} in Common
4164 Lisp; it is not a name invented for this package like @code{member*}
4168 @defun ldiff list sublist
4169 If @var{sublist} is a sublist of @var{list}, i.e., is @code{eq} to
4170 one of the cons cells of @var{list}, then this function returns
4171 a copy of the part of @var{list} up to but not including
4172 @var{sublist}. For example, @code{(ldiff x (cddr x))} returns
4173 the first two elements of the list @code{x}. The result is a
4174 copy; the original @var{list} is not modified. If @var{sublist}
4175 is not a sublist of @var{list}, a copy of the entire @var{list}
4179 @defun copy-list list
4180 This function returns a copy of the list @var{list}. It copies
4181 dotted lists like @code{(1 2 . 3)} correctly.
4184 @defun copy-tree x &optional vecp
4185 This function returns a copy of the tree of cons cells @var{x}.
4186 Unlike @code{copy-sequence} (and its alias @code{copy-list}),
4187 which copies only along the @code{cdr} direction, this function
4188 copies (recursively) along both the @code{car} and the @code{cdr}
4189 directions. If @var{x} is not a cons cell, the function simply
4190 returns @var{x} unchanged. If the optional @var{vecp} argument
4191 is true, this function copies vectors (recursively) as well as
4195 @defun tree-equal x y @t{&key :test :test-not :key}
4196 This function compares two trees of cons cells. If @var{x} and
4197 @var{y} are both cons cells, their @code{car}s and @code{cdr}s are
4198 compared recursively. If neither @var{x} nor @var{y} is a cons
4199 cell, they are compared by @code{eql}, or according to the
4200 specified test. The @code{:key} function, if specified, is
4201 applied to the elements of both trees. @xref{Sequences}.
4208 @node Substitution of Expressions, Lists as Sets, List Functions, Lists
4209 @section Substitution of Expressions
4212 These functions substitute elements throughout a tree of cons
4213 cells. (@xref{Sequence Functions}, for the @code{substitute}
4214 function, which works on just the top-level elements of a list.)
4216 @defun subst new old tree @t{&key :test :test-not :key}
4217 This function substitutes occurrences of @var{old} with @var{new}
4218 in @var{tree}, a tree of cons cells. It returns a substituted
4219 tree, which will be a copy except that it may share storage with
4220 the argument @var{tree} in parts where no substitutions occurred.
4221 The original @var{tree} is not modified. This function recurses
4222 on, and compares against @var{old}, both @code{car}s and @code{cdr}s
4223 of the component cons cells. If @var{old} is itself a cons cell,
4224 then matching cells in the tree are substituted as usual without
4225 recursively substituting in that cell. Comparisons with @var{old}
4226 are done according to the specified test (@code{eql} by default).
4227 The @code{:key} function is applied to the elements of the tree
4228 but not to @var{old}.
4231 @defun nsubst new old tree @t{&key :test :test-not :key}
4232 This function is like @code{subst}, except that it works by
4233 destructive modification (by @code{setcar} or @code{setcdr})
4234 rather than copying.
4238 @findex subst-if-not
4240 @findex nsubst-if-not
4241 The @code{subst-if}, @code{subst-if-not}, @code{nsubst-if}, and
4242 @code{nsubst-if-not} functions are defined similarly.
4244 @defun sublis alist tree @t{&key :test :test-not :key}
4245 This function is like @code{subst}, except that it takes an
4246 association list @var{alist} of @var{old}-@var{new} pairs.
4247 Each element of the tree (after applying the @code{:key}
4248 function, if any), is compared with the @code{car}s of
4249 @var{alist}; if it matches, it is replaced by the corresponding
4253 @defun nsublis alist tree @t{&key :test :test-not :key}
4254 This is a destructive version of @code{sublis}.
4257 @node Lists as Sets, Association Lists, Substitution of Expressions, Lists
4258 @section Lists as Sets
4261 These functions perform operations on lists which represent sets
4264 @defun member* item list @t{&key :test :test-not :key}
4265 This function searches @var{list} for an element matching @var{item}.
4266 If a match is found, it returns the cons cell whose @code{car} was
4267 the matching element. Otherwise, it returns @code{nil}. Elements
4268 are compared by @code{eql} by default; you can use the @code{:test},
4269 @code{:test-not}, and @code{:key} arguments to modify this behavior.
4272 Note that this function's name is suffixed by @samp{*} to avoid
4273 the incompatible @code{member} function defined in Emacs.
4274 (That function uses @code{equal} for comparisons; it is equivalent
4275 to @code{(member* @var{item} @var{list} :test 'equal)}.)
4279 @findex member-if-not
4280 The @code{member-if} and @code{member-if-not} functions
4281 analogously search for elements which satisfy a given predicate.
4283 @defun tailp sublist list
4284 This function returns @code{t} if @var{sublist} is a sublist of
4285 @var{list}, i.e., if @var{sublist} is @code{eql} to @var{list} or to
4286 any of its @code{cdr}s.
4289 @defun adjoin item list @t{&key :test :test-not :key}
4290 This function conses @var{item} onto the front of @var{list},
4291 like @code{(cons @var{item} @var{list})}, but only if @var{item}
4292 is not already present on the list (as determined by @code{member*}).
4293 If a @code{:key} argument is specified, it is applied to
4294 @var{item} as well as to the elements of @var{list} during
4295 the search, on the reasoning that @var{item} is ``about'' to
4296 become part of the list.
4299 @defun union list1 list2 @t{&key :test :test-not :key}
4300 This function combines two lists which represent sets of items,
4301 returning a list that represents the union of those two sets.
4302 The result list will contain all items which appear in @var{list1}
4303 or @var{list2}, and no others. If an item appears in both
4304 @var{list1} and @var{list2} it will be copied only once. If
4305 an item is duplicated in @var{list1} or @var{list2}, it is
4306 undefined whether or not that duplication will survive in the
4307 result list. The order of elements in the result list is also
4311 @defun nunion list1 list2 @t{&key :test :test-not :key}
4312 This is a destructive version of @code{union}; rather than copying,
4313 it tries to reuse the storage of the argument lists if possible.
4316 @defun intersection list1 list2 @t{&key :test :test-not :key}
4317 This function computes the intersection of the sets represented
4318 by @var{list1} and @var{list2}. It returns the list of items
4319 which appear in both @var{list1} and @var{list2}.
4322 @defun nintersection list1 list2 @t{&key :test :test-not :key}
4323 This is a destructive version of @code{intersection}. It
4324 tries to reuse storage of @var{list1} rather than copying.
4325 It does @emph{not} reuse the storage of @var{list2}.
4328 @defun set-difference list1 list2 @t{&key :test :test-not :key}
4329 This function computes the ``set difference'' of @var{list1}
4330 and @var{list2}, i.e., the set of elements that appear in
4331 @var{list1} but @emph{not} in @var{list2}.
4334 @defun nset-difference list1 list2 @t{&key :test :test-not :key}
4335 This is a destructive @code{set-difference}, which will try
4336 to reuse @var{list1} if possible.
4339 @defun set-exclusive-or list1 list2 @t{&key :test :test-not :key}
4340 This function computes the ``set exclusive or'' of @var{list1}
4341 and @var{list2}, i.e., the set of elements that appear in
4342 exactly one of @var{list1} and @var{list2}.
4345 @defun nset-exclusive-or list1 list2 @t{&key :test :test-not :key}
4346 This is a destructive @code{set-exclusive-or}, which will try
4347 to reuse @var{list1} and @var{list2} if possible.
4350 @defun subsetp list1 list2 @t{&key :test :test-not :key}
4351 This function checks whether @var{list1} represents a subset
4352 of @var{list2}, i.e., whether every element of @var{list1}
4353 also appears in @var{list2}.
4356 @node Association Lists, , Lists as Sets, Lists
4357 @section Association Lists
4360 An @dfn{association list} is a list representing a mapping from
4361 one set of values to another; any list whose elements are cons
4362 cells is an association list.
4364 @defun assoc* item a-list @t{&key :test :test-not :key}
4365 This function searches the association list @var{a-list} for an
4366 element whose @code{car} matches (in the sense of @code{:test},
4367 @code{:test-not}, and @code{:key}, or by comparison with @code{eql})
4368 a given @var{item}. It returns the matching element, if any,
4369 otherwise @code{nil}. It ignores elements of @var{a-list} which
4370 are not cons cells. (This corresponds to the behavior of
4371 @code{assq} and @code{assoc} in Emacs Lisp; Common Lisp's
4372 @code{assoc} ignores @code{nil}s but considers any other non-cons
4373 elements of @var{a-list} to be an error.)
4376 @defun rassoc* item a-list @t{&key :test :test-not :key}
4377 This function searches for an element whose @code{cdr} matches
4378 @var{item}. If @var{a-list} represents a mapping, this applies
4379 the inverse of the mapping to @var{item}.
4383 @findex assoc-if-not
4385 @findex rassoc-if-not
4386 The @code{assoc-if}, @code{assoc-if-not}, @code{rassoc-if},
4387 and @code{rassoc-if-not} functions are defined similarly.
4389 Two simple functions for constructing association lists are:
4391 @defun acons key value alist
4392 This is equivalent to @code{(cons (cons @var{key} @var{value}) @var{alist})}.
4395 @defun pairlis keys values &optional alist
4396 This is equivalent to @code{(nconc (mapcar* 'cons @var{keys} @var{values})
4404 @node Structures, Assertions, Lists, Top
4408 The Common Lisp @dfn{structure} mechanism provides a general way
4409 to define data types similar to C's @code{struct} types. A
4410 structure is a Lisp object containing some number of @dfn{slots},
4411 each of which can hold any Lisp data object. Functions are
4412 provided for accessing and setting the slots, creating or copying
4413 structure objects, and recognizing objects of a particular structure
4416 In true Common Lisp, each structure type is a new type distinct
4417 from all existing Lisp types. Since the underlying Emacs Lisp
4418 system provides no way to create new distinct types, this package
4419 implements structures as vectors (or lists upon request) with a
4420 special ``tag'' symbol to identify them.
4422 @defspec defstruct name slots@dots{}
4423 The @code{defstruct} form defines a new structure type called
4424 @var{name}, with the specified @var{slots}. (The @var{slots}
4425 may begin with a string which documents the structure type.)
4426 In the simplest case, @var{name} and each of the @var{slots}
4427 are symbols. For example,
4430 (defstruct person name age sex)
4434 defines a struct type called @code{person} which contains three
4435 slots. Given a @code{person} object @var{p}, you can access those
4436 slots by calling @code{(person-name @var{p})}, @code{(person-age @var{p})},
4437 and @code{(person-sex @var{p})}. You can also change these slots by
4438 using @code{setf} on any of these place forms:
4441 (incf (person-age birthday-boy))
4444 You can create a new @code{person} by calling @code{make-person},
4445 which takes keyword arguments @code{:name}, @code{:age}, and
4446 @code{:sex} to specify the initial values of these slots in the
4447 new object. (Omitting any of these arguments leaves the corresponding
4448 slot ``undefined,'' according to the Common Lisp standard; in Emacs
4449 Lisp, such uninitialized slots are filled with @code{nil}.)
4451 Given a @code{person}, @code{(copy-person @var{p})} makes a new
4452 object of the same type whose slots are @code{eq} to those of @var{p}.
4454 Given any Lisp object @var{x}, @code{(person-p @var{x})} returns
4455 true if @var{x} looks like a @code{person}, false otherwise. (Again,
4456 in Common Lisp this predicate would be exact; in Emacs Lisp the
4457 best it can do is verify that @var{x} is a vector of the correct
4458 length which starts with the correct tag symbol.)
4460 Accessors like @code{person-name} normally check their arguments
4461 (effectively using @code{person-p}) and signal an error if the
4462 argument is the wrong type. This check is affected by
4463 @code{(optimize (safety @dots{}))} declarations. Safety level 1,
4464 the default, uses a somewhat optimized check that will detect all
4465 incorrect arguments, but may use an uninformative error message
4466 (e.g., ``expected a vector'' instead of ``expected a @code{person}'').
4467 Safety level 0 omits all checks except as provided by the underlying
4468 @code{aref} call; safety levels 2 and 3 do rigorous checking that will
4469 always print a descriptive error message for incorrect inputs.
4470 @xref{Declarations}.
4473 (setq dave (make-person :name "Dave" :sex 'male))
4474 @result{} [cl-struct-person "Dave" nil male]
4475 (setq other (copy-person dave))
4476 @result{} [cl-struct-person "Dave" nil male]
4479 (eq (person-name dave) (person-name other))
4483 (person-p [1 2 3 4])
4487 (person-p '[cl-struct-person counterfeit person object])
4491 In general, @var{name} is either a name symbol or a list of a name
4492 symbol followed by any number of @dfn{struct options}; each @var{slot}
4493 is either a slot symbol or a list of the form @samp{(@var{slot-name}
4494 @var{default-value} @var{slot-options}@dots{})}. The @var{default-value}
4495 is a Lisp form which is evaluated any time an instance of the
4496 structure type is created without specifying that slot's value.
4498 Common Lisp defines several slot options, but the only one
4499 implemented in this package is @code{:read-only}. A non-@code{nil}
4500 value for this option means the slot should not be @code{setf}-able;
4501 the slot's value is determined when the object is created and does
4502 not change afterward.
4506 (name nil :read-only t)
4511 Any slot options other than @code{:read-only} are ignored.
4513 For obscure historical reasons, structure options take a different
4514 form than slot options. A structure option is either a keyword
4515 symbol, or a list beginning with a keyword symbol possibly followed
4516 by arguments. (By contrast, slot options are key-value pairs not
4520 (defstruct (person (:constructor create-person)
4526 The following structure options are recognized.
4531 @advance@leftskip-.5@tableindent
4534 The argument is a symbol whose print name is used as the prefix for
4535 the names of slot accessor functions. The default is the name of
4536 the struct type followed by a hyphen. The option @code{(:conc-name p-)}
4537 would change this prefix to @code{p-}. Specifying @code{nil} as an
4538 argument means no prefix, so that the slot names themselves are used
4539 to name the accessor functions.
4542 In the simple case, this option takes one argument which is an
4543 alternate name to use for the constructor function. The default
4544 is @code{make-@var{name}}, e.g., @code{make-person}. The above
4545 example changes this to @code{create-person}. Specifying @code{nil}
4546 as an argument means that no standard constructor should be
4549 In the full form of this option, the constructor name is followed
4550 by an arbitrary argument list. @xref{Program Structure}, for a
4551 description of the format of Common Lisp argument lists. All
4552 options, such as @code{&rest} and @code{&key}, are supported.
4553 The argument names should match the slot names; each slot is
4554 initialized from the corresponding argument. Slots whose names
4555 do not appear in the argument list are initialized based on the
4556 @var{default-value} in their slot descriptor. Also, @code{&optional}
4557 and @code{&key} arguments which don't specify defaults take their
4558 defaults from the slot descriptor. It is valid to include arguments
4559 which don't correspond to slot names; these are useful if they are
4560 referred to in the defaults for optional, keyword, or @code{&aux}
4561 arguments which @emph{do} correspond to slots.
4563 You can specify any number of full-format @code{:constructor}
4564 options on a structure. The default constructor is still generated
4565 as well unless you disable it with a simple-format @code{:constructor}
4571 (:constructor nil) ; no default constructor
4572 (:constructor new-person (name sex &optional (age 0)))
4573 (:constructor new-hound (&key (name "Rover")
4575 &aux (age (* 7 dog-years))
4580 The first constructor here takes its arguments positionally rather
4581 than by keyword. (In official Common Lisp terminology, constructors
4582 that work By Order of Arguments instead of by keyword are called
4583 ``BOA constructors.'' No, I'm not making this up.) For example,
4584 @code{(new-person "Jane" 'female)} generates a person whose slots
4585 are @code{"Jane"}, 0, and @code{female}, respectively.
4587 The second constructor takes two keyword arguments, @code{:name},
4588 which initializes the @code{name} slot and defaults to @code{"Rover"},
4589 and @code{:dog-years}, which does not itself correspond to a slot
4590 but which is used to initialize the @code{age} slot. The @code{sex}
4591 slot is forced to the symbol @code{canine} with no syntax for
4595 The argument is an alternate name for the copier function for
4596 this type. The default is @code{copy-@var{name}}. @code{nil}
4597 means not to generate a copier function. (In this implementation,
4598 all copier functions are simply synonyms for @code{copy-sequence}.)
4601 The argument is an alternate name for the predicate which recognizes
4602 objects of this type. The default is @code{@var{name}-p}. @code{nil}
4603 means not to generate a predicate function. (If the @code{:type}
4604 option is used without the @code{:named} option, no predicate is
4607 In true Common Lisp, @code{typep} is always able to recognize a
4608 structure object even if @code{:predicate} was used. In this
4609 package, @code{typep} simply looks for a function called
4610 @code{@var{typename}-p}, so it will work for structure types
4611 only if they used the default predicate name.
4614 This option implements a very limited form of C++-style inheritance.
4615 The argument is the name of another structure type previously
4616 created with @code{defstruct}. The effect is to cause the new
4617 structure type to inherit all of the included structure's slots
4618 (plus, of course, any new slots described by this struct's slot
4619 descriptors). The new structure is considered a ``specialization''
4620 of the included one. In fact, the predicate and slot accessors
4621 for the included type will also accept objects of the new type.
4623 If there are extra arguments to the @code{:include} option after
4624 the included-structure name, these options are treated as replacement
4625 slot descriptors for slots in the included structure, possibly with
4626 modified default values. Borrowing an example from Steele:
4629 (defstruct person name (age 0) sex)
4631 (defstruct (astronaut (:include person (age 45)))
4633 (favorite-beverage 'tang))
4636 (setq joe (make-person :name "Joe"))
4637 @result{} [cl-struct-person "Joe" 0 nil]
4638 (setq buzz (make-astronaut :name "Buzz"))
4639 @result{} [cl-struct-astronaut "Buzz" 45 nil nil tang]
4641 (list (person-p joe) (person-p buzz))
4643 (list (astronaut-p joe) (astronaut-p buzz))
4648 (astronaut-name joe)
4649 @result{} error: "astronaut-name accessing a non-astronaut"
4652 Thus, if @code{astronaut} is a specialization of @code{person},
4653 then every @code{astronaut} is also a @code{person} (but not the
4654 other way around). Every @code{astronaut} includes all the slots
4655 of a @code{person}, plus extra slots that are specific to
4656 astronauts. Operations that work on people (like @code{person-name})
4657 work on astronauts just like other people.
4659 @item :print-function
4660 In full Common Lisp, this option allows you to specify a function
4661 which is called to print an instance of the structure type. The
4662 Emacs Lisp system offers no hooks into the Lisp printer which would
4663 allow for such a feature, so this package simply ignores
4664 @code{:print-function}.
4667 The argument should be one of the symbols @code{vector} or @code{list}.
4668 This tells which underlying Lisp data type should be used to implement
4669 the new structure type. Vectors are used by default, but
4670 @code{(:type list)} will cause structure objects to be stored as
4673 The vector representation for structure objects has the advantage
4674 that all structure slots can be accessed quickly, although creating
4675 vectors is a bit slower in Emacs Lisp. Lists are easier to create,
4676 but take a relatively long time accessing the later slots.
4679 This option, which takes no arguments, causes a characteristic ``tag''
4680 symbol to be stored at the front of the structure object. Using
4681 @code{:type} without also using @code{:named} will result in a
4682 structure type stored as plain vectors or lists with no identifying
4685 The default, if you don't specify @code{:type} explicitly, is to
4686 use named vectors. Therefore, @code{:named} is only useful in
4687 conjunction with @code{:type}.
4690 (defstruct (person1) name age sex)
4691 (defstruct (person2 (:type list) :named) name age sex)
4692 (defstruct (person3 (:type list)) name age sex)
4694 (setq p1 (make-person1))
4695 @result{} [cl-struct-person1 nil nil nil]
4696 (setq p2 (make-person2))
4697 @result{} (person2 nil nil nil)
4698 (setq p3 (make-person3))
4699 @result{} (nil nil nil)
4706 @result{} error: function person3-p undefined
4709 Since unnamed structures don't have tags, @code{defstruct} is not
4710 able to make a useful predicate for recognizing them. Also,
4711 accessors like @code{person3-name} will be generated but they
4712 will not be able to do any type checking. The @code{person3-name}
4713 function, for example, will simply be a synonym for @code{car} in
4714 this case. By contrast, @code{person2-name} is able to verify
4715 that its argument is indeed a @code{person2} object before
4718 @item :initial-offset
4719 The argument must be a nonnegative integer. It specifies a
4720 number of slots to be left ``empty'' at the front of the
4721 structure. If the structure is named, the tag appears at the
4722 specified position in the list or vector; otherwise, the first
4723 slot appears at that position. Earlier positions are filled
4724 with @code{nil} by the constructors and ignored otherwise. If
4725 the type @code{:include}s another type, then @code{:initial-offset}
4726 specifies a number of slots to be skipped between the last slot
4727 of the included type and the first new slot.
4731 Except as noted, the @code{defstruct} facility of this package is
4732 entirely compatible with that of Common Lisp.
4738 @node Assertions, Efficiency Concerns, Structures, Top
4739 @chapter Assertions and Errors
4742 This section describes two macros that test @dfn{assertions}, i.e.,
4743 conditions which must be true if the program is operating correctly.
4744 Assertions never add to the behavior of a Lisp program; they simply
4745 make ``sanity checks'' to make sure everything is as it should be.
4747 If the optimization property @code{speed} has been set to 3, and
4748 @code{safety} is less than 3, then the byte-compiler will optimize
4749 away the following assertions. Because assertions might be optimized
4750 away, it is a bad idea for them to include side-effects.
4752 @defspec assert test-form [show-args string args@dots{}]
4753 This form verifies that @var{test-form} is true (i.e., evaluates to
4754 a non-@code{nil} value). If so, it returns @code{nil}. If the test
4755 is not satisfied, @code{assert} signals an error.
4757 A default error message will be supplied which includes @var{test-form}.
4758 You can specify a different error message by including a @var{string}
4759 argument plus optional extra arguments. Those arguments are simply
4760 passed to @code{error} to signal the error.
4762 If the optional second argument @var{show-args} is @code{t} instead
4763 of @code{nil}, then the error message (with or without @var{string})
4764 will also include all non-constant arguments of the top-level
4765 @var{form}. For example:
4768 (assert (> x 10) t "x is too small: %d")
4771 This usage of @var{show-args} is an extension to Common Lisp. In
4772 true Common Lisp, the second argument gives a list of @var{places}
4773 which can be @code{setf}'d by the user before continuing from the
4774 error. Since Emacs Lisp does not support continuable errors, it
4775 makes no sense to specify @var{places}.
4778 @defspec check-type form type [string]
4779 This form verifies that @var{form} evaluates to a value of type
4780 @var{type}. If so, it returns @code{nil}. If not, @code{check-type}
4781 signals a @code{wrong-type-argument} error. The default error message
4782 lists the erroneous value along with @var{type} and @var{form}
4783 themselves. If @var{string} is specified, it is included in the
4784 error message in place of @var{type}. For example:
4787 (check-type x (integer 1 *) "a positive integer")
4790 @xref{Type Predicates}, for a description of the type specifiers
4791 that may be used for @var{type}.
4793 Note that in Common Lisp, the first argument to @code{check-type}
4794 must be a @var{place} suitable for use by @code{setf}, because
4795 @code{check-type} signals a continuable error that allows the
4796 user to modify @var{place}.
4799 The following error-related macro is also defined:
4801 @defspec ignore-errors forms@dots{}
4802 This executes @var{forms} exactly like a @code{progn}, except that
4803 errors are ignored during the @var{forms}. More precisely, if
4804 an error is signaled then @code{ignore-errors} immediately
4805 aborts execution of the @var{forms} and returns @code{nil}.
4806 If the @var{forms} complete successfully, @code{ignore-errors}
4807 returns the result of the last @var{form}.
4810 @node Efficiency Concerns, Common Lisp Compatibility, Assertions, Top
4811 @appendix Efficiency Concerns
4816 Many of the advanced features of this package, such as @code{defun*},
4817 @code{loop}, and @code{setf}, are implemented as Lisp macros. In
4818 byte-compiled code, these complex notations will be expanded into
4819 equivalent Lisp code which is simple and efficient. For example,
4828 are expanded at compile-time to the Lisp forms
4832 (setcar p (cons x (car p)))
4836 which are the most efficient ways of doing these respective operations
4837 in Lisp. Thus, there is no performance penalty for using the more
4838 readable @code{incf} and @code{push} forms in your compiled code.
4840 @emph{Interpreted} code, on the other hand, must expand these macros
4841 every time they are executed. For this reason it is strongly
4842 recommended that code making heavy use of macros be compiled.
4843 (The features labeled ``Special Form'' instead of ``Function'' in
4844 this manual are macros.) A loop using @code{incf} a hundred times
4845 will execute considerably faster if compiled, and will also
4846 garbage-collect less because the macro expansion will not have
4847 to be generated, used, and thrown away a hundred times.
4849 You can find out how a macro expands by using the
4850 @code{cl-prettyexpand} function.
4852 @defun cl-prettyexpand form &optional full
4853 This function takes a single Lisp form as an argument and inserts
4854 a nicely formatted copy of it in the current buffer (which must be
4855 in Lisp mode so that indentation works properly). It also expands
4856 all Lisp macros which appear in the form. The easiest way to use
4857 this function is to go to the @code{*scratch*} buffer and type, say,
4860 (cl-prettyexpand '(loop for x below 10 collect x))
4864 and type @kbd{C-x C-e} immediately after the closing parenthesis;
4872 (setq G1004 (cons x G1004))
4878 will be inserted into the buffer. (The @code{block} macro is
4879 expanded differently in the interpreter and compiler, so
4880 @code{cl-prettyexpand} just leaves it alone. The temporary
4881 variable @code{G1004} was created by @code{gensym}.)
4883 If the optional argument @var{full} is true, then @emph{all}
4884 macros are expanded, including @code{block}, @code{eval-when},
4885 and compiler macros. Expansion is done as if @var{form} were
4886 a top-level form in a file being compiled. For example,
4889 (cl-prettyexpand '(pushnew 'x list))
4890 @print{} (setq list (adjoin 'x list))
4891 (cl-prettyexpand '(pushnew 'x list) t)
4892 @print{} (setq list (if (memq 'x list) list (cons 'x list)))
4893 (cl-prettyexpand '(caddr (member* 'a list)) t)
4894 @print{} (car (cdr (cdr (memq 'a list))))
4897 Note that @code{adjoin}, @code{caddr}, and @code{member*} all
4898 have built-in compiler macros to optimize them in common cases.
4906 @appendixsec Error Checking
4909 Common Lisp compliance has in general not been sacrificed for the
4910 sake of efficiency. A few exceptions have been made for cases
4911 where substantial gains were possible at the expense of marginal
4914 The Common Lisp standard (as embodied in Steele's book) uses the
4915 phrase ``it is an error if'' to indicate a situation which is not
4916 supposed to arise in complying programs; implementations are strongly
4917 encouraged but not required to signal an error in these situations.
4918 This package sometimes omits such error checking in the interest of
4919 compactness and efficiency. For example, @code{do} variable
4920 specifiers are supposed to be lists of one, two, or three forms;
4921 extra forms are ignored by this package rather than signaling a
4922 syntax error. The @code{endp} function is simply a synonym for
4923 @code{null} in this package. Functions taking keyword arguments
4924 will accept an odd number of arguments, treating the trailing
4925 keyword as if it were followed by the value @code{nil}.
4927 Argument lists (as processed by @code{defun*} and friends)
4928 @emph{are} checked rigorously except for the minor point just
4929 mentioned; in particular, keyword arguments are checked for
4930 validity, and @code{&allow-other-keys} and @code{:allow-other-keys}
4931 are fully implemented. Keyword validity checking is slightly
4932 time consuming (though not too bad in byte-compiled code);
4933 you can use @code{&allow-other-keys} to omit this check. Functions
4934 defined in this package such as @code{find} and @code{member*}
4935 do check their keyword arguments for validity.
4942 @appendixsec Optimizing Compiler
4945 Use of the optimizing Emacs compiler is highly recommended; many of the Common
4947 code which can be improved by optimization. In particular,
4948 @code{block}s (whether explicit or implicit in constructs like
4949 @code{defun*} and @code{loop}) carry a fair run-time penalty; the
4950 optimizing compiler removes @code{block}s which are not actually
4951 referenced by @code{return} or @code{return-from} inside the block.
4953 @node Common Lisp Compatibility, Old CL Compatibility, Efficiency Concerns, Top
4954 @appendix Common Lisp Compatibility
4957 Following is a list of all known incompatibilities between this
4958 package and Common Lisp as documented in Steele (2nd edition).
4960 Certain function names, such as @code{member}, @code{assoc}, and
4961 @code{floor}, were already taken by (incompatible) Emacs Lisp
4962 functions; this package appends @samp{*} to the names of its
4963 Common Lisp versions of these functions.
4965 The word @code{defun*} is required instead of @code{defun} in order
4966 to use extended Common Lisp argument lists in a function. Likewise,
4967 @code{defmacro*} and @code{function*} are versions of those forms
4968 which understand full-featured argument lists. The @code{&whole}
4969 keyword does not work in @code{defmacro} argument lists (except
4970 inside recursive argument lists).
4972 The @code{equal} predicate does not distinguish
4973 between IEEE floating-point plus and minus zero. The @code{equalp}
4974 predicate has several differences with Common Lisp; @pxref{Predicates}.
4976 The @code{setf} mechanism is entirely compatible, except that
4977 setf-methods return a list of five values rather than five
4978 values directly. Also, the new ``@code{setf} function'' concept
4979 (typified by @code{(defun (setf foo) @dots{})}) is not implemented.
4981 The @code{do-all-symbols} form is the same as @code{do-symbols}
4982 with no @var{obarray} argument. In Common Lisp, this form would
4983 iterate over all symbols in all packages. Since Emacs obarrays
4984 are not a first-class package mechanism, there is no way for
4985 @code{do-all-symbols} to locate any but the default obarray.
4987 The @code{loop} macro is complete except that @code{loop-finish}
4988 and type specifiers are unimplemented.
4990 The multiple-value return facility treats lists as multiple
4991 values, since Emacs Lisp cannot support multiple return values
4992 directly. The macros will be compatible with Common Lisp if
4993 @code{values} or @code{values-list} is always used to return to
4994 a @code{multiple-value-bind} or other multiple-value receiver;
4995 if @code{values} is used without @code{multiple-value-@dots{}}
4996 or vice-versa the effect will be different from Common Lisp.
4998 Many Common Lisp declarations are ignored, and others match
4999 the Common Lisp standard in concept but not in detail. For
5000 example, local @code{special} declarations, which are purely
5001 advisory in Emacs Lisp, do not rigorously obey the scoping rules
5002 set down in Steele's book.
5004 The variable @code{*gensym-counter*} starts out with a pseudo-random
5005 value rather than with zero. This is to cope with the fact that
5006 generated symbols become interned when they are written to and
5007 loaded back from a file.
5009 The @code{defstruct} facility is compatible, except that structures
5010 are of type @code{:type vector :named} by default rather than some
5011 special, distinct type. Also, the @code{:type} slot option is ignored.
5013 The second argument of @code{check-type} is treated differently.
5015 @node Old CL Compatibility, Porting Common Lisp, Common Lisp Compatibility, Top
5016 @appendix Old CL Compatibility
5019 Following is a list of all known incompatibilities between this package
5020 and the older Quiroz @file{cl.el} package.
5022 This package's emulation of multiple return values in functions is
5023 incompatible with that of the older package. That package attempted
5024 to come as close as possible to true Common Lisp multiple return
5025 values; unfortunately, it could not be 100% reliable and so was prone
5026 to occasional surprises if used freely. This package uses a simpler
5027 method, namely replacing multiple values with lists of values, which
5028 is more predictable though more noticeably different from Common Lisp.
5030 The @code{defkeyword} form and @code{keywordp} function are not
5031 implemented in this package.
5033 The @code{member}, @code{floor}, @code{ceiling}, @code{truncate},
5034 @code{round}, @code{mod}, and @code{rem} functions are suffixed
5035 by @samp{*} in this package to avoid collision with existing
5036 functions in Emacs. The older package simply
5037 redefined these functions, overwriting the built-in meanings and
5038 causing serious portability problems. (Some more
5039 recent versions of the Quiroz package changed the names to
5040 @code{cl-member}, etc.; this package defines the latter names as
5041 aliases for @code{member*}, etc.)
5043 Certain functions in the old package which were buggy or inconsistent
5044 with the Common Lisp standard are incompatible with the conforming
5045 versions in this package. For example, @code{eql} and @code{member}
5046 were synonyms for @code{eq} and @code{memq} in that package, @code{setf}
5047 failed to preserve correct order of evaluation of its arguments, etc.
5049 Finally, unlike the older package, this package is careful to
5050 prefix all of its internal names with @code{cl-}. Except for a
5051 few functions which are explicitly defined as additional features
5052 (such as @code{floatp-safe} and @code{letf}), this package does not
5053 export any non-@samp{cl-} symbols which are not also part of Common
5061 @appendixsec The @code{cl-compat} package
5064 The @dfn{CL} package includes emulations of some features of the
5065 old @file{cl.el}, in the form of a compatibility package
5066 @code{cl-compat}. This file is obsolete and may be removed in future,
5067 so it should not be used in new code.
5069 The old package defined a number of internal routines without
5070 @code{cl-} prefixes or other annotations. Call to these routines
5071 may have crept into existing Lisp code. @code{cl-compat}
5072 provides emulations of the following internal routines:
5073 @code{pair-with-newsyms}, @code{zip-lists}, @code{unzip-lists},
5074 @code{reassemble-arglists}, @code{duplicate-symbols-p},
5077 Some @code{setf} forms translated into calls to internal
5078 functions that user code might call directly. The functions
5079 @code{setnth}, @code{setnthcdr}, and @code{setelt} fall in
5080 this category; they are defined by @code{cl-compat}, but the
5081 best fix is to change to use @code{setf} properly.
5083 The @code{cl-compat} file defines the keyword functions
5084 @code{keywordp}, @code{keyword-of}, and @code{defkeyword},
5085 which are not defined by the new @dfn{CL} package because the
5086 use of keywords as data is discouraged.
5088 The @code{build-klist} mechanism for parsing keyword arguments
5089 is emulated by @code{cl-compat}; the @code{with-keyword-args}
5090 macro is not, however, and in any case it's best to change to
5091 use the more natural keyword argument processing offered by
5094 Multiple return values are treated differently by the two
5095 Common Lisp packages. The old package's method was more
5096 compatible with true Common Lisp, though it used heuristics
5097 that caused it to report spurious multiple return values in
5098 certain cases. The @code{cl-compat} package defines a set
5099 of multiple-value macros that are compatible with the old
5100 CL package; again, they are heuristic in nature, but they
5101 are guaranteed to work in any case where the old package's
5102 macros worked. To avoid name collision with the ``official''
5103 multiple-value facilities, the ones in @code{cl-compat} have
5104 capitalized names: @code{Values}, @code{Values-list},
5105 @code{Multiple-value-bind}, etc.
5107 The functions @code{cl-floor}, @code{cl-ceiling}, @code{cl-truncate},
5108 and @code{cl-round} are defined by @code{cl-compat} to use the
5109 old-style multiple-value mechanism, just as they did in the old
5110 package. The newer @code{floor*} and friends return their two
5111 results in a list rather than as multiple values. Note that
5112 older versions of the old package used the unadorned names
5113 @code{floor}, @code{ceiling}, etc.; @code{cl-compat} cannot use
5114 these names because they conflict with Emacs built-ins.
5116 @node Porting Common Lisp, GNU Free Documentation License, Old CL Compatibility, Top
5117 @appendix Porting Common Lisp
5120 This package is meant to be used as an extension to Emacs Lisp,
5121 not as an Emacs implementation of true Common Lisp. Some of the
5122 remaining differences between Emacs Lisp and Common Lisp make it
5123 difficult to port large Common Lisp applications to Emacs. For
5124 one, some of the features in this package are not fully compliant
5125 with ANSI or Steele; @pxref{Common Lisp Compatibility}. But there
5126 are also quite a few features that this package does not provide
5127 at all. Here are some major omissions that you will want to watch out
5128 for when bringing Common Lisp code into Emacs.
5132 Case-insensitivity. Symbols in Common Lisp are case-insensitive
5133 by default. Some programs refer to a function or variable as
5134 @code{foo} in one place and @code{Foo} or @code{FOO} in another.
5135 Emacs Lisp will treat these as three distinct symbols.
5137 Some Common Lisp code is written entirely in upper case. While Emacs
5138 is happy to let the program's own functions and variables use
5139 this convention, calls to Lisp builtins like @code{if} and
5140 @code{defun} will have to be changed to lower case.
5143 Lexical scoping. In Common Lisp, function arguments and @code{let}
5144 bindings apply only to references physically within their bodies
5145 (or within macro expansions in their bodies). Emacs Lisp, by
5146 contrast, uses @dfn{dynamic scoping} wherein a binding to a
5147 variable is visible even inside functions called from the body.
5149 Variables in Common Lisp can be made dynamically scoped by
5150 declaring them @code{special} or using @code{defvar}. In Emacs
5151 Lisp it is as if all variables were declared @code{special}.
5153 Often you can use code that was written for lexical scoping
5154 even in a dynamically scoped Lisp, but not always. Here is
5155 an example of a Common Lisp code fragment that would fail in
5159 (defun map-odd-elements (func list)
5161 for flag = t then (not flag)
5162 collect (if flag x (funcall func x))))
5164 (defun add-odd-elements (list x)
5165 (map-odd-elements (lambda (a) (+ a x)) list))
5169 In Common Lisp, the two functions' usages of @code{x} are completely
5170 independent. In Emacs Lisp, the binding to @code{x} made by
5171 @code{add-odd-elements} will have been hidden by the binding
5172 in @code{map-odd-elements} by the time the @code{(+ a x)} function
5175 (This package avoids such problems in its own mapping functions
5176 by using names like @code{cl-x} instead of @code{x} internally;
5177 as long as you don't use the @code{cl-} prefix for your own
5178 variables no collision can occur.)
5180 @xref{Lexical Bindings}, for a description of the @code{lexical-let}
5181 form which establishes a Common Lisp-style lexical binding, and some
5182 examples of how it differs from Emacs' regular @code{let}.
5185 Reader macros. Common Lisp includes a second type of macro that
5186 works at the level of individual characters. For example, Common
5187 Lisp implements the quote notation by a reader macro called @code{'},
5188 whereas Emacs Lisp's parser just treats quote as a special case.
5189 Some Lisp packages use reader macros to create special syntaxes
5190 for themselves, which the Emacs parser is incapable of reading.
5193 Other syntactic features. Common Lisp provides a number of
5194 notations beginning with @code{#} that the Emacs Lisp parser
5195 won't understand. For example, @samp{#| ... |#} is an
5196 alternate comment notation, and @samp{#+lucid (foo)} tells
5197 the parser to ignore the @code{(foo)} except in Lucid Common
5201 Packages. In Common Lisp, symbols are divided into @dfn{packages}.
5202 Symbols that are Lisp built-ins are typically stored in one package;
5203 symbols that are vendor extensions are put in another, and each
5204 application program would have a package for its own symbols.
5205 Certain symbols are ``exported'' by a package and others are
5206 internal; certain packages ``use'' or import the exported symbols
5207 of other packages. To access symbols that would not normally be
5208 visible due to this importing and exporting, Common Lisp provides
5209 a syntax like @code{package:symbol} or @code{package::symbol}.
5211 Emacs Lisp has a single namespace for all interned symbols, and
5212 then uses a naming convention of putting a prefix like @code{cl-}
5213 in front of the name. Some Emacs packages adopt the Common Lisp-like
5214 convention of using @code{cl:} or @code{cl::} as the prefix.
5215 However, the Emacs parser does not understand colons and just
5216 treats them as part of the symbol name. Thus, while @code{mapcar}
5217 and @code{lisp:mapcar} may refer to the same symbol in Common
5218 Lisp, they are totally distinct in Emacs Lisp. Common Lisp
5219 programs which refer to a symbol by the full name sometimes
5220 and the short name other times will not port cleanly to Emacs.
5222 Emacs Lisp does have a concept of ``obarrays,'' which are
5223 package-like collections of symbols, but this feature is not
5224 strong enough to be used as a true package mechanism.
5227 The @code{format} function is quite different between Common
5228 Lisp and Emacs Lisp. It takes an additional ``destination''
5229 argument before the format string. A destination of @code{nil}
5230 means to format to a string as in Emacs Lisp; a destination
5231 of @code{t} means to write to the terminal (similar to
5232 @code{message} in Emacs). Also, format control strings are
5233 utterly different; @code{~} is used instead of @code{%} to
5234 introduce format codes, and the set of available codes is
5235 much richer. There are no notations like @code{\n} for
5236 string literals; instead, @code{format} is used with the
5237 ``newline'' format code, @code{~%}. More advanced formatting
5238 codes provide such features as paragraph filling, case
5239 conversion, and even loops and conditionals.
5241 While it would have been possible to implement most of Common
5242 Lisp @code{format} in this package (under the name @code{format*},
5243 of course), it was not deemed worthwhile. It would have required
5244 a huge amount of code to implement even a decent subset of
5245 @code{format*}, yet the functionality it would provide over
5246 Emacs Lisp's @code{format} would rarely be useful.
5249 Vector constants use square brackets in Emacs Lisp, but
5250 @code{#(a b c)} notation in Common Lisp. To further complicate
5251 matters, Emacs has its own @code{#(} notation for
5252 something entirely different---strings with properties.
5255 Characters are distinct from integers in Common Lisp. The notation
5256 for character constants is also different: @code{#\A} in Common Lisp
5257 where Emacs Lisp uses @code{?A}. Also, @code{string=} and
5258 @code{string-equal} are synonyms in Emacs Lisp, whereas the latter is
5259 case-insensitive in Common Lisp.
5262 Data types. Some Common Lisp data types do not exist in Emacs
5263 Lisp. Rational numbers and complex numbers are not present,
5264 nor are large integers (all integers are ``fixnums''). All
5265 arrays are one-dimensional. There are no readtables or pathnames;
5266 streams are a set of existing data types rather than a new data
5267 type of their own. Hash tables, random-states, structures, and
5268 packages (obarrays) are built from Lisp vectors or lists rather
5269 than being distinct types.
5272 The Common Lisp Object System (CLOS) is not implemented,
5273 nor is the Common Lisp Condition System. However, the EIEIO package
5274 (@pxref{Top, , Introduction, eieio, EIEIO}) does implement some
5278 Common Lisp features that are completely redundant with Emacs
5279 Lisp features of a different name generally have not been
5280 implemented. For example, Common Lisp writes @code{defconstant}
5281 where Emacs Lisp uses @code{defconst}. Similarly, @code{make-list}
5282 takes its arguments in different ways in the two Lisps but does
5283 exactly the same thing, so this package has not bothered to
5284 implement a Common Lisp-style @code{make-list}.
5287 A few more notable Common Lisp features not included in this
5288 package: @code{compiler-let}, @code{tagbody}, @code{prog},
5289 @code{ldb/dpb}, @code{parse-integer}, @code{cerror}.
5292 Recursion. While recursion works in Emacs Lisp just like it
5293 does in Common Lisp, various details of the Emacs Lisp system
5294 and compiler make recursion much less efficient than it is in
5295 most Lisps. Some schools of thought prefer to use recursion
5296 in Lisp over other techniques; they would sum a list of
5297 numbers using something like
5300 (defun sum-list (list)
5302 (+ (car list) (sum-list (cdr list)))
5307 where a more iteratively-minded programmer might write one of
5311 (let ((total 0)) (dolist (x my-list) (incf total x)) total)
5312 (loop for x in my-list sum x)
5315 While this would be mainly a stylistic choice in most Common Lisps,
5316 in Emacs Lisp you should be aware that the iterative forms are
5317 much faster than recursion. Also, Lisp programmers will want to
5318 note that the current Emacs Lisp compiler does not optimize tail
5322 @node GNU Free Documentation License, Function Index, Porting Common Lisp, Top
5323 @appendix GNU Free Documentation License
5324 @include doclicense.texi
5326 @node Function Index, Variable Index, GNU Free Documentation License, Top
5327 @unnumbered Function Index
5331 @node Variable Index, , Function Index, Top
5332 @unnumbered Variable Index