1 \input texinfo @c -*-texinfo-*-
2 @setfilename ../../info/cl
3 @settitle Common Lisp Extensions
7 This file documents the GNU Emacs Common Lisp emulation package.
9 Copyright @copyright{} 1993, 2001-2012 Free Software Foundation, Inc.
12 Permission is granted to copy, distribute and/or modify this document
13 under the terms of the GNU Free Documentation License, Version 1.3 or
14 any later version published by the Free Software Foundation; with no
15 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
16 and with the Back-Cover Texts as in (a) below. A copy of the license
17 is included in the section entitled ``GNU Free Documentation License''.
19 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
20 modify this GNU manual. Buying copies from the FSF supports it in
21 developing GNU and promoting software freedom.''
25 @dircategory Emacs lisp libraries
27 * CL: (cl). Partial Common Lisp support for Emacs Lisp.
34 @center @titlefont{Common Lisp Extensions}
36 @center For GNU Emacs Lisp
38 @center as distributed with Emacs @value{EMACSVER}
40 @center Dave Gillespie
41 @center daveg@@synaptics.com
43 @vskip 0pt plus 1filll
51 @top GNU Emacs Common Lisp Emulation
57 * Overview:: Basics, usage, etc.
58 * Program Structure:: Arglists, @code{cl-eval-when}, @code{defalias}.
59 * Predicates:: @code{cl-typep} and @code{cl-equalp}.
60 * Control Structure:: @code{setf}, @code{cl-do}, @code{cl-loop}, etc.
61 * Macros:: Destructuring, @code{cl-define-compiler-macro}.
62 * Declarations:: @code{cl-proclaim}, @code{cl-declare}, etc.
63 * Symbols:: Property lists, @code{cl-gensym}.
64 * Numbers:: Predicates, functions, random numbers.
65 * Sequences:: Mapping, functions, searching, sorting.
66 * Lists:: @code{cl-caddr}, @code{cl-sublis}, @code{cl-member}, @code{cl-assoc}, etc.
67 * Structures:: @code{cl-defstruct}.
68 * Assertions:: @code{cl-check-type}, @code{cl-assert}, @code{ignore-errors}.
70 * Efficiency Concerns:: Hints and techniques.
71 * Common Lisp Compatibility:: All known differences with Steele.
72 * Old CL Compatibility:: All known differences with old cl.el.
73 * Porting Common Lisp:: Hints for porting Common Lisp code.
75 * GNU Free Documentation License:: The license for this documentation.
84 This document describes a set of Emacs Lisp facilities borrowed from
85 Common Lisp. All the facilities are described here in detail. While
86 this document does not assume any prior knowledge of Common Lisp, it
87 does assume a basic familiarity with Emacs Lisp.
89 Common Lisp is a huge language, and Common Lisp systems tend to be
90 massive and extremely complex. Emacs Lisp, by contrast, is rather
91 minimalist in the choice of Lisp features it offers the programmer.
92 As Emacs Lisp programmers have grown in number, and the applications
93 they write have grown more ambitious, it has become clear that Emacs
94 Lisp could benefit from many of the conveniences of Common Lisp.
96 The @code{CL} package adds a number of Common Lisp functions and
97 control structures to Emacs Lisp. While not a 100% complete
98 implementation of Common Lisp, @code{CL} adds enough functionality
99 to make Emacs Lisp programming significantly more convenient.
101 Some Common Lisp features have been omitted from this package
106 Some features are too complex or bulky relative to their benefit
107 to Emacs Lisp programmers. CLOS and Common Lisp streams are fine
108 examples of this group.
111 Other features cannot be implemented without modification to the
112 Emacs Lisp interpreter itself, such as multiple return values,
113 case-insensitive symbols, and complex numbers.
114 The @code{CL} package generally makes no attempt to emulate these
119 The package described here was originally written by Dave Gillespie,
120 @file{daveg@@synaptics.com}, as a total rewrite of an earlier
121 1986 @file{cl.el} package by Cesar Quiroz. Most features of the
122 Quiroz package were retained; any incompatibilities are
123 noted in the descriptions below. Care has been taken in this
124 version to ensure that each function is defined efficiently,
125 concisely, and with minimal impact on the rest of the Emacs
126 environment. Stefan Monnier added the file @file{cl-lib.el} and
127 rationalized the namespace for Emacs 24.3.
130 * Usage:: How to use the CL package.
131 * Organization:: The package's five component files.
132 * Naming Conventions:: Notes on CL function names.
139 The @code{CL} package is distributed with Emacs, so there is no need
140 to install any additional files in order to start using it. Lisp code
141 that uses features from the @code{CL} package should simply include at
149 You may wish to add such a statement to your init file, if you
150 make frequent use of CL features.
153 @section Organization
156 The Common Lisp package is organized into four main files:
160 This is the main file, which contains basic functions
161 and information about the package. This file is relatively compact.
164 This file contains the larger, more complex or unusual functions.
165 It is kept separate so that packages which only want to use Common
166 Lisp fundamentals like the @code{cl-incf} function won't need to pay
167 the overhead of loading the more advanced functions.
170 This file contains most of the advanced functions for operating
171 on sequences or lists, such as @code{cl-delete-if} and @code{cl-assoc}.
174 This file contains the features that are macros instead of functions.
175 Macros expand when the caller is compiled, not when it is run, so the
176 macros generally only need to be present when the byte-compiler is
177 running (or when the macros are used in uncompiled code). Most of the
178 macros of this package are isolated in @file{cl-macs.el} so that they
179 won't take up memory unless you are compiling.
182 The file @file{cl-lib.el} includes all necessary @code{autoload}
183 commands for the functions and macros in the other three files.
184 All you have to do is @code{(require 'cl-lib)}, and @file{cl-lib.el}
185 will take care of pulling in the other files when they are
188 There is another file, @file{cl.el}, which was the main entry point
189 to the CL package prior to Emacs 24.3. Nowadays, it is replaced
190 by @file{cl-lib.el}. The two provide the same features, but use
191 different function names (in fact, @file{cl.el} just defines aliases
192 to the @file{cl-lib.el} definitions). In particular, the old @file{cl.el}
193 does not use a clean namespace. For this reason, Emacs has a policy
194 that packages distributed with Emacs must not load @code{cl} at run time.
195 (It is ok for them to load @code{cl} at @emph{compile} time, with
196 @code{eval-when-compile}, and use the macros it provides.) There is
197 no such restriction on the use of @code{cl-lib}. New code should use
198 @code{cl-lib} rather than @code{cl}. @xref{Naming Conventions}.
200 There is one more file, @file{cl-compat.el}, which defines some
201 routines from the older CL package that are not otherwise
202 present in the new package. This includes internal routines
203 like @code{setelt} and @code{zip-lists}, deprecated features
204 like @code{defkeyword}, and an emulation of the old-style
205 multiple-values feature. This file is obsolete and should not be used
206 in new code. @xref{Old CL Compatibility}.
208 @node Naming Conventions
209 @section Naming Conventions
212 Except where noted, all functions defined by this package have the
213 same calling conventions as their Common Lisp counterparts, and
214 names that are those of Common Lisp plus a @samp{cl-} prefix.
216 Internal function and variable names in the package are prefixed
217 by @code{cl--}. Here is a complete list of functions prefixed by
218 @code{cl-} that were not taken from Common Lisp:
220 @c FIXME lexical-let lexical-let*
222 cl-callf cl-callf2 cl-defsubst
223 cl-floatp-safe cl-letf cl-letf*
226 The following simple functions and macros are defined in @file{cl-lib.el};
227 they do not cause other components like @file{cl-extra} to be loaded.
230 cl-floatp-safe cl-endp
231 cl-evenp cl-oddp cl-plusp cl-minusp
232 cl-caaar .. cl-cddddr
233 cl-list* cl-ldiff cl-rest cl-first .. cl-tenth
234 cl-copy-list cl-subst cl-mapcar [2]
235 cl-adjoin [3] cl-acons cl-pairlis
236 cl-pushnew [3,4] cl-incf [4] cl-decf [4]
237 cl-proclaim cl-declaim
241 [2] Only for one sequence argument or two list arguments.
244 [3] Only if @code{:test} is @code{eq}, @code{equal}, or unspecified,
245 and @code{:key} is not used.
248 [4] Only when @var{place} is a plain variable name.
250 @node Program Structure
251 @chapter Program Structure
254 This section describes features of the @code{CL} package that have to
255 do with programs as a whole: advanced argument lists for functions,
256 and the @code{cl-eval-when} construct.
259 * Argument Lists:: @code{&key}, @code{&aux}, @code{cl-defun}, @code{cl-defmacro}.
260 * Time of Evaluation:: The @code{cl-eval-when} construct.
268 @section Argument Lists
271 Emacs Lisp's notation for argument lists of functions is a subset of
272 the Common Lisp notation. As well as the familiar @code{&optional}
273 and @code{&rest} markers, Common Lisp allows you to specify default
274 values for optional arguments, and it provides the additional markers
275 @code{&key} and @code{&aux}.
277 Since argument parsing is built-in to Emacs, there is no way for
278 this package to implement Common Lisp argument lists seamlessly.
279 Instead, this package defines alternates for several Lisp forms
280 which you must use if you need Common Lisp argument lists.
282 @defspec cl-defun name arglist body...
283 This form is identical to the regular @code{defun} form, except
284 that @var{arglist} is allowed to be a full Common Lisp argument
285 list. Also, the function body is enclosed in an implicit block
286 called @var{name}; @pxref{Blocks and Exits}.
289 @defspec cl-defsubst name arglist body...
290 This is just like @code{cl-defun}, except that the function that
291 is defined is automatically proclaimed @code{inline}, i.e.,
292 calls to it may be expanded into in-line code by the byte compiler.
293 This is analogous to the @code{defsubst} form;
294 @code{cl-defsubst} uses a different method (compiler macros) which
295 works in all versions of Emacs, and also generates somewhat more
296 efficient inline expansions. In particular, @code{cl-defsubst}
297 arranges for the processing of keyword arguments, default values,
298 etc., to be done at compile-time whenever possible.
301 @defspec cl-defmacro name arglist body...
302 This is identical to the regular @code{defmacro} form,
303 except that @var{arglist} is allowed to be a full Common Lisp
304 argument list. The @code{&environment} keyword is supported as
305 described in Steele. The @code{&whole} keyword is supported only
306 within destructured lists (see below); top-level @code{&whole}
307 cannot be implemented with the current Emacs Lisp interpreter.
308 The macro expander body is enclosed in an implicit block called
312 @defspec cl-function symbol-or-lambda
313 This is identical to the regular @code{function} form,
314 except that if the argument is a @code{lambda} form then that
315 form may use a full Common Lisp argument list.
318 Also, all forms (such as @code{cl-flet} and @code{cl-labels}) defined
319 in this package that include @var{arglist}s in their syntax allow
320 full Common Lisp argument lists.
322 Note that it is @emph{not} necessary to use @code{cl-defun} in
323 order to have access to most @code{CL} features in your function.
324 These features are always present; @code{cl-defun}'s only
325 difference from @code{defun} is its more flexible argument
326 lists and its implicit block.
328 The full form of a Common Lisp argument list is
332 &optional (@var{var} @var{initform} @var{svar})...
334 &key ((@var{keyword} @var{var}) @var{initform} @var{svar})...
335 &aux (@var{var} @var{initform})...)
338 Each of the five argument list sections is optional. The @var{svar},
339 @var{initform}, and @var{keyword} parts are optional; if they are
340 omitted, then @samp{(@var{var})} may be written simply @samp{@var{var}}.
342 The first section consists of zero or more @dfn{required} arguments.
343 These arguments must always be specified in a call to the function;
344 there is no difference between Emacs Lisp and Common Lisp as far as
345 required arguments are concerned.
347 The second section consists of @dfn{optional} arguments. These
348 arguments may be specified in the function call; if they are not,
349 @var{initform} specifies the default value used for the argument.
350 (No @var{initform} means to use @code{nil} as the default.) The
351 @var{initform} is evaluated with the bindings for the preceding
352 arguments already established; @code{(a &optional (b (1+ a)))}
353 matches one or two arguments, with the second argument defaulting
354 to one plus the first argument. If the @var{svar} is specified,
355 it is an auxiliary variable which is bound to @code{t} if the optional
356 argument was specified, or to @code{nil} if the argument was omitted.
357 If you don't use an @var{svar}, then there will be no way for your
358 function to tell whether it was called with no argument, or with
359 the default value passed explicitly as an argument.
361 The third section consists of a single @dfn{rest} argument. If
362 more arguments were passed to the function than are accounted for
363 by the required and optional arguments, those extra arguments are
364 collected into a list and bound to the ``rest'' argument variable.
365 Common Lisp's @code{&rest} is equivalent to that of Emacs Lisp.
366 Common Lisp accepts @code{&body} as a synonym for @code{&rest} in
367 macro contexts; this package accepts it all the time.
369 The fourth section consists of @dfn{keyword} arguments. These
370 are optional arguments which are specified by name rather than
371 positionally in the argument list. For example,
374 (cl-defun foo (a &optional b &key c d (e 17)))
378 defines a function which may be called with one, two, or more
379 arguments. The first two arguments are bound to @code{a} and
380 @code{b} in the usual way. The remaining arguments must be
381 pairs of the form @code{:c}, @code{:d}, or @code{:e} followed
382 by the value to be bound to the corresponding argument variable.
383 (Symbols whose names begin with a colon are called @dfn{keywords},
384 and they are self-quoting in the same way as @code{nil} and
387 For example, the call @code{(foo 1 2 :d 3 :c 4)} sets the five
388 arguments to 1, 2, 4, 3, and 17, respectively. If the same keyword
389 appears more than once in the function call, the first occurrence
390 takes precedence over the later ones. Note that it is not possible
391 to specify keyword arguments without specifying the optional
392 argument @code{b} as well, since @code{(foo 1 :c 2)} would bind
393 @code{b} to the keyword @code{:c}, then signal an error because
394 @code{2} is not a valid keyword.
396 You can also explicitly specify the keyword argument; it need not be
397 simply the variable name prefixed with a colon. For example,
400 (cl-defun bar (&key (a 1) ((baz b) 4)))
405 specifies a keyword @code{:a} that sets the variable @code{a} with
406 default value 1, as well as a keyword @code{baz} that sets the
407 variable @code{b} with default value 4. In this case, because
408 @code{baz} is not self-quoting, you must quote it explicitly in the
409 function call, like this:
415 Ordinarily, it is an error to pass an unrecognized keyword to
416 a function, e.g., @code{(foo 1 2 :c 3 :goober 4)}. You can ask
417 Lisp to ignore unrecognized keywords, either by adding the
418 marker @code{&allow-other-keys} after the keyword section
419 of the argument list, or by specifying an @code{:allow-other-keys}
420 argument in the call whose value is non-@code{nil}. If the
421 function uses both @code{&rest} and @code{&key} at the same time,
422 the ``rest'' argument is bound to the keyword list as it appears
423 in the call. For example:
426 (cl-defun find-thing (thing &rest rest &key need &allow-other-keys)
427 (or (apply 'cl-member thing thing-list :allow-other-keys t rest)
428 (if need (error "Thing not found"))))
432 This function takes a @code{:need} keyword argument, but also
433 accepts other keyword arguments which are passed on to the
434 @code{cl-member} function. @code{allow-other-keys} is used to
435 keep both @code{find-thing} and @code{cl-member} from complaining
436 about each others' keywords in the arguments.
438 The fifth section of the argument list consists of @dfn{auxiliary
439 variables}. These are not really arguments at all, but simply
440 variables which are bound to @code{nil} or to the specified
441 @var{initforms} during execution of the function. There is no
442 difference between the following two functions, except for a
443 matter of stylistic taste:
446 (cl-defun foo (a b &aux (c (+ a b)) d)
454 Argument lists support @dfn{destructuring}. In Common Lisp,
455 destructuring is only allowed with @code{defmacro}; this package
456 allows it with @code{cl-defun} and other argument lists as well.
457 In destructuring, any argument variable (@var{var} in the above
458 diagram) can be replaced by a list of variables, or more generally,
459 a recursive argument list. The corresponding argument value must
460 be a list whose elements match this recursive argument list.
464 (cl-defmacro dolist ((var listform &optional resultform)
469 This says that the first argument of @code{dolist} must be a list
470 of two or three items; if there are other arguments as well as this
471 list, they are stored in @code{body}. All features allowed in
472 regular argument lists are allowed in these recursive argument lists.
473 In addition, the clause @samp{&whole @var{var}} is allowed at the
474 front of a recursive argument list. It binds @var{var} to the
475 whole list being matched; thus @code{(&whole all a b)} matches
476 a list of two things, with @code{a} bound to the first thing,
477 @code{b} bound to the second thing, and @code{all} bound to the
478 list itself. (Common Lisp allows @code{&whole} in top-level
479 @code{defmacro} argument lists as well, but Emacs Lisp does not
482 One last feature of destructuring is that the argument list may be
483 dotted, so that the argument list @code{(a b . c)} is functionally
484 equivalent to @code{(a b &rest c)}.
486 If the optimization quality @code{safety} is set to 0
487 (@pxref{Declarations}), error checking for wrong number of
488 arguments and invalid keyword arguments is disabled. By default,
489 argument lists are rigorously checked.
491 @node Time of Evaluation
492 @section Time of Evaluation
495 Normally, the byte-compiler does not actually execute the forms in
496 a file it compiles. For example, if a file contains @code{(setq foo t)},
497 the act of compiling it will not actually set @code{foo} to @code{t}.
498 This is true even if the @code{setq} was a top-level form (i.e., not
499 enclosed in a @code{defun} or other form). Sometimes, though, you
500 would like to have certain top-level forms evaluated at compile-time.
501 For example, the compiler effectively evaluates @code{defmacro} forms
502 at compile-time so that later parts of the file can refer to the
503 macros that are defined.
505 @defspec cl-eval-when (situations...) forms...
506 This form controls when the body @var{forms} are evaluated.
507 The @var{situations} list may contain any set of the symbols
508 @code{compile}, @code{load}, and @code{eval} (or their long-winded
509 ANSI equivalents, @code{:compile-toplevel}, @code{:load-toplevel},
510 and @code{:execute}).
512 The @code{cl-eval-when} form is handled differently depending on
513 whether or not it is being compiled as a top-level form.
514 Specifically, it gets special treatment if it is being compiled
515 by a command such as @code{byte-compile-file} which compiles files
516 or buffers of code, and it appears either literally at the
517 top level of the file or inside a top-level @code{progn}.
519 For compiled top-level @code{cl-eval-when}s, the body @var{forms} are
520 executed at compile-time if @code{compile} is in the @var{situations}
521 list, and the @var{forms} are written out to the file (to be executed
522 at load-time) if @code{load} is in the @var{situations} list.
524 For non-compiled-top-level forms, only the @code{eval} situation is
525 relevant. (This includes forms executed by the interpreter, forms
526 compiled with @code{byte-compile} rather than @code{byte-compile-file},
527 and non-top-level forms.) The @code{cl-eval-when} acts like a
528 @code{progn} if @code{eval} is specified, and like @code{nil}
529 (ignoring the body @var{forms}) if not.
531 The rules become more subtle when @code{cl-eval-when}s are nested;
532 consult Steele (second edition) for the gruesome details (and
533 some gruesome examples).
535 Some simple examples:
538 ;; Top-level forms in foo.el:
539 (cl-eval-when (compile) (setq foo1 'bar))
540 (cl-eval-when (load) (setq foo2 'bar))
541 (cl-eval-when (compile load) (setq foo3 'bar))
542 (cl-eval-when (eval) (setq foo4 'bar))
543 (cl-eval-when (eval compile) (setq foo5 'bar))
544 (cl-eval-when (eval load) (setq foo6 'bar))
545 (cl-eval-when (eval compile load) (setq foo7 'bar))
548 When @file{foo.el} is compiled, these variables will be set during
549 the compilation itself:
552 foo1 foo3 foo5 foo7 ; `compile'
555 When @file{foo.elc} is loaded, these variables will be set:
558 foo2 foo3 foo6 foo7 ; `load'
561 And if @file{foo.el} is loaded uncompiled, these variables will
565 foo4 foo5 foo6 foo7 ; `eval'
568 If these seven @code{cl-eval-when}s had been, say, inside a @code{defun},
569 then the first three would have been equivalent to @code{nil} and the
570 last four would have been equivalent to the corresponding @code{setq}s.
572 Note that @code{(cl-eval-when (load eval) @dots{})} is equivalent
573 to @code{(progn @dots{})} in all contexts. The compiler treats
574 certain top-level forms, like @code{defmacro} (sort-of) and
575 @code{require}, as if they were wrapped in @code{(eval-when
576 (compile load eval) @dots{})}.
579 Emacs includes two special forms related to @code{cl-eval-when}.
580 One of these, @code{eval-when-compile}, is not quite equivalent to
581 any @code{eval-when} construct and is described below.
583 The other form, @code{(eval-and-compile @dots{})}, is exactly
584 equivalent to @samp{(eval-when (compile load eval) @dots{})} and
585 so is not itself defined by this package.
587 @defspec eval-when-compile forms...
588 The @var{forms} are evaluated at compile-time; at execution time,
589 this form acts like a quoted constant of the resulting value. Used
590 at top-level, @code{eval-when-compile} is just like @samp{eval-when
591 (compile eval)}. In other contexts, @code{eval-when-compile}
592 allows code to be evaluated once at compile-time for efficiency
595 This form is similar to the @samp{#.} syntax of true Common Lisp.
598 @defspec cl-load-time-value form
599 The @var{form} is evaluated at load-time; at execution time,
600 this form acts like a quoted constant of the resulting value.
602 Early Common Lisp had a @samp{#,} syntax that was similar to
603 this, but ANSI Common Lisp replaced it with @code{load-time-value}
604 and gave it more well-defined semantics.
606 In a compiled file, @code{cl-load-time-value} arranges for @var{form}
607 to be evaluated when the @file{.elc} file is loaded and then used
608 as if it were a quoted constant. In code compiled by
609 @code{byte-compile} rather than @code{byte-compile-file}, the
610 effect is identical to @code{eval-when-compile}. In uncompiled
611 code, both @code{eval-when-compile} and @code{cl-load-time-value}
612 act exactly like @code{progn}.
616 (insert "This function was executed on: "
617 (current-time-string)
619 (eval-when-compile (current-time-string))
620 ;; or '#.(current-time-string) in real Common Lisp
622 (cl-load-time-value (current-time-string))))
626 Byte-compiled, the above defun will result in the following code
627 (or its compiled equivalent, of course) in the @file{.elc} file:
630 (setq --temp-- (current-time-string))
632 (insert "This function was executed on: "
633 (current-time-string)
635 '"Wed Jun 23 18:33:43 1993"
645 This section describes functions for testing whether various
646 facts are true or false.
649 * Type Predicates:: @code{cl-typep}, @code{cl-deftype}, and @code{cl-coerce}.
650 * Equality Predicates:: @code{cl-equalp}.
653 @node Type Predicates
654 @section Type Predicates
657 The @code{CL} package defines a version of the Common Lisp @code{typep}
660 @defun cl-typep object type
661 Check if @var{object} is of type @var{type}, where @var{type} is a
662 (quoted) type name of the sort used by Common Lisp. For example,
663 @code{(cl-typep foo 'integer)} is equivalent to @code{(integerp foo)}.
666 The @var{type} argument to the above function is either a symbol
667 or a list beginning with a symbol.
671 If the type name is a symbol, Emacs appends @samp{-p} to the
672 symbol name to form the name of a predicate function for testing
673 the type. (Built-in predicates whose names end in @samp{p} rather
674 than @samp{-p} are used when appropriate.)
677 The type symbol @code{t} stands for the union of all types.
678 @code{(cl-typep @var{object} t)} is always true. Likewise, the
679 type symbol @code{nil} stands for nothing at all, and
680 @code{(cl-typep @var{object} nil)} is always false.
683 The type symbol @code{null} represents the symbol @code{nil}.
684 Thus @code{(cl-typep @var{object} 'null)} is equivalent to
685 @code{(null @var{object})}.
688 The type symbol @code{atom} represents all objects that are not cons
689 cells. Thus @code{(cl-typep @var{object} 'atom)} is equivalent to
690 @code{(atom @var{object})}.
693 The type symbol @code{real} is a synonym for @code{number}, and
694 @code{fixnum} is a synonym for @code{integer}.
697 The type symbols @code{character} and @code{string-char} match
698 integers in the range from 0 to 255.
701 The type symbol @code{float} uses the @code{cl-floatp-safe} predicate
702 defined by this package rather than @code{floatp}, so it will work
703 correctly even in Emacs versions without floating-point support.
706 The type list @code{(integer @var{low} @var{high})} represents all
707 integers between @var{low} and @var{high}, inclusive. Either bound
708 may be a list of a single integer to specify an exclusive limit,
709 or a @code{*} to specify no limit. The type @code{(integer * *)}
710 is thus equivalent to @code{integer}.
713 Likewise, lists beginning with @code{float}, @code{real}, or
714 @code{number} represent numbers of that type falling in a particular
718 Lists beginning with @code{and}, @code{or}, and @code{not} form
719 combinations of types. For example, @code{(or integer (float 0 *))}
720 represents all objects that are integers or non-negative floats.
723 Lists beginning with @code{member} or @code{cl-member} represent
724 objects @code{eql} to any of the following values. For example,
725 @code{(member 1 2 3 4)} is equivalent to @code{(integer 1 4)},
726 and @code{(member nil)} is equivalent to @code{null}.
729 Lists of the form @code{(satisfies @var{predicate})} represent
730 all objects for which @var{predicate} returns true when called
731 with that object as an argument.
734 The following function and macro (not technically predicates) are
735 related to @code{cl-typep}.
737 @defun cl-coerce object type
738 This function attempts to convert @var{object} to the specified
739 @var{type}. If @var{object} is already of that type as determined by
740 @code{typep}, it is simply returned. Otherwise, certain types of
741 conversions will be made: If @var{type} is any sequence type
742 (@code{string}, @code{list}, etc.) then @var{object} will be
743 converted to that type if possible. If @var{type} is
744 @code{character}, then strings of length one and symbols with
745 one-character names can be coerced. If @var{type} is @code{float},
746 then integers can be coerced in versions of Emacs that support
747 floats. In all other circumstances, @code{cl-coerce} signals an
751 @defspec cl-deftype name arglist forms...
752 This macro defines a new type called @var{name}. It is similar
753 to @code{defmacro} in many ways; when @var{name} is encountered
754 as a type name, the body @var{forms} are evaluated and should
755 return a type specifier that is equivalent to the type. The
756 @var{arglist} is a Common Lisp argument list of the sort accepted
757 by @code{cl-defmacro}. The type specifier @samp{(@var{name} @var{args}...)}
758 is expanded by calling the expander with those arguments; the type
759 symbol @samp{@var{name}} is expanded by calling the expander with
760 no arguments. The @var{arglist} is processed the same as for
761 @code{cl-defmacro} except that optional arguments without explicit
762 defaults use @code{*} instead of @code{nil} as the ``default''
763 default. Some examples:
766 (cl-deftype null () '(satisfies null)) ; predefined
767 (cl-deftype list () '(or null cons)) ; predefined
768 (cl-deftype unsigned-byte (&optional bits)
769 (list 'integer 0 (if (eq bits '*) bits (1- (lsh 1 bits)))))
770 (unsigned-byte 8) @equiv{} (integer 0 255)
771 (unsigned-byte) @equiv{} (integer 0 *)
772 unsigned-byte @equiv{} (integer 0 *)
776 The last example shows how the Common Lisp @code{unsigned-byte}
777 type specifier could be implemented if desired; this package does
778 not implement @code{unsigned-byte} by default.
781 The @code{cl-typecase} and @code{cl-check-type} macros also use type
782 names. @xref{Conditionals}. @xref{Assertions}. The @code{cl-map},
783 @code{cl-concatenate}, and @code{cl-merge} functions take type-name
784 arguments to specify the type of sequence to return. @xref{Sequences}.
786 @node Equality Predicates
787 @section Equality Predicates
790 This package defines the Common Lisp predicate @code{cl-equalp}.
793 This function is a more flexible version of @code{equal}. In
794 particular, it compares strings case-insensitively, and it compares
795 numbers without regard to type (so that @code{(cl-equalp 3 3.0)} is
796 true). Vectors and conses are compared recursively. All other
797 objects are compared as if by @code{equal}.
799 This function differs from Common Lisp @code{equalp} in several
800 respects. First, Common Lisp's @code{equalp} also compares
801 @emph{characters} case-insensitively, which would be impractical
802 in this package since Emacs does not distinguish between integers
803 and characters. In keeping with the idea that strings are less
804 vector-like in Emacs Lisp, this package's @code{cl-equalp} also will
805 not compare strings against vectors of integers.
808 Also note that the Common Lisp functions @code{member} and @code{assoc}
809 use @code{eql} to compare elements, whereas Emacs Lisp follows the
810 MacLisp tradition and uses @code{equal} for these two functions.
811 In Emacs, use @code{memq} (or @code{cl-member}) and @code{assq} (or
812 @code{cl-assoc}) to get functions which use @code{eql} for comparisons.
814 @node Control Structure
815 @chapter Control Structure
818 The features described in the following sections implement
819 various advanced control structures, including the powerful
820 @c FIXME setf is now in gv.el, not cl.
821 @code{setf} facility and a number of looping and conditional
824 @c FIXME setf, push are standard now.
825 @c lexical-let is obsolete; flet is not cl-flet.
826 @c values is not cl-values.
828 * Assignment:: The @code{cl-psetq} form.
829 * Generalized Variables:: @code{setf}, @code{cl-incf}, @code{push}, etc.
830 * Variable Bindings:: @code{cl-progv}, @code{lexical-let}, @code{flet}, @code{cl-macrolet}.
831 * Conditionals:: @code{cl-case}, @code{cl-typecase}.
832 * Blocks and Exits:: @code{cl-block}, @code{cl-return}, @code{cl-return-from}.
833 * Iteration:: @code{cl-do}, @code{cl-dotimes}, @code{cl-dolist}, @code{cl-do-symbols}.
834 * Loop Facility:: The Common Lisp @code{cl-loop} macro.
835 * Multiple Values:: @code{values}, @code{cl-multiple-value-bind}, etc.
842 The @code{cl-psetq} form is just like @code{setq}, except that multiple
843 assignments are done in parallel rather than sequentially.
845 @defspec cl-psetq [symbol form]@dots{}
846 This special form (actually a macro) is used to assign to several
847 variables simultaneously. Given only one @var{symbol} and @var{form},
848 it has the same effect as @code{setq}. Given several @var{symbol}
849 and @var{form} pairs, it evaluates all the @var{form}s in advance
850 and then stores the corresponding variables afterwards.
854 (setq x (+ x y) y (* x y))
857 y ; @r{@code{y} was computed after @code{x} was set.}
860 (cl-psetq x (+ x y) y (* x y))
863 y ; @r{@code{y} was computed before @code{x} was set.}
867 The simplest use of @code{cl-psetq} is @code{(cl-psetq x y y x)}, which
868 exchanges the values of two variables. (The @code{cl-rotatef} form
869 provides an even more convenient way to swap two variables;
870 @pxref{Modify Macros}.)
872 @code{cl-psetq} always returns @code{nil}.
875 @c FIXME now in gv.el.
876 @node Generalized Variables
877 @section Generalized Variables
880 A ``generalized variable'' or ``place form'' is one of the many places
881 in Lisp memory where values can be stored. The simplest place form is
882 a regular Lisp variable. But the cars and cdrs of lists, elements
883 of arrays, properties of symbols, and many other locations are also
884 places where Lisp values are stored.
886 The @code{setf} form is like @code{setq}, except that it accepts
887 arbitrary place forms on the left side rather than just
888 symbols. For example, @code{(setf (car a) b)} sets the car of
889 @code{a} to @code{b}, doing the same operation as @code{(setcar a b)}
890 but without having to remember two separate functions for setting
891 and accessing every type of place.
893 Generalized variables are analogous to ``lvalues'' in the C
894 language, where @samp{x = a[i]} gets an element from an array
895 and @samp{a[i] = x} stores an element using the same notation.
896 Just as certain forms like @code{a[i]} can be lvalues in C, there
897 is a set of forms that can be generalized variables in Lisp.
900 * Basic Setf:: @code{setf} and place forms.
901 * Modify Macros:: @code{cl-incf}, @code{push}, @code{cl-rotatef}, @code{letf}, @code{cl-callf}, etc.
902 * Customizing Setf:: @code{define-modify-macro}, @code{defsetf}, @code{define-setf-method}.
906 @subsection Basic Setf
909 The @code{setf} macro is the most basic way to operate on generalized
912 @defspec setf [place form]@dots{}
913 This macro evaluates @var{form} and stores it in @var{place}, which
914 must be a valid generalized variable form. If there are several
915 @var{place} and @var{form} pairs, the assignments are done sequentially
916 just as with @code{setq}. @code{setf} returns the value of the last
919 The following Lisp forms will work as generalized variables, and
920 so may appear in the @var{place} argument of @code{setf}:
924 A symbol naming a variable. In other words, @code{(setf x y)} is
925 exactly equivalent to @code{(setq x y)}, and @code{setq} itself is
926 strictly speaking redundant now that @code{setf} exists. Many
927 programmers continue to prefer @code{setq} for setting simple
928 variables, though, purely for stylistic or historical reasons.
929 The macro @code{(setf x y)} actually expands to @code{(setq x y)},
930 so there is no performance penalty for using it in compiled code.
933 A call to any of the following Lisp functions:
936 car cdr caar .. cddddr
937 nth rest first .. tenth
939 symbol-function symbol-value symbol-plist
945 Note that for @code{nthcdr} and @code{getf}, the list argument
946 of the function must itself be a valid @var{place} form. For
947 example, @code{(setf (nthcdr 0 foo) 7)} will set @code{foo} itself
948 to 7. Note that @code{push} and @code{pop} on an @code{nthcdr}
949 place can be used to insert or delete at any position in a list.
950 The use of @code{nthcdr} as a @var{place} form is an extension
951 to standard Common Lisp.
954 The following Emacs-specific functions are also @code{setf}-able.
957 buffer-file-name marker-position
958 buffer-modified-p match-data
959 buffer-name mouse-position
960 buffer-string overlay-end
961 buffer-substring overlay-get
962 current-buffer overlay-start
963 current-case-table point
964 current-column point-marker
965 current-global-map point-max
966 current-input-mode point-min
967 current-local-map process-buffer
968 current-window-configuration process-filter
969 default-file-modes process-sentinel
970 default-value read-mouse-position
971 documentation-property screen-height
972 extent-data screen-menubar
973 extent-end-position screen-width
974 extent-start-position selected-window
975 face-background selected-screen
976 face-background-pixmap selected-frame
977 face-font standard-case-table
978 face-foreground syntax-table
979 face-underline-p window-buffer
980 file-modes window-dedicated-p
981 frame-height window-display-table
982 frame-parameters window-height
983 frame-visible-p window-hscroll
984 frame-width window-point
985 get-register window-start
987 global-key-binding x-get-secondary-selection
988 keymap-parent x-get-selection
994 Most of these have directly corresponding ``set'' functions, like
995 @code{use-local-map} for @code{current-local-map}, or @code{goto-char}
996 for @code{point}. A few, like @code{point-min}, expand to longer
997 sequences of code when they are @code{setf}'d (@code{(narrow-to-region
998 x (point-max))} in this case).
1001 A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])},
1002 where @var{subplace} is itself a valid generalized variable whose
1003 current value is a string, and where the value stored is also a
1004 string. The new string is spliced into the specified part of the
1005 destination string. For example:
1008 (setq a (list "hello" "world"))
1009 @result{} ("hello" "world")
1012 (substring (cadr a) 2 4)
1014 (setf (substring (cadr a) 2 4) "o")
1019 @result{} ("hello" "wood")
1022 The generalized variable @code{buffer-substring}, listed above,
1023 also works in this way by replacing a portion of the current buffer.
1026 A call of the form @code{(apply '@var{func} @dots{})} or
1027 @code{(apply (function @var{func}) @dots{})}, where @var{func}
1028 is a @code{setf}-able function whose store function is ``suitable''
1029 in the sense described in Steele's book; since none of the standard
1030 Emacs place functions are suitable in this sense, this feature is
1031 only interesting when used with places you define yourself with
1032 @code{define-setf-method} or the long form of @code{defsetf}.
1035 A macro call, in which case the macro is expanded and @code{setf}
1036 is applied to the resulting form.
1039 Any form for which a @code{defsetf} or @code{define-setf-method}
1043 Using any forms other than these in the @var{place} argument to
1044 @code{setf} will signal an error.
1046 The @code{setf} macro takes care to evaluate all subforms in
1047 the proper left-to-right order; for example,
1050 (setf (aref vec (incf i)) i)
1054 looks like it will evaluate @code{(incf i)} exactly once, before the
1055 following access to @code{i}; the @code{setf} expander will insert
1056 temporary variables as necessary to ensure that it does in fact work
1057 this way no matter what setf-method is defined for @code{aref}.
1058 (In this case, @code{aset} would be used and no such steps would
1059 be necessary since @code{aset} takes its arguments in a convenient
1062 However, if the @var{place} form is a macro which explicitly
1063 evaluates its arguments in an unusual order, this unusual order
1064 will be preserved. Adapting an example from Steele, given
1067 (defmacro wrong-order (x y) (list 'aref y x))
1071 the form @code{(setf (wrong-order @var{a} @var{b}) 17)} will
1072 evaluate @var{b} first, then @var{a}, just as in an actual call
1073 to @code{wrong-order}.
1077 @subsection Modify Macros
1080 This package defines a number of other macros besides @code{setf}
1081 that operate on generalized variables. Many are interesting and
1082 useful even when the @var{place} is just a variable name.
1084 @defspec psetf [place form]@dots{}
1085 This macro is to @code{setf} what @code{cl-psetq} is to @code{setq}:
1086 When several @var{place}s and @var{form}s are involved, the
1087 assignments take place in parallel rather than sequentially.
1088 Specifically, all subforms are evaluated from left to right, then
1089 all the assignments are done (in an undefined order).
1092 @defspec incf place &optional x
1093 This macro increments the number stored in @var{place} by one, or
1094 by @var{x} if specified. The incremented value is returned. For
1095 example, @code{(incf i)} is equivalent to @code{(setq i (1+ i))}, and
1096 @code{(incf (car x) 2)} is equivalent to @code{(setcar x (+ (car x) 2))}.
1098 Once again, care is taken to preserve the ``apparent'' order of
1099 evaluation. For example,
1102 (incf (aref vec (incf i)))
1106 appears to increment @code{i} once, then increment the element of
1107 @code{vec} addressed by @code{i}; this is indeed exactly what it
1108 does, which means the above form is @emph{not} equivalent to the
1109 ``obvious'' expansion,
1112 (setf (aref vec (incf i)) (1+ (aref vec (incf i)))) ; Wrong!
1116 but rather to something more like
1119 (let ((temp (incf i)))
1120 (setf (aref vec temp) (1+ (aref vec temp))))
1124 Again, all of this is taken care of automatically by @code{incf} and
1125 the other generalized-variable macros.
1127 As a more Emacs-specific example of @code{incf}, the expression
1128 @code{(incf (point) @var{n})} is essentially equivalent to
1129 @code{(forward-char @var{n})}.
1132 @defspec decf place &optional x
1133 This macro decrements the number stored in @var{place} by one, or
1134 by @var{x} if specified.
1138 This macro removes and returns the first element of the list stored
1139 in @var{place}. It is analogous to @code{(prog1 (car @var{place})
1140 (setf @var{place} (cdr @var{place})))}, except that it takes care
1141 to evaluate all subforms only once.
1144 @defspec push x place
1145 This macro inserts @var{x} at the front of the list stored in
1146 @var{place}. It is analogous to @code{(setf @var{place} (cons
1147 @var{x} @var{place}))}, except for evaluation of the subforms.
1150 @defspec pushnew x place @t{&key :test :test-not :key}
1151 This macro inserts @var{x} at the front of the list stored in
1152 @var{place}, but only if @var{x} was not @code{eql} to any
1153 existing element of the list. The optional keyword arguments
1154 are interpreted in the same way as for @code{adjoin}.
1155 @xref{Lists as Sets}.
1158 @defspec shiftf place@dots{} newvalue
1159 This macro shifts the @var{place}s left by one, shifting in the
1160 value of @var{newvalue} (which may be any Lisp expression, not just
1161 a generalized variable), and returning the value shifted out of
1162 the first @var{place}. Thus, @code{(shiftf @var{a} @var{b} @var{c}
1163 @var{d})} is equivalent to
1168 (psetf @var{a} @var{b}
1174 except that the subforms of @var{a}, @var{b}, and @var{c} are actually
1175 evaluated only once each and in the apparent order.
1178 @defspec rotatef place@dots{}
1179 This macro rotates the @var{place}s left by one in circular fashion.
1180 Thus, @code{(rotatef @var{a} @var{b} @var{c} @var{d})} is equivalent to
1183 (psetf @var{a} @var{b}
1190 except for the evaluation of subforms. @code{rotatef} always
1191 returns @code{nil}. Note that @code{(rotatef @var{a} @var{b})}
1192 conveniently exchanges @var{a} and @var{b}.
1195 The following macros were invented for this package; they have no
1196 analogues in Common Lisp.
1198 @defspec letf (bindings@dots{}) forms@dots{}
1199 This macro is analogous to @code{let}, but for generalized variables
1200 rather than just symbols. Each @var{binding} should be of the form
1201 @code{(@var{place} @var{value})}; the original contents of the
1202 @var{place}s are saved, the @var{value}s are stored in them, and
1203 then the body @var{form}s are executed. Afterwards, the @var{places}
1204 are set back to their original saved contents. This cleanup happens
1205 even if the @var{form}s exit irregularly due to a @code{throw} or an
1211 (letf (((point) (point-min))
1217 moves ``point'' in the current buffer to the beginning of the buffer,
1218 and also binds @code{a} to 17 (as if by a normal @code{let}, since
1219 @code{a} is just a regular variable). After the body exits, @code{a}
1220 is set back to its original value and point is moved back to its
1223 Note that @code{letf} on @code{(point)} is not quite like a
1224 @code{save-excursion}, as the latter effectively saves a marker
1225 which tracks insertions and deletions in the buffer. Actually,
1226 a @code{letf} of @code{(point-marker)} is much closer to this
1227 behavior. (@code{point} and @code{point-marker} are equivalent
1228 as @code{setf} places; each will accept either an integer or a
1229 marker as the stored value.)
1231 Since generalized variables look like lists, @code{let}'s shorthand
1232 of using @samp{foo} for @samp{(foo nil)} as a @var{binding} would
1233 be ambiguous in @code{letf} and is not allowed.
1235 However, a @var{binding} specifier may be a one-element list
1236 @samp{(@var{place})}, which is similar to @samp{(@var{place}
1237 @var{place})}. In other words, the @var{place} is not disturbed
1238 on entry to the body, and the only effect of the @code{letf} is
1239 to restore the original value of @var{place} afterwards. (The
1240 redundant access-and-store suggested by the @code{(@var{place}
1241 @var{place})} example does not actually occur.)
1243 In most cases, the @var{place} must have a well-defined value on
1244 entry to the @code{letf} form. The only exceptions are plain
1245 variables and calls to @code{symbol-value} and @code{symbol-function}.
1246 If the symbol is not bound on entry, it is simply made unbound by
1247 @code{makunbound} or @code{fmakunbound} on exit.
1250 @defspec letf* (bindings@dots{}) forms@dots{}
1251 This macro is to @code{letf} what @code{let*} is to @code{let}:
1252 It does the bindings in sequential rather than parallel order.
1255 @defspec callf @var{function} @var{place} @var{args}@dots{}
1256 This is the ``generic'' modify macro. It calls @var{function},
1257 which should be an unquoted function name, macro name, or lambda.
1258 It passes @var{place} and @var{args} as arguments, and assigns the
1259 result back to @var{place}. For example, @code{(incf @var{place}
1260 @var{n})} is the same as @code{(callf + @var{place} @var{n})}.
1264 (callf abs my-number)
1265 (callf concat (buffer-name) "<" (int-to-string n) ">")
1266 (callf union happy-people (list joe bob) :test 'same-person)
1269 @xref{Customizing Setf}, for @code{define-modify-macro}, a way
1270 to create even more concise notations for modify macros. Note
1271 again that @code{callf} is an extension to standard Common Lisp.
1274 @defspec callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{}
1275 This macro is like @code{callf}, except that @var{place} is
1276 the @emph{second} argument of @var{function} rather than the
1277 first. For example, @code{(push @var{x} @var{place})} is
1278 equivalent to @code{(callf2 cons @var{x} @var{place})}.
1281 The @code{callf} and @code{callf2} macros serve as building
1282 blocks for other macros like @code{incf}, @code{pushnew}, and
1283 @code{define-modify-macro}. The @code{letf} and @code{letf*}
1284 macros are used in the processing of symbol macros;
1285 @pxref{Macro Bindings}.
1287 @node Customizing Setf
1288 @subsection Customizing Setf
1291 Common Lisp defines three macros, @code{define-modify-macro},
1292 @code{defsetf}, and @code{define-setf-method}, that allow the
1293 user to extend generalized variables in various ways.
1295 @defspec define-modify-macro name arglist function [doc-string]
1296 This macro defines a ``read-modify-write'' macro similar to
1297 @code{incf} and @code{decf}. The macro @var{name} is defined
1298 to take a @var{place} argument followed by additional arguments
1299 described by @var{arglist}. The call
1302 (@var{name} @var{place} @var{args}...)
1309 (callf @var{func} @var{place} @var{args}...)
1313 which in turn is roughly equivalent to
1316 (setf @var{place} (@var{func} @var{place} @var{args}...))
1322 (define-modify-macro incf (&optional (n 1)) +)
1323 (define-modify-macro concatf (&rest args) concat)
1326 Note that @code{&key} is not allowed in @var{arglist}, but
1327 @code{&rest} is sufficient to pass keywords on to the function.
1329 Most of the modify macros defined by Common Lisp do not exactly
1330 follow the pattern of @code{define-modify-macro}. For example,
1331 @code{push} takes its arguments in the wrong order, and @code{pop}
1332 is completely irregular. You can define these macros ``by hand''
1333 using @code{get-setf-method}, or consult the source file
1334 @file{cl-macs.el} to see how to use the internal @code{setf}
1338 @defspec defsetf access-fn update-fn
1339 This is the simpler of two @code{defsetf} forms. Where
1340 @var{access-fn} is the name of a function which accesses a place,
1341 this declares @var{update-fn} to be the corresponding store
1342 function. From now on,
1345 (setf (@var{access-fn} @var{arg1} @var{arg2} @var{arg3}) @var{value})
1352 (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} @var{value})
1356 The @var{update-fn} is required to be either a true function, or
1357 a macro which evaluates its arguments in a function-like way. Also,
1358 the @var{update-fn} is expected to return @var{value} as its result.
1359 Otherwise, the above expansion would not obey the rules for the way
1360 @code{setf} is supposed to behave.
1362 As a special (non-Common-Lisp) extension, a third argument of @code{t}
1363 to @code{defsetf} says that the @code{update-fn}'s return value is
1364 not suitable, so that the above @code{setf} should be expanded to
1368 (let ((temp @var{value}))
1369 (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} temp)
1373 Some examples of the use of @code{defsetf}, drawn from the standard
1374 suite of setf methods, are:
1377 (defsetf car setcar)
1378 (defsetf symbol-value set)
1379 (defsetf buffer-name rename-buffer t)
1383 @defspec defsetf access-fn arglist (store-var) forms@dots{}
1384 This is the second, more complex, form of @code{defsetf}. It is
1385 rather like @code{defmacro} except for the additional @var{store-var}
1386 argument. The @var{forms} should return a Lisp form which stores
1387 the value of @var{store-var} into the generalized variable formed
1388 by a call to @var{access-fn} with arguments described by @var{arglist}.
1389 The @var{forms} may begin with a string which documents the @code{setf}
1390 method (analogous to the doc string that appears at the front of a
1393 For example, the simple form of @code{defsetf} is shorthand for
1396 (defsetf @var{access-fn} (&rest args) (store)
1397 (append '(@var{update-fn}) args (list store)))
1400 The Lisp form that is returned can access the arguments from
1401 @var{arglist} and @var{store-var} in an unrestricted fashion;
1402 macros like @code{setf} and @code{incf} which invoke this
1403 setf-method will insert temporary variables as needed to make
1404 sure the apparent order of evaluation is preserved.
1406 Another example drawn from the standard package:
1409 (defsetf nth (n x) (store)
1410 (list 'setcar (list 'nthcdr n x) store))
1414 @defspec define-setf-method access-fn arglist forms@dots{}
1415 This is the most general way to create new place forms. When
1416 a @code{setf} to @var{access-fn} with arguments described by
1417 @var{arglist} is expanded, the @var{forms} are evaluated and
1418 must return a list of five items:
1422 A list of @dfn{temporary variables}.
1425 A list of @dfn{value forms} corresponding to the temporary variables
1426 above. The temporary variables will be bound to these value forms
1427 as the first step of any operation on the generalized variable.
1430 A list of exactly one @dfn{store variable} (generally obtained
1431 from a call to @code{gensym}).
1434 A Lisp form which stores the contents of the store variable into
1435 the generalized variable, assuming the temporaries have been
1436 bound as described above.
1439 A Lisp form which accesses the contents of the generalized variable,
1440 assuming the temporaries have been bound.
1443 This is exactly like the Common Lisp macro of the same name,
1444 except that the method returns a list of five values rather
1445 than the five values themselves, since Emacs Lisp does not
1446 support Common Lisp's notion of multiple return values.
1448 Once again, the @var{forms} may begin with a documentation string.
1450 A setf-method should be maximally conservative with regard to
1451 temporary variables. In the setf-methods generated by
1452 @code{defsetf}, the second return value is simply the list of
1453 arguments in the place form, and the first return value is a
1454 list of a corresponding number of temporary variables generated
1455 by @code{gensym}. Macros like @code{setf} and @code{incf} which
1456 use this setf-method will optimize away most temporaries that
1457 turn out to be unnecessary, so there is little reason for the
1458 setf-method itself to optimize.
1461 @defun get-setf-method place &optional env
1462 This function returns the setf-method for @var{place}, by
1463 invoking the definition previously recorded by @code{defsetf}
1464 or @code{define-setf-method}. The result is a list of five
1465 values as described above. You can use this function to build
1466 your own @code{incf}-like modify macros. (Actually, it is
1467 better to use the internal functions @code{cl-setf-do-modify}
1468 and @code{cl-setf-do-store}, which are a bit easier to use and
1469 which also do a number of optimizations; consult the source
1470 code for the @code{incf} function for a simple example.)
1472 The argument @var{env} specifies the ``environment'' to be
1473 passed on to @code{macroexpand} if @code{get-setf-method} should
1474 need to expand a macro in @var{place}. It should come from
1475 an @code{&environment} argument to the macro or setf-method
1476 that called @code{get-setf-method}.
1478 See also the source code for the setf-methods for @code{apply}
1479 and @code{substring}, each of which works by calling
1480 @code{get-setf-method} on a simpler case, then massaging
1481 the result in various ways.
1484 Modern Common Lisp defines a second, independent way to specify
1485 the @code{setf} behavior of a function, namely ``@code{setf}
1486 functions'' whose names are lists @code{(setf @var{name})}
1487 rather than symbols. For example, @code{(defun (setf foo) @dots{})}
1488 defines the function that is used when @code{setf} is applied to
1489 @code{foo}. This package does not currently support @code{setf}
1490 functions. In particular, it is a compile-time error to use
1491 @code{setf} on a form which has not already been @code{defsetf}'d
1492 or otherwise declared; in newer Common Lisps, this would not be
1493 an error since the function @code{(setf @var{func})} might be
1500 @node Variable Bindings
1501 @section Variable Bindings
1504 These Lisp forms make bindings to variables and function names,
1505 analogous to Lisp's built-in @code{let} form.
1507 @xref{Modify Macros}, for the @code{letf} and @code{letf*} forms which
1508 are also related to variable bindings.
1511 * Dynamic Bindings:: The @code{progv} form.
1512 * Lexical Bindings:: @code{lexical-let} and lexical closures.
1513 * Function Bindings:: @code{flet} and @code{labels}.
1514 * Macro Bindings:: @code{macrolet} and @code{symbol-macrolet}.
1517 @node Dynamic Bindings
1518 @subsection Dynamic Bindings
1521 The standard @code{let} form binds variables whose names are known
1522 at compile-time. The @code{progv} form provides an easy way to
1523 bind variables whose names are computed at run-time.
1525 @defspec progv symbols values forms@dots{}
1526 This form establishes @code{let}-style variable bindings on a
1527 set of variables computed at run-time. The expressions
1528 @var{symbols} and @var{values} are evaluated, and must return lists
1529 of symbols and values, respectively. The symbols are bound to the
1530 corresponding values for the duration of the body @var{form}s.
1531 If @var{values} is shorter than @var{symbols}, the last few symbols
1532 are made unbound (as if by @code{makunbound}) inside the body.
1533 If @var{symbols} is shorter than @var{values}, the excess values
1537 @node Lexical Bindings
1538 @subsection Lexical Bindings
1541 The @code{CL} package defines the following macro which
1542 more closely follows the Common Lisp @code{let} form:
1544 @defspec lexical-let (bindings@dots{}) forms@dots{}
1545 This form is exactly like @code{let} except that the bindings it
1546 establishes are purely lexical. Lexical bindings are similar to
1547 local variables in a language like C: Only the code physically
1548 within the body of the @code{lexical-let} (after macro expansion)
1549 may refer to the bound variables.
1553 (defun foo (b) (+ a b))
1554 (let ((a 2)) (foo a))
1556 (lexical-let ((a 2)) (foo a))
1561 In this example, a regular @code{let} binding of @code{a} actually
1562 makes a temporary change to the global variable @code{a}, so @code{foo}
1563 is able to see the binding of @code{a} to 2. But @code{lexical-let}
1564 actually creates a distinct local variable @code{a} for use within its
1565 body, without any effect on the global variable of the same name.
1567 The most important use of lexical bindings is to create @dfn{closures}.
1568 A closure is a function object that refers to an outside lexical
1569 variable. For example:
1572 (defun make-adder (n)
1573 (lexical-let ((n n))
1574 (function (lambda (m) (+ n m)))))
1575 (setq add17 (make-adder 17))
1581 The call @code{(make-adder 17)} returns a function object which adds
1582 17 to its argument. If @code{let} had been used instead of
1583 @code{lexical-let}, the function object would have referred to the
1584 global @code{n}, which would have been bound to 17 only during the
1585 call to @code{make-adder} itself.
1588 (defun make-counter ()
1589 (lexical-let ((n 0))
1590 (function* (lambda (&optional (m 1)) (incf n m)))))
1591 (setq count-1 (make-counter))
1594 (funcall count-1 14)
1596 (setq count-2 (make-counter))
1606 Here we see that each call to @code{make-counter} creates a distinct
1607 local variable @code{n}, which serves as a private counter for the
1608 function object that is returned.
1610 Closed-over lexical variables persist until the last reference to
1611 them goes away, just like all other Lisp objects. For example,
1612 @code{count-2} refers to a function object which refers to an
1613 instance of the variable @code{n}; this is the only reference
1614 to that variable, so after @code{(setq count-2 nil)} the garbage
1615 collector would be able to delete this instance of @code{n}.
1616 Of course, if a @code{lexical-let} does not actually create any
1617 closures, then the lexical variables are free as soon as the
1618 @code{lexical-let} returns.
1620 Many closures are used only during the extent of the bindings they
1621 refer to; these are known as ``downward funargs'' in Lisp parlance.
1622 When a closure is used in this way, regular Emacs Lisp dynamic
1623 bindings suffice and will be more efficient than @code{lexical-let}
1627 (defun add-to-list (x list)
1628 (mapcar (lambda (y) (+ x y))) list)
1629 (add-to-list 7 '(1 2 5))
1634 Since this lambda is only used while @code{x} is still bound,
1635 it is not necessary to make a true closure out of it.
1637 You can use @code{defun} or @code{flet} inside a @code{lexical-let}
1638 to create a named closure. If several closures are created in the
1639 body of a single @code{lexical-let}, they all close over the same
1640 instance of the lexical variable.
1642 The @code{lexical-let} form is an extension to Common Lisp. In
1643 true Common Lisp, all bindings are lexical unless declared otherwise.
1646 @defspec lexical-let* (bindings@dots{}) forms@dots{}
1647 This form is just like @code{lexical-let}, except that the bindings
1648 are made sequentially in the manner of @code{let*}.
1651 @node Function Bindings
1652 @subsection Function Bindings
1655 These forms make @code{let}-like bindings to functions instead
1658 @defspec flet (bindings@dots{}) forms@dots{}
1659 This form establishes @code{let}-style bindings on the function
1660 cells of symbols rather than on the value cells. Each @var{binding}
1661 must be a list of the form @samp{(@var{name} @var{arglist}
1662 @var{forms}@dots{})}, which defines a function exactly as if
1663 it were a @code{defun*} form. The function @var{name} is defined
1664 accordingly for the duration of the body of the @code{flet}; then
1665 the old function definition, or lack thereof, is restored.
1667 While @code{flet} in Common Lisp establishes a lexical binding of
1668 @var{name}, Emacs Lisp @code{flet} makes a dynamic binding. The
1669 result is that @code{flet} affects indirect calls to a function as
1670 well as calls directly inside the @code{flet} form itself.
1672 You can use @code{flet} to disable or modify the behavior of a
1673 function in a temporary fashion. This will even work on Emacs
1674 primitives, although note that some calls to primitive functions
1675 internal to Emacs are made without going through the symbol's
1676 function cell, and so will not be affected by @code{flet}. For
1680 (flet ((message (&rest args) (push args saved-msgs)))
1684 This code attempts to replace the built-in function @code{message}
1685 with a function that simply saves the messages in a list rather
1686 than displaying them. The original definition of @code{message}
1687 will be restored after @code{do-something} exits. This code will
1688 work fine on messages generated by other Lisp code, but messages
1689 generated directly inside Emacs will not be caught since they make
1690 direct C-language calls to the message routines rather than going
1691 through the Lisp @code{message} function.
1694 Also note that many primitives (e.g. @code{+}) have special byte-compile
1695 handling. Attempts to redefine such functions using @code{flet} will
1696 fail if byte-compiled. In such cases, use @code{labels} instead.
1698 Functions defined by @code{flet} may use the full Common Lisp
1699 argument notation supported by @code{defun*}; also, the function
1700 body is enclosed in an implicit block as if by @code{defun*}.
1701 @xref{Program Structure}.
1704 @defspec labels (bindings@dots{}) forms@dots{}
1705 The @code{labels} form is like @code{flet}, except that it
1706 makes lexical bindings of the function names rather than
1707 dynamic bindings. (In true Common Lisp, both @code{flet} and
1708 @code{labels} make lexical bindings of slightly different sorts;
1709 since Emacs Lisp is dynamically bound by default, it seemed
1710 more appropriate for @code{flet} also to use dynamic binding.
1711 The @code{labels} form, with its lexical binding, is fully
1712 compatible with Common Lisp.)
1714 Lexical scoping means that all references to the named
1715 functions must appear physically within the body of the
1716 @code{labels} form. References may appear both in the body
1717 @var{forms} of @code{labels} itself, and in the bodies of
1718 the functions themselves. Thus, @code{labels} can define
1719 local recursive functions, or mutually-recursive sets of
1722 A ``reference'' to a function name is either a call to that
1723 function, or a use of its name quoted by @code{quote} or
1724 @code{function} to be passed on to, say, @code{mapcar}.
1727 @node Macro Bindings
1728 @subsection Macro Bindings
1731 These forms create local macros and ``symbol macros.''
1733 @defspec macrolet (bindings@dots{}) forms@dots{}
1734 This form is analogous to @code{flet}, but for macros instead of
1735 functions. Each @var{binding} is a list of the same form as the
1736 arguments to @code{defmacro*} (i.e., a macro name, argument list,
1737 and macro-expander forms). The macro is defined accordingly for
1738 use within the body of the @code{macrolet}.
1740 Because of the nature of macros, @code{macrolet} is lexically
1741 scoped even in Emacs Lisp: The @code{macrolet} binding will
1742 affect only calls that appear physically within the body
1743 @var{forms}, possibly after expansion of other macros in the
1747 @defspec symbol-macrolet (bindings@dots{}) forms@dots{}
1748 This form creates @dfn{symbol macros}, which are macros that look
1749 like variable references rather than function calls. Each
1750 @var{binding} is a list @samp{(@var{var} @var{expansion})};
1751 any reference to @var{var} within the body @var{forms} is
1752 replaced by @var{expansion}.
1756 (symbol-macrolet ((foo (car bar)))
1762 A @code{setq} of a symbol macro is treated the same as a @code{setf}.
1763 I.e., @code{(setq foo 4)} in the above would be equivalent to
1764 @code{(setf foo 4)}, which in turn expands to @code{(setf (car bar) 4)}.
1766 Likewise, a @code{let} or @code{let*} binding a symbol macro is
1767 treated like a @code{letf} or @code{letf*}. This differs from true
1768 Common Lisp, where the rules of lexical scoping cause a @code{let}
1769 binding to shadow a @code{symbol-macrolet} binding. In this package,
1770 only @code{lexical-let} and @code{lexical-let*} will shadow a symbol
1773 There is no analogue of @code{defmacro} for symbol macros; all symbol
1774 macros are local. A typical use of @code{symbol-macrolet} is in the
1775 expansion of another macro:
1778 (defmacro* my-dolist ((x list) &rest body)
1779 (let ((var (gensym)))
1780 (list 'loop 'for var 'on list 'do
1781 (list* 'symbol-macrolet (list (list x (list 'car var)))
1784 (setq mylist '(1 2 3 4))
1785 (my-dolist (x mylist) (incf x))
1791 In this example, the @code{my-dolist} macro is similar to @code{dolist}
1792 (@pxref{Iteration}) except that the variable @code{x} becomes a true
1793 reference onto the elements of the list. The @code{my-dolist} call
1794 shown here expands to
1797 (loop for G1234 on mylist do
1798 (symbol-macrolet ((x (car G1234)))
1803 which in turn expands to
1806 (loop for G1234 on mylist do (incf (car G1234)))
1809 @xref{Loop Facility}, for a description of the @code{loop} macro.
1810 This package defines a nonstandard @code{in-ref} loop clause that
1811 works much like @code{my-dolist}.
1815 @section Conditionals
1818 These conditional forms augment Emacs Lisp's simple @code{if},
1819 @code{and}, @code{or}, and @code{cond} forms.
1821 @defspec case keyform clause@dots{}
1822 This macro evaluates @var{keyform}, then compares it with the key
1823 values listed in the various @var{clause}s. Whichever clause matches
1824 the key is executed; comparison is done by @code{eql}. If no clause
1825 matches, the @code{case} form returns @code{nil}. The clauses are
1829 (@var{keylist} @var{body-forms}@dots{})
1833 where @var{keylist} is a list of key values. If there is exactly
1834 one value, and it is not a cons cell or the symbol @code{nil} or
1835 @code{t}, then it can be used by itself as a @var{keylist} without
1836 being enclosed in a list. All key values in the @code{case} form
1837 must be distinct. The final clauses may use @code{t} in place of
1838 a @var{keylist} to indicate a default clause that should be taken
1839 if none of the other clauses match. (The symbol @code{otherwise}
1840 is also recognized in place of @code{t}. To make a clause that
1841 matches the actual symbol @code{t}, @code{nil}, or @code{otherwise},
1842 enclose the symbol in a list.)
1844 For example, this expression reads a keystroke, then does one of
1845 four things depending on whether it is an @samp{a}, a @samp{b},
1846 a @key{RET} or @kbd{C-j}, or anything else.
1852 ((?\r ?\n) (do-ret-thing))
1853 (t (do-other-thing)))
1857 @defspec ecase keyform clause@dots{}
1858 This macro is just like @code{case}, except that if the key does
1859 not match any of the clauses, an error is signaled rather than
1860 simply returning @code{nil}.
1863 @defspec typecase keyform clause@dots{}
1864 This macro is a version of @code{case} that checks for types
1865 rather than values. Each @var{clause} is of the form
1866 @samp{(@var{type} @var{body}...)}. @xref{Type Predicates},
1867 for a description of type specifiers. For example,
1871 (integer (munch-integer x))
1872 (float (munch-float x))
1873 (string (munch-integer (string-to-int x)))
1874 (t (munch-anything x)))
1877 The type specifier @code{t} matches any type of object; the word
1878 @code{otherwise} is also allowed. To make one clause match any of
1879 several types, use an @code{(or ...)} type specifier.
1882 @defspec etypecase keyform clause@dots{}
1883 This macro is just like @code{typecase}, except that if the key does
1884 not match any of the clauses, an error is signaled rather than
1885 simply returning @code{nil}.
1888 @node Blocks and Exits
1889 @section Blocks and Exits
1892 Common Lisp @dfn{blocks} provide a non-local exit mechanism very
1893 similar to @code{catch} and @code{throw}, but lexically rather than
1894 dynamically scoped. This package actually implements @code{block}
1895 in terms of @code{catch}; however, the lexical scoping allows the
1896 optimizing byte-compiler to omit the costly @code{catch} step if the
1897 body of the block does not actually @code{return-from} the block.
1899 @defspec block name forms@dots{}
1900 The @var{forms} are evaluated as if by a @code{progn}. However,
1901 if any of the @var{forms} execute @code{(return-from @var{name})},
1902 they will jump out and return directly from the @code{block} form.
1903 The @code{block} returns the result of the last @var{form} unless
1904 a @code{return-from} occurs.
1906 The @code{block}/@code{return-from} mechanism is quite similar to
1907 the @code{catch}/@code{throw} mechanism. The main differences are
1908 that block @var{name}s are unevaluated symbols, rather than forms
1909 (such as quoted symbols) which evaluate to a tag at run-time; and
1910 also that blocks are lexically scoped whereas @code{catch}/@code{throw}
1911 are dynamically scoped. This means that functions called from the
1912 body of a @code{catch} can also @code{throw} to the @code{catch},
1913 but the @code{return-from} referring to a block name must appear
1914 physically within the @var{forms} that make up the body of the block.
1915 They may not appear within other called functions, although they may
1916 appear within macro expansions or @code{lambda}s in the body. Block
1917 names and @code{catch} names form independent name-spaces.
1919 In true Common Lisp, @code{defun} and @code{defmacro} surround
1920 the function or expander bodies with implicit blocks with the
1921 same name as the function or macro. This does not occur in Emacs
1922 Lisp, but this package provides @code{defun*} and @code{defmacro*}
1923 forms which do create the implicit block.
1925 The Common Lisp looping constructs defined by this package,
1926 such as @code{loop} and @code{dolist}, also create implicit blocks
1927 just as in Common Lisp.
1929 Because they are implemented in terms of Emacs Lisp @code{catch}
1930 and @code{throw}, blocks have the same overhead as actual
1931 @code{catch} constructs (roughly two function calls). However,
1932 the optimizing byte compiler will optimize away the @code{catch}
1934 not in fact contain any @code{return} or @code{return-from} calls
1935 that jump to it. This means that @code{do} loops and @code{defun*}
1936 functions which don't use @code{return} don't pay the overhead to
1940 @defspec return-from name [result]
1941 This macro returns from the block named @var{name}, which must be
1942 an (unevaluated) symbol. If a @var{result} form is specified, it
1943 is evaluated to produce the result returned from the @code{block}.
1944 Otherwise, @code{nil} is returned.
1947 @defspec return [result]
1948 This macro is exactly like @code{(return-from nil @var{result})}.
1949 Common Lisp loops like @code{do} and @code{dolist} implicitly enclose
1950 themselves in @code{nil} blocks.
1957 The macros described here provide more sophisticated, high-level
1958 looping constructs to complement Emacs Lisp's basic @code{while}
1961 @defspec loop forms@dots{}
1962 The @code{CL} package supports both the simple, old-style meaning of
1963 @code{loop} and the extremely powerful and flexible feature known as
1964 the @dfn{Loop Facility} or @dfn{Loop Macro}. This more advanced
1965 facility is discussed in the following section; @pxref{Loop Facility}.
1966 The simple form of @code{loop} is described here.
1968 If @code{loop} is followed by zero or more Lisp expressions,
1969 then @code{(loop @var{exprs}@dots{})} simply creates an infinite
1970 loop executing the expressions over and over. The loop is
1971 enclosed in an implicit @code{nil} block. Thus,
1974 (loop (foo) (if (no-more) (return 72)) (bar))
1978 is exactly equivalent to
1981 (block nil (while t (foo) (if (no-more) (return 72)) (bar)))
1984 If any of the expressions are plain symbols, the loop is instead
1985 interpreted as a Loop Macro specification as described later.
1986 (This is not a restriction in practice, since a plain symbol
1987 in the above notation would simply access and throw away the
1988 value of a variable.)
1991 @defspec do (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
1992 This macro creates a general iterative loop. Each @var{spec} is
1996 (@var{var} [@var{init} [@var{step}]])
1999 The loop works as follows: First, each @var{var} is bound to the
2000 associated @var{init} value as if by a @code{let} form. Then, in
2001 each iteration of the loop, the @var{end-test} is evaluated; if
2002 true, the loop is finished. Otherwise, the body @var{forms} are
2003 evaluated, then each @var{var} is set to the associated @var{step}
2004 expression (as if by a @code{cl-psetq} form) and the next iteration
2005 begins. Once the @var{end-test} becomes true, the @var{result}
2006 forms are evaluated (with the @var{var}s still bound to their
2007 values) to produce the result returned by @code{do}.
2009 The entire @code{do} loop is enclosed in an implicit @code{nil}
2010 block, so that you can use @code{(return)} to break out of the
2013 If there are no @var{result} forms, the loop returns @code{nil}.
2014 If a given @var{var} has no @var{step} form, it is bound to its
2015 @var{init} value but not otherwise modified during the @code{do}
2016 loop (unless the code explicitly modifies it); this case is just
2017 a shorthand for putting a @code{(let ((@var{var} @var{init})) @dots{})}
2018 around the loop. If @var{init} is also omitted it defaults to
2019 @code{nil}, and in this case a plain @samp{@var{var}} can be used
2020 in place of @samp{(@var{var})}, again following the analogy with
2023 This example (from Steele) illustrates a loop which applies the
2024 function @code{f} to successive pairs of values from the lists
2025 @code{foo} and @code{bar}; it is equivalent to the call
2026 @code{(mapcar* 'f foo bar)}. Note that this loop has no body
2027 @var{forms} at all, performing all its work as side effects of
2028 the rest of the loop.
2031 (do ((x foo (cdr x))
2033 (z nil (cons (f (car x) (car y)) z)))
2034 ((or (null x) (null y))
2039 @defspec do* (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
2040 This is to @code{do} what @code{let*} is to @code{let}. In
2041 particular, the initial values are bound as if by @code{let*}
2042 rather than @code{let}, and the steps are assigned as if by
2043 @code{setq} rather than @code{cl-psetq}.
2045 Here is another way to write the above loop:
2048 (do* ((xp foo (cdr xp))
2050 (x (car xp) (car xp))
2051 (y (car yp) (car yp))
2053 ((or (null xp) (null yp))
2059 @defspec dolist (var list [result]) forms@dots{}
2060 This is a more specialized loop which iterates across the elements
2061 of a list. @var{list} should evaluate to a list; the body @var{forms}
2062 are executed with @var{var} bound to each element of the list in
2063 turn. Finally, the @var{result} form (or @code{nil}) is evaluated
2064 with @var{var} bound to @code{nil} to produce the result returned by
2065 the loop. Unlike with Emacs's built in @code{dolist}, the loop is
2066 surrounded by an implicit @code{nil} block.
2069 @defspec dotimes (var count [result]) forms@dots{}
2070 This is a more specialized loop which iterates a specified number
2071 of times. The body is executed with @var{var} bound to the integers
2072 from zero (inclusive) to @var{count} (exclusive), in turn. Then
2073 the @code{result} form is evaluated with @var{var} bound to the total
2074 number of iterations that were done (i.e., @code{(max 0 @var{count})})
2075 to get the return value for the loop form. Unlike with Emacs's built in
2076 @code{dolist}, the loop is surrounded by an implicit @code{nil} block.
2079 @defspec do-symbols (var [obarray [result]]) forms@dots{}
2080 This loop iterates over all interned symbols. If @var{obarray}
2081 is specified and is not @code{nil}, it loops over all symbols in
2082 that obarray. For each symbol, the body @var{forms} are evaluated
2083 with @var{var} bound to that symbol. The symbols are visited in
2084 an unspecified order. Afterward the @var{result} form, if any,
2085 is evaluated (with @var{var} bound to @code{nil}) to get the return
2086 value. The loop is surrounded by an implicit @code{nil} block.
2089 @defspec do-all-symbols (var [result]) forms@dots{}
2090 This is identical to @code{do-symbols} except that the @var{obarray}
2091 argument is omitted; it always iterates over the default obarray.
2094 @xref{Mapping over Sequences}, for some more functions for
2095 iterating over vectors or lists.
2098 @section Loop Facility
2101 A common complaint with Lisp's traditional looping constructs is
2102 that they are either too simple and limited, such as Common Lisp's
2103 @code{dotimes} or Emacs Lisp's @code{while}, or too unreadable and
2104 obscure, like Common Lisp's @code{do} loop.
2106 To remedy this, recent versions of Common Lisp have added a new
2107 construct called the ``Loop Facility'' or ``@code{loop} macro,''
2108 with an easy-to-use but very powerful and expressive syntax.
2111 * Loop Basics:: @code{loop} macro, basic clause structure.
2112 * Loop Examples:: Working examples of @code{loop} macro.
2113 * For Clauses:: Clauses introduced by @code{for} or @code{as}.
2114 * Iteration Clauses:: @code{repeat}, @code{while}, @code{thereis}, etc.
2115 * Accumulation Clauses:: @code{collect}, @code{sum}, @code{maximize}, etc.
2116 * Other Clauses:: @code{with}, @code{if}, @code{initially}, @code{finally}.
2120 @subsection Loop Basics
2123 The @code{loop} macro essentially creates a mini-language within
2124 Lisp that is specially tailored for describing loops. While this
2125 language is a little strange-looking by the standards of regular Lisp,
2126 it turns out to be very easy to learn and well-suited to its purpose.
2128 Since @code{loop} is a macro, all parsing of the loop language
2129 takes place at byte-compile time; compiled @code{loop}s are just
2130 as efficient as the equivalent @code{while} loops written longhand.
2132 @defspec loop clauses@dots{}
2133 A loop construct consists of a series of @var{clause}s, each
2134 introduced by a symbol like @code{for} or @code{do}. Clauses
2135 are simply strung together in the argument list of @code{loop},
2136 with minimal extra parentheses. The various types of clauses
2137 specify initializations, such as the binding of temporary
2138 variables, actions to be taken in the loop, stepping actions,
2141 Common Lisp specifies a certain general order of clauses in a
2145 (loop @var{name-clause}
2146 @var{var-clauses}@dots{}
2147 @var{action-clauses}@dots{})
2150 The @var{name-clause} optionally gives a name to the implicit
2151 block that surrounds the loop. By default, the implicit block
2152 is named @code{nil}. The @var{var-clauses} specify what
2153 variables should be bound during the loop, and how they should
2154 be modified or iterated throughout the course of the loop. The
2155 @var{action-clauses} are things to be done during the loop, such
2156 as computing, collecting, and returning values.
2158 The Emacs version of the @code{loop} macro is less restrictive about
2159 the order of clauses, but things will behave most predictably if
2160 you put the variable-binding clauses @code{with}, @code{for}, and
2161 @code{repeat} before the action clauses. As in Common Lisp,
2162 @code{initially} and @code{finally} clauses can go anywhere.
2164 Loops generally return @code{nil} by default, but you can cause
2165 them to return a value by using an accumulation clause like
2166 @code{collect}, an end-test clause like @code{always}, or an
2167 explicit @code{return} clause to jump out of the implicit block.
2168 (Because the loop body is enclosed in an implicit block, you can
2169 also use regular Lisp @code{return} or @code{return-from} to
2170 break out of the loop.)
2173 The following sections give some examples of the Loop Macro in
2174 action, and describe the particular loop clauses in great detail.
2175 Consult the second edition of Steele's @dfn{Common Lisp, the Language},
2176 for additional discussion and examples of the @code{loop} macro.
2179 @subsection Loop Examples
2182 Before listing the full set of clauses that are allowed, let's
2183 look at a few example loops just to get a feel for the @code{loop}
2187 (loop for buf in (buffer-list)
2188 collect (buffer-file-name buf))
2192 This loop iterates over all Emacs buffers, using the list
2193 returned by @code{buffer-list}. For each buffer @code{buf},
2194 it calls @code{buffer-file-name} and collects the results into
2195 a list, which is then returned from the @code{loop} construct.
2196 The result is a list of the file names of all the buffers in
2197 Emacs's memory. The words @code{for}, @code{in}, and @code{collect}
2198 are reserved words in the @code{loop} language.
2201 (loop repeat 20 do (insert "Yowsa\n"))
2205 This loop inserts the phrase ``Yowsa'' twenty times in the
2209 (loop until (eobp) do (munch-line) (forward-line 1))
2213 This loop calls @code{munch-line} on every line until the end
2214 of the buffer. If point is already at the end of the buffer,
2215 the loop exits immediately.
2218 (loop do (munch-line) until (eobp) do (forward-line 1))
2222 This loop is similar to the above one, except that @code{munch-line}
2223 is always called at least once.
2226 (loop for x from 1 to 100
2229 finally return (list x (= y 729)))
2233 This more complicated loop searches for a number @code{x} whose
2234 square is 729. For safety's sake it only examines @code{x}
2235 values up to 100; dropping the phrase @samp{to 100} would
2236 cause the loop to count upwards with no limit. The second
2237 @code{for} clause defines @code{y} to be the square of @code{x}
2238 within the loop; the expression after the @code{=} sign is
2239 reevaluated each time through the loop. The @code{until}
2240 clause gives a condition for terminating the loop, and the
2241 @code{finally} clause says what to do when the loop finishes.
2242 (This particular example was written less concisely than it
2243 could have been, just for the sake of illustration.)
2245 Note that even though this loop contains three clauses (two
2246 @code{for}s and an @code{until}) that would have been enough to
2247 define loops all by themselves, it still creates a single loop
2248 rather than some sort of triple-nested loop. You must explicitly
2249 nest your @code{loop} constructs if you want nested loops.
2252 @subsection For Clauses
2255 Most loops are governed by one or more @code{for} clauses.
2256 A @code{for} clause simultaneously describes variables to be
2257 bound, how those variables are to be stepped during the loop,
2258 and usually an end condition based on those variables.
2260 The word @code{as} is a synonym for the word @code{for}. This
2261 word is followed by a variable name, then a word like @code{from}
2262 or @code{across} that describes the kind of iteration desired.
2263 In Common Lisp, the phrase @code{being the} sometimes precedes
2264 the type of iteration; in this package both @code{being} and
2265 @code{the} are optional. The word @code{each} is a synonym
2266 for @code{the}, and the word that follows it may be singular
2267 or plural: @samp{for x being the elements of y} or
2268 @samp{for x being each element of y}. Which form you use
2269 is purely a matter of style.
2271 The variable is bound around the loop as if by @code{let}:
2275 (loop for i from 1 to 10 do (do-something-with i))
2281 @item for @var{var} from @var{expr1} to @var{expr2} by @var{expr3}
2282 This type of @code{for} clause creates a counting loop. Each of
2283 the three sub-terms is optional, though there must be at least one
2284 term so that the clause is marked as a counting clause.
2286 The three expressions are the starting value, the ending value, and
2287 the step value, respectively, of the variable. The loop counts
2288 upwards by default (@var{expr3} must be positive), from @var{expr1}
2289 to @var{expr2} inclusively. If you omit the @code{from} term, the
2290 loop counts from zero; if you omit the @code{to} term, the loop
2291 counts forever without stopping (unless stopped by some other
2292 loop clause, of course); if you omit the @code{by} term, the loop
2293 counts in steps of one.
2295 You can replace the word @code{from} with @code{upfrom} or
2296 @code{downfrom} to indicate the direction of the loop. Likewise,
2297 you can replace @code{to} with @code{upto} or @code{downto}.
2298 For example, @samp{for x from 5 downto 1} executes five times
2299 with @code{x} taking on the integers from 5 down to 1 in turn.
2300 Also, you can replace @code{to} with @code{below} or @code{above},
2301 which are like @code{upto} and @code{downto} respectively except
2302 that they are exclusive rather than inclusive limits:
2305 (loop for x to 10 collect x)
2306 @result{} (0 1 2 3 4 5 6 7 8 9 10)
2307 (loop for x below 10 collect x)
2308 @result{} (0 1 2 3 4 5 6 7 8 9)
2311 The @code{by} value is always positive, even for downward-counting
2312 loops. Some sort of @code{from} value is required for downward
2313 loops; @samp{for x downto 5} is not a valid loop clause all by
2316 @item for @var{var} in @var{list} by @var{function}
2317 This clause iterates @var{var} over all the elements of @var{list},
2318 in turn. If you specify the @code{by} term, then @var{function}
2319 is used to traverse the list instead of @code{cdr}; it must be a
2320 function taking one argument. For example:
2323 (loop for x in '(1 2 3 4 5 6) collect (* x x))
2324 @result{} (1 4 9 16 25 36)
2325 (loop for x in '(1 2 3 4 5 6) by 'cddr collect (* x x))
2329 @item for @var{var} on @var{list} by @var{function}
2330 This clause iterates @var{var} over all the cons cells of @var{list}.
2333 (loop for x on '(1 2 3 4) collect x)
2334 @result{} ((1 2 3 4) (2 3 4) (3 4) (4))
2337 With @code{by}, there is no real reason that the @code{on} expression
2338 must be a list. For example:
2341 (loop for x on first-animal by 'next-animal collect x)
2345 where @code{(next-animal x)} takes an ``animal'' @var{x} and returns
2346 the next in the (assumed) sequence of animals, or @code{nil} if
2347 @var{x} was the last animal in the sequence.
2349 @item for @var{var} in-ref @var{list} by @var{function}
2350 This is like a regular @code{in} clause, but @var{var} becomes
2351 a @code{setf}-able ``reference'' onto the elements of the list
2352 rather than just a temporary variable. For example,
2355 (loop for x in-ref my-list do (incf x))
2359 increments every element of @code{my-list} in place. This clause
2360 is an extension to standard Common Lisp.
2362 @item for @var{var} across @var{array}
2363 This clause iterates @var{var} over all the elements of @var{array},
2364 which may be a vector or a string.
2367 (loop for x across "aeiou"
2368 do (use-vowel (char-to-string x)))
2371 @item for @var{var} across-ref @var{array}
2372 This clause iterates over an array, with @var{var} a @code{setf}-able
2373 reference onto the elements; see @code{in-ref} above.
2375 @item for @var{var} being the elements of @var{sequence}
2376 This clause iterates over the elements of @var{sequence}, which may
2377 be a list, vector, or string. Since the type must be determined
2378 at run-time, this is somewhat less efficient than @code{in} or
2379 @code{across}. The clause may be followed by the additional term
2380 @samp{using (index @var{var2})} to cause @var{var2} to be bound to
2381 the successive indices (starting at 0) of the elements.
2383 This clause type is taken from older versions of the @code{loop} macro,
2384 and is not present in modern Common Lisp. The @samp{using (sequence ...)}
2385 term of the older macros is not supported.
2387 @item for @var{var} being the elements of-ref @var{sequence}
2388 This clause iterates over a sequence, with @var{var} a @code{setf}-able
2389 reference onto the elements; see @code{in-ref} above.
2391 @item for @var{var} being the symbols [of @var{obarray}]
2392 This clause iterates over symbols, either over all interned symbols
2393 or over all symbols in @var{obarray}. The loop is executed with
2394 @var{var} bound to each symbol in turn. The symbols are visited in
2395 an unspecified order.
2400 (loop for sym being the symbols
2402 when (string-match "^map" (symbol-name sym))
2407 returns a list of all the functions whose names begin with @samp{map}.
2409 The Common Lisp words @code{external-symbols} and @code{present-symbols}
2410 are also recognized but are equivalent to @code{symbols} in Emacs Lisp.
2412 Due to a minor implementation restriction, it will not work to have
2413 more than one @code{for} clause iterating over symbols, hash tables,
2414 keymaps, overlays, or intervals in a given @code{loop}. Fortunately,
2415 it would rarely if ever be useful to do so. It @emph{is} valid to mix
2416 one of these types of clauses with other clauses like @code{for ... to}
2419 @item for @var{var} being the hash-keys of @var{hash-table}
2420 @itemx for @var{var} being the hash-values of @var{hash-table}
2421 This clause iterates over the entries in @var{hash-table} with
2422 @var{var} bound to each key, or value. A @samp{using} clause can bind
2423 a second variable to the opposite part.
2426 (loop for k being the hash-keys of h
2427 using (hash-values v)
2429 (message "key %S -> value %S" k v))
2432 @item for @var{var} being the key-codes of @var{keymap}
2433 @itemx for @var{var} being the key-bindings of @var{keymap}
2434 This clause iterates over the entries in @var{keymap}.
2435 The iteration does not enter nested keymaps but does enter inherited
2437 A @code{using} clause can access both the codes and the bindings
2441 (loop for c being the key-codes of (current-local-map)
2442 using (key-bindings b)
2444 (message "key %S -> binding %S" c b))
2448 @item for @var{var} being the key-seqs of @var{keymap}
2449 This clause iterates over all key sequences defined by @var{keymap}
2450 and its nested keymaps, where @var{var} takes on values which are
2451 vectors. The strings or vectors
2452 are reused for each iteration, so you must copy them if you wish to keep
2453 them permanently. You can add a @samp{using (key-bindings ...)}
2454 clause to get the command bindings as well.
2456 @item for @var{var} being the overlays [of @var{buffer}] @dots{}
2457 This clause iterates over the ``overlays'' of a buffer
2458 (the clause @code{extents} is synonymous
2459 with @code{overlays}). If the @code{of} term is omitted, the current
2461 This clause also accepts optional @samp{from @var{pos}} and
2462 @samp{to @var{pos}} terms, limiting the clause to overlays which
2463 overlap the specified region.
2465 @item for @var{var} being the intervals [of @var{buffer}] @dots{}
2466 This clause iterates over all intervals of a buffer with constant
2467 text properties. The variable @var{var} will be bound to conses
2468 of start and end positions, where one start position is always equal
2469 to the previous end position. The clause allows @code{of},
2470 @code{from}, @code{to}, and @code{property} terms, where the latter
2471 term restricts the search to just the specified property. The
2472 @code{of} term may specify either a buffer or a string.
2474 @item for @var{var} being the frames
2475 This clause iterates over all Emacs frames. The clause @code{screens} is
2476 a synonym for @code{frames}. The frames are visited in
2477 @code{next-frame} order starting from @code{selected-frame}.
2479 @item for @var{var} being the windows [of @var{frame}]
2480 This clause iterates over the windows (in the Emacs sense) of
2481 the current frame, or of the specified @var{frame}. It visits windows
2482 in @code{next-window} order starting from @code{selected-window}
2483 (or @code{frame-selected-window} if you specify @var{frame}).
2484 This clause treats the minibuffer window in the same way as
2485 @code{next-window} does. For greater flexibility, consider using
2486 @code{walk-windows} instead.
2488 @item for @var{var} being the buffers
2489 This clause iterates over all buffers in Emacs. It is equivalent
2490 to @samp{for @var{var} in (buffer-list)}.
2492 @item for @var{var} = @var{expr1} then @var{expr2}
2493 This clause does a general iteration. The first time through
2494 the loop, @var{var} will be bound to @var{expr1}. On the second
2495 and successive iterations it will be set by evaluating @var{expr2}
2496 (which may refer to the old value of @var{var}). For example,
2497 these two loops are effectively the same:
2500 (loop for x on my-list by 'cddr do ...)
2501 (loop for x = my-list then (cddr x) while x do ...)
2504 Note that this type of @code{for} clause does not imply any sort
2505 of terminating condition; the above example combines it with a
2506 @code{while} clause to tell when to end the loop.
2508 If you omit the @code{then} term, @var{expr1} is used both for
2509 the initial setting and for successive settings:
2512 (loop for x = (random) when (> x 0) return x)
2516 This loop keeps taking random numbers from the @code{(random)}
2517 function until it gets a positive one, which it then returns.
2520 If you include several @code{for} clauses in a row, they are
2521 treated sequentially (as if by @code{let*} and @code{setq}).
2522 You can instead use the word @code{and} to link the clauses,
2523 in which case they are processed in parallel (as if by @code{let}
2524 and @code{cl-psetq}).
2527 (loop for x below 5 for y = nil then x collect (list x y))
2528 @result{} ((0 nil) (1 1) (2 2) (3 3) (4 4))
2529 (loop for x below 5 and y = nil then x collect (list x y))
2530 @result{} ((0 nil) (1 0) (2 1) (3 2) (4 3))
2534 In the first loop, @code{y} is set based on the value of @code{x}
2535 that was just set by the previous clause; in the second loop,
2536 @code{x} and @code{y} are set simultaneously so @code{y} is set
2537 based on the value of @code{x} left over from the previous time
2540 Another feature of the @code{loop} macro is @dfn{destructuring},
2541 similar in concept to the destructuring provided by @code{defmacro}.
2542 The @var{var} part of any @code{for} clause can be given as a list
2543 of variables instead of a single variable. The values produced
2544 during loop execution must be lists; the values in the lists are
2545 stored in the corresponding variables.
2548 (loop for (x y) in '((2 3) (4 5) (6 7)) collect (+ x y))
2552 In loop destructuring, if there are more values than variables
2553 the trailing values are ignored, and if there are more variables
2554 than values the trailing variables get the value @code{nil}.
2555 If @code{nil} is used as a variable name, the corresponding
2556 values are ignored. Destructuring may be nested, and dotted
2557 lists of variables like @code{(x . y)} are allowed, so for example
2561 (loop for (key . value) in '((a . 1) (b . 2))
2566 @node Iteration Clauses
2567 @subsection Iteration Clauses
2570 Aside from @code{for} clauses, there are several other loop clauses
2571 that control the way the loop operates. They might be used by
2572 themselves, or in conjunction with one or more @code{for} clauses.
2575 @item repeat @var{integer}
2576 This clause simply counts up to the specified number using an
2577 internal temporary variable. The loops
2580 (loop repeat (1+ n) do ...)
2581 (loop for temp to n do ...)
2585 are identical except that the second one forces you to choose
2586 a name for a variable you aren't actually going to use.
2588 @item while @var{condition}
2589 This clause stops the loop when the specified condition (any Lisp
2590 expression) becomes @code{nil}. For example, the following two
2591 loops are equivalent, except for the implicit @code{nil} block
2592 that surrounds the second one:
2595 (while @var{cond} @var{forms}@dots{})
2596 (loop while @var{cond} do @var{forms}@dots{})
2599 @item until @var{condition}
2600 This clause stops the loop when the specified condition is true,
2601 i.e., non-@code{nil}.
2603 @item always @var{condition}
2604 This clause stops the loop when the specified condition is @code{nil}.
2605 Unlike @code{while}, it stops the loop using @code{return nil} so that
2606 the @code{finally} clauses are not executed. If all the conditions
2607 were non-@code{nil}, the loop returns @code{t}:
2610 (if (loop for size in size-list always (> size 10))
2615 @item never @var{condition}
2616 This clause is like @code{always}, except that the loop returns
2617 @code{t} if any conditions were false, or @code{nil} otherwise.
2619 @item thereis @var{condition}
2620 This clause stops the loop when the specified form is non-@code{nil};
2621 in this case, it returns that non-@code{nil} value. If all the
2622 values were @code{nil}, the loop returns @code{nil}.
2625 @node Accumulation Clauses
2626 @subsection Accumulation Clauses
2629 These clauses cause the loop to accumulate information about the
2630 specified Lisp @var{form}. The accumulated result is returned
2631 from the loop unless overridden, say, by a @code{return} clause.
2634 @item collect @var{form}
2635 This clause collects the values of @var{form} into a list. Several
2636 examples of @code{collect} appear elsewhere in this manual.
2638 The word @code{collecting} is a synonym for @code{collect}, and
2639 likewise for the other accumulation clauses.
2641 @item append @var{form}
2642 This clause collects lists of values into a result list using
2645 @item nconc @var{form}
2646 This clause collects lists of values into a result list by
2647 destructively modifying the lists rather than copying them.
2649 @item concat @var{form}
2650 This clause concatenates the values of the specified @var{form}
2651 into a string. (It and the following clause are extensions to
2652 standard Common Lisp.)
2654 @item vconcat @var{form}
2655 This clause concatenates the values of the specified @var{form}
2658 @item count @var{form}
2659 This clause counts the number of times the specified @var{form}
2660 evaluates to a non-@code{nil} value.
2662 @item sum @var{form}
2663 This clause accumulates the sum of the values of the specified
2664 @var{form}, which must evaluate to a number.
2666 @item maximize @var{form}
2667 This clause accumulates the maximum value of the specified @var{form},
2668 which must evaluate to a number. The return value is undefined if
2669 @code{maximize} is executed zero times.
2671 @item minimize @var{form}
2672 This clause accumulates the minimum value of the specified @var{form}.
2675 Accumulation clauses can be followed by @samp{into @var{var}} to
2676 cause the data to be collected into variable @var{var} (which is
2677 automatically @code{let}-bound during the loop) rather than an
2678 unnamed temporary variable. Also, @code{into} accumulations do
2679 not automatically imply a return value. The loop must use some
2680 explicit mechanism, such as @code{finally return}, to return
2681 the accumulated result.
2683 It is valid for several accumulation clauses of the same type to
2684 accumulate into the same place. From Steele:
2687 (loop for name in '(fred sue alice joe june)
2688 for kids in '((bob ken) () () (kris sunshine) ())
2691 @result{} (fred bob ken sue alice joe kris sunshine june)
2695 @subsection Other Clauses
2698 This section describes the remaining loop clauses.
2701 @item with @var{var} = @var{value}
2702 This clause binds a variable to a value around the loop, but
2703 otherwise leaves the variable alone during the loop. The following
2704 loops are basically equivalent:
2707 (loop with x = 17 do ...)
2708 (let ((x 17)) (loop do ...))
2709 (loop for x = 17 then x do ...)
2712 Naturally, the variable @var{var} might be used for some purpose
2713 in the rest of the loop. For example:
2716 (loop for x in my-list with res = nil do (push x res)
2720 This loop inserts the elements of @code{my-list} at the front of
2721 a new list being accumulated in @code{res}, then returns the
2722 list @code{res} at the end of the loop. The effect is similar
2723 to that of a @code{collect} clause, but the list gets reversed
2724 by virtue of the fact that elements are being pushed onto the
2725 front of @code{res} rather than the end.
2727 If you omit the @code{=} term, the variable is initialized to
2728 @code{nil}. (Thus the @samp{= nil} in the above example is
2731 Bindings made by @code{with} are sequential by default, as if
2732 by @code{let*}. Just like @code{for} clauses, @code{with} clauses
2733 can be linked with @code{and} to cause the bindings to be made by
2736 @item if @var{condition} @var{clause}
2737 This clause executes the following loop clause only if the specified
2738 condition is true. The following @var{clause} should be an accumulation,
2739 @code{do}, @code{return}, @code{if}, or @code{unless} clause.
2740 Several clauses may be linked by separating them with @code{and}.
2741 These clauses may be followed by @code{else} and a clause or clauses
2742 to execute if the condition was false. The whole construct may
2743 optionally be followed by the word @code{end} (which may be used to
2744 disambiguate an @code{else} or @code{and} in a nested @code{if}).
2746 The actual non-@code{nil} value of the condition form is available
2747 by the name @code{it} in the ``then'' part. For example:
2750 (setq funny-numbers '(6 13 -1))
2752 (loop for x below 10
2755 and if (memq x funny-numbers) return (cdr it) end
2757 collect x into evens
2758 finally return (vector odds evens))
2759 @result{} [(1 3 5 7 9) (0 2 4 6 8)]
2760 (setq funny-numbers '(6 7 13 -1))
2761 @result{} (6 7 13 -1)
2762 (loop <@r{same thing again}>)
2766 Note the use of @code{and} to put two clauses into the ``then''
2767 part, one of which is itself an @code{if} clause. Note also that
2768 @code{end}, while normally optional, was necessary here to make
2769 it clear that the @code{else} refers to the outermost @code{if}
2770 clause. In the first case, the loop returns a vector of lists
2771 of the odd and even values of @var{x}. In the second case, the
2772 odd number 7 is one of the @code{funny-numbers} so the loop
2773 returns early; the actual returned value is based on the result
2774 of the @code{memq} call.
2776 @item when @var{condition} @var{clause}
2777 This clause is just a synonym for @code{if}.
2779 @item unless @var{condition} @var{clause}
2780 The @code{unless} clause is just like @code{if} except that the
2781 sense of the condition is reversed.
2783 @item named @var{name}
2784 This clause gives a name other than @code{nil} to the implicit
2785 block surrounding the loop. The @var{name} is the symbol to be
2786 used as the block name.
2788 @item initially [do] @var{forms}...
2789 This keyword introduces one or more Lisp forms which will be
2790 executed before the loop itself begins (but after any variables
2791 requested by @code{for} or @code{with} have been bound to their
2792 initial values). @code{initially} clauses can appear anywhere;
2793 if there are several, they are executed in the order they appear
2794 in the loop. The keyword @code{do} is optional.
2796 @item finally [do] @var{forms}...
2797 This introduces Lisp forms which will be executed after the loop
2798 finishes (say, on request of a @code{for} or @code{while}).
2799 @code{initially} and @code{finally} clauses may appear anywhere
2800 in the loop construct, but they are executed (in the specified
2801 order) at the beginning or end, respectively, of the loop.
2803 @item finally return @var{form}
2804 This says that @var{form} should be executed after the loop
2805 is done to obtain a return value. (Without this, or some other
2806 clause like @code{collect} or @code{return}, the loop will simply
2807 return @code{nil}.) Variables bound by @code{for}, @code{with},
2808 or @code{into} will still contain their final values when @var{form}
2811 @item do @var{forms}...
2812 The word @code{do} may be followed by any number of Lisp expressions
2813 which are executed as an implicit @code{progn} in the body of the
2814 loop. Many of the examples in this section illustrate the use of
2817 @item return @var{form}
2818 This clause causes the loop to return immediately. The following
2819 Lisp form is evaluated to give the return value of the @code{loop}
2820 form. The @code{finally} clauses, if any, are not executed.
2821 Of course, @code{return} is generally used inside an @code{if} or
2822 @code{unless}, as its use in a top-level loop clause would mean
2823 the loop would never get to ``loop'' more than once.
2825 The clause @samp{return @var{form}} is equivalent to
2826 @samp{do (return @var{form})} (or @code{return-from} if the loop
2827 was named). The @code{return} clause is implemented a bit more
2828 efficiently, though.
2831 While there is no high-level way to add user extensions to @code{loop}
2832 (comparable to @code{defsetf} for @code{setf}, say), this package
2833 does offer two properties called @code{cl-loop-handler} and
2834 @code{cl-loop-for-handler} which are functions to be called when
2835 a given symbol is encountered as a top-level loop clause or
2836 @code{for} clause, respectively. Consult the source code in
2837 file @file{cl-macs.el} for details.
2839 This package's @code{loop} macro is compatible with that of Common
2840 Lisp, except that a few features are not implemented: @code{loop-finish}
2841 and data-type specifiers. Naturally, the @code{for} clauses which
2842 iterate over keymaps, overlays, intervals, frames, windows, and
2843 buffers are Emacs-specific extensions.
2845 @node Multiple Values
2846 @section Multiple Values
2849 Common Lisp functions can return zero or more results. Emacs Lisp
2850 functions, by contrast, always return exactly one result. This
2851 package makes no attempt to emulate Common Lisp multiple return
2852 values; Emacs versions of Common Lisp functions that return more
2853 than one value either return just the first value (as in
2854 @code{compiler-macroexpand}) or return a list of values (as in
2855 @code{get-setf-method}). This package @emph{does} define placeholders
2856 for the Common Lisp functions that work with multiple values, but
2857 in Emacs Lisp these functions simply operate on lists instead.
2858 The @code{values} form, for example, is a synonym for @code{list}
2861 @defspec multiple-value-bind (var@dots{}) values-form forms@dots{}
2862 This form evaluates @var{values-form}, which must return a list of
2863 values. It then binds the @var{var}s to these respective values,
2864 as if by @code{let}, and then executes the body @var{forms}.
2865 If there are more @var{var}s than values, the extra @var{var}s
2866 are bound to @code{nil}. If there are fewer @var{var}s than
2867 values, the excess values are ignored.
2870 @defspec multiple-value-setq (var@dots{}) form
2871 This form evaluates @var{form}, which must return a list of values.
2872 It then sets the @var{var}s to these respective values, as if by
2873 @code{setq}. Extra @var{var}s or values are treated the same as
2874 in @code{multiple-value-bind}.
2877 The older Quiroz package attempted a more faithful (but still
2878 imperfect) emulation of Common Lisp multiple values. The old
2879 method ``usually'' simulated true multiple values quite well,
2880 but under certain circumstances would leave spurious return
2881 values in memory where a later, unrelated @code{multiple-value-bind}
2882 form would see them.
2884 Since a perfect emulation is not feasible in Emacs Lisp, this
2885 package opts to keep it as simple and predictable as possible.
2891 This package implements the various Common Lisp features of
2892 @code{defmacro}, such as destructuring, @code{&environment},
2893 and @code{&body}. Top-level @code{&whole} is not implemented
2894 for @code{defmacro} due to technical difficulties.
2895 @xref{Argument Lists}.
2897 Destructuring is made available to the user by way of the
2900 @defspec destructuring-bind arglist expr forms@dots{}
2901 This macro expands to code which executes @var{forms}, with
2902 the variables in @var{arglist} bound to the list of values
2903 returned by @var{expr}. The @var{arglist} can include all
2904 the features allowed for @code{defmacro} argument lists,
2905 including destructuring. (The @code{&environment} keyword
2906 is not allowed.) The macro expansion will signal an error
2907 if @var{expr} returns a list of the wrong number of arguments
2908 or with incorrect keyword arguments.
2911 This package also includes the Common Lisp @code{define-compiler-macro}
2912 facility, which allows you to define compile-time expansions and
2913 optimizations for your functions.
2915 @defspec define-compiler-macro name arglist forms@dots{}
2916 This form is similar to @code{defmacro}, except that it only expands
2917 calls to @var{name} at compile-time; calls processed by the Lisp
2918 interpreter are not expanded, nor are they expanded by the
2919 @code{macroexpand} function.
2921 The argument list may begin with a @code{&whole} keyword and a
2922 variable. This variable is bound to the macro-call form itself,
2923 i.e., to a list of the form @samp{(@var{name} @var{args}@dots{})}.
2924 If the macro expander returns this form unchanged, then the
2925 compiler treats it as a normal function call. This allows
2926 compiler macros to work as optimizers for special cases of a
2927 function, leaving complicated cases alone.
2929 For example, here is a simplified version of a definition that
2930 appears as a standard part of this package:
2933 (define-compiler-macro member* (&whole form a list &rest keys)
2934 (if (and (null keys)
2935 (eq (car-safe a) 'quote)
2936 (not (floatp-safe (cadr a))))
2942 This definition causes @code{(member* @var{a} @var{list})} to change
2943 to a call to the faster @code{memq} in the common case where @var{a}
2944 is a non-floating-point constant; if @var{a} is anything else, or
2945 if there are any keyword arguments in the call, then the original
2946 @code{member*} call is left intact. (The actual compiler macro
2947 for @code{member*} optimizes a number of other cases, including
2948 common @code{:test} predicates.)
2951 @defun compiler-macroexpand form
2952 This function is analogous to @code{macroexpand}, except that it
2953 expands compiler macros rather than regular macros. It returns
2954 @var{form} unchanged if it is not a call to a function for which
2955 a compiler macro has been defined, or if that compiler macro
2956 decided to punt by returning its @code{&whole} argument. Like
2957 @code{macroexpand}, it expands repeatedly until it reaches a form
2958 for which no further expansion is possible.
2961 @xref{Macro Bindings}, for descriptions of the @code{macrolet}
2962 and @code{symbol-macrolet} forms for making ``local'' macro
2966 @chapter Declarations
2969 Common Lisp includes a complex and powerful ``declaration''
2970 mechanism that allows you to give the compiler special hints
2971 about the types of data that will be stored in particular variables,
2972 and about the ways those variables and functions will be used. This
2973 package defines versions of all the Common Lisp declaration forms:
2974 @code{declare}, @code{locally}, @code{proclaim}, @code{declaim},
2977 Most of the Common Lisp declarations are not currently useful in
2978 Emacs Lisp, as the byte-code system provides little opportunity
2979 to benefit from type information, and @code{special} declarations
2980 are redundant in a fully dynamically-scoped Lisp. A few
2981 declarations are meaningful when the optimizing byte
2982 compiler is being used, however. Under the earlier non-optimizing
2983 compiler, these declarations will effectively be ignored.
2985 @defun proclaim decl-spec
2986 This function records a ``global'' declaration specified by
2987 @var{decl-spec}. Since @code{proclaim} is a function, @var{decl-spec}
2988 is evaluated and thus should normally be quoted.
2991 @defspec declaim decl-specs@dots{}
2992 This macro is like @code{proclaim}, except that it takes any number
2993 of @var{decl-spec} arguments, and the arguments are unevaluated and
2994 unquoted. The @code{declaim} macro also puts an @code{(eval-when
2995 (compile load eval) ...)} around the declarations so that they will
2996 be registered at compile-time as well as at run-time. (This is vital,
2997 since normally the declarations are meant to influence the way the
2998 compiler treats the rest of the file that contains the @code{declaim}
3002 @defspec declare decl-specs@dots{}
3003 This macro is used to make declarations within functions and other
3004 code. Common Lisp allows declarations in various locations, generally
3005 at the beginning of any of the many ``implicit @code{progn}s''
3006 throughout Lisp syntax, such as function bodies, @code{let} bodies,
3007 etc. Currently the only declaration understood by @code{declare}
3011 @defspec locally declarations@dots{} forms@dots{}
3012 In this package, @code{locally} is no different from @code{progn}.
3015 @defspec the type form
3016 Type information provided by @code{the} is ignored in this package;
3017 in other words, @code{(the @var{type} @var{form})} is equivalent
3018 to @var{form}. Future versions of the optimizing byte-compiler may
3019 make use of this information.
3021 For example, @code{mapcar} can map over both lists and arrays. It is
3022 hard for the compiler to expand @code{mapcar} into an in-line loop
3023 unless it knows whether the sequence will be a list or an array ahead
3024 of time. With @code{(mapcar 'car (the vector foo))}, a future
3025 compiler would have enough information to expand the loop in-line.
3026 For now, Emacs Lisp will treat the above code as exactly equivalent
3027 to @code{(mapcar 'car foo)}.
3030 Each @var{decl-spec} in a @code{proclaim}, @code{declaim}, or
3031 @code{declare} should be a list beginning with a symbol that says
3032 what kind of declaration it is. This package currently understands
3033 @code{special}, @code{inline}, @code{notinline}, @code{optimize},
3034 and @code{warn} declarations. (The @code{warn} declaration is an
3035 extension of standard Common Lisp.) Other Common Lisp declarations,
3036 such as @code{type} and @code{ftype}, are silently ignored.
3040 Since all variables in Emacs Lisp are ``special'' (in the Common
3041 Lisp sense), @code{special} declarations are only advisory. They
3042 simply tell the optimizing byte compiler that the specified
3043 variables are intentionally being referred to without being
3044 bound in the body of the function. The compiler normally emits
3045 warnings for such references, since they could be typographical
3046 errors for references to local variables.
3048 The declaration @code{(declare (special @var{var1} @var{var2}))} is
3049 equivalent to @code{(defvar @var{var1}) (defvar @var{var2})} in the
3050 optimizing compiler, or to nothing at all in older compilers (which
3051 do not warn for non-local references).
3053 In top-level contexts, it is generally better to write
3054 @code{(defvar @var{var})} than @code{(declaim (special @var{var}))},
3055 since @code{defvar} makes your intentions clearer. But the older
3056 byte compilers can not handle @code{defvar}s appearing inside of
3057 functions, while @code{(declare (special @var{var}))} takes care
3058 to work correctly with all compilers.
3061 The @code{inline} @var{decl-spec} lists one or more functions
3062 whose bodies should be expanded ``in-line'' into calling functions
3063 whenever the compiler is able to arrange for it. For example,
3064 the Common Lisp function @code{cadr} is declared @code{inline}
3065 by this package so that the form @code{(cadr @var{x})} will
3066 expand directly into @code{(car (cdr @var{x}))} when it is called
3067 in user functions, for a savings of one (relatively expensive)
3070 The following declarations are all equivalent. Note that the
3071 @code{defsubst} form is a convenient way to define a function
3072 and declare it inline all at once.
3075 (declaim (inline foo bar))
3076 (eval-when (compile load eval) (proclaim '(inline foo bar)))
3077 (defsubst foo (...) ...) ; instead of defun
3080 @strong{Please note:} this declaration remains in effect after the
3081 containing source file is done. It is correct to use it to
3082 request that a function you have defined should be inlined,
3083 but it is impolite to use it to request inlining of an external
3086 In Common Lisp, it is possible to use @code{(declare (inline @dots{}))}
3087 before a particular call to a function to cause just that call to
3088 be inlined; the current byte compilers provide no way to implement
3089 this, so @code{(declare (inline @dots{}))} is currently ignored by
3093 The @code{notinline} declaration lists functions which should
3094 not be inlined after all; it cancels a previous @code{inline}
3098 This declaration controls how much optimization is performed by
3099 the compiler. Naturally, it is ignored by the earlier non-optimizing
3102 The word @code{optimize} is followed by any number of lists like
3103 @code{(speed 3)} or @code{(safety 2)}. Common Lisp defines several
3104 optimization ``qualities''; this package ignores all but @code{speed}
3105 and @code{safety}. The value of a quality should be an integer from
3106 0 to 3, with 0 meaning ``unimportant'' and 3 meaning ``very important.''
3107 The default level for both qualities is 1.
3109 In this package, with the optimizing compiler, the
3110 @code{speed} quality is tied to the @code{byte-compile-optimize}
3111 flag, which is set to @code{nil} for @code{(speed 0)} and to
3112 @code{t} for higher settings; and the @code{safety} quality is
3113 tied to the @code{byte-compile-delete-errors} flag, which is
3114 set to @code{t} for @code{(safety 3)} and to @code{nil} for all
3115 lower settings. (The latter flag controls whether the compiler
3116 is allowed to optimize out code whose only side-effect could
3117 be to signal an error, e.g., rewriting @code{(progn foo bar)} to
3118 @code{bar} when it is not known whether @code{foo} will be bound
3121 Note that even compiling with @code{(safety 0)}, the Emacs
3122 byte-code system provides sufficient checking to prevent real
3123 harm from being done. For example, barring serious bugs in
3124 Emacs itself, Emacs will not crash with a segmentation fault
3125 just because of an error in a fully-optimized Lisp program.
3127 The @code{optimize} declaration is normally used in a top-level
3128 @code{proclaim} or @code{declaim} in a file; Common Lisp allows
3129 it to be used with @code{declare} to set the level of optimization
3130 locally for a given form, but this will not work correctly with the
3131 current version of the optimizing compiler. (The @code{declare}
3132 will set the new optimization level, but that level will not
3133 automatically be unset after the enclosing form is done.)
3136 This declaration controls what sorts of warnings are generated
3137 by the byte compiler. Again, only the optimizing compiler
3138 generates warnings. The word @code{warn} is followed by any
3139 number of ``warning qualities,'' similar in form to optimization
3140 qualities. The currently supported warning types are
3141 @code{redefine}, @code{callargs}, @code{unresolved}, and
3142 @code{free-vars}; in the current system, a value of 0 will
3143 disable these warnings and any higher value will enable them.
3144 See the documentation for the optimizing byte compiler for details.
3151 This package defines several symbol-related features that were
3152 missing from Emacs Lisp.
3155 * Property Lists:: @code{get*}, @code{remprop}, @code{getf}, @code{remf}.
3156 * Creating Symbols:: @code{gensym}, @code{gentemp}.
3159 @node Property Lists
3160 @section Property Lists
3163 These functions augment the standard Emacs Lisp functions @code{get}
3164 and @code{put} for operating on properties attached to symbols.
3165 There are also functions for working with property lists as
3166 first-class data structures not attached to particular symbols.
3168 @defun get* symbol property &optional default
3169 This function is like @code{get}, except that if the property is
3170 not found, the @var{default} argument provides the return value.
3171 (The Emacs Lisp @code{get} function always uses @code{nil} as
3172 the default; this package's @code{get*} is equivalent to Common
3175 The @code{get*} function is @code{setf}-able; when used in this
3176 fashion, the @var{default} argument is allowed but ignored.
3179 @defun remprop symbol property
3180 This function removes the entry for @var{property} from the property
3181 list of @var{symbol}. It returns a true value if the property was
3182 indeed found and removed, or @code{nil} if there was no such property.
3183 (This function was probably omitted from Emacs originally because,
3184 since @code{get} did not allow a @var{default}, it was very difficult
3185 to distinguish between a missing property and a property whose value
3186 was @code{nil}; thus, setting a property to @code{nil} was close
3187 enough to @code{remprop} for most purposes.)
3190 @defun getf place property &optional default
3191 This function scans the list @var{place} as if it were a property
3192 list, i.e., a list of alternating property names and values. If
3193 an even-numbered element of @var{place} is found which is @code{eq}
3194 to @var{property}, the following odd-numbered element is returned.
3195 Otherwise, @var{default} is returned (or @code{nil} if no default
3201 (get sym prop) @equiv{} (getf (symbol-plist sym) prop)
3204 It is valid to use @code{getf} as a @code{setf} place, in which case
3205 its @var{place} argument must itself be a valid @code{setf} place.
3206 The @var{default} argument, if any, is ignored in this context.
3207 The effect is to change (via @code{setcar}) the value cell in the
3208 list that corresponds to @var{property}, or to cons a new property-value
3209 pair onto the list if the property is not yet present.
3212 (put sym prop val) @equiv{} (setf (getf (symbol-plist sym) prop) val)
3215 The @code{get} and @code{get*} functions are also @code{setf}-able.
3216 The fact that @code{default} is ignored can sometimes be useful:
3219 (incf (get* 'foo 'usage-count 0))
3222 Here, symbol @code{foo}'s @code{usage-count} property is incremented
3223 if it exists, or set to 1 (an incremented 0) otherwise.
3225 When not used as a @code{setf} form, @code{getf} is just a regular
3226 function and its @var{place} argument can actually be any Lisp
3230 @defspec remf place property
3231 This macro removes the property-value pair for @var{property} from
3232 the property list stored at @var{place}, which is any @code{setf}-able
3233 place expression. It returns true if the property was found. Note
3234 that if @var{property} happens to be first on the list, this will
3235 effectively do a @code{(setf @var{place} (cddr @var{place}))},
3236 whereas if it occurs later, this simply uses @code{setcdr} to splice
3237 out the property and value cells.
3244 @node Creating Symbols
3245 @section Creating Symbols
3248 These functions create unique symbols, typically for use as
3249 temporary variables.
3251 @defun gensym &optional x
3252 This function creates a new, uninterned symbol (using @code{make-symbol})
3253 with a unique name. (The name of an uninterned symbol is relevant
3254 only if the symbol is printed.) By default, the name is generated
3255 from an increasing sequence of numbers, @samp{G1000}, @samp{G1001},
3256 @samp{G1002}, etc. If the optional argument @var{x} is a string, that
3257 string is used as a prefix instead of @samp{G}. Uninterned symbols
3258 are used in macro expansions for temporary variables, to ensure that
3259 their names will not conflict with ``real'' variables in the user's
3263 @defvar *gensym-counter*
3264 This variable holds the counter used to generate @code{gensym} names.
3265 It is incremented after each use by @code{gensym}. In Common Lisp
3266 this is initialized with 0, but this package initializes it with a
3267 random (time-dependent) value to avoid trouble when two files that
3268 each used @code{gensym} in their compilation are loaded together.
3269 (Uninterned symbols become interned when the compiler writes them
3270 out to a file and the Emacs loader loads them, so their names have to
3271 be treated a bit more carefully than in Common Lisp where uninterned
3272 symbols remain uninterned after loading.)
3275 @defun gentemp &optional x
3276 This function is like @code{gensym}, except that it produces a new
3277 @emph{interned} symbol. If the symbol that is generated already
3278 exists, the function keeps incrementing the counter and trying
3279 again until a new symbol is generated.
3282 The Quiroz @file{cl.el} package also defined a @code{defkeyword}
3283 form for creating self-quoting keyword symbols. This package
3284 automatically creates all keywords that are called for by
3285 @code{&key} argument specifiers, and discourages the use of
3286 keywords as data unrelated to keyword arguments, so the
3287 @code{defkeyword} form has been discontinued.
3293 This section defines a few simple Common Lisp operations on numbers
3294 which were left out of Emacs Lisp.
3297 * Predicates on Numbers:: @code{plusp}, @code{oddp}, @code{floatp-safe}, etc.
3298 * Numerical Functions:: @code{abs}, @code{floor*}, etc.
3299 * Random Numbers:: @code{random*}, @code{make-random-state}.
3300 * Implementation Parameters:: @code{most-positive-float}.
3307 @node Predicates on Numbers
3308 @section Predicates on Numbers
3311 These functions return @code{t} if the specified condition is
3312 true of the numerical argument, or @code{nil} otherwise.
3315 This predicate tests whether @var{number} is positive. It is an
3316 error if the argument is not a number.
3319 @defun minusp number
3320 This predicate tests whether @var{number} is negative. It is an
3321 error if the argument is not a number.
3325 This predicate tests whether @var{integer} is odd. It is an
3326 error if the argument is not an integer.
3329 @defun evenp integer
3330 This predicate tests whether @var{integer} is even. It is an
3331 error if the argument is not an integer.
3334 @defun floatp-safe object
3335 This predicate tests whether @var{object} is a floating-point
3336 number. On systems that support floating-point, this is equivalent
3337 to @code{floatp}. On other systems, this always returns @code{nil}.
3344 @node Numerical Functions
3345 @section Numerical Functions
3348 These functions perform various arithmetic operations on numbers.
3350 @defun gcd &rest integers
3351 This function returns the Greatest Common Divisor of the arguments.
3352 For one argument, it returns the absolute value of that argument.
3353 For zero arguments, it returns zero.
3356 @defun lcm &rest integers
3357 This function returns the Least Common Multiple of the arguments.
3358 For one argument, it returns the absolute value of that argument.
3359 For zero arguments, it returns one.
3362 @defun isqrt integer
3363 This function computes the ``integer square root'' of its integer
3364 argument, i.e., the greatest integer less than or equal to the true
3365 square root of the argument.
3368 @defun floor* number &optional divisor
3369 This function implements the Common Lisp @code{floor} function.
3370 It is called @code{floor*} to avoid name conflicts with the
3371 simpler @code{floor} function built-in to Emacs.
3373 With one argument, @code{floor*} returns a list of two numbers:
3374 The argument rounded down (toward minus infinity) to an integer,
3375 and the ``remainder'' which would have to be added back to the
3376 first return value to yield the argument again. If the argument
3377 is an integer @var{x}, the result is always the list @code{(@var{x} 0)}.
3378 If the argument is a floating-point number, the first
3379 result is a Lisp integer and the second is a Lisp float between
3380 0 (inclusive) and 1 (exclusive).
3382 With two arguments, @code{floor*} divides @var{number} by
3383 @var{divisor}, and returns the floor of the quotient and the
3384 corresponding remainder as a list of two numbers. If
3385 @code{(floor* @var{x} @var{y})} returns @code{(@var{q} @var{r})},
3386 then @code{@var{q}*@var{y} + @var{r} = @var{x}}, with @var{r}
3387 between 0 (inclusive) and @var{r} (exclusive). Also, note
3388 that @code{(floor* @var{x})} is exactly equivalent to
3389 @code{(floor* @var{x} 1)}.
3391 This function is entirely compatible with Common Lisp's @code{floor}
3392 function, except that it returns the two results in a list since
3393 Emacs Lisp does not support multiple-valued functions.
3396 @defun ceiling* number &optional divisor
3397 This function implements the Common Lisp @code{ceiling} function,
3398 which is analogous to @code{floor} except that it rounds the
3399 argument or quotient of the arguments up toward plus infinity.
3400 The remainder will be between 0 and minus @var{r}.
3403 @defun truncate* number &optional divisor
3404 This function implements the Common Lisp @code{truncate} function,
3405 which is analogous to @code{floor} except that it rounds the
3406 argument or quotient of the arguments toward zero. Thus it is
3407 equivalent to @code{floor*} if the argument or quotient is
3408 positive, or to @code{ceiling*} otherwise. The remainder has
3409 the same sign as @var{number}.
3412 @defun round* number &optional divisor
3413 This function implements the Common Lisp @code{round} function,
3414 which is analogous to @code{floor} except that it rounds the
3415 argument or quotient of the arguments to the nearest integer.
3416 In the case of a tie (the argument or quotient is exactly
3417 halfway between two integers), it rounds to the even integer.
3420 @defun mod* number divisor
3421 This function returns the same value as the second return value
3425 @defun rem* number divisor
3426 This function returns the same value as the second return value
3430 These definitions are compatible with those in the Quiroz
3431 @file{cl.el} package, except that this package appends @samp{*}
3432 to certain function names to avoid conflicts with existing
3433 Emacs functions, and that the mechanism for returning
3434 multiple values is different.
3440 @node Random Numbers
3441 @section Random Numbers
3444 This package also provides an implementation of the Common Lisp
3445 random number generator. It uses its own additive-congruential
3446 algorithm, which is much more likely to give statistically clean
3447 random numbers than the simple generators supplied by many
3450 @defun random* number &optional state
3451 This function returns a random nonnegative number less than
3452 @var{number}, and of the same type (either integer or floating-point).
3453 The @var{state} argument should be a @code{random-state} object
3454 which holds the state of the random number generator. The
3455 function modifies this state object as a side effect. If
3456 @var{state} is omitted, it defaults to the variable
3457 @code{*random-state*}, which contains a pre-initialized
3458 @code{random-state} object.
3461 @defvar *random-state*
3462 This variable contains the system ``default'' @code{random-state}
3463 object, used for calls to @code{random*} that do not specify an
3464 alternative state object. Since any number of programs in the
3465 Emacs process may be accessing @code{*random-state*} in interleaved
3466 fashion, the sequence generated from this variable will be
3467 irreproducible for all intents and purposes.
3470 @defun make-random-state &optional state
3471 This function creates or copies a @code{random-state} object.
3472 If @var{state} is omitted or @code{nil}, it returns a new copy of
3473 @code{*random-state*}. This is a copy in the sense that future
3474 sequences of calls to @code{(random* @var{n})} and
3475 @code{(random* @var{n} @var{s})} (where @var{s} is the new
3476 random-state object) will return identical sequences of random
3479 If @var{state} is a @code{random-state} object, this function
3480 returns a copy of that object. If @var{state} is @code{t}, this
3481 function returns a new @code{random-state} object seeded from the
3482 date and time. As an extension to Common Lisp, @var{state} may also
3483 be an integer in which case the new object is seeded from that
3484 integer; each different integer seed will result in a completely
3485 different sequence of random numbers.
3487 It is valid to print a @code{random-state} object to a buffer or
3488 file and later read it back with @code{read}. If a program wishes
3489 to use a sequence of pseudo-random numbers which can be reproduced
3490 later for debugging, it can call @code{(make-random-state t)} to
3491 get a new sequence, then print this sequence to a file. When the
3492 program is later rerun, it can read the original run's random-state
3496 @defun random-state-p object
3497 This predicate returns @code{t} if @var{object} is a
3498 @code{random-state} object, or @code{nil} otherwise.
3501 @node Implementation Parameters
3502 @section Implementation Parameters
3505 This package defines several useful constants having to with numbers.
3507 The following parameters have to do with floating-point numbers.
3508 This package determines their values by exercising the computer's
3509 floating-point arithmetic in various ways. Because this operation
3510 might be slow, the code for initializing them is kept in a separate
3511 function that must be called before the parameters can be used.
3513 @defun cl-float-limits
3514 This function makes sure that the Common Lisp floating-point parameters
3515 like @code{most-positive-float} have been initialized. Until it is
3516 called, these parameters will be @code{nil}. If this version of Emacs
3517 does not support floats, the parameters will remain @code{nil}. If the
3518 parameters have already been initialized, the function returns
3521 The algorithm makes assumptions that will be valid for most modern
3522 machines, but will fail if the machine's arithmetic is extremely
3523 unusual, e.g., decimal.
3526 Since true Common Lisp supports up to four different floating-point
3527 precisions, it has families of constants like
3528 @code{most-positive-single-float}, @code{most-positive-double-float},
3529 @code{most-positive-long-float}, and so on. Emacs has only one
3530 floating-point precision, so this package omits the precision word
3531 from the constants' names.
3533 @defvar most-positive-float
3534 This constant equals the largest value a Lisp float can hold.
3535 For those systems whose arithmetic supports infinities, this is
3536 the largest @emph{finite} value. For IEEE machines, the value
3537 is approximately @code{1.79e+308}.
3540 @defvar most-negative-float
3541 This constant equals the most-negative value a Lisp float can hold.
3542 (It is assumed to be equal to @code{(- most-positive-float)}.)
3545 @defvar least-positive-float
3546 This constant equals the smallest Lisp float value greater than zero.
3547 For IEEE machines, it is about @code{4.94e-324} if denormals are
3548 supported or @code{2.22e-308} if not.
3551 @defvar least-positive-normalized-float
3552 This constant equals the smallest @emph{normalized} Lisp float greater
3553 than zero, i.e., the smallest value for which IEEE denormalization
3554 will not result in a loss of precision. For IEEE machines, this
3555 value is about @code{2.22e-308}. For machines that do not support
3556 the concept of denormalization and gradual underflow, this constant
3557 will always equal @code{least-positive-float}.
3560 @defvar least-negative-float
3561 This constant is the negative counterpart of @code{least-positive-float}.
3564 @defvar least-negative-normalized-float
3565 This constant is the negative counterpart of
3566 @code{least-positive-normalized-float}.
3569 @defvar float-epsilon
3570 This constant is the smallest positive Lisp float that can be added
3571 to 1.0 to produce a distinct value. Adding a smaller number to 1.0
3572 will yield 1.0 again due to roundoff. For IEEE machines, epsilon
3573 is about @code{2.22e-16}.
3576 @defvar float-negative-epsilon
3577 This is the smallest positive value that can be subtracted from
3578 1.0 to produce a distinct value. For IEEE machines, it is about
3586 Common Lisp defines a number of functions that operate on
3587 @dfn{sequences}, which are either lists, strings, or vectors.
3588 Emacs Lisp includes a few of these, notably @code{elt} and
3589 @code{length}; this package defines most of the rest.
3592 * Sequence Basics:: Arguments shared by all sequence functions.
3593 * Mapping over Sequences:: @code{mapcar*}, @code{mapcan}, @code{map}, @code{every}, etc.
3594 * Sequence Functions:: @code{subseq}, @code{remove*}, @code{substitute}, etc.
3595 * Searching Sequences:: @code{find}, @code{position}, @code{count}, @code{search}, etc.
3596 * Sorting Sequences:: @code{sort*}, @code{stable-sort}, @code{merge}.
3599 @node Sequence Basics
3600 @section Sequence Basics
3603 Many of the sequence functions take keyword arguments; @pxref{Argument
3604 Lists}. All keyword arguments are optional and, if specified,
3605 may appear in any order.
3607 The @code{:key} argument should be passed either @code{nil}, or a
3608 function of one argument. This key function is used as a filter
3609 through which the elements of the sequence are seen; for example,
3610 @code{(find x y :key 'car)} is similar to @code{(assoc* x y)}:
3611 It searches for an element of the list whose @code{car} equals
3612 @code{x}, rather than for an element which equals @code{x} itself.
3613 If @code{:key} is omitted or @code{nil}, the filter is effectively
3614 the identity function.
3616 The @code{:test} and @code{:test-not} arguments should be either
3617 @code{nil}, or functions of two arguments. The test function is
3618 used to compare two sequence elements, or to compare a search value
3619 with sequence elements. (The two values are passed to the test
3620 function in the same order as the original sequence function
3621 arguments from which they are derived, or, if they both come from
3622 the same sequence, in the same order as they appear in that sequence.)
3623 The @code{:test} argument specifies a function which must return
3624 true (non-@code{nil}) to indicate a match; instead, you may use
3625 @code{:test-not} to give a function which returns @emph{false} to
3626 indicate a match. The default test function is @code{eql}.
3628 Many functions which take @var{item} and @code{:test} or @code{:test-not}
3629 arguments also come in @code{-if} and @code{-if-not} varieties,
3630 where a @var{predicate} function is passed instead of @var{item},
3631 and sequence elements match if the predicate returns true on them
3632 (or false in the case of @code{-if-not}). For example:
3635 (remove* 0 seq :test '=) @equiv{} (remove-if 'zerop seq)
3639 to remove all zeros from sequence @code{seq}.
3641 Some operations can work on a subsequence of the argument sequence;
3642 these function take @code{:start} and @code{:end} arguments which
3643 default to zero and the length of the sequence, respectively.
3644 Only elements between @var{start} (inclusive) and @var{end}
3645 (exclusive) are affected by the operation. The @var{end} argument
3646 may be passed @code{nil} to signify the length of the sequence;
3647 otherwise, both @var{start} and @var{end} must be integers, with
3648 @code{0 <= @var{start} <= @var{end} <= (length @var{seq})}.
3649 If the function takes two sequence arguments, the limits are
3650 defined by keywords @code{:start1} and @code{:end1} for the first,
3651 and @code{:start2} and @code{:end2} for the second.
3653 A few functions accept a @code{:from-end} argument, which, if
3654 non-@code{nil}, causes the operation to go from right-to-left
3655 through the sequence instead of left-to-right, and a @code{:count}
3656 argument, which specifies an integer maximum number of elements
3657 to be removed or otherwise processed.
3659 The sequence functions make no guarantees about the order in
3660 which the @code{:test}, @code{:test-not}, and @code{:key} functions
3661 are called on various elements. Therefore, it is a bad idea to depend
3662 on side effects of these functions. For example, @code{:from-end}
3663 may cause the sequence to be scanned actually in reverse, or it may
3664 be scanned forwards but computing a result ``as if'' it were scanned
3665 backwards. (Some functions, like @code{mapcar*} and @code{every},
3666 @emph{do} specify exactly the order in which the function is called
3667 so side effects are perfectly acceptable in those cases.)
3669 Strings may contain ``text properties'' as well
3670 as character data. Except as noted, it is undefined whether or
3671 not text properties are preserved by sequence functions. For
3672 example, @code{(remove* ?A @var{str})} may or may not preserve
3673 the properties of the characters copied from @var{str} into the
3676 @node Mapping over Sequences
3677 @section Mapping over Sequences
3680 These functions ``map'' the function you specify over the elements
3681 of lists or arrays. They are all variations on the theme of the
3682 built-in function @code{mapcar}.
3684 @defun mapcar* function seq &rest more-seqs
3685 This function calls @var{function} on successive parallel sets of
3686 elements from its argument sequences. Given a single @var{seq}
3687 argument it is equivalent to @code{mapcar}; given @var{n} sequences,
3688 it calls the function with the first elements of each of the sequences
3689 as the @var{n} arguments to yield the first element of the result
3690 list, then with the second elements, and so on. The mapping stops as
3691 soon as the shortest sequence runs out. The argument sequences may
3692 be any mixture of lists, strings, and vectors; the return sequence
3695 Common Lisp's @code{mapcar} accepts multiple arguments but works
3696 only on lists; Emacs Lisp's @code{mapcar} accepts a single sequence
3697 argument. This package's @code{mapcar*} works as a compatible
3701 @defun map result-type function seq &rest more-seqs
3702 This function maps @var{function} over the argument sequences,
3703 just like @code{mapcar*}, but it returns a sequence of type
3704 @var{result-type} rather than a list. @var{result-type} must
3705 be one of the following symbols: @code{vector}, @code{string},
3706 @code{list} (in which case the effect is the same as for
3707 @code{mapcar*}), or @code{nil} (in which case the results are
3708 thrown away and @code{map} returns @code{nil}).
3711 @defun maplist function list &rest more-lists
3712 This function calls @var{function} on each of its argument lists,
3713 then on the @code{cdr}s of those lists, and so on, until the
3714 shortest list runs out. The results are returned in the form
3715 of a list. Thus, @code{maplist} is like @code{mapcar*} except
3716 that it passes in the list pointers themselves rather than the
3717 @code{car}s of the advancing pointers.
3720 @defun cl-mapc function seq &rest more-seqs
3721 This function is like @code{mapcar*}, except that the values returned
3722 by @var{function} are ignored and thrown away rather than being
3723 collected into a list. The return value of @code{cl-mapc} is @var{seq},
3724 the first sequence. This function is more general than the Emacs
3725 primitive @code{mapc}.
3728 @defun mapl function list &rest more-lists
3729 This function is like @code{maplist}, except that it throws away
3730 the values returned by @var{function}.
3733 @defun mapcan function seq &rest more-seqs
3734 This function is like @code{mapcar*}, except that it concatenates
3735 the return values (which must be lists) using @code{nconc},
3736 rather than simply collecting them into a list.
3739 @defun mapcon function list &rest more-lists
3740 This function is like @code{maplist}, except that it concatenates
3741 the return values using @code{nconc}.
3744 @defun some predicate seq &rest more-seqs
3745 This function calls @var{predicate} on each element of @var{seq}
3746 in turn; if @var{predicate} returns a non-@code{nil} value,
3747 @code{some} returns that value, otherwise it returns @code{nil}.
3748 Given several sequence arguments, it steps through the sequences
3749 in parallel until the shortest one runs out, just as in
3750 @code{mapcar*}. You can rely on the left-to-right order in which
3751 the elements are visited, and on the fact that mapping stops
3752 immediately as soon as @var{predicate} returns non-@code{nil}.
3755 @defun every predicate seq &rest more-seqs
3756 This function calls @var{predicate} on each element of the sequence(s)
3757 in turn; it returns @code{nil} as soon as @var{predicate} returns
3758 @code{nil} for any element, or @code{t} if the predicate was true
3762 @defun notany predicate seq &rest more-seqs
3763 This function calls @var{predicate} on each element of the sequence(s)
3764 in turn; it returns @code{nil} as soon as @var{predicate} returns
3765 a non-@code{nil} value for any element, or @code{t} if the predicate
3766 was @code{nil} for all elements.
3769 @defun notevery predicate seq &rest more-seqs
3770 This function calls @var{predicate} on each element of the sequence(s)
3771 in turn; it returns a non-@code{nil} value as soon as @var{predicate}
3772 returns @code{nil} for any element, or @code{t} if the predicate was
3773 true for all elements.
3776 @defun reduce function seq @t{&key :from-end :start :end :initial-value :key}
3777 This function combines the elements of @var{seq} using an associative
3778 binary operation. Suppose @var{function} is @code{*} and @var{seq} is
3779 the list @code{(2 3 4 5)}. The first two elements of the list are
3780 combined with @code{(* 2 3) = 6}; this is combined with the next
3781 element, @code{(* 6 4) = 24}, and that is combined with the final
3782 element: @code{(* 24 5) = 120}. Note that the @code{*} function happens
3783 to be self-reducing, so that @code{(* 2 3 4 5)} has the same effect as
3784 an explicit call to @code{reduce}.
3786 If @code{:from-end} is true, the reduction is right-associative instead
3787 of left-associative:
3790 (reduce '- '(1 2 3 4))
3791 @equiv{} (- (- (- 1 2) 3) 4) @result{} -8
3792 (reduce '- '(1 2 3 4) :from-end t)
3793 @equiv{} (- 1 (- 2 (- 3 4))) @result{} -2
3796 If @code{:key} is specified, it is a function of one argument which
3797 is called on each of the sequence elements in turn.
3799 If @code{:initial-value} is specified, it is effectively added to the
3800 front (or rear in the case of @code{:from-end}) of the sequence.
3801 The @code{:key} function is @emph{not} applied to the initial value.
3803 If the sequence, including the initial value, has exactly one element
3804 then that element is returned without ever calling @var{function}.
3805 If the sequence is empty (and there is no initial value), then
3806 @var{function} is called with no arguments to obtain the return value.
3809 All of these mapping operations can be expressed conveniently in
3810 terms of the @code{loop} macro. In compiled code, @code{loop} will
3811 be faster since it generates the loop as in-line code with no
3814 @node Sequence Functions
3815 @section Sequence Functions
3818 This section describes a number of Common Lisp functions for
3819 operating on sequences.
3821 @defun subseq sequence start &optional end
3822 This function returns a given subsequence of the argument
3823 @var{sequence}, which may be a list, string, or vector.
3824 The indices @var{start} and @var{end} must be in range, and
3825 @var{start} must be no greater than @var{end}. If @var{end}
3826 is omitted, it defaults to the length of the sequence. The
3827 return value is always a copy; it does not share structure
3828 with @var{sequence}.
3830 As an extension to Common Lisp, @var{start} and/or @var{end}
3831 may be negative, in which case they represent a distance back
3832 from the end of the sequence. This is for compatibility with
3833 Emacs's @code{substring} function. Note that @code{subseq} is
3834 the @emph{only} sequence function that allows negative
3835 @var{start} and @var{end}.
3837 You can use @code{setf} on a @code{subseq} form to replace a
3838 specified range of elements with elements from another sequence.
3839 The replacement is done as if by @code{replace}, described below.
3842 @defun concatenate result-type &rest seqs
3843 This function concatenates the argument sequences together to
3844 form a result sequence of type @var{result-type}, one of the
3845 symbols @code{vector}, @code{string}, or @code{list}. The
3846 arguments are always copied, even in cases such as
3847 @code{(concatenate 'list '(1 2 3))} where the result is
3848 identical to an argument.
3851 @defun fill seq item @t{&key :start :end}
3852 This function fills the elements of the sequence (or the specified
3853 part of the sequence) with the value @var{item}.
3856 @defun replace seq1 seq2 @t{&key :start1 :end1 :start2 :end2}
3857 This function copies part of @var{seq2} into part of @var{seq1}.
3858 The sequence @var{seq1} is not stretched or resized; the amount
3859 of data copied is simply the shorter of the source and destination
3860 (sub)sequences. The function returns @var{seq1}.
3862 If @var{seq1} and @var{seq2} are @code{eq}, then the replacement
3863 will work correctly even if the regions indicated by the start
3864 and end arguments overlap. However, if @var{seq1} and @var{seq2}
3865 are lists which share storage but are not @code{eq}, and the
3866 start and end arguments specify overlapping regions, the effect
3870 @defun remove* item seq @t{&key :test :test-not :key :count :start :end :from-end}
3871 This returns a copy of @var{seq} with all elements matching
3872 @var{item} removed. The result may share storage with or be
3873 @code{eq} to @var{seq} in some circumstances, but the original
3874 @var{seq} will not be modified. The @code{:test}, @code{:test-not},
3875 and @code{:key} arguments define the matching test that is used;
3876 by default, elements @code{eql} to @var{item} are removed. The
3877 @code{:count} argument specifies the maximum number of matching
3878 elements that can be removed (only the leftmost @var{count} matches
3879 are removed). The @code{:start} and @code{:end} arguments specify
3880 a region in @var{seq} in which elements will be removed; elements
3881 outside that region are not matched or removed. The @code{:from-end}
3882 argument, if true, says that elements should be deleted from the
3883 end of the sequence rather than the beginning (this matters only
3884 if @var{count} was also specified).
3887 @defun delete* item seq @t{&key :test :test-not :key :count :start :end :from-end}
3888 This deletes all elements of @var{seq} which match @var{item}.
3889 It is a destructive operation. Since Emacs Lisp does not support
3890 stretchable strings or vectors, this is the same as @code{remove*}
3891 for those sequence types. On lists, @code{remove*} will copy the
3892 list if necessary to preserve the original list, whereas
3893 @code{delete*} will splice out parts of the argument list.
3894 Compare @code{append} and @code{nconc}, which are analogous
3895 non-destructive and destructive list operations in Emacs Lisp.
3899 @findex remove-if-not
3901 @findex delete-if-not
3902 The predicate-oriented functions @code{remove-if}, @code{remove-if-not},
3903 @code{delete-if}, and @code{delete-if-not} are defined similarly.
3905 @defun remove-duplicates seq @t{&key :test :test-not :key :start :end :from-end}
3906 This function returns a copy of @var{seq} with duplicate elements
3907 removed. Specifically, if two elements from the sequence match
3908 according to the @code{:test}, @code{:test-not}, and @code{:key}
3909 arguments, only the rightmost one is retained. If @code{:from-end}
3910 is true, the leftmost one is retained instead. If @code{:start} or
3911 @code{:end} is specified, only elements within that subsequence are
3912 examined or removed.
3915 @defun delete-duplicates seq @t{&key :test :test-not :key :start :end :from-end}
3916 This function deletes duplicate elements from @var{seq}. It is
3917 a destructive version of @code{remove-duplicates}.
3920 @defun substitute new old seq @t{&key :test :test-not :key :count :start :end :from-end}
3921 This function returns a copy of @var{seq}, with all elements
3922 matching @var{old} replaced with @var{new}. The @code{:count},
3923 @code{:start}, @code{:end}, and @code{:from-end} arguments may be
3924 used to limit the number of substitutions made.
3927 @defun nsubstitute new old seq @t{&key :test :test-not :key :count :start :end :from-end}
3928 This is a destructive version of @code{substitute}; it performs
3929 the substitution using @code{setcar} or @code{aset} rather than
3930 by returning a changed copy of the sequence.
3933 @findex substitute-if
3934 @findex substitute-if-not
3935 @findex nsubstitute-if
3936 @findex nsubstitute-if-not
3937 The @code{substitute-if}, @code{substitute-if-not}, @code{nsubstitute-if},
3938 and @code{nsubstitute-if-not} functions are defined similarly. For
3939 these, a @var{predicate} is given in place of the @var{old} argument.
3941 @node Searching Sequences
3942 @section Searching Sequences
3945 These functions search for elements or subsequences in a sequence.
3946 (See also @code{member*} and @code{assoc*}; @pxref{Lists}.)
3948 @defun find item seq @t{&key :test :test-not :key :start :end :from-end}
3949 This function searches @var{seq} for an element matching @var{item}.
3950 If it finds a match, it returns the matching element. Otherwise,
3951 it returns @code{nil}. It returns the leftmost match, unless
3952 @code{:from-end} is true, in which case it returns the rightmost
3953 match. The @code{:start} and @code{:end} arguments may be used to
3954 limit the range of elements that are searched.
3957 @defun position item seq @t{&key :test :test-not :key :start :end :from-end}
3958 This function is like @code{find}, except that it returns the
3959 integer position in the sequence of the matching item rather than
3960 the item itself. The position is relative to the start of the
3961 sequence as a whole, even if @code{:start} is non-zero. The function
3962 returns @code{nil} if no matching element was found.
3965 @defun count item seq @t{&key :test :test-not :key :start :end}
3966 This function returns the number of elements of @var{seq} which
3967 match @var{item}. The result is always a nonnegative integer.
3973 @findex position-if-not
3975 @findex count-if-not
3976 The @code{find-if}, @code{find-if-not}, @code{position-if},
3977 @code{position-if-not}, @code{count-if}, and @code{count-if-not}
3978 functions are defined similarly.
3980 @defun mismatch seq1 seq2 @t{&key :test :test-not :key :start1 :end1 :start2 :end2 :from-end}
3981 This function compares the specified parts of @var{seq1} and
3982 @var{seq2}. If they are the same length and the corresponding
3983 elements match (according to @code{:test}, @code{:test-not},
3984 and @code{:key}), the function returns @code{nil}. If there is
3985 a mismatch, the function returns the index (relative to @var{seq1})
3986 of the first mismatching element. This will be the leftmost pair of
3987 elements which do not match, or the position at which the shorter of
3988 the two otherwise-matching sequences runs out.
3990 If @code{:from-end} is true, then the elements are compared from right
3991 to left starting at @code{(1- @var{end1})} and @code{(1- @var{end2})}.
3992 If the sequences differ, then one plus the index of the rightmost
3993 difference (relative to @var{seq1}) is returned.
3995 An interesting example is @code{(mismatch str1 str2 :key 'upcase)},
3996 which compares two strings case-insensitively.
3999 @defun search seq1 seq2 @t{&key :test :test-not :key :from-end :start1 :end1 :start2 :end2}
4000 This function searches @var{seq2} for a subsequence that matches
4001 @var{seq1} (or part of it specified by @code{:start1} and
4002 @code{:end1}.) Only matches which fall entirely within the region
4003 defined by @code{:start2} and @code{:end2} will be considered.
4004 The return value is the index of the leftmost element of the
4005 leftmost match, relative to the start of @var{seq2}, or @code{nil}
4006 if no matches were found. If @code{:from-end} is true, the
4007 function finds the @emph{rightmost} matching subsequence.
4010 @node Sorting Sequences
4011 @section Sorting Sequences
4013 @defun sort* seq predicate @t{&key :key}
4014 This function sorts @var{seq} into increasing order as determined
4015 by using @var{predicate} to compare pairs of elements. @var{predicate}
4016 should return true (non-@code{nil}) if and only if its first argument
4017 is less than (not equal to) its second argument. For example,
4018 @code{<} and @code{string-lessp} are suitable predicate functions
4019 for sorting numbers and strings, respectively; @code{>} would sort
4020 numbers into decreasing rather than increasing order.
4022 This function differs from Emacs's built-in @code{sort} in that it
4023 can operate on any type of sequence, not just lists. Also, it
4024 accepts a @code{:key} argument which is used to preprocess data
4025 fed to the @var{predicate} function. For example,
4028 (setq data (sort* data 'string-lessp :key 'downcase))
4032 sorts @var{data}, a sequence of strings, into increasing alphabetical
4033 order without regard to case. A @code{:key} function of @code{car}
4034 would be useful for sorting association lists. It should only be a
4035 simple accessor though, it's used heavily in the current
4038 The @code{sort*} function is destructive; it sorts lists by actually
4039 rearranging the @code{cdr} pointers in suitable fashion.
4042 @defun stable-sort seq predicate @t{&key :key}
4043 This function sorts @var{seq} @dfn{stably}, meaning two elements
4044 which are equal in terms of @var{predicate} are guaranteed not to
4045 be rearranged out of their original order by the sort.
4047 In practice, @code{sort*} and @code{stable-sort} are equivalent
4048 in Emacs Lisp because the underlying @code{sort} function is
4049 stable by default. However, this package reserves the right to
4050 use non-stable methods for @code{sort*} in the future.
4053 @defun merge type seq1 seq2 predicate @t{&key :key}
4054 This function merges two sequences @var{seq1} and @var{seq2} by
4055 interleaving their elements. The result sequence, of type @var{type}
4056 (in the sense of @code{concatenate}), has length equal to the sum
4057 of the lengths of the two input sequences. The sequences may be
4058 modified destructively. Order of elements within @var{seq1} and
4059 @var{seq2} is preserved in the interleaving; elements of the two
4060 sequences are compared by @var{predicate} (in the sense of
4061 @code{sort}) and the lesser element goes first in the result.
4062 When elements are equal, those from @var{seq1} precede those from
4063 @var{seq2} in the result. Thus, if @var{seq1} and @var{seq2} are
4064 both sorted according to @var{predicate}, then the result will be
4065 a merged sequence which is (stably) sorted according to
4073 The functions described here operate on lists.
4076 * List Functions:: @code{caddr}, @code{first}, @code{list*}, etc.
4077 * Substitution of Expressions:: @code{subst}, @code{sublis}, etc.
4078 * Lists as Sets:: @code{member*}, @code{adjoin}, @code{union}, etc.
4079 * Association Lists:: @code{assoc*}, @code{rassoc*}, @code{acons}, @code{pairlis}.
4082 @node List Functions
4083 @section List Functions
4086 This section describes a number of simple operations on lists,
4087 i.e., chains of cons cells.
4090 This function is equivalent to @code{(car (cdr (cdr @var{x})))}.
4091 Likewise, this package defines all 28 @code{c@var{xxx}r} functions
4092 where @var{xxx} is up to four @samp{a}s and/or @samp{d}s.
4093 All of these functions are @code{setf}-able, and calls to them
4094 are expanded inline by the byte-compiler for maximum efficiency.
4098 This function is a synonym for @code{(car @var{x})}. Likewise,
4099 the functions @code{second}, @code{third}, @dots{}, through
4100 @code{tenth} return the given element of the list @var{x}.
4104 This function is a synonym for @code{(cdr @var{x})}.
4108 Common Lisp defines this function to act like @code{null}, but
4109 signaling an error if @code{x} is neither a @code{nil} nor a
4110 cons cell. This package simply defines @code{endp} as a synonym
4114 @defun list-length x
4115 This function returns the length of list @var{x}, exactly like
4116 @code{(length @var{x})}, except that if @var{x} is a circular
4117 list (where the cdr-chain forms a loop rather than terminating
4118 with @code{nil}), this function returns @code{nil}. (The regular
4119 @code{length} function would get stuck if given a circular list.)
4122 @defun list* arg &rest others
4123 This function constructs a list of its arguments. The final
4124 argument becomes the @code{cdr} of the last cell constructed.
4125 Thus, @code{(list* @var{a} @var{b} @var{c})} is equivalent to
4126 @code{(cons @var{a} (cons @var{b} @var{c}))}, and
4127 @code{(list* @var{a} @var{b} nil)} is equivalent to
4128 @code{(list @var{a} @var{b})}.
4130 (Note that this function really is called @code{list*} in Common
4131 Lisp; it is not a name invented for this package like @code{member*}
4135 @defun ldiff list sublist
4136 If @var{sublist} is a sublist of @var{list}, i.e., is @code{eq} to
4137 one of the cons cells of @var{list}, then this function returns
4138 a copy of the part of @var{list} up to but not including
4139 @var{sublist}. For example, @code{(ldiff x (cddr x))} returns
4140 the first two elements of the list @code{x}. The result is a
4141 copy; the original @var{list} is not modified. If @var{sublist}
4142 is not a sublist of @var{list}, a copy of the entire @var{list}
4146 @defun copy-list list
4147 This function returns a copy of the list @var{list}. It copies
4148 dotted lists like @code{(1 2 . 3)} correctly.
4151 @defun copy-tree x &optional vecp
4152 This function returns a copy of the tree of cons cells @var{x}.
4153 Unlike @code{copy-sequence} (and its alias @code{copy-list}),
4154 which copies only along the @code{cdr} direction, this function
4155 copies (recursively) along both the @code{car} and the @code{cdr}
4156 directions. If @var{x} is not a cons cell, the function simply
4157 returns @var{x} unchanged. If the optional @var{vecp} argument
4158 is true, this function copies vectors (recursively) as well as
4162 @defun tree-equal x y @t{&key :test :test-not :key}
4163 This function compares two trees of cons cells. If @var{x} and
4164 @var{y} are both cons cells, their @code{car}s and @code{cdr}s are
4165 compared recursively. If neither @var{x} nor @var{y} is a cons
4166 cell, they are compared by @code{eql}, or according to the
4167 specified test. The @code{:key} function, if specified, is
4168 applied to the elements of both trees. @xref{Sequences}.
4175 @node Substitution of Expressions
4176 @section Substitution of Expressions
4179 These functions substitute elements throughout a tree of cons
4180 cells. (@xref{Sequence Functions}, for the @code{substitute}
4181 function, which works on just the top-level elements of a list.)
4183 @defun subst new old tree @t{&key :test :test-not :key}
4184 This function substitutes occurrences of @var{old} with @var{new}
4185 in @var{tree}, a tree of cons cells. It returns a substituted
4186 tree, which will be a copy except that it may share storage with
4187 the argument @var{tree} in parts where no substitutions occurred.
4188 The original @var{tree} is not modified. This function recurses
4189 on, and compares against @var{old}, both @code{car}s and @code{cdr}s
4190 of the component cons cells. If @var{old} is itself a cons cell,
4191 then matching cells in the tree are substituted as usual without
4192 recursively substituting in that cell. Comparisons with @var{old}
4193 are done according to the specified test (@code{eql} by default).
4194 The @code{:key} function is applied to the elements of the tree
4195 but not to @var{old}.
4198 @defun nsubst new old tree @t{&key :test :test-not :key}
4199 This function is like @code{subst}, except that it works by
4200 destructive modification (by @code{setcar} or @code{setcdr})
4201 rather than copying.
4205 @findex subst-if-not
4207 @findex nsubst-if-not
4208 The @code{subst-if}, @code{subst-if-not}, @code{nsubst-if}, and
4209 @code{nsubst-if-not} functions are defined similarly.
4211 @defun sublis alist tree @t{&key :test :test-not :key}
4212 This function is like @code{subst}, except that it takes an
4213 association list @var{alist} of @var{old}-@var{new} pairs.
4214 Each element of the tree (after applying the @code{:key}
4215 function, if any), is compared with the @code{car}s of
4216 @var{alist}; if it matches, it is replaced by the corresponding
4220 @defun nsublis alist tree @t{&key :test :test-not :key}
4221 This is a destructive version of @code{sublis}.
4225 @section Lists as Sets
4228 These functions perform operations on lists which represent sets
4231 @defun member* item list @t{&key :test :test-not :key}
4232 This function searches @var{list} for an element matching @var{item}.
4233 If a match is found, it returns the cons cell whose @code{car} was
4234 the matching element. Otherwise, it returns @code{nil}. Elements
4235 are compared by @code{eql} by default; you can use the @code{:test},
4236 @code{:test-not}, and @code{:key} arguments to modify this behavior.
4239 Note that this function's name is suffixed by @samp{*} to avoid
4240 the incompatible @code{member} function defined in Emacs.
4241 (That function uses @code{equal} for comparisons; it is equivalent
4242 to @code{(member* @var{item} @var{list} :test 'equal)}.)
4246 @findex member-if-not
4247 The @code{member-if} and @code{member-if-not} functions
4248 analogously search for elements which satisfy a given predicate.
4250 @defun tailp sublist list
4251 This function returns @code{t} if @var{sublist} is a sublist of
4252 @var{list}, i.e., if @var{sublist} is @code{eql} to @var{list} or to
4253 any of its @code{cdr}s.
4256 @defun adjoin item list @t{&key :test :test-not :key}
4257 This function conses @var{item} onto the front of @var{list},
4258 like @code{(cons @var{item} @var{list})}, but only if @var{item}
4259 is not already present on the list (as determined by @code{member*}).
4260 If a @code{:key} argument is specified, it is applied to
4261 @var{item} as well as to the elements of @var{list} during
4262 the search, on the reasoning that @var{item} is ``about'' to
4263 become part of the list.
4266 @defun union list1 list2 @t{&key :test :test-not :key}
4267 This function combines two lists which represent sets of items,
4268 returning a list that represents the union of those two sets.
4269 The result list will contain all items which appear in @var{list1}
4270 or @var{list2}, and no others. If an item appears in both
4271 @var{list1} and @var{list2} it will be copied only once. If
4272 an item is duplicated in @var{list1} or @var{list2}, it is
4273 undefined whether or not that duplication will survive in the
4274 result list. The order of elements in the result list is also
4278 @defun nunion list1 list2 @t{&key :test :test-not :key}
4279 This is a destructive version of @code{union}; rather than copying,
4280 it tries to reuse the storage of the argument lists if possible.
4283 @defun intersection list1 list2 @t{&key :test :test-not :key}
4284 This function computes the intersection of the sets represented
4285 by @var{list1} and @var{list2}. It returns the list of items
4286 which appear in both @var{list1} and @var{list2}.
4289 @defun nintersection list1 list2 @t{&key :test :test-not :key}
4290 This is a destructive version of @code{intersection}. It
4291 tries to reuse storage of @var{list1} rather than copying.
4292 It does @emph{not} reuse the storage of @var{list2}.
4295 @defun set-difference list1 list2 @t{&key :test :test-not :key}
4296 This function computes the ``set difference'' of @var{list1}
4297 and @var{list2}, i.e., the set of elements that appear in
4298 @var{list1} but @emph{not} in @var{list2}.
4301 @defun nset-difference list1 list2 @t{&key :test :test-not :key}
4302 This is a destructive @code{set-difference}, which will try
4303 to reuse @var{list1} if possible.
4306 @defun set-exclusive-or list1 list2 @t{&key :test :test-not :key}
4307 This function computes the ``set exclusive or'' of @var{list1}
4308 and @var{list2}, i.e., the set of elements that appear in
4309 exactly one of @var{list1} and @var{list2}.
4312 @defun nset-exclusive-or list1 list2 @t{&key :test :test-not :key}
4313 This is a destructive @code{set-exclusive-or}, which will try
4314 to reuse @var{list1} and @var{list2} if possible.
4317 @defun subsetp list1 list2 @t{&key :test :test-not :key}
4318 This function checks whether @var{list1} represents a subset
4319 of @var{list2}, i.e., whether every element of @var{list1}
4320 also appears in @var{list2}.
4323 @node Association Lists
4324 @section Association Lists
4327 An @dfn{association list} is a list representing a mapping from
4328 one set of values to another; any list whose elements are cons
4329 cells is an association list.
4331 @defun assoc* item a-list @t{&key :test :test-not :key}
4332 This function searches the association list @var{a-list} for an
4333 element whose @code{car} matches (in the sense of @code{:test},
4334 @code{:test-not}, and @code{:key}, or by comparison with @code{eql})
4335 a given @var{item}. It returns the matching element, if any,
4336 otherwise @code{nil}. It ignores elements of @var{a-list} which
4337 are not cons cells. (This corresponds to the behavior of
4338 @code{assq} and @code{assoc} in Emacs Lisp; Common Lisp's
4339 @code{assoc} ignores @code{nil}s but considers any other non-cons
4340 elements of @var{a-list} to be an error.)
4343 @defun rassoc* item a-list @t{&key :test :test-not :key}
4344 This function searches for an element whose @code{cdr} matches
4345 @var{item}. If @var{a-list} represents a mapping, this applies
4346 the inverse of the mapping to @var{item}.
4350 @findex assoc-if-not
4352 @findex rassoc-if-not
4353 The @code{assoc-if}, @code{assoc-if-not}, @code{rassoc-if},
4354 and @code{rassoc-if-not} functions are defined similarly.
4356 Two simple functions for constructing association lists are:
4358 @defun acons key value alist
4359 This is equivalent to @code{(cons (cons @var{key} @var{value}) @var{alist})}.
4362 @defun pairlis keys values &optional alist
4363 This is equivalent to @code{(nconc (mapcar* 'cons @var{keys} @var{values})
4371 The Common Lisp @dfn{structure} mechanism provides a general way
4372 to define data types similar to C's @code{struct} types. A
4373 structure is a Lisp object containing some number of @dfn{slots},
4374 each of which can hold any Lisp data object. Functions are
4375 provided for accessing and setting the slots, creating or copying
4376 structure objects, and recognizing objects of a particular structure
4379 In true Common Lisp, each structure type is a new type distinct
4380 from all existing Lisp types. Since the underlying Emacs Lisp
4381 system provides no way to create new distinct types, this package
4382 implements structures as vectors (or lists upon request) with a
4383 special ``tag'' symbol to identify them.
4385 @defspec defstruct name slots@dots{}
4386 The @code{defstruct} form defines a new structure type called
4387 @var{name}, with the specified @var{slots}. (The @var{slots}
4388 may begin with a string which documents the structure type.)
4389 In the simplest case, @var{name} and each of the @var{slots}
4390 are symbols. For example,
4393 (defstruct person name age sex)
4397 defines a struct type called @code{person} which contains three
4398 slots. Given a @code{person} object @var{p}, you can access those
4399 slots by calling @code{(person-name @var{p})}, @code{(person-age @var{p})},
4400 and @code{(person-sex @var{p})}. You can also change these slots by
4401 using @code{setf} on any of these place forms:
4404 (incf (person-age birthday-boy))
4407 You can create a new @code{person} by calling @code{make-person},
4408 which takes keyword arguments @code{:name}, @code{:age}, and
4409 @code{:sex} to specify the initial values of these slots in the
4410 new object. (Omitting any of these arguments leaves the corresponding
4411 slot ``undefined,'' according to the Common Lisp standard; in Emacs
4412 Lisp, such uninitialized slots are filled with @code{nil}.)
4414 Given a @code{person}, @code{(copy-person @var{p})} makes a new
4415 object of the same type whose slots are @code{eq} to those of @var{p}.
4417 Given any Lisp object @var{x}, @code{(person-p @var{x})} returns
4418 true if @var{x} looks like a @code{person}, false otherwise. (Again,
4419 in Common Lisp this predicate would be exact; in Emacs Lisp the
4420 best it can do is verify that @var{x} is a vector of the correct
4421 length which starts with the correct tag symbol.)
4423 Accessors like @code{person-name} normally check their arguments
4424 (effectively using @code{person-p}) and signal an error if the
4425 argument is the wrong type. This check is affected by
4426 @code{(optimize (safety @dots{}))} declarations. Safety level 1,
4427 the default, uses a somewhat optimized check that will detect all
4428 incorrect arguments, but may use an uninformative error message
4429 (e.g., ``expected a vector'' instead of ``expected a @code{person}'').
4430 Safety level 0 omits all checks except as provided by the underlying
4431 @code{aref} call; safety levels 2 and 3 do rigorous checking that will
4432 always print a descriptive error message for incorrect inputs.
4433 @xref{Declarations}.
4436 (setq dave (make-person :name "Dave" :sex 'male))
4437 @result{} [cl-struct-person "Dave" nil male]
4438 (setq other (copy-person dave))
4439 @result{} [cl-struct-person "Dave" nil male]
4442 (eq (person-name dave) (person-name other))
4446 (person-p [1 2 3 4])
4450 (person-p '[cl-struct-person counterfeit person object])
4454 In general, @var{name} is either a name symbol or a list of a name
4455 symbol followed by any number of @dfn{struct options}; each @var{slot}
4456 is either a slot symbol or a list of the form @samp{(@var{slot-name}
4457 @var{default-value} @var{slot-options}@dots{})}. The @var{default-value}
4458 is a Lisp form which is evaluated any time an instance of the
4459 structure type is created without specifying that slot's value.
4461 Common Lisp defines several slot options, but the only one
4462 implemented in this package is @code{:read-only}. A non-@code{nil}
4463 value for this option means the slot should not be @code{setf}-able;
4464 the slot's value is determined when the object is created and does
4465 not change afterward.
4469 (name nil :read-only t)
4474 Any slot options other than @code{:read-only} are ignored.
4476 For obscure historical reasons, structure options take a different
4477 form than slot options. A structure option is either a keyword
4478 symbol, or a list beginning with a keyword symbol possibly followed
4479 by arguments. (By contrast, slot options are key-value pairs not
4483 (defstruct (person (:constructor create-person)
4489 The following structure options are recognized.
4494 @advance@leftskip-.5@tableindent
4497 The argument is a symbol whose print name is used as the prefix for
4498 the names of slot accessor functions. The default is the name of
4499 the struct type followed by a hyphen. The option @code{(:conc-name p-)}
4500 would change this prefix to @code{p-}. Specifying @code{nil} as an
4501 argument means no prefix, so that the slot names themselves are used
4502 to name the accessor functions.
4505 In the simple case, this option takes one argument which is an
4506 alternate name to use for the constructor function. The default
4507 is @code{make-@var{name}}, e.g., @code{make-person}. The above
4508 example changes this to @code{create-person}. Specifying @code{nil}
4509 as an argument means that no standard constructor should be
4512 In the full form of this option, the constructor name is followed
4513 by an arbitrary argument list. @xref{Program Structure}, for a
4514 description of the format of Common Lisp argument lists. All
4515 options, such as @code{&rest} and @code{&key}, are supported.
4516 The argument names should match the slot names; each slot is
4517 initialized from the corresponding argument. Slots whose names
4518 do not appear in the argument list are initialized based on the
4519 @var{default-value} in their slot descriptor. Also, @code{&optional}
4520 and @code{&key} arguments which don't specify defaults take their
4521 defaults from the slot descriptor. It is valid to include arguments
4522 which don't correspond to slot names; these are useful if they are
4523 referred to in the defaults for optional, keyword, or @code{&aux}
4524 arguments which @emph{do} correspond to slots.
4526 You can specify any number of full-format @code{:constructor}
4527 options on a structure. The default constructor is still generated
4528 as well unless you disable it with a simple-format @code{:constructor}
4534 (:constructor nil) ; no default constructor
4535 (:constructor new-person (name sex &optional (age 0)))
4536 (:constructor new-hound (&key (name "Rover")
4538 &aux (age (* 7 dog-years))
4543 The first constructor here takes its arguments positionally rather
4544 than by keyword. (In official Common Lisp terminology, constructors
4545 that work By Order of Arguments instead of by keyword are called
4546 ``BOA constructors.'' No, I'm not making this up.) For example,
4547 @code{(new-person "Jane" 'female)} generates a person whose slots
4548 are @code{"Jane"}, 0, and @code{female}, respectively.
4550 The second constructor takes two keyword arguments, @code{:name},
4551 which initializes the @code{name} slot and defaults to @code{"Rover"},
4552 and @code{:dog-years}, which does not itself correspond to a slot
4553 but which is used to initialize the @code{age} slot. The @code{sex}
4554 slot is forced to the symbol @code{canine} with no syntax for
4558 The argument is an alternate name for the copier function for
4559 this type. The default is @code{copy-@var{name}}. @code{nil}
4560 means not to generate a copier function. (In this implementation,
4561 all copier functions are simply synonyms for @code{copy-sequence}.)
4564 The argument is an alternate name for the predicate which recognizes
4565 objects of this type. The default is @code{@var{name}-p}. @code{nil}
4566 means not to generate a predicate function. (If the @code{:type}
4567 option is used without the @code{:named} option, no predicate is
4570 In true Common Lisp, @code{typep} is always able to recognize a
4571 structure object even if @code{:predicate} was used. In this
4572 package, @code{typep} simply looks for a function called
4573 @code{@var{typename}-p}, so it will work for structure types
4574 only if they used the default predicate name.
4577 This option implements a very limited form of C++-style inheritance.
4578 The argument is the name of another structure type previously
4579 created with @code{defstruct}. The effect is to cause the new
4580 structure type to inherit all of the included structure's slots
4581 (plus, of course, any new slots described by this struct's slot
4582 descriptors). The new structure is considered a ``specialization''
4583 of the included one. In fact, the predicate and slot accessors
4584 for the included type will also accept objects of the new type.
4586 If there are extra arguments to the @code{:include} option after
4587 the included-structure name, these options are treated as replacement
4588 slot descriptors for slots in the included structure, possibly with
4589 modified default values. Borrowing an example from Steele:
4592 (defstruct person name (age 0) sex)
4594 (defstruct (astronaut (:include person (age 45)))
4596 (favorite-beverage 'tang))
4599 (setq joe (make-person :name "Joe"))
4600 @result{} [cl-struct-person "Joe" 0 nil]
4601 (setq buzz (make-astronaut :name "Buzz"))
4602 @result{} [cl-struct-astronaut "Buzz" 45 nil nil tang]
4604 (list (person-p joe) (person-p buzz))
4606 (list (astronaut-p joe) (astronaut-p buzz))
4611 (astronaut-name joe)
4612 @result{} error: "astronaut-name accessing a non-astronaut"
4615 Thus, if @code{astronaut} is a specialization of @code{person},
4616 then every @code{astronaut} is also a @code{person} (but not the
4617 other way around). Every @code{astronaut} includes all the slots
4618 of a @code{person}, plus extra slots that are specific to
4619 astronauts. Operations that work on people (like @code{person-name})
4620 work on astronauts just like other people.
4622 @item :print-function
4623 In full Common Lisp, this option allows you to specify a function
4624 which is called to print an instance of the structure type. The
4625 Emacs Lisp system offers no hooks into the Lisp printer which would
4626 allow for such a feature, so this package simply ignores
4627 @code{:print-function}.
4630 The argument should be one of the symbols @code{vector} or @code{list}.
4631 This tells which underlying Lisp data type should be used to implement
4632 the new structure type. Vectors are used by default, but
4633 @code{(:type list)} will cause structure objects to be stored as
4636 The vector representation for structure objects has the advantage
4637 that all structure slots can be accessed quickly, although creating
4638 vectors is a bit slower in Emacs Lisp. Lists are easier to create,
4639 but take a relatively long time accessing the later slots.
4642 This option, which takes no arguments, causes a characteristic ``tag''
4643 symbol to be stored at the front of the structure object. Using
4644 @code{:type} without also using @code{:named} will result in a
4645 structure type stored as plain vectors or lists with no identifying
4648 The default, if you don't specify @code{:type} explicitly, is to
4649 use named vectors. Therefore, @code{:named} is only useful in
4650 conjunction with @code{:type}.
4653 (defstruct (person1) name age sex)
4654 (defstruct (person2 (:type list) :named) name age sex)
4655 (defstruct (person3 (:type list)) name age sex)
4657 (setq p1 (make-person1))
4658 @result{} [cl-struct-person1 nil nil nil]
4659 (setq p2 (make-person2))
4660 @result{} (person2 nil nil nil)
4661 (setq p3 (make-person3))
4662 @result{} (nil nil nil)
4669 @result{} error: function person3-p undefined
4672 Since unnamed structures don't have tags, @code{defstruct} is not
4673 able to make a useful predicate for recognizing them. Also,
4674 accessors like @code{person3-name} will be generated but they
4675 will not be able to do any type checking. The @code{person3-name}
4676 function, for example, will simply be a synonym for @code{car} in
4677 this case. By contrast, @code{person2-name} is able to verify
4678 that its argument is indeed a @code{person2} object before
4681 @item :initial-offset
4682 The argument must be a nonnegative integer. It specifies a
4683 number of slots to be left ``empty'' at the front of the
4684 structure. If the structure is named, the tag appears at the
4685 specified position in the list or vector; otherwise, the first
4686 slot appears at that position. Earlier positions are filled
4687 with @code{nil} by the constructors and ignored otherwise. If
4688 the type @code{:include}s another type, then @code{:initial-offset}
4689 specifies a number of slots to be skipped between the last slot
4690 of the included type and the first new slot.
4694 Except as noted, the @code{defstruct} facility of this package is
4695 entirely compatible with that of Common Lisp.
4698 @chapter Assertions and Errors
4701 This section describes two macros that test @dfn{assertions}, i.e.,
4702 conditions which must be true if the program is operating correctly.
4703 Assertions never add to the behavior of a Lisp program; they simply
4704 make ``sanity checks'' to make sure everything is as it should be.
4706 If the optimization property @code{speed} has been set to 3, and
4707 @code{safety} is less than 3, then the byte-compiler will optimize
4708 away the following assertions. Because assertions might be optimized
4709 away, it is a bad idea for them to include side-effects.
4711 @defspec assert test-form [show-args string args@dots{}]
4712 This form verifies that @var{test-form} is true (i.e., evaluates to
4713 a non-@code{nil} value). If so, it returns @code{nil}. If the test
4714 is not satisfied, @code{assert} signals an error.
4716 A default error message will be supplied which includes @var{test-form}.
4717 You can specify a different error message by including a @var{string}
4718 argument plus optional extra arguments. Those arguments are simply
4719 passed to @code{error} to signal the error.
4721 If the optional second argument @var{show-args} is @code{t} instead
4722 of @code{nil}, then the error message (with or without @var{string})
4723 will also include all non-constant arguments of the top-level
4724 @var{form}. For example:
4727 (assert (> x 10) t "x is too small: %d")
4730 This usage of @var{show-args} is an extension to Common Lisp. In
4731 true Common Lisp, the second argument gives a list of @var{places}
4732 which can be @code{setf}'d by the user before continuing from the
4733 error. Since Emacs Lisp does not support continuable errors, it
4734 makes no sense to specify @var{places}.
4737 @defspec check-type form type [string]
4738 This form verifies that @var{form} evaluates to a value of type
4739 @var{type}. If so, it returns @code{nil}. If not, @code{check-type}
4740 signals a @code{wrong-type-argument} error. The default error message
4741 lists the erroneous value along with @var{type} and @var{form}
4742 themselves. If @var{string} is specified, it is included in the
4743 error message in place of @var{type}. For example:
4746 (check-type x (integer 1 *) "a positive integer")
4749 @xref{Type Predicates}, for a description of the type specifiers
4750 that may be used for @var{type}.
4752 Note that in Common Lisp, the first argument to @code{check-type}
4753 must be a @var{place} suitable for use by @code{setf}, because
4754 @code{check-type} signals a continuable error that allows the
4755 user to modify @var{place}.
4758 The following error-related macro is also defined:
4760 @defspec ignore-errors forms@dots{}
4761 This executes @var{forms} exactly like a @code{progn}, except that
4762 errors are ignored during the @var{forms}. More precisely, if
4763 an error is signaled then @code{ignore-errors} immediately
4764 aborts execution of the @var{forms} and returns @code{nil}.
4765 If the @var{forms} complete successfully, @code{ignore-errors}
4766 returns the result of the last @var{form}.
4769 @node Efficiency Concerns
4770 @appendix Efficiency Concerns
4775 Many of the advanced features of this package, such as @code{defun*},
4776 @code{loop}, and @code{setf}, are implemented as Lisp macros. In
4777 byte-compiled code, these complex notations will be expanded into
4778 equivalent Lisp code which is simple and efficient. For example,
4787 are expanded at compile-time to the Lisp forms
4791 (setcar p (cons x (car p)))
4795 which are the most efficient ways of doing these respective operations
4796 in Lisp. Thus, there is no performance penalty for using the more
4797 readable @code{incf} and @code{push} forms in your compiled code.
4799 @emph{Interpreted} code, on the other hand, must expand these macros
4800 every time they are executed. For this reason it is strongly
4801 recommended that code making heavy use of macros be compiled.
4802 (The features labeled ``Special Form'' instead of ``Function'' in
4803 this manual are macros.) A loop using @code{incf} a hundred times
4804 will execute considerably faster if compiled, and will also
4805 garbage-collect less because the macro expansion will not have
4806 to be generated, used, and thrown away a hundred times.
4808 You can find out how a macro expands by using the
4809 @code{cl-prettyexpand} function.
4811 @defun cl-prettyexpand form &optional full
4812 This function takes a single Lisp form as an argument and inserts
4813 a nicely formatted copy of it in the current buffer (which must be
4814 in Lisp mode so that indentation works properly). It also expands
4815 all Lisp macros which appear in the form. The easiest way to use
4816 this function is to go to the @code{*scratch*} buffer and type, say,
4819 (cl-prettyexpand '(loop for x below 10 collect x))
4823 and type @kbd{C-x C-e} immediately after the closing parenthesis;
4831 (setq G1004 (cons x G1004))
4837 will be inserted into the buffer. (The @code{block} macro is
4838 expanded differently in the interpreter and compiler, so
4839 @code{cl-prettyexpand} just leaves it alone. The temporary
4840 variable @code{G1004} was created by @code{gensym}.)
4842 If the optional argument @var{full} is true, then @emph{all}
4843 macros are expanded, including @code{block}, @code{eval-when},
4844 and compiler macros. Expansion is done as if @var{form} were
4845 a top-level form in a file being compiled. For example,
4848 (cl-prettyexpand '(pushnew 'x list))
4849 @print{} (setq list (adjoin 'x list))
4850 (cl-prettyexpand '(pushnew 'x list) t)
4851 @print{} (setq list (if (memq 'x list) list (cons 'x list)))
4852 (cl-prettyexpand '(caddr (member* 'a list)) t)
4853 @print{} (car (cdr (cdr (memq 'a list))))
4856 Note that @code{adjoin}, @code{caddr}, and @code{member*} all
4857 have built-in compiler macros to optimize them in common cases.
4865 @appendixsec Error Checking
4868 Common Lisp compliance has in general not been sacrificed for the
4869 sake of efficiency. A few exceptions have been made for cases
4870 where substantial gains were possible at the expense of marginal
4873 The Common Lisp standard (as embodied in Steele's book) uses the
4874 phrase ``it is an error if'' to indicate a situation which is not
4875 supposed to arise in complying programs; implementations are strongly
4876 encouraged but not required to signal an error in these situations.
4877 This package sometimes omits such error checking in the interest of
4878 compactness and efficiency. For example, @code{do} variable
4879 specifiers are supposed to be lists of one, two, or three forms;
4880 extra forms are ignored by this package rather than signaling a
4881 syntax error. The @code{endp} function is simply a synonym for
4882 @code{null} in this package. Functions taking keyword arguments
4883 will accept an odd number of arguments, treating the trailing
4884 keyword as if it were followed by the value @code{nil}.
4886 Argument lists (as processed by @code{defun*} and friends)
4887 @emph{are} checked rigorously except for the minor point just
4888 mentioned; in particular, keyword arguments are checked for
4889 validity, and @code{&allow-other-keys} and @code{:allow-other-keys}
4890 are fully implemented. Keyword validity checking is slightly
4891 time consuming (though not too bad in byte-compiled code);
4892 you can use @code{&allow-other-keys} to omit this check. Functions
4893 defined in this package such as @code{find} and @code{member*}
4894 do check their keyword arguments for validity.
4901 @appendixsec Optimizing Compiler
4904 Use of the optimizing Emacs compiler is highly recommended; many of the Common
4906 code which can be improved by optimization. In particular,
4907 @code{block}s (whether explicit or implicit in constructs like
4908 @code{defun*} and @code{loop}) carry a fair run-time penalty; the
4909 optimizing compiler removes @code{block}s which are not actually
4910 referenced by @code{return} or @code{return-from} inside the block.
4912 @node Common Lisp Compatibility
4913 @appendix Common Lisp Compatibility
4916 Following is a list of all known incompatibilities between this
4917 package and Common Lisp as documented in Steele (2nd edition).
4919 Certain function names, such as @code{member}, @code{assoc}, and
4920 @code{floor}, were already taken by (incompatible) Emacs Lisp
4921 functions; this package appends @samp{*} to the names of its
4922 Common Lisp versions of these functions.
4924 The word @code{defun*} is required instead of @code{defun} in order
4925 to use extended Common Lisp argument lists in a function. Likewise,
4926 @code{defmacro*} and @code{function*} are versions of those forms
4927 which understand full-featured argument lists. The @code{&whole}
4928 keyword does not work in @code{defmacro} argument lists (except
4929 inside recursive argument lists).
4931 The @code{equal} predicate does not distinguish
4932 between IEEE floating-point plus and minus zero. The @code{equalp}
4933 predicate has several differences with Common Lisp; @pxref{Predicates}.
4935 The @code{setf} mechanism is entirely compatible, except that
4936 setf-methods return a list of five values rather than five
4937 values directly. Also, the new ``@code{setf} function'' concept
4938 (typified by @code{(defun (setf foo) @dots{})}) is not implemented.
4940 The @code{do-all-symbols} form is the same as @code{do-symbols}
4941 with no @var{obarray} argument. In Common Lisp, this form would
4942 iterate over all symbols in all packages. Since Emacs obarrays
4943 are not a first-class package mechanism, there is no way for
4944 @code{do-all-symbols} to locate any but the default obarray.
4946 The @code{loop} macro is complete except that @code{loop-finish}
4947 and type specifiers are unimplemented.
4949 The multiple-value return facility treats lists as multiple
4950 values, since Emacs Lisp cannot support multiple return values
4951 directly. The macros will be compatible with Common Lisp if
4952 @code{values} or @code{values-list} is always used to return to
4953 a @code{multiple-value-bind} or other multiple-value receiver;
4954 if @code{values} is used without @code{multiple-value-@dots{}}
4955 or vice-versa the effect will be different from Common Lisp.
4957 Many Common Lisp declarations are ignored, and others match
4958 the Common Lisp standard in concept but not in detail. For
4959 example, local @code{special} declarations, which are purely
4960 advisory in Emacs Lisp, do not rigorously obey the scoping rules
4961 set down in Steele's book.
4963 The variable @code{*gensym-counter*} starts out with a pseudo-random
4964 value rather than with zero. This is to cope with the fact that
4965 generated symbols become interned when they are written to and
4966 loaded back from a file.
4968 The @code{defstruct} facility is compatible, except that structures
4969 are of type @code{:type vector :named} by default rather than some
4970 special, distinct type. Also, the @code{:type} slot option is ignored.
4972 The second argument of @code{check-type} is treated differently.
4974 @node Old CL Compatibility
4975 @appendix Old CL Compatibility
4978 Following is a list of all known incompatibilities between this package
4979 and the older Quiroz @file{cl.el} package.
4981 This package's emulation of multiple return values in functions is
4982 incompatible with that of the older package. That package attempted
4983 to come as close as possible to true Common Lisp multiple return
4984 values; unfortunately, it could not be 100% reliable and so was prone
4985 to occasional surprises if used freely. This package uses a simpler
4986 method, namely replacing multiple values with lists of values, which
4987 is more predictable though more noticeably different from Common Lisp.
4989 The @code{defkeyword} form and @code{keywordp} function are not
4990 implemented in this package.
4992 The @code{member}, @code{floor}, @code{ceiling}, @code{truncate},
4993 @code{round}, @code{mod}, and @code{rem} functions are suffixed
4994 by @samp{*} in this package to avoid collision with existing
4995 functions in Emacs. The older package simply
4996 redefined these functions, overwriting the built-in meanings and
4997 causing serious portability problems. (Some more
4998 recent versions of the Quiroz package changed the names to
4999 @code{cl-member}, etc.; this package defines the latter names as
5000 aliases for @code{member*}, etc.)
5002 Certain functions in the old package which were buggy or inconsistent
5003 with the Common Lisp standard are incompatible with the conforming
5004 versions in this package. For example, @code{eql} and @code{member}
5005 were synonyms for @code{eq} and @code{memq} in that package, @code{setf}
5006 failed to preserve correct order of evaluation of its arguments, etc.
5008 Finally, unlike the older package, this package is careful to
5009 prefix all of its internal names with @code{cl-}. Except for a
5010 few functions which are explicitly defined as additional features
5011 (such as @code{floatp-safe} and @code{letf}), this package does not
5012 export any non-@samp{cl-} symbols which are not also part of Common
5020 @appendixsec The @code{cl-compat} package
5023 The @code{CL} package includes emulations of some features of the
5024 old @file{cl.el}, in the form of a compatibility package
5025 @code{cl-compat}. This file is obsolete and may be removed in future,
5026 so it should not be used in new code.
5028 The old package defined a number of internal routines without
5029 @code{cl-} prefixes or other annotations. Call to these routines
5030 may have crept into existing Lisp code. @code{cl-compat}
5031 provides emulations of the following internal routines:
5032 @code{pair-with-newsyms}, @code{zip-lists}, @code{unzip-lists},
5033 @code{reassemble-arglists}, @code{duplicate-symbols-p},
5036 Some @code{setf} forms translated into calls to internal
5037 functions that user code might call directly. The functions
5038 @code{setnth}, @code{setnthcdr}, and @code{setelt} fall in
5039 this category; they are defined by @code{cl-compat}, but the
5040 best fix is to change to use @code{setf} properly.
5042 The @code{cl-compat} file defines the keyword functions
5043 @code{keywordp}, @code{keyword-of}, and @code{defkeyword},
5044 which are not defined by the new @code{CL} package because the
5045 use of keywords as data is discouraged.
5047 The @code{build-klist} mechanism for parsing keyword arguments
5048 is emulated by @code{cl-compat}; the @code{with-keyword-args}
5049 macro is not, however, and in any case it's best to change to
5050 use the more natural keyword argument processing offered by
5053 Multiple return values are treated differently by the two
5054 Common Lisp packages. The old package's method was more
5055 compatible with true Common Lisp, though it used heuristics
5056 that caused it to report spurious multiple return values in
5057 certain cases. The @code{cl-compat} package defines a set
5058 of multiple-value macros that are compatible with the old
5059 CL package; again, they are heuristic in nature, but they
5060 are guaranteed to work in any case where the old package's
5061 macros worked. To avoid name collision with the ``official''
5062 multiple-value facilities, the ones in @code{cl-compat} have
5063 capitalized names: @code{Values}, @code{Values-list},
5064 @code{Multiple-value-bind}, etc.
5066 The functions @code{cl-floor}, @code{cl-ceiling}, @code{cl-truncate},
5067 and @code{cl-round} are defined by @code{cl-compat} to use the
5068 old-style multiple-value mechanism, just as they did in the old
5069 package. The newer @code{floor*} and friends return their two
5070 results in a list rather than as multiple values. Note that
5071 older versions of the old package used the unadorned names
5072 @code{floor}, @code{ceiling}, etc.; @code{cl-compat} cannot use
5073 these names because they conflict with Emacs built-ins.
5075 @node Porting Common Lisp
5076 @appendix Porting Common Lisp
5079 This package is meant to be used as an extension to Emacs Lisp,
5080 not as an Emacs implementation of true Common Lisp. Some of the
5081 remaining differences between Emacs Lisp and Common Lisp make it
5082 difficult to port large Common Lisp applications to Emacs. For
5083 one, some of the features in this package are not fully compliant
5084 with ANSI or Steele; @pxref{Common Lisp Compatibility}. But there
5085 are also quite a few features that this package does not provide
5086 at all. Here are some major omissions that you will want to watch out
5087 for when bringing Common Lisp code into Emacs.
5091 Case-insensitivity. Symbols in Common Lisp are case-insensitive
5092 by default. Some programs refer to a function or variable as
5093 @code{foo} in one place and @code{Foo} or @code{FOO} in another.
5094 Emacs Lisp will treat these as three distinct symbols.
5096 Some Common Lisp code is written entirely in upper case. While Emacs
5097 is happy to let the program's own functions and variables use
5098 this convention, calls to Lisp builtins like @code{if} and
5099 @code{defun} will have to be changed to lower case.
5102 Lexical scoping. In Common Lisp, function arguments and @code{let}
5103 bindings apply only to references physically within their bodies
5104 (or within macro expansions in their bodies). Emacs Lisp, by
5105 contrast, uses @dfn{dynamic scoping} wherein a binding to a
5106 variable is visible even inside functions called from the body.
5108 Variables in Common Lisp can be made dynamically scoped by
5109 declaring them @code{special} or using @code{defvar}. In Emacs
5110 Lisp it is as if all variables were declared @code{special}.
5112 Often you can use code that was written for lexical scoping
5113 even in a dynamically scoped Lisp, but not always. Here is
5114 an example of a Common Lisp code fragment that would fail in
5118 (defun map-odd-elements (func list)
5120 for flag = t then (not flag)
5121 collect (if flag x (funcall func x))))
5123 (defun add-odd-elements (list x)
5124 (map-odd-elements (lambda (a) (+ a x)) list))
5128 In Common Lisp, the two functions' usages of @code{x} are completely
5129 independent. In Emacs Lisp, the binding to @code{x} made by
5130 @code{add-odd-elements} will have been hidden by the binding
5131 in @code{map-odd-elements} by the time the @code{(+ a x)} function
5134 (This package avoids such problems in its own mapping functions
5135 by using names like @code{cl-x} instead of @code{x} internally;
5136 as long as you don't use the @code{cl-} prefix for your own
5137 variables no collision can occur.)
5139 @xref{Lexical Bindings}, for a description of the @code{lexical-let}
5140 form which establishes a Common Lisp-style lexical binding, and some
5141 examples of how it differs from Emacs's regular @code{let}.
5144 Reader macros. Common Lisp includes a second type of macro that
5145 works at the level of individual characters. For example, Common
5146 Lisp implements the quote notation by a reader macro called @code{'},
5147 whereas Emacs Lisp's parser just treats quote as a special case.
5148 Some Lisp packages use reader macros to create special syntaxes
5149 for themselves, which the Emacs parser is incapable of reading.
5152 Other syntactic features. Common Lisp provides a number of
5153 notations beginning with @code{#} that the Emacs Lisp parser
5154 won't understand. For example, @samp{#| ... |#} is an
5155 alternate comment notation, and @samp{#+lucid (foo)} tells
5156 the parser to ignore the @code{(foo)} except in Lucid Common
5160 Packages. In Common Lisp, symbols are divided into @dfn{packages}.
5161 Symbols that are Lisp built-ins are typically stored in one package;
5162 symbols that are vendor extensions are put in another, and each
5163 application program would have a package for its own symbols.
5164 Certain symbols are ``exported'' by a package and others are
5165 internal; certain packages ``use'' or import the exported symbols
5166 of other packages. To access symbols that would not normally be
5167 visible due to this importing and exporting, Common Lisp provides
5168 a syntax like @code{package:symbol} or @code{package::symbol}.
5170 Emacs Lisp has a single namespace for all interned symbols, and
5171 then uses a naming convention of putting a prefix like @code{cl-}
5172 in front of the name. Some Emacs packages adopt the Common Lisp-like
5173 convention of using @code{cl:} or @code{cl::} as the prefix.
5174 However, the Emacs parser does not understand colons and just
5175 treats them as part of the symbol name. Thus, while @code{mapcar}
5176 and @code{lisp:mapcar} may refer to the same symbol in Common
5177 Lisp, they are totally distinct in Emacs Lisp. Common Lisp
5178 programs which refer to a symbol by the full name sometimes
5179 and the short name other times will not port cleanly to Emacs.
5181 Emacs Lisp does have a concept of ``obarrays,'' which are
5182 package-like collections of symbols, but this feature is not
5183 strong enough to be used as a true package mechanism.
5186 The @code{format} function is quite different between Common
5187 Lisp and Emacs Lisp. It takes an additional ``destination''
5188 argument before the format string. A destination of @code{nil}
5189 means to format to a string as in Emacs Lisp; a destination
5190 of @code{t} means to write to the terminal (similar to
5191 @code{message} in Emacs). Also, format control strings are
5192 utterly different; @code{~} is used instead of @code{%} to
5193 introduce format codes, and the set of available codes is
5194 much richer. There are no notations like @code{\n} for
5195 string literals; instead, @code{format} is used with the
5196 ``newline'' format code, @code{~%}. More advanced formatting
5197 codes provide such features as paragraph filling, case
5198 conversion, and even loops and conditionals.
5200 While it would have been possible to implement most of Common
5201 Lisp @code{format} in this package (under the name @code{format*},
5202 of course), it was not deemed worthwhile. It would have required
5203 a huge amount of code to implement even a decent subset of
5204 @code{format*}, yet the functionality it would provide over
5205 Emacs Lisp's @code{format} would rarely be useful.
5208 Vector constants use square brackets in Emacs Lisp, but
5209 @code{#(a b c)} notation in Common Lisp. To further complicate
5210 matters, Emacs has its own @code{#(} notation for
5211 something entirely different---strings with properties.
5214 Characters are distinct from integers in Common Lisp. The notation
5215 for character constants is also different: @code{#\A} in Common Lisp
5216 where Emacs Lisp uses @code{?A}. Also, @code{string=} and
5217 @code{string-equal} are synonyms in Emacs Lisp, whereas the latter is
5218 case-insensitive in Common Lisp.
5221 Data types. Some Common Lisp data types do not exist in Emacs
5222 Lisp. Rational numbers and complex numbers are not present,
5223 nor are large integers (all integers are ``fixnums''). All
5224 arrays are one-dimensional. There are no readtables or pathnames;
5225 streams are a set of existing data types rather than a new data
5226 type of their own. Hash tables, random-states, structures, and
5227 packages (obarrays) are built from Lisp vectors or lists rather
5228 than being distinct types.
5231 The Common Lisp Object System (CLOS) is not implemented,
5232 nor is the Common Lisp Condition System. However, the EIEIO package
5233 (@pxref{Top, , Introduction, eieio, EIEIO}) does implement some
5237 Common Lisp features that are completely redundant with Emacs
5238 Lisp features of a different name generally have not been
5239 implemented. For example, Common Lisp writes @code{defconstant}
5240 where Emacs Lisp uses @code{defconst}. Similarly, @code{make-list}
5241 takes its arguments in different ways in the two Lisps but does
5242 exactly the same thing, so this package has not bothered to
5243 implement a Common Lisp-style @code{make-list}.
5246 A few more notable Common Lisp features not included in this
5247 package: @code{compiler-let}, @code{tagbody}, @code{prog},
5248 @code{ldb/dpb}, @code{parse-integer}, @code{cerror}.
5251 Recursion. While recursion works in Emacs Lisp just like it
5252 does in Common Lisp, various details of the Emacs Lisp system
5253 and compiler make recursion much less efficient than it is in
5254 most Lisps. Some schools of thought prefer to use recursion
5255 in Lisp over other techniques; they would sum a list of
5256 numbers using something like
5259 (defun sum-list (list)
5261 (+ (car list) (sum-list (cdr list)))
5266 where a more iteratively-minded programmer might write one of
5270 (let ((total 0)) (dolist (x my-list) (incf total x)) total)
5271 (loop for x in my-list sum x)
5274 While this would be mainly a stylistic choice in most Common Lisps,
5275 in Emacs Lisp you should be aware that the iterative forms are
5276 much faster than recursion. Also, Lisp programmers will want to
5277 note that the current Emacs Lisp compiler does not optimize tail
5281 @node GNU Free Documentation License
5282 @appendix GNU Free Documentation License
5283 @include doclicense.texi
5285 @node Function Index
5286 @unnumbered Function Index
5290 @node Variable Index
5291 @unnumbered Variable Index