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{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 This package was originally written by Dave Gillespie,
119 @file{daveg@@synaptics.com}, as a total rewrite of an earlier 1986
120 @file{cl.el} package by Cesar Quiroz. Care has been taken to ensure
121 that each function is defined efficiently, concisely, and with minimal
122 impact on the rest of the Emacs environment. Stefan Monnier added the
123 file @file{cl-lib.el} and rationalized the namespace for Emacs 24.3.
126 * Usage:: How to use the CL package.
127 * Organization:: The package's component files.
128 * Naming Conventions:: Notes on CL function names.
135 The @code{CL} package is distributed with Emacs, so there is no need
136 to install any additional files in order to start using it. Lisp code
137 that uses features from the @code{CL} package should simply include at
145 You may wish to add such a statement to your init file, if you
146 make frequent use of CL features.
149 @section Organization
152 The Common Lisp package is organized into four main files:
156 This is the main file, which contains basic functions
157 and information about the package. This file is relatively compact.
160 This file contains the larger, more complex or unusual functions.
161 It is kept separate so that packages which only want to use Common
162 Lisp fundamentals like the @code{cl-incf} function won't need to pay
163 the overhead of loading the more advanced functions.
166 This file contains most of the advanced functions for operating
167 on sequences or lists, such as @code{cl-delete-if} and @code{cl-assoc}.
170 This file contains the features that are macros instead of functions.
171 Macros expand when the caller is compiled, not when it is run, so the
172 macros generally only need to be present when the byte-compiler is
173 running (or when the macros are used in uncompiled code). Most of the
174 macros of this package are isolated in @file{cl-macs.el} so that they
175 won't take up memory unless you are compiling.
178 The file @file{cl-lib.el} includes all necessary @code{autoload}
179 commands for the functions and macros in the other three files.
180 All you have to do is @code{(require 'cl-lib)}, and @file{cl-lib.el}
181 will take care of pulling in the other files when they are
184 There is another file, @file{cl.el}, which was the main entry point
185 to the CL package prior to Emacs 24.3. Nowadays, it is replaced
186 by @file{cl-lib.el}. The two provide the same features, but use
187 different function names (in fact, @file{cl.el} just defines aliases
188 to the @file{cl-lib.el} definitions). In particular, the old @file{cl.el}
189 does not use a clean namespace. For this reason, Emacs has a policy
190 that packages distributed with Emacs must not load @code{cl} at run time.
191 (It is ok for them to load @code{cl} at @emph{compile} time, with
192 @code{eval-when-compile}, and use the macros it provides.) There is
193 no such restriction on the use of @code{cl-lib}. New code should use
194 @code{cl-lib} rather than @code{cl}. @xref{Naming Conventions}.
196 There is one more file, @file{cl-compat.el}, which defines some
197 routines from the older Quiroz CL package that are not otherwise
198 present in the new package. This file is obsolete and should not be
201 @node Naming Conventions
202 @section Naming Conventions
205 Except where noted, all functions defined by this package have the
206 same calling conventions as their Common Lisp counterparts, and
207 names that are those of Common Lisp plus a @samp{cl-} prefix.
209 Internal function and variable names in the package are prefixed
210 by @code{cl--}. Here is a complete list of functions prefixed by
211 @code{cl-} that were not taken from Common Lisp:
213 @c FIXME lexical-let lexical-let*
215 cl-callf cl-callf2 cl-defsubst
216 cl-floatp-safe cl-letf cl-letf*
219 The following simple functions and macros are defined in @file{cl-lib.el};
220 they do not cause other components like @file{cl-extra} to be loaded.
223 cl-floatp-safe cl-endp
224 cl-evenp cl-oddp cl-plusp cl-minusp
225 cl-caaar .. cl-cddddr
226 cl-list* cl-ldiff cl-rest cl-first .. cl-tenth
227 cl-copy-list cl-subst cl-mapcar [2]
228 cl-adjoin [3] cl-acons cl-pairlis
229 cl-pushnew [3,4] cl-incf [4] cl-decf [4]
230 cl-proclaim cl-declaim
234 [2] Only for one sequence argument or two list arguments.
237 [3] Only if @code{:test} is @code{eq}, @code{equal}, or unspecified,
238 and @code{:key} is not used.
241 [4] Only when @var{place} is a plain variable name.
243 @node Program Structure
244 @chapter Program Structure
247 This section describes features of the @code{CL} package that have to
248 do with programs as a whole: advanced argument lists for functions,
249 and the @code{cl-eval-when} construct.
252 * Argument Lists:: @code{&key}, @code{&aux}, @code{cl-defun}, @code{cl-defmacro}.
253 * Time of Evaluation:: The @code{cl-eval-when} construct.
257 @section Argument Lists
260 Emacs Lisp's notation for argument lists of functions is a subset of
261 the Common Lisp notation. As well as the familiar @code{&optional}
262 and @code{&rest} markers, Common Lisp allows you to specify default
263 values for optional arguments, and it provides the additional markers
264 @code{&key} and @code{&aux}.
266 Since argument parsing is built-in to Emacs, there is no way for
267 this package to implement Common Lisp argument lists seamlessly.
268 Instead, this package defines alternates for several Lisp forms
269 which you must use if you need Common Lisp argument lists.
271 @defmac cl-defun name arglist body...
272 This form is identical to the regular @code{defun} form, except
273 that @var{arglist} is allowed to be a full Common Lisp argument
274 list. Also, the function body is enclosed in an implicit block
275 called @var{name}; @pxref{Blocks and Exits}.
278 @defmac cl-defsubst name arglist body...
279 This is just like @code{cl-defun}, except that the function that
280 is defined is automatically proclaimed @code{inline}, i.e.,
281 calls to it may be expanded into in-line code by the byte compiler.
282 This is analogous to the @code{defsubst} form;
283 @code{cl-defsubst} uses a different method (compiler macros) which
284 works in all versions of Emacs, and also generates somewhat more
285 efficient inline expansions. In particular, @code{cl-defsubst}
286 arranges for the processing of keyword arguments, default values,
287 etc., to be done at compile-time whenever possible.
290 @defmac cl-defmacro name arglist body...
291 This is identical to the regular @code{defmacro} form,
292 except that @var{arglist} is allowed to be a full Common Lisp
293 argument list. The @code{&environment} keyword is supported as
294 described in Steele. The @code{&whole} keyword is supported only
295 within destructured lists (see below); top-level @code{&whole}
296 cannot be implemented with the current Emacs Lisp interpreter.
297 The macro expander body is enclosed in an implicit block called
301 @defmac cl-function symbol-or-lambda
302 This is identical to the regular @code{function} form,
303 except that if the argument is a @code{lambda} form then that
304 form may use a full Common Lisp argument list.
307 Also, all forms (such as @code{cl-flet} and @code{cl-labels}) defined
308 in this package that include @var{arglist}s in their syntax allow
309 full Common Lisp argument lists.
311 Note that it is @emph{not} necessary to use @code{cl-defun} in
312 order to have access to most @code{CL} features in your function.
313 These features are always present; @code{cl-defun}'s only
314 difference from @code{defun} is its more flexible argument
315 lists and its implicit block.
317 The full form of a Common Lisp argument list is
321 &optional (@var{var} @var{initform} @var{svar})...
323 &key ((@var{keyword} @var{var}) @var{initform} @var{svar})...
324 &aux (@var{var} @var{initform})...)
327 Each of the five argument list sections is optional. The @var{svar},
328 @var{initform}, and @var{keyword} parts are optional; if they are
329 omitted, then @samp{(@var{var})} may be written simply @samp{@var{var}}.
331 The first section consists of zero or more @dfn{required} arguments.
332 These arguments must always be specified in a call to the function;
333 there is no difference between Emacs Lisp and Common Lisp as far as
334 required arguments are concerned.
336 The second section consists of @dfn{optional} arguments. These
337 arguments may be specified in the function call; if they are not,
338 @var{initform} specifies the default value used for the argument.
339 (No @var{initform} means to use @code{nil} as the default.) The
340 @var{initform} is evaluated with the bindings for the preceding
341 arguments already established; @code{(a &optional (b (1+ a)))}
342 matches one or two arguments, with the second argument defaulting
343 to one plus the first argument. If the @var{svar} is specified,
344 it is an auxiliary variable which is bound to @code{t} if the optional
345 argument was specified, or to @code{nil} if the argument was omitted.
346 If you don't use an @var{svar}, then there will be no way for your
347 function to tell whether it was called with no argument, or with
348 the default value passed explicitly as an argument.
350 The third section consists of a single @dfn{rest} argument. If
351 more arguments were passed to the function than are accounted for
352 by the required and optional arguments, those extra arguments are
353 collected into a list and bound to the ``rest'' argument variable.
354 Common Lisp's @code{&rest} is equivalent to that of Emacs Lisp.
355 Common Lisp accepts @code{&body} as a synonym for @code{&rest} in
356 macro contexts; this package accepts it all the time.
358 The fourth section consists of @dfn{keyword} arguments. These
359 are optional arguments which are specified by name rather than
360 positionally in the argument list. For example,
363 (cl-defun foo (a &optional b &key c d (e 17)))
367 defines a function which may be called with one, two, or more
368 arguments. The first two arguments are bound to @code{a} and
369 @code{b} in the usual way. The remaining arguments must be
370 pairs of the form @code{:c}, @code{:d}, or @code{:e} followed
371 by the value to be bound to the corresponding argument variable.
372 (Symbols whose names begin with a colon are called @dfn{keywords},
373 and they are self-quoting in the same way as @code{nil} and
376 For example, the call @code{(foo 1 2 :d 3 :c 4)} sets the five
377 arguments to 1, 2, 4, 3, and 17, respectively. If the same keyword
378 appears more than once in the function call, the first occurrence
379 takes precedence over the later ones. Note that it is not possible
380 to specify keyword arguments without specifying the optional
381 argument @code{b} as well, since @code{(foo 1 :c 2)} would bind
382 @code{b} to the keyword @code{:c}, then signal an error because
383 @code{2} is not a valid keyword.
385 You can also explicitly specify the keyword argument; it need not be
386 simply the variable name prefixed with a colon. For example,
389 (cl-defun bar (&key (a 1) ((baz b) 4)))
394 specifies a keyword @code{:a} that sets the variable @code{a} with
395 default value 1, as well as a keyword @code{baz} that sets the
396 variable @code{b} with default value 4. In this case, because
397 @code{baz} is not self-quoting, you must quote it explicitly in the
398 function call, like this:
404 Ordinarily, it is an error to pass an unrecognized keyword to
405 a function, e.g., @code{(foo 1 2 :c 3 :goober 4)}. You can ask
406 Lisp to ignore unrecognized keywords, either by adding the
407 marker @code{&allow-other-keys} after the keyword section
408 of the argument list, or by specifying an @code{:allow-other-keys}
409 argument in the call whose value is non-@code{nil}. If the
410 function uses both @code{&rest} and @code{&key} at the same time,
411 the ``rest'' argument is bound to the keyword list as it appears
412 in the call. For example:
415 (cl-defun find-thing (thing &rest rest &key need &allow-other-keys)
416 (or (apply 'cl-member thing thing-list :allow-other-keys t rest)
417 (if need (error "Thing not found"))))
421 This function takes a @code{:need} keyword argument, but also
422 accepts other keyword arguments which are passed on to the
423 @code{cl-member} function. @code{allow-other-keys} is used to
424 keep both @code{find-thing} and @code{cl-member} from complaining
425 about each others' keywords in the arguments.
427 The fifth section of the argument list consists of @dfn{auxiliary
428 variables}. These are not really arguments at all, but simply
429 variables which are bound to @code{nil} or to the specified
430 @var{initforms} during execution of the function. There is no
431 difference between the following two functions, except for a
432 matter of stylistic taste:
435 (cl-defun foo (a b &aux (c (+ a b)) d)
443 Argument lists support @dfn{destructuring}. In Common Lisp,
444 destructuring is only allowed with @code{defmacro}; this package
445 allows it with @code{cl-defun} and other argument lists as well.
446 In destructuring, any argument variable (@var{var} in the above
447 diagram) can be replaced by a list of variables, or more generally,
448 a recursive argument list. The corresponding argument value must
449 be a list whose elements match this recursive argument list.
453 (cl-defmacro dolist ((var listform &optional resultform)
458 This says that the first argument of @code{dolist} must be a list
459 of two or three items; if there are other arguments as well as this
460 list, they are stored in @code{body}. All features allowed in
461 regular argument lists are allowed in these recursive argument lists.
462 In addition, the clause @samp{&whole @var{var}} is allowed at the
463 front of a recursive argument list. It binds @var{var} to the
464 whole list being matched; thus @code{(&whole all a b)} matches
465 a list of two things, with @code{a} bound to the first thing,
466 @code{b} bound to the second thing, and @code{all} bound to the
467 list itself. (Common Lisp allows @code{&whole} in top-level
468 @code{defmacro} argument lists as well, but Emacs Lisp does not
471 One last feature of destructuring is that the argument list may be
472 dotted, so that the argument list @code{(a b . c)} is functionally
473 equivalent to @code{(a b &rest c)}.
475 If the optimization quality @code{safety} is set to 0
476 (@pxref{Declarations}), error checking for wrong number of
477 arguments and invalid keyword arguments is disabled. By default,
478 argument lists are rigorously checked.
480 @node Time of Evaluation
481 @section Time of Evaluation
484 Normally, the byte-compiler does not actually execute the forms in
485 a file it compiles. For example, if a file contains @code{(setq foo t)},
486 the act of compiling it will not actually set @code{foo} to @code{t}.
487 This is true even if the @code{setq} was a top-level form (i.e., not
488 enclosed in a @code{defun} or other form). Sometimes, though, you
489 would like to have certain top-level forms evaluated at compile-time.
490 For example, the compiler effectively evaluates @code{defmacro} forms
491 at compile-time so that later parts of the file can refer to the
492 macros that are defined.
494 @defmac cl-eval-when (situations...) forms...
495 This form controls when the body @var{forms} are evaluated.
496 The @var{situations} list may contain any set of the symbols
497 @code{compile}, @code{load}, and @code{eval} (or their long-winded
498 ANSI equivalents, @code{:compile-toplevel}, @code{:load-toplevel},
499 and @code{:execute}).
501 The @code{cl-eval-when} form is handled differently depending on
502 whether or not it is being compiled as a top-level form.
503 Specifically, it gets special treatment if it is being compiled
504 by a command such as @code{byte-compile-file} which compiles files
505 or buffers of code, and it appears either literally at the
506 top level of the file or inside a top-level @code{progn}.
508 For compiled top-level @code{cl-eval-when}s, the body @var{forms} are
509 executed at compile-time if @code{compile} is in the @var{situations}
510 list, and the @var{forms} are written out to the file (to be executed
511 at load-time) if @code{load} is in the @var{situations} list.
513 For non-compiled-top-level forms, only the @code{eval} situation is
514 relevant. (This includes forms executed by the interpreter, forms
515 compiled with @code{byte-compile} rather than @code{byte-compile-file},
516 and non-top-level forms.) The @code{cl-eval-when} acts like a
517 @code{progn} if @code{eval} is specified, and like @code{nil}
518 (ignoring the body @var{forms}) if not.
520 The rules become more subtle when @code{cl-eval-when}s are nested;
521 consult Steele (second edition) for the gruesome details (and
522 some gruesome examples).
524 Some simple examples:
527 ;; Top-level forms in foo.el:
528 (cl-eval-when (compile) (setq foo1 'bar))
529 (cl-eval-when (load) (setq foo2 'bar))
530 (cl-eval-when (compile load) (setq foo3 'bar))
531 (cl-eval-when (eval) (setq foo4 'bar))
532 (cl-eval-when (eval compile) (setq foo5 'bar))
533 (cl-eval-when (eval load) (setq foo6 'bar))
534 (cl-eval-when (eval compile load) (setq foo7 'bar))
537 When @file{foo.el} is compiled, these variables will be set during
538 the compilation itself:
541 foo1 foo3 foo5 foo7 ; `compile'
544 When @file{foo.elc} is loaded, these variables will be set:
547 foo2 foo3 foo6 foo7 ; `load'
550 And if @file{foo.el} is loaded uncompiled, these variables will
554 foo4 foo5 foo6 foo7 ; `eval'
557 If these seven @code{cl-eval-when}s had been, say, inside a @code{defun},
558 then the first three would have been equivalent to @code{nil} and the
559 last four would have been equivalent to the corresponding @code{setq}s.
561 Note that @code{(cl-eval-when (load eval) @dots{})} is equivalent
562 to @code{(progn @dots{})} in all contexts. The compiler treats
563 certain top-level forms, like @code{defmacro} (sort-of) and
564 @code{require}, as if they were wrapped in @code{(cl-eval-when
565 (compile load eval) @dots{})}.
568 Emacs includes two special forms related to @code{cl-eval-when}.
569 One of these, @code{eval-when-compile}, is not quite equivalent to
570 any @code{cl-eval-when} construct and is described below.
572 The other form, @code{(eval-and-compile @dots{})}, is exactly
573 equivalent to @samp{(cl-eval-when (compile load eval) @dots{})} and
574 so is not itself defined by this package.
576 @defmac eval-when-compile forms...
577 The @var{forms} are evaluated at compile-time; at execution time,
578 this form acts like a quoted constant of the resulting value. Used
579 at top-level, @code{eval-when-compile} is just like @samp{eval-when
580 (compile eval)}. In other contexts, @code{eval-when-compile}
581 allows code to be evaluated once at compile-time for efficiency
584 This form is similar to the @samp{#.} syntax of true Common Lisp.
587 @defmac cl-load-time-value form
588 The @var{form} is evaluated at load-time; at execution time,
589 this form acts like a quoted constant of the resulting value.
591 Early Common Lisp had a @samp{#,} syntax that was similar to
592 this, but ANSI Common Lisp replaced it with @code{load-time-value}
593 and gave it more well-defined semantics.
595 In a compiled file, @code{cl-load-time-value} arranges for @var{form}
596 to be evaluated when the @file{.elc} file is loaded and then used
597 as if it were a quoted constant. In code compiled by
598 @code{byte-compile} rather than @code{byte-compile-file}, the
599 effect is identical to @code{eval-when-compile}. In uncompiled
600 code, both @code{eval-when-compile} and @code{cl-load-time-value}
601 act exactly like @code{progn}.
605 (insert "This function was executed on: "
606 (current-time-string)
608 (eval-when-compile (current-time-string))
609 ;; or '#.(current-time-string) in real Common Lisp
611 (cl-load-time-value (current-time-string))))
615 Byte-compiled, the above defun will result in the following code
616 (or its compiled equivalent, of course) in the @file{.elc} file:
619 (setq --temp-- (current-time-string))
621 (insert "This function was executed on: "
622 (current-time-string)
624 '"Wed Jun 23 18:33:43 1993"
634 This section describes functions for testing whether various
635 facts are true or false.
638 * Type Predicates:: @code{cl-typep}, @code{cl-deftype}, and @code{cl-coerce}.
639 * Equality Predicates:: @code{cl-equalp}.
642 @node Type Predicates
643 @section Type Predicates
645 @defun cl-typep object type
646 Check if @var{object} is of type @var{type}, where @var{type} is a
647 (quoted) type name of the sort used by Common Lisp. For example,
648 @code{(cl-typep foo 'integer)} is equivalent to @code{(integerp foo)}.
651 The @var{type} argument to the above function is either a symbol
652 or a list beginning with a symbol.
656 If the type name is a symbol, Emacs appends @samp{-p} to the
657 symbol name to form the name of a predicate function for testing
658 the type. (Built-in predicates whose names end in @samp{p} rather
659 than @samp{-p} are used when appropriate.)
662 The type symbol @code{t} stands for the union of all types.
663 @code{(cl-typep @var{object} t)} is always true. Likewise, the
664 type symbol @code{nil} stands for nothing at all, and
665 @code{(cl-typep @var{object} nil)} is always false.
668 The type symbol @code{null} represents the symbol @code{nil}.
669 Thus @code{(cl-typep @var{object} 'null)} is equivalent to
670 @code{(null @var{object})}.
673 The type symbol @code{atom} represents all objects that are not cons
674 cells. Thus @code{(cl-typep @var{object} 'atom)} is equivalent to
675 @code{(atom @var{object})}.
678 The type symbol @code{real} is a synonym for @code{number}, and
679 @code{fixnum} is a synonym for @code{integer}.
682 The type symbols @code{character} and @code{string-char} match
683 integers in the range from 0 to 255.
686 The type symbol @code{float} uses the @code{cl-floatp-safe} predicate
687 defined by this package rather than @code{floatp}, so it will work
688 correctly even in Emacs versions without floating-point support.
691 The type list @code{(integer @var{low} @var{high})} represents all
692 integers between @var{low} and @var{high}, inclusive. Either bound
693 may be a list of a single integer to specify an exclusive limit,
694 or a @code{*} to specify no limit. The type @code{(integer * *)}
695 is thus equivalent to @code{integer}.
698 Likewise, lists beginning with @code{float}, @code{real}, or
699 @code{number} represent numbers of that type falling in a particular
703 Lists beginning with @code{and}, @code{or}, and @code{not} form
704 combinations of types. For example, @code{(or integer (float 0 *))}
705 represents all objects that are integers or non-negative floats.
708 Lists beginning with @code{member} or @code{cl-member} represent
709 objects @code{eql} to any of the following values. For example,
710 @code{(member 1 2 3 4)} is equivalent to @code{(integer 1 4)},
711 and @code{(member nil)} is equivalent to @code{null}.
714 Lists of the form @code{(satisfies @var{predicate})} represent
715 all objects for which @var{predicate} returns true when called
716 with that object as an argument.
719 The following function and macro (not technically predicates) are
720 related to @code{cl-typep}.
722 @defun cl-coerce object type
723 This function attempts to convert @var{object} to the specified
724 @var{type}. If @var{object} is already of that type as determined by
725 @code{cl-typep}, it is simply returned. Otherwise, certain types of
726 conversions will be made: If @var{type} is any sequence type
727 (@code{string}, @code{list}, etc.) then @var{object} will be
728 converted to that type if possible. If @var{type} is
729 @code{character}, then strings of length one and symbols with
730 one-character names can be coerced. If @var{type} is @code{float},
731 then integers can be coerced in versions of Emacs that support
732 floats. In all other circumstances, @code{cl-coerce} signals an
736 @defmac cl-deftype name arglist forms...
737 This macro defines a new type called @var{name}. It is similar
738 to @code{defmacro} in many ways; when @var{name} is encountered
739 as a type name, the body @var{forms} are evaluated and should
740 return a type specifier that is equivalent to the type. The
741 @var{arglist} is a Common Lisp argument list of the sort accepted
742 by @code{cl-defmacro}. The type specifier @samp{(@var{name} @var{args}...)}
743 is expanded by calling the expander with those arguments; the type
744 symbol @samp{@var{name}} is expanded by calling the expander with
745 no arguments. The @var{arglist} is processed the same as for
746 @code{cl-defmacro} except that optional arguments without explicit
747 defaults use @code{*} instead of @code{nil} as the ``default''
748 default. Some examples:
751 (cl-deftype null () '(satisfies null)) ; predefined
752 (cl-deftype list () '(or null cons)) ; predefined
753 (cl-deftype unsigned-byte (&optional bits)
754 (list 'integer 0 (if (eq bits '*) bits (1- (lsh 1 bits)))))
755 (unsigned-byte 8) @equiv{} (integer 0 255)
756 (unsigned-byte) @equiv{} (integer 0 *)
757 unsigned-byte @equiv{} (integer 0 *)
761 The last example shows how the Common Lisp @code{unsigned-byte}
762 type specifier could be implemented if desired; this package does
763 not implement @code{unsigned-byte} by default.
766 The @code{cl-typecase} and @code{cl-check-type} macros also use type
767 names. @xref{Conditionals}. @xref{Assertions}. The @code{cl-map},
768 @code{cl-concatenate}, and @code{cl-merge} functions take type-name
769 arguments to specify the type of sequence to return. @xref{Sequences}.
771 @node Equality Predicates
772 @section Equality Predicates
775 This package defines the Common Lisp predicate @code{cl-equalp}.
778 This function is a more flexible version of @code{equal}. In
779 particular, it compares strings case-insensitively, and it compares
780 numbers without regard to type (so that @code{(cl-equalp 3 3.0)} is
781 true). Vectors and conses are compared recursively. All other
782 objects are compared as if by @code{equal}.
784 This function differs from Common Lisp @code{equalp} in several
785 respects. First, Common Lisp's @code{equalp} also compares
786 @emph{characters} case-insensitively, which would be impractical
787 in this package since Emacs does not distinguish between integers
788 and characters. In keeping with the idea that strings are less
789 vector-like in Emacs Lisp, this package's @code{cl-equalp} also will
790 not compare strings against vectors of integers.
793 Also note that the Common Lisp functions @code{member} and @code{assoc}
794 use @code{eql} to compare elements, whereas Emacs Lisp follows the
795 MacLisp tradition and uses @code{equal} for these two functions.
796 In Emacs, use @code{memq} (or @code{cl-member}) and @code{assq} (or
797 @code{cl-assoc}) to get functions which use @code{eql} for comparisons.
799 @node Control Structure
800 @chapter Control Structure
803 The features described in the following sections implement
804 various advanced control structures, including extensions to the
805 standard @code{setf} facility, and a number of looping and conditional
809 @c lexical-let is obsolete; flet is not cl-flet.
810 @c values is not cl-values.
812 * Assignment:: The @code{cl-psetq} form.
813 * Generalized Variables:: Extensions to generalized variables.
814 * Variable Bindings:: @code{cl-progv}, @code{lexical-let}, @code{flet}, @code{cl-macrolet}.
815 * Conditionals:: @code{cl-case}, @code{cl-typecase}.
816 * Blocks and Exits:: @code{cl-block}, @code{cl-return}, @code{cl-return-from}.
817 * Iteration:: @code{cl-do}, @code{cl-dotimes}, @code{cl-dolist}, @code{cl-do-symbols}.
818 * Loop Facility:: The Common Lisp @code{cl-loop} macro.
819 * Multiple Values:: @code{values}, @code{cl-multiple-value-bind}, etc.
826 The @code{cl-psetq} form is just like @code{setq}, except that multiple
827 assignments are done in parallel rather than sequentially.
829 @defmac cl-psetq [symbol form]@dots{}
830 This special form (actually a macro) is used to assign to several
831 variables simultaneously. Given only one @var{symbol} and @var{form},
832 it has the same effect as @code{setq}. Given several @var{symbol}
833 and @var{form} pairs, it evaluates all the @var{form}s in advance
834 and then stores the corresponding variables afterwards.
838 (setq x (+ x y) y (* x y))
841 y ; @r{@code{y} was computed after @code{x} was set.}
844 (cl-psetq x (+ x y) y (* x y))
847 y ; @r{@code{y} was computed before @code{x} was set.}
851 The simplest use of @code{cl-psetq} is @code{(cl-psetq x y y x)}, which
852 exchanges the values of two variables. (The @code{cl-rotatef} form
853 provides an even more convenient way to swap two variables;
854 @pxref{Modify Macros}.)
856 @code{cl-psetq} always returns @code{nil}.
859 @node Generalized Variables
860 @section Generalized Variables
862 A @dfn{generalized variable} or @dfn{place form} is one of the many
863 places in Lisp memory where values can be stored. The simplest place
864 form is a regular Lisp variable. But the cars and cdrs of lists,
865 elements of arrays, properties of symbols, and many other locations
866 are also places where Lisp values are stored. For basic information,
867 @pxref{Generalized Variables,,,elisp,GNU Emacs Lisp Reference Manual}.
868 This package provides several additional features related to
869 generalized variables.
872 * Setf Extensions:: Additional @code{setf} places.
873 * Modify Macros:: @code{cl-incf}, @code{cl-rotatef}, @code{letf}, @code{cl-callf}, etc.
874 * Customizing Setf:: @code{define-modify-macro}, @code{defsetf}, @code{define-setf-method}.
877 @node Setf Extensions
878 @subsection Setf Extensions
880 Several standard (e.g. @code{car}) and Emacs-specific
881 (e.g. @code{window-point}) Lisp functions are @code{setf}-able by default.
882 This package defines @code{setf} handlers for several additional functions:
886 Functions from @code{CL} itself:
888 cl-caaar .. cl-cddddr cl-first .. cl-tenth
889 cl-rest cl-get cl-getf cl-subseq
893 General Emacs Lisp functions:
895 buffer-file-name getenv
896 buffer-modified-p global-key-binding
897 buffer-name local-key-binding
899 buffer-substring mark-marker
900 current-buffer marker-position
901 current-case-table mouse-position
903 current-global-map point-marker
904 current-input-mode point-max
905 current-local-map point-min
906 current-window-configuration read-mouse-position
907 default-file-modes screen-height
908 documentation-property screen-width
909 face-background selected-window
910 face-background-pixmap selected-screen
911 face-font selected-frame
912 face-foreground standard-case-table
913 face-underline-p syntax-table
914 file-modes visited-file-modtime
915 frame-height window-height
916 frame-parameters window-width
917 frame-visible-p x-get-secondary-selection
918 frame-width x-get-selection
922 Most of these have directly corresponding ``set'' functions, like
923 @code{use-local-map} for @code{current-local-map}, or @code{goto-char}
924 for @code{point}. A few, like @code{point-min}, expand to longer
925 sequences of code when they are used with @code{setf}
926 (@code{(narrow-to-region x (point-max))} in this case).
929 A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])},
930 where @var{subplace} is itself a valid generalized variable whose
931 current value is a string, and where the value stored is also a
932 string. The new string is spliced into the specified part of the
933 destination string. For example:
936 (setq a (list "hello" "world"))
937 @result{} ("hello" "world")
940 (substring (cadr a) 2 4)
942 (setf (substring (cadr a) 2 4) "o")
947 @result{} ("hello" "wood")
950 The generalized variable @code{buffer-substring}, listed above,
951 also works in this way by replacing a portion of the current buffer.
953 @c FIXME? Also `eq'? (see cl-lib.el)
956 A call of the form @code{(apply '@var{func} @dots{})} or
957 @code{(apply (function @var{func}) @dots{})}, where @var{func}
958 is a @code{setf}-able function whose store function is ``suitable''
959 in the sense described in Steele's book; since none of the standard
960 Emacs place functions are suitable in this sense, this feature is
961 only interesting when used with places you define yourself with
962 @code{define-setf-method} or the long form of @code{defsetf}.
965 A macro call, in which case the macro is expanded and @code{setf}
966 is applied to the resulting form.
969 Any form for which a @code{defsetf} or @code{define-setf-method}
973 @c FIXME should this be in lispref? It seems self-evident.
974 @c Contrast with the cl-incf example later on.
975 @c Here it really only serves as a constrast to wrong-order.
976 The @code{setf} macro takes care to evaluate all subforms in
977 the proper left-to-right order; for example,
980 (setf (aref vec (cl-incf i)) i)
984 looks like it will evaluate @code{(cl-incf i)} exactly once, before the
985 following access to @code{i}; the @code{setf} expander will insert
986 temporary variables as necessary to ensure that it does in fact work
987 this way no matter what setf-method is defined for @code{aref}.
988 (In this case, @code{aset} would be used and no such steps would
989 be necessary since @code{aset} takes its arguments in a convenient
992 However, if the @var{place} form is a macro which explicitly
993 evaluates its arguments in an unusual order, this unusual order
994 will be preserved. Adapting an example from Steele, given
997 (defmacro wrong-order (x y) (list 'aref y x))
1001 the form @code{(setf (wrong-order @var{a} @var{b}) 17)} will
1002 evaluate @var{b} first, then @var{a}, just as in an actual call
1003 to @code{wrong-order}.
1006 @subsection Modify Macros
1009 This package defines a number of macros that operate on generalized
1010 variables. Many are interesting and useful even when the @var{place}
1011 is just a variable name.
1013 @defmac cl-psetf [place form]@dots{}
1014 This macro is to @code{setf} what @code{cl-psetq} is to @code{setq}:
1015 When several @var{place}s and @var{form}s are involved, the
1016 assignments take place in parallel rather than sequentially.
1017 Specifically, all subforms are evaluated from left to right, then
1018 all the assignments are done (in an undefined order).
1021 @defmac cl-incf place &optional x
1022 This macro increments the number stored in @var{place} by one, or
1023 by @var{x} if specified. The incremented value is returned. For
1024 example, @code{(cl-incf i)} is equivalent to @code{(setq i (1+ i))}, and
1025 @code{(cl-incf (car x) 2)} is equivalent to @code{(setcar x (+ (car x) 2))}.
1027 As with @code{setf}, care is taken to preserve the ``apparent'' order
1028 of evaluation. For example,
1031 (cl-incf (aref vec (cl-incf i)))
1035 appears to increment @code{i} once, then increment the element of
1036 @code{vec} addressed by @code{i}; this is indeed exactly what it
1037 does, which means the above form is @emph{not} equivalent to the
1038 ``obvious'' expansion,
1041 (setf (aref vec (cl-incf i))
1042 (1+ (aref vec (cl-incf i)))) ; wrong!
1046 but rather to something more like
1049 (let ((temp (cl-incf i)))
1050 (setf (aref vec temp) (1+ (aref vec temp))))
1054 Again, all of this is taken care of automatically by @code{cl-incf} and
1055 the other generalized-variable macros.
1057 As a more Emacs-specific example of @code{cl-incf}, the expression
1058 @code{(cl-incf (point) @var{n})} is essentially equivalent to
1059 @code{(forward-char @var{n})}.
1062 @defmac cl-decf place &optional x
1063 This macro decrements the number stored in @var{place} by one, or
1064 by @var{x} if specified.
1067 @defmac cl-pushnew x place @t{&key :test :test-not :key}
1068 This macro inserts @var{x} at the front of the list stored in
1069 @var{place}, but only if @var{x} was not @code{eql} to any
1070 existing element of the list. The optional keyword arguments
1071 are interpreted in the same way as for @code{cl-adjoin}.
1072 @xref{Lists as Sets}.
1075 @defmac cl-shiftf place@dots{} newvalue
1076 This macro shifts the @var{place}s left by one, shifting in the
1077 value of @var{newvalue} (which may be any Lisp expression, not just
1078 a generalized variable), and returning the value shifted out of
1079 the first @var{place}. Thus, @code{(cl-shiftf @var{a} @var{b} @var{c}
1080 @var{d})} is equivalent to
1085 (cl-psetf @var{a} @var{b}
1091 except that the subforms of @var{a}, @var{b}, and @var{c} are actually
1092 evaluated only once each and in the apparent order.
1095 @defmac cl-rotatef place@dots{}
1096 This macro rotates the @var{place}s left by one in circular fashion.
1097 Thus, @code{(cl-rotatef @var{a} @var{b} @var{c} @var{d})} is equivalent to
1100 (cl-psetf @var{a} @var{b}
1107 except for the evaluation of subforms. @code{cl-rotatef} always
1108 returns @code{nil}. Note that @code{(cl-rotatef @var{a} @var{b})}
1109 conveniently exchanges @var{a} and @var{b}.
1112 The following macros were invented for this package; they have no
1113 analogues in Common Lisp.
1115 @defmac letf (bindings@dots{}) forms@dots{}
1116 This macro is analogous to @code{let}, but for generalized variables
1117 rather than just symbols. Each @var{binding} should be of the form
1118 @code{(@var{place} @var{value})}; the original contents of the
1119 @var{place}s are saved, the @var{value}s are stored in them, and
1120 then the body @var{form}s are executed. Afterwards, the @var{places}
1121 are set back to their original saved contents. This cleanup happens
1122 even if the @var{form}s exit irregularly due to a @code{throw} or an
1128 (letf (((point) (point-min))
1134 moves ``point'' in the current buffer to the beginning of the buffer,
1135 and also binds @code{a} to 17 (as if by a normal @code{let}, since
1136 @code{a} is just a regular variable). After the body exits, @code{a}
1137 is set back to its original value and point is moved back to its
1140 Note that @code{letf} on @code{(point)} is not quite like a
1141 @code{save-excursion}, as the latter effectively saves a marker
1142 which tracks insertions and deletions in the buffer. Actually,
1143 a @code{letf} of @code{(point-marker)} is much closer to this
1144 behavior. (@code{point} and @code{point-marker} are equivalent
1145 as @code{setf} places; each will accept either an integer or a
1146 marker as the stored value.)
1148 Since generalized variables look like lists, @code{let}'s shorthand
1149 of using @samp{foo} for @samp{(foo nil)} as a @var{binding} would
1150 be ambiguous in @code{letf} and is not allowed.
1152 However, a @var{binding} specifier may be a one-element list
1153 @samp{(@var{place})}, which is similar to @samp{(@var{place}
1154 @var{place})}. In other words, the @var{place} is not disturbed
1155 on entry to the body, and the only effect of the @code{letf} is
1156 to restore the original value of @var{place} afterwards. (The
1157 redundant access-and-store suggested by the @code{(@var{place}
1158 @var{place})} example does not actually occur.)
1160 In most cases, the @var{place} must have a well-defined value on
1161 entry to the @code{letf} form. The only exceptions are plain
1162 variables and calls to @code{symbol-value} and @code{symbol-function}.
1163 If the symbol is not bound on entry, it is simply made unbound by
1164 @code{makunbound} or @code{fmakunbound} on exit.
1167 @defmac cl-letf* (bindings@dots{}) forms@dots{}
1168 This macro is to @code{letf} what @code{let*} is to @code{let}:
1169 It does the bindings in sequential rather than parallel order.
1172 @defmac cl-callf @var{function} @var{place} @var{args}@dots{}
1173 This is the ``generic'' modify macro. It calls @var{function},
1174 which should be an unquoted function name, macro name, or lambda.
1175 It passes @var{place} and @var{args} as arguments, and assigns the
1176 result back to @var{place}. For example, @code{(cl-incf @var{place}
1177 @var{n})} is the same as @code{(cl-callf + @var{place} @var{n})}.
1181 (cl-callf abs my-number)
1182 (cl-callf concat (buffer-name) "<" (number-to-string n) ">")
1183 (cl-callf cl-union happy-people (list joe bob) :test 'same-person)
1186 @xref{Customizing Setf}, for @code{define-modify-macro}, a way
1187 to create even more concise notations for modify macros. Note
1188 again that @code{cl-callf} is an extension to standard Common Lisp.
1191 @defmac cl-callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{}
1192 This macro is like @code{cl-callf}, except that @var{place} is
1193 the @emph{second} argument of @var{function} rather than the
1194 first. For example, @code{(push @var{x} @var{place})} is
1195 equivalent to @code{(cl-callf2 cons @var{x} @var{place})}.
1198 The @code{cl-callf} and @code{cl-callf2} macros serve as building
1199 blocks for other macros like @code{cl-incf}, @code{cl-pushnew}, and
1200 @code{define-modify-macro}. The @code{letf} and @code{cl-letf*}
1201 macros are used in the processing of symbol macros;
1202 @pxref{Macro Bindings}.
1204 @node Customizing Setf
1205 @subsection Customizing Setf
1208 Common Lisp defines three macros, @code{define-modify-macro},
1209 @code{defsetf}, and @code{define-setf-method}, that allow the
1210 user to extend generalized variables in various ways.
1212 @defmac define-modify-macro name arglist function [doc-string]
1213 This macro defines a ``read-modify-write'' macro similar to
1214 @code{cl-incf} and @code{cl-decf}. The macro @var{name} is defined
1215 to take a @var{place} argument followed by additional arguments
1216 described by @var{arglist}. The call
1219 (@var{name} @var{place} @var{args}...)
1226 (cl-callf @var{func} @var{place} @var{args}...)
1230 which in turn is roughly equivalent to
1233 (setf @var{place} (@var{func} @var{place} @var{args}...))
1239 (define-modify-macro cl-incf (&optional (n 1)) +)
1240 (define-modify-macro cl-concatf (&rest args) concat)
1243 Note that @code{&key} is not allowed in @var{arglist}, but
1244 @code{&rest} is sufficient to pass keywords on to the function.
1246 Most of the modify macros defined by Common Lisp do not exactly
1247 follow the pattern of @code{define-modify-macro}. For example,
1248 @code{push} takes its arguments in the wrong order, and @code{pop}
1249 is completely irregular. You can define these macros ``by hand''
1250 using @code{get-setf-method}, or consult the source
1251 to see how to use the internal @code{setf} building blocks.
1254 @defmac defsetf access-fn update-fn
1255 This is the simpler of two @code{defsetf} forms. Where
1256 @var{access-fn} is the name of a function which accesses a place,
1257 this declares @var{update-fn} to be the corresponding store
1258 function. From now on,
1261 (setf (@var{access-fn} @var{arg1} @var{arg2} @var{arg3}) @var{value})
1268 (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} @var{value})
1272 The @var{update-fn} is required to be either a true function, or
1273 a macro which evaluates its arguments in a function-like way. Also,
1274 the @var{update-fn} is expected to return @var{value} as its result.
1275 Otherwise, the above expansion would not obey the rules for the way
1276 @code{setf} is supposed to behave.
1278 As a special (non-Common-Lisp) extension, a third argument of @code{t}
1279 to @code{defsetf} says that the @code{update-fn}'s return value is
1280 not suitable, so that the above @code{setf} should be expanded to
1284 (let ((temp @var{value}))
1285 (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} temp)
1289 Some examples of the use of @code{defsetf}, drawn from the standard
1290 suite of setf methods, are:
1293 (defsetf car setcar)
1294 (defsetf symbol-value set)
1295 (defsetf buffer-name rename-buffer t)
1299 @defmac defsetf access-fn arglist (store-var) forms@dots{}
1300 This is the second, more complex, form of @code{defsetf}. It is
1301 rather like @code{defmacro} except for the additional @var{store-var}
1302 argument. The @var{forms} should return a Lisp form which stores
1303 the value of @var{store-var} into the generalized variable formed
1304 by a call to @var{access-fn} with arguments described by @var{arglist}.
1305 The @var{forms} may begin with a string which documents the @code{setf}
1306 method (analogous to the doc string that appears at the front of a
1309 For example, the simple form of @code{defsetf} is shorthand for
1312 (defsetf @var{access-fn} (&rest args) (store)
1313 (append '(@var{update-fn}) args (list store)))
1316 The Lisp form that is returned can access the arguments from
1317 @var{arglist} and @var{store-var} in an unrestricted fashion;
1318 macros like @code{setf} and @code{cl-incf} which invoke this
1319 setf-method will insert temporary variables as needed to make
1320 sure the apparent order of evaluation is preserved.
1322 Another example drawn from the standard package:
1325 (defsetf nth (n x) (store)
1326 (list 'setcar (list 'nthcdr n x) store))
1330 @defmac define-setf-method access-fn arglist forms@dots{}
1331 This is the most general way to create new place forms. When
1332 a @code{setf} to @var{access-fn} with arguments described by
1333 @var{arglist} is expanded, the @var{forms} are evaluated and
1334 must return a list of five items:
1338 A list of @dfn{temporary variables}.
1341 A list of @dfn{value forms} corresponding to the temporary variables
1342 above. The temporary variables will be bound to these value forms
1343 as the first step of any operation on the generalized variable.
1346 A list of exactly one @dfn{store variable} (generally obtained
1347 from a call to @code{gensym}).
1350 A Lisp form which stores the contents of the store variable into
1351 the generalized variable, assuming the temporaries have been
1352 bound as described above.
1355 A Lisp form which accesses the contents of the generalized variable,
1356 assuming the temporaries have been bound.
1359 This is exactly like the Common Lisp macro of the same name,
1360 except that the method returns a list of five values rather
1361 than the five values themselves, since Emacs Lisp does not
1362 support Common Lisp's notion of multiple return values.
1364 Once again, the @var{forms} may begin with a documentation string.
1366 A setf-method should be maximally conservative with regard to
1367 temporary variables. In the setf-methods generated by
1368 @code{defsetf}, the second return value is simply the list of
1369 arguments in the place form, and the first return value is a
1370 list of a corresponding number of temporary variables generated
1371 by @code{cl-gensym}. Macros like @code{setf} and @code{cl-incf} which
1372 use this setf-method will optimize away most temporaries that
1373 turn out to be unnecessary, so there is little reason for the
1374 setf-method itself to optimize.
1377 @defun get-setf-method place &optional env
1378 This function returns the setf-method for @var{place}, by
1379 invoking the definition previously recorded by @code{defsetf}
1380 or @code{define-setf-method}. The result is a list of five
1381 values as described above. You can use this function to build
1382 your own @code{cl-incf}-like modify macros. (Actually, it is
1384 better to use the internal functions @code{cl-setf-do-modify}
1385 and @code{cl-setf-do-store}, which are a bit easier to use and
1386 which also do a number of optimizations; consult the source
1387 code for the @code{cl-incf} function for a simple example.)
1389 The argument @var{env} specifies the ``environment'' to be
1390 passed on to @code{macroexpand} if @code{get-setf-method} should
1391 need to expand a macro in @var{place}. It should come from
1392 an @code{&environment} argument to the macro or setf-method
1393 that called @code{get-setf-method}.
1395 See also the source code for the setf-methods for @code{apply}
1396 and @code{substring}, each of which works by calling
1397 @code{get-setf-method} on a simpler case, then massaging
1398 the result in various ways.
1401 Modern Common Lisp defines a second, independent way to specify
1402 the @code{setf} behavior of a function, namely ``@code{setf}
1403 functions'' whose names are lists @code{(setf @var{name})}
1404 rather than symbols. For example, @code{(defun (setf foo) @dots{})}
1405 defines the function that is used when @code{setf} is applied to
1406 @code{foo}. This package does not currently support @code{setf}
1407 functions. In particular, it is a compile-time error to use
1408 @code{setf} on a form which has not already been @code{defsetf}'d
1409 or otherwise declared; in newer Common Lisps, this would not be
1410 an error since the function @code{(setf @var{func})} might be
1413 @node Variable Bindings
1414 @section Variable Bindings
1417 These Lisp forms make bindings to variables and function names,
1418 analogous to Lisp's built-in @code{let} form.
1420 @xref{Modify Macros}, for the @code{letf} and @code{cl-letf*} forms which
1421 are also related to variable bindings.
1424 * Dynamic Bindings:: The @code{cl-progv} form.
1425 * Lexical Bindings:: @code{lexical-let} and lexical closures.
1426 * Function Bindings:: @code{flet} and @code{labels}.
1427 * Macro Bindings:: @code{cl-macrolet} and @code{cl-symbol-macrolet}.
1430 @node Dynamic Bindings
1431 @subsection Dynamic Bindings
1434 The standard @code{let} form binds variables whose names are known
1435 at compile-time. The @code{cl-progv} form provides an easy way to
1436 bind variables whose names are computed at run-time.
1438 @defmac cl-progv symbols values forms@dots{}
1439 This form establishes @code{let}-style variable bindings on a
1440 set of variables computed at run-time. The expressions
1441 @var{symbols} and @var{values} are evaluated, and must return lists
1442 of symbols and values, respectively. The symbols are bound to the
1443 corresponding values for the duration of the body @var{form}s.
1444 If @var{values} is shorter than @var{symbols}, the last few symbols
1445 are bound to @code{nil}.
1446 If @var{symbols} is shorter than @var{values}, the excess values
1450 @node Lexical Bindings
1451 @subsection Lexical Bindings
1454 The @code{CL} package defines the following macro which
1455 more closely follows the Common Lisp @code{let} form:
1457 @defmac lexical-let (bindings@dots{}) forms@dots{}
1458 This form is exactly like @code{let} except that the bindings it
1459 establishes are purely lexical. Lexical bindings are similar to
1460 local variables in a language like C: Only the code physically
1461 within the body of the @code{lexical-let} (after macro expansion)
1462 may refer to the bound variables.
1466 (defun foo (b) (+ a b))
1467 (let ((a 2)) (foo a))
1469 (lexical-let ((a 2)) (foo a))
1474 In this example, a regular @code{let} binding of @code{a} actually
1475 makes a temporary change to the global variable @code{a}, so @code{foo}
1476 is able to see the binding of @code{a} to 2. But @code{lexical-let}
1477 actually creates a distinct local variable @code{a} for use within its
1478 body, without any effect on the global variable of the same name.
1480 The most important use of lexical bindings is to create @dfn{closures}.
1481 A closure is a function object that refers to an outside lexical
1482 variable. For example:
1485 (defun make-adder (n)
1486 (lexical-let ((n n))
1487 (function (lambda (m) (+ n m)))))
1488 (setq add17 (make-adder 17))
1494 The call @code{(make-adder 17)} returns a function object which adds
1495 17 to its argument. If @code{let} had been used instead of
1496 @code{lexical-let}, the function object would have referred to the
1497 global @code{n}, which would have been bound to 17 only during the
1498 call to @code{make-adder} itself.
1501 (defun make-counter ()
1502 (lexical-let ((n 0))
1503 (cl-function (lambda (&optional (m 1)) (cl-incf n m)))))
1504 (setq count-1 (make-counter))
1507 (funcall count-1 14)
1509 (setq count-2 (make-counter))
1519 Here we see that each call to @code{make-counter} creates a distinct
1520 local variable @code{n}, which serves as a private counter for the
1521 function object that is returned.
1523 Closed-over lexical variables persist until the last reference to
1524 them goes away, just like all other Lisp objects. For example,
1525 @code{count-2} refers to a function object which refers to an
1526 instance of the variable @code{n}; this is the only reference
1527 to that variable, so after @code{(setq count-2 nil)} the garbage
1528 collector would be able to delete this instance of @code{n}.
1529 Of course, if a @code{lexical-let} does not actually create any
1530 closures, then the lexical variables are free as soon as the
1531 @code{lexical-let} returns.
1533 Many closures are used only during the extent of the bindings they
1534 refer to; these are known as ``downward funargs'' in Lisp parlance.
1535 When a closure is used in this way, regular Emacs Lisp dynamic
1536 bindings suffice and will be more efficient than @code{lexical-let}
1540 (defun add-to-list (x list)
1541 (mapcar (lambda (y) (+ x y))) list)
1542 (add-to-list 7 '(1 2 5))
1547 Since this lambda is only used while @code{x} is still bound,
1548 it is not necessary to make a true closure out of it.
1550 You can use @code{defun} or @code{flet} inside a @code{lexical-let}
1551 to create a named closure. If several closures are created in the
1552 body of a single @code{lexical-let}, they all close over the same
1553 instance of the lexical variable.
1555 The @code{lexical-let} form is an extension to Common Lisp. In
1556 true Common Lisp, all bindings are lexical unless declared otherwise.
1559 @defmac lexical-let* (bindings@dots{}) forms@dots{}
1560 This form is just like @code{lexical-let}, except that the bindings
1561 are made sequentially in the manner of @code{let*}.
1564 @node Function Bindings
1565 @subsection Function Bindings
1568 These forms make @code{let}-like bindings to functions instead
1571 @defmac flet (bindings@dots{}) forms@dots{}
1572 This form establishes @code{let}-style bindings on the function
1573 cells of symbols rather than on the value cells. Each @var{binding}
1574 must be a list of the form @samp{(@var{name} @var{arglist}
1575 @var{forms}@dots{})}, which defines a function exactly as if
1576 it were a @code{cl-defun} form. The function @var{name} is defined
1577 accordingly for the duration of the body of the @code{flet}; then
1578 the old function definition, or lack thereof, is restored.
1580 While @code{flet} in Common Lisp establishes a lexical binding of
1581 @var{name}, Emacs Lisp @code{flet} makes a dynamic binding. The
1582 result is that @code{flet} affects indirect calls to a function as
1583 well as calls directly inside the @code{flet} form itself.
1585 You can use @code{flet} to disable or modify the behavior of a
1586 function in a temporary fashion. This will even work on Emacs
1587 primitives, although note that some calls to primitive functions
1588 internal to Emacs are made without going through the symbol's
1589 function cell, and so will not be affected by @code{flet}. For
1593 (flet ((message (&rest args) (push args saved-msgs)))
1597 This code attempts to replace the built-in function @code{message}
1598 with a function that simply saves the messages in a list rather
1599 than displaying them. The original definition of @code{message}
1600 will be restored after @code{do-something} exits. This code will
1601 work fine on messages generated by other Lisp code, but messages
1602 generated directly inside Emacs will not be caught since they make
1603 direct C-language calls to the message routines rather than going
1604 through the Lisp @code{message} function.
1607 Also note that many primitives (e.g. @code{+}) have special byte-compile
1608 handling. Attempts to redefine such functions using @code{flet} will
1609 fail if byte-compiled. In such cases, use @code{labels} instead.
1611 Functions defined by @code{flet} may use the full Common Lisp
1612 argument notation supported by @code{cl-defun}; also, the function
1613 body is enclosed in an implicit block as if by @code{cl-defun}.
1614 @xref{Program Structure}.
1617 @defmac labels (bindings@dots{}) forms@dots{}
1618 The @code{labels} form is like @code{flet}, except that it
1619 makes lexical bindings of the function names rather than
1620 dynamic bindings. (In true Common Lisp, both @code{flet} and
1621 @code{labels} make lexical bindings of slightly different sorts;
1622 since Emacs Lisp is dynamically bound by default, it seemed
1623 more appropriate for @code{flet} also to use dynamic binding.
1624 The @code{labels} form, with its lexical binding, is fully
1625 compatible with Common Lisp.)
1627 Lexical scoping means that all references to the named
1628 functions must appear physically within the body of the
1629 @code{labels} form. References may appear both in the body
1630 @var{forms} of @code{labels} itself, and in the bodies of
1631 the functions themselves. Thus, @code{labels} can define
1632 local recursive functions, or mutually-recursive sets of
1635 A ``reference'' to a function name is either a call to that
1636 function, or a use of its name quoted by @code{quote} or
1637 @code{function} to be passed on to, say, @code{mapcar}.
1640 @node Macro Bindings
1641 @subsection Macro Bindings
1644 These forms create local macros and ``symbol macros''.
1646 @defmac cl-macrolet (bindings@dots{}) forms@dots{}
1647 This form is analogous to @code{flet}, but for macros instead of
1648 functions. Each @var{binding} is a list of the same form as the
1649 arguments to @code{cl-defmacro} (i.e., a macro name, argument list,
1650 and macro-expander forms). The macro is defined accordingly for
1651 use within the body of the @code{cl-macrolet}.
1653 Because of the nature of macros, @code{cl-macrolet} is lexically
1654 scoped even in Emacs Lisp: The @code{cl-macrolet} binding will
1655 affect only calls that appear physically within the body
1656 @var{forms}, possibly after expansion of other macros in the
1660 @defmac cl-symbol-macrolet (bindings@dots{}) forms@dots{}
1661 This form creates @dfn{symbol macros}, which are macros that look
1662 like variable references rather than function calls. Each
1663 @var{binding} is a list @samp{(@var{var} @var{expansion})};
1664 any reference to @var{var} within the body @var{forms} is
1665 replaced by @var{expansion}.
1669 (cl-symbol-macrolet ((foo (car bar)))
1675 A @code{setq} of a symbol macro is treated the same as a @code{setf}.
1676 I.e., @code{(setq foo 4)} in the above would be equivalent to
1677 @code{(setf foo 4)}, which in turn expands to @code{(setf (car bar) 4)}.
1679 Likewise, a @code{let} or @code{let*} binding a symbol macro is
1680 treated like a @code{letf} or @code{cl-letf*}. This differs from true
1681 Common Lisp, where the rules of lexical scoping cause a @code{let}
1682 binding to shadow a @code{cl-symbol-macrolet} binding. In this package,
1683 only @code{lexical-let} and @code{lexical-let*} will shadow a symbol
1686 There is no analogue of @code{defmacro} for symbol macros; all symbol
1687 macros are local. A typical use of @code{cl-symbol-macrolet} is in the
1688 expansion of another macro:
1691 (cl-defmacro my-dolist ((x list) &rest body)
1692 (let ((var (gensym)))
1693 (list 'cl-loop 'for var 'on list 'do
1694 (cl-list* 'cl-symbol-macrolet
1695 (list (list x (list 'car var)))
1698 (setq mylist '(1 2 3 4))
1699 (my-dolist (x mylist) (cl-incf x))
1705 In this example, the @code{my-dolist} macro is similar to @code{dolist}
1706 (@pxref{Iteration}) except that the variable @code{x} becomes a true
1707 reference onto the elements of the list. The @code{my-dolist} call
1708 shown here expands to
1711 (cl-loop for G1234 on mylist do
1712 (cl-symbol-macrolet ((x (car G1234)))
1717 which in turn expands to
1720 (cl-loop for G1234 on mylist do (cl-incf (car G1234)))
1723 @xref{Loop Facility}, for a description of the @code{cl-loop} macro.
1724 This package defines a nonstandard @code{in-ref} loop clause that
1725 works much like @code{my-dolist}.
1729 @section Conditionals
1732 These conditional forms augment Emacs Lisp's simple @code{if},
1733 @code{and}, @code{or}, and @code{cond} forms.
1735 @defmac cl-case keyform clause@dots{}
1736 This macro evaluates @var{keyform}, then compares it with the key
1737 values listed in the various @var{clause}s. Whichever clause matches
1738 the key is executed; comparison is done by @code{eql}. If no clause
1739 matches, the @code{cl-case} form returns @code{nil}. The clauses are
1743 (@var{keylist} @var{body-forms}@dots{})
1747 where @var{keylist} is a list of key values. If there is exactly
1748 one value, and it is not a cons cell or the symbol @code{nil} or
1749 @code{t}, then it can be used by itself as a @var{keylist} without
1750 being enclosed in a list. All key values in the @code{cl-case} form
1751 must be distinct. The final clauses may use @code{t} in place of
1752 a @var{keylist} to indicate a default clause that should be taken
1753 if none of the other clauses match. (The symbol @code{otherwise}
1754 is also recognized in place of @code{t}. To make a clause that
1755 matches the actual symbol @code{t}, @code{nil}, or @code{otherwise},
1756 enclose the symbol in a list.)
1758 For example, this expression reads a keystroke, then does one of
1759 four things depending on whether it is an @samp{a}, a @samp{b},
1760 a @key{RET} or @kbd{C-j}, or anything else.
1763 (cl-case (read-char)
1766 ((?\r ?\n) (do-ret-thing))
1767 (t (do-other-thing)))
1771 @defmac cl-ecase keyform clause@dots{}
1772 This macro is just like @code{cl-case}, except that if the key does
1773 not match any of the clauses, an error is signaled rather than
1774 simply returning @code{nil}.
1777 @defmac cl-typecase keyform clause@dots{}
1778 This macro is a version of @code{cl-case} that checks for types
1779 rather than values. Each @var{clause} is of the form
1780 @samp{(@var{type} @var{body}...)}. @xref{Type Predicates},
1781 for a description of type specifiers. For example,
1785 (integer (munch-integer x))
1786 (float (munch-float x))
1787 (string (munch-integer (string-to-int x)))
1788 (t (munch-anything x)))
1791 The type specifier @code{t} matches any type of object; the word
1792 @code{otherwise} is also allowed. To make one clause match any of
1793 several types, use an @code{(or ...)} type specifier.
1796 @defmac cl-etypecase keyform clause@dots{}
1797 This macro is just like @code{cl-typecase}, except that if the key does
1798 not match any of the clauses, an error is signaled rather than
1799 simply returning @code{nil}.
1802 @node Blocks and Exits
1803 @section Blocks and Exits
1806 Common Lisp @dfn{blocks} provide a non-local exit mechanism very
1807 similar to @code{catch} and @code{throw}, but lexically rather than
1808 dynamically scoped. This package actually implements @code{cl-block}
1809 in terms of @code{catch}; however, the lexical scoping allows the
1810 optimizing byte-compiler to omit the costly @code{catch} step if the
1811 body of the block does not actually @code{cl-return-from} the block.
1813 @defmac cl-block name forms@dots{}
1814 The @var{forms} are evaluated as if by a @code{progn}. However,
1815 if any of the @var{forms} execute @code{(cl-return-from @var{name})},
1816 they will jump out and return directly from the @code{cl-block} form.
1817 The @code{cl-block} returns the result of the last @var{form} unless
1818 a @code{cl-return-from} occurs.
1820 The @code{cl-block}/@code{cl-return-from} mechanism is quite similar to
1821 the @code{catch}/@code{throw} mechanism. The main differences are
1822 that block @var{name}s are unevaluated symbols, rather than forms
1823 (such as quoted symbols) which evaluate to a tag at run-time; and
1824 also that blocks are lexically scoped whereas @code{catch}/@code{throw}
1825 are dynamically scoped. This means that functions called from the
1826 body of a @code{catch} can also @code{throw} to the @code{catch},
1827 but the @code{cl-return-from} referring to a block name must appear
1828 physically within the @var{forms} that make up the body of the block.
1829 They may not appear within other called functions, although they may
1830 appear within macro expansions or @code{lambda}s in the body. Block
1831 names and @code{catch} names form independent name-spaces.
1833 In true Common Lisp, @code{defun} and @code{defmacro} surround
1834 the function or expander bodies with implicit blocks with the
1835 same name as the function or macro. This does not occur in Emacs
1836 Lisp, but this package provides @code{cl-defun} and @code{cl-defmacro}
1837 forms which do create the implicit block.
1839 The Common Lisp looping constructs defined by this package,
1840 such as @code{cl-loop} and @code{cl-dolist}, also create implicit blocks
1841 just as in Common Lisp.
1843 Because they are implemented in terms of Emacs Lisp @code{catch}
1844 and @code{throw}, blocks have the same overhead as actual
1845 @code{catch} constructs (roughly two function calls). However,
1846 the optimizing byte compiler will optimize away the @code{catch}
1848 not in fact contain any @code{cl-return} or @code{cl-return-from} calls
1849 that jump to it. This means that @code{cl-do} loops and @code{cl-defun}
1850 functions which don't use @code{cl-return} don't pay the overhead to
1854 @defmac cl-return-from name [result]
1855 This macro returns from the block named @var{name}, which must be
1856 an (unevaluated) symbol. If a @var{result} form is specified, it
1857 is evaluated to produce the result returned from the @code{block}.
1858 Otherwise, @code{nil} is returned.
1861 @defmac cl-return [result]
1862 This macro is exactly like @code{(cl-return-from nil @var{result})}.
1863 Common Lisp loops like @code{cl-do} and @code{cl-dolist} implicitly enclose
1864 themselves in @code{nil} blocks.
1871 The macros described here provide more sophisticated, high-level
1872 looping constructs to complement Emacs Lisp's basic @code{while}
1875 @defmac cl-loop forms@dots{}
1876 The @code{CL} package supports both the simple, old-style meaning of
1877 @code{loop} and the extremely powerful and flexible feature known as
1878 the @dfn{Loop Facility} or @dfn{Loop Macro}. This more advanced
1879 facility is discussed in the following section; @pxref{Loop Facility}.
1880 The simple form of @code{loop} is described here.
1882 If @code{cl-loop} is followed by zero or more Lisp expressions,
1883 then @code{(cl-loop @var{exprs}@dots{})} simply creates an infinite
1884 loop executing the expressions over and over. The loop is
1885 enclosed in an implicit @code{nil} block. Thus,
1888 (cl-loop (foo) (if (no-more) (return 72)) (bar))
1892 is exactly equivalent to
1895 (cl-block nil (while t (foo) (if (no-more) (return 72)) (bar)))
1898 If any of the expressions are plain symbols, the loop is instead
1899 interpreted as a Loop Macro specification as described later.
1900 (This is not a restriction in practice, since a plain symbol
1901 in the above notation would simply access and throw away the
1902 value of a variable.)
1905 @defmac cl-do (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
1906 This macro creates a general iterative loop. Each @var{spec} is
1910 (@var{var} [@var{init} [@var{step}]])
1913 The loop works as follows: First, each @var{var} is bound to the
1914 associated @var{init} value as if by a @code{let} form. Then, in
1915 each iteration of the loop, the @var{end-test} is evaluated; if
1916 true, the loop is finished. Otherwise, the body @var{forms} are
1917 evaluated, then each @var{var} is set to the associated @var{step}
1918 expression (as if by a @code{cl-psetq} form) and the next iteration
1919 begins. Once the @var{end-test} becomes true, the @var{result}
1920 forms are evaluated (with the @var{var}s still bound to their
1921 values) to produce the result returned by @code{cl-do}.
1923 The entire @code{cl-do} loop is enclosed in an implicit @code{nil}
1924 block, so that you can use @code{(cl-return)} to break out of the
1927 If there are no @var{result} forms, the loop returns @code{nil}.
1928 If a given @var{var} has no @var{step} form, it is bound to its
1929 @var{init} value but not otherwise modified during the @code{cl-do}
1930 loop (unless the code explicitly modifies it); this case is just
1931 a shorthand for putting a @code{(let ((@var{var} @var{init})) @dots{})}
1932 around the loop. If @var{init} is also omitted it defaults to
1933 @code{nil}, and in this case a plain @samp{@var{var}} can be used
1934 in place of @samp{(@var{var})}, again following the analogy with
1937 This example (from Steele) illustrates a loop which applies the
1938 function @code{f} to successive pairs of values from the lists
1939 @code{foo} and @code{bar}; it is equivalent to the call
1940 @code{(cl-mapcar 'f foo bar)}. Note that this loop has no body
1941 @var{forms} at all, performing all its work as side effects of
1942 the rest of the loop.
1945 (cl-do ((x foo (cdr x))
1947 (z nil (cons (f (car x) (car y)) z)))
1948 ((or (null x) (null y))
1953 @defmac cl-do* (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
1954 This is to @code{cl-do} what @code{let*} is to @code{let}. In
1955 particular, the initial values are bound as if by @code{let*}
1956 rather than @code{let}, and the steps are assigned as if by
1957 @code{setq} rather than @code{cl-psetq}.
1959 Here is another way to write the above loop:
1962 (cl-do* ((xp foo (cdr xp))
1964 (x (car xp) (car xp))
1965 (y (car yp) (car yp))
1967 ((or (null xp) (null yp))
1973 @defmac cl-dolist (var list [result]) forms@dots{}
1974 This is a more specialized loop which iterates across the elements
1975 of a list. @var{list} should evaluate to a list; the body @var{forms}
1976 are executed with @var{var} bound to each element of the list in
1977 turn. Finally, the @var{result} form (or @code{nil}) is evaluated
1978 with @var{var} bound to @code{nil} to produce the result returned by
1979 the loop. Unlike with Emacs's built in @code{dolist}, the loop is
1980 surrounded by an implicit @code{nil} block.
1983 @defmac cl-dotimes (var count [result]) forms@dots{}
1984 This is a more specialized loop which iterates a specified number
1985 of times. The body is executed with @var{var} bound to the integers
1986 from zero (inclusive) to @var{count} (exclusive), in turn. Then
1987 the @code{result} form is evaluated with @var{var} bound to the total
1988 number of iterations that were done (i.e., @code{(max 0 @var{count})})
1989 to get the return value for the loop form. Unlike with Emacs's built in
1990 @code{dolist}, the loop is surrounded by an implicit @code{nil} block.
1993 @defmac cl-do-symbols (var [obarray [result]]) forms@dots{}
1994 This loop iterates over all interned symbols. If @var{obarray}
1995 is specified and is not @code{nil}, it loops over all symbols in
1996 that obarray. For each symbol, the body @var{forms} are evaluated
1997 with @var{var} bound to that symbol. The symbols are visited in
1998 an unspecified order. Afterward the @var{result} form, if any,
1999 is evaluated (with @var{var} bound to @code{nil}) to get the return
2000 value. The loop is surrounded by an implicit @code{nil} block.
2003 @defmac cl-do-all-symbols (var [result]) forms@dots{}
2004 This is identical to @code{cl-do-symbols} except that the @var{obarray}
2005 argument is omitted; it always iterates over the default obarray.
2008 @xref{Mapping over Sequences}, for some more functions for
2009 iterating over vectors or lists.
2012 @section Loop Facility
2015 A common complaint with Lisp's traditional looping constructs is
2016 that they are either too simple and limited, such as Common Lisp's
2017 @code{dotimes} or Emacs Lisp's @code{while}, or too unreadable and
2018 obscure, like Common Lisp's @code{do} loop.
2020 To remedy this, recent versions of Common Lisp have added a new
2021 construct called the ``Loop Facility'' or ``@code{loop} macro'',
2022 with an easy-to-use but very powerful and expressive syntax.
2025 * Loop Basics:: @code{cl-loop} macro, basic clause structure.
2026 * Loop Examples:: Working examples of @code{cl-loop} macro.
2027 * For Clauses:: Clauses introduced by @code{for} or @code{as}.
2028 * Iteration Clauses:: @code{repeat}, @code{while}, @code{thereis}, etc.
2029 * Accumulation Clauses:: @code{collect}, @code{sum}, @code{maximize}, etc.
2030 * Other Clauses:: @code{with}, @code{if}, @code{initially}, @code{finally}.
2034 @subsection Loop Basics
2037 The @code{cl-loop} macro essentially creates a mini-language within
2038 Lisp that is specially tailored for describing loops. While this
2039 language is a little strange-looking by the standards of regular Lisp,
2040 it turns out to be very easy to learn and well-suited to its purpose.
2042 Since @code{cl-loop} is a macro, all parsing of the loop language
2043 takes place at byte-compile time; compiled @code{cl-loop}s are just
2044 as efficient as the equivalent @code{while} loops written longhand.
2046 @defmac cl-loop clauses@dots{}
2047 A loop construct consists of a series of @var{clause}s, each
2048 introduced by a symbol like @code{for} or @code{do}. Clauses
2049 are simply strung together in the argument list of @code{cl-loop},
2050 with minimal extra parentheses. The various types of clauses
2051 specify initializations, such as the binding of temporary
2052 variables, actions to be taken in the loop, stepping actions,
2055 Common Lisp specifies a certain general order of clauses in a
2059 (cl-loop @var{name-clause}
2060 @var{var-clauses}@dots{}
2061 @var{action-clauses}@dots{})
2064 The @var{name-clause} optionally gives a name to the implicit
2065 block that surrounds the loop. By default, the implicit block
2066 is named @code{nil}. The @var{var-clauses} specify what
2067 variables should be bound during the loop, and how they should
2068 be modified or iterated throughout the course of the loop. The
2069 @var{action-clauses} are things to be done during the loop, such
2070 as computing, collecting, and returning values.
2072 The Emacs version of the @code{cl-loop} macro is less restrictive about
2073 the order of clauses, but things will behave most predictably if
2074 you put the variable-binding clauses @code{with}, @code{for}, and
2075 @code{repeat} before the action clauses. As in Common Lisp,
2076 @code{initially} and @code{finally} clauses can go anywhere.
2078 Loops generally return @code{nil} by default, but you can cause
2079 them to return a value by using an accumulation clause like
2080 @code{collect}, an end-test clause like @code{always}, or an
2081 explicit @code{return} clause to jump out of the implicit block.
2082 (Because the loop body is enclosed in an implicit block, you can
2083 also use regular Lisp @code{cl-return} or @code{cl-return-from} to
2084 break out of the loop.)
2087 The following sections give some examples of the Loop Macro in
2088 action, and describe the particular loop clauses in great detail.
2089 Consult the second edition of Steele's @dfn{Common Lisp, the Language},
2090 for additional discussion and examples of the @code{loop} macro.
2093 @subsection Loop Examples
2096 Before listing the full set of clauses that are allowed, let's
2097 look at a few example loops just to get a feel for the @code{cl-loop}
2101 (cl-loop for buf in (buffer-list)
2102 collect (buffer-file-name buf))
2106 This loop iterates over all Emacs buffers, using the list
2107 returned by @code{buffer-list}. For each buffer @var{buf},
2108 it calls @code{buffer-file-name} and collects the results into
2109 a list, which is then returned from the @code{cl-loop} construct.
2110 The result is a list of the file names of all the buffers in
2111 Emacs's memory. The words @code{for}, @code{in}, and @code{collect}
2112 are reserved words in the @code{cl-loop} language.
2115 (cl-loop repeat 20 do (insert "Yowsa\n"))
2119 This loop inserts the phrase ``Yowsa'' twenty times in the
2123 (cl-loop until (eobp) do (munch-line) (forward-line 1))
2127 This loop calls @code{munch-line} on every line until the end
2128 of the buffer. If point is already at the end of the buffer,
2129 the loop exits immediately.
2132 (cl-loop do (munch-line) until (eobp) do (forward-line 1))
2136 This loop is similar to the above one, except that @code{munch-line}
2137 is always called at least once.
2140 (cl-loop for x from 1 to 100
2143 finally return (list x (= y 729)))
2147 This more complicated loop searches for a number @code{x} whose
2148 square is 729. For safety's sake it only examines @code{x}
2149 values up to 100; dropping the phrase @samp{to 100} would
2150 cause the loop to count upwards with no limit. The second
2151 @code{for} clause defines @code{y} to be the square of @code{x}
2152 within the loop; the expression after the @code{=} sign is
2153 reevaluated each time through the loop. The @code{until}
2154 clause gives a condition for terminating the loop, and the
2155 @code{finally} clause says what to do when the loop finishes.
2156 (This particular example was written less concisely than it
2157 could have been, just for the sake of illustration.)
2159 Note that even though this loop contains three clauses (two
2160 @code{for}s and an @code{until}) that would have been enough to
2161 define loops all by themselves, it still creates a single loop
2162 rather than some sort of triple-nested loop. You must explicitly
2163 nest your @code{cl-loop} constructs if you want nested loops.
2166 @subsection For Clauses
2169 Most loops are governed by one or more @code{for} clauses.
2170 A @code{for} clause simultaneously describes variables to be
2171 bound, how those variables are to be stepped during the loop,
2172 and usually an end condition based on those variables.
2174 The word @code{as} is a synonym for the word @code{for}. This
2175 word is followed by a variable name, then a word like @code{from}
2176 or @code{across} that describes the kind of iteration desired.
2177 In Common Lisp, the phrase @code{being the} sometimes precedes
2178 the type of iteration; in this package both @code{being} and
2179 @code{the} are optional. The word @code{each} is a synonym
2180 for @code{the}, and the word that follows it may be singular
2181 or plural: @samp{for x being the elements of y} or
2182 @samp{for x being each element of y}. Which form you use
2183 is purely a matter of style.
2185 The variable is bound around the loop as if by @code{let}:
2189 (cl-loop for i from 1 to 10 do (do-something-with i))
2195 @item for @var{var} from @var{expr1} to @var{expr2} by @var{expr3}
2196 This type of @code{for} clause creates a counting loop. Each of
2197 the three sub-terms is optional, though there must be at least one
2198 term so that the clause is marked as a counting clause.
2200 The three expressions are the starting value, the ending value, and
2201 the step value, respectively, of the variable. The loop counts
2202 upwards by default (@var{expr3} must be positive), from @var{expr1}
2203 to @var{expr2} inclusively. If you omit the @code{from} term, the
2204 loop counts from zero; if you omit the @code{to} term, the loop
2205 counts forever without stopping (unless stopped by some other
2206 loop clause, of course); if you omit the @code{by} term, the loop
2207 counts in steps of one.
2209 You can replace the word @code{from} with @code{upfrom} or
2210 @code{downfrom} to indicate the direction of the loop. Likewise,
2211 you can replace @code{to} with @code{upto} or @code{downto}.
2212 For example, @samp{for x from 5 downto 1} executes five times
2213 with @code{x} taking on the integers from 5 down to 1 in turn.
2214 Also, you can replace @code{to} with @code{below} or @code{above},
2215 which are like @code{upto} and @code{downto} respectively except
2216 that they are exclusive rather than inclusive limits:
2219 (cl-loop for x to 10 collect x)
2220 @result{} (0 1 2 3 4 5 6 7 8 9 10)
2221 (cl-loop for x below 10 collect x)
2222 @result{} (0 1 2 3 4 5 6 7 8 9)
2225 The @code{by} value is always positive, even for downward-counting
2226 loops. Some sort of @code{from} value is required for downward
2227 loops; @samp{for x downto 5} is not a valid loop clause all by
2230 @item for @var{var} in @var{list} by @var{function}
2231 This clause iterates @var{var} over all the elements of @var{list},
2232 in turn. If you specify the @code{by} term, then @var{function}
2233 is used to traverse the list instead of @code{cdr}; it must be a
2234 function taking one argument. For example:
2237 (cl-loop for x in '(1 2 3 4 5 6) collect (* x x))
2238 @result{} (1 4 9 16 25 36)
2239 (cl-loop for x in '(1 2 3 4 5 6) by 'cddr collect (* x x))
2243 @item for @var{var} on @var{list} by @var{function}
2244 This clause iterates @var{var} over all the cons cells of @var{list}.
2247 (cl-loop for x on '(1 2 3 4) collect x)
2248 @result{} ((1 2 3 4) (2 3 4) (3 4) (4))
2251 With @code{by}, there is no real reason that the @code{on} expression
2252 must be a list. For example:
2255 (cl-loop for x on first-animal by 'next-animal collect x)
2259 where @code{(next-animal x)} takes an ``animal'' @var{x} and returns
2260 the next in the (assumed) sequence of animals, or @code{nil} if
2261 @var{x} was the last animal in the sequence.
2263 @item for @var{var} in-ref @var{list} by @var{function}
2264 This is like a regular @code{in} clause, but @var{var} becomes
2265 a @code{setf}-able ``reference'' onto the elements of the list
2266 rather than just a temporary variable. For example,
2269 (cl-loop for x in-ref my-list do (cl-incf x))
2273 increments every element of @code{my-list} in place. This clause
2274 is an extension to standard Common Lisp.
2276 @item for @var{var} across @var{array}
2277 This clause iterates @var{var} over all the elements of @var{array},
2278 which may be a vector or a string.
2281 (cl-loop for x across "aeiou"
2282 do (use-vowel (char-to-string x)))
2285 @item for @var{var} across-ref @var{array}
2286 This clause iterates over an array, with @var{var} a @code{setf}-able
2287 reference onto the elements; see @code{in-ref} above.
2289 @item for @var{var} being the elements of @var{sequence}
2290 This clause iterates over the elements of @var{sequence}, which may
2291 be a list, vector, or string. Since the type must be determined
2292 at run-time, this is somewhat less efficient than @code{in} or
2293 @code{across}. The clause may be followed by the additional term
2294 @samp{using (index @var{var2})} to cause @var{var2} to be bound to
2295 the successive indices (starting at 0) of the elements.
2297 This clause type is taken from older versions of the @code{loop} macro,
2298 and is not present in modern Common Lisp. The @samp{using (sequence ...)}
2299 term of the older macros is not supported.
2301 @item for @var{var} being the elements of-ref @var{sequence}
2302 This clause iterates over a sequence, with @var{var} a @code{setf}-able
2303 reference onto the elements; see @code{in-ref} above.
2305 @item for @var{var} being the symbols [of @var{obarray}]
2306 This clause iterates over symbols, either over all interned symbols
2307 or over all symbols in @var{obarray}. The loop is executed with
2308 @var{var} bound to each symbol in turn. The symbols are visited in
2309 an unspecified order.
2314 (cl-loop for sym being the symbols
2316 when (string-match "^map" (symbol-name sym))
2321 returns a list of all the functions whose names begin with @samp{map}.
2323 The Common Lisp words @code{external-symbols} and @code{present-symbols}
2324 are also recognized but are equivalent to @code{symbols} in Emacs Lisp.
2326 Due to a minor implementation restriction, it will not work to have
2327 more than one @code{for} clause iterating over symbols, hash tables,
2328 keymaps, overlays, or intervals in a given @code{cl-loop}. Fortunately,
2329 it would rarely if ever be useful to do so. It @emph{is} valid to mix
2330 one of these types of clauses with other clauses like @code{for ... to}
2333 @item for @var{var} being the hash-keys of @var{hash-table}
2334 @itemx for @var{var} being the hash-values of @var{hash-table}
2335 This clause iterates over the entries in @var{hash-table} with
2336 @var{var} bound to each key, or value. A @samp{using} clause can bind
2337 a second variable to the opposite part.
2340 (cl-loop for k being the hash-keys of h
2341 using (hash-values v)
2343 (message "key %S -> value %S" k v))
2346 @item for @var{var} being the key-codes of @var{keymap}
2347 @itemx for @var{var} being the key-bindings of @var{keymap}
2348 This clause iterates over the entries in @var{keymap}.
2349 The iteration does not enter nested keymaps but does enter inherited
2351 A @code{using} clause can access both the codes and the bindings
2355 (cl-loop for c being the key-codes of (current-local-map)
2356 using (key-bindings b)
2358 (message "key %S -> binding %S" c b))
2362 @item for @var{var} being the key-seqs of @var{keymap}
2363 This clause iterates over all key sequences defined by @var{keymap}
2364 and its nested keymaps, where @var{var} takes on values which are
2365 vectors. The strings or vectors
2366 are reused for each iteration, so you must copy them if you wish to keep
2367 them permanently. You can add a @samp{using (key-bindings ...)}
2368 clause to get the command bindings as well.
2370 @item for @var{var} being the overlays [of @var{buffer}] @dots{}
2371 This clause iterates over the ``overlays'' of a buffer
2372 (the clause @code{extents} is synonymous
2373 with @code{overlays}). If the @code{of} term is omitted, the current
2375 This clause also accepts optional @samp{from @var{pos}} and
2376 @samp{to @var{pos}} terms, limiting the clause to overlays which
2377 overlap the specified region.
2379 @item for @var{var} being the intervals [of @var{buffer}] @dots{}
2380 This clause iterates over all intervals of a buffer with constant
2381 text properties. The variable @var{var} will be bound to conses
2382 of start and end positions, where one start position is always equal
2383 to the previous end position. The clause allows @code{of},
2384 @code{from}, @code{to}, and @code{property} terms, where the latter
2385 term restricts the search to just the specified property. The
2386 @code{of} term may specify either a buffer or a string.
2388 @item for @var{var} being the frames
2389 This clause iterates over all Emacs frames. The clause @code{screens} is
2390 a synonym for @code{frames}. The frames are visited in
2391 @code{next-frame} order starting from @code{selected-frame}.
2393 @item for @var{var} being the windows [of @var{frame}]
2394 This clause iterates over the windows (in the Emacs sense) of
2395 the current frame, or of the specified @var{frame}. It visits windows
2396 in @code{next-window} order starting from @code{selected-window}
2397 (or @code{frame-selected-window} if you specify @var{frame}).
2398 This clause treats the minibuffer window in the same way as
2399 @code{next-window} does. For greater flexibility, consider using
2400 @code{walk-windows} instead.
2402 @item for @var{var} being the buffers
2403 This clause iterates over all buffers in Emacs. It is equivalent
2404 to @samp{for @var{var} in (buffer-list)}.
2406 @item for @var{var} = @var{expr1} then @var{expr2}
2407 This clause does a general iteration. The first time through
2408 the loop, @var{var} will be bound to @var{expr1}. On the second
2409 and successive iterations it will be set by evaluating @var{expr2}
2410 (which may refer to the old value of @var{var}). For example,
2411 these two loops are effectively the same:
2414 (cl-loop for x on my-list by 'cddr do ...)
2415 (cl-loop for x = my-list then (cddr x) while x do ...)
2418 Note that this type of @code{for} clause does not imply any sort
2419 of terminating condition; the above example combines it with a
2420 @code{while} clause to tell when to end the loop.
2422 If you omit the @code{then} term, @var{expr1} is used both for
2423 the initial setting and for successive settings:
2426 (cl-loop for x = (random) when (> x 0) return x)
2430 This loop keeps taking random numbers from the @code{(random)}
2431 function until it gets a positive one, which it then returns.
2434 If you include several @code{for} clauses in a row, they are
2435 treated sequentially (as if by @code{let*} and @code{setq}).
2436 You can instead use the word @code{and} to link the clauses,
2437 in which case they are processed in parallel (as if by @code{let}
2438 and @code{cl-psetq}).
2441 (cl-loop for x below 5 for y = nil then x collect (list x y))
2442 @result{} ((0 nil) (1 1) (2 2) (3 3) (4 4))
2443 (cl-loop for x below 5 and y = nil then x collect (list x y))
2444 @result{} ((0 nil) (1 0) (2 1) (3 2) (4 3))
2448 In the first loop, @code{y} is set based on the value of @code{x}
2449 that was just set by the previous clause; in the second loop,
2450 @code{x} and @code{y} are set simultaneously so @code{y} is set
2451 based on the value of @code{x} left over from the previous time
2454 Another feature of the @code{cl-loop} macro is @dfn{destructuring},
2455 similar in concept to the destructuring provided by @code{defmacro}.
2456 The @var{var} part of any @code{for} clause can be given as a list
2457 of variables instead of a single variable. The values produced
2458 during loop execution must be lists; the values in the lists are
2459 stored in the corresponding variables.
2462 (cl-loop for (x y) in '((2 3) (4 5) (6 7)) collect (+ x y))
2466 In loop destructuring, if there are more values than variables
2467 the trailing values are ignored, and if there are more variables
2468 than values the trailing variables get the value @code{nil}.
2469 If @code{nil} is used as a variable name, the corresponding
2470 values are ignored. Destructuring may be nested, and dotted
2471 lists of variables like @code{(x . y)} are allowed, so for example
2475 (cl-loop for (key . value) in '((a . 1) (b . 2))
2480 @node Iteration Clauses
2481 @subsection Iteration Clauses
2484 Aside from @code{for} clauses, there are several other loop clauses
2485 that control the way the loop operates. They might be used by
2486 themselves, or in conjunction with one or more @code{for} clauses.
2489 @item repeat @var{integer}
2490 This clause simply counts up to the specified number using an
2491 internal temporary variable. The loops
2494 (cl-loop repeat (1+ n) do ...)
2495 (cl-loop for temp to n do ...)
2499 are identical except that the second one forces you to choose
2500 a name for a variable you aren't actually going to use.
2502 @item while @var{condition}
2503 This clause stops the loop when the specified condition (any Lisp
2504 expression) becomes @code{nil}. For example, the following two
2505 loops are equivalent, except for the implicit @code{nil} block
2506 that surrounds the second one:
2509 (while @var{cond} @var{forms}@dots{})
2510 (cl-loop while @var{cond} do @var{forms}@dots{})
2513 @item until @var{condition}
2514 This clause stops the loop when the specified condition is true,
2515 i.e., non-@code{nil}.
2517 @item always @var{condition}
2518 This clause stops the loop when the specified condition is @code{nil}.
2519 Unlike @code{while}, it stops the loop using @code{return nil} so that
2520 the @code{finally} clauses are not executed. If all the conditions
2521 were non-@code{nil}, the loop returns @code{t}:
2524 (if (cl-loop for size in size-list always (> size 10))
2529 @item never @var{condition}
2530 This clause is like @code{always}, except that the loop returns
2531 @code{t} if any conditions were false, or @code{nil} otherwise.
2533 @item thereis @var{condition}
2534 This clause stops the loop when the specified form is non-@code{nil};
2535 in this case, it returns that non-@code{nil} value. If all the
2536 values were @code{nil}, the loop returns @code{nil}.
2539 @node Accumulation Clauses
2540 @subsection Accumulation Clauses
2543 These clauses cause the loop to accumulate information about the
2544 specified Lisp @var{form}. The accumulated result is returned
2545 from the loop unless overridden, say, by a @code{return} clause.
2548 @item collect @var{form}
2549 This clause collects the values of @var{form} into a list. Several
2550 examples of @code{collect} appear elsewhere in this manual.
2552 The word @code{collecting} is a synonym for @code{collect}, and
2553 likewise for the other accumulation clauses.
2555 @item append @var{form}
2556 This clause collects lists of values into a result list using
2559 @item nconc @var{form}
2560 This clause collects lists of values into a result list by
2561 destructively modifying the lists rather than copying them.
2563 @item concat @var{form}
2564 This clause concatenates the values of the specified @var{form}
2565 into a string. (It and the following clause are extensions to
2566 standard Common Lisp.)
2568 @item vconcat @var{form}
2569 This clause concatenates the values of the specified @var{form}
2572 @item count @var{form}
2573 This clause counts the number of times the specified @var{form}
2574 evaluates to a non-@code{nil} value.
2576 @item sum @var{form}
2577 This clause accumulates the sum of the values of the specified
2578 @var{form}, which must evaluate to a number.
2580 @item maximize @var{form}
2581 This clause accumulates the maximum value of the specified @var{form},
2582 which must evaluate to a number. The return value is undefined if
2583 @code{maximize} is executed zero times.
2585 @item minimize @var{form}
2586 This clause accumulates the minimum value of the specified @var{form}.
2589 Accumulation clauses can be followed by @samp{into @var{var}} to
2590 cause the data to be collected into variable @var{var} (which is
2591 automatically @code{let}-bound during the loop) rather than an
2592 unnamed temporary variable. Also, @code{into} accumulations do
2593 not automatically imply a return value. The loop must use some
2594 explicit mechanism, such as @code{finally return}, to return
2595 the accumulated result.
2597 It is valid for several accumulation clauses of the same type to
2598 accumulate into the same place. From Steele:
2601 (cl-loop for name in '(fred sue alice joe june)
2602 for kids in '((bob ken) () () (kris sunshine) ())
2605 @result{} (fred bob ken sue alice joe kris sunshine june)
2609 @subsection Other Clauses
2612 This section describes the remaining loop clauses.
2615 @item with @var{var} = @var{value}
2616 This clause binds a variable to a value around the loop, but
2617 otherwise leaves the variable alone during the loop. The following
2618 loops are basically equivalent:
2621 (cl-loop with x = 17 do ...)
2622 (let ((x 17)) (cl-loop do ...))
2623 (cl-loop for x = 17 then x do ...)
2626 Naturally, the variable @var{var} might be used for some purpose
2627 in the rest of the loop. For example:
2630 (cl-loop for x in my-list with res = nil do (push x res)
2634 This loop inserts the elements of @code{my-list} at the front of
2635 a new list being accumulated in @code{res}, then returns the
2636 list @code{res} at the end of the loop. The effect is similar
2637 to that of a @code{collect} clause, but the list gets reversed
2638 by virtue of the fact that elements are being pushed onto the
2639 front of @code{res} rather than the end.
2641 If you omit the @code{=} term, the variable is initialized to
2642 @code{nil}. (Thus the @samp{= nil} in the above example is
2645 Bindings made by @code{with} are sequential by default, as if
2646 by @code{let*}. Just like @code{for} clauses, @code{with} clauses
2647 can be linked with @code{and} to cause the bindings to be made by
2650 @item if @var{condition} @var{clause}
2651 This clause executes the following loop clause only if the specified
2652 condition is true. The following @var{clause} should be an accumulation,
2653 @code{do}, @code{return}, @code{if}, or @code{unless} clause.
2654 Several clauses may be linked by separating them with @code{and}.
2655 These clauses may be followed by @code{else} and a clause or clauses
2656 to execute if the condition was false. The whole construct may
2657 optionally be followed by the word @code{end} (which may be used to
2658 disambiguate an @code{else} or @code{and} in a nested @code{if}).
2660 The actual non-@code{nil} value of the condition form is available
2661 by the name @code{it} in the ``then'' part. For example:
2664 (setq funny-numbers '(6 13 -1))
2666 (cl-loop for x below 10
2669 and if (memq x funny-numbers) return (cdr it) end
2671 collect x into evens
2672 finally return (vector odds evens))
2673 @result{} [(1 3 5 7 9) (0 2 4 6 8)]
2674 (setq funny-numbers '(6 7 13 -1))
2675 @result{} (6 7 13 -1)
2676 (cl-loop <@r{same thing again}>)
2680 Note the use of @code{and} to put two clauses into the ``then''
2681 part, one of which is itself an @code{if} clause. Note also that
2682 @code{end}, while normally optional, was necessary here to make
2683 it clear that the @code{else} refers to the outermost @code{if}
2684 clause. In the first case, the loop returns a vector of lists
2685 of the odd and even values of @var{x}. In the second case, the
2686 odd number 7 is one of the @code{funny-numbers} so the loop
2687 returns early; the actual returned value is based on the result
2688 of the @code{memq} call.
2690 @item when @var{condition} @var{clause}
2691 This clause is just a synonym for @code{if}.
2693 @item unless @var{condition} @var{clause}
2694 The @code{unless} clause is just like @code{if} except that the
2695 sense of the condition is reversed.
2697 @item named @var{name}
2698 This clause gives a name other than @code{nil} to the implicit
2699 block surrounding the loop. The @var{name} is the symbol to be
2700 used as the block name.
2702 @item initially [do] @var{forms}...
2703 This keyword introduces one or more Lisp forms which will be
2704 executed before the loop itself begins (but after any variables
2705 requested by @code{for} or @code{with} have been bound to their
2706 initial values). @code{initially} clauses can appear anywhere;
2707 if there are several, they are executed in the order they appear
2708 in the loop. The keyword @code{do} is optional.
2710 @item finally [do] @var{forms}...
2711 This introduces Lisp forms which will be executed after the loop
2712 finishes (say, on request of a @code{for} or @code{while}).
2713 @code{initially} and @code{finally} clauses may appear anywhere
2714 in the loop construct, but they are executed (in the specified
2715 order) at the beginning or end, respectively, of the loop.
2717 @item finally return @var{form}
2718 This says that @var{form} should be executed after the loop
2719 is done to obtain a return value. (Without this, or some other
2720 clause like @code{collect} or @code{return}, the loop will simply
2721 return @code{nil}.) Variables bound by @code{for}, @code{with},
2722 or @code{into} will still contain their final values when @var{form}
2725 @item do @var{forms}...
2726 The word @code{do} may be followed by any number of Lisp expressions
2727 which are executed as an implicit @code{progn} in the body of the
2728 loop. Many of the examples in this section illustrate the use of
2731 @item return @var{form}
2732 This clause causes the loop to return immediately. The following
2733 Lisp form is evaluated to give the return value of the @code{loop}
2734 form. The @code{finally} clauses, if any, are not executed.
2735 Of course, @code{return} is generally used inside an @code{if} or
2736 @code{unless}, as its use in a top-level loop clause would mean
2737 the loop would never get to ``loop'' more than once.
2739 The clause @samp{return @var{form}} is equivalent to
2740 @c FIXME cl-do, cl-return?
2741 @samp{do (return @var{form})} (or @code{return-from} if the loop
2742 was named). The @code{return} clause is implemented a bit more
2743 efficiently, though.
2746 While there is no high-level way to add user extensions to @code{cl-loop}
2747 (comparable to @code{defsetf} for @code{setf}, say), this package
2748 does offer two properties called @code{cl-loop-handler} and
2749 @code{cl-loop-for-handler} which are functions to be called when
2750 a given symbol is encountered as a top-level loop clause or
2751 @code{for} clause, respectively. Consult the source code in
2752 file @file{cl-macs.el} for details.
2754 This package's @code{cl-loop} macro is compatible with that of Common
2755 Lisp, except that a few features are not implemented: @code{loop-finish}
2756 and data-type specifiers. Naturally, the @code{for} clauses which
2757 iterate over keymaps, overlays, intervals, frames, windows, and
2758 buffers are Emacs-specific extensions.
2760 @node Multiple Values
2761 @section Multiple Values
2764 Common Lisp functions can return zero or more results. Emacs Lisp
2765 functions, by contrast, always return exactly one result. This
2766 package makes no attempt to emulate Common Lisp multiple return
2767 values; Emacs versions of Common Lisp functions that return more
2768 than one value either return just the first value (as in
2769 @code{cl-compiler-macroexpand}) or return a list of values (as in
2770 @code{get-setf-method}). This package @emph{does} define placeholders
2771 for the Common Lisp functions that work with multiple values, but
2772 in Emacs Lisp these functions simply operate on lists instead.
2773 The @code{values} form, for example, is a synonym for @code{list}
2776 @defmac cl-multiple-value-bind (var@dots{}) values-form forms@dots{}
2777 This form evaluates @var{values-form}, which must return a list of
2778 values. It then binds the @var{var}s to these respective values,
2779 as if by @code{let}, and then executes the body @var{forms}.
2780 If there are more @var{var}s than values, the extra @var{var}s
2781 are bound to @code{nil}. If there are fewer @var{var}s than
2782 values, the excess values are ignored.
2785 @defmac cl-multiple-value-setq (var@dots{}) form
2786 This form evaluates @var{form}, which must return a list of values.
2787 It then sets the @var{var}s to these respective values, as if by
2788 @code{setq}. Extra @var{var}s or values are treated the same as
2789 in @code{cl-multiple-value-bind}.
2792 Since a perfect emulation is not feasible in Emacs Lisp, this
2793 package opts to keep it as simple and predictable as possible.
2799 This package implements the various Common Lisp features of
2800 @code{defmacro}, such as destructuring, @code{&environment},
2801 and @code{&body}. Top-level @code{&whole} is not implemented
2802 for @code{defmacro} due to technical difficulties.
2803 @xref{Argument Lists}.
2805 Destructuring is made available to the user by way of the
2808 @defmac cl-destructuring-bind arglist expr forms@dots{}
2809 This macro expands to code which executes @var{forms}, with
2810 the variables in @var{arglist} bound to the list of values
2811 returned by @var{expr}. The @var{arglist} can include all
2812 the features allowed for @code{defmacro} argument lists,
2813 including destructuring. (The @code{&environment} keyword
2814 is not allowed.) The macro expansion will signal an error
2815 if @var{expr} returns a list of the wrong number of arguments
2816 or with incorrect keyword arguments.
2819 This package also includes the Common Lisp @code{cl-define-compiler-macro}
2820 facility, which allows you to define compile-time expansions and
2821 optimizations for your functions.
2823 @defmac cl-define-compiler-macro name arglist forms@dots{}
2824 This form is similar to @code{defmacro}, except that it only expands
2825 calls to @var{name} at compile-time; calls processed by the Lisp
2826 interpreter are not expanded, nor are they expanded by the
2827 @code{macroexpand} function.
2829 The argument list may begin with a @code{&whole} keyword and a
2830 variable. This variable is bound to the macro-call form itself,
2831 i.e., to a list of the form @samp{(@var{name} @var{args}@dots{})}.
2832 If the macro expander returns this form unchanged, then the
2833 compiler treats it as a normal function call. This allows
2834 compiler macros to work as optimizers for special cases of a
2835 function, leaving complicated cases alone.
2837 For example, here is a simplified version of a definition that
2838 appears as a standard part of this package:
2841 (cl-define-compiler-macro cl-member (&whole form a list &rest keys)
2842 (if (and (null keys)
2843 (eq (car-safe a) 'quote)
2844 (not (floatp-safe (cadr a))))
2850 This definition causes @code{(cl-member @var{a} @var{list})} to change
2851 to a call to the faster @code{memq} in the common case where @var{a}
2852 is a non-floating-point constant; if @var{a} is anything else, or
2853 if there are any keyword arguments in the call, then the original
2854 @code{cl-member} call is left intact. (The actual compiler macro
2855 for @code{cl-member} optimizes a number of other cases, including
2856 common @code{:test} predicates.)
2859 @defun cl-compiler-macroexpand form
2860 This function is analogous to @code{macroexpand}, except that it
2861 expands compiler macros rather than regular macros. It returns
2862 @var{form} unchanged if it is not a call to a function for which
2863 a compiler macro has been defined, or if that compiler macro
2864 decided to punt by returning its @code{&whole} argument. Like
2865 @code{macroexpand}, it expands repeatedly until it reaches a form
2866 for which no further expansion is possible.
2869 @xref{Macro Bindings}, for descriptions of the @code{cl-macrolet}
2870 and @code{cl-symbol-macrolet} forms for making ``local'' macro
2874 @chapter Declarations
2877 Common Lisp includes a complex and powerful ``declaration''
2878 mechanism that allows you to give the compiler special hints
2879 about the types of data that will be stored in particular variables,
2880 and about the ways those variables and functions will be used. This
2881 package defines versions of all the Common Lisp declaration forms:
2882 @code{cl-declare}, @code{cl-locally}, @code{cl-proclaim}, @code{cl-declaim},
2885 Most of the Common Lisp declarations are not currently useful in
2886 Emacs Lisp, as the byte-code system provides little opportunity
2887 to benefit from type information, and @code{special} declarations
2888 are redundant in a fully dynamically-scoped Lisp. A few
2889 declarations are meaningful when the optimizing byte
2890 compiler is being used, however. Under the earlier non-optimizing
2891 compiler, these declarations will effectively be ignored.
2893 @defun cl-proclaim decl-spec
2894 This function records a ``global'' declaration specified by
2895 @var{decl-spec}. Since @code{cl-proclaim} is a function, @var{decl-spec}
2896 is evaluated and thus should normally be quoted.
2899 @defmac cl-declaim decl-specs@dots{}
2900 This macro is like @code{cl-proclaim}, except that it takes any number
2901 of @var{decl-spec} arguments, and the arguments are unevaluated and
2902 unquoted. The @code{cl-declaim} macro also puts an @code{(cl-eval-when
2903 (compile load eval) ...)} around the declarations so that they will
2904 be registered at compile-time as well as at run-time. (This is vital,
2905 since normally the declarations are meant to influence the way the
2906 compiler treats the rest of the file that contains the @code{cl-declaim}
2910 @defmac cl-declare decl-specs@dots{}
2911 This macro is used to make declarations within functions and other
2912 code. Common Lisp allows declarations in various locations, generally
2913 at the beginning of any of the many ``implicit @code{progn}s''
2914 throughout Lisp syntax, such as function bodies, @code{let} bodies,
2915 etc. Currently the only declaration understood by @code{cl-declare}
2919 @defmac cl-locally declarations@dots{} forms@dots{}
2920 In this package, @code{cl-locally} is no different from @code{progn}.
2923 @defmac cl-the type form
2924 Type information provided by @code{cl-the} is ignored in this package;
2925 in other words, @code{(cl-the @var{type} @var{form})} is equivalent
2926 to @var{form}. Future versions of the optimizing byte-compiler may
2927 make use of this information.
2929 For example, @code{mapcar} can map over both lists and arrays. It is
2930 hard for the compiler to expand @code{mapcar} into an in-line loop
2931 unless it knows whether the sequence will be a list or an array ahead
2932 of time. With @code{(mapcar 'car (cl-the vector foo))}, a future
2933 compiler would have enough information to expand the loop in-line.
2934 For now, Emacs Lisp will treat the above code as exactly equivalent
2935 to @code{(mapcar 'car foo)}.
2938 Each @var{decl-spec} in a @code{cl-proclaim}, @code{cl-declaim}, or
2939 @code{cl-declare} should be a list beginning with a symbol that says
2940 what kind of declaration it is. This package currently understands
2941 @code{special}, @code{inline}, @code{notinline}, @code{optimize},
2942 and @code{warn} declarations. (The @code{warn} declaration is an
2943 extension of standard Common Lisp.) Other Common Lisp declarations,
2944 such as @code{type} and @code{ftype}, are silently ignored.
2948 Since all variables in Emacs Lisp are ``special'' (in the Common
2949 Lisp sense), @code{special} declarations are only advisory. They
2950 simply tell the optimizing byte compiler that the specified
2951 variables are intentionally being referred to without being
2952 bound in the body of the function. The compiler normally emits
2953 warnings for such references, since they could be typographical
2954 errors for references to local variables.
2956 The declaration @code{(cl-declare (special @var{var1} @var{var2}))} is
2957 equivalent to @code{(defvar @var{var1}) (defvar @var{var2})} in the
2958 optimizing compiler, or to nothing at all in older compilers (which
2959 do not warn for non-local references).
2961 In top-level contexts, it is generally better to write
2962 @code{(defvar @var{var})} than @code{(cl-declaim (special @var{var}))},
2963 since @code{defvar} makes your intentions clearer. But the older
2964 byte compilers can not handle @code{defvar}s appearing inside of
2965 functions, while @code{(cl-declare (special @var{var}))} takes care
2966 to work correctly with all compilers.
2969 The @code{inline} @var{decl-spec} lists one or more functions
2970 whose bodies should be expanded ``in-line'' into calling functions
2971 whenever the compiler is able to arrange for it. For example,
2972 the Common Lisp function @code{cadr} is declared @code{inline}
2973 by this package so that the form @code{(cadr @var{x})} will
2974 expand directly into @code{(car (cdr @var{x}))} when it is called
2975 in user functions, for a savings of one (relatively expensive)
2978 The following declarations are all equivalent. Note that the
2979 @code{defsubst} form is a convenient way to define a function
2980 and declare it inline all at once.
2983 (cl-declaim (inline foo bar))
2984 (cl-eval-when (compile load eval)
2985 (cl-proclaim '(inline foo bar)))
2986 (defsubst foo (...) ...) ; instead of defun
2989 @strong{Please note:} this declaration remains in effect after the
2990 containing source file is done. It is correct to use it to
2991 request that a function you have defined should be inlined,
2992 but it is impolite to use it to request inlining of an external
2995 In Common Lisp, it is possible to use @code{(cl-declare (inline @dots{}))}
2996 before a particular call to a function to cause just that call to
2997 be inlined; the current byte compilers provide no way to implement
2998 this, so @code{(cl-declare (inline @dots{}))} is currently ignored by
3002 The @code{notinline} declaration lists functions which should
3003 not be inlined after all; it cancels a previous @code{inline}
3007 This declaration controls how much optimization is performed by
3008 the compiler. Naturally, it is ignored by the earlier non-optimizing
3011 The word @code{optimize} is followed by any number of lists like
3012 @code{(speed 3)} or @code{(safety 2)}. Common Lisp defines several
3013 optimization ``qualities''; this package ignores all but @code{speed}
3014 and @code{safety}. The value of a quality should be an integer from
3015 0 to 3, with 0 meaning ``unimportant'' and 3 meaning ``very important''.
3016 The default level for both qualities is 1.
3018 In this package, with the optimizing compiler, the
3019 @code{speed} quality is tied to the @code{byte-optimize}
3020 flag, which is set to @code{nil} for @code{(speed 0)} and to
3021 @code{t} for higher settings; and the @code{safety} quality is
3022 tied to the @code{byte-compile-delete-errors} flag, which is
3023 set to @code{nil} for @code{(safety 3)} and to @code{t} for all
3024 lower settings. (The latter flag controls whether the compiler
3025 is allowed to optimize out code whose only side-effect could
3026 be to signal an error, e.g., rewriting @code{(progn foo bar)} to
3027 @code{bar} when it is not known whether @code{foo} will be bound
3030 Note that even compiling with @code{(safety 0)}, the Emacs
3031 byte-code system provides sufficient checking to prevent real
3032 harm from being done. For example, barring serious bugs in
3033 Emacs itself, Emacs will not crash with a segmentation fault
3034 just because of an error in a fully-optimized Lisp program.
3036 The @code{optimize} declaration is normally used in a top-level
3037 @code{cl-proclaim} or @code{cl-declaim} in a file; Common Lisp allows
3038 it to be used with @code{cl-declare} to set the level of optimization
3039 locally for a given form, but this will not work correctly with the
3040 current version of the optimizing compiler. (The @code{cl-declare}
3041 will set the new optimization level, but that level will not
3042 automatically be unset after the enclosing form is done.)
3045 This declaration controls what sorts of warnings are generated
3046 by the byte compiler. Again, only the optimizing compiler
3047 generates warnings. The word @code{warn} is followed by any
3048 number of ``warning qualities'', similar in form to optimization
3049 qualities. The currently supported warning types are
3050 @code{redefine}, @code{callargs}, @code{unresolved}, and
3051 @code{free-vars}; in the current system, a value of 0 will
3052 disable these warnings and any higher value will enable them.
3053 See the documentation for the optimizing byte compiler for details.
3060 This package defines several symbol-related features that were
3061 missing from Emacs Lisp.
3064 * Property Lists:: @code{cl-get}, @code{cl-remprop}, @code{cl-getf}, @code{cl-remf}.
3065 * Creating Symbols:: @code{cl-gensym}, @code{cl-gentemp}.
3068 @node Property Lists
3069 @section Property Lists
3072 These functions augment the standard Emacs Lisp functions @code{get}
3073 and @code{put} for operating on properties attached to symbols.
3074 There are also functions for working with property lists as
3075 first-class data structures not attached to particular symbols.
3077 @defun cl-get symbol property &optional default
3078 This function is like @code{get}, except that if the property is
3079 not found, the @var{default} argument provides the return value.
3080 (The Emacs Lisp @code{get} function always uses @code{nil} as
3081 the default; this package's @code{cl-get} is equivalent to Common
3084 The @code{cl-get} function is @code{setf}-able; when used in this
3085 fashion, the @var{default} argument is allowed but ignored.
3088 @defun cl-remprop symbol property
3089 This function removes the entry for @var{property} from the property
3090 list of @var{symbol}. It returns a true value if the property was
3091 indeed found and removed, or @code{nil} if there was no such property.
3092 (This function was probably omitted from Emacs originally because,
3093 since @code{get} did not allow a @var{default}, it was very difficult
3094 to distinguish between a missing property and a property whose value
3095 was @code{nil}; thus, setting a property to @code{nil} was close
3096 enough to @code{cl-remprop} for most purposes.)
3099 @defun cl-getf place property &optional default
3100 This function scans the list @var{place} as if it were a property
3101 list, i.e., a list of alternating property names and values. If
3102 an even-numbered element of @var{place} is found which is @code{eq}
3103 to @var{property}, the following odd-numbered element is returned.
3104 Otherwise, @var{default} is returned (or @code{nil} if no default
3110 (get sym prop) @equiv{} (cl-get (symbol-plist sym) prop)
3113 It is valid to use @code{getf} as a @code{setf} place, in which case
3114 its @var{place} argument must itself be a valid @code{setf} place.
3115 The @var{default} argument, if any, is ignored in this context.
3116 The effect is to change (via @code{setcar}) the value cell in the
3117 list that corresponds to @var{property}, or to cons a new property-value
3118 pair onto the list if the property is not yet present.
3121 (put sym prop val) @equiv{} (setf (cl-get (symbol-plist sym) prop) val)
3124 The @code{get} and @code{cl-get} functions are also @code{setf}-able.
3125 The fact that @code{default} is ignored can sometimes be useful:
3128 (cl-incf (cl-get 'foo 'usage-count 0))
3131 Here, symbol @code{foo}'s @code{usage-count} property is incremented
3132 if it exists, or set to 1 (an incremented 0) otherwise.
3135 When not used as a @code{setf} form, @code{getf} is just a regular
3136 function and its @var{place} argument can actually be any Lisp
3140 @defmac cl-remf place property
3141 This macro removes the property-value pair for @var{property} from
3142 the property list stored at @var{place}, which is any @code{setf}-able
3143 place expression. It returns true if the property was found. Note
3144 that if @var{property} happens to be first on the list, this will
3145 effectively do a @code{(setf @var{place} (cddr @var{place}))},
3146 whereas if it occurs later, this simply uses @code{setcdr} to splice
3147 out the property and value cells.
3150 @node Creating Symbols
3151 @section Creating Symbols
3154 These functions create unique symbols, typically for use as
3155 temporary variables.
3157 @defun cl-gensym &optional x
3158 This function creates a new, uninterned symbol (using @code{make-symbol})
3159 with a unique name. (The name of an uninterned symbol is relevant
3160 only if the symbol is printed.) By default, the name is generated
3161 from an increasing sequence of numbers, @samp{G1000}, @samp{G1001},
3162 @samp{G1002}, etc. If the optional argument @var{x} is a string, that
3163 string is used as a prefix instead of @samp{G}. Uninterned symbols
3164 are used in macro expansions for temporary variables, to ensure that
3165 their names will not conflict with ``real'' variables in the user's
3169 @defvar cl--gensym-counter
3170 This variable holds the counter used to generate @code{cl-gensym} names.
3171 It is incremented after each use by @code{cl-gensym}. In Common Lisp
3172 this is initialized with 0, but this package initializes it with a
3173 random (time-dependent) value to avoid trouble when two files that
3174 each used @code{cl-gensym} in their compilation are loaded together.
3175 (Uninterned symbols become interned when the compiler writes them
3176 out to a file and the Emacs loader loads them, so their names have to
3177 be treated a bit more carefully than in Common Lisp where uninterned
3178 symbols remain uninterned after loading.)
3181 @defun cl-gentemp &optional x
3182 This function is like @code{cl-gensym}, except that it produces a new
3183 @emph{interned} symbol. If the symbol that is generated already
3184 exists, the function keeps incrementing the counter and trying
3185 again until a new symbol is generated.
3188 This package automatically creates all keywords that are called for by
3189 @code{&key} argument specifiers, and discourages the use of keywords
3190 as data unrelated to keyword arguments, so the related function
3191 @code{defkeyword} (to create self-quoting keyword symbols) is not
3198 This section defines a few simple Common Lisp operations on numbers
3199 which were left out of Emacs Lisp.
3202 * Predicates on Numbers:: @code{cl-plusp}, @code{cl-oddp}, @code{cl-floatp-safe}, etc.
3203 * Numerical Functions:: @code{abs}, @code{cl-floor}, etc.
3204 * Random Numbers:: @code{cl-random}, @code{cl-make-random-state}.
3205 * Implementation Parameters:: @code{cl-most-positive-float}.
3208 @node Predicates on Numbers
3209 @section Predicates on Numbers
3212 These functions return @code{t} if the specified condition is
3213 true of the numerical argument, or @code{nil} otherwise.
3215 @defun cl-plusp number
3216 This predicate tests whether @var{number} is positive. It is an
3217 error if the argument is not a number.
3220 @defun cl-minusp number
3221 This predicate tests whether @var{number} is negative. It is an
3222 error if the argument is not a number.
3225 @defun cl-oddp integer
3226 This predicate tests whether @var{integer} is odd. It is an
3227 error if the argument is not an integer.
3230 @defun cl-evenp integer
3231 This predicate tests whether @var{integer} is even. It is an
3232 error if the argument is not an integer.
3235 @defun cl-floatp-safe object
3236 This predicate tests whether @var{object} is a floating-point
3237 number. On systems that support floating-point, this is equivalent
3238 to @code{floatp}. On other systems, this always returns @code{nil}.
3241 @node Numerical Functions
3242 @section Numerical Functions
3245 These functions perform various arithmetic operations on numbers.
3247 @defun cl-gcd &rest integers
3248 This function returns the Greatest Common Divisor of the arguments.
3249 For one argument, it returns the absolute value of that argument.
3250 For zero arguments, it returns zero.
3253 @defun cl-lcm &rest integers
3254 This function returns the Least Common Multiple of the arguments.
3255 For one argument, it returns the absolute value of that argument.
3256 For zero arguments, it returns one.
3259 @defun cl-isqrt integer
3260 This function computes the ``integer square root'' of its integer
3261 argument, i.e., the greatest integer less than or equal to the true
3262 square root of the argument.
3265 @defun cl-floor number &optional divisor
3266 With one argument, @code{cl-floor} returns a list of two numbers:
3267 The argument rounded down (toward minus infinity) to an integer,
3268 and the ``remainder'' which would have to be added back to the
3269 first return value to yield the argument again. If the argument
3270 is an integer @var{x}, the result is always the list @code{(@var{x} 0)}.
3271 If the argument is a floating-point number, the first
3272 result is a Lisp integer and the second is a Lisp float between
3273 0 (inclusive) and 1 (exclusive).
3275 With two arguments, @code{cl-floor} divides @var{number} by
3276 @var{divisor}, and returns the floor of the quotient and the
3277 corresponding remainder as a list of two numbers. If
3278 @code{(cl-floor @var{x} @var{y})} returns @code{(@var{q} @var{r})},
3279 then @code{@var{q}*@var{y} + @var{r} = @var{x}}, with @var{r}
3280 between 0 (inclusive) and @var{r} (exclusive). Also, note
3281 that @code{(cl-floor @var{x})} is exactly equivalent to
3282 @code{(cl-floor @var{x} 1)}.
3284 This function is entirely compatible with Common Lisp's @code{floor}
3285 function, except that it returns the two results in a list since
3286 Emacs Lisp does not support multiple-valued functions.
3289 @defun cl-ceiling number &optional divisor
3290 This function implements the Common Lisp @code{ceiling} function,
3291 which is analogous to @code{floor} except that it rounds the
3292 argument or quotient of the arguments up toward plus infinity.
3293 The remainder will be between 0 and minus @var{r}.
3296 @defun cl-truncate number &optional divisor
3297 This function implements the Common Lisp @code{truncate} function,
3298 which is analogous to @code{floor} except that it rounds the
3299 argument or quotient of the arguments toward zero. Thus it is
3300 equivalent to @code{cl-floor} if the argument or quotient is
3301 positive, or to @code{cl-ceiling} otherwise. The remainder has
3302 the same sign as @var{number}.
3305 @defun cl-round number &optional divisor
3306 This function implements the Common Lisp @code{round} function,
3307 which is analogous to @code{floor} except that it rounds the
3308 argument or quotient of the arguments to the nearest integer.
3309 In the case of a tie (the argument or quotient is exactly
3310 halfway between two integers), it rounds to the even integer.
3313 @defun cl-mod number divisor
3314 This function returns the same value as the second return value
3318 @defun cl-rem number divisor
3319 This function returns the same value as the second return value
3320 of @code{cl-truncate}.
3323 @node Random Numbers
3324 @section Random Numbers
3327 This package also provides an implementation of the Common Lisp
3328 random number generator. It uses its own additive-congruential
3329 algorithm, which is much more likely to give statistically clean
3330 random numbers than the simple generators supplied by many
3333 @defun cl-random number &optional state
3334 This function returns a random nonnegative number less than
3335 @var{number}, and of the same type (either integer or floating-point).
3336 The @var{state} argument should be a @code{random-state} object
3337 which holds the state of the random number generator. The
3338 function modifies this state object as a side effect. If
3339 @var{state} is omitted, it defaults to the variable
3340 @code{cl--random-state}, which contains a pre-initialized
3341 @code{random-state} object.
3344 @defvar cl--random-state
3345 This variable contains the system ``default'' @code{random-state}
3346 object, used for calls to @code{cl-random} that do not specify an
3347 alternative state object. Since any number of programs in the
3348 Emacs process may be accessing @code{cl--random-state} in interleaved
3349 fashion, the sequence generated from this variable will be
3350 irreproducible for all intents and purposes.
3353 @defun cl-make-random-state &optional state
3354 This function creates or copies a @code{random-state} object.
3355 If @var{state} is omitted or @code{nil}, it returns a new copy of
3356 @code{cl--random-state}. This is a copy in the sense that future
3357 sequences of calls to @code{(cl-random @var{n})} and
3358 @code{(cl-random @var{n} @var{s})} (where @var{s} is the new
3359 random-state object) will return identical sequences of random
3362 If @var{state} is a @code{random-state} object, this function
3363 returns a copy of that object. If @var{state} is @code{t}, this
3364 function returns a new @code{random-state} object seeded from the
3365 date and time. As an extension to Common Lisp, @var{state} may also
3366 be an integer in which case the new object is seeded from that
3367 integer; each different integer seed will result in a completely
3368 different sequence of random numbers.
3370 It is valid to print a @code{random-state} object to a buffer or
3371 file and later read it back with @code{read}. If a program wishes
3372 to use a sequence of pseudo-random numbers which can be reproduced
3373 later for debugging, it can call @code{(cl-make-random-state t)} to
3374 get a new sequence, then print this sequence to a file. When the
3375 program is later rerun, it can read the original run's random-state
3379 @defun cl-random-state-p object
3380 This predicate returns @code{t} if @var{object} is a
3381 @code{random-state} object, or @code{nil} otherwise.
3384 @node Implementation Parameters
3385 @section Implementation Parameters
3388 This package defines several useful constants having to with numbers.
3390 The following parameters have to do with floating-point numbers.
3391 This package determines their values by exercising the computer's
3392 floating-point arithmetic in various ways. Because this operation
3393 might be slow, the code for initializing them is kept in a separate
3394 function that must be called before the parameters can be used.
3396 @defun cl-float-limits
3397 This function makes sure that the Common Lisp floating-point parameters
3398 like @code{cl-most-positive-float} have been initialized. Until it is
3399 called, these parameters will be @code{nil}. If this version of Emacs
3400 does not support floats, the parameters will remain @code{nil}. If the
3401 parameters have already been initialized, the function returns
3404 The algorithm makes assumptions that will be valid for most modern
3405 machines, but will fail if the machine's arithmetic is extremely
3406 unusual, e.g., decimal.
3409 Since true Common Lisp supports up to four different floating-point
3410 precisions, it has families of constants like
3411 @code{most-positive-single-float}, @code{most-positive-double-float},
3412 @code{most-positive-long-float}, and so on. Emacs has only one
3413 floating-point precision, so this package omits the precision word
3414 from the constants' names.
3416 @defvar cl-most-positive-float
3417 This constant equals the largest value a Lisp float can hold.
3418 For those systems whose arithmetic supports infinities, this is
3419 the largest @emph{finite} value. For IEEE machines, the value
3420 is approximately @code{1.79e+308}.
3423 @defvar cl-most-negative-float
3424 This constant equals the most-negative value a Lisp float can hold.
3425 (It is assumed to be equal to @code{(- cl-most-positive-float)}.)
3428 @defvar cl-least-positive-float
3429 This constant equals the smallest Lisp float value greater than zero.
3430 For IEEE machines, it is about @code{4.94e-324} if denormals are
3431 supported or @code{2.22e-308} if not.
3434 @defvar cl-least-positive-normalized-float
3435 This constant equals the smallest @emph{normalized} Lisp float greater
3436 than zero, i.e., the smallest value for which IEEE denormalization
3437 will not result in a loss of precision. For IEEE machines, this
3438 value is about @code{2.22e-308}. For machines that do not support
3439 the concept of denormalization and gradual underflow, this constant
3440 will always equal @code{cl-least-positive-float}.
3443 @defvar cl-least-negative-float
3444 This constant is the negative counterpart of @code{cl-least-positive-float}.
3447 @defvar cl-least-negative-normalized-float
3448 This constant is the negative counterpart of
3449 @code{cl-least-positive-normalized-float}.
3452 @defvar cl-float-epsilon
3453 This constant is the smallest positive Lisp float that can be added
3454 to 1.0 to produce a distinct value. Adding a smaller number to 1.0
3455 will yield 1.0 again due to roundoff. For IEEE machines, epsilon
3456 is about @code{2.22e-16}.
3459 @defvar cl-float-negative-epsilon
3460 This is the smallest positive value that can be subtracted from
3461 1.0 to produce a distinct value. For IEEE machines, it is about
3469 Common Lisp defines a number of functions that operate on
3470 @dfn{sequences}, which are either lists, strings, or vectors.
3471 Emacs Lisp includes a few of these, notably @code{elt} and
3472 @code{length}; this package defines most of the rest.
3475 * Sequence Basics:: Arguments shared by all sequence functions.
3476 * Mapping over Sequences:: @code{cl-mapcar}, @code{cl-mapcan}, @code{cl-map}, @code{cl-every}, etc.
3477 * Sequence Functions:: @code{cl-subseq}, @code{cl-remove}, @code{cl-substitute}, etc.
3478 * Searching Sequences:: @code{cl-find}, @code{cl-position}, @code{cl-count}, @code{cl-search}, etc.
3479 * Sorting Sequences:: @code{cl-sort}, @code{cl-stable-sort}, @code{cl-merge}.
3482 @node Sequence Basics
3483 @section Sequence Basics
3486 Many of the sequence functions take keyword arguments; @pxref{Argument
3487 Lists}. All keyword arguments are optional and, if specified,
3488 may appear in any order.
3490 The @code{:key} argument should be passed either @code{nil}, or a
3491 function of one argument. This key function is used as a filter
3492 through which the elements of the sequence are seen; for example,
3493 @code{(cl-find x y :key 'car)} is similar to @code{(cl-assoc x y)}:
3494 It searches for an element of the list whose @code{car} equals
3495 @code{x}, rather than for an element which equals @code{x} itself.
3496 If @code{:key} is omitted or @code{nil}, the filter is effectively
3497 the identity function.
3499 The @code{:test} and @code{:test-not} arguments should be either
3500 @code{nil}, or functions of two arguments. The test function is
3501 used to compare two sequence elements, or to compare a search value
3502 with sequence elements. (The two values are passed to the test
3503 function in the same order as the original sequence function
3504 arguments from which they are derived, or, if they both come from
3505 the same sequence, in the same order as they appear in that sequence.)
3506 The @code{:test} argument specifies a function which must return
3507 true (non-@code{nil}) to indicate a match; instead, you may use
3508 @code{:test-not} to give a function which returns @emph{false} to
3509 indicate a match. The default test function is @code{eql}.
3511 Many functions which take @var{item} and @code{:test} or @code{:test-not}
3512 arguments also come in @code{-if} and @code{-if-not} varieties,
3513 where a @var{predicate} function is passed instead of @var{item},
3514 and sequence elements match if the predicate returns true on them
3515 (or false in the case of @code{-if-not}). For example:
3518 (cl-remove 0 seq :test '=) @equiv{} (cl-remove-if 'zerop seq)
3522 to remove all zeros from sequence @code{seq}.
3524 Some operations can work on a subsequence of the argument sequence;
3525 these function take @code{:start} and @code{:end} arguments which
3526 default to zero and the length of the sequence, respectively.
3527 Only elements between @var{start} (inclusive) and @var{end}
3528 (exclusive) are affected by the operation. The @var{end} argument
3529 may be passed @code{nil} to signify the length of the sequence;
3530 otherwise, both @var{start} and @var{end} must be integers, with
3531 @code{0 <= @var{start} <= @var{end} <= (length @var{seq})}.
3532 If the function takes two sequence arguments, the limits are
3533 defined by keywords @code{:start1} and @code{:end1} for the first,
3534 and @code{:start2} and @code{:end2} for the second.
3536 A few functions accept a @code{:from-end} argument, which, if
3537 non-@code{nil}, causes the operation to go from right-to-left
3538 through the sequence instead of left-to-right, and a @code{:count}
3539 argument, which specifies an integer maximum number of elements
3540 to be removed or otherwise processed.
3542 The sequence functions make no guarantees about the order in
3543 which the @code{:test}, @code{:test-not}, and @code{:key} functions
3544 are called on various elements. Therefore, it is a bad idea to depend
3545 on side effects of these functions. For example, @code{:from-end}
3546 may cause the sequence to be scanned actually in reverse, or it may
3547 be scanned forwards but computing a result ``as if'' it were scanned
3548 backwards. (Some functions, like @code{cl-mapcar} and @code{cl-every},
3549 @emph{do} specify exactly the order in which the function is called
3550 so side effects are perfectly acceptable in those cases.)
3552 Strings may contain ``text properties'' as well
3553 as character data. Except as noted, it is undefined whether or
3554 not text properties are preserved by sequence functions. For
3555 example, @code{(cl-remove ?A @var{str})} may or may not preserve
3556 the properties of the characters copied from @var{str} into the
3559 @node Mapping over Sequences
3560 @section Mapping over Sequences
3563 These functions ``map'' the function you specify over the elements
3564 of lists or arrays. They are all variations on the theme of the
3565 built-in function @code{mapcar}.
3567 @defun cl-mapcar function seq &rest more-seqs
3568 This function calls @var{function} on successive parallel sets of
3569 elements from its argument sequences. Given a single @var{seq}
3570 argument it is equivalent to @code{mapcar}; given @var{n} sequences,
3571 it calls the function with the first elements of each of the sequences
3572 as the @var{n} arguments to yield the first element of the result
3573 list, then with the second elements, and so on. The mapping stops as
3574 soon as the shortest sequence runs out. The argument sequences may
3575 be any mixture of lists, strings, and vectors; the return sequence
3578 Common Lisp's @code{mapcar} accepts multiple arguments but works
3579 only on lists; Emacs Lisp's @code{mapcar} accepts a single sequence
3580 argument. This package's @code{cl-mapcar} works as a compatible
3584 @defun cl-map result-type function seq &rest more-seqs
3585 This function maps @var{function} over the argument sequences,
3586 just like @code{cl-mapcar}, but it returns a sequence of type
3587 @var{result-type} rather than a list. @var{result-type} must
3588 be one of the following symbols: @code{vector}, @code{string},
3589 @code{list} (in which case the effect is the same as for
3590 @code{cl-mapcar}), or @code{nil} (in which case the results are
3591 thrown away and @code{cl-map} returns @code{nil}).
3594 @defun cl-maplist function list &rest more-lists
3595 This function calls @var{function} on each of its argument lists,
3596 then on the @code{cdr}s of those lists, and so on, until the
3597 shortest list runs out. The results are returned in the form
3598 of a list. Thus, @code{cl-maplist} is like @code{cl-mapcar} except
3599 that it passes in the list pointers themselves rather than the
3600 @code{car}s of the advancing pointers.
3603 @c FIXME does not exist?
3604 @defun cl-mapc function seq &rest more-seqs
3605 This function is like @code{cl-mapcar}, except that the values returned
3606 by @var{function} are ignored and thrown away rather than being
3607 collected into a list. The return value of @code{cl-mapc} is @var{seq},
3608 the first sequence. This function is more general than the Emacs
3609 primitive @code{mapc}.
3612 @defun cl-mapl function list &rest more-lists
3613 This function is like @code{cl-maplist}, except that it throws away
3614 the values returned by @var{function}.
3617 @defun cl-mapcan function seq &rest more-seqs
3618 This function is like @code{cl-mapcar}, except that it concatenates
3619 the return values (which must be lists) using @code{nconc},
3620 rather than simply collecting them into a list.
3623 @defun cl-mapcon function list &rest more-lists
3624 This function is like @code{cl-maplist}, except that it concatenates
3625 the return values using @code{nconc}.
3628 @defun cl-some predicate seq &rest more-seqs
3629 This function calls @var{predicate} on each element of @var{seq}
3630 in turn; if @var{predicate} returns a non-@code{nil} value,
3631 @code{some} returns that value, otherwise it returns @code{nil}.
3632 Given several sequence arguments, it steps through the sequences
3633 in parallel until the shortest one runs out, just as in
3634 @code{cl-mapcar}. You can rely on the left-to-right order in which
3635 the elements are visited, and on the fact that mapping stops
3636 immediately as soon as @var{predicate} returns non-@code{nil}.
3639 @defun cl-every predicate seq &rest more-seqs
3640 This function calls @var{predicate} on each element of the sequence(s)
3641 in turn; it returns @code{nil} as soon as @var{predicate} returns
3642 @code{nil} for any element, or @code{t} if the predicate was true
3646 @defun cl-notany predicate seq &rest more-seqs
3647 This function calls @var{predicate} on each element of the sequence(s)
3648 in turn; it returns @code{nil} as soon as @var{predicate} returns
3649 a non-@code{nil} value for any element, or @code{t} if the predicate
3650 was @code{nil} for all elements.
3653 @defun cl-notevery predicate seq &rest more-seqs
3654 This function calls @var{predicate} on each element of the sequence(s)
3655 in turn; it returns a non-@code{nil} value as soon as @var{predicate}
3656 returns @code{nil} for any element, or @code{t} if the predicate was
3657 true for all elements.
3660 @defun cl-reduce function seq @t{&key :from-end :start :end :initial-value :key}
3661 This function combines the elements of @var{seq} using an associative
3662 binary operation. Suppose @var{function} is @code{*} and @var{seq} is
3663 the list @code{(2 3 4 5)}. The first two elements of the list are
3664 combined with @code{(* 2 3) = 6}; this is combined with the next
3665 element, @code{(* 6 4) = 24}, and that is combined with the final
3666 element: @code{(* 24 5) = 120}. Note that the @code{*} function happens
3667 to be self-reducing, so that @code{(* 2 3 4 5)} has the same effect as
3668 an explicit call to @code{cl-reduce}.
3670 If @code{:from-end} is true, the reduction is right-associative instead
3671 of left-associative:
3674 (cl-reduce '- '(1 2 3 4))
3675 @equiv{} (- (- (- 1 2) 3) 4) @result{} -8
3676 (cl-reduce '- '(1 2 3 4) :from-end t)
3677 @equiv{} (- 1 (- 2 (- 3 4))) @result{} -2
3680 If @code{:key} is specified, it is a function of one argument which
3681 is called on each of the sequence elements in turn.
3683 If @code{:initial-value} is specified, it is effectively added to the
3684 front (or rear in the case of @code{:from-end}) of the sequence.
3685 The @code{:key} function is @emph{not} applied to the initial value.
3687 If the sequence, including the initial value, has exactly one element
3688 then that element is returned without ever calling @var{function}.
3689 If the sequence is empty (and there is no initial value), then
3690 @var{function} is called with no arguments to obtain the return value.
3693 All of these mapping operations can be expressed conveniently in
3694 terms of the @code{cl-loop} macro. In compiled code, @code{cl-loop} will
3695 be faster since it generates the loop as in-line code with no
3698 @node Sequence Functions
3699 @section Sequence Functions
3702 This section describes a number of Common Lisp functions for
3703 operating on sequences.
3705 @defun cl-subseq sequence start &optional end
3706 This function returns a given subsequence of the argument
3707 @var{sequence}, which may be a list, string, or vector.
3708 The indices @var{start} and @var{end} must be in range, and
3709 @var{start} must be no greater than @var{end}. If @var{end}
3710 is omitted, it defaults to the length of the sequence. The
3711 return value is always a copy; it does not share structure
3712 with @var{sequence}.
3714 As an extension to Common Lisp, @var{start} and/or @var{end}
3715 may be negative, in which case they represent a distance back
3716 from the end of the sequence. This is for compatibility with
3717 Emacs's @code{substring} function. Note that @code{cl-subseq} is
3718 the @emph{only} sequence function that allows negative
3719 @var{start} and @var{end}.
3721 You can use @code{setf} on a @code{cl-subseq} form to replace a
3722 specified range of elements with elements from another sequence.
3723 The replacement is done as if by @code{cl-replace}, described below.
3726 @defun cl-concatenate result-type &rest seqs
3727 This function concatenates the argument sequences together to
3728 form a result sequence of type @var{result-type}, one of the
3729 symbols @code{vector}, @code{string}, or @code{list}. The
3730 arguments are always copied, even in cases such as
3731 @code{(cl-concatenate 'list '(1 2 3))} where the result is
3732 identical to an argument.
3735 @defun cl-fill seq item @t{&key :start :end}
3736 This function fills the elements of the sequence (or the specified
3737 part of the sequence) with the value @var{item}.
3740 @defun cl-replace seq1 seq2 @t{&key :start1 :end1 :start2 :end2}
3741 This function copies part of @var{seq2} into part of @var{seq1}.
3742 The sequence @var{seq1} is not stretched or resized; the amount
3743 of data copied is simply the shorter of the source and destination
3744 (sub)sequences. The function returns @var{seq1}.
3746 If @var{seq1} and @var{seq2} are @code{eq}, then the replacement
3747 will work correctly even if the regions indicated by the start
3748 and end arguments overlap. However, if @var{seq1} and @var{seq2}
3749 are lists which share storage but are not @code{eq}, and the
3750 start and end arguments specify overlapping regions, the effect
3754 @defun cl-remove item seq @t{&key :test :test-not :key :count :start :end :from-end}
3755 This returns a copy of @var{seq} with all elements matching
3756 @var{item} removed. The result may share storage with or be
3757 @code{eq} to @var{seq} in some circumstances, but the original
3758 @var{seq} will not be modified. The @code{:test}, @code{:test-not},
3759 and @code{:key} arguments define the matching test that is used;
3760 by default, elements @code{eql} to @var{item} are removed. The
3761 @code{:count} argument specifies the maximum number of matching
3762 elements that can be removed (only the leftmost @var{count} matches
3763 are removed). The @code{:start} and @code{:end} arguments specify
3764 a region in @var{seq} in which elements will be removed; elements
3765 outside that region are not matched or removed. The @code{:from-end}
3766 argument, if true, says that elements should be deleted from the
3767 end of the sequence rather than the beginning (this matters only
3768 if @var{count} was also specified).
3771 @defun cl-delete item seq @t{&key :test :test-not :key :count :start :end :from-end}
3772 This deletes all elements of @var{seq} which match @var{item}.
3773 It is a destructive operation. Since Emacs Lisp does not support
3774 stretchable strings or vectors, this is the same as @code{cl-remove}
3775 for those sequence types. On lists, @code{cl-remove} will copy the
3776 list if necessary to preserve the original list, whereas
3777 @code{cl-delete} will splice out parts of the argument list.
3778 Compare @code{append} and @code{nconc}, which are analogous
3779 non-destructive and destructive list operations in Emacs Lisp.
3782 @findex cl-remove-if
3783 @findex cl-remove-if-not
3784 @findex cl-delete-if
3785 @findex cl-delete-if-not
3786 The predicate-oriented functions @code{cl-remove-if}, @code{cl-remove-if-not},
3787 @code{cl-delete-if}, and @code{cl-delete-if-not} are defined similarly.
3789 @defun cl-remove-duplicates seq @t{&key :test :test-not :key :start :end :from-end}
3790 This function returns a copy of @var{seq} with duplicate elements
3791 removed. Specifically, if two elements from the sequence match
3792 according to the @code{:test}, @code{:test-not}, and @code{:key}
3793 arguments, only the rightmost one is retained. If @code{:from-end}
3794 is true, the leftmost one is retained instead. If @code{:start} or
3795 @code{:end} is specified, only elements within that subsequence are
3796 examined or removed.
3799 @defun cl-delete-duplicates seq @t{&key :test :test-not :key :start :end :from-end}
3800 This function deletes duplicate elements from @var{seq}. It is
3801 a destructive version of @code{cl-remove-duplicates}.
3804 @defun cl-substitute new old seq @t{&key :test :test-not :key :count :start :end :from-end}
3805 This function returns a copy of @var{seq}, with all elements
3806 matching @var{old} replaced with @var{new}. The @code{:count},
3807 @code{:start}, @code{:end}, and @code{:from-end} arguments may be
3808 used to limit the number of substitutions made.
3811 @defun cl-nsubstitute new old seq @t{&key :test :test-not :key :count :start :end :from-end}
3812 This is a destructive version of @code{cl-substitute}; it performs
3813 the substitution using @code{setcar} or @code{aset} rather than
3814 by returning a changed copy of the sequence.
3817 @findex cl-substitute-if
3818 @findex cl-substitute-if-not
3819 @findex cl-nsubstitute-if
3820 @findex cl-nsubstitute-if-not
3821 The functions @code{cl-substitute-if}, @code{cl-substitute-if-not},
3822 @code{cl-nsubstitute-if}, and @code{cl-nsubstitute-if-not} are defined
3823 similarly. For these, a @var{predicate} is given in place of the
3826 @node Searching Sequences
3827 @section Searching Sequences
3830 These functions search for elements or subsequences in a sequence.
3831 (See also @code{cl-member} and @code{cl-assoc}; @pxref{Lists}.)
3833 @defun cl-find item seq @t{&key :test :test-not :key :start :end :from-end}
3834 This function searches @var{seq} for an element matching @var{item}.
3835 If it finds a match, it returns the matching element. Otherwise,
3836 it returns @code{nil}. It returns the leftmost match, unless
3837 @code{:from-end} is true, in which case it returns the rightmost
3838 match. The @code{:start} and @code{:end} arguments may be used to
3839 limit the range of elements that are searched.
3842 @defun cl-position item seq @t{&key :test :test-not :key :start :end :from-end}
3843 This function is like @code{cl-find}, except that it returns the
3844 integer position in the sequence of the matching item rather than
3845 the item itself. The position is relative to the start of the
3846 sequence as a whole, even if @code{:start} is non-zero. The function
3847 returns @code{nil} if no matching element was found.
3850 @defun cl-count item seq @t{&key :test :test-not :key :start :end}
3851 This function returns the number of elements of @var{seq} which
3852 match @var{item}. The result is always a nonnegative integer.
3856 @findex cl-find-if-not
3857 @findex cl-position-if
3858 @findex cl-position-if-not
3860 @findex cl-count-if-not
3861 The @code{cl-find-if}, @code{cl-find-if-not}, @code{cl-position-if},
3862 @code{cl-position-if-not}, @code{cl-count-if}, and @code{cl-count-if-not}
3863 functions are defined similarly.
3865 @defun cl-mismatch seq1 seq2 @t{&key :test :test-not :key :start1 :end1 :start2 :end2 :from-end}
3866 This function compares the specified parts of @var{seq1} and
3867 @var{seq2}. If they are the same length and the corresponding
3868 elements match (according to @code{:test}, @code{:test-not},
3869 and @code{:key}), the function returns @code{nil}. If there is
3870 a mismatch, the function returns the index (relative to @var{seq1})
3871 of the first mismatching element. This will be the leftmost pair of
3872 elements which do not match, or the position at which the shorter of
3873 the two otherwise-matching sequences runs out.
3875 If @code{:from-end} is true, then the elements are compared from right
3876 to left starting at @code{(1- @var{end1})} and @code{(1- @var{end2})}.
3877 If the sequences differ, then one plus the index of the rightmost
3878 difference (relative to @var{seq1}) is returned.
3880 An interesting example is @code{(cl-mismatch str1 str2 :key 'upcase)},
3881 which compares two strings case-insensitively.
3884 @defun cl-search seq1 seq2 @t{&key :test :test-not :key :from-end :start1 :end1 :start2 :end2}
3885 This function searches @var{seq2} for a subsequence that matches
3886 @var{seq1} (or part of it specified by @code{:start1} and
3887 @code{:end1}.) Only matches which fall entirely within the region
3888 defined by @code{:start2} and @code{:end2} will be considered.
3889 The return value is the index of the leftmost element of the
3890 leftmost match, relative to the start of @var{seq2}, or @code{nil}
3891 if no matches were found. If @code{:from-end} is true, the
3892 function finds the @emph{rightmost} matching subsequence.
3895 @node Sorting Sequences
3896 @section Sorting Sequences
3898 @defun clsort seq predicate @t{&key :key}
3899 This function sorts @var{seq} into increasing order as determined
3900 by using @var{predicate} to compare pairs of elements. @var{predicate}
3901 should return true (non-@code{nil}) if and only if its first argument
3902 is less than (not equal to) its second argument. For example,
3903 @code{<} and @code{string-lessp} are suitable predicate functions
3904 for sorting numbers and strings, respectively; @code{>} would sort
3905 numbers into decreasing rather than increasing order.
3907 This function differs from Emacs's built-in @code{sort} in that it
3908 can operate on any type of sequence, not just lists. Also, it
3909 accepts a @code{:key} argument which is used to preprocess data
3910 fed to the @var{predicate} function. For example,
3913 (setq data (cl-sort data 'string-lessp :key 'downcase))
3917 sorts @var{data}, a sequence of strings, into increasing alphabetical
3918 order without regard to case. A @code{:key} function of @code{car}
3919 would be useful for sorting association lists. It should only be a
3920 simple accessor though, it's used heavily in the current
3923 The @code{cl-sort} function is destructive; it sorts lists by actually
3924 rearranging the @code{cdr} pointers in suitable fashion.
3927 @defun cl-stable-sort seq predicate @t{&key :key}
3928 This function sorts @var{seq} @dfn{stably}, meaning two elements
3929 which are equal in terms of @var{predicate} are guaranteed not to
3930 be rearranged out of their original order by the sort.
3932 In practice, @code{cl-sort} and @code{cl-stable-sort} are equivalent
3933 in Emacs Lisp because the underlying @code{sort} function is
3934 stable by default. However, this package reserves the right to
3935 use non-stable methods for @code{cl-sort} in the future.
3938 @defun cl-merge type seq1 seq2 predicate @t{&key :key}
3939 This function merges two sequences @var{seq1} and @var{seq2} by
3940 interleaving their elements. The result sequence, of type @var{type}
3941 (in the sense of @code{cl-concatenate}), has length equal to the sum
3942 of the lengths of the two input sequences. The sequences may be
3943 modified destructively. Order of elements within @var{seq1} and
3944 @var{seq2} is preserved in the interleaving; elements of the two
3945 sequences are compared by @var{predicate} (in the sense of
3946 @code{sort}) and the lesser element goes first in the result.
3947 When elements are equal, those from @var{seq1} precede those from
3948 @var{seq2} in the result. Thus, if @var{seq1} and @var{seq2} are
3949 both sorted according to @var{predicate}, then the result will be
3950 a merged sequence which is (stably) sorted according to
3958 The functions described here operate on lists.
3961 * List Functions:: @code{cl-caddr}, @code{cl-first}, @code{cl-list*}, etc.
3962 * Substitution of Expressions:: @code{cl-subst}, @code{cl-sublis}, etc.
3963 * Lists as Sets:: @code{cl-member}, @code{cl-adjoin}, @code{cl-union}, etc.
3964 * Association Lists:: @code{cl-assoc}, @code{cl-rassoc}, @code{cl-acons}, @code{cl-pairlis}.
3967 @node List Functions
3968 @section List Functions
3971 This section describes a number of simple operations on lists,
3972 i.e., chains of cons cells.
3975 This function is equivalent to @code{(car (cdr (cdr @var{x})))}.
3976 Likewise, this package defines all 28 @code{c@var{xxx}r} functions
3977 where @var{xxx} is up to four @samp{a}s and/or @samp{d}s.
3978 All of these functions are @code{setf}-able, and calls to them
3979 are expanded inline by the byte-compiler for maximum efficiency.
3983 This function is a synonym for @code{(car @var{x})}. Likewise,
3984 the functions @code{cl-second}, @code{cl-third}, @dots{}, through
3985 @code{cl-tenth} return the given element of the list @var{x}.
3989 This function is a synonym for @code{(cdr @var{x})}.
3993 Common Lisp defines this function to act like @code{null}, but
3994 signaling an error if @code{x} is neither a @code{nil} nor a
3995 cons cell. This package simply defines @code{cl-endp} as a synonym
3999 @defun cl-list-length x
4000 This function returns the length of list @var{x}, exactly like
4001 @code{(length @var{x})}, except that if @var{x} is a circular
4002 list (where the cdr-chain forms a loop rather than terminating
4003 with @code{nil}), this function returns @code{nil}. (The regular
4004 @code{length} function would get stuck if given a circular list.)
4007 @defun cl-list* arg &rest others
4008 This function constructs a list of its arguments. The final
4009 argument becomes the @code{cdr} of the last cell constructed.
4010 Thus, @code{(cl-list* @var{a} @var{b} @var{c})} is equivalent to
4011 @code{(cons @var{a} (cons @var{b} @var{c}))}, and
4012 @code{(cl-list* @var{a} @var{b} nil)} is equivalent to
4013 @code{(list @var{a} @var{b})}.
4016 @defun cl-ldiff list sublist
4017 If @var{sublist} is a sublist of @var{list}, i.e., is @code{eq} to
4018 one of the cons cells of @var{list}, then this function returns
4019 a copy of the part of @var{list} up to but not including
4020 @var{sublist}. For example, @code{(cl-ldiff x (cddr x))} returns
4021 the first two elements of the list @code{x}. The result is a
4022 copy; the original @var{list} is not modified. If @var{sublist}
4023 is not a sublist of @var{list}, a copy of the entire @var{list}
4027 @defun cl-copy-list list
4028 This function returns a copy of the list @var{list}. It copies
4029 dotted lists like @code{(1 2 . 3)} correctly.
4032 @defun copy-tree x &optional vecp
4033 This function returns a copy of the tree of cons cells @var{x}.
4034 @c FIXME? cl-copy-list is not an alias of copy-sequence.
4035 Unlike @code{copy-sequence} (and its alias @code{cl-copy-list}),
4036 which copies only along the @code{cdr} direction, this function
4037 copies (recursively) along both the @code{car} and the @code{cdr}
4038 directions. If @var{x} is not a cons cell, the function simply
4039 returns @var{x} unchanged. If the optional @var{vecp} argument
4040 is true, this function copies vectors (recursively) as well as
4044 @defun cl-tree-equal x y @t{&key :test :test-not :key}
4045 This function compares two trees of cons cells. If @var{x} and
4046 @var{y} are both cons cells, their @code{car}s and @code{cdr}s are
4047 compared recursively. If neither @var{x} nor @var{y} is a cons
4048 cell, they are compared by @code{eql}, or according to the
4049 specified test. The @code{:key} function, if specified, is
4050 applied to the elements of both trees. @xref{Sequences}.
4053 @node Substitution of Expressions
4054 @section Substitution of Expressions
4057 These functions substitute elements throughout a tree of cons
4058 cells. (@xref{Sequence Functions}, for the @code{cl-substitute}
4059 function, which works on just the top-level elements of a list.)
4061 @defun cl-subst new old tree @t{&key :test :test-not :key}
4062 This function substitutes occurrences of @var{old} with @var{new}
4063 in @var{tree}, a tree of cons cells. It returns a substituted
4064 tree, which will be a copy except that it may share storage with
4065 the argument @var{tree} in parts where no substitutions occurred.
4066 The original @var{tree} is not modified. This function recurses
4067 on, and compares against @var{old}, both @code{car}s and @code{cdr}s
4068 of the component cons cells. If @var{old} is itself a cons cell,
4069 then matching cells in the tree are substituted as usual without
4070 recursively substituting in that cell. Comparisons with @var{old}
4071 are done according to the specified test (@code{eql} by default).
4072 The @code{:key} function is applied to the elements of the tree
4073 but not to @var{old}.
4076 @defun cl-nsubst new old tree @t{&key :test :test-not :key}
4077 This function is like @code{cl-subst}, except that it works by
4078 destructive modification (by @code{setcar} or @code{setcdr})
4079 rather than copying.
4083 @findex cl-subst-if-not
4084 @findex cl-nsubst-if
4085 @findex cl-nsubst-if-not
4086 The @code{cl-subst-if}, @code{cl-subst-if-not}, @code{cl-nsubst-if}, and
4087 @code{cl-nsubst-if-not} functions are defined similarly.
4089 @defun cl-sublis alist tree @t{&key :test :test-not :key}
4090 This function is like @code{cl-subst}, except that it takes an
4091 association list @var{alist} of @var{old}-@var{new} pairs.
4092 Each element of the tree (after applying the @code{:key}
4093 function, if any), is compared with the @code{car}s of
4094 @var{alist}; if it matches, it is replaced by the corresponding
4098 @defun cl-nsublis alist tree @t{&key :test :test-not :key}
4099 This is a destructive version of @code{cl-sublis}.
4103 @section Lists as Sets
4106 These functions perform operations on lists which represent sets
4109 @defun cl-member item list @t{&key :test :test-not :key}
4110 This function searches @var{list} for an element matching @var{item}.
4111 If a match is found, it returns the cons cell whose @code{car} was
4112 the matching element. Otherwise, it returns @code{nil}. Elements
4113 are compared by @code{eql} by default; you can use the @code{:test},
4114 @code{:test-not}, and @code{:key} arguments to modify this behavior.
4117 The standard Emacs lisp function @code{member} uses @code{equal} for
4118 comparisons; it is equivalent to @code{(cl-member @var{item} @var{list}
4122 @findex cl-member-if
4123 @findex cl-member-if-not
4124 The @code{cl-member-if} and @code{cl-member-if-not} functions
4125 analogously search for elements which satisfy a given predicate.
4127 @defun cl-tailp sublist list
4128 This function returns @code{t} if @var{sublist} is a sublist of
4129 @var{list}, i.e., if @var{sublist} is @code{eql} to @var{list} or to
4130 any of its @code{cdr}s.
4133 @defun cl-adjoin item list @t{&key :test :test-not :key}
4134 This function conses @var{item} onto the front of @var{list},
4135 like @code{(cons @var{item} @var{list})}, but only if @var{item}
4136 is not already present on the list (as determined by @code{cl-member}).
4137 If a @code{:key} argument is specified, it is applied to
4138 @var{item} as well as to the elements of @var{list} during
4139 the search, on the reasoning that @var{item} is ``about'' to
4140 become part of the list.
4143 @defun cl-union list1 list2 @t{&key :test :test-not :key}
4144 This function combines two lists which represent sets of items,
4145 returning a list that represents the union of those two sets.
4146 The result list will contain all items which appear in @var{list1}
4147 or @var{list2}, and no others. If an item appears in both
4148 @var{list1} and @var{list2} it will be copied only once. If
4149 an item is duplicated in @var{list1} or @var{list2}, it is
4150 undefined whether or not that duplication will survive in the
4151 result list. The order of elements in the result list is also
4155 @defun cl-nunion list1 list2 @t{&key :test :test-not :key}
4156 This is a destructive version of @code{cl-union}; rather than copying,
4157 it tries to reuse the storage of the argument lists if possible.
4160 @defun cl-intersection list1 list2 @t{&key :test :test-not :key}
4161 This function computes the intersection of the sets represented
4162 by @var{list1} and @var{list2}. It returns the list of items
4163 which appear in both @var{list1} and @var{list2}.
4166 @defun cl-nintersection list1 list2 @t{&key :test :test-not :key}
4167 This is a destructive version of @code{cl-intersection}. It
4168 tries to reuse storage of @var{list1} rather than copying.
4169 It does @emph{not} reuse the storage of @var{list2}.
4172 @defun cl-set-difference list1 list2 @t{&key :test :test-not :key}
4173 This function computes the ``set difference'' of @var{list1}
4174 and @var{list2}, i.e., the set of elements that appear in
4175 @var{list1} but @emph{not} in @var{list2}.
4178 @defun cl-nset-difference list1 list2 @t{&key :test :test-not :key}
4179 This is a destructive @code{cl-set-difference}, which will try
4180 to reuse @var{list1} if possible.
4183 @defun cl-set-exclusive-or list1 list2 @t{&key :test :test-not :key}
4184 This function computes the ``set exclusive or'' of @var{list1}
4185 and @var{list2}, i.e., the set of elements that appear in
4186 exactly one of @var{list1} and @var{list2}.
4189 @defun cl-nset-exclusive-or list1 list2 @t{&key :test :test-not :key}
4190 This is a destructive @code{cl-set-exclusive-or}, which will try
4191 to reuse @var{list1} and @var{list2} if possible.
4194 @defun cl-subsetp list1 list2 @t{&key :test :test-not :key}
4195 This function checks whether @var{list1} represents a subset
4196 of @var{list2}, i.e., whether every element of @var{list1}
4197 also appears in @var{list2}.
4200 @node Association Lists
4201 @section Association Lists
4204 An @dfn{association list} is a list representing a mapping from
4205 one set of values to another; any list whose elements are cons
4206 cells is an association list.
4208 @defun cl-assoc item a-list @t{&key :test :test-not :key}
4209 This function searches the association list @var{a-list} for an
4210 element whose @code{car} matches (in the sense of @code{:test},
4211 @code{:test-not}, and @code{:key}, or by comparison with @code{eql})
4212 a given @var{item}. It returns the matching element, if any,
4213 otherwise @code{nil}. It ignores elements of @var{a-list} which
4214 are not cons cells. (This corresponds to the behavior of
4215 @code{assq} and @code{assoc} in Emacs Lisp; Common Lisp's
4216 @code{assoc} ignores @code{nil}s but considers any other non-cons
4217 elements of @var{a-list} to be an error.)
4220 @defun cl-rassoc item a-list @t{&key :test :test-not :key}
4221 This function searches for an element whose @code{cdr} matches
4222 @var{item}. If @var{a-list} represents a mapping, this applies
4223 the inverse of the mapping to @var{item}.
4227 @findex cl-assoc-if-not
4228 @findex cl-rassoc-if
4229 @findex cl-rassoc-if-not
4230 The @code{cl-assoc-if}, @code{cl-assoc-if-not}, @code{cl-rassoc-if},
4231 and @code{cl-rassoc-if-not} functions are defined similarly.
4233 Two simple functions for constructing association lists are:
4235 @defun cl-acons key value alist
4236 This is equivalent to @code{(cons (cons @var{key} @var{value}) @var{alist})}.
4239 @defun cl-pairlis keys values &optional alist
4240 This is equivalent to @code{(nconc (cl-mapcar 'cons @var{keys} @var{values})
4248 The Common Lisp @dfn{structure} mechanism provides a general way
4249 to define data types similar to C's @code{struct} types. A
4250 structure is a Lisp object containing some number of @dfn{slots},
4251 each of which can hold any Lisp data object. Functions are
4252 provided for accessing and setting the slots, creating or copying
4253 structure objects, and recognizing objects of a particular structure
4256 In true Common Lisp, each structure type is a new type distinct
4257 from all existing Lisp types. Since the underlying Emacs Lisp
4258 system provides no way to create new distinct types, this package
4259 implements structures as vectors (or lists upon request) with a
4260 special ``tag'' symbol to identify them.
4262 @defmac cl-defstruct name slots@dots{}
4263 The @code{cl-defstruct} form defines a new structure type called
4264 @var{name}, with the specified @var{slots}. (The @var{slots}
4265 may begin with a string which documents the structure type.)
4266 In the simplest case, @var{name} and each of the @var{slots}
4267 are symbols. For example,
4270 (cl-defstruct person name age sex)
4274 defines a struct type called @code{person} which contains three
4275 slots. Given a @code{person} object @var{p}, you can access those
4276 slots by calling @code{(person-name @var{p})}, @code{(person-age @var{p})},
4277 and @code{(person-sex @var{p})}. You can also change these slots by
4278 using @code{setf} on any of these place forms:
4281 (cl-incf (person-age birthday-boy))
4284 You can create a new @code{person} by calling @code{make-person},
4285 which takes keyword arguments @code{:name}, @code{:age}, and
4286 @code{:sex} to specify the initial values of these slots in the
4287 new object. (Omitting any of these arguments leaves the corresponding
4288 slot ``undefined'', according to the Common Lisp standard; in Emacs
4289 Lisp, such uninitialized slots are filled with @code{nil}.)
4291 Given a @code{person}, @code{(copy-person @var{p})} makes a new
4292 object of the same type whose slots are @code{eq} to those of @var{p}.
4294 Given any Lisp object @var{x}, @code{(person-p @var{x})} returns
4295 true if @var{x} looks like a @code{person}, false otherwise. (Again,
4296 in Common Lisp this predicate would be exact; in Emacs Lisp the
4297 best it can do is verify that @var{x} is a vector of the correct
4298 length which starts with the correct tag symbol.)
4300 Accessors like @code{person-name} normally check their arguments
4301 (effectively using @code{person-p}) and signal an error if the
4302 argument is the wrong type. This check is affected by
4303 @code{(optimize (safety @dots{}))} declarations. Safety level 1,
4304 the default, uses a somewhat optimized check that will detect all
4305 incorrect arguments, but may use an uninformative error message
4306 (e.g., ``expected a vector'' instead of ``expected a @code{person}'').
4307 Safety level 0 omits all checks except as provided by the underlying
4308 @code{aref} call; safety levels 2 and 3 do rigorous checking that will
4309 always print a descriptive error message for incorrect inputs.
4310 @xref{Declarations}.
4313 (setq dave (make-person :name "Dave" :sex 'male))
4314 @result{} [cl-struct-person "Dave" nil male]
4315 (setq other (copy-person dave))
4316 @result{} [cl-struct-person "Dave" nil male]
4319 (eq (person-name dave) (person-name other))
4323 (person-p [1 2 3 4])
4327 (person-p '[cl-struct-person counterfeit person object])
4331 In general, @var{name} is either a name symbol or a list of a name
4332 symbol followed by any number of @dfn{struct options}; each @var{slot}
4333 is either a slot symbol or a list of the form @samp{(@var{slot-name}
4334 @var{default-value} @var{slot-options}@dots{})}. The @var{default-value}
4335 is a Lisp form which is evaluated any time an instance of the
4336 structure type is created without specifying that slot's value.
4338 Common Lisp defines several slot options, but the only one
4339 implemented in this package is @code{:read-only}. A non-@code{nil}
4340 value for this option means the slot should not be @code{setf}-able;
4341 the slot's value is determined when the object is created and does
4342 not change afterward.
4345 (cl-defstruct person
4346 (name nil :read-only t)
4351 Any slot options other than @code{:read-only} are ignored.
4353 For obscure historical reasons, structure options take a different
4354 form than slot options. A structure option is either a keyword
4355 symbol, or a list beginning with a keyword symbol possibly followed
4356 by arguments. (By contrast, slot options are key-value pairs not
4360 (cl-defstruct (person (:constructor create-person)
4366 The following structure options are recognized.
4370 The argument is a symbol whose print name is used as the prefix for
4371 the names of slot accessor functions. The default is the name of
4372 the struct type followed by a hyphen. The option @code{(:conc-name p-)}
4373 would change this prefix to @code{p-}. Specifying @code{nil} as an
4374 argument means no prefix, so that the slot names themselves are used
4375 to name the accessor functions.
4378 In the simple case, this option takes one argument which is an
4379 alternate name to use for the constructor function. The default
4380 is @code{make-@var{name}}, e.g., @code{make-person}. The above
4381 example changes this to @code{create-person}. Specifying @code{nil}
4382 as an argument means that no standard constructor should be
4385 In the full form of this option, the constructor name is followed
4386 by an arbitrary argument list. @xref{Program Structure}, for a
4387 description of the format of Common Lisp argument lists. All
4388 options, such as @code{&rest} and @code{&key}, are supported.
4389 The argument names should match the slot names; each slot is
4390 initialized from the corresponding argument. Slots whose names
4391 do not appear in the argument list are initialized based on the
4392 @var{default-value} in their slot descriptor. Also, @code{&optional}
4393 and @code{&key} arguments which don't specify defaults take their
4394 defaults from the slot descriptor. It is valid to include arguments
4395 which don't correspond to slot names; these are useful if they are
4396 referred to in the defaults for optional, keyword, or @code{&aux}
4397 arguments which @emph{do} correspond to slots.
4399 You can specify any number of full-format @code{:constructor}
4400 options on a structure. The default constructor is still generated
4401 as well unless you disable it with a simple-format @code{:constructor}
4407 (:constructor nil) ; no default constructor
4408 (:constructor new-person
4409 (name sex &optional (age 0)))
4410 (:constructor new-hound (&key (name "Rover")
4412 &aux (age (* 7 dog-years))
4417 The first constructor here takes its arguments positionally rather
4418 than by keyword. (In official Common Lisp terminology, constructors
4419 that work By Order of Arguments instead of by keyword are called
4420 ``BOA constructors''. No, I'm not making this up.) For example,
4421 @code{(new-person "Jane" 'female)} generates a person whose slots
4422 are @code{"Jane"}, 0, and @code{female}, respectively.
4424 The second constructor takes two keyword arguments, @code{:name},
4425 which initializes the @code{name} slot and defaults to @code{"Rover"},
4426 and @code{:dog-years}, which does not itself correspond to a slot
4427 but which is used to initialize the @code{age} slot. The @code{sex}
4428 slot is forced to the symbol @code{canine} with no syntax for
4432 The argument is an alternate name for the copier function for
4433 this type. The default is @code{copy-@var{name}}. @code{nil}
4434 means not to generate a copier function. (In this implementation,
4435 all copier functions are simply synonyms for @code{copy-sequence}.)
4438 The argument is an alternate name for the predicate which recognizes
4439 objects of this type. The default is @code{@var{name}-p}. @code{nil}
4440 means not to generate a predicate function. (If the @code{:type}
4441 option is used without the @code{:named} option, no predicate is
4444 In true Common Lisp, @code{typep} is always able to recognize a
4445 structure object even if @code{:predicate} was used. In this
4446 package, @code{cl-typep} simply looks for a function called
4447 @code{@var{typename}-p}, so it will work for structure types
4448 only if they used the default predicate name.
4451 This option implements a very limited form of C++-style inheritance.
4452 The argument is the name of another structure type previously
4453 created with @code{cl-defstruct}. The effect is to cause the new
4454 structure type to inherit all of the included structure's slots
4455 (plus, of course, any new slots described by this struct's slot
4456 descriptors). The new structure is considered a ``specialization''
4457 of the included one. In fact, the predicate and slot accessors
4458 for the included type will also accept objects of the new type.
4460 If there are extra arguments to the @code{:include} option after
4461 the included-structure name, these options are treated as replacement
4462 slot descriptors for slots in the included structure, possibly with
4463 modified default values. Borrowing an example from Steele:
4466 (cl-defstruct person name (age 0) sex)
4468 (cl-defstruct (astronaut (:include person (age 45)))
4470 (favorite-beverage 'tang))
4473 (setq joe (make-person :name "Joe"))
4474 @result{} [cl-struct-person "Joe" 0 nil]
4475 (setq buzz (make-astronaut :name "Buzz"))
4476 @result{} [cl-struct-astronaut "Buzz" 45 nil nil tang]
4478 (list (person-p joe) (person-p buzz))
4480 (list (astronaut-p joe) (astronaut-p buzz))
4485 (astronaut-name joe)
4486 @result{} error: "astronaut-name accessing a non-astronaut"
4489 Thus, if @code{astronaut} is a specialization of @code{person},
4490 then every @code{astronaut} is also a @code{person} (but not the
4491 other way around). Every @code{astronaut} includes all the slots
4492 of a @code{person}, plus extra slots that are specific to
4493 astronauts. Operations that work on people (like @code{person-name})
4494 work on astronauts just like other people.
4496 @item :print-function
4497 In full Common Lisp, this option allows you to specify a function
4498 which is called to print an instance of the structure type. The
4499 Emacs Lisp system offers no hooks into the Lisp printer which would
4500 allow for such a feature, so this package simply ignores
4501 @code{:print-function}.
4504 The argument should be one of the symbols @code{vector} or @code{list}.
4505 This tells which underlying Lisp data type should be used to implement
4506 the new structure type. Vectors are used by default, but
4507 @code{(:type list)} will cause structure objects to be stored as
4510 The vector representation for structure objects has the advantage
4511 that all structure slots can be accessed quickly, although creating
4512 vectors is a bit slower in Emacs Lisp. Lists are easier to create,
4513 but take a relatively long time accessing the later slots.
4516 This option, which takes no arguments, causes a characteristic ``tag''
4517 symbol to be stored at the front of the structure object. Using
4518 @code{:type} without also using @code{:named} will result in a
4519 structure type stored as plain vectors or lists with no identifying
4522 The default, if you don't specify @code{:type} explicitly, is to
4523 use named vectors. Therefore, @code{:named} is only useful in
4524 conjunction with @code{:type}.
4527 (cl-defstruct (person1) name age sex)
4528 (cl-defstruct (person2 (:type list) :named) name age sex)
4529 (cl-defstruct (person3 (:type list)) name age sex)
4531 (setq p1 (make-person1))
4532 @result{} [cl-struct-person1 nil nil nil]
4533 (setq p2 (make-person2))
4534 @result{} (person2 nil nil nil)
4535 (setq p3 (make-person3))
4536 @result{} (nil nil nil)
4543 @result{} error: function person3-p undefined
4546 Since unnamed structures don't have tags, @code{cl-defstruct} is not
4547 able to make a useful predicate for recognizing them. Also,
4548 accessors like @code{person3-name} will be generated but they
4549 will not be able to do any type checking. The @code{person3-name}
4550 function, for example, will simply be a synonym for @code{car} in
4551 this case. By contrast, @code{person2-name} is able to verify
4552 that its argument is indeed a @code{person2} object before
4555 @item :initial-offset
4556 The argument must be a nonnegative integer. It specifies a
4557 number of slots to be left ``empty'' at the front of the
4558 structure. If the structure is named, the tag appears at the
4559 specified position in the list or vector; otherwise, the first
4560 slot appears at that position. Earlier positions are filled
4561 with @code{nil} by the constructors and ignored otherwise. If
4562 the type @code{:include}s another type, then @code{:initial-offset}
4563 specifies a number of slots to be skipped between the last slot
4564 of the included type and the first new slot.
4568 Except as noted, the @code{cl-defstruct} facility of this package is
4569 entirely compatible with that of Common Lisp.
4572 @chapter Assertions and Errors
4575 This section describes two macros that test @dfn{assertions}, i.e.,
4576 conditions which must be true if the program is operating correctly.
4577 Assertions never add to the behavior of a Lisp program; they simply
4578 make ``sanity checks'' to make sure everything is as it should be.
4580 If the optimization property @code{speed} has been set to 3, and
4581 @code{safety} is less than 3, then the byte-compiler will optimize
4582 away the following assertions. Because assertions might be optimized
4583 away, it is a bad idea for them to include side-effects.
4585 @defmac cl-assert test-form [show-args string args@dots{}]
4586 This form verifies that @var{test-form} is true (i.e., evaluates to
4587 a non-@code{nil} value). If so, it returns @code{nil}. If the test
4588 is not satisfied, @code{cl-assert} signals an error.
4590 A default error message will be supplied which includes @var{test-form}.
4591 You can specify a different error message by including a @var{string}
4592 argument plus optional extra arguments. Those arguments are simply
4593 passed to @code{error} to signal the error.
4595 If the optional second argument @var{show-args} is @code{t} instead
4596 of @code{nil}, then the error message (with or without @var{string})
4597 will also include all non-constant arguments of the top-level
4598 @var{form}. For example:
4601 (cl-assert (> x 10) t "x is too small: %d")
4604 This usage of @var{show-args} is an extension to Common Lisp. In
4605 true Common Lisp, the second argument gives a list of @var{places}
4606 which can be @code{setf}'d by the user before continuing from the
4607 error. Since Emacs Lisp does not support continuable errors, it
4608 makes no sense to specify @var{places}.
4611 @defmac cl-check-type form type [string]
4612 This form verifies that @var{form} evaluates to a value of type
4613 @var{type}. If so, it returns @code{nil}. If not, @code{cl-check-type}
4614 signals a @code{wrong-type-argument} error. The default error message
4615 lists the erroneous value along with @var{type} and @var{form}
4616 themselves. If @var{string} is specified, it is included in the
4617 error message in place of @var{type}. For example:
4620 (cl-check-type x (integer 1 *) "a positive integer")
4623 @xref{Type Predicates}, for a description of the type specifiers
4624 that may be used for @var{type}.
4626 Note that in Common Lisp, the first argument to @code{check-type}
4627 must be a @var{place} suitable for use by @code{setf}, because
4628 @code{check-type} signals a continuable error that allows the
4629 user to modify @var{place}.
4632 @node Efficiency Concerns
4633 @appendix Efficiency Concerns
4638 Many of the advanced features of this package, such as @code{cl-defun},
4639 @code{cl-loop}, etc., are implemented as Lisp macros. In
4640 byte-compiled code, these complex notations will be expanded into
4641 equivalent Lisp code which is simple and efficient. For example,
4649 is expanded at compile-time to the Lisp form
4656 which is the most efficient ways of doing this operation
4657 in Lisp. Thus, there is no performance penalty for using the more
4658 readable @code{cl-incf} form in your compiled code.
4660 @emph{Interpreted} code, on the other hand, must expand these macros
4661 every time they are executed. For this reason it is strongly
4662 recommended that code making heavy use of macros be compiled.
4663 A loop using @code{cl-incf} a hundred times will execute considerably
4664 faster if compiled, and will also garbage-collect less because the
4665 macro expansion will not have to be generated, used, and thrown away a
4668 You can find out how a macro expands by using the
4669 @code{cl-prettyexpand} function.
4671 @defun cl-prettyexpand form &optional full
4672 This function takes a single Lisp form as an argument and inserts
4673 a nicely formatted copy of it in the current buffer (which must be
4674 in Lisp mode so that indentation works properly). It also expands
4675 all Lisp macros which appear in the form. The easiest way to use
4676 this function is to go to the @file{*scratch*} buffer and type, say,
4679 (cl-prettyexpand '(cl-loop for x below 10 collect x))
4683 and type @kbd{C-x C-e} immediately after the closing parenthesis;
4691 (setq G1004 (cons x G1004))
4697 will be inserted into the buffer. (The @code{cl-block} macro is
4698 expanded differently in the interpreter and compiler, so
4699 @code{cl-prettyexpand} just leaves it alone. The temporary
4700 variable @code{G1004} was created by @code{cl-gensym}.)
4702 If the optional argument @var{full} is true, then @emph{all}
4703 macros are expanded, including @code{cl-block}, @code{cl-eval-when},
4704 and compiler macros. Expansion is done as if @var{form} were
4705 a top-level form in a file being compiled. For example,
4708 (cl-prettyexpand '(cl-pushnew 'x list))
4709 @print{} (setq list (cl-adjoin 'x list))
4710 (cl-prettyexpand '(cl-pushnew 'x list) t)
4711 @print{} (setq list (if (memq 'x list) list (cons 'x list)))
4712 (cl-prettyexpand '(caddr (cl-member 'a list)) t)
4713 @print{} (car (cdr (cdr (memq 'a list))))
4716 Note that @code{cl-adjoin}, @code{cl-caddr}, and @code{cl-member} all
4717 have built-in compiler macros to optimize them in common cases.
4725 @appendixsec Error Checking
4728 Common Lisp compliance has in general not been sacrificed for the
4729 sake of efficiency. A few exceptions have been made for cases
4730 where substantial gains were possible at the expense of marginal
4733 The Common Lisp standard (as embodied in Steele's book) uses the
4734 phrase ``it is an error if'' to indicate a situation which is not
4735 supposed to arise in complying programs; implementations are strongly
4736 encouraged but not required to signal an error in these situations.
4737 This package sometimes omits such error checking in the interest of
4738 compactness and efficiency. For example, @code{cl-do} variable
4739 specifiers are supposed to be lists of one, two, or three forms;
4740 extra forms are ignored by this package rather than signaling a
4741 syntax error. The @code{cl-endp} function is simply a synonym for
4742 @code{null} in this package. Functions taking keyword arguments
4743 will accept an odd number of arguments, treating the trailing
4744 keyword as if it were followed by the value @code{nil}.
4746 Argument lists (as processed by @code{cl-defun} and friends)
4747 @emph{are} checked rigorously except for the minor point just
4748 mentioned; in particular, keyword arguments are checked for
4749 validity, and @code{&allow-other-keys} and @code{:allow-other-keys}
4750 are fully implemented. Keyword validity checking is slightly
4751 time consuming (though not too bad in byte-compiled code);
4752 you can use @code{&allow-other-keys} to omit this check. Functions
4753 defined in this package such as @code{cl-find} and @code{cl-member}
4754 do check their keyword arguments for validity.
4761 @appendixsec Optimizing Compiler
4764 Use of the optimizing Emacs compiler is highly recommended; many of the Common
4766 code which can be improved by optimization. In particular,
4767 @code{cl-block}s (whether explicit or implicit in constructs like
4768 @code{cl-defun} and @code{cl-loop}) carry a fair run-time penalty; the
4769 optimizing compiler removes @code{cl-block}s which are not actually
4770 referenced by @code{cl-return} or @code{cl-return-from} inside the block.
4772 @node Common Lisp Compatibility
4773 @appendix Common Lisp Compatibility
4776 Following is a list of all known incompatibilities between this
4777 package and Common Lisp as documented in Steele (2nd edition).
4780 Certain function names, such as @code{member}, @code{assoc}, and
4781 @code{floor}, were already taken by (incompatible) Emacs Lisp
4782 functions; this package appends @samp{*} to the names of its
4783 Common Lisp versions of these functions.
4786 The word @code{cl-defun} is required instead of @code{defun} in order
4787 to use extended Common Lisp argument lists in a function. Likewise,
4788 @code{cl-defmacro} and @code{cl-function} are versions of those forms
4789 which understand full-featured argument lists. The @code{&whole}
4790 keyword does not work in @code{defmacro} argument lists (except
4791 inside recursive argument lists).
4793 The @code{equal} predicate does not distinguish
4794 between IEEE floating-point plus and minus zero. The @code{cl-equalp}
4795 predicate has several differences with Common Lisp; @pxref{Predicates}.
4797 The @code{setf} mechanism is entirely compatible, except that
4798 setf-methods return a list of five values rather than five
4799 values directly. Also, the new ``@code{setf} function'' concept
4800 (typified by @code{(defun (setf foo) @dots{})}) is not implemented.
4802 The @code{cl-do-all-symbols} form is the same as @code{cl-do-symbols}
4803 with no @var{obarray} argument. In Common Lisp, this form would
4804 iterate over all symbols in all packages. Since Emacs obarrays
4805 are not a first-class package mechanism, there is no way for
4806 @code{cl-do-all-symbols} to locate any but the default obarray.
4808 The @code{cl-loop} macro is complete except that @code{loop-finish}
4809 and type specifiers are unimplemented.
4811 The multiple-value return facility treats lists as multiple
4812 values, since Emacs Lisp cannot support multiple return values
4813 directly. The macros will be compatible with Common Lisp if
4814 @code{values} or @code{values-list} is always used to return to
4815 a @code{cl-multiple-value-bind} or other multiple-value receiver;
4816 if @code{values} is used without @code{cl-multiple-value-@dots{}}
4817 or vice-versa the effect will be different from Common Lisp.
4819 Many Common Lisp declarations are ignored, and others match
4820 the Common Lisp standard in concept but not in detail. For
4821 example, local @code{special} declarations, which are purely
4822 advisory in Emacs Lisp, do not rigorously obey the scoping rules
4823 set down in Steele's book.
4825 The variable @code{cl--gensym-counter} starts out with a pseudo-random
4826 value rather than with zero. This is to cope with the fact that
4827 generated symbols become interned when they are written to and
4828 loaded back from a file.
4830 The @code{cl-defstruct} facility is compatible, except that structures
4831 are of type @code{:type vector :named} by default rather than some
4832 special, distinct type. Also, the @code{:type} slot option is ignored.
4834 The second argument of @code{cl-check-type} is treated differently.
4836 @node Porting Common Lisp
4837 @appendix Porting Common Lisp
4840 This package is meant to be used as an extension to Emacs Lisp,
4841 not as an Emacs implementation of true Common Lisp. Some of the
4842 remaining differences between Emacs Lisp and Common Lisp make it
4843 difficult to port large Common Lisp applications to Emacs. For
4844 one, some of the features in this package are not fully compliant
4845 with ANSI or Steele; @pxref{Common Lisp Compatibility}. But there
4846 are also quite a few features that this package does not provide
4847 at all. Here are some major omissions that you will want to watch out
4848 for when bringing Common Lisp code into Emacs.
4852 Case-insensitivity. Symbols in Common Lisp are case-insensitive
4853 by default. Some programs refer to a function or variable as
4854 @code{foo} in one place and @code{Foo} or @code{FOO} in another.
4855 Emacs Lisp will treat these as three distinct symbols.
4857 Some Common Lisp code is written entirely in upper case. While Emacs
4858 is happy to let the program's own functions and variables use
4859 this convention, calls to Lisp builtins like @code{if} and
4860 @code{defun} will have to be changed to lower case.
4863 Lexical scoping. In Common Lisp, function arguments and @code{let}
4864 bindings apply only to references physically within their bodies
4865 (or within macro expansions in their bodies). Emacs Lisp, by
4866 contrast, uses @dfn{dynamic scoping} wherein a binding to a
4867 variable is visible even inside functions called from the body.
4869 Variables in Common Lisp can be made dynamically scoped by
4870 declaring them @code{special} or using @code{defvar}. In Emacs
4871 Lisp it is as if all variables were declared @code{special}.
4873 Often you can use code that was written for lexical scoping
4874 even in a dynamically scoped Lisp, but not always. Here is
4875 an example of a Common Lisp code fragment that would fail in
4879 (defun map-odd-elements (func list)
4881 for flag = t then (not flag)
4882 collect (if flag x (funcall func x))))
4884 (defun add-odd-elements (list x)
4885 (map-odd-elements (lambda (a) (+ a x)) list))
4889 In Common Lisp, the two functions' usages of @code{x} are completely
4890 independent. In Emacs Lisp, the binding to @code{x} made by
4891 @code{add-odd-elements} will have been hidden by the binding
4892 in @code{map-odd-elements} by the time the @code{(+ a x)} function
4895 (This package avoids such problems in its own mapping functions
4896 by using names like @code{cl--x} instead of @code{x} internally;
4897 as long as you don't use this prefix for your own
4898 variables no collision can occur.)
4900 @xref{Lexical Bindings}, for a description of the @code{lexical-let}
4901 form which establishes a Common Lisp-style lexical binding, and some
4902 examples of how it differs from Emacs's regular @code{let}.
4905 Reader macros. Common Lisp includes a second type of macro that
4906 works at the level of individual characters. For example, Common
4907 Lisp implements the quote notation by a reader macro called @code{'},
4908 whereas Emacs Lisp's parser just treats quote as a special case.
4909 Some Lisp packages use reader macros to create special syntaxes
4910 for themselves, which the Emacs parser is incapable of reading.
4913 Other syntactic features. Common Lisp provides a number of
4914 notations beginning with @code{#} that the Emacs Lisp parser
4915 won't understand. For example, @samp{#| ... |#} is an
4916 alternate comment notation, and @samp{#+lucid (foo)} tells
4917 the parser to ignore the @code{(foo)} except in Lucid Common
4921 Packages. In Common Lisp, symbols are divided into @dfn{packages}.
4922 Symbols that are Lisp built-ins are typically stored in one package;
4923 symbols that are vendor extensions are put in another, and each
4924 application program would have a package for its own symbols.
4925 Certain symbols are ``exported'' by a package and others are
4926 internal; certain packages ``use'' or import the exported symbols
4927 of other packages. To access symbols that would not normally be
4928 visible due to this importing and exporting, Common Lisp provides
4929 a syntax like @code{package:symbol} or @code{package::symbol}.
4931 Emacs Lisp has a single namespace for all interned symbols, and
4932 then uses a naming convention of putting a prefix like @code{cl-}
4933 in front of the name. Some Emacs packages adopt the Common Lisp-like
4934 convention of using @code{cl:} or @code{cl::} as the prefix.
4935 However, the Emacs parser does not understand colons and just
4936 treats them as part of the symbol name. Thus, while @code{mapcar}
4937 and @code{lisp:mapcar} may refer to the same symbol in Common
4938 Lisp, they are totally distinct in Emacs Lisp. Common Lisp
4939 programs which refer to a symbol by the full name sometimes
4940 and the short name other times will not port cleanly to Emacs.
4942 Emacs Lisp does have a concept of ``obarrays'', which are
4943 package-like collections of symbols, but this feature is not
4944 strong enough to be used as a true package mechanism.
4947 The @code{format} function is quite different between Common
4948 Lisp and Emacs Lisp. It takes an additional ``destination''
4949 argument before the format string. A destination of @code{nil}
4950 means to format to a string as in Emacs Lisp; a destination
4951 of @code{t} means to write to the terminal (similar to
4952 @code{message} in Emacs). Also, format control strings are
4953 utterly different; @code{~} is used instead of @code{%} to
4954 introduce format codes, and the set of available codes is
4955 much richer. There are no notations like @code{\n} for
4956 string literals; instead, @code{format} is used with the
4957 ``newline'' format code, @code{~%}. More advanced formatting
4958 codes provide such features as paragraph filling, case
4959 conversion, and even loops and conditionals.
4961 While it would have been possible to implement most of Common
4962 Lisp @code{format} in this package (under the name @code{cl-format},
4963 of course), it was not deemed worthwhile. It would have required
4964 a huge amount of code to implement even a decent subset of
4965 @code{cl-format}, yet the functionality it would provide over
4966 Emacs Lisp's @code{format} would rarely be useful.
4969 Vector constants use square brackets in Emacs Lisp, but
4970 @code{#(a b c)} notation in Common Lisp. To further complicate
4971 matters, Emacs has its own @code{#(} notation for
4972 something entirely different---strings with properties.
4975 Characters are distinct from integers in Common Lisp. The notation
4976 for character constants is also different: @code{#\A} in Common Lisp
4977 where Emacs Lisp uses @code{?A}. Also, @code{string=} and
4978 @code{string-equal} are synonyms in Emacs Lisp, whereas the latter is
4979 case-insensitive in Common Lisp.
4982 Data types. Some Common Lisp data types do not exist in Emacs
4983 Lisp. Rational numbers and complex numbers are not present,
4984 nor are large integers (all integers are ``fixnums''). All
4985 arrays are one-dimensional. There are no readtables or pathnames;
4986 streams are a set of existing data types rather than a new data
4987 type of their own. Hash tables, random-states, structures, and
4988 packages (obarrays) are built from Lisp vectors or lists rather
4989 than being distinct types.
4992 The Common Lisp Object System (CLOS) is not implemented,
4993 nor is the Common Lisp Condition System. However, the EIEIO package
4994 (@pxref{Top, , Introduction, eieio, EIEIO}) does implement some
4998 Common Lisp features that are completely redundant with Emacs
4999 Lisp features of a different name generally have not been
5000 implemented. For example, Common Lisp writes @code{defconstant}
5001 where Emacs Lisp uses @code{defconst}. Similarly, @code{make-list}
5002 takes its arguments in different ways in the two Lisps but does
5003 exactly the same thing, so this package has not bothered to
5004 implement a Common Lisp-style @code{make-list}.
5007 A few more notable Common Lisp features not included in this
5008 package: @code{compiler-let}, @code{tagbody}, @code{prog},
5009 @code{ldb/dpb}, @code{parse-integer}, @code{cerror}.
5012 Recursion. While recursion works in Emacs Lisp just like it
5013 does in Common Lisp, various details of the Emacs Lisp system
5014 and compiler make recursion much less efficient than it is in
5015 most Lisps. Some schools of thought prefer to use recursion
5016 in Lisp over other techniques; they would sum a list of
5017 numbers using something like
5020 (defun sum-list (list)
5022 (+ (car list) (sum-list (cdr list)))
5027 where a more iteratively-minded programmer might write one of
5031 (let ((total 0)) (dolist (x my-list) (cl-incf total x)) total)
5032 (cl-loop for x in my-list sum x)
5035 While this would be mainly a stylistic choice in most Common Lisps,
5036 in Emacs Lisp you should be aware that the iterative forms are
5037 much faster than recursion. Also, Lisp programmers will want to
5038 note that the current Emacs Lisp compiler does not optimize tail
5042 @node GNU Free Documentation License
5043 @appendix GNU Free Documentation License
5044 @include doclicense.texi
5046 @node Function Index
5047 @unnumbered Function Index
5051 @node Variable Index
5052 @unnumbered Variable Index