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}.
70 * Efficiency Concerns:: Hints and techniques.
71 * Common Lisp Compatibility:: All known differences with Steele.
72 * Porting Common Lisp:: Hints for porting Common Lisp code.
74 * GNU Free Documentation License:: The license for this documentation.
83 This document describes a set of Emacs Lisp facilities borrowed from
84 Common Lisp. All the facilities are described here in detail. While
85 this document does not assume any prior knowledge of Common Lisp, it
86 does assume a basic familiarity with Emacs Lisp.
88 Common Lisp is a huge language, and Common Lisp systems tend to be
89 massive and extremely complex. Emacs Lisp, by contrast, is rather
90 minimalist in the choice of Lisp features it offers the programmer.
91 As Emacs Lisp programmers have grown in number, and the applications
92 they write have grown more ambitious, it has become clear that Emacs
93 Lisp could benefit from many of the conveniences of Common Lisp.
95 The @code{CL} package adds a number of Common Lisp functions and
96 control structures to Emacs Lisp. While not a 100% complete
97 implementation of Common Lisp, @code{CL} adds enough functionality
98 to make Emacs Lisp programming significantly more convenient.
100 Some Common Lisp features have been omitted from this package
105 Some features are too complex or bulky relative to their benefit
106 to Emacs Lisp programmers. CLOS and Common Lisp streams are fine
107 examples of this group.
110 Other features cannot be implemented without modification to the
111 Emacs Lisp interpreter itself, such as multiple return values,
112 case-insensitive symbols, and complex numbers.
113 The @code{CL} package generally makes no attempt to emulate these
118 The package described here was originally written by Dave Gillespie,
119 @file{daveg@@synaptics.com}, as a total rewrite of an earlier
120 1986 @file{cl.el} package by Cesar Quiroz. Care has been taken
121 to ensure that each function is defined efficiently, concisely, and
122 with minimal impact on the rest of the Emacs environment. Stefan
123 Monnier added the file @file{cl-lib.el} and rationalized the namespace
127 * Usage:: How to use the CL package.
128 * Organization:: The package's five component files.
129 * Naming Conventions:: Notes on CL function names.
136 The @code{CL} package is distributed with Emacs, so there is no need
137 to install any additional files in order to start using it. Lisp code
138 that uses features from the @code{CL} package should simply include at
146 You may wish to add such a statement to your init file, if you
147 make frequent use of CL features.
150 @section Organization
153 The Common Lisp package is organized into four main files:
157 This is the main file, which contains basic functions
158 and information about the package. This file is relatively compact.
161 This file contains the larger, more complex or unusual functions.
162 It is kept separate so that packages which only want to use Common
163 Lisp fundamentals like the @code{cl-incf} function won't need to pay
164 the overhead of loading the more advanced functions.
167 This file contains most of the advanced functions for operating
168 on sequences or lists, such as @code{cl-delete-if} and @code{cl-assoc}.
171 This file contains the features that are macros instead of functions.
172 Macros expand when the caller is compiled, not when it is run, so the
173 macros generally only need to be present when the byte-compiler is
174 running (or when the macros are used in uncompiled code). Most of the
175 macros of this package are isolated in @file{cl-macs.el} so that they
176 won't take up memory unless you are compiling.
179 The file @file{cl-lib.el} includes all necessary @code{autoload}
180 commands for the functions and macros in the other three files.
181 All you have to do is @code{(require 'cl-lib)}, and @file{cl-lib.el}
182 will take care of pulling in the other files when they are
185 There is another file, @file{cl.el}, which was the main entry point
186 to the CL package prior to Emacs 24.3. Nowadays, it is replaced
187 by @file{cl-lib.el}. The two provide the same features, but use
188 different function names (in fact, @file{cl.el} just defines aliases
189 to the @file{cl-lib.el} definitions). In particular, the old @file{cl.el}
190 does not use a clean namespace. For this reason, Emacs has a policy
191 that packages distributed with Emacs must not load @code{cl} at run time.
192 (It is ok for them to load @code{cl} at @emph{compile} time, with
193 @code{eval-when-compile}, and use the macros it provides.) There is
194 no such restriction on the use of @code{cl-lib}. New code should use
195 @code{cl-lib} rather than @code{cl}. @xref{Naming Conventions}.
197 There is one more file, @file{cl-compat.el}, which defines some
198 routines from the older Quiroz CL package that are not otherwise
199 present in the new package. This file is obsolete and should not be
202 @node Naming Conventions
203 @section Naming Conventions
206 Except where noted, all functions defined by this package have the
207 same calling conventions as their Common Lisp counterparts, and
208 names that are those of Common Lisp plus a @samp{cl-} prefix.
210 Internal function and variable names in the package are prefixed
211 by @code{cl--}. Here is a complete list of functions prefixed by
212 @code{cl-} that were not taken from Common Lisp:
214 @c FIXME lexical-let lexical-let*
216 cl-callf cl-callf2 cl-defsubst
217 cl-floatp-safe cl-letf cl-letf*
220 The following simple functions and macros are defined in @file{cl-lib.el};
221 they do not cause other components like @file{cl-extra} to be loaded.
224 cl-floatp-safe cl-endp
225 cl-evenp cl-oddp cl-plusp cl-minusp
226 cl-caaar .. cl-cddddr
227 cl-list* cl-ldiff cl-rest cl-first .. cl-tenth
228 cl-copy-list cl-subst cl-mapcar [2]
229 cl-adjoin [3] cl-acons cl-pairlis
230 cl-pushnew [3,4] cl-incf [4] cl-decf [4]
231 cl-proclaim cl-declaim
235 [2] Only for one sequence argument or two list arguments.
238 [3] Only if @code{:test} is @code{eq}, @code{equal}, or unspecified,
239 and @code{:key} is not used.
242 [4] Only when @var{place} is a plain variable name.
244 @node Program Structure
245 @chapter Program Structure
248 This section describes features of the @code{CL} package that have to
249 do with programs as a whole: advanced argument lists for functions,
250 and the @code{cl-eval-when} construct.
253 * Argument Lists:: @code{&key}, @code{&aux}, @code{cl-defun}, @code{cl-defmacro}.
254 * Time of Evaluation:: The @code{cl-eval-when} construct.
262 @section Argument Lists
265 Emacs Lisp's notation for argument lists of functions is a subset of
266 the Common Lisp notation. As well as the familiar @code{&optional}
267 and @code{&rest} markers, Common Lisp allows you to specify default
268 values for optional arguments, and it provides the additional markers
269 @code{&key} and @code{&aux}.
271 Since argument parsing is built-in to Emacs, there is no way for
272 this package to implement Common Lisp argument lists seamlessly.
273 Instead, this package defines alternates for several Lisp forms
274 which you must use if you need Common Lisp argument lists.
276 @defspec cl-defun name arglist body...
277 This form is identical to the regular @code{defun} form, except
278 that @var{arglist} is allowed to be a full Common Lisp argument
279 list. Also, the function body is enclosed in an implicit block
280 called @var{name}; @pxref{Blocks and Exits}.
283 @defspec cl-defsubst name arglist body...
284 This is just like @code{cl-defun}, except that the function that
285 is defined is automatically proclaimed @code{inline}, i.e.,
286 calls to it may be expanded into in-line code by the byte compiler.
287 This is analogous to the @code{defsubst} form;
288 @code{cl-defsubst} uses a different method (compiler macros) which
289 works in all versions of Emacs, and also generates somewhat more
290 efficient inline expansions. In particular, @code{cl-defsubst}
291 arranges for the processing of keyword arguments, default values,
292 etc., to be done at compile-time whenever possible.
295 @defspec cl-defmacro name arglist body...
296 This is identical to the regular @code{defmacro} form,
297 except that @var{arglist} is allowed to be a full Common Lisp
298 argument list. The @code{&environment} keyword is supported as
299 described in Steele. The @code{&whole} keyword is supported only
300 within destructured lists (see below); top-level @code{&whole}
301 cannot be implemented with the current Emacs Lisp interpreter.
302 The macro expander body is enclosed in an implicit block called
306 @defspec cl-function symbol-or-lambda
307 This is identical to the regular @code{function} form,
308 except that if the argument is a @code{lambda} form then that
309 form may use a full Common Lisp argument list.
312 Also, all forms (such as @code{cl-flet} and @code{cl-labels}) defined
313 in this package that include @var{arglist}s in their syntax allow
314 full Common Lisp argument lists.
316 Note that it is @emph{not} necessary to use @code{cl-defun} in
317 order to have access to most @code{CL} features in your function.
318 These features are always present; @code{cl-defun}'s only
319 difference from @code{defun} is its more flexible argument
320 lists and its implicit block.
322 The full form of a Common Lisp argument list is
326 &optional (@var{var} @var{initform} @var{svar})...
328 &key ((@var{keyword} @var{var}) @var{initform} @var{svar})...
329 &aux (@var{var} @var{initform})...)
332 Each of the five argument list sections is optional. The @var{svar},
333 @var{initform}, and @var{keyword} parts are optional; if they are
334 omitted, then @samp{(@var{var})} may be written simply @samp{@var{var}}.
336 The first section consists of zero or more @dfn{required} arguments.
337 These arguments must always be specified in a call to the function;
338 there is no difference between Emacs Lisp and Common Lisp as far as
339 required arguments are concerned.
341 The second section consists of @dfn{optional} arguments. These
342 arguments may be specified in the function call; if they are not,
343 @var{initform} specifies the default value used for the argument.
344 (No @var{initform} means to use @code{nil} as the default.) The
345 @var{initform} is evaluated with the bindings for the preceding
346 arguments already established; @code{(a &optional (b (1+ a)))}
347 matches one or two arguments, with the second argument defaulting
348 to one plus the first argument. If the @var{svar} is specified,
349 it is an auxiliary variable which is bound to @code{t} if the optional
350 argument was specified, or to @code{nil} if the argument was omitted.
351 If you don't use an @var{svar}, then there will be no way for your
352 function to tell whether it was called with no argument, or with
353 the default value passed explicitly as an argument.
355 The third section consists of a single @dfn{rest} argument. If
356 more arguments were passed to the function than are accounted for
357 by the required and optional arguments, those extra arguments are
358 collected into a list and bound to the ``rest'' argument variable.
359 Common Lisp's @code{&rest} is equivalent to that of Emacs Lisp.
360 Common Lisp accepts @code{&body} as a synonym for @code{&rest} in
361 macro contexts; this package accepts it all the time.
363 The fourth section consists of @dfn{keyword} arguments. These
364 are optional arguments which are specified by name rather than
365 positionally in the argument list. For example,
368 (cl-defun foo (a &optional b &key c d (e 17)))
372 defines a function which may be called with one, two, or more
373 arguments. The first two arguments are bound to @code{a} and
374 @code{b} in the usual way. The remaining arguments must be
375 pairs of the form @code{:c}, @code{:d}, or @code{:e} followed
376 by the value to be bound to the corresponding argument variable.
377 (Symbols whose names begin with a colon are called @dfn{keywords},
378 and they are self-quoting in the same way as @code{nil} and
381 For example, the call @code{(foo 1 2 :d 3 :c 4)} sets the five
382 arguments to 1, 2, 4, 3, and 17, respectively. If the same keyword
383 appears more than once in the function call, the first occurrence
384 takes precedence over the later ones. Note that it is not possible
385 to specify keyword arguments without specifying the optional
386 argument @code{b} as well, since @code{(foo 1 :c 2)} would bind
387 @code{b} to the keyword @code{:c}, then signal an error because
388 @code{2} is not a valid keyword.
390 You can also explicitly specify the keyword argument; it need not be
391 simply the variable name prefixed with a colon. For example,
394 (cl-defun bar (&key (a 1) ((baz b) 4)))
399 specifies a keyword @code{:a} that sets the variable @code{a} with
400 default value 1, as well as a keyword @code{baz} that sets the
401 variable @code{b} with default value 4. In this case, because
402 @code{baz} is not self-quoting, you must quote it explicitly in the
403 function call, like this:
409 Ordinarily, it is an error to pass an unrecognized keyword to
410 a function, e.g., @code{(foo 1 2 :c 3 :goober 4)}. You can ask
411 Lisp to ignore unrecognized keywords, either by adding the
412 marker @code{&allow-other-keys} after the keyword section
413 of the argument list, or by specifying an @code{:allow-other-keys}
414 argument in the call whose value is non-@code{nil}. If the
415 function uses both @code{&rest} and @code{&key} at the same time,
416 the ``rest'' argument is bound to the keyword list as it appears
417 in the call. For example:
420 (cl-defun find-thing (thing &rest rest &key need &allow-other-keys)
421 (or (apply 'cl-member thing thing-list :allow-other-keys t rest)
422 (if need (error "Thing not found"))))
426 This function takes a @code{:need} keyword argument, but also
427 accepts other keyword arguments which are passed on to the
428 @code{cl-member} function. @code{allow-other-keys} is used to
429 keep both @code{find-thing} and @code{cl-member} from complaining
430 about each others' keywords in the arguments.
432 The fifth section of the argument list consists of @dfn{auxiliary
433 variables}. These are not really arguments at all, but simply
434 variables which are bound to @code{nil} or to the specified
435 @var{initforms} during execution of the function. There is no
436 difference between the following two functions, except for a
437 matter of stylistic taste:
440 (cl-defun foo (a b &aux (c (+ a b)) d)
448 Argument lists support @dfn{destructuring}. In Common Lisp,
449 destructuring is only allowed with @code{defmacro}; this package
450 allows it with @code{cl-defun} and other argument lists as well.
451 In destructuring, any argument variable (@var{var} in the above
452 diagram) can be replaced by a list of variables, or more generally,
453 a recursive argument list. The corresponding argument value must
454 be a list whose elements match this recursive argument list.
458 (cl-defmacro dolist ((var listform &optional resultform)
463 This says that the first argument of @code{dolist} must be a list
464 of two or three items; if there are other arguments as well as this
465 list, they are stored in @code{body}. All features allowed in
466 regular argument lists are allowed in these recursive argument lists.
467 In addition, the clause @samp{&whole @var{var}} is allowed at the
468 front of a recursive argument list. It binds @var{var} to the
469 whole list being matched; thus @code{(&whole all a b)} matches
470 a list of two things, with @code{a} bound to the first thing,
471 @code{b} bound to the second thing, and @code{all} bound to the
472 list itself. (Common Lisp allows @code{&whole} in top-level
473 @code{defmacro} argument lists as well, but Emacs Lisp does not
476 One last feature of destructuring is that the argument list may be
477 dotted, so that the argument list @code{(a b . c)} is functionally
478 equivalent to @code{(a b &rest c)}.
480 If the optimization quality @code{safety} is set to 0
481 (@pxref{Declarations}), error checking for wrong number of
482 arguments and invalid keyword arguments is disabled. By default,
483 argument lists are rigorously checked.
485 @node Time of Evaluation
486 @section Time of Evaluation
489 Normally, the byte-compiler does not actually execute the forms in
490 a file it compiles. For example, if a file contains @code{(setq foo t)},
491 the act of compiling it will not actually set @code{foo} to @code{t}.
492 This is true even if the @code{setq} was a top-level form (i.e., not
493 enclosed in a @code{defun} or other form). Sometimes, though, you
494 would like to have certain top-level forms evaluated at compile-time.
495 For example, the compiler effectively evaluates @code{defmacro} forms
496 at compile-time so that later parts of the file can refer to the
497 macros that are defined.
499 @defspec cl-eval-when (situations...) forms...
500 This form controls when the body @var{forms} are evaluated.
501 The @var{situations} list may contain any set of the symbols
502 @code{compile}, @code{load}, and @code{eval} (or their long-winded
503 ANSI equivalents, @code{:compile-toplevel}, @code{:load-toplevel},
504 and @code{:execute}).
506 The @code{cl-eval-when} form is handled differently depending on
507 whether or not it is being compiled as a top-level form.
508 Specifically, it gets special treatment if it is being compiled
509 by a command such as @code{byte-compile-file} which compiles files
510 or buffers of code, and it appears either literally at the
511 top level of the file or inside a top-level @code{progn}.
513 For compiled top-level @code{cl-eval-when}s, the body @var{forms} are
514 executed at compile-time if @code{compile} is in the @var{situations}
515 list, and the @var{forms} are written out to the file (to be executed
516 at load-time) if @code{load} is in the @var{situations} list.
518 For non-compiled-top-level forms, only the @code{eval} situation is
519 relevant. (This includes forms executed by the interpreter, forms
520 compiled with @code{byte-compile} rather than @code{byte-compile-file},
521 and non-top-level forms.) The @code{cl-eval-when} acts like a
522 @code{progn} if @code{eval} is specified, and like @code{nil}
523 (ignoring the body @var{forms}) if not.
525 The rules become more subtle when @code{cl-eval-when}s are nested;
526 consult Steele (second edition) for the gruesome details (and
527 some gruesome examples).
529 Some simple examples:
532 ;; Top-level forms in foo.el:
533 (cl-eval-when (compile) (setq foo1 'bar))
534 (cl-eval-when (load) (setq foo2 'bar))
535 (cl-eval-when (compile load) (setq foo3 'bar))
536 (cl-eval-when (eval) (setq foo4 'bar))
537 (cl-eval-when (eval compile) (setq foo5 'bar))
538 (cl-eval-when (eval load) (setq foo6 'bar))
539 (cl-eval-when (eval compile load) (setq foo7 'bar))
542 When @file{foo.el} is compiled, these variables will be set during
543 the compilation itself:
546 foo1 foo3 foo5 foo7 ; `compile'
549 When @file{foo.elc} is loaded, these variables will be set:
552 foo2 foo3 foo6 foo7 ; `load'
555 And if @file{foo.el} is loaded uncompiled, these variables will
559 foo4 foo5 foo6 foo7 ; `eval'
562 If these seven @code{cl-eval-when}s had been, say, inside a @code{defun},
563 then the first three would have been equivalent to @code{nil} and the
564 last four would have been equivalent to the corresponding @code{setq}s.
566 Note that @code{(cl-eval-when (load eval) @dots{})} is equivalent
567 to @code{(progn @dots{})} in all contexts. The compiler treats
568 certain top-level forms, like @code{defmacro} (sort-of) and
569 @code{require}, as if they were wrapped in @code{(eval-when
570 (compile load eval) @dots{})}.
573 Emacs includes two special forms related to @code{cl-eval-when}.
574 One of these, @code{eval-when-compile}, is not quite equivalent to
575 any @code{eval-when} construct and is described below.
577 The other form, @code{(eval-and-compile @dots{})}, is exactly
578 equivalent to @samp{(eval-when (compile load eval) @dots{})} and
579 so is not itself defined by this package.
581 @defspec eval-when-compile forms...
582 The @var{forms} are evaluated at compile-time; at execution time,
583 this form acts like a quoted constant of the resulting value. Used
584 at top-level, @code{eval-when-compile} is just like @samp{eval-when
585 (compile eval)}. In other contexts, @code{eval-when-compile}
586 allows code to be evaluated once at compile-time for efficiency
589 This form is similar to the @samp{#.} syntax of true Common Lisp.
592 @defspec cl-load-time-value form
593 The @var{form} is evaluated at load-time; at execution time,
594 this form acts like a quoted constant of the resulting value.
596 Early Common Lisp had a @samp{#,} syntax that was similar to
597 this, but ANSI Common Lisp replaced it with @code{load-time-value}
598 and gave it more well-defined semantics.
600 In a compiled file, @code{cl-load-time-value} arranges for @var{form}
601 to be evaluated when the @file{.elc} file is loaded and then used
602 as if it were a quoted constant. In code compiled by
603 @code{byte-compile} rather than @code{byte-compile-file}, the
604 effect is identical to @code{eval-when-compile}. In uncompiled
605 code, both @code{eval-when-compile} and @code{cl-load-time-value}
606 act exactly like @code{progn}.
610 (insert "This function was executed on: "
611 (current-time-string)
613 (eval-when-compile (current-time-string))
614 ;; or '#.(current-time-string) in real Common Lisp
616 (cl-load-time-value (current-time-string))))
620 Byte-compiled, the above defun will result in the following code
621 (or its compiled equivalent, of course) in the @file{.elc} file:
624 (setq --temp-- (current-time-string))
626 (insert "This function was executed on: "
627 (current-time-string)
629 '"Wed Jun 23 18:33:43 1993"
639 This section describes functions for testing whether various
640 facts are true or false.
643 * Type Predicates:: @code{cl-typep}, @code{cl-deftype}, and @code{cl-coerce}.
644 * Equality Predicates:: @code{cl-equalp}.
647 @node Type Predicates
648 @section Type Predicates
651 The @code{CL} package defines a version of the Common Lisp @code{typep}
654 @defun cl-typep object type
655 Check if @var{object} is of type @var{type}, where @var{type} is a
656 (quoted) type name of the sort used by Common Lisp. For example,
657 @code{(cl-typep foo 'integer)} is equivalent to @code{(integerp foo)}.
660 The @var{type} argument to the above function is either a symbol
661 or a list beginning with a symbol.
665 If the type name is a symbol, Emacs appends @samp{-p} to the
666 symbol name to form the name of a predicate function for testing
667 the type. (Built-in predicates whose names end in @samp{p} rather
668 than @samp{-p} are used when appropriate.)
671 The type symbol @code{t} stands for the union of all types.
672 @code{(cl-typep @var{object} t)} is always true. Likewise, the
673 type symbol @code{nil} stands for nothing at all, and
674 @code{(cl-typep @var{object} nil)} is always false.
677 The type symbol @code{null} represents the symbol @code{nil}.
678 Thus @code{(cl-typep @var{object} 'null)} is equivalent to
679 @code{(null @var{object})}.
682 The type symbol @code{atom} represents all objects that are not cons
683 cells. Thus @code{(cl-typep @var{object} 'atom)} is equivalent to
684 @code{(atom @var{object})}.
687 The type symbol @code{real} is a synonym for @code{number}, and
688 @code{fixnum} is a synonym for @code{integer}.
691 The type symbols @code{character} and @code{string-char} match
692 integers in the range from 0 to 255.
695 The type symbol @code{float} uses the @code{cl-floatp-safe} predicate
696 defined by this package rather than @code{floatp}, so it will work
697 correctly even in Emacs versions without floating-point support.
700 The type list @code{(integer @var{low} @var{high})} represents all
701 integers between @var{low} and @var{high}, inclusive. Either bound
702 may be a list of a single integer to specify an exclusive limit,
703 or a @code{*} to specify no limit. The type @code{(integer * *)}
704 is thus equivalent to @code{integer}.
707 Likewise, lists beginning with @code{float}, @code{real}, or
708 @code{number} represent numbers of that type falling in a particular
712 Lists beginning with @code{and}, @code{or}, and @code{not} form
713 combinations of types. For example, @code{(or integer (float 0 *))}
714 represents all objects that are integers or non-negative floats.
717 Lists beginning with @code{member} or @code{cl-member} represent
718 objects @code{eql} to any of the following values. For example,
719 @code{(member 1 2 3 4)} is equivalent to @code{(integer 1 4)},
720 and @code{(member nil)} is equivalent to @code{null}.
723 Lists of the form @code{(satisfies @var{predicate})} represent
724 all objects for which @var{predicate} returns true when called
725 with that object as an argument.
728 The following function and macro (not technically predicates) are
729 related to @code{cl-typep}.
731 @defun cl-coerce object type
732 This function attempts to convert @var{object} to the specified
733 @var{type}. If @var{object} is already of that type as determined by
734 @code{typep}, it is simply returned. Otherwise, certain types of
735 conversions will be made: If @var{type} is any sequence type
736 (@code{string}, @code{list}, etc.) then @var{object} will be
737 converted to that type if possible. If @var{type} is
738 @code{character}, then strings of length one and symbols with
739 one-character names can be coerced. If @var{type} is @code{float},
740 then integers can be coerced in versions of Emacs that support
741 floats. In all other circumstances, @code{cl-coerce} signals an
745 @defspec cl-deftype name arglist forms...
746 This macro defines a new type called @var{name}. It is similar
747 to @code{defmacro} in many ways; when @var{name} is encountered
748 as a type name, the body @var{forms} are evaluated and should
749 return a type specifier that is equivalent to the type. The
750 @var{arglist} is a Common Lisp argument list of the sort accepted
751 by @code{cl-defmacro}. The type specifier @samp{(@var{name} @var{args}...)}
752 is expanded by calling the expander with those arguments; the type
753 symbol @samp{@var{name}} is expanded by calling the expander with
754 no arguments. The @var{arglist} is processed the same as for
755 @code{cl-defmacro} except that optional arguments without explicit
756 defaults use @code{*} instead of @code{nil} as the ``default''
757 default. Some examples:
760 (cl-deftype null () '(satisfies null)) ; predefined
761 (cl-deftype list () '(or null cons)) ; predefined
762 (cl-deftype unsigned-byte (&optional bits)
763 (list 'integer 0 (if (eq bits '*) bits (1- (lsh 1 bits)))))
764 (unsigned-byte 8) @equiv{} (integer 0 255)
765 (unsigned-byte) @equiv{} (integer 0 *)
766 unsigned-byte @equiv{} (integer 0 *)
770 The last example shows how the Common Lisp @code{unsigned-byte}
771 type specifier could be implemented if desired; this package does
772 not implement @code{unsigned-byte} by default.
775 The @code{cl-typecase} and @code{cl-check-type} macros also use type
776 names. @xref{Conditionals}. @xref{Assertions}. The @code{cl-map},
777 @code{cl-concatenate}, and @code{cl-merge} functions take type-name
778 arguments to specify the type of sequence to return. @xref{Sequences}.
780 @node Equality Predicates
781 @section Equality Predicates
784 This package defines the Common Lisp predicate @code{cl-equalp}.
787 This function is a more flexible version of @code{equal}. In
788 particular, it compares strings case-insensitively, and it compares
789 numbers without regard to type (so that @code{(cl-equalp 3 3.0)} is
790 true). Vectors and conses are compared recursively. All other
791 objects are compared as if by @code{equal}.
793 This function differs from Common Lisp @code{equalp} in several
794 respects. First, Common Lisp's @code{equalp} also compares
795 @emph{characters} case-insensitively, which would be impractical
796 in this package since Emacs does not distinguish between integers
797 and characters. In keeping with the idea that strings are less
798 vector-like in Emacs Lisp, this package's @code{cl-equalp} also will
799 not compare strings against vectors of integers.
802 Also note that the Common Lisp functions @code{member} and @code{assoc}
803 use @code{eql} to compare elements, whereas Emacs Lisp follows the
804 MacLisp tradition and uses @code{equal} for these two functions.
805 In Emacs, use @code{memq} (or @code{cl-member}) and @code{assq} (or
806 @code{cl-assoc}) to get functions which use @code{eql} for comparisons.
808 @node Control Structure
809 @chapter Control Structure
812 The features described in the following sections implement
813 various advanced control structures, including the powerful
814 @c FIXME setf is now in gv.el, not cl.
815 @code{setf} facility and a number of looping and conditional
818 @c FIXME setf, push are standard now.
819 @c lexical-let is obsolete; flet is not cl-flet.
820 @c values is not cl-values.
822 * Assignment:: The @code{cl-psetq} form.
823 * Generalized Variables:: @code{setf}, @code{cl-incf}, @code{push}, etc.
824 * Variable Bindings:: @code{cl-progv}, @code{lexical-let}, @code{flet}, @code{cl-macrolet}.
825 * Conditionals:: @code{cl-case}, @code{cl-typecase}.
826 * Blocks and Exits:: @code{cl-block}, @code{cl-return}, @code{cl-return-from}.
827 * Iteration:: @code{cl-do}, @code{cl-dotimes}, @code{cl-dolist}, @code{cl-do-symbols}.
828 * Loop Facility:: The Common Lisp @code{cl-loop} macro.
829 * Multiple Values:: @code{values}, @code{cl-multiple-value-bind}, etc.
836 The @code{cl-psetq} form is just like @code{setq}, except that multiple
837 assignments are done in parallel rather than sequentially.
839 @defspec cl-psetq [symbol form]@dots{}
840 This special form (actually a macro) is used to assign to several
841 variables simultaneously. Given only one @var{symbol} and @var{form},
842 it has the same effect as @code{setq}. Given several @var{symbol}
843 and @var{form} pairs, it evaluates all the @var{form}s in advance
844 and then stores the corresponding variables afterwards.
848 (setq x (+ x y) y (* x y))
851 y ; @r{@code{y} was computed after @code{x} was set.}
854 (cl-psetq x (+ x y) y (* x y))
857 y ; @r{@code{y} was computed before @code{x} was set.}
861 The simplest use of @code{cl-psetq} is @code{(cl-psetq x y y x)}, which
862 exchanges the values of two variables. (The @code{cl-rotatef} form
863 provides an even more convenient way to swap two variables;
864 @pxref{Modify Macros}.)
866 @code{cl-psetq} always returns @code{nil}.
869 @c FIXME now in gv.el.
870 @node Generalized Variables
871 @section Generalized Variables
874 A ``generalized variable'' or ``place form'' is one of the many places
875 in Lisp memory where values can be stored. The simplest place form is
876 a regular Lisp variable. But the cars and cdrs of lists, elements
877 of arrays, properties of symbols, and many other locations are also
878 places where Lisp values are stored.
880 The @code{setf} form is like @code{setq}, except that it accepts
881 arbitrary place forms on the left side rather than just
882 symbols. For example, @code{(setf (car a) b)} sets the car of
883 @code{a} to @code{b}, doing the same operation as @code{(setcar a b)}
884 but without having to remember two separate functions for setting
885 and accessing every type of place.
887 Generalized variables are analogous to ``lvalues'' in the C
888 language, where @samp{x = a[i]} gets an element from an array
889 and @samp{a[i] = x} stores an element using the same notation.
890 Just as certain forms like @code{a[i]} can be lvalues in C, there
891 is a set of forms that can be generalized variables in Lisp.
894 * Basic Setf:: @code{setf} and place forms.
895 * Modify Macros:: @code{cl-incf}, @code{push}, @code{cl-rotatef}, @code{letf}, @code{cl-callf}, etc.
896 * Customizing Setf:: @code{define-modify-macro}, @code{defsetf}, @code{define-setf-method}.
900 @subsection Basic Setf
903 The @code{setf} macro is the most basic way to operate on generalized
906 @defspec setf [place form]@dots{}
907 This macro evaluates @var{form} and stores it in @var{place}, which
908 must be a valid generalized variable form. If there are several
909 @var{place} and @var{form} pairs, the assignments are done sequentially
910 just as with @code{setq}. @code{setf} returns the value of the last
913 The following Lisp forms will work as generalized variables, and
914 so may appear in the @var{place} argument of @code{setf}:
918 A symbol naming a variable. In other words, @code{(setf x y)} is
919 exactly equivalent to @code{(setq x y)}, and @code{setq} itself is
920 strictly speaking redundant now that @code{setf} exists. Many
921 programmers continue to prefer @code{setq} for setting simple
922 variables, though, purely for stylistic or historical reasons.
923 The macro @code{(setf x y)} actually expands to @code{(setq x y)},
924 so there is no performance penalty for using it in compiled code.
927 A call to any of the following Lisp functions:
930 car cdr caar .. cddddr
931 nth rest first .. tenth
933 symbol-function symbol-value symbol-plist
939 Note that for @code{nthcdr} and @code{getf}, the list argument
940 of the function must itself be a valid @var{place} form. For
941 example, @code{(setf (nthcdr 0 foo) 7)} will set @code{foo} itself
942 to 7. Note that @code{push} and @code{pop} on an @code{nthcdr}
943 place can be used to insert or delete at any position in a list.
944 The use of @code{nthcdr} as a @var{place} form is an extension
945 to standard Common Lisp.
948 The following Emacs-specific functions are also @code{setf}-able.
951 buffer-file-name marker-position
952 buffer-modified-p match-data
953 buffer-name mouse-position
954 buffer-string overlay-end
955 buffer-substring overlay-get
956 current-buffer overlay-start
957 current-case-table point
958 current-column point-marker
959 current-global-map point-max
960 current-input-mode point-min
961 current-local-map process-buffer
962 current-window-configuration process-filter
963 default-file-modes process-sentinel
964 default-value read-mouse-position
965 documentation-property screen-height
966 extent-data screen-menubar
967 extent-end-position screen-width
968 extent-start-position selected-window
969 face-background selected-screen
970 face-background-pixmap selected-frame
971 face-font standard-case-table
972 face-foreground syntax-table
973 face-underline-p window-buffer
974 file-modes window-dedicated-p
975 frame-height window-display-table
976 frame-parameters window-height
977 frame-visible-p window-hscroll
978 frame-width window-point
979 get-register window-start
981 global-key-binding x-get-secondary-selection
982 keymap-parent x-get-selection
988 Most of these have directly corresponding ``set'' functions, like
989 @code{use-local-map} for @code{current-local-map}, or @code{goto-char}
990 for @code{point}. A few, like @code{point-min}, expand to longer
991 sequences of code when they are @code{setf}'d (@code{(narrow-to-region
992 x (point-max))} in this case).
995 A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])},
996 where @var{subplace} is itself a valid generalized variable whose
997 current value is a string, and where the value stored is also a
998 string. The new string is spliced into the specified part of the
999 destination string. For example:
1002 (setq a (list "hello" "world"))
1003 @result{} ("hello" "world")
1006 (substring (cadr a) 2 4)
1008 (setf (substring (cadr a) 2 4) "o")
1013 @result{} ("hello" "wood")
1016 The generalized variable @code{buffer-substring}, listed above,
1017 also works in this way by replacing a portion of the current buffer.
1020 A call of the form @code{(apply '@var{func} @dots{})} or
1021 @code{(apply (function @var{func}) @dots{})}, where @var{func}
1022 is a @code{setf}-able function whose store function is ``suitable''
1023 in the sense described in Steele's book; since none of the standard
1024 Emacs place functions are suitable in this sense, this feature is
1025 only interesting when used with places you define yourself with
1026 @code{define-setf-method} or the long form of @code{defsetf}.
1029 A macro call, in which case the macro is expanded and @code{setf}
1030 is applied to the resulting form.
1033 Any form for which a @code{defsetf} or @code{define-setf-method}
1037 Using any forms other than these in the @var{place} argument to
1038 @code{setf} will signal an error.
1040 The @code{setf} macro takes care to evaluate all subforms in
1041 the proper left-to-right order; for example,
1044 (setf (aref vec (cl-incf i)) i)
1048 looks like it will evaluate @code{(cl-incf i)} exactly once, before the
1049 following access to @code{i}; the @code{setf} expander will insert
1050 temporary variables as necessary to ensure that it does in fact work
1051 this way no matter what setf-method is defined for @code{aref}.
1052 (In this case, @code{aset} would be used and no such steps would
1053 be necessary since @code{aset} takes its arguments in a convenient
1056 However, if the @var{place} form is a macro which explicitly
1057 evaluates its arguments in an unusual order, this unusual order
1058 will be preserved. Adapting an example from Steele, given
1061 (defmacro wrong-order (x y) (list 'aref y x))
1065 the form @code{(setf (wrong-order @var{a} @var{b}) 17)} will
1066 evaluate @var{b} first, then @var{a}, just as in an actual call
1067 to @code{wrong-order}.
1071 @subsection Modify Macros
1074 This package defines a number of other macros besides @code{setf}
1075 that operate on generalized variables. Many are interesting and
1076 useful even when the @var{place} is just a variable name.
1078 @defspec cl-psetf [place form]@dots{}
1079 This macro is to @code{setf} what @code{cl-psetq} is to @code{setq}:
1080 When several @var{place}s and @var{form}s are involved, the
1081 assignments take place in parallel rather than sequentially.
1082 Specifically, all subforms are evaluated from left to right, then
1083 all the assignments are done (in an undefined order).
1086 @defspec cl-incf place &optional x
1087 This macro increments the number stored in @var{place} by one, or
1088 by @var{x} if specified. The incremented value is returned. For
1089 example, @code{(cl-incf i)} is equivalent to @code{(setq i (1+ i))}, and
1090 @code{(cl-incf (car x) 2)} is equivalent to @code{(setcar x (+ (car x) 2))}.
1092 Once again, care is taken to preserve the ``apparent'' order of
1093 evaluation. For example,
1096 (cl-incf (aref vec (cl-incf i)))
1100 appears to increment @code{i} once, then increment the element of
1101 @code{vec} addressed by @code{i}; this is indeed exactly what it
1102 does, which means the above form is @emph{not} equivalent to the
1103 ``obvious'' expansion,
1106 (setf (aref vec (cl-incf i)) (1+ (aref vec (cl-incf i)))) ; Wrong!
1110 but rather to something more like
1113 (let ((temp (cl-incf i)))
1114 (setf (aref vec temp) (1+ (aref vec temp))))
1118 Again, all of this is taken care of automatically by @code{cl-incf} and
1119 the other generalized-variable macros.
1121 As a more Emacs-specific example of @code{cl-incf}, the expression
1122 @code{(cl-incf (point) @var{n})} is essentially equivalent to
1123 @code{(forward-char @var{n})}.
1126 @defspec cl-decf place &optional x
1127 This macro decrements the number stored in @var{place} by one, or
1128 by @var{x} if specified.
1132 This macro removes and returns the first element of the list stored
1133 in @var{place}. It is analogous to @code{(prog1 (car @var{place})
1134 (setf @var{place} (cdr @var{place})))}, except that it takes care
1135 to evaluate all subforms only once.
1138 @defspec push x place
1139 This macro inserts @var{x} at the front of the list stored in
1140 @var{place}. It is analogous to @code{(setf @var{place} (cons
1141 @var{x} @var{place}))}, except for evaluation of the subforms.
1144 @defspec pushnew x place @t{&key :test :test-not :key}
1145 This macro inserts @var{x} at the front of the list stored in
1146 @var{place}, but only if @var{x} was not @code{eql} to any
1147 existing element of the list. The optional keyword arguments
1148 are interpreted in the same way as for @code{adjoin}.
1149 @xref{Lists as Sets}.
1152 @defspec shiftf place@dots{} newvalue
1153 This macro shifts the @var{place}s left by one, shifting in the
1154 value of @var{newvalue} (which may be any Lisp expression, not just
1155 a generalized variable), and returning the value shifted out of
1156 the first @var{place}. Thus, @code{(shiftf @var{a} @var{b} @var{c}
1157 @var{d})} is equivalent to
1162 (psetf @var{a} @var{b}
1168 except that the subforms of @var{a}, @var{b}, and @var{c} are actually
1169 evaluated only once each and in the apparent order.
1172 @defspec rotatef place@dots{}
1173 This macro rotates the @var{place}s left by one in circular fashion.
1174 Thus, @code{(rotatef @var{a} @var{b} @var{c} @var{d})} is equivalent to
1177 (psetf @var{a} @var{b}
1184 except for the evaluation of subforms. @code{rotatef} always
1185 returns @code{nil}. Note that @code{(rotatef @var{a} @var{b})}
1186 conveniently exchanges @var{a} and @var{b}.
1189 The following macros were invented for this package; they have no
1190 analogues in Common Lisp.
1192 @defspec letf (bindings@dots{}) forms@dots{}
1193 This macro is analogous to @code{let}, but for generalized variables
1194 rather than just symbols. Each @var{binding} should be of the form
1195 @code{(@var{place} @var{value})}; the original contents of the
1196 @var{place}s are saved, the @var{value}s are stored in them, and
1197 then the body @var{form}s are executed. Afterwards, the @var{places}
1198 are set back to their original saved contents. This cleanup happens
1199 even if the @var{form}s exit irregularly due to a @code{throw} or an
1205 (letf (((point) (point-min))
1211 moves ``point'' in the current buffer to the beginning of the buffer,
1212 and also binds @code{a} to 17 (as if by a normal @code{let}, since
1213 @code{a} is just a regular variable). After the body exits, @code{a}
1214 is set back to its original value and point is moved back to its
1217 Note that @code{letf} on @code{(point)} is not quite like a
1218 @code{save-excursion}, as the latter effectively saves a marker
1219 which tracks insertions and deletions in the buffer. Actually,
1220 a @code{letf} of @code{(point-marker)} is much closer to this
1221 behavior. (@code{point} and @code{point-marker} are equivalent
1222 as @code{setf} places; each will accept either an integer or a
1223 marker as the stored value.)
1225 Since generalized variables look like lists, @code{let}'s shorthand
1226 of using @samp{foo} for @samp{(foo nil)} as a @var{binding} would
1227 be ambiguous in @code{letf} and is not allowed.
1229 However, a @var{binding} specifier may be a one-element list
1230 @samp{(@var{place})}, which is similar to @samp{(@var{place}
1231 @var{place})}. In other words, the @var{place} is not disturbed
1232 on entry to the body, and the only effect of the @code{letf} is
1233 to restore the original value of @var{place} afterwards. (The
1234 redundant access-and-store suggested by the @code{(@var{place}
1235 @var{place})} example does not actually occur.)
1237 In most cases, the @var{place} must have a well-defined value on
1238 entry to the @code{letf} form. The only exceptions are plain
1239 variables and calls to @code{symbol-value} and @code{symbol-function}.
1240 If the symbol is not bound on entry, it is simply made unbound by
1241 @code{makunbound} or @code{fmakunbound} on exit.
1244 @defspec letf* (bindings@dots{}) forms@dots{}
1245 This macro is to @code{letf} what @code{let*} is to @code{let}:
1246 It does the bindings in sequential rather than parallel order.
1249 @defspec callf @var{function} @var{place} @var{args}@dots{}
1250 This is the ``generic'' modify macro. It calls @var{function},
1251 which should be an unquoted function name, macro name, or lambda.
1252 It passes @var{place} and @var{args} as arguments, and assigns the
1253 result back to @var{place}. For example, @code{(cl-incf @var{place}
1254 @var{n})} is the same as @code{(callf + @var{place} @var{n})}.
1258 (callf abs my-number)
1259 (callf concat (buffer-name) "<" (int-to-string n) ">")
1260 (callf union happy-people (list joe bob) :test 'same-person)
1263 @xref{Customizing Setf}, for @code{define-modify-macro}, a way
1264 to create even more concise notations for modify macros. Note
1265 again that @code{callf} is an extension to standard Common Lisp.
1268 @defspec callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{}
1269 This macro is like @code{callf}, except that @var{place} is
1270 the @emph{second} argument of @var{function} rather than the
1271 first. For example, @code{(push @var{x} @var{place})} is
1272 equivalent to @code{(callf2 cons @var{x} @var{place})}.
1275 The @code{callf} and @code{callf2} macros serve as building
1276 blocks for other macros like @code{cl-incf}, @code{pushnew}, and
1277 @code{define-modify-macro}. The @code{letf} and @code{letf*}
1278 macros are used in the processing of symbol macros;
1279 @pxref{Macro Bindings}.
1281 @node Customizing Setf
1282 @subsection Customizing Setf
1285 Common Lisp defines three macros, @code{define-modify-macro},
1286 @code{defsetf}, and @code{define-setf-method}, that allow the
1287 user to extend generalized variables in various ways.
1289 @defspec define-modify-macro name arglist function [doc-string]
1290 This macro defines a ``read-modify-write'' macro similar to
1291 @code{cl-incf} and @code{cl-decf}. The macro @var{name} is defined
1292 to take a @var{place} argument followed by additional arguments
1293 described by @var{arglist}. The call
1296 (@var{name} @var{place} @var{args}...)
1303 (cl-callf @var{func} @var{place} @var{args}...)
1307 which in turn is roughly equivalent to
1310 (setf @var{place} (@var{func} @var{place} @var{args}...))
1316 (define-modify-macro cl-incf (&optional (n 1)) +)
1317 (define-modify-macro cl-concatf (&rest args) concat)
1320 Note that @code{&key} is not allowed in @var{arglist}, but
1321 @code{&rest} is sufficient to pass keywords on to the function.
1323 Most of the modify macros defined by Common Lisp do not exactly
1324 follow the pattern of @code{define-modify-macro}. For example,
1325 @code{push} takes its arguments in the wrong order, and @code{pop}
1326 is completely irregular. You can define these macros ``by hand''
1327 using @code{get-setf-method}, or consult the source file
1328 @file{cl-macs.el} to see how to use the internal @code{setf}
1332 @defspec defsetf access-fn update-fn
1333 This is the simpler of two @code{defsetf} forms. Where
1334 @var{access-fn} is the name of a function which accesses a place,
1335 this declares @var{update-fn} to be the corresponding store
1336 function. From now on,
1339 (setf (@var{access-fn} @var{arg1} @var{arg2} @var{arg3}) @var{value})
1346 (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} @var{value})
1350 The @var{update-fn} is required to be either a true function, or
1351 a macro which evaluates its arguments in a function-like way. Also,
1352 the @var{update-fn} is expected to return @var{value} as its result.
1353 Otherwise, the above expansion would not obey the rules for the way
1354 @code{setf} is supposed to behave.
1356 As a special (non-Common-Lisp) extension, a third argument of @code{t}
1357 to @code{defsetf} says that the @code{update-fn}'s return value is
1358 not suitable, so that the above @code{setf} should be expanded to
1362 (let ((temp @var{value}))
1363 (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} temp)
1367 Some examples of the use of @code{defsetf}, drawn from the standard
1368 suite of setf methods, are:
1371 (defsetf car setcar)
1372 (defsetf symbol-value set)
1373 (defsetf buffer-name rename-buffer t)
1377 @defspec defsetf access-fn arglist (store-var) forms@dots{}
1378 This is the second, more complex, form of @code{defsetf}. It is
1379 rather like @code{defmacro} except for the additional @var{store-var}
1380 argument. The @var{forms} should return a Lisp form which stores
1381 the value of @var{store-var} into the generalized variable formed
1382 by a call to @var{access-fn} with arguments described by @var{arglist}.
1383 The @var{forms} may begin with a string which documents the @code{setf}
1384 method (analogous to the doc string that appears at the front of a
1387 For example, the simple form of @code{defsetf} is shorthand for
1390 (defsetf @var{access-fn} (&rest args) (store)
1391 (append '(@var{update-fn}) args (list store)))
1394 The Lisp form that is returned can access the arguments from
1395 @var{arglist} and @var{store-var} in an unrestricted fashion;
1396 macros like @code{setf} and @code{cl-incf} which invoke this
1397 setf-method will insert temporary variables as needed to make
1398 sure the apparent order of evaluation is preserved.
1400 Another example drawn from the standard package:
1403 (defsetf nth (n x) (store)
1404 (list 'setcar (list 'nthcdr n x) store))
1408 @defspec define-setf-method access-fn arglist forms@dots{}
1409 This is the most general way to create new place forms. When
1410 a @code{setf} to @var{access-fn} with arguments described by
1411 @var{arglist} is expanded, the @var{forms} are evaluated and
1412 must return a list of five items:
1416 A list of @dfn{temporary variables}.
1419 A list of @dfn{value forms} corresponding to the temporary variables
1420 above. The temporary variables will be bound to these value forms
1421 as the first step of any operation on the generalized variable.
1424 A list of exactly one @dfn{store variable} (generally obtained
1425 from a call to @code{gensym}).
1428 A Lisp form which stores the contents of the store variable into
1429 the generalized variable, assuming the temporaries have been
1430 bound as described above.
1433 A Lisp form which accesses the contents of the generalized variable,
1434 assuming the temporaries have been bound.
1437 This is exactly like the Common Lisp macro of the same name,
1438 except that the method returns a list of five values rather
1439 than the five values themselves, since Emacs Lisp does not
1440 support Common Lisp's notion of multiple return values.
1442 Once again, the @var{forms} may begin with a documentation string.
1444 A setf-method should be maximally conservative with regard to
1445 temporary variables. In the setf-methods generated by
1446 @code{defsetf}, the second return value is simply the list of
1447 arguments in the place form, and the first return value is a
1448 list of a corresponding number of temporary variables generated
1449 by @code{cl-gensym}. Macros like @code{setf} and @code{cl-incf} which
1450 use this setf-method will optimize away most temporaries that
1451 turn out to be unnecessary, so there is little reason for the
1452 setf-method itself to optimize.
1455 @defun get-setf-method place &optional env
1456 This function returns the setf-method for @var{place}, by
1457 invoking the definition previously recorded by @code{defsetf}
1458 or @code{define-setf-method}. The result is a list of five
1459 values as described above. You can use this function to build
1460 your own @code{cl-incf}-like modify macros. (Actually, it is
1462 better to use the internal functions @code{cl-setf-do-modify}
1463 and @code{cl-setf-do-store}, which are a bit easier to use and
1464 which also do a number of optimizations; consult the source
1465 code for the @code{cl-incf} function for a simple example.)
1467 The argument @var{env} specifies the ``environment'' to be
1468 passed on to @code{macroexpand} if @code{get-setf-method} should
1469 need to expand a macro in @var{place}. It should come from
1470 an @code{&environment} argument to the macro or setf-method
1471 that called @code{get-setf-method}.
1473 See also the source code for the setf-methods for @code{apply}
1474 and @code{substring}, each of which works by calling
1475 @code{get-setf-method} on a simpler case, then massaging
1476 the result in various ways.
1479 Modern Common Lisp defines a second, independent way to specify
1480 the @code{setf} behavior of a function, namely ``@code{setf}
1481 functions'' whose names are lists @code{(setf @var{name})}
1482 rather than symbols. For example, @code{(defun (setf foo) @dots{})}
1483 defines the function that is used when @code{setf} is applied to
1484 @code{foo}. This package does not currently support @code{setf}
1485 functions. In particular, it is a compile-time error to use
1486 @code{setf} on a form which has not already been @code{defsetf}'d
1487 or otherwise declared; in newer Common Lisps, this would not be
1488 an error since the function @code{(setf @var{func})} might be
1495 @node Variable Bindings
1496 @section Variable Bindings
1499 These Lisp forms make bindings to variables and function names,
1500 analogous to Lisp's built-in @code{let} form.
1502 @xref{Modify Macros}, for the @code{letf} and @code{cl-letf*} forms which
1503 are also related to variable bindings.
1506 * Dynamic Bindings:: The @code{cl-progv} form.
1507 * Lexical Bindings:: @code{lexical-let} and lexical closures.
1508 * Function Bindings:: @code{flet} and @code{labels}.
1509 * Macro Bindings:: @code{cl-macrolet} and @code{cl-symbol-macrolet}.
1512 @node Dynamic Bindings
1513 @subsection Dynamic Bindings
1516 The standard @code{let} form binds variables whose names are known
1517 at compile-time. The @code{cl-progv} form provides an easy way to
1518 bind variables whose names are computed at run-time.
1520 @defspec cl-progv symbols values forms@dots{}
1521 This form establishes @code{let}-style variable bindings on a
1522 set of variables computed at run-time. The expressions
1523 @var{symbols} and @var{values} are evaluated, and must return lists
1524 of symbols and values, respectively. The symbols are bound to the
1525 corresponding values for the duration of the body @var{form}s.
1526 If @var{values} is shorter than @var{symbols}, the last few symbols
1527 are made unbound (as if by @code{makunbound}) inside the body.
1528 If @var{symbols} is shorter than @var{values}, the excess values
1532 @node Lexical Bindings
1533 @subsection Lexical Bindings
1536 The @code{CL} package defines the following macro which
1537 more closely follows the Common Lisp @code{let} form:
1539 @defspec lexical-let (bindings@dots{}) forms@dots{}
1540 This form is exactly like @code{let} except that the bindings it
1541 establishes are purely lexical. Lexical bindings are similar to
1542 local variables in a language like C: Only the code physically
1543 within the body of the @code{lexical-let} (after macro expansion)
1544 may refer to the bound variables.
1548 (defun foo (b) (+ a b))
1549 (let ((a 2)) (foo a))
1551 (lexical-let ((a 2)) (foo a))
1556 In this example, a regular @code{let} binding of @code{a} actually
1557 makes a temporary change to the global variable @code{a}, so @code{foo}
1558 is able to see the binding of @code{a} to 2. But @code{lexical-let}
1559 actually creates a distinct local variable @code{a} for use within its
1560 body, without any effect on the global variable of the same name.
1562 The most important use of lexical bindings is to create @dfn{closures}.
1563 A closure is a function object that refers to an outside lexical
1564 variable. For example:
1567 (defun make-adder (n)
1568 (lexical-let ((n n))
1569 (function (lambda (m) (+ n m)))))
1570 (setq add17 (make-adder 17))
1576 The call @code{(make-adder 17)} returns a function object which adds
1577 17 to its argument. If @code{let} had been used instead of
1578 @code{lexical-let}, the function object would have referred to the
1579 global @code{n}, which would have been bound to 17 only during the
1580 call to @code{make-adder} itself.
1583 (defun make-counter ()
1584 (lexical-let ((n 0))
1585 (cl-function (lambda (&optional (m 1)) (cl-incf n m)))))
1586 (setq count-1 (make-counter))
1589 (funcall count-1 14)
1591 (setq count-2 (make-counter))
1601 Here we see that each call to @code{make-counter} creates a distinct
1602 local variable @code{n}, which serves as a private counter for the
1603 function object that is returned.
1605 Closed-over lexical variables persist until the last reference to
1606 them goes away, just like all other Lisp objects. For example,
1607 @code{count-2} refers to a function object which refers to an
1608 instance of the variable @code{n}; this is the only reference
1609 to that variable, so after @code{(setq count-2 nil)} the garbage
1610 collector would be able to delete this instance of @code{n}.
1611 Of course, if a @code{lexical-let} does not actually create any
1612 closures, then the lexical variables are free as soon as the
1613 @code{lexical-let} returns.
1615 Many closures are used only during the extent of the bindings they
1616 refer to; these are known as ``downward funargs'' in Lisp parlance.
1617 When a closure is used in this way, regular Emacs Lisp dynamic
1618 bindings suffice and will be more efficient than @code{lexical-let}
1622 (defun add-to-list (x list)
1623 (mapcar (lambda (y) (+ x y))) list)
1624 (add-to-list 7 '(1 2 5))
1629 Since this lambda is only used while @code{x} is still bound,
1630 it is not necessary to make a true closure out of it.
1632 You can use @code{defun} or @code{flet} inside a @code{lexical-let}
1633 to create a named closure. If several closures are created in the
1634 body of a single @code{lexical-let}, they all close over the same
1635 instance of the lexical variable.
1637 The @code{lexical-let} form is an extension to Common Lisp. In
1638 true Common Lisp, all bindings are lexical unless declared otherwise.
1641 @defspec lexical-let* (bindings@dots{}) forms@dots{}
1642 This form is just like @code{lexical-let}, except that the bindings
1643 are made sequentially in the manner of @code{let*}.
1646 @node Function Bindings
1647 @subsection Function Bindings
1650 These forms make @code{let}-like bindings to functions instead
1653 @defspec flet (bindings@dots{}) forms@dots{}
1654 This form establishes @code{let}-style bindings on the function
1655 cells of symbols rather than on the value cells. Each @var{binding}
1656 must be a list of the form @samp{(@var{name} @var{arglist}
1657 @var{forms}@dots{})}, which defines a function exactly as if
1658 it were a @code{defun*} form. The function @var{name} is defined
1659 accordingly for the duration of the body of the @code{flet}; then
1660 the old function definition, or lack thereof, is restored.
1662 While @code{flet} in Common Lisp establishes a lexical binding of
1663 @var{name}, Emacs Lisp @code{flet} makes a dynamic binding. The
1664 result is that @code{flet} affects indirect calls to a function as
1665 well as calls directly inside the @code{flet} form itself.
1667 You can use @code{flet} to disable or modify the behavior of a
1668 function in a temporary fashion. This will even work on Emacs
1669 primitives, although note that some calls to primitive functions
1670 internal to Emacs are made without going through the symbol's
1671 function cell, and so will not be affected by @code{flet}. For
1675 (flet ((message (&rest args) (push args saved-msgs)))
1679 This code attempts to replace the built-in function @code{message}
1680 with a function that simply saves the messages in a list rather
1681 than displaying them. The original definition of @code{message}
1682 will be restored after @code{do-something} exits. This code will
1683 work fine on messages generated by other Lisp code, but messages
1684 generated directly inside Emacs will not be caught since they make
1685 direct C-language calls to the message routines rather than going
1686 through the Lisp @code{message} function.
1689 Also note that many primitives (e.g. @code{+}) have special byte-compile
1690 handling. Attempts to redefine such functions using @code{flet} will
1691 fail if byte-compiled. In such cases, use @code{labels} instead.
1693 Functions defined by @code{flet} may use the full Common Lisp
1694 argument notation supported by @code{cl-defun}; also, the function
1695 body is enclosed in an implicit block as if by @code{cl-defun}.
1696 @xref{Program Structure}.
1699 @defspec labels (bindings@dots{}) forms@dots{}
1700 The @code{labels} form is like @code{flet}, except that it
1701 makes lexical bindings of the function names rather than
1702 dynamic bindings. (In true Common Lisp, both @code{flet} and
1703 @code{labels} make lexical bindings of slightly different sorts;
1704 since Emacs Lisp is dynamically bound by default, it seemed
1705 more appropriate for @code{flet} also to use dynamic binding.
1706 The @code{labels} form, with its lexical binding, is fully
1707 compatible with Common Lisp.)
1709 Lexical scoping means that all references to the named
1710 functions must appear physically within the body of the
1711 @code{labels} form. References may appear both in the body
1712 @var{forms} of @code{labels} itself, and in the bodies of
1713 the functions themselves. Thus, @code{labels} can define
1714 local recursive functions, or mutually-recursive sets of
1717 A ``reference'' to a function name is either a call to that
1718 function, or a use of its name quoted by @code{quote} or
1719 @code{function} to be passed on to, say, @code{mapcar}.
1722 @node Macro Bindings
1723 @subsection Macro Bindings
1726 These forms create local macros and ``symbol macros.''
1728 @defspec cl-macrolet (bindings@dots{}) forms@dots{}
1729 This form is analogous to @code{flet}, but for macros instead of
1730 functions. Each @var{binding} is a list of the same form as the
1731 arguments to @code{cl-defmacro} (i.e., a macro name, argument list,
1732 and macro-expander forms). The macro is defined accordingly for
1733 use within the body of the @code{cl-macrolet}.
1735 Because of the nature of macros, @code{cl-macrolet} is lexically
1736 scoped even in Emacs Lisp: The @code{cl-macrolet} binding will
1737 affect only calls that appear physically within the body
1738 @var{forms}, possibly after expansion of other macros in the
1742 @defspec cl-symbol-macrolet (bindings@dots{}) forms@dots{}
1743 This form creates @dfn{symbol macros}, which are macros that look
1744 like variable references rather than function calls. Each
1745 @var{binding} is a list @samp{(@var{var} @var{expansion})};
1746 any reference to @var{var} within the body @var{forms} is
1747 replaced by @var{expansion}.
1751 (cl-symbol-macrolet ((foo (car bar)))
1757 A @code{setq} of a symbol macro is treated the same as a @code{setf}.
1758 I.e., @code{(setq foo 4)} in the above would be equivalent to
1759 @code{(setf foo 4)}, which in turn expands to @code{(setf (car bar) 4)}.
1761 Likewise, a @code{let} or @code{let*} binding a symbol macro is
1762 treated like a @code{letf} or @code{letf*}. This differs from true
1763 Common Lisp, where the rules of lexical scoping cause a @code{let}
1764 binding to shadow a @code{cl-symbol-macrolet} binding. In this package,
1765 only @code{lexical-let} and @code{lexical-let*} will shadow a symbol
1768 There is no analogue of @code{defmacro} for symbol macros; all symbol
1769 macros are local. A typical use of @code{cl-symbol-macrolet} is in the
1770 expansion of another macro:
1773 (cl-defmacro my-dolist ((x list) &rest body)
1774 (let ((var (gensym)))
1775 (list 'cl-loop 'for var 'on list 'do
1776 (cl-list* 'cl-symbol-macrolet (list (list x (list 'car var)))
1779 (setq mylist '(1 2 3 4))
1780 (my-dolist (x mylist) (cl-incf x))
1786 In this example, the @code{my-dolist} macro is similar to @code{dolist}
1787 (@pxref{Iteration}) except that the variable @code{x} becomes a true
1788 reference onto the elements of the list. The @code{my-dolist} call
1789 shown here expands to
1792 (cl-loop for G1234 on mylist do
1793 (cl-symbol-macrolet ((x (car G1234)))
1798 which in turn expands to
1801 (cl-loop for G1234 on mylist do (cl-incf (car G1234)))
1804 @xref{Loop Facility}, for a description of the @code{cl-loop} macro.
1805 This package defines a nonstandard @code{in-ref} loop clause that
1806 works much like @code{my-dolist}.
1810 @section Conditionals
1813 These conditional forms augment Emacs Lisp's simple @code{if},
1814 @code{and}, @code{or}, and @code{cond} forms.
1816 @defspec cl-case keyform clause@dots{}
1817 This macro evaluates @var{keyform}, then compares it with the key
1818 values listed in the various @var{clause}s. Whichever clause matches
1819 the key is executed; comparison is done by @code{eql}. If no clause
1820 matches, the @code{cl-case} form returns @code{nil}. The clauses are
1824 (@var{keylist} @var{body-forms}@dots{})
1828 where @var{keylist} is a list of key values. If there is exactly
1829 one value, and it is not a cons cell or the symbol @code{nil} or
1830 @code{t}, then it can be used by itself as a @var{keylist} without
1831 being enclosed in a list. All key values in the @code{case} form
1832 must be distinct. The final clauses may use @code{t} in place of
1833 a @var{keylist} to indicate a default clause that should be taken
1834 if none of the other clauses match. (The symbol @code{otherwise}
1835 is also recognized in place of @code{t}. To make a clause that
1836 matches the actual symbol @code{t}, @code{nil}, or @code{otherwise},
1837 enclose the symbol in a list.)
1839 For example, this expression reads a keystroke, then does one of
1840 four things depending on whether it is an @samp{a}, a @samp{b},
1841 a @key{RET} or @kbd{C-j}, or anything else.
1844 (cl-case (read-char)
1847 ((?\r ?\n) (do-ret-thing))
1848 (t (do-other-thing)))
1852 @defspec cl-ecase keyform clause@dots{}
1853 This macro is just like @code{cl-case}, except that if the key does
1854 not match any of the clauses, an error is signaled rather than
1855 simply returning @code{nil}.
1858 @defspec cl-typecase keyform clause@dots{}
1859 This macro is a version of @code{cl-case} that checks for types
1860 rather than values. Each @var{clause} is of the form
1861 @samp{(@var{type} @var{body}...)}. @xref{Type Predicates},
1862 for a description of type specifiers. For example,
1866 (integer (munch-integer x))
1867 (float (munch-float x))
1868 (string (munch-integer (string-to-int x)))
1869 (t (munch-anything x)))
1872 The type specifier @code{t} matches any type of object; the word
1873 @code{otherwise} is also allowed. To make one clause match any of
1874 several types, use an @code{(or ...)} type specifier.
1877 @defspec cl-etypecase keyform clause@dots{}
1878 This macro is just like @code{cl-typecase}, except that if the key does
1879 not match any of the clauses, an error is signaled rather than
1880 simply returning @code{nil}.
1883 @node Blocks and Exits
1884 @section Blocks and Exits
1887 Common Lisp @dfn{blocks} provide a non-local exit mechanism very
1888 similar to @code{catch} and @code{throw}, but lexically rather than
1889 dynamically scoped. This package actually implements @code{cl-block}
1890 in terms of @code{catch}; however, the lexical scoping allows the
1891 optimizing byte-compiler to omit the costly @code{catch} step if the
1892 body of the block does not actually @code{cl-return-from} the block.
1894 @defspec cl-block name forms@dots{}
1895 The @var{forms} are evaluated as if by a @code{progn}. However,
1896 if any of the @var{forms} execute @code{(cl-return-from @var{name})},
1897 they will jump out and return directly from the @code{cl-block} form.
1898 The @code{cl-block} returns the result of the last @var{form} unless
1899 a @code{cl-return-from} occurs.
1901 The @code{cl-block}/@code{cl-return-from} mechanism is quite similar to
1902 the @code{catch}/@code{throw} mechanism. The main differences are
1903 that block @var{name}s are unevaluated symbols, rather than forms
1904 (such as quoted symbols) which evaluate to a tag at run-time; and
1905 also that blocks are lexically scoped whereas @code{catch}/@code{throw}
1906 are dynamically scoped. This means that functions called from the
1907 body of a @code{catch} can also @code{throw} to the @code{catch},
1908 but the @code{cl-return-from} referring to a block name must appear
1909 physically within the @var{forms} that make up the body of the block.
1910 They may not appear within other called functions, although they may
1911 appear within macro expansions or @code{lambda}s in the body. Block
1912 names and @code{catch} names form independent name-spaces.
1914 In true Common Lisp, @code{defun} and @code{defmacro} surround
1915 the function or expander bodies with implicit blocks with the
1916 same name as the function or macro. This does not occur in Emacs
1917 Lisp, but this package provides @code{cl-defun} and @code{cl-defmacro}
1918 forms which do create the implicit block.
1920 The Common Lisp looping constructs defined by this package,
1921 such as @code{cl-loop} and @code{cl-dolist}, also create implicit blocks
1922 just as in Common Lisp.
1924 Because they are implemented in terms of Emacs Lisp @code{catch}
1925 and @code{throw}, blocks have the same overhead as actual
1926 @code{catch} constructs (roughly two function calls). However,
1927 the optimizing byte compiler will optimize away the @code{catch}
1929 not in fact contain any @code{cl-return} or @code{cl-return-from} calls
1930 that jump to it. This means that @code{cl-do} loops and @code{cl-defun}
1931 functions which don't use @code{cl-return} don't pay the overhead to
1935 @defspec cl-return-from name [result]
1936 This macro returns from the block named @var{name}, which must be
1937 an (unevaluated) symbol. If a @var{result} form is specified, it
1938 is evaluated to produce the result returned from the @code{block}.
1939 Otherwise, @code{nil} is returned.
1942 @defspec cl-return [result]
1943 This macro is exactly like @code{(cl-return-from nil @var{result})}.
1944 Common Lisp loops like @code{cl-do} and @code{cl-dolist} implicitly enclose
1945 themselves in @code{nil} blocks.
1952 The macros described here provide more sophisticated, high-level
1953 looping constructs to complement Emacs Lisp's basic @code{while}
1956 @defspec cl-loop forms@dots{}
1957 The @code{CL} package supports both the simple, old-style meaning of
1958 @code{loop} and the extremely powerful and flexible feature known as
1959 the @dfn{Loop Facility} or @dfn{Loop Macro}. This more advanced
1960 facility is discussed in the following section; @pxref{Loop Facility}.
1961 The simple form of @code{loop} is described here.
1963 If @code{cl-loop} is followed by zero or more Lisp expressions,
1964 then @code{(cl-loop @var{exprs}@dots{})} simply creates an infinite
1965 loop executing the expressions over and over. The loop is
1966 enclosed in an implicit @code{nil} block. Thus,
1969 (cl-loop (foo) (if (no-more) (return 72)) (bar))
1973 is exactly equivalent to
1976 (cl-block nil (while t (foo) (if (no-more) (return 72)) (bar)))
1979 If any of the expressions are plain symbols, the loop is instead
1980 interpreted as a Loop Macro specification as described later.
1981 (This is not a restriction in practice, since a plain symbol
1982 in the above notation would simply access and throw away the
1983 value of a variable.)
1986 @defspec cl-do (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
1987 This macro creates a general iterative loop. Each @var{spec} is
1991 (@var{var} [@var{init} [@var{step}]])
1994 The loop works as follows: First, each @var{var} is bound to the
1995 associated @var{init} value as if by a @code{let} form. Then, in
1996 each iteration of the loop, the @var{end-test} is evaluated; if
1997 true, the loop is finished. Otherwise, the body @var{forms} are
1998 evaluated, then each @var{var} is set to the associated @var{step}
1999 expression (as if by a @code{cl-psetq} form) and the next iteration
2000 begins. Once the @var{end-test} becomes true, the @var{result}
2001 forms are evaluated (with the @var{var}s still bound to their
2002 values) to produce the result returned by @code{do}.
2004 The entire @code{cl-do} loop is enclosed in an implicit @code{nil}
2005 block, so that you can use @code{(cl-return)} to break out of the
2008 If there are no @var{result} forms, the loop returns @code{nil}.
2009 If a given @var{var} has no @var{step} form, it is bound to its
2010 @var{init} value but not otherwise modified during the @code{do}
2011 loop (unless the code explicitly modifies it); this case is just
2012 a shorthand for putting a @code{(let ((@var{var} @var{init})) @dots{})}
2013 around the loop. If @var{init} is also omitted it defaults to
2014 @code{nil}, and in this case a plain @samp{@var{var}} can be used
2015 in place of @samp{(@var{var})}, again following the analogy with
2018 This example (from Steele) illustrates a loop which applies the
2019 function @code{f} to successive pairs of values from the lists
2020 @code{foo} and @code{bar}; it is equivalent to the call
2021 @code{(cl-mapcar 'f foo bar)}. Note that this loop has no body
2022 @var{forms} at all, performing all its work as side effects of
2023 the rest of the loop.
2026 (cl-do ((x foo (cdr x))
2028 (z nil (cons (f (car x) (car y)) z)))
2029 ((or (null x) (null y))
2034 @defspec cl-do* (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
2035 This is to @code{cl-do} what @code{let*} is to @code{let}. In
2036 particular, the initial values are bound as if by @code{let*}
2037 rather than @code{let}, and the steps are assigned as if by
2038 @code{setq} rather than @code{cl-psetq}.
2040 Here is another way to write the above loop:
2043 (cl-do* ((xp foo (cdr xp))
2045 (x (car xp) (car xp))
2046 (y (car yp) (car yp))
2048 ((or (null xp) (null yp))
2054 @defspec cl-dolist (var list [result]) forms@dots{}
2055 This is a more specialized loop which iterates across the elements
2056 of a list. @var{list} should evaluate to a list; the body @var{forms}
2057 are executed with @var{var} bound to each element of the list in
2058 turn. Finally, the @var{result} form (or @code{nil}) is evaluated
2059 with @var{var} bound to @code{nil} to produce the result returned by
2060 the loop. Unlike with Emacs's built in @code{dolist}, the loop is
2061 surrounded by an implicit @code{nil} block.
2064 @defspec cl-dotimes (var count [result]) forms@dots{}
2065 This is a more specialized loop which iterates a specified number
2066 of times. The body is executed with @var{var} bound to the integers
2067 from zero (inclusive) to @var{count} (exclusive), in turn. Then
2068 the @code{result} form is evaluated with @var{var} bound to the total
2069 number of iterations that were done (i.e., @code{(max 0 @var{count})})
2070 to get the return value for the loop form. Unlike with Emacs's built in
2071 @code{dolist}, the loop is surrounded by an implicit @code{nil} block.
2074 @defspec cl-do-symbols (var [obarray [result]]) forms@dots{}
2075 This loop iterates over all interned symbols. If @var{obarray}
2076 is specified and is not @code{nil}, it loops over all symbols in
2077 that obarray. For each symbol, the body @var{forms} are evaluated
2078 with @var{var} bound to that symbol. The symbols are visited in
2079 an unspecified order. Afterward the @var{result} form, if any,
2080 is evaluated (with @var{var} bound to @code{nil}) to get the return
2081 value. The loop is surrounded by an implicit @code{nil} block.
2084 @defspec cl-do-all-symbols (var [result]) forms@dots{}
2085 This is identical to @code{cl-do-symbols} except that the @var{obarray}
2086 argument is omitted; it always iterates over the default obarray.
2089 @xref{Mapping over Sequences}, for some more functions for
2090 iterating over vectors or lists.
2093 @section Loop Facility
2096 A common complaint with Lisp's traditional looping constructs is
2097 that they are either too simple and limited, such as Common Lisp's
2098 @code{dotimes} or Emacs Lisp's @code{while}, or too unreadable and
2099 obscure, like Common Lisp's @code{do} loop.
2101 To remedy this, recent versions of Common Lisp have added a new
2102 construct called the ``Loop Facility'' or ``@code{loop} macro,''
2103 with an easy-to-use but very powerful and expressive syntax.
2106 * Loop Basics:: @code{cl-loop} macro, basic clause structure.
2107 * Loop Examples:: Working examples of @code{cl-loop} macro.
2108 * For Clauses:: Clauses introduced by @code{for} or @code{as}.
2109 * Iteration Clauses:: @code{repeat}, @code{while}, @code{thereis}, etc.
2110 * Accumulation Clauses:: @code{collect}, @code{sum}, @code{maximize}, etc.
2111 * Other Clauses:: @code{with}, @code{if}, @code{initially}, @code{finally}.
2115 @subsection Loop Basics
2118 The @code{cl-loop} macro essentially creates a mini-language within
2119 Lisp that is specially tailored for describing loops. While this
2120 language is a little strange-looking by the standards of regular Lisp,
2121 it turns out to be very easy to learn and well-suited to its purpose.
2123 Since @code{cl-loop} is a macro, all parsing of the loop language
2124 takes place at byte-compile time; compiled @code{cl-loop}s are just
2125 as efficient as the equivalent @code{while} loops written longhand.
2127 @defspec cl-loop clauses@dots{}
2128 A loop construct consists of a series of @var{clause}s, each
2129 introduced by a symbol like @code{for} or @code{do}. Clauses
2130 are simply strung together in the argument list of @code{cl-loop},
2131 with minimal extra parentheses. The various types of clauses
2132 specify initializations, such as the binding of temporary
2133 variables, actions to be taken in the loop, stepping actions,
2136 Common Lisp specifies a certain general order of clauses in a
2140 (cl-loop @var{name-clause}
2141 @var{var-clauses}@dots{}
2142 @var{action-clauses}@dots{})
2145 The @var{name-clause} optionally gives a name to the implicit
2146 block that surrounds the loop. By default, the implicit block
2147 is named @code{nil}. The @var{var-clauses} specify what
2148 variables should be bound during the loop, and how they should
2149 be modified or iterated throughout the course of the loop. The
2150 @var{action-clauses} are things to be done during the loop, such
2151 as computing, collecting, and returning values.
2153 The Emacs version of the @code{cl-loop} macro is less restrictive about
2154 the order of clauses, but things will behave most predictably if
2155 you put the variable-binding clauses @code{with}, @code{for}, and
2156 @code{repeat} before the action clauses. As in Common Lisp,
2157 @code{initially} and @code{finally} clauses can go anywhere.
2159 Loops generally return @code{nil} by default, but you can cause
2160 them to return a value by using an accumulation clause like
2161 @code{collect}, an end-test clause like @code{always}, or an
2162 explicit @code{return} clause to jump out of the implicit block.
2163 (Because the loop body is enclosed in an implicit block, you can
2164 also use regular Lisp @code{return} or @code{return-from} to
2165 break out of the loop.)
2168 The following sections give some examples of the Loop Macro in
2169 action, and describe the particular loop clauses in great detail.
2170 Consult the second edition of Steele's @dfn{Common Lisp, the Language},
2171 for additional discussion and examples of the @code{loop} macro.
2174 @subsection Loop Examples
2177 Before listing the full set of clauses that are allowed, let's
2178 look at a few example loops just to get a feel for the @code{cl-loop}
2182 (cl-loop for buf in (buffer-list)
2183 collect (buffer-file-name buf))
2187 This loop iterates over all Emacs buffers, using the list
2188 returned by @code{buffer-list}. For each buffer @code{buf},
2189 it calls @code{buffer-file-name} and collects the results into
2190 a list, which is then returned from the @code{cl-loop} construct.
2191 The result is a list of the file names of all the buffers in
2192 Emacs's memory. The words @code{for}, @code{in}, and @code{collect}
2193 are reserved words in the @code{cl-loop} language.
2196 (cl-loop repeat 20 do (insert "Yowsa\n"))
2200 This loop inserts the phrase ``Yowsa'' twenty times in the
2204 (cl-loop until (eobp) do (munch-line) (forward-line 1))
2208 This loop calls @code{munch-line} on every line until the end
2209 of the buffer. If point is already at the end of the buffer,
2210 the loop exits immediately.
2213 (cl-loop do (munch-line) until (eobp) do (forward-line 1))
2217 This loop is similar to the above one, except that @code{munch-line}
2218 is always called at least once.
2221 (cl-loop for x from 1 to 100
2224 finally return (list x (= y 729)))
2228 This more complicated loop searches for a number @code{x} whose
2229 square is 729. For safety's sake it only examines @code{x}
2230 values up to 100; dropping the phrase @samp{to 100} would
2231 cause the loop to count upwards with no limit. The second
2232 @code{for} clause defines @code{y} to be the square of @code{x}
2233 within the loop; the expression after the @code{=} sign is
2234 reevaluated each time through the loop. The @code{until}
2235 clause gives a condition for terminating the loop, and the
2236 @code{finally} clause says what to do when the loop finishes.
2237 (This particular example was written less concisely than it
2238 could have been, just for the sake of illustration.)
2240 Note that even though this loop contains three clauses (two
2241 @code{for}s and an @code{until}) that would have been enough to
2242 define loops all by themselves, it still creates a single loop
2243 rather than some sort of triple-nested loop. You must explicitly
2244 nest your @code{cl-loop} constructs if you want nested loops.
2247 @subsection For Clauses
2250 Most loops are governed by one or more @code{for} clauses.
2251 A @code{for} clause simultaneously describes variables to be
2252 bound, how those variables are to be stepped during the loop,
2253 and usually an end condition based on those variables.
2255 The word @code{as} is a synonym for the word @code{for}. This
2256 word is followed by a variable name, then a word like @code{from}
2257 or @code{across} that describes the kind of iteration desired.
2258 In Common Lisp, the phrase @code{being the} sometimes precedes
2259 the type of iteration; in this package both @code{being} and
2260 @code{the} are optional. The word @code{each} is a synonym
2261 for @code{the}, and the word that follows it may be singular
2262 or plural: @samp{for x being the elements of y} or
2263 @samp{for x being each element of y}. Which form you use
2264 is purely a matter of style.
2266 The variable is bound around the loop as if by @code{let}:
2270 (cl-loop for i from 1 to 10 do (do-something-with i))
2276 @item for @var{var} from @var{expr1} to @var{expr2} by @var{expr3}
2277 This type of @code{for} clause creates a counting loop. Each of
2278 the three sub-terms is optional, though there must be at least one
2279 term so that the clause is marked as a counting clause.
2281 The three expressions are the starting value, the ending value, and
2282 the step value, respectively, of the variable. The loop counts
2283 upwards by default (@var{expr3} must be positive), from @var{expr1}
2284 to @var{expr2} inclusively. If you omit the @code{from} term, the
2285 loop counts from zero; if you omit the @code{to} term, the loop
2286 counts forever without stopping (unless stopped by some other
2287 loop clause, of course); if you omit the @code{by} term, the loop
2288 counts in steps of one.
2290 You can replace the word @code{from} with @code{upfrom} or
2291 @code{downfrom} to indicate the direction of the loop. Likewise,
2292 you can replace @code{to} with @code{upto} or @code{downto}.
2293 For example, @samp{for x from 5 downto 1} executes five times
2294 with @code{x} taking on the integers from 5 down to 1 in turn.
2295 Also, you can replace @code{to} with @code{below} or @code{above},
2296 which are like @code{upto} and @code{downto} respectively except
2297 that they are exclusive rather than inclusive limits:
2300 (cl-loop for x to 10 collect x)
2301 @result{} (0 1 2 3 4 5 6 7 8 9 10)
2302 (cl-loop for x below 10 collect x)
2303 @result{} (0 1 2 3 4 5 6 7 8 9)
2306 The @code{by} value is always positive, even for downward-counting
2307 loops. Some sort of @code{from} value is required for downward
2308 loops; @samp{for x downto 5} is not a valid loop clause all by
2311 @item for @var{var} in @var{list} by @var{function}
2312 This clause iterates @var{var} over all the elements of @var{list},
2313 in turn. If you specify the @code{by} term, then @var{function}
2314 is used to traverse the list instead of @code{cdr}; it must be a
2315 function taking one argument. For example:
2318 (cl-loop for x in '(1 2 3 4 5 6) collect (* x x))
2319 @result{} (1 4 9 16 25 36)
2320 (cl-loop for x in '(1 2 3 4 5 6) by 'cddr collect (* x x))
2324 @item for @var{var} on @var{list} by @var{function}
2325 This clause iterates @var{var} over all the cons cells of @var{list}.
2328 (cl-loop for x on '(1 2 3 4) collect x)
2329 @result{} ((1 2 3 4) (2 3 4) (3 4) (4))
2332 With @code{by}, there is no real reason that the @code{on} expression
2333 must be a list. For example:
2336 (cl-loop for x on first-animal by 'next-animal collect x)
2340 where @code{(next-animal x)} takes an ``animal'' @var{x} and returns
2341 the next in the (assumed) sequence of animals, or @code{nil} if
2342 @var{x} was the last animal in the sequence.
2344 @item for @var{var} in-ref @var{list} by @var{function}
2345 This is like a regular @code{in} clause, but @var{var} becomes
2346 a @code{setf}-able ``reference'' onto the elements of the list
2347 rather than just a temporary variable. For example,
2350 (cl-loop for x in-ref my-list do (cl-incf x))
2354 increments every element of @code{my-list} in place. This clause
2355 is an extension to standard Common Lisp.
2357 @item for @var{var} across @var{array}
2358 This clause iterates @var{var} over all the elements of @var{array},
2359 which may be a vector or a string.
2362 (cl-loop for x across "aeiou"
2363 do (use-vowel (char-to-string x)))
2366 @item for @var{var} across-ref @var{array}
2367 This clause iterates over an array, with @var{var} a @code{setf}-able
2368 reference onto the elements; see @code{in-ref} above.
2370 @item for @var{var} being the elements of @var{sequence}
2371 This clause iterates over the elements of @var{sequence}, which may
2372 be a list, vector, or string. Since the type must be determined
2373 at run-time, this is somewhat less efficient than @code{in} or
2374 @code{across}. The clause may be followed by the additional term
2375 @samp{using (index @var{var2})} to cause @var{var2} to be bound to
2376 the successive indices (starting at 0) of the elements.
2378 This clause type is taken from older versions of the @code{loop} macro,
2379 and is not present in modern Common Lisp. The @samp{using (sequence ...)}
2380 term of the older macros is not supported.
2382 @item for @var{var} being the elements of-ref @var{sequence}
2383 This clause iterates over a sequence, with @var{var} a @code{setf}-able
2384 reference onto the elements; see @code{in-ref} above.
2386 @item for @var{var} being the symbols [of @var{obarray}]
2387 This clause iterates over symbols, either over all interned symbols
2388 or over all symbols in @var{obarray}. The loop is executed with
2389 @var{var} bound to each symbol in turn. The symbols are visited in
2390 an unspecified order.
2395 (cl-loop for sym being the symbols
2397 when (string-match "^map" (symbol-name sym))
2402 returns a list of all the functions whose names begin with @samp{map}.
2404 The Common Lisp words @code{external-symbols} and @code{present-symbols}
2405 are also recognized but are equivalent to @code{symbols} in Emacs Lisp.
2407 Due to a minor implementation restriction, it will not work to have
2408 more than one @code{for} clause iterating over symbols, hash tables,
2409 keymaps, overlays, or intervals in a given @code{cl-loop}. Fortunately,
2410 it would rarely if ever be useful to do so. It @emph{is} valid to mix
2411 one of these types of clauses with other clauses like @code{for ... to}
2414 @item for @var{var} being the hash-keys of @var{hash-table}
2415 @itemx for @var{var} being the hash-values of @var{hash-table}
2416 This clause iterates over the entries in @var{hash-table} with
2417 @var{var} bound to each key, or value. A @samp{using} clause can bind
2418 a second variable to the opposite part.
2421 (cl-loop for k being the hash-keys of h
2422 using (hash-values v)
2424 (message "key %S -> value %S" k v))
2427 @item for @var{var} being the key-codes of @var{keymap}
2428 @itemx for @var{var} being the key-bindings of @var{keymap}
2429 This clause iterates over the entries in @var{keymap}.
2430 The iteration does not enter nested keymaps but does enter inherited
2432 A @code{using} clause can access both the codes and the bindings
2436 (cl-loop for c being the key-codes of (current-local-map)
2437 using (key-bindings b)
2439 (message "key %S -> binding %S" c b))
2443 @item for @var{var} being the key-seqs of @var{keymap}
2444 This clause iterates over all key sequences defined by @var{keymap}
2445 and its nested keymaps, where @var{var} takes on values which are
2446 vectors. The strings or vectors
2447 are reused for each iteration, so you must copy them if you wish to keep
2448 them permanently. You can add a @samp{using (key-bindings ...)}
2449 clause to get the command bindings as well.
2451 @item for @var{var} being the overlays [of @var{buffer}] @dots{}
2452 This clause iterates over the ``overlays'' of a buffer
2453 (the clause @code{extents} is synonymous
2454 with @code{overlays}). If the @code{of} term is omitted, the current
2456 This clause also accepts optional @samp{from @var{pos}} and
2457 @samp{to @var{pos}} terms, limiting the clause to overlays which
2458 overlap the specified region.
2460 @item for @var{var} being the intervals [of @var{buffer}] @dots{}
2461 This clause iterates over all intervals of a buffer with constant
2462 text properties. The variable @var{var} will be bound to conses
2463 of start and end positions, where one start position is always equal
2464 to the previous end position. The clause allows @code{of},
2465 @code{from}, @code{to}, and @code{property} terms, where the latter
2466 term restricts the search to just the specified property. The
2467 @code{of} term may specify either a buffer or a string.
2469 @item for @var{var} being the frames
2470 This clause iterates over all Emacs frames. The clause @code{screens} is
2471 a synonym for @code{frames}. The frames are visited in
2472 @code{next-frame} order starting from @code{selected-frame}.
2474 @item for @var{var} being the windows [of @var{frame}]
2475 This clause iterates over the windows (in the Emacs sense) of
2476 the current frame, or of the specified @var{frame}. It visits windows
2477 in @code{next-window} order starting from @code{selected-window}
2478 (or @code{frame-selected-window} if you specify @var{frame}).
2479 This clause treats the minibuffer window in the same way as
2480 @code{next-window} does. For greater flexibility, consider using
2481 @code{walk-windows} instead.
2483 @item for @var{var} being the buffers
2484 This clause iterates over all buffers in Emacs. It is equivalent
2485 to @samp{for @var{var} in (buffer-list)}.
2487 @item for @var{var} = @var{expr1} then @var{expr2}
2488 This clause does a general iteration. The first time through
2489 the loop, @var{var} will be bound to @var{expr1}. On the second
2490 and successive iterations it will be set by evaluating @var{expr2}
2491 (which may refer to the old value of @var{var}). For example,
2492 these two loops are effectively the same:
2495 (cl-loop for x on my-list by 'cddr do ...)
2496 (cl-loop for x = my-list then (cddr x) while x do ...)
2499 Note that this type of @code{for} clause does not imply any sort
2500 of terminating condition; the above example combines it with a
2501 @code{while} clause to tell when to end the loop.
2503 If you omit the @code{then} term, @var{expr1} is used both for
2504 the initial setting and for successive settings:
2507 (cl-loop for x = (random) when (> x 0) return x)
2511 This loop keeps taking random numbers from the @code{(random)}
2512 function until it gets a positive one, which it then returns.
2515 If you include several @code{for} clauses in a row, they are
2516 treated sequentially (as if by @code{let*} and @code{setq}).
2517 You can instead use the word @code{and} to link the clauses,
2518 in which case they are processed in parallel (as if by @code{let}
2519 and @code{cl-psetq}).
2522 (cl-loop for x below 5 for y = nil then x collect (list x y))
2523 @result{} ((0 nil) (1 1) (2 2) (3 3) (4 4))
2524 (cl-loop for x below 5 and y = nil then x collect (list x y))
2525 @result{} ((0 nil) (1 0) (2 1) (3 2) (4 3))
2529 In the first loop, @code{y} is set based on the value of @code{x}
2530 that was just set by the previous clause; in the second loop,
2531 @code{x} and @code{y} are set simultaneously so @code{y} is set
2532 based on the value of @code{x} left over from the previous time
2535 Another feature of the @code{cl-loop} macro is @dfn{destructuring},
2536 similar in concept to the destructuring provided by @code{defmacro}.
2537 The @var{var} part of any @code{for} clause can be given as a list
2538 of variables instead of a single variable. The values produced
2539 during loop execution must be lists; the values in the lists are
2540 stored in the corresponding variables.
2543 (cl-loop for (x y) in '((2 3) (4 5) (6 7)) collect (+ x y))
2547 In loop destructuring, if there are more values than variables
2548 the trailing values are ignored, and if there are more variables
2549 than values the trailing variables get the value @code{nil}.
2550 If @code{nil} is used as a variable name, the corresponding
2551 values are ignored. Destructuring may be nested, and dotted
2552 lists of variables like @code{(x . y)} are allowed, so for example
2556 (cl-loop for (key . value) in '((a . 1) (b . 2))
2561 @node Iteration Clauses
2562 @subsection Iteration Clauses
2565 Aside from @code{for} clauses, there are several other loop clauses
2566 that control the way the loop operates. They might be used by
2567 themselves, or in conjunction with one or more @code{for} clauses.
2570 @item repeat @var{integer}
2571 This clause simply counts up to the specified number using an
2572 internal temporary variable. The loops
2575 (cl-loop repeat (1+ n) do ...)
2576 (cl-loop for temp to n do ...)
2580 are identical except that the second one forces you to choose
2581 a name for a variable you aren't actually going to use.
2583 @item while @var{condition}
2584 This clause stops the loop when the specified condition (any Lisp
2585 expression) becomes @code{nil}. For example, the following two
2586 loops are equivalent, except for the implicit @code{nil} block
2587 that surrounds the second one:
2590 (while @var{cond} @var{forms}@dots{})
2591 (cl-loop while @var{cond} do @var{forms}@dots{})
2594 @item until @var{condition}
2595 This clause stops the loop when the specified condition is true,
2596 i.e., non-@code{nil}.
2598 @item always @var{condition}
2599 This clause stops the loop when the specified condition is @code{nil}.
2600 Unlike @code{while}, it stops the loop using @code{return nil} so that
2601 the @code{finally} clauses are not executed. If all the conditions
2602 were non-@code{nil}, the loop returns @code{t}:
2605 (if (cl-loop for size in size-list always (> size 10))
2610 @item never @var{condition}
2611 This clause is like @code{always}, except that the loop returns
2612 @code{t} if any conditions were false, or @code{nil} otherwise.
2614 @item thereis @var{condition}
2615 This clause stops the loop when the specified form is non-@code{nil};
2616 in this case, it returns that non-@code{nil} value. If all the
2617 values were @code{nil}, the loop returns @code{nil}.
2620 @node Accumulation Clauses
2621 @subsection Accumulation Clauses
2624 These clauses cause the loop to accumulate information about the
2625 specified Lisp @var{form}. The accumulated result is returned
2626 from the loop unless overridden, say, by a @code{return} clause.
2629 @item collect @var{form}
2630 This clause collects the values of @var{form} into a list. Several
2631 examples of @code{collect} appear elsewhere in this manual.
2633 The word @code{collecting} is a synonym for @code{collect}, and
2634 likewise for the other accumulation clauses.
2636 @item append @var{form}
2637 This clause collects lists of values into a result list using
2640 @item nconc @var{form}
2641 This clause collects lists of values into a result list by
2642 destructively modifying the lists rather than copying them.
2644 @item concat @var{form}
2645 This clause concatenates the values of the specified @var{form}
2646 into a string. (It and the following clause are extensions to
2647 standard Common Lisp.)
2649 @item vconcat @var{form}
2650 This clause concatenates the values of the specified @var{form}
2653 @item count @var{form}
2654 This clause counts the number of times the specified @var{form}
2655 evaluates to a non-@code{nil} value.
2657 @item sum @var{form}
2658 This clause accumulates the sum of the values of the specified
2659 @var{form}, which must evaluate to a number.
2661 @item maximize @var{form}
2662 This clause accumulates the maximum value of the specified @var{form},
2663 which must evaluate to a number. The return value is undefined if
2664 @code{maximize} is executed zero times.
2666 @item minimize @var{form}
2667 This clause accumulates the minimum value of the specified @var{form}.
2670 Accumulation clauses can be followed by @samp{into @var{var}} to
2671 cause the data to be collected into variable @var{var} (which is
2672 automatically @code{let}-bound during the loop) rather than an
2673 unnamed temporary variable. Also, @code{into} accumulations do
2674 not automatically imply a return value. The loop must use some
2675 explicit mechanism, such as @code{finally return}, to return
2676 the accumulated result.
2678 It is valid for several accumulation clauses of the same type to
2679 accumulate into the same place. From Steele:
2682 (cl-loop for name in '(fred sue alice joe june)
2683 for kids in '((bob ken) () () (kris sunshine) ())
2686 @result{} (fred bob ken sue alice joe kris sunshine june)
2690 @subsection Other Clauses
2693 This section describes the remaining loop clauses.
2696 @item with @var{var} = @var{value}
2697 This clause binds a variable to a value around the loop, but
2698 otherwise leaves the variable alone during the loop. The following
2699 loops are basically equivalent:
2702 (cl-loop with x = 17 do ...)
2703 (let ((x 17)) (cl-loop do ...))
2704 (cl-loop for x = 17 then x do ...)
2707 Naturally, the variable @var{var} might be used for some purpose
2708 in the rest of the loop. For example:
2711 (cl-loop for x in my-list with res = nil do (push x res)
2715 This loop inserts the elements of @code{my-list} at the front of
2716 a new list being accumulated in @code{res}, then returns the
2717 list @code{res} at the end of the loop. The effect is similar
2718 to that of a @code{collect} clause, but the list gets reversed
2719 by virtue of the fact that elements are being pushed onto the
2720 front of @code{res} rather than the end.
2722 If you omit the @code{=} term, the variable is initialized to
2723 @code{nil}. (Thus the @samp{= nil} in the above example is
2726 Bindings made by @code{with} are sequential by default, as if
2727 by @code{let*}. Just like @code{for} clauses, @code{with} clauses
2728 can be linked with @code{and} to cause the bindings to be made by
2731 @item if @var{condition} @var{clause}
2732 This clause executes the following loop clause only if the specified
2733 condition is true. The following @var{clause} should be an accumulation,
2734 @code{do}, @code{return}, @code{if}, or @code{unless} clause.
2735 Several clauses may be linked by separating them with @code{and}.
2736 These clauses may be followed by @code{else} and a clause or clauses
2737 to execute if the condition was false. The whole construct may
2738 optionally be followed by the word @code{end} (which may be used to
2739 disambiguate an @code{else} or @code{and} in a nested @code{if}).
2741 The actual non-@code{nil} value of the condition form is available
2742 by the name @code{it} in the ``then'' part. For example:
2745 (setq funny-numbers '(6 13 -1))
2747 (cl-loop for x below 10
2750 and if (memq x funny-numbers) return (cdr it) end
2752 collect x into evens
2753 finally return (vector odds evens))
2754 @result{} [(1 3 5 7 9) (0 2 4 6 8)]
2755 (setq funny-numbers '(6 7 13 -1))
2756 @result{} (6 7 13 -1)
2757 (cl-loop <@r{same thing again}>)
2761 Note the use of @code{and} to put two clauses into the ``then''
2762 part, one of which is itself an @code{if} clause. Note also that
2763 @code{end}, while normally optional, was necessary here to make
2764 it clear that the @code{else} refers to the outermost @code{if}
2765 clause. In the first case, the loop returns a vector of lists
2766 of the odd and even values of @var{x}. In the second case, the
2767 odd number 7 is one of the @code{funny-numbers} so the loop
2768 returns early; the actual returned value is based on the result
2769 of the @code{memq} call.
2771 @item when @var{condition} @var{clause}
2772 This clause is just a synonym for @code{if}.
2774 @item unless @var{condition} @var{clause}
2775 The @code{unless} clause is just like @code{if} except that the
2776 sense of the condition is reversed.
2778 @item named @var{name}
2779 This clause gives a name other than @code{nil} to the implicit
2780 block surrounding the loop. The @var{name} is the symbol to be
2781 used as the block name.
2783 @item initially [do] @var{forms}...
2784 This keyword introduces one or more Lisp forms which will be
2785 executed before the loop itself begins (but after any variables
2786 requested by @code{for} or @code{with} have been bound to their
2787 initial values). @code{initially} clauses can appear anywhere;
2788 if there are several, they are executed in the order they appear
2789 in the loop. The keyword @code{do} is optional.
2791 @item finally [do] @var{forms}...
2792 This introduces Lisp forms which will be executed after the loop
2793 finishes (say, on request of a @code{for} or @code{while}).
2794 @code{initially} and @code{finally} clauses may appear anywhere
2795 in the loop construct, but they are executed (in the specified
2796 order) at the beginning or end, respectively, of the loop.
2798 @item finally return @var{form}
2799 This says that @var{form} should be executed after the loop
2800 is done to obtain a return value. (Without this, or some other
2801 clause like @code{collect} or @code{return}, the loop will simply
2802 return @code{nil}.) Variables bound by @code{for}, @code{with},
2803 or @code{into} will still contain their final values when @var{form}
2806 @item do @var{forms}...
2807 The word @code{do} may be followed by any number of Lisp expressions
2808 which are executed as an implicit @code{progn} in the body of the
2809 loop. Many of the examples in this section illustrate the use of
2812 @item return @var{form}
2813 This clause causes the loop to return immediately. The following
2814 Lisp form is evaluated to give the return value of the @code{loop}
2815 form. The @code{finally} clauses, if any, are not executed.
2816 Of course, @code{return} is generally used inside an @code{if} or
2817 @code{unless}, as its use in a top-level loop clause would mean
2818 the loop would never get to ``loop'' more than once.
2820 The clause @samp{return @var{form}} is equivalent to
2821 @samp{do (return @var{form})} (or @code{return-from} if the loop
2822 was named). The @code{return} clause is implemented a bit more
2823 efficiently, though.
2826 While there is no high-level way to add user extensions to @code{cl-loop}
2827 (comparable to @code{defsetf} for @code{setf}, say), this package
2828 does offer two properties called @code{cl-loop-handler} and
2829 @code{cl-loop-for-handler} which are functions to be called when
2830 a given symbol is encountered as a top-level loop clause or
2831 @code{for} clause, respectively. Consult the source code in
2832 file @file{cl-macs.el} for details.
2834 This package's @code{cl-loop} macro is compatible with that of Common
2835 Lisp, except that a few features are not implemented: @code{loop-finish}
2836 and data-type specifiers. Naturally, the @code{for} clauses which
2837 iterate over keymaps, overlays, intervals, frames, windows, and
2838 buffers are Emacs-specific extensions.
2840 @node Multiple Values
2841 @section Multiple Values
2844 Common Lisp functions can return zero or more results. Emacs Lisp
2845 functions, by contrast, always return exactly one result. This
2846 package makes no attempt to emulate Common Lisp multiple return
2847 values; Emacs versions of Common Lisp functions that return more
2848 than one value either return just the first value (as in
2849 @code{cl-compiler-macroexpand}) or return a list of values (as in
2850 @code{get-setf-method}). This package @emph{does} define placeholders
2851 for the Common Lisp functions that work with multiple values, but
2852 in Emacs Lisp these functions simply operate on lists instead.
2853 The @code{values} form, for example, is a synonym for @code{list}
2856 @defspec cl-multiple-value-bind (var@dots{}) values-form forms@dots{}
2857 This form evaluates @var{values-form}, which must return a list of
2858 values. It then binds the @var{var}s to these respective values,
2859 as if by @code{let}, and then executes the body @var{forms}.
2860 If there are more @var{var}s than values, the extra @var{var}s
2861 are bound to @code{nil}. If there are fewer @var{var}s than
2862 values, the excess values are ignored.
2865 @defspec cl-multiple-value-setq (var@dots{}) form
2866 This form evaluates @var{form}, which must return a list of values.
2867 It then sets the @var{var}s to these respective values, as if by
2868 @code{setq}. Extra @var{var}s or values are treated the same as
2869 in @code{cl-multiple-value-bind}.
2872 Since a perfect emulation is not feasible in Emacs Lisp, this
2873 package opts to keep it as simple and predictable as possible.
2879 This package implements the various Common Lisp features of
2880 @code{defmacro}, such as destructuring, @code{&environment},
2881 and @code{&body}. Top-level @code{&whole} is not implemented
2882 for @code{defmacro} due to technical difficulties.
2883 @xref{Argument Lists}.
2885 Destructuring is made available to the user by way of the
2888 @defspec cl-destructuring-bind arglist expr forms@dots{}
2889 This macro expands to code which executes @var{forms}, with
2890 the variables in @var{arglist} bound to the list of values
2891 returned by @var{expr}. The @var{arglist} can include all
2892 the features allowed for @code{defmacro} argument lists,
2893 including destructuring. (The @code{&environment} keyword
2894 is not allowed.) The macro expansion will signal an error
2895 if @var{expr} returns a list of the wrong number of arguments
2896 or with incorrect keyword arguments.
2899 This package also includes the Common Lisp @code{cl-define-compiler-macro}
2900 facility, which allows you to define compile-time expansions and
2901 optimizations for your functions.
2903 @defspec cl-define-compiler-macro name arglist forms@dots{}
2904 This form is similar to @code{defmacro}, except that it only expands
2905 calls to @var{name} at compile-time; calls processed by the Lisp
2906 interpreter are not expanded, nor are they expanded by the
2907 @code{macroexpand} function.
2909 The argument list may begin with a @code{&whole} keyword and a
2910 variable. This variable is bound to the macro-call form itself,
2911 i.e., to a list of the form @samp{(@var{name} @var{args}@dots{})}.
2912 If the macro expander returns this form unchanged, then the
2913 compiler treats it as a normal function call. This allows
2914 compiler macros to work as optimizers for special cases of a
2915 function, leaving complicated cases alone.
2917 For example, here is a simplified version of a definition that
2918 appears as a standard part of this package:
2921 (cl-define-compiler-macro cl-member (&whole form a list &rest keys)
2922 (if (and (null keys)
2923 (eq (car-safe a) 'quote)
2924 (not (floatp-safe (cadr a))))
2930 This definition causes @code{(cl-member @var{a} @var{list})} to change
2931 to a call to the faster @code{memq} in the common case where @var{a}
2932 is a non-floating-point constant; if @var{a} is anything else, or
2933 if there are any keyword arguments in the call, then the original
2934 @code{cl-member} call is left intact. (The actual compiler macro
2935 for @code{cl-member} optimizes a number of other cases, including
2936 common @code{:test} predicates.)
2939 @defun cl-compiler-macroexpand form
2940 This function is analogous to @code{macroexpand}, except that it
2941 expands compiler macros rather than regular macros. It returns
2942 @var{form} unchanged if it is not a call to a function for which
2943 a compiler macro has been defined, or if that compiler macro
2944 decided to punt by returning its @code{&whole} argument. Like
2945 @code{macroexpand}, it expands repeatedly until it reaches a form
2946 for which no further expansion is possible.
2949 @xref{Macro Bindings}, for descriptions of the @code{cl-macrolet}
2950 and @code{cl-symbol-macrolet} forms for making ``local'' macro
2954 @chapter Declarations
2957 Common Lisp includes a complex and powerful ``declaration''
2958 mechanism that allows you to give the compiler special hints
2959 about the types of data that will be stored in particular variables,
2960 and about the ways those variables and functions will be used. This
2961 package defines versions of all the Common Lisp declaration forms:
2962 @code{cl-declare}, @code{cl-locally}, @code{cl-proclaim}, @code{cl-declaim},
2965 Most of the Common Lisp declarations are not currently useful in
2966 Emacs Lisp, as the byte-code system provides little opportunity
2967 to benefit from type information, and @code{special} declarations
2968 are redundant in a fully dynamically-scoped Lisp. A few
2969 declarations are meaningful when the optimizing byte
2970 compiler is being used, however. Under the earlier non-optimizing
2971 compiler, these declarations will effectively be ignored.
2973 @defun cl-proclaim decl-spec
2974 This function records a ``global'' declaration specified by
2975 @var{decl-spec}. Since @code{cl-proclaim} is a function, @var{decl-spec}
2976 is evaluated and thus should normally be quoted.
2979 @defspec cl-declaim decl-specs@dots{}
2980 This macro is like @code{cl-proclaim}, except that it takes any number
2981 of @var{decl-spec} arguments, and the arguments are unevaluated and
2982 unquoted. The @code{cl-declaim} macro also puts an @code{(cl-eval-when
2983 (compile load eval) ...)} around the declarations so that they will
2984 be registered at compile-time as well as at run-time. (This is vital,
2985 since normally the declarations are meant to influence the way the
2986 compiler treats the rest of the file that contains the @code{cl-declaim}
2990 @defspec cl-declare decl-specs@dots{}
2991 This macro is used to make declarations within functions and other
2992 code. Common Lisp allows declarations in various locations, generally
2993 at the beginning of any of the many ``implicit @code{progn}s''
2994 throughout Lisp syntax, such as function bodies, @code{let} bodies,
2995 etc. Currently the only declaration understood by @code{cl-declare}
2999 @defspec cl-locally declarations@dots{} forms@dots{}
3000 In this package, @code{cl-locally} is no different from @code{progn}.
3003 @defspec cl-the type form
3004 Type information provided by @code{cl-the} is ignored in this package;
3005 in other words, @code{(cl-the @var{type} @var{form})} is equivalent
3006 to @var{form}. Future versions of the optimizing byte-compiler may
3007 make use of this information.
3009 For example, @code{mapcar} can map over both lists and arrays. It is
3010 hard for the compiler to expand @code{mapcar} into an in-line loop
3011 unless it knows whether the sequence will be a list or an array ahead
3012 of time. With @code{(mapcar 'car (cl-the vector foo))}, a future
3013 compiler would have enough information to expand the loop in-line.
3014 For now, Emacs Lisp will treat the above code as exactly equivalent
3015 to @code{(mapcar 'car foo)}.
3018 Each @var{decl-spec} in a @code{cl-proclaim}, @code{cl-declaim}, or
3019 @code{cl-declare} should be a list beginning with a symbol that says
3020 what kind of declaration it is. This package currently understands
3021 @code{special}, @code{inline}, @code{notinline}, @code{optimize},
3022 and @code{warn} declarations. (The @code{warn} declaration is an
3023 extension of standard Common Lisp.) Other Common Lisp declarations,
3024 such as @code{type} and @code{ftype}, are silently ignored.
3028 Since all variables in Emacs Lisp are ``special'' (in the Common
3029 Lisp sense), @code{special} declarations are only advisory. They
3030 simply tell the optimizing byte compiler that the specified
3031 variables are intentionally being referred to without being
3032 bound in the body of the function. The compiler normally emits
3033 warnings for such references, since they could be typographical
3034 errors for references to local variables.
3036 The declaration @code{(cl-declare (special @var{var1} @var{var2}))} is
3037 equivalent to @code{(defvar @var{var1}) (defvar @var{var2})} in the
3038 optimizing compiler, or to nothing at all in older compilers (which
3039 do not warn for non-local references).
3041 In top-level contexts, it is generally better to write
3042 @code{(defvar @var{var})} than @code{(cl-declaim (special @var{var}))},
3043 since @code{defvar} makes your intentions clearer. But the older
3044 byte compilers can not handle @code{defvar}s appearing inside of
3045 functions, while @code{(cl-declare (special @var{var}))} takes care
3046 to work correctly with all compilers.
3049 The @code{inline} @var{decl-spec} lists one or more functions
3050 whose bodies should be expanded ``in-line'' into calling functions
3051 whenever the compiler is able to arrange for it. For example,
3052 the Common Lisp function @code{cadr} is declared @code{inline}
3053 by this package so that the form @code{(cadr @var{x})} will
3054 expand directly into @code{(car (cdr @var{x}))} when it is called
3055 in user functions, for a savings of one (relatively expensive)
3058 The following declarations are all equivalent. Note that the
3059 @code{defsubst} form is a convenient way to define a function
3060 and declare it inline all at once.
3063 (cl-declaim (inline foo bar))
3064 (cl-eval-when (compile load eval) (cl-proclaim '(inline foo bar)))
3065 (defsubst foo (...) ...) ; instead of defun
3068 @strong{Please note:} this declaration remains in effect after the
3069 containing source file is done. It is correct to use it to
3070 request that a function you have defined should be inlined,
3071 but it is impolite to use it to request inlining of an external
3074 In Common Lisp, it is possible to use @code{(cl-declare (inline @dots{}))}
3075 before a particular call to a function to cause just that call to
3076 be inlined; the current byte compilers provide no way to implement
3077 this, so @code{(cl-declare (inline @dots{}))} is currently ignored by
3081 The @code{notinline} declaration lists functions which should
3082 not be inlined after all; it cancels a previous @code{inline}
3086 This declaration controls how much optimization is performed by
3087 the compiler. Naturally, it is ignored by the earlier non-optimizing
3090 The word @code{optimize} is followed by any number of lists like
3091 @code{(speed 3)} or @code{(safety 2)}. Common Lisp defines several
3092 optimization ``qualities''; this package ignores all but @code{speed}
3093 and @code{safety}. The value of a quality should be an integer from
3094 0 to 3, with 0 meaning ``unimportant'' and 3 meaning ``very important.''
3095 The default level for both qualities is 1.
3097 In this package, with the optimizing compiler, the
3098 @c FIXME does not exist?
3099 @code{speed} quality is tied to the @code{byte-compile-optimize}
3100 flag, which is set to @code{nil} for @code{(speed 0)} and to
3101 @code{t} for higher settings; and the @code{safety} quality is
3102 tied to the @code{byte-compile-delete-errors} flag, which is
3103 set to @code{t} for @code{(safety 3)} and to @code{nil} for all
3104 lower settings. (The latter flag controls whether the compiler
3105 is allowed to optimize out code whose only side-effect could
3106 be to signal an error, e.g., rewriting @code{(progn foo bar)} to
3107 @code{bar} when it is not known whether @code{foo} will be bound
3110 Note that even compiling with @code{(safety 0)}, the Emacs
3111 byte-code system provides sufficient checking to prevent real
3112 harm from being done. For example, barring serious bugs in
3113 Emacs itself, Emacs will not crash with a segmentation fault
3114 just because of an error in a fully-optimized Lisp program.
3116 The @code{optimize} declaration is normally used in a top-level
3117 @code{cl-proclaim} or @code{cl-declaim} in a file; Common Lisp allows
3118 it to be used with @code{cl-declare} to set the level of optimization
3119 locally for a given form, but this will not work correctly with the
3120 current version of the optimizing compiler. (The @code{cl-declare}
3121 will set the new optimization level, but that level will not
3122 automatically be unset after the enclosing form is done.)
3125 This declaration controls what sorts of warnings are generated
3126 by the byte compiler. Again, only the optimizing compiler
3127 generates warnings. The word @code{warn} is followed by any
3128 number of ``warning qualities,'' similar in form to optimization
3129 qualities. The currently supported warning types are
3130 @code{redefine}, @code{callargs}, @code{unresolved}, and
3131 @code{free-vars}; in the current system, a value of 0 will
3132 disable these warnings and any higher value will enable them.
3133 See the documentation for the optimizing byte compiler for details.
3140 This package defines several symbol-related features that were
3141 missing from Emacs Lisp.
3144 * Property Lists:: @code{cl-get}, @code{cl-remprop}, @code{cl-getf}, @code{cl-remf}.
3145 * Creating Symbols:: @code{cl-gensym}, @code{cl-gentemp}.
3148 @node Property Lists
3149 @section Property Lists
3152 These functions augment the standard Emacs Lisp functions @code{get}
3153 and @code{put} for operating on properties attached to symbols.
3154 There are also functions for working with property lists as
3155 first-class data structures not attached to particular symbols.
3157 @defun cl-get symbol property &optional default
3158 This function is like @code{get}, except that if the property is
3159 not found, the @var{default} argument provides the return value.
3160 (The Emacs Lisp @code{get} function always uses @code{nil} as
3161 the default; this package's @code{cl-get} is equivalent to Common
3164 The @code{cl-get} function is @code{setf}-able; when used in this
3165 fashion, the @var{default} argument is allowed but ignored.
3168 @defun cl-remprop symbol property
3169 This function removes the entry for @var{property} from the property
3170 list of @var{symbol}. It returns a true value if the property was
3171 indeed found and removed, or @code{nil} if there was no such property.
3172 (This function was probably omitted from Emacs originally because,
3173 since @code{get} did not allow a @var{default}, it was very difficult
3174 to distinguish between a missing property and a property whose value
3175 was @code{nil}; thus, setting a property to @code{nil} was close
3176 enough to @code{cl-remprop} for most purposes.)
3179 @defun cl-getf place property &optional default
3180 This function scans the list @var{place} as if it were a property
3181 list, i.e., a list of alternating property names and values. If
3182 an even-numbered element of @var{place} is found which is @code{eq}
3183 to @var{property}, the following odd-numbered element is returned.
3184 Otherwise, @var{default} is returned (or @code{nil} if no default
3190 (get sym prop) @equiv{} (cl-get (symbol-plist sym) prop)
3193 It is valid to use @code{getf} as a @code{setf} place, in which case
3194 its @var{place} argument must itself be a valid @code{setf} place.
3195 The @var{default} argument, if any, is ignored in this context.
3196 The effect is to change (via @code{setcar}) the value cell in the
3197 list that corresponds to @var{property}, or to cons a new property-value
3198 pair onto the list if the property is not yet present.
3201 (put sym prop val) @equiv{} (setf (cl-get (symbol-plist sym) prop) val)
3204 The @code{get} and @code{cl-get} functions are also @code{setf}-able.
3205 The fact that @code{default} is ignored can sometimes be useful:
3208 (cl-incf (cl-get 'foo 'usage-count 0))
3211 Here, symbol @code{foo}'s @code{usage-count} property is incremented
3212 if it exists, or set to 1 (an incremented 0) otherwise.
3215 When not used as a @code{setf} form, @code{getf} is just a regular
3216 function and its @var{place} argument can actually be any Lisp
3220 @defspec cl-remf place property
3221 This macro removes the property-value pair for @var{property} from
3222 the property list stored at @var{place}, which is any @code{setf}-able
3223 place expression. It returns true if the property was found. Note
3224 that if @var{property} happens to be first on the list, this will
3225 effectively do a @code{(setf @var{place} (cddr @var{place}))},
3226 whereas if it occurs later, this simply uses @code{setcdr} to splice
3227 out the property and value cells.
3234 @node Creating Symbols
3235 @section Creating Symbols
3238 These functions create unique symbols, typically for use as
3239 temporary variables.
3241 @defun cl-gensym &optional x
3242 This function creates a new, uninterned symbol (using @code{make-symbol})
3243 with a unique name. (The name of an uninterned symbol is relevant
3244 only if the symbol is printed.) By default, the name is generated
3245 from an increasing sequence of numbers, @samp{G1000}, @samp{G1001},
3246 @samp{G1002}, etc. If the optional argument @var{x} is a string, that
3247 string is used as a prefix instead of @samp{G}. Uninterned symbols
3248 are used in macro expansions for temporary variables, to ensure that
3249 their names will not conflict with ``real'' variables in the user's
3253 @defvar cl--gensym-counter
3254 This variable holds the counter used to generate @code{cl-gensym} names.
3255 It is incremented after each use by @code{cl-gensym}. In Common Lisp
3256 this is initialized with 0, but this package initializes it with a
3257 random (time-dependent) value to avoid trouble when two files that
3258 each used @code{cl-gensym} in their compilation are loaded together.
3259 (Uninterned symbols become interned when the compiler writes them
3260 out to a file and the Emacs loader loads them, so their names have to
3261 be treated a bit more carefully than in Common Lisp where uninterned
3262 symbols remain uninterned after loading.)
3265 @defun cl-gentemp &optional x
3266 This function is like @code{cl-gensym}, except that it produces a new
3267 @emph{interned} symbol. If the symbol that is generated already
3268 exists, the function keeps incrementing the counter and trying
3269 again until a new symbol is generated.
3272 This package automatically creates all keywords that are called for by
3273 @code{&key} argument specifiers, and discourages the use of keywords
3274 as data unrelated to keyword arguments, so the related function
3275 @code{defkeyword} (to create self-quoting keyword symbols) is not
3282 This section defines a few simple Common Lisp operations on numbers
3283 which were left out of Emacs Lisp.
3286 * Predicates on Numbers:: @code{cl-plusp}, @code{cl-oddp}, @code{cl-floatp-safe}, etc.
3287 * Numerical Functions:: @code{abs}, @code{cl-floor}, etc.
3288 * Random Numbers:: @code{cl-random}, @code{cl-make-random-state}.
3289 * Implementation Parameters:: @code{cl-most-positive-float}.
3296 @node Predicates on Numbers
3297 @section Predicates on Numbers
3300 These functions return @code{t} if the specified condition is
3301 true of the numerical argument, or @code{nil} otherwise.
3303 @defun cl-plusp number
3304 This predicate tests whether @var{number} is positive. It is an
3305 error if the argument is not a number.
3308 @defun cl-minusp number
3309 This predicate tests whether @var{number} is negative. It is an
3310 error if the argument is not a number.
3313 @defun cl-oddp integer
3314 This predicate tests whether @var{integer} is odd. It is an
3315 error if the argument is not an integer.
3318 @defun cl-evenp integer
3319 This predicate tests whether @var{integer} is even. It is an
3320 error if the argument is not an integer.
3323 @defun cl-floatp-safe object
3324 This predicate tests whether @var{object} is a floating-point
3325 number. On systems that support floating-point, this is equivalent
3326 to @code{floatp}. On other systems, this always returns @code{nil}.
3333 @node Numerical Functions
3334 @section Numerical Functions
3337 These functions perform various arithmetic operations on numbers.
3339 @defun cl-gcd &rest integers
3340 This function returns the Greatest Common Divisor of the arguments.
3341 For one argument, it returns the absolute value of that argument.
3342 For zero arguments, it returns zero.
3345 @defun cl-lcm &rest integers
3346 This function returns the Least Common Multiple of the arguments.
3347 For one argument, it returns the absolute value of that argument.
3348 For zero arguments, it returns one.
3351 @defun cl-isqrt integer
3352 This function computes the ``integer square root'' of its integer
3353 argument, i.e., the greatest integer less than or equal to the true
3354 square root of the argument.
3357 @defun cl-floor number &optional divisor
3358 With one argument, @code{cl-floor} returns a list of two numbers:
3359 The argument rounded down (toward minus infinity) to an integer,
3360 and the ``remainder'' which would have to be added back to the
3361 first return value to yield the argument again. If the argument
3362 is an integer @var{x}, the result is always the list @code{(@var{x} 0)}.
3363 If the argument is a floating-point number, the first
3364 result is a Lisp integer and the second is a Lisp float between
3365 0 (inclusive) and 1 (exclusive).
3367 With two arguments, @code{cl-floor} divides @var{number} by
3368 @var{divisor}, and returns the floor of the quotient and the
3369 corresponding remainder as a list of two numbers. If
3370 @code{(cl-floor @var{x} @var{y})} returns @code{(@var{q} @var{r})},
3371 then @code{@var{q}*@var{y} + @var{r} = @var{x}}, with @var{r}
3372 between 0 (inclusive) and @var{r} (exclusive). Also, note
3373 that @code{(cl-floor @var{x})} is exactly equivalent to
3374 @code{(cl-floor @var{x} 1)}.
3376 This function is entirely compatible with Common Lisp's @code{floor}
3377 function, except that it returns the two results in a list since
3378 Emacs Lisp does not support multiple-valued functions.
3381 @defun cl-ceiling number &optional divisor
3382 This function implements the Common Lisp @code{ceiling} function,
3383 which is analogous to @code{floor} except that it rounds the
3384 argument or quotient of the arguments up toward plus infinity.
3385 The remainder will be between 0 and minus @var{r}.
3388 @defun cl-truncate number &optional divisor
3389 This function implements the Common Lisp @code{truncate} function,
3390 which is analogous to @code{floor} except that it rounds the
3391 argument or quotient of the arguments toward zero. Thus it is
3392 equivalent to @code{cl-floor} if the argument or quotient is
3393 positive, or to @code{cl-ceiling} otherwise. The remainder has
3394 the same sign as @var{number}.
3397 @defun cl-round number &optional divisor
3398 This function implements the Common Lisp @code{round} function,
3399 which is analogous to @code{floor} except that it rounds the
3400 argument or quotient of the arguments to the nearest integer.
3401 In the case of a tie (the argument or quotient is exactly
3402 halfway between two integers), it rounds to the even integer.
3405 @defun cl-mod number divisor
3406 This function returns the same value as the second return value
3410 @defun cl-rem number divisor
3411 This function returns the same value as the second return value
3412 of @code{cl-truncate}.
3419 @node Random Numbers
3420 @section Random Numbers
3423 This package also provides an implementation of the Common Lisp
3424 random number generator. It uses its own additive-congruential
3425 algorithm, which is much more likely to give statistically clean
3426 random numbers than the simple generators supplied by many
3429 @defun cl-random number &optional state
3430 This function returns a random nonnegative number less than
3431 @var{number}, and of the same type (either integer or floating-point).
3432 The @var{state} argument should be a @code{random-state} object
3433 which holds the state of the random number generator. The
3434 function modifies this state object as a side effect. If
3435 @var{state} is omitted, it defaults to the variable
3436 @code{*random-state*}, which contains a pre-initialized
3437 @code{random-state} object.
3440 @defvar cl--random-state
3441 This variable contains the system ``default'' @code{random-state}
3442 object, used for calls to @code{cl-random} that do not specify an
3443 alternative state object. Since any number of programs in the
3444 Emacs process may be accessing @code{cl--random-state} in interleaved
3445 fashion, the sequence generated from this variable will be
3446 irreproducible for all intents and purposes.
3449 @defun cl-make-random-state &optional state
3450 This function creates or copies a @code{random-state} object.
3451 If @var{state} is omitted or @code{nil}, it returns a new copy of
3452 @code{cl--random-state}. This is a copy in the sense that future
3453 sequences of calls to @code{(cl-random @var{n})} and
3454 @code{(cl-random @var{n} @var{s})} (where @var{s} is the new
3455 random-state object) will return identical sequences of random
3458 If @var{state} is a @code{random-state} object, this function
3459 returns a copy of that object. If @var{state} is @code{t}, this
3460 function returns a new @code{random-state} object seeded from the
3461 date and time. As an extension to Common Lisp, @var{state} may also
3462 be an integer in which case the new object is seeded from that
3463 integer; each different integer seed will result in a completely
3464 different sequence of random numbers.
3466 It is valid to print a @code{random-state} object to a buffer or
3467 file and later read it back with @code{read}. If a program wishes
3468 to use a sequence of pseudo-random numbers which can be reproduced
3469 later for debugging, it can call @code{(cl-make-random-state t)} to
3470 get a new sequence, then print this sequence to a file. When the
3471 program is later rerun, it can read the original run's random-state
3475 @defun cl-random-state-p object
3476 This predicate returns @code{t} if @var{object} is a
3477 @code{random-state} object, or @code{nil} otherwise.
3480 @node Implementation Parameters
3481 @section Implementation Parameters
3484 This package defines several useful constants having to with numbers.
3486 The following parameters have to do with floating-point numbers.
3487 This package determines their values by exercising the computer's
3488 floating-point arithmetic in various ways. Because this operation
3489 might be slow, the code for initializing them is kept in a separate
3490 function that must be called before the parameters can be used.
3492 @defun cl-float-limits
3493 This function makes sure that the Common Lisp floating-point parameters
3494 like @code{cl-most-positive-float} have been initialized. Until it is
3495 called, these parameters will be @code{nil}. If this version of Emacs
3496 does not support floats, the parameters will remain @code{nil}. If the
3497 parameters have already been initialized, the function returns
3500 The algorithm makes assumptions that will be valid for most modern
3501 machines, but will fail if the machine's arithmetic is extremely
3502 unusual, e.g., decimal.
3505 Since true Common Lisp supports up to four different floating-point
3506 precisions, it has families of constants like
3507 @code{most-positive-single-float}, @code{most-positive-double-float},
3508 @code{most-positive-long-float}, and so on. Emacs has only one
3509 floating-point precision, so this package omits the precision word
3510 from the constants' names.
3512 @defvar cl-most-positive-float
3513 This constant equals the largest value a Lisp float can hold.
3514 For those systems whose arithmetic supports infinities, this is
3515 the largest @emph{finite} value. For IEEE machines, the value
3516 is approximately @code{1.79e+308}.
3519 @defvar cl-most-negative-float
3520 This constant equals the most-negative value a Lisp float can hold.
3521 (It is assumed to be equal to @code{(- cl-most-positive-float)}.)
3524 @defvar cl-least-positive-float
3525 This constant equals the smallest Lisp float value greater than zero.
3526 For IEEE machines, it is about @code{4.94e-324} if denormals are
3527 supported or @code{2.22e-308} if not.
3530 @defvar cl-least-positive-normalized-float
3531 This constant equals the smallest @emph{normalized} Lisp float greater
3532 than zero, i.e., the smallest value for which IEEE denormalization
3533 will not result in a loss of precision. For IEEE machines, this
3534 value is about @code{2.22e-308}. For machines that do not support
3535 the concept of denormalization and gradual underflow, this constant
3536 will always equal @code{cl-least-positive-float}.
3539 @defvar cl-least-negative-float
3540 This constant is the negative counterpart of @code{cl-least-positive-float}.
3543 @defvar cl-least-negative-normalized-float
3544 This constant is the negative counterpart of
3545 @code{cl-least-positive-normalized-float}.
3548 @defvar cl-float-epsilon
3549 This constant is the smallest positive Lisp float that can be added
3550 to 1.0 to produce a distinct value. Adding a smaller number to 1.0
3551 will yield 1.0 again due to roundoff. For IEEE machines, epsilon
3552 is about @code{2.22e-16}.
3555 @defvar cl-float-negative-epsilon
3556 This is the smallest positive value that can be subtracted from
3557 1.0 to produce a distinct value. For IEEE machines, it is about
3565 Common Lisp defines a number of functions that operate on
3566 @dfn{sequences}, which are either lists, strings, or vectors.
3567 Emacs Lisp includes a few of these, notably @code{elt} and
3568 @code{length}; this package defines most of the rest.
3571 * Sequence Basics:: Arguments shared by all sequence functions.
3572 * Mapping over Sequences:: @code{cl-mapcar}, @code{cl-mapcan}, @code{cl-map}, @code{cl-every}, etc.
3573 * Sequence Functions:: @code{cl-subseq}, @code{cl-remove}, @code{cl-substitute}, etc.
3574 * Searching Sequences:: @code{cl-find}, @code{cl-position}, @code{cl-count}, @code{cl-search}, etc.
3575 * Sorting Sequences:: @code{cl-sort}, @code{cl-stable-sort}, @code{cl-merge}.
3578 @node Sequence Basics
3579 @section Sequence Basics
3582 Many of the sequence functions take keyword arguments; @pxref{Argument
3583 Lists}. All keyword arguments are optional and, if specified,
3584 may appear in any order.
3586 The @code{:key} argument should be passed either @code{nil}, or a
3587 function of one argument. This key function is used as a filter
3588 through which the elements of the sequence are seen; for example,
3589 @code{(cl-find x y :key 'car)} is similar to @code{(cl-assoc x y)}:
3590 It searches for an element of the list whose @code{car} equals
3591 @code{x}, rather than for an element which equals @code{x} itself.
3592 If @code{:key} is omitted or @code{nil}, the filter is effectively
3593 the identity function.
3595 The @code{:test} and @code{:test-not} arguments should be either
3596 @code{nil}, or functions of two arguments. The test function is
3597 used to compare two sequence elements, or to compare a search value
3598 with sequence elements. (The two values are passed to the test
3599 function in the same order as the original sequence function
3600 arguments from which they are derived, or, if they both come from
3601 the same sequence, in the same order as they appear in that sequence.)
3602 The @code{:test} argument specifies a function which must return
3603 true (non-@code{nil}) to indicate a match; instead, you may use
3604 @code{:test-not} to give a function which returns @emph{false} to
3605 indicate a match. The default test function is @code{eql}.
3607 Many functions which take @var{item} and @code{:test} or @code{:test-not}
3608 arguments also come in @code{-if} and @code{-if-not} varieties,
3609 where a @var{predicate} function is passed instead of @var{item},
3610 and sequence elements match if the predicate returns true on them
3611 (or false in the case of @code{-if-not}). For example:
3614 (cl-remove 0 seq :test '=) @equiv{} (cl-remove-if 'zerop seq)
3618 to remove all zeros from sequence @code{seq}.
3620 Some operations can work on a subsequence of the argument sequence;
3621 these function take @code{:start} and @code{:end} arguments which
3622 default to zero and the length of the sequence, respectively.
3623 Only elements between @var{start} (inclusive) and @var{end}
3624 (exclusive) are affected by the operation. The @var{end} argument
3625 may be passed @code{nil} to signify the length of the sequence;
3626 otherwise, both @var{start} and @var{end} must be integers, with
3627 @code{0 <= @var{start} <= @var{end} <= (length @var{seq})}.
3628 If the function takes two sequence arguments, the limits are
3629 defined by keywords @code{:start1} and @code{:end1} for the first,
3630 and @code{:start2} and @code{:end2} for the second.
3632 A few functions accept a @code{:from-end} argument, which, if
3633 non-@code{nil}, causes the operation to go from right-to-left
3634 through the sequence instead of left-to-right, and a @code{:count}
3635 argument, which specifies an integer maximum number of elements
3636 to be removed or otherwise processed.
3638 The sequence functions make no guarantees about the order in
3639 which the @code{:test}, @code{:test-not}, and @code{:key} functions
3640 are called on various elements. Therefore, it is a bad idea to depend
3641 on side effects of these functions. For example, @code{:from-end}
3642 may cause the sequence to be scanned actually in reverse, or it may
3643 be scanned forwards but computing a result ``as if'' it were scanned
3644 backwards. (Some functions, like @code{cl-mapcar} and @code{cl-every},
3645 @emph{do} specify exactly the order in which the function is called
3646 so side effects are perfectly acceptable in those cases.)
3648 Strings may contain ``text properties'' as well
3649 as character data. Except as noted, it is undefined whether or
3650 not text properties are preserved by sequence functions. For
3651 example, @code{(cl-remove ?A @var{str})} may or may not preserve
3652 the properties of the characters copied from @var{str} into the
3655 @node Mapping over Sequences
3656 @section Mapping over Sequences
3659 These functions ``map'' the function you specify over the elements
3660 of lists or arrays. They are all variations on the theme of the
3661 built-in function @code{mapcar}.
3663 @defun cl-mapcar function seq &rest more-seqs
3664 This function calls @var{function} on successive parallel sets of
3665 elements from its argument sequences. Given a single @var{seq}
3666 argument it is equivalent to @code{mapcar}; given @var{n} sequences,
3667 it calls the function with the first elements of each of the sequences
3668 as the @var{n} arguments to yield the first element of the result
3669 list, then with the second elements, and so on. The mapping stops as
3670 soon as the shortest sequence runs out. The argument sequences may
3671 be any mixture of lists, strings, and vectors; the return sequence
3674 Common Lisp's @code{mapcar} accepts multiple arguments but works
3675 only on lists; Emacs Lisp's @code{mapcar} accepts a single sequence
3676 argument. This package's @code{cl-mapcar} works as a compatible
3680 @defun cl-map result-type function seq &rest more-seqs
3681 This function maps @var{function} over the argument sequences,
3682 just like @code{cl-mapcar}, but it returns a sequence of type
3683 @var{result-type} rather than a list. @var{result-type} must
3684 be one of the following symbols: @code{vector}, @code{string},
3685 @code{list} (in which case the effect is the same as for
3686 @code{mapcar*}), or @code{nil} (in which case the results are
3687 thrown away and @code{cl-map} returns @code{nil}).
3690 @defun cl-maplist function list &rest more-lists
3691 This function calls @var{function} on each of its argument lists,
3692 then on the @code{cdr}s of those lists, and so on, until the
3693 shortest list runs out. The results are returned in the form
3694 of a list. Thus, @code{cl-maplist} is like @code{cl-mapcar} except
3695 that it passes in the list pointers themselves rather than the
3696 @code{car}s of the advancing pointers.
3699 @c FIXME does not exist?
3700 @defun cl-mapc function seq &rest more-seqs
3701 This function is like @code{cl-mapcar}, except that the values returned
3702 by @var{function} are ignored and thrown away rather than being
3703 collected into a list. The return value of @code{cl-mapc} is @var{seq},
3704 the first sequence. This function is more general than the Emacs
3705 primitive @code{mapc}.
3708 @defun cl-mapl function list &rest more-lists
3709 This function is like @code{cl-maplist}, except that it throws away
3710 the values returned by @var{function}.
3713 @defun cl-mapcan function seq &rest more-seqs
3714 This function is like @code{cl-mapcar}, except that it concatenates
3715 the return values (which must be lists) using @code{nconc},
3716 rather than simply collecting them into a list.
3719 @defun cl-mapcon function list &rest more-lists
3720 This function is like @code{cl-maplist}, except that it concatenates
3721 the return values using @code{nconc}.
3724 @defun cl-some predicate seq &rest more-seqs
3725 This function calls @var{predicate} on each element of @var{seq}
3726 in turn; if @var{predicate} returns a non-@code{nil} value,
3727 @code{some} returns that value, otherwise it returns @code{nil}.
3728 Given several sequence arguments, it steps through the sequences
3729 in parallel until the shortest one runs out, just as in
3730 @code{cl-mapcar}. You can rely on the left-to-right order in which
3731 the elements are visited, and on the fact that mapping stops
3732 immediately as soon as @var{predicate} returns non-@code{nil}.
3735 @defun cl-every predicate seq &rest more-seqs
3736 This function calls @var{predicate} on each element of the sequence(s)
3737 in turn; it returns @code{nil} as soon as @var{predicate} returns
3738 @code{nil} for any element, or @code{t} if the predicate was true
3742 @defun cl-notany predicate seq &rest more-seqs
3743 This function calls @var{predicate} on each element of the sequence(s)
3744 in turn; it returns @code{nil} as soon as @var{predicate} returns
3745 a non-@code{nil} value for any element, or @code{t} if the predicate
3746 was @code{nil} for all elements.
3749 @defun cl-notevery predicate seq &rest more-seqs
3750 This function calls @var{predicate} on each element of the sequence(s)
3751 in turn; it returns a non-@code{nil} value as soon as @var{predicate}
3752 returns @code{nil} for any element, or @code{t} if the predicate was
3753 true for all elements.
3756 @defun cl-reduce function seq @t{&key :from-end :start :end :initial-value :key}
3757 This function combines the elements of @var{seq} using an associative
3758 binary operation. Suppose @var{function} is @code{*} and @var{seq} is
3759 the list @code{(2 3 4 5)}. The first two elements of the list are
3760 combined with @code{(* 2 3) = 6}; this is combined with the next
3761 element, @code{(* 6 4) = 24}, and that is combined with the final
3762 element: @code{(* 24 5) = 120}. Note that the @code{*} function happens
3763 to be self-reducing, so that @code{(* 2 3 4 5)} has the same effect as
3764 an explicit call to @code{cl-reduce}.
3766 If @code{:from-end} is true, the reduction is right-associative instead
3767 of left-associative:
3770 (cl-reduce '- '(1 2 3 4))
3771 @equiv{} (- (- (- 1 2) 3) 4) @result{} -8
3772 (cl-reduce '- '(1 2 3 4) :from-end t)
3773 @equiv{} (- 1 (- 2 (- 3 4))) @result{} -2
3776 If @code{:key} is specified, it is a function of one argument which
3777 is called on each of the sequence elements in turn.
3779 If @code{:initial-value} is specified, it is effectively added to the
3780 front (or rear in the case of @code{:from-end}) of the sequence.
3781 The @code{:key} function is @emph{not} applied to the initial value.
3783 If the sequence, including the initial value, has exactly one element
3784 then that element is returned without ever calling @var{function}.
3785 If the sequence is empty (and there is no initial value), then
3786 @var{function} is called with no arguments to obtain the return value.
3789 All of these mapping operations can be expressed conveniently in
3790 terms of the @code{cl-loop} macro. In compiled code, @code{cl-loop} will
3791 be faster since it generates the loop as in-line code with no
3794 @node Sequence Functions
3795 @section Sequence Functions
3798 This section describes a number of Common Lisp functions for
3799 operating on sequences.
3801 @defun cl-subseq sequence start &optional end
3802 This function returns a given subsequence of the argument
3803 @var{sequence}, which may be a list, string, or vector.
3804 The indices @var{start} and @var{end} must be in range, and
3805 @var{start} must be no greater than @var{end}. If @var{end}
3806 is omitted, it defaults to the length of the sequence. The
3807 return value is always a copy; it does not share structure
3808 with @var{sequence}.
3810 As an extension to Common Lisp, @var{start} and/or @var{end}
3811 may be negative, in which case they represent a distance back
3812 from the end of the sequence. This is for compatibility with
3813 Emacs's @code{substring} function. Note that @code{cl-subseq} is
3814 the @emph{only} sequence function that allows negative
3815 @var{start} and @var{end}.
3817 You can use @code{setf} on a @code{cl-subseq} form to replace a
3818 specified range of elements with elements from another sequence.
3819 The replacement is done as if by @code{cl-replace}, described below.
3822 @defun cl-concatenate result-type &rest seqs
3823 This function concatenates the argument sequences together to
3824 form a result sequence of type @var{result-type}, one of the
3825 symbols @code{vector}, @code{string}, or @code{list}. The
3826 arguments are always copied, even in cases such as
3827 @code{(cl-concatenate 'list '(1 2 3))} where the result is
3828 identical to an argument.
3831 @defun cl-fill seq item @t{&key :start :end}
3832 This function fills the elements of the sequence (or the specified
3833 part of the sequence) with the value @var{item}.
3836 @defun cl-replace seq1 seq2 @t{&key :start1 :end1 :start2 :end2}
3837 This function copies part of @var{seq2} into part of @var{seq1}.
3838 The sequence @var{seq1} is not stretched or resized; the amount
3839 of data copied is simply the shorter of the source and destination
3840 (sub)sequences. The function returns @var{seq1}.
3842 If @var{seq1} and @var{seq2} are @code{eq}, then the replacement
3843 will work correctly even if the regions indicated by the start
3844 and end arguments overlap. However, if @var{seq1} and @var{seq2}
3845 are lists which share storage but are not @code{eq}, and the
3846 start and end arguments specify overlapping regions, the effect
3850 @defun cl-remove item seq @t{&key :test :test-not :key :count :start :end :from-end}
3851 This returns a copy of @var{seq} with all elements matching
3852 @var{item} removed. The result may share storage with or be
3853 @code{eq} to @var{seq} in some circumstances, but the original
3854 @var{seq} will not be modified. The @code{:test}, @code{:test-not},
3855 and @code{:key} arguments define the matching test that is used;
3856 by default, elements @code{eql} to @var{item} are removed. The
3857 @code{:count} argument specifies the maximum number of matching
3858 elements that can be removed (only the leftmost @var{count} matches
3859 are removed). The @code{:start} and @code{:end} arguments specify
3860 a region in @var{seq} in which elements will be removed; elements
3861 outside that region are not matched or removed. The @code{:from-end}
3862 argument, if true, says that elements should be deleted from the
3863 end of the sequence rather than the beginning (this matters only
3864 if @var{count} was also specified).
3867 @defun cl-delete item seq @t{&key :test :test-not :key :count :start :end :from-end}
3868 This deletes all elements of @var{seq} which match @var{item}.
3869 It is a destructive operation. Since Emacs Lisp does not support
3870 stretchable strings or vectors, this is the same as @code{cl-remove}
3871 for those sequence types. On lists, @code{cl-remove} will copy the
3872 list if necessary to preserve the original list, whereas
3873 @code{cl-delete} will splice out parts of the argument list.
3874 Compare @code{append} and @code{nconc}, which are analogous
3875 non-destructive and destructive list operations in Emacs Lisp.
3878 @findex cl-remove-if
3879 @findex cl-remove-if-not
3880 @findex cl-delete-if
3881 @findex cl-delete-if-not
3882 The predicate-oriented functions @code{cl-remove-if}, @code{cl-remove-if-not},
3883 @code{cl-delete-if}, and @code{cl-delete-if-not} are defined similarly.
3885 @defun cl-remove-duplicates seq @t{&key :test :test-not :key :start :end :from-end}
3886 This function returns a copy of @var{seq} with duplicate elements
3887 removed. Specifically, if two elements from the sequence match
3888 according to the @code{:test}, @code{:test-not}, and @code{:key}
3889 arguments, only the rightmost one is retained. If @code{:from-end}
3890 is true, the leftmost one is retained instead. If @code{:start} or
3891 @code{:end} is specified, only elements within that subsequence are
3892 examined or removed.
3895 @defun cl-delete-duplicates seq @t{&key :test :test-not :key :start :end :from-end}
3896 This function deletes duplicate elements from @var{seq}. It is
3897 a destructive version of @code{cl-remove-duplicates}.
3900 @defun cl-substitute new old seq @t{&key :test :test-not :key :count :start :end :from-end}
3901 This function returns a copy of @var{seq}, with all elements
3902 matching @var{old} replaced with @var{new}. The @code{:count},
3903 @code{:start}, @code{:end}, and @code{:from-end} arguments may be
3904 used to limit the number of substitutions made.
3907 @defun cl-nsubstitute new old seq @t{&key :test :test-not :key :count :start :end :from-end}
3908 This is a destructive version of @code{cl-substitute}; it performs
3909 the substitution using @code{setcar} or @code{aset} rather than
3910 by returning a changed copy of the sequence.
3913 @findex cl-substitute-if
3914 @findex cl-substitute-if-not
3915 @findex cl-nsubstitute-if
3916 @findex cl-nsubstitute-if-not
3917 The @code{cl-substitute-if}, @code{cl-substitute-if-not}, @code{cl-nsubstitute-if},
3918 and @code{cl-nsubstitute-if-not} functions are defined similarly. For
3919 these, a @var{predicate} is given in place of the @var{old} argument.
3921 @node Searching Sequences
3922 @section Searching Sequences
3925 These functions search for elements or subsequences in a sequence.
3926 (See also @code{cl-member} and @code{cl-assoc}; @pxref{Lists}.)
3928 @defun cl-find item seq @t{&key :test :test-not :key :start :end :from-end}
3929 This function searches @var{seq} for an element matching @var{item}.
3930 If it finds a match, it returns the matching element. Otherwise,
3931 it returns @code{nil}. It returns the leftmost match, unless
3932 @code{:from-end} is true, in which case it returns the rightmost
3933 match. The @code{:start} and @code{:end} arguments may be used to
3934 limit the range of elements that are searched.
3937 @defun cl-position item seq @t{&key :test :test-not :key :start :end :from-end}
3938 This function is like @code{cl-find}, except that it returns the
3939 integer position in the sequence of the matching item rather than
3940 the item itself. The position is relative to the start of the
3941 sequence as a whole, even if @code{:start} is non-zero. The function
3942 returns @code{nil} if no matching element was found.
3945 @defun cl-count item seq @t{&key :test :test-not :key :start :end}
3946 This function returns the number of elements of @var{seq} which
3947 match @var{item}. The result is always a nonnegative integer.
3951 @findex cl-find-if-not
3952 @findex cl-position-if
3953 @findex cl-position-if-not
3955 @findex cl-count-if-not
3956 The @code{cl-find-if}, @code{cl-find-if-not}, @code{cl-position-if},
3957 @code{cl-position-if-not}, @code{cl-count-if}, and @code{cl-count-if-not}
3958 functions are defined similarly.
3960 @defun cl-mismatch seq1 seq2 @t{&key :test :test-not :key :start1 :end1 :start2 :end2 :from-end}
3961 This function compares the specified parts of @var{seq1} and
3962 @var{seq2}. If they are the same length and the corresponding
3963 elements match (according to @code{:test}, @code{:test-not},
3964 and @code{:key}), the function returns @code{nil}. If there is
3965 a mismatch, the function returns the index (relative to @var{seq1})
3966 of the first mismatching element. This will be the leftmost pair of
3967 elements which do not match, or the position at which the shorter of
3968 the two otherwise-matching sequences runs out.
3970 If @code{:from-end} is true, then the elements are compared from right
3971 to left starting at @code{(1- @var{end1})} and @code{(1- @var{end2})}.
3972 If the sequences differ, then one plus the index of the rightmost
3973 difference (relative to @var{seq1}) is returned.
3975 An interesting example is @code{(cl-mismatch str1 str2 :key 'upcase)},
3976 which compares two strings case-insensitively.
3979 @defun cl-search seq1 seq2 @t{&key :test :test-not :key :from-end :start1 :end1 :start2 :end2}
3980 This function searches @var{seq2} for a subsequence that matches
3981 @var{seq1} (or part of it specified by @code{:start1} and
3982 @code{:end1}.) Only matches which fall entirely within the region
3983 defined by @code{:start2} and @code{:end2} will be considered.
3984 The return value is the index of the leftmost element of the
3985 leftmost match, relative to the start of @var{seq2}, or @code{nil}
3986 if no matches were found. If @code{:from-end} is true, the
3987 function finds the @emph{rightmost} matching subsequence.
3990 @node Sorting Sequences
3991 @section Sorting Sequences
3993 @defun clsort seq predicate @t{&key :key}
3994 This function sorts @var{seq} into increasing order as determined
3995 by using @var{predicate} to compare pairs of elements. @var{predicate}
3996 should return true (non-@code{nil}) if and only if its first argument
3997 is less than (not equal to) its second argument. For example,
3998 @code{<} and @code{string-lessp} are suitable predicate functions
3999 for sorting numbers and strings, respectively; @code{>} would sort
4000 numbers into decreasing rather than increasing order.
4002 This function differs from Emacs's built-in @code{sort} in that it
4003 can operate on any type of sequence, not just lists. Also, it
4004 accepts a @code{:key} argument which is used to preprocess data
4005 fed to the @var{predicate} function. For example,
4008 (setq data (cl-sort data 'string-lessp :key 'downcase))
4012 sorts @var{data}, a sequence of strings, into increasing alphabetical
4013 order without regard to case. A @code{:key} function of @code{car}
4014 would be useful for sorting association lists. It should only be a
4015 simple accessor though, it's used heavily in the current
4018 The @code{cl-sort} function is destructive; it sorts lists by actually
4019 rearranging the @code{cdr} pointers in suitable fashion.
4022 @defun cl-stable-sort seq predicate @t{&key :key}
4023 This function sorts @var{seq} @dfn{stably}, meaning two elements
4024 which are equal in terms of @var{predicate} are guaranteed not to
4025 be rearranged out of their original order by the sort.
4027 In practice, @code{cl-sort} and @code{cl-stable-sort} are equivalent
4028 in Emacs Lisp because the underlying @code{sort} function is
4029 stable by default. However, this package reserves the right to
4030 use non-stable methods for @code{cl-sort} in the future.
4033 @defun cl-merge type seq1 seq2 predicate @t{&key :key}
4034 This function merges two sequences @var{seq1} and @var{seq2} by
4035 interleaving their elements. The result sequence, of type @var{type}
4036 (in the sense of @code{cl-concatenate}), has length equal to the sum
4037 of the lengths of the two input sequences. The sequences may be
4038 modified destructively. Order of elements within @var{seq1} and
4039 @var{seq2} is preserved in the interleaving; elements of the two
4040 sequences are compared by @var{predicate} (in the sense of
4041 @code{sort}) and the lesser element goes first in the result.
4042 When elements are equal, those from @var{seq1} precede those from
4043 @var{seq2} in the result. Thus, if @var{seq1} and @var{seq2} are
4044 both sorted according to @var{predicate}, then the result will be
4045 a merged sequence which is (stably) sorted according to
4053 The functions described here operate on lists.
4056 * List Functions:: @code{cl-caddr}, @code{cl-first}, @code{cl-list*}, etc.
4057 * Substitution of Expressions:: @code{cl-subst}, @code{cl-sublis}, etc.
4058 * Lists as Sets:: @code{cl-member}, @code{cl-adjoin}, @code{cl-union}, etc.
4059 * Association Lists:: @code{cl-assoc}, @code{cl-rassoc}, @code{cl-acons}, @code{cl-pairlis}.
4062 @node List Functions
4063 @section List Functions
4066 This section describes a number of simple operations on lists,
4067 i.e., chains of cons cells.
4070 This function is equivalent to @code{(car (cdr (cdr @var{x})))}.
4071 Likewise, this package defines all 28 @code{c@var{xxx}r} functions
4072 where @var{xxx} is up to four @samp{a}s and/or @samp{d}s.
4073 All of these functions are @code{setf}-able, and calls to them
4074 are expanded inline by the byte-compiler for maximum efficiency.
4078 This function is a synonym for @code{(car @var{x})}. Likewise,
4079 the functions @code{cl-second}, @code{cl-third}, @dots{}, through
4080 @code{cl-tenth} return the given element of the list @var{x}.
4084 This function is a synonym for @code{(cdr @var{x})}.
4088 Common Lisp defines this function to act like @code{null}, but
4089 signaling an error if @code{x} is neither a @code{nil} nor a
4090 cons cell. This package simply defines @code{cl-endp} as a synonym
4094 @defun cl-list-length x
4095 This function returns the length of list @var{x}, exactly like
4096 @code{(length @var{x})}, except that if @var{x} is a circular
4097 list (where the cdr-chain forms a loop rather than terminating
4098 with @code{nil}), this function returns @code{nil}. (The regular
4099 @code{length} function would get stuck if given a circular list.)
4102 @defun cl-list* arg &rest others
4103 This function constructs a list of its arguments. The final
4104 argument becomes the @code{cdr} of the last cell constructed.
4105 Thus, @code{(cl-list* @var{a} @var{b} @var{c})} is equivalent to
4106 @code{(cons @var{a} (cons @var{b} @var{c}))}, and
4107 @code{(cl-list* @var{a} @var{b} nil)} is equivalent to
4108 @code{(list @var{a} @var{b})}.
4111 @defun cl-ldiff list sublist
4112 If @var{sublist} is a sublist of @var{list}, i.e., is @code{eq} to
4113 one of the cons cells of @var{list}, then this function returns
4114 a copy of the part of @var{list} up to but not including
4115 @var{sublist}. For example, @code{(cl-ldiff x (cddr x))} returns
4116 the first two elements of the list @code{x}. The result is a
4117 copy; the original @var{list} is not modified. If @var{sublist}
4118 is not a sublist of @var{list}, a copy of the entire @var{list}
4122 @defun cl-copy-list list
4123 This function returns a copy of the list @var{list}. It copies
4124 dotted lists like @code{(1 2 . 3)} correctly.
4127 @defun copy-tree x &optional vecp
4128 This function returns a copy of the tree of cons cells @var{x}.
4129 @c FIXME? cl-copy-list is not an alias of copy-sequence.
4130 Unlike @code{copy-sequence} (and its alias @code{cl-copy-list}),
4131 which copies only along the @code{cdr} direction, this function
4132 copies (recursively) along both the @code{car} and the @code{cdr}
4133 directions. If @var{x} is not a cons cell, the function simply
4134 returns @var{x} unchanged. If the optional @var{vecp} argument
4135 is true, this function copies vectors (recursively) as well as
4139 @defun cl-tree-equal x y @t{&key :test :test-not :key}
4140 This function compares two trees of cons cells. If @var{x} and
4141 @var{y} are both cons cells, their @code{car}s and @code{cdr}s are
4142 compared recursively. If neither @var{x} nor @var{y} is a cons
4143 cell, they are compared by @code{eql}, or according to the
4144 specified test. The @code{:key} function, if specified, is
4145 applied to the elements of both trees. @xref{Sequences}.
4152 @node Substitution of Expressions
4153 @section Substitution of Expressions
4156 These functions substitute elements throughout a tree of cons
4157 cells. (@xref{Sequence Functions}, for the @code{cl-substitute}
4158 function, which works on just the top-level elements of a list.)
4160 @defun cl-subst new old tree @t{&key :test :test-not :key}
4161 This function substitutes occurrences of @var{old} with @var{new}
4162 in @var{tree}, a tree of cons cells. It returns a substituted
4163 tree, which will be a copy except that it may share storage with
4164 the argument @var{tree} in parts where no substitutions occurred.
4165 The original @var{tree} is not modified. This function recurses
4166 on, and compares against @var{old}, both @code{car}s and @code{cdr}s
4167 of the component cons cells. If @var{old} is itself a cons cell,
4168 then matching cells in the tree are substituted as usual without
4169 recursively substituting in that cell. Comparisons with @var{old}
4170 are done according to the specified test (@code{eql} by default).
4171 The @code{:key} function is applied to the elements of the tree
4172 but not to @var{old}.
4175 @defun cl-nsubst new old tree @t{&key :test :test-not :key}
4176 This function is like @code{cl-subst}, except that it works by
4177 destructive modification (by @code{setcar} or @code{setcdr})
4178 rather than copying.
4182 @findex cl-subst-if-not
4183 @findex cl-nsubst-if
4184 @findex cl-nsubst-if-not
4185 The @code{cl-subst-if}, @code{cl-subst-if-not}, @code{cl-nsubst-if}, and
4186 @code{cl-nsubst-if-not} functions are defined similarly.
4188 @defun cl-sublis alist tree @t{&key :test :test-not :key}
4189 This function is like @code{cl-subst}, except that it takes an
4190 association list @var{alist} of @var{old}-@var{new} pairs.
4191 Each element of the tree (after applying the @code{:key}
4192 function, if any), is compared with the @code{car}s of
4193 @var{alist}; if it matches, it is replaced by the corresponding
4197 @defun cl-nsublis alist tree @t{&key :test :test-not :key}
4198 This is a destructive version of @code{cl-sublis}.
4202 @section Lists as Sets
4205 These functions perform operations on lists which represent sets
4208 @defun cl-member item list @t{&key :test :test-not :key}
4209 This function searches @var{list} for an element matching @var{item}.
4210 If a match is found, it returns the cons cell whose @code{car} was
4211 the matching element. Otherwise, it returns @code{nil}. Elements
4212 are compared by @code{eql} by default; you can use the @code{:test},
4213 @code{:test-not}, and @code{:key} arguments to modify this behavior.
4216 The standard Emacs lisp function @code{member} uses @code{equal} for
4217 comparisons; it is equivalent to @code{(cl-member @var{item} @var{list}
4221 @findex cl-member-if
4222 @findex cl-member-if-not
4223 The @code{cl-member-if} and @code{cl-member-if-not} functions
4224 analogously search for elements which satisfy a given predicate.
4226 @defun cl-tailp sublist list
4227 This function returns @code{t} if @var{sublist} is a sublist of
4228 @var{list}, i.e., if @var{sublist} is @code{eql} to @var{list} or to
4229 any of its @code{cdr}s.
4232 @defun cl-adjoin item list @t{&key :test :test-not :key}
4233 This function conses @var{item} onto the front of @var{list},
4234 like @code{(cons @var{item} @var{list})}, but only if @var{item}
4235 is not already present on the list (as determined by @code{cl-member}).
4236 If a @code{:key} argument is specified, it is applied to
4237 @var{item} as well as to the elements of @var{list} during
4238 the search, on the reasoning that @var{item} is ``about'' to
4239 become part of the list.
4242 @defun cl-union list1 list2 @t{&key :test :test-not :key}
4243 This function combines two lists which represent sets of items,
4244 returning a list that represents the union of those two sets.
4245 The result list will contain all items which appear in @var{list1}
4246 or @var{list2}, and no others. If an item appears in both
4247 @var{list1} and @var{list2} it will be copied only once. If
4248 an item is duplicated in @var{list1} or @var{list2}, it is
4249 undefined whether or not that duplication will survive in the
4250 result list. The order of elements in the result list is also
4254 @defun cl-nunion list1 list2 @t{&key :test :test-not :key}
4255 This is a destructive version of @code{cl-union}; rather than copying,
4256 it tries to reuse the storage of the argument lists if possible.
4259 @defun cl-intersection list1 list2 @t{&key :test :test-not :key}
4260 This function computes the intersection of the sets represented
4261 by @var{list1} and @var{list2}. It returns the list of items
4262 which appear in both @var{list1} and @var{list2}.
4265 @defun cl-nintersection list1 list2 @t{&key :test :test-not :key}
4266 This is a destructive version of @code{cl-intersection}. It
4267 tries to reuse storage of @var{list1} rather than copying.
4268 It does @emph{not} reuse the storage of @var{list2}.
4271 @defun cl-set-difference list1 list2 @t{&key :test :test-not :key}
4272 This function computes the ``set difference'' of @var{list1}
4273 and @var{list2}, i.e., the set of elements that appear in
4274 @var{list1} but @emph{not} in @var{list2}.
4277 @defun cl-nset-difference list1 list2 @t{&key :test :test-not :key}
4278 This is a destructive @code{cl-set-difference}, which will try
4279 to reuse @var{list1} if possible.
4282 @defun cl-set-exclusive-or list1 list2 @t{&key :test :test-not :key}
4283 This function computes the ``set exclusive or'' of @var{list1}
4284 and @var{list2}, i.e., the set of elements that appear in
4285 exactly one of @var{list1} and @var{list2}.
4288 @defun cl-nset-exclusive-or list1 list2 @t{&key :test :test-not :key}
4289 This is a destructive @code{cl-set-exclusive-or}, which will try
4290 to reuse @var{list1} and @var{list2} if possible.
4293 @defun cl-subsetp list1 list2 @t{&key :test :test-not :key}
4294 This function checks whether @var{list1} represents a subset
4295 of @var{list2}, i.e., whether every element of @var{list1}
4296 also appears in @var{list2}.
4299 @node Association Lists
4300 @section Association Lists
4303 An @dfn{association list} is a list representing a mapping from
4304 one set of values to another; any list whose elements are cons
4305 cells is an association list.
4307 @defun cl-assoc item a-list @t{&key :test :test-not :key}
4308 This function searches the association list @var{a-list} for an
4309 element whose @code{car} matches (in the sense of @code{:test},
4310 @code{:test-not}, and @code{:key}, or by comparison with @code{eql})
4311 a given @var{item}. It returns the matching element, if any,
4312 otherwise @code{nil}. It ignores elements of @var{a-list} which
4313 are not cons cells. (This corresponds to the behavior of
4314 @code{assq} and @code{assoc} in Emacs Lisp; Common Lisp's
4315 @code{assoc} ignores @code{nil}s but considers any other non-cons
4316 elements of @var{a-list} to be an error.)
4319 @defun cl-rassoc item a-list @t{&key :test :test-not :key}
4320 This function searches for an element whose @code{cdr} matches
4321 @var{item}. If @var{a-list} represents a mapping, this applies
4322 the inverse of the mapping to @var{item}.
4326 @findex cl-assoc-if-not
4327 @findex cl-rassoc-if
4328 @findex cl-rassoc-if-not
4329 The @code{cl-assoc-if}, @code{cl-assoc-if-not}, @code{cl-rassoc-if},
4330 and @code{cl-rassoc-if-not} functions are defined similarly.
4332 Two simple functions for constructing association lists are:
4334 @defun cl-acons key value alist
4335 This is equivalent to @code{(cons (cons @var{key} @var{value}) @var{alist})}.
4338 @defun cl-pairlis keys values &optional alist
4339 This is equivalent to @code{(nconc (cl-mapcar 'cons @var{keys} @var{values})
4347 The Common Lisp @dfn{structure} mechanism provides a general way
4348 to define data types similar to C's @code{struct} types. A
4349 structure is a Lisp object containing some number of @dfn{slots},
4350 each of which can hold any Lisp data object. Functions are
4351 provided for accessing and setting the slots, creating or copying
4352 structure objects, and recognizing objects of a particular structure
4355 In true Common Lisp, each structure type is a new type distinct
4356 from all existing Lisp types. Since the underlying Emacs Lisp
4357 system provides no way to create new distinct types, this package
4358 implements structures as vectors (or lists upon request) with a
4359 special ``tag'' symbol to identify them.
4361 @defspec cl-defstruct name slots@dots{}
4362 The @code{cl-defstruct} form defines a new structure type called
4363 @var{name}, with the specified @var{slots}. (The @var{slots}
4364 may begin with a string which documents the structure type.)
4365 In the simplest case, @var{name} and each of the @var{slots}
4366 are symbols. For example,
4369 (cl-defstruct person name age sex)
4373 defines a struct type called @code{person} which contains three
4374 slots. Given a @code{person} object @var{p}, you can access those
4375 slots by calling @code{(person-name @var{p})}, @code{(person-age @var{p})},
4376 and @code{(person-sex @var{p})}. You can also change these slots by
4377 using @code{setf} on any of these place forms:
4380 (cl-incf (person-age birthday-boy))
4383 You can create a new @code{person} by calling @code{make-person},
4384 which takes keyword arguments @code{:name}, @code{:age}, and
4385 @code{:sex} to specify the initial values of these slots in the
4386 new object. (Omitting any of these arguments leaves the corresponding
4387 slot ``undefined,'' according to the Common Lisp standard; in Emacs
4388 Lisp, such uninitialized slots are filled with @code{nil}.)
4390 Given a @code{person}, @code{(copy-person @var{p})} makes a new
4391 object of the same type whose slots are @code{eq} to those of @var{p}.
4393 Given any Lisp object @var{x}, @code{(person-p @var{x})} returns
4394 true if @var{x} looks like a @code{person}, false otherwise. (Again,
4395 in Common Lisp this predicate would be exact; in Emacs Lisp the
4396 best it can do is verify that @var{x} is a vector of the correct
4397 length which starts with the correct tag symbol.)
4399 Accessors like @code{person-name} normally check their arguments
4400 (effectively using @code{person-p}) and signal an error if the
4401 argument is the wrong type. This check is affected by
4402 @code{(optimize (safety @dots{}))} declarations. Safety level 1,
4403 the default, uses a somewhat optimized check that will detect all
4404 incorrect arguments, but may use an uninformative error message
4405 (e.g., ``expected a vector'' instead of ``expected a @code{person}'').
4406 Safety level 0 omits all checks except as provided by the underlying
4407 @code{aref} call; safety levels 2 and 3 do rigorous checking that will
4408 always print a descriptive error message for incorrect inputs.
4409 @xref{Declarations}.
4412 (setq dave (make-person :name "Dave" :sex 'male))
4413 @result{} [cl-struct-person "Dave" nil male]
4414 (setq other (copy-person dave))
4415 @result{} [cl-struct-person "Dave" nil male]
4418 (eq (person-name dave) (person-name other))
4422 (person-p [1 2 3 4])
4426 (person-p '[cl-struct-person counterfeit person object])
4430 In general, @var{name} is either a name symbol or a list of a name
4431 symbol followed by any number of @dfn{struct options}; each @var{slot}
4432 is either a slot symbol or a list of the form @samp{(@var{slot-name}
4433 @var{default-value} @var{slot-options}@dots{})}. The @var{default-value}
4434 is a Lisp form which is evaluated any time an instance of the
4435 structure type is created without specifying that slot's value.
4437 Common Lisp defines several slot options, but the only one
4438 implemented in this package is @code{:read-only}. A non-@code{nil}
4439 value for this option means the slot should not be @code{setf}-able;
4440 the slot's value is determined when the object is created and does
4441 not change afterward.
4444 (cl-defstruct person
4445 (name nil :read-only t)
4450 Any slot options other than @code{:read-only} are ignored.
4452 For obscure historical reasons, structure options take a different
4453 form than slot options. A structure option is either a keyword
4454 symbol, or a list beginning with a keyword symbol possibly followed
4455 by arguments. (By contrast, slot options are key-value pairs not
4459 (cl-defstruct (person (:constructor create-person)
4465 The following structure options are recognized.
4470 @advance@leftskip-.5@tableindent
4473 The argument is a symbol whose print name is used as the prefix for
4474 the names of slot accessor functions. The default is the name of
4475 the struct type followed by a hyphen. The option @code{(:conc-name p-)}
4476 would change this prefix to @code{p-}. Specifying @code{nil} as an
4477 argument means no prefix, so that the slot names themselves are used
4478 to name the accessor functions.
4481 In the simple case, this option takes one argument which is an
4482 alternate name to use for the constructor function. The default
4483 is @code{make-@var{name}}, e.g., @code{make-person}. The above
4484 example changes this to @code{create-person}. Specifying @code{nil}
4485 as an argument means that no standard constructor should be
4488 In the full form of this option, the constructor name is followed
4489 by an arbitrary argument list. @xref{Program Structure}, for a
4490 description of the format of Common Lisp argument lists. All
4491 options, such as @code{&rest} and @code{&key}, are supported.
4492 The argument names should match the slot names; each slot is
4493 initialized from the corresponding argument. Slots whose names
4494 do not appear in the argument list are initialized based on the
4495 @var{default-value} in their slot descriptor. Also, @code{&optional}
4496 and @code{&key} arguments which don't specify defaults take their
4497 defaults from the slot descriptor. It is valid to include arguments
4498 which don't correspond to slot names; these are useful if they are
4499 referred to in the defaults for optional, keyword, or @code{&aux}
4500 arguments which @emph{do} correspond to slots.
4502 You can specify any number of full-format @code{:constructor}
4503 options on a structure. The default constructor is still generated
4504 as well unless you disable it with a simple-format @code{:constructor}
4510 (:constructor nil) ; no default constructor
4511 (:constructor new-person (name sex &optional (age 0)))
4512 (:constructor new-hound (&key (name "Rover")
4514 &aux (age (* 7 dog-years))
4519 The first constructor here takes its arguments positionally rather
4520 than by keyword. (In official Common Lisp terminology, constructors
4521 that work By Order of Arguments instead of by keyword are called
4522 ``BOA constructors.'' No, I'm not making this up.) For example,
4523 @code{(new-person "Jane" 'female)} generates a person whose slots
4524 are @code{"Jane"}, 0, and @code{female}, respectively.
4526 The second constructor takes two keyword arguments, @code{:name},
4527 which initializes the @code{name} slot and defaults to @code{"Rover"},
4528 and @code{:dog-years}, which does not itself correspond to a slot
4529 but which is used to initialize the @code{age} slot. The @code{sex}
4530 slot is forced to the symbol @code{canine} with no syntax for
4534 The argument is an alternate name for the copier function for
4535 this type. The default is @code{copy-@var{name}}. @code{nil}
4536 means not to generate a copier function. (In this implementation,
4537 all copier functions are simply synonyms for @code{copy-sequence}.)
4540 The argument is an alternate name for the predicate which recognizes
4541 objects of this type. The default is @code{@var{name}-p}. @code{nil}
4542 means not to generate a predicate function. (If the @code{:type}
4543 option is used without the @code{:named} option, no predicate is
4546 In true Common Lisp, @code{typep} is always able to recognize a
4547 structure object even if @code{:predicate} was used. In this
4548 package, @code{typep} simply looks for a function called
4549 @code{@var{typename}-p}, so it will work for structure types
4550 only if they used the default predicate name.
4553 This option implements a very limited form of C++-style inheritance.
4554 The argument is the name of another structure type previously
4555 created with @code{cl-defstruct}. The effect is to cause the new
4556 structure type to inherit all of the included structure's slots
4557 (plus, of course, any new slots described by this struct's slot
4558 descriptors). The new structure is considered a ``specialization''
4559 of the included one. In fact, the predicate and slot accessors
4560 for the included type will also accept objects of the new type.
4562 If there are extra arguments to the @code{:include} option after
4563 the included-structure name, these options are treated as replacement
4564 slot descriptors for slots in the included structure, possibly with
4565 modified default values. Borrowing an example from Steele:
4568 (cl-defstruct person name (age 0) sex)
4570 (cl-defstruct (astronaut (:include person (age 45)))
4572 (favorite-beverage 'tang))
4575 (setq joe (make-person :name "Joe"))
4576 @result{} [cl-struct-person "Joe" 0 nil]
4577 (setq buzz (make-astronaut :name "Buzz"))
4578 @result{} [cl-struct-astronaut "Buzz" 45 nil nil tang]
4580 (list (person-p joe) (person-p buzz))
4582 (list (astronaut-p joe) (astronaut-p buzz))
4587 (astronaut-name joe)
4588 @result{} error: "astronaut-name accessing a non-astronaut"
4591 Thus, if @code{astronaut} is a specialization of @code{person},
4592 then every @code{astronaut} is also a @code{person} (but not the
4593 other way around). Every @code{astronaut} includes all the slots
4594 of a @code{person}, plus extra slots that are specific to
4595 astronauts. Operations that work on people (like @code{person-name})
4596 work on astronauts just like other people.
4598 @item :print-function
4599 In full Common Lisp, this option allows you to specify a function
4600 which is called to print an instance of the structure type. The
4601 Emacs Lisp system offers no hooks into the Lisp printer which would
4602 allow for such a feature, so this package simply ignores
4603 @code{:print-function}.
4606 The argument should be one of the symbols @code{vector} or @code{list}.
4607 This tells which underlying Lisp data type should be used to implement
4608 the new structure type. Vectors are used by default, but
4609 @code{(:type list)} will cause structure objects to be stored as
4612 The vector representation for structure objects has the advantage
4613 that all structure slots can be accessed quickly, although creating
4614 vectors is a bit slower in Emacs Lisp. Lists are easier to create,
4615 but take a relatively long time accessing the later slots.
4618 This option, which takes no arguments, causes a characteristic ``tag''
4619 symbol to be stored at the front of the structure object. Using
4620 @code{:type} without also using @code{:named} will result in a
4621 structure type stored as plain vectors or lists with no identifying
4624 The default, if you don't specify @code{:type} explicitly, is to
4625 use named vectors. Therefore, @code{:named} is only useful in
4626 conjunction with @code{:type}.
4629 (cl-defstruct (person1) name age sex)
4630 (cl-defstruct (person2 (:type list) :named) name age sex)
4631 (cl-defstruct (person3 (:type list)) name age sex)
4633 (setq p1 (make-person1))
4634 @result{} [cl-struct-person1 nil nil nil]
4635 (setq p2 (make-person2))
4636 @result{} (person2 nil nil nil)
4637 (setq p3 (make-person3))
4638 @result{} (nil nil nil)
4645 @result{} error: function person3-p undefined
4648 Since unnamed structures don't have tags, @code{cl-defstruct} is not
4649 able to make a useful predicate for recognizing them. Also,
4650 accessors like @code{person3-name} will be generated but they
4651 will not be able to do any type checking. The @code{person3-name}
4652 function, for example, will simply be a synonym for @code{car} in
4653 this case. By contrast, @code{person2-name} is able to verify
4654 that its argument is indeed a @code{person2} object before
4657 @item :initial-offset
4658 The argument must be a nonnegative integer. It specifies a
4659 number of slots to be left ``empty'' at the front of the
4660 structure. If the structure is named, the tag appears at the
4661 specified position in the list or vector; otherwise, the first
4662 slot appears at that position. Earlier positions are filled
4663 with @code{nil} by the constructors and ignored otherwise. If
4664 the type @code{:include}s another type, then @code{:initial-offset}
4665 specifies a number of slots to be skipped between the last slot
4666 of the included type and the first new slot.
4670 Except as noted, the @code{cl-defstruct} facility of this package is
4671 entirely compatible with that of Common Lisp.
4674 @chapter Assertions and Errors
4677 This section describes two macros that test @dfn{assertions}, i.e.,
4678 conditions which must be true if the program is operating correctly.
4679 Assertions never add to the behavior of a Lisp program; they simply
4680 make ``sanity checks'' to make sure everything is as it should be.
4682 If the optimization property @code{speed} has been set to 3, and
4683 @code{safety} is less than 3, then the byte-compiler will optimize
4684 away the following assertions. Because assertions might be optimized
4685 away, it is a bad idea for them to include side-effects.
4687 @defspec cl-assert test-form [show-args string args@dots{}]
4688 This form verifies that @var{test-form} is true (i.e., evaluates to
4689 a non-@code{nil} value). If so, it returns @code{nil}. If the test
4690 is not satisfied, @code{cl-assert} signals an error.
4692 A default error message will be supplied which includes @var{test-form}.
4693 You can specify a different error message by including a @var{string}
4694 argument plus optional extra arguments. Those arguments are simply
4695 passed to @code{error} to signal the error.
4697 If the optional second argument @var{show-args} is @code{t} instead
4698 of @code{nil}, then the error message (with or without @var{string})
4699 will also include all non-constant arguments of the top-level
4700 @var{form}. For example:
4703 (cl-assert (> x 10) t "x is too small: %d")
4706 This usage of @var{show-args} is an extension to Common Lisp. In
4707 true Common Lisp, the second argument gives a list of @var{places}
4708 which can be @code{setf}'d by the user before continuing from the
4709 error. Since Emacs Lisp does not support continuable errors, it
4710 makes no sense to specify @var{places}.
4713 @defspec cl-check-type form type [string]
4714 This form verifies that @var{form} evaluates to a value of type
4715 @var{type}. If so, it returns @code{nil}. If not, @code{cl-check-type}
4716 signals a @code{wrong-type-argument} error. The default error message
4717 lists the erroneous value along with @var{type} and @var{form}
4718 themselves. If @var{string} is specified, it is included in the
4719 error message in place of @var{type}. For example:
4722 (cl-check-type x (integer 1 *) "a positive integer")
4725 @xref{Type Predicates}, for a description of the type specifiers
4726 that may be used for @var{type}.
4728 Note that in Common Lisp, the first argument to @code{check-type}
4729 must be a @var{place} suitable for use by @code{setf}, because
4730 @code{check-type} signals a continuable error that allows the
4731 user to modify @var{place}.
4734 @node Efficiency Concerns
4735 @appendix Efficiency Concerns
4740 Many of the advanced features of this package, such as @code{cl-defun},
4741 @code{cl-loop}, and @code{setf}, are implemented as Lisp macros. In
4742 byte-compiled code, these complex notations will be expanded into
4743 equivalent Lisp code which is simple and efficient. For example,
4752 are expanded at compile-time to the Lisp forms
4756 (setcar p (cons x (car p)))
4760 which are the most efficient ways of doing these respective operations
4761 in Lisp. Thus, there is no performance penalty for using the more
4762 readable @code{cl-incf} and @code{push} forms in your compiled code.
4764 @emph{Interpreted} code, on the other hand, must expand these macros
4765 every time they are executed. For this reason it is strongly
4766 recommended that code making heavy use of macros be compiled.
4767 (The features labeled ``Special Form'' instead of ``Function'' in
4768 this manual are macros.) A loop using @code{cl-incf} a hundred times
4769 will execute considerably faster if compiled, and will also
4770 garbage-collect less because the macro expansion will not have
4771 to be generated, used, and thrown away a hundred times.
4773 You can find out how a macro expands by using the
4774 @code{cl-prettyexpand} function.
4776 @defun cl-prettyexpand form &optional full
4777 This function takes a single Lisp form as an argument and inserts
4778 a nicely formatted copy of it in the current buffer (which must be
4779 in Lisp mode so that indentation works properly). It also expands
4780 all Lisp macros which appear in the form. The easiest way to use
4781 this function is to go to the @code{*scratch*} buffer and type, say,
4784 (cl-prettyexpand '(loop for x below 10 collect x))
4788 and type @kbd{C-x C-e} immediately after the closing parenthesis;
4796 (setq G1004 (cons x G1004))
4802 will be inserted into the buffer. (The @code{cl-block} macro is
4803 expanded differently in the interpreter and compiler, so
4804 @code{cl-prettyexpand} just leaves it alone. The temporary
4805 variable @code{G1004} was created by @code{cl-gensym}.)
4807 If the optional argument @var{full} is true, then @emph{all}
4808 macros are expanded, including @code{cl-block}, @code{cl-eval-when},
4809 and compiler macros. Expansion is done as if @var{form} were
4810 a top-level form in a file being compiled. For example,
4813 (cl-prettyexpand '(cl-pushnew 'x list))
4814 @print{} (setq list (cl-adjoin 'x list))
4815 (cl-prettyexpand '(cl-pushnew 'x list) t)
4816 @print{} (setq list (if (memq 'x list) list (cons 'x list)))
4817 (cl-prettyexpand '(caddr (cl-member 'a list)) t)
4818 @print{} (car (cdr (cdr (memq 'a list))))
4821 Note that @code{cl-adjoin}, @code{cl-caddr}, and @code{cl-member} all
4822 have built-in compiler macros to optimize them in common cases.
4830 @appendixsec Error Checking
4833 Common Lisp compliance has in general not been sacrificed for the
4834 sake of efficiency. A few exceptions have been made for cases
4835 where substantial gains were possible at the expense of marginal
4838 The Common Lisp standard (as embodied in Steele's book) uses the
4839 phrase ``it is an error if'' to indicate a situation which is not
4840 supposed to arise in complying programs; implementations are strongly
4841 encouraged but not required to signal an error in these situations.
4842 This package sometimes omits such error checking in the interest of
4843 compactness and efficiency. For example, @code{cl-do} variable
4844 specifiers are supposed to be lists of one, two, or three forms;
4845 extra forms are ignored by this package rather than signaling a
4846 syntax error. The @code{cl-endp} function is simply a synonym for
4847 @code{null} in this package. Functions taking keyword arguments
4848 will accept an odd number of arguments, treating the trailing
4849 keyword as if it were followed by the value @code{nil}.
4851 Argument lists (as processed by @code{cl-defun} and friends)
4852 @emph{are} checked rigorously except for the minor point just
4853 mentioned; in particular, keyword arguments are checked for
4854 validity, and @code{&allow-other-keys} and @code{:allow-other-keys}
4855 are fully implemented. Keyword validity checking is slightly
4856 time consuming (though not too bad in byte-compiled code);
4857 you can use @code{&allow-other-keys} to omit this check. Functions
4858 defined in this package such as @code{cl-find} and @code{cl-member}
4859 do check their keyword arguments for validity.
4866 @appendixsec Optimizing Compiler
4869 Use of the optimizing Emacs compiler is highly recommended; many of the Common
4871 code which can be improved by optimization. In particular,
4872 @code{cl-block}s (whether explicit or implicit in constructs like
4873 @code{cl-defun} and @code{cl-loop}) carry a fair run-time penalty; the
4874 optimizing compiler removes @code{cl-block}s which are not actually
4875 referenced by @code{cl-return} or @code{cl-return-from} inside the block.
4877 @node Common Lisp Compatibility
4878 @appendix Common Lisp Compatibility
4881 Following is a list of all known incompatibilities between this
4882 package and Common Lisp as documented in Steele (2nd edition).
4885 Certain function names, such as @code{member}, @code{assoc}, and
4886 @code{floor}, were already taken by (incompatible) Emacs Lisp
4887 functions; this package appends @samp{*} to the names of its
4888 Common Lisp versions of these functions.
4891 The word @code{cl-defun} is required instead of @code{defun} in order
4892 to use extended Common Lisp argument lists in a function. Likewise,
4893 @code{cl-defmacro} and @code{cl-function} are versions of those forms
4894 which understand full-featured argument lists. The @code{&whole}
4895 keyword does not work in @code{defmacro} argument lists (except
4896 inside recursive argument lists).
4898 The @code{equal} predicate does not distinguish
4899 between IEEE floating-point plus and minus zero. The @code{cl-equalp}
4900 predicate has several differences with Common Lisp; @pxref{Predicates}.
4902 The @code{setf} mechanism is entirely compatible, except that
4903 setf-methods return a list of five values rather than five
4904 values directly. Also, the new ``@code{setf} function'' concept
4905 (typified by @code{(defun (setf foo) @dots{})}) is not implemented.
4907 The @code{cl-do-all-symbols} form is the same as @code{cl-do-symbols}
4908 with no @var{obarray} argument. In Common Lisp, this form would
4909 iterate over all symbols in all packages. Since Emacs obarrays
4910 are not a first-class package mechanism, there is no way for
4911 @code{cl-do-all-symbols} to locate any but the default obarray.
4913 The @code{cl-loop} macro is complete except that @code{loop-finish}
4914 and type specifiers are unimplemented.
4916 The multiple-value return facility treats lists as multiple
4917 values, since Emacs Lisp cannot support multiple return values
4918 directly. The macros will be compatible with Common Lisp if
4919 @code{values} or @code{values-list} is always used to return to
4920 a @code{cl-multiple-value-bind} or other multiple-value receiver;
4921 if @code{values} is used without @code{cl-multiple-value-@dots{}}
4922 or vice-versa the effect will be different from Common Lisp.
4924 Many Common Lisp declarations are ignored, and others match
4925 the Common Lisp standard in concept but not in detail. For
4926 example, local @code{special} declarations, which are purely
4927 advisory in Emacs Lisp, do not rigorously obey the scoping rules
4928 set down in Steele's book.
4930 The variable @code{cl--gensym-counter} starts out with a pseudo-random
4931 value rather than with zero. This is to cope with the fact that
4932 generated symbols become interned when they are written to and
4933 loaded back from a file.
4935 The @code{cl-defstruct} facility is compatible, except that structures
4936 are of type @code{:type vector :named} by default rather than some
4937 special, distinct type. Also, the @code{:type} slot option is ignored.
4939 The second argument of @code{cl-check-type} is treated differently.
4941 @node Porting Common Lisp
4942 @appendix Porting Common Lisp
4945 This package is meant to be used as an extension to Emacs Lisp,
4946 not as an Emacs implementation of true Common Lisp. Some of the
4947 remaining differences between Emacs Lisp and Common Lisp make it
4948 difficult to port large Common Lisp applications to Emacs. For
4949 one, some of the features in this package are not fully compliant
4950 with ANSI or Steele; @pxref{Common Lisp Compatibility}. But there
4951 are also quite a few features that this package does not provide
4952 at all. Here are some major omissions that you will want to watch out
4953 for when bringing Common Lisp code into Emacs.
4957 Case-insensitivity. Symbols in Common Lisp are case-insensitive
4958 by default. Some programs refer to a function or variable as
4959 @code{foo} in one place and @code{Foo} or @code{FOO} in another.
4960 Emacs Lisp will treat these as three distinct symbols.
4962 Some Common Lisp code is written entirely in upper case. While Emacs
4963 is happy to let the program's own functions and variables use
4964 this convention, calls to Lisp builtins like @code{if} and
4965 @code{defun} will have to be changed to lower case.
4968 Lexical scoping. In Common Lisp, function arguments and @code{let}
4969 bindings apply only to references physically within their bodies
4970 (or within macro expansions in their bodies). Emacs Lisp, by
4971 contrast, uses @dfn{dynamic scoping} wherein a binding to a
4972 variable is visible even inside functions called from the body.
4974 Variables in Common Lisp can be made dynamically scoped by
4975 declaring them @code{special} or using @code{defvar}. In Emacs
4976 Lisp it is as if all variables were declared @code{special}.
4978 Often you can use code that was written for lexical scoping
4979 even in a dynamically scoped Lisp, but not always. Here is
4980 an example of a Common Lisp code fragment that would fail in
4984 (defun map-odd-elements (func list)
4986 for flag = t then (not flag)
4987 collect (if flag x (funcall func x))))
4989 (defun add-odd-elements (list x)
4990 (map-odd-elements (lambda (a) (+ a x)) list))
4994 In Common Lisp, the two functions' usages of @code{x} are completely
4995 independent. In Emacs Lisp, the binding to @code{x} made by
4996 @code{add-odd-elements} will have been hidden by the binding
4997 in @code{map-odd-elements} by the time the @code{(+ a x)} function
5000 (This package avoids such problems in its own mapping functions
5001 by using names like @code{cl-x} instead of @code{x} internally;
5002 as long as you don't use the @code{cl-} prefix for your own
5003 variables no collision can occur.)
5005 @xref{Lexical Bindings}, for a description of the @code{lexical-let}
5006 form which establishes a Common Lisp-style lexical binding, and some
5007 examples of how it differs from Emacs's regular @code{let}.
5010 Reader macros. Common Lisp includes a second type of macro that
5011 works at the level of individual characters. For example, Common
5012 Lisp implements the quote notation by a reader macro called @code{'},
5013 whereas Emacs Lisp's parser just treats quote as a special case.
5014 Some Lisp packages use reader macros to create special syntaxes
5015 for themselves, which the Emacs parser is incapable of reading.
5018 Other syntactic features. Common Lisp provides a number of
5019 notations beginning with @code{#} that the Emacs Lisp parser
5020 won't understand. For example, @samp{#| ... |#} is an
5021 alternate comment notation, and @samp{#+lucid (foo)} tells
5022 the parser to ignore the @code{(foo)} except in Lucid Common
5026 Packages. In Common Lisp, symbols are divided into @dfn{packages}.
5027 Symbols that are Lisp built-ins are typically stored in one package;
5028 symbols that are vendor extensions are put in another, and each
5029 application program would have a package for its own symbols.
5030 Certain symbols are ``exported'' by a package and others are
5031 internal; certain packages ``use'' or import the exported symbols
5032 of other packages. To access symbols that would not normally be
5033 visible due to this importing and exporting, Common Lisp provides
5034 a syntax like @code{package:symbol} or @code{package::symbol}.
5036 Emacs Lisp has a single namespace for all interned symbols, and
5037 then uses a naming convention of putting a prefix like @code{cl-}
5038 in front of the name. Some Emacs packages adopt the Common Lisp-like
5039 convention of using @code{cl:} or @code{cl::} as the prefix.
5040 However, the Emacs parser does not understand colons and just
5041 treats them as part of the symbol name. Thus, while @code{mapcar}
5042 and @code{lisp:mapcar} may refer to the same symbol in Common
5043 Lisp, they are totally distinct in Emacs Lisp. Common Lisp
5044 programs which refer to a symbol by the full name sometimes
5045 and the short name other times will not port cleanly to Emacs.
5047 Emacs Lisp does have a concept of ``obarrays,'' which are
5048 package-like collections of symbols, but this feature is not
5049 strong enough to be used as a true package mechanism.
5052 The @code{format} function is quite different between Common
5053 Lisp and Emacs Lisp. It takes an additional ``destination''
5054 argument before the format string. A destination of @code{nil}
5055 means to format to a string as in Emacs Lisp; a destination
5056 of @code{t} means to write to the terminal (similar to
5057 @code{message} in Emacs). Also, format control strings are
5058 utterly different; @code{~} is used instead of @code{%} to
5059 introduce format codes, and the set of available codes is
5060 much richer. There are no notations like @code{\n} for
5061 string literals; instead, @code{format} is used with the
5062 ``newline'' format code, @code{~%}. More advanced formatting
5063 codes provide such features as paragraph filling, case
5064 conversion, and even loops and conditionals.
5066 While it would have been possible to implement most of Common
5067 Lisp @code{format} in this package (under the name @code{format*},
5068 of course), it was not deemed worthwhile. It would have required
5069 a huge amount of code to implement even a decent subset of
5070 @code{format*}, yet the functionality it would provide over
5071 Emacs Lisp's @code{format} would rarely be useful.
5074 Vector constants use square brackets in Emacs Lisp, but
5075 @code{#(a b c)} notation in Common Lisp. To further complicate
5076 matters, Emacs has its own @code{#(} notation for
5077 something entirely different---strings with properties.
5080 Characters are distinct from integers in Common Lisp. The notation
5081 for character constants is also different: @code{#\A} in Common Lisp
5082 where Emacs Lisp uses @code{?A}. Also, @code{string=} and
5083 @code{string-equal} are synonyms in Emacs Lisp, whereas the latter is
5084 case-insensitive in Common Lisp.
5087 Data types. Some Common Lisp data types do not exist in Emacs
5088 Lisp. Rational numbers and complex numbers are not present,
5089 nor are large integers (all integers are ``fixnums''). All
5090 arrays are one-dimensional. There are no readtables or pathnames;
5091 streams are a set of existing data types rather than a new data
5092 type of their own. Hash tables, random-states, structures, and
5093 packages (obarrays) are built from Lisp vectors or lists rather
5094 than being distinct types.
5097 The Common Lisp Object System (CLOS) is not implemented,
5098 nor is the Common Lisp Condition System. However, the EIEIO package
5099 (@pxref{Top, , Introduction, eieio, EIEIO}) does implement some
5103 Common Lisp features that are completely redundant with Emacs
5104 Lisp features of a different name generally have not been
5105 implemented. For example, Common Lisp writes @code{defconstant}
5106 where Emacs Lisp uses @code{defconst}. Similarly, @code{make-list}
5107 takes its arguments in different ways in the two Lisps but does
5108 exactly the same thing, so this package has not bothered to
5109 implement a Common Lisp-style @code{make-list}.
5112 A few more notable Common Lisp features not included in this
5113 package: @code{compiler-let}, @code{tagbody}, @code{prog},
5114 @code{ldb/dpb}, @code{parse-integer}, @code{cerror}.
5117 Recursion. While recursion works in Emacs Lisp just like it
5118 does in Common Lisp, various details of the Emacs Lisp system
5119 and compiler make recursion much less efficient than it is in
5120 most Lisps. Some schools of thought prefer to use recursion
5121 in Lisp over other techniques; they would sum a list of
5122 numbers using something like
5125 (defun sum-list (list)
5127 (+ (car list) (sum-list (cdr list)))
5132 where a more iteratively-minded programmer might write one of
5136 (let ((total 0)) (dolist (x my-list) (cl-incf total x)) total)
5137 (loop for x in my-list sum x)
5140 While this would be mainly a stylistic choice in most Common Lisps,
5141 in Emacs Lisp you should be aware that the iterative forms are
5142 much faster than recursion. Also, Lisp programmers will want to
5143 note that the current Emacs Lisp compiler does not optimize tail
5147 @node GNU Free Documentation License
5148 @appendix GNU Free Documentation License
5149 @include doclicense.texi
5151 @node Function Index
5152 @unnumbered Function Index
5156 @node Variable Index
5157 @unnumbered Variable Index