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, organization, naming conventions.
58 * Program Structure:: Arglists, @code{cl-eval-when}.
59 * Predicates:: Type predicates and equality predicates.
60 * Control Structure:: Assignment, conditionals, blocks, looping.
61 * Macros:: Destructuring, compiler macros.
62 * Declarations:: @code{cl-proclaim}, @code{cl-declare}, etc.
63 * Symbols:: Property lists, creating symbols.
64 * Numbers:: Predicates, functions, random numbers.
65 * Sequences:: Mapping, functions, searching, sorting.
66 * Lists:: Functions, substitution, sets, associations.
67 * Structures:: @code{cl-defstruct}.
68 * Assertions:: Assertions and type checking.
71 * Efficiency Concerns:: Hints and techniques.
72 * Common Lisp Compatibility:: All known differences with Steele.
73 * Porting Common Lisp:: Hints for porting Common Lisp code.
74 * Obsolete Features:: Obsolete features.
75 * GNU Free Documentation License:: The license for this documentation.
78 * Function Index:: An entry for each documented function.
79 * Variable Index:: An entry for each documented variable.
86 This document describes a set of Emacs Lisp facilities borrowed from
87 Common Lisp. All the facilities are described here in detail. While
88 this document does not assume any prior knowledge of Common Lisp, it
89 does assume a basic familiarity with Emacs Lisp.
91 Common Lisp is a huge language, and Common Lisp systems tend to be
92 massive and extremely complex. Emacs Lisp, by contrast, is rather
93 minimalist in the choice of Lisp features it offers the programmer.
94 As Emacs Lisp programmers have grown in number, and the applications
95 they write have grown more ambitious, it has become clear that Emacs
96 Lisp could benefit from many of the conveniences of Common Lisp.
98 The @dfn{CL} package adds a number of Common Lisp functions and
99 control structures to Emacs Lisp. While not a 100% complete
100 implementation of Common Lisp, it adds enough functionality
101 to make Emacs Lisp programming significantly more convenient.
103 Some Common Lisp features have been omitted from this package
108 Some features are too complex or bulky relative to their benefit
109 to Emacs Lisp programmers. CLOS and Common Lisp streams are fine
110 examples of this group.
113 Other features cannot be implemented without modification to the
114 Emacs Lisp interpreter itself, such as multiple return values,
115 case-insensitive symbols, and complex numbers.
116 This package generally makes no attempt to emulate these features.
120 This package was originally written by Dave Gillespie,
121 @file{daveg@@synaptics.com}, as a total rewrite of an earlier 1986
122 @file{cl.el} package by Cesar Quiroz. Care has been taken to ensure
123 that each function is defined efficiently, concisely, and with minimal
124 impact on the rest of the Emacs environment. Stefan Monnier added the
125 file @file{cl-lib.el} and rationalized the namespace for Emacs 24.3.
128 * Usage:: How to use this package.
129 * Organization:: The package's component files.
130 * Naming Conventions:: Notes on function names.
137 This package is distributed with Emacs, so there is no need
138 to install any additional files in order to start using it. Lisp code
139 that uses features from this package should simply include at
147 You may wish to add such a statement to your init file, if you
148 make frequent use of features from this package.
151 @section Organization
154 The Common Lisp package is organized into four main files:
158 This is the main file, which contains basic functions
159 and information about the package. This file is relatively compact.
162 This file contains the larger, more complex or unusual functions.
163 It is kept separate so that packages which only want to use Common
164 Lisp fundamentals like the @code{cl-incf} function won't need to pay
165 the overhead of loading the more advanced functions.
168 This file contains most of the advanced functions for operating
169 on sequences or lists, such as @code{cl-delete-if} and @code{cl-assoc}.
172 This file contains the features that are macros instead of functions.
173 Macros expand when the caller is compiled, not when it is run, so the
174 macros generally only need to be present when the byte-compiler is
175 running (or when the macros are used in uncompiled code). Most of the
176 macros of this package are isolated in @file{cl-macs.el} so that they
177 won't take up memory unless you are compiling.
180 The file @file{cl-lib.el} includes all necessary @code{autoload}
181 commands for the functions and macros in the other three files.
182 All you have to do is @code{(require 'cl-lib)}, and @file{cl-lib.el}
183 will take care of pulling in the other files when they are
186 There is another file, @file{cl.el}, which was the main entry point to
187 this package prior to Emacs 24.3. Nowadays, it is replaced by
188 @file{cl-lib.el}. The two provide the same features (in most cases),
189 but use different function names (in fact, @file{cl.el} mainly just
190 defines aliases to the @file{cl-lib.el} definitions). Where
191 @file{cl-lib.el} defines a function called, for example,
192 @code{cl-incf}, @file{cl.el} uses the same name but without the
193 @samp{cl-} prefix, e.g.@: @code{incf} in this example. There are a few
194 exceptions to this. First, functions such as @code{cl-defun} where
195 the unprefixed version was already used for a standard Emacs Lisp
196 function. In such cases, the @file{cl.el} version adds a @samp{*}
197 suffix, e.g.@: @code{defun*}. Second, there are some obsolete features
198 that are only implemented in @file{cl.el}, not in @file{cl-lib.el},
199 because they are replaced by other standard Emacs Lisp features.
200 Finally, in a very few cases the old @file{cl.el} versions do not
201 behave in exactly the same way as the @file{cl-lib.el} versions.
202 @xref{Obsolete Features}.
203 @c There is also cl-mapc, which was called cl-mapc even before cl-lib.el.
204 @c But not autoloaded, so maybe not much used?
206 Since the old @file{cl.el} does not use a clean namespace, Emacs has a
207 policy that packages distributed with Emacs must not load @code{cl} at
208 run time. (It is ok for them to load @code{cl} at @emph{compile}
209 time, with @code{eval-when-compile}, and use the macros it provides.)
210 There is no such restriction on the use of @code{cl-lib}. New code
211 should use @code{cl-lib} rather than @code{cl}.
213 There is one more file, @file{cl-compat.el}, which defines some
214 routines from the older Quiroz @file{cl.el} package that are not otherwise
215 present in the new package. This file is obsolete and should not be
218 @node Naming Conventions
219 @section Naming Conventions
222 Except where noted, all functions defined by this package have the
223 same calling conventions as their Common Lisp counterparts, and
224 names that are those of Common Lisp plus a @samp{cl-} prefix.
226 Internal function and variable names in the package are prefixed
227 by @code{cl--}. Here is a complete list of functions prefixed by
228 @code{cl-} that were @emph{not} taken from Common Lisp:
231 cl-callf cl-callf2 cl-defsubst
232 cl-floatp-safe cl-letf cl-letf*
235 @c This is not uninteresting I suppose, but is of zero practical relevance
236 @c to the user, and seems like a hostage to changing implementation details.
237 The following simple functions and macros are defined in @file{cl-lib.el};
238 they do not cause other components like @file{cl-extra} to be loaded.
241 cl-evenp cl-oddp cl-minusp
242 cl-plusp cl-floatp-safe cl-endp
243 cl-copy-list cl-list* cl-ldiff
244 cl-rest cl-decf [1] cl-incf [1]
245 cl-acons cl-adjoin [2] cl-pairlis
246 cl-pushnew [1,2] cl-declaim cl-proclaim
247 cl-caaar@dots{}cl-cddddr cl-first@dots{}cl-tenth
248 cl-subst cl-mapcar [3]
252 [1] Only when @var{place} is a plain variable name.
255 [2] Only if @code{:test} is @code{eq}, @code{equal}, or unspecified,
256 and @code{:key} is not used.
259 [3] Only for one sequence argument or two list arguments.
261 @node Program Structure
262 @chapter Program Structure
265 This section describes features of this package that have to
266 do with programs as a whole: advanced argument lists for functions,
267 and the @code{cl-eval-when} construct.
270 * Argument Lists:: @code{&key}, @code{&aux}, @code{cl-defun}, @code{cl-defmacro}.
271 * Time of Evaluation:: The @code{cl-eval-when} construct.
275 @section Argument Lists
278 Emacs Lisp's notation for argument lists of functions is a subset of
279 the Common Lisp notation. As well as the familiar @code{&optional}
280 and @code{&rest} markers, Common Lisp allows you to specify default
281 values for optional arguments, and it provides the additional markers
282 @code{&key} and @code{&aux}.
284 Since argument parsing is built-in to Emacs, there is no way for
285 this package to implement Common Lisp argument lists seamlessly.
286 Instead, this package defines alternates for several Lisp forms
287 which you must use if you need Common Lisp argument lists.
289 @defmac cl-defun name arglist body@dots{}
290 This form is identical to the regular @code{defun} form, except
291 that @var{arglist} is allowed to be a full Common Lisp argument
292 list. Also, the function body is enclosed in an implicit block
293 called @var{name}; @pxref{Blocks and Exits}.
296 @defmac cl-defsubst name arglist body@dots{}
297 This is just like @code{cl-defun}, except that the function that
298 is defined is automatically proclaimed @code{inline}, i.e.,
299 calls to it may be expanded into in-line code by the byte compiler.
300 This is analogous to the @code{defsubst} form;
301 @code{cl-defsubst} uses a different method (compiler macros) which
302 works in all versions of Emacs, and also generates somewhat more
304 efficient inline expansions. In particular, @code{cl-defsubst}
305 arranges for the processing of keyword arguments, default values,
306 etc., to be done at compile-time whenever possible.
309 @defmac cl-defmacro name arglist body@dots{}
310 This is identical to the regular @code{defmacro} form,
311 except that @var{arglist} is allowed to be a full Common Lisp
312 argument list. The @code{&environment} keyword is supported as
313 described in Steele's book @cite{Common Lisp, the Language}.
314 The @code{&whole} keyword is supported only
315 within destructured lists (see below); top-level @code{&whole}
316 cannot be implemented with the current Emacs Lisp interpreter.
317 The macro expander body is enclosed in an implicit block called
321 @defmac cl-function symbol-or-lambda
322 This is identical to the regular @code{function} form,
323 except that if the argument is a @code{lambda} form then that
324 form may use a full Common Lisp argument list.
327 Also, all forms (such as @code{cl-flet} and @code{cl-labels}) defined
328 in this package that include @var{arglist}s in their syntax allow
329 full Common Lisp argument lists.
331 Note that it is @emph{not} necessary to use @code{cl-defun} in
332 order to have access to most CL features in your function.
333 These features are always present; @code{cl-defun}'s only
334 difference from @code{defun} is its more flexible argument
335 lists and its implicit block.
337 The full form of a Common Lisp argument list is
341 &optional (@var{var} @var{initform} @var{svar})@dots{}
343 &key ((@var{keyword} @var{var}) @var{initform} @var{svar})@dots{}
344 &aux (@var{var} @var{initform})@dots{})
347 Each of the five argument list sections is optional. The @var{svar},
348 @var{initform}, and @var{keyword} parts are optional; if they are
349 omitted, then @samp{(@var{var})} may be written simply @samp{@var{var}}.
351 The first section consists of zero or more @dfn{required} arguments.
352 These arguments must always be specified in a call to the function;
353 there is no difference between Emacs Lisp and Common Lisp as far as
354 required arguments are concerned.
356 The second section consists of @dfn{optional} arguments. These
357 arguments may be specified in the function call; if they are not,
358 @var{initform} specifies the default value used for the argument.
359 (No @var{initform} means to use @code{nil} as the default.) The
360 @var{initform} is evaluated with the bindings for the preceding
361 arguments already established; @code{(a &optional (b (1+ a)))}
362 matches one or two arguments, with the second argument defaulting
363 to one plus the first argument. If the @var{svar} is specified,
364 it is an auxiliary variable which is bound to @code{t} if the optional
365 argument was specified, or to @code{nil} if the argument was omitted.
366 If you don't use an @var{svar}, then there will be no way for your
367 function to tell whether it was called with no argument, or with
368 the default value passed explicitly as an argument.
370 The third section consists of a single @dfn{rest} argument. If
371 more arguments were passed to the function than are accounted for
372 by the required and optional arguments, those extra arguments are
373 collected into a list and bound to the ``rest'' argument variable.
374 Common Lisp's @code{&rest} is equivalent to that of Emacs Lisp.
375 Common Lisp accepts @code{&body} as a synonym for @code{&rest} in
376 macro contexts; this package accepts it all the time.
378 The fourth section consists of @dfn{keyword} arguments. These
379 are optional arguments which are specified by name rather than
380 positionally in the argument list. For example,
383 (cl-defun foo (a &optional b &key c d (e 17)))
387 defines a function which may be called with one, two, or more
388 arguments. The first two arguments are bound to @code{a} and
389 @code{b} in the usual way. The remaining arguments must be
390 pairs of the form @code{:c}, @code{:d}, or @code{:e} followed
391 by the value to be bound to the corresponding argument variable.
392 (Symbols whose names begin with a colon are called @dfn{keywords},
393 and they are self-quoting in the same way as @code{nil} and
396 For example, the call @code{(foo 1 2 :d 3 :c 4)} sets the five
397 arguments to 1, 2, 4, 3, and 17, respectively. If the same keyword
398 appears more than once in the function call, the first occurrence
399 takes precedence over the later ones. Note that it is not possible
400 to specify keyword arguments without specifying the optional
401 argument @code{b} as well, since @code{(foo 1 :c 2)} would bind
402 @code{b} to the keyword @code{:c}, then signal an error because
403 @code{2} is not a valid keyword.
405 You can also explicitly specify the keyword argument; it need not be
406 simply the variable name prefixed with a colon. For example,
409 (cl-defun bar (&key (a 1) ((baz b) 4)))
414 specifies a keyword @code{:a} that sets the variable @code{a} with
415 default value 1, as well as a keyword @code{baz} that sets the
416 variable @code{b} with default value 4. In this case, because
417 @code{baz} is not self-quoting, you must quote it explicitly in the
418 function call, like this:
424 Ordinarily, it is an error to pass an unrecognized keyword to
425 a function, e.g., @code{(foo 1 2 :c 3 :goober 4)}. You can ask
426 Lisp to ignore unrecognized keywords, either by adding the
427 marker @code{&allow-other-keys} after the keyword section
428 of the argument list, or by specifying an @code{:allow-other-keys}
429 argument in the call whose value is non-@code{nil}. If the
430 function uses both @code{&rest} and @code{&key} at the same time,
431 the ``rest'' argument is bound to the keyword list as it appears
432 in the call. For example:
435 (cl-defun find-thing (thing &rest rest &key need &allow-other-keys)
436 (or (apply 'cl-member thing thing-list :allow-other-keys t rest)
437 (if need (error "Thing not found"))))
441 This function takes a @code{:need} keyword argument, but also
442 accepts other keyword arguments which are passed on to the
443 @code{cl-member} function. @code{allow-other-keys} is used to
444 keep both @code{find-thing} and @code{cl-member} from complaining
445 about each others' keywords in the arguments.
447 The fifth section of the argument list consists of @dfn{auxiliary
448 variables}. These are not really arguments at all, but simply
449 variables which are bound to @code{nil} or to the specified
450 @var{initforms} during execution of the function. There is no
451 difference between the following two functions, except for a
452 matter of stylistic taste:
455 (cl-defun foo (a b &aux (c (+ a b)) d)
463 Argument lists support @dfn{destructuring}. In Common Lisp,
464 destructuring is only allowed with @code{defmacro}; this package
465 allows it with @code{cl-defun} and other argument lists as well.
466 In destructuring, any argument variable (@var{var} in the above
467 example) can be replaced by a list of variables, or more generally,
468 a recursive argument list. The corresponding argument value must
469 be a list whose elements match this recursive argument list.
473 (cl-defmacro dolist ((var listform &optional resultform)
478 This says that the first argument of @code{dolist} must be a list
479 of two or three items; if there are other arguments as well as this
480 list, they are stored in @code{body}. All features allowed in
481 regular argument lists are allowed in these recursive argument lists.
482 In addition, the clause @samp{&whole @var{var}} is allowed at the
483 front of a recursive argument list. It binds @var{var} to the
484 whole list being matched; thus @code{(&whole all a b)} matches
485 a list of two things, with @code{a} bound to the first thing,
486 @code{b} bound to the second thing, and @code{all} bound to the
487 list itself. (Common Lisp allows @code{&whole} in top-level
488 @code{defmacro} argument lists as well, but Emacs Lisp does not
491 One last feature of destructuring is that the argument list may be
492 dotted, so that the argument list @code{(a b . c)} is functionally
493 equivalent to @code{(a b &rest c)}.
495 If the optimization quality @code{safety} is set to 0
496 (@pxref{Declarations}), error checking for wrong number of
497 arguments and invalid keyword arguments is disabled. By default,
498 argument lists are rigorously checked.
500 @node Time of Evaluation
501 @section Time of Evaluation
504 Normally, the byte-compiler does not actually execute the forms in
505 a file it compiles. For example, if a file contains @code{(setq foo t)},
506 the act of compiling it will not actually set @code{foo} to @code{t}.
507 This is true even if the @code{setq} was a top-level form (i.e., not
508 enclosed in a @code{defun} or other form). Sometimes, though, you
509 would like to have certain top-level forms evaluated at compile-time.
510 For example, the compiler effectively evaluates @code{defmacro} forms
511 at compile-time so that later parts of the file can refer to the
512 macros that are defined.
514 @defmac cl-eval-when (situations@dots{}) forms@dots{}
515 This form controls when the body @var{forms} are evaluated.
516 The @var{situations} list may contain any set of the symbols
517 @code{compile}, @code{load}, and @code{eval} (or their long-winded
518 ANSI equivalents, @code{:compile-toplevel}, @code{:load-toplevel},
519 and @code{:execute}).
521 The @code{cl-eval-when} form is handled differently depending on
522 whether or not it is being compiled as a top-level form.
523 Specifically, it gets special treatment if it is being compiled
524 by a command such as @code{byte-compile-file} which compiles files
525 or buffers of code, and it appears either literally at the
526 top level of the file or inside a top-level @code{progn}.
528 For compiled top-level @code{cl-eval-when}s, the body @var{forms} are
529 executed at compile-time if @code{compile} is in the @var{situations}
530 list, and the @var{forms} are written out to the file (to be executed
531 at load-time) if @code{load} is in the @var{situations} list.
533 For non-compiled-top-level forms, only the @code{eval} situation is
534 relevant. (This includes forms executed by the interpreter, forms
535 compiled with @code{byte-compile} rather than @code{byte-compile-file},
536 and non-top-level forms.) The @code{cl-eval-when} acts like a
537 @code{progn} if @code{eval} is specified, and like @code{nil}
538 (ignoring the body @var{forms}) if not.
540 The rules become more subtle when @code{cl-eval-when}s are nested;
541 consult Steele (second edition) for the gruesome details (and
542 some gruesome examples).
544 Some simple examples:
547 ;; Top-level forms in foo.el:
548 (cl-eval-when (compile) (setq foo1 'bar))
549 (cl-eval-when (load) (setq foo2 'bar))
550 (cl-eval-when (compile load) (setq foo3 'bar))
551 (cl-eval-when (eval) (setq foo4 'bar))
552 (cl-eval-when (eval compile) (setq foo5 'bar))
553 (cl-eval-when (eval load) (setq foo6 'bar))
554 (cl-eval-when (eval compile load) (setq foo7 'bar))
557 When @file{foo.el} is compiled, these variables will be set during
558 the compilation itself:
561 foo1 foo3 foo5 foo7 ; `compile'
564 When @file{foo.elc} is loaded, these variables will be set:
567 foo2 foo3 foo6 foo7 ; `load'
570 And if @file{foo.el} is loaded uncompiled, these variables will
574 foo4 foo5 foo6 foo7 ; `eval'
577 If these seven @code{cl-eval-when}s had been, say, inside a @code{defun},
578 then the first three would have been equivalent to @code{nil} and the
579 last four would have been equivalent to the corresponding @code{setq}s.
581 Note that @code{(cl-eval-when (load eval) @dots{})} is equivalent
582 to @code{(progn @dots{})} in all contexts. The compiler treats
583 certain top-level forms, like @code{defmacro} (sort-of) and
584 @code{require}, as if they were wrapped in @code{(cl-eval-when
585 (compile load eval) @dots{})}.
588 Emacs includes two special forms related to @code{cl-eval-when}.
589 @xref{Eval During Compile,,,elisp,GNU Emacs Lisp Reference Manual}.
590 One of these, @code{eval-when-compile}, is not quite equivalent to
591 any @code{cl-eval-when} construct and is described below.
593 The other form, @code{(eval-and-compile @dots{})}, is exactly
594 equivalent to @samp{(cl-eval-when (compile load eval) @dots{})}.
596 @defmac eval-when-compile forms@dots{}
597 The @var{forms} are evaluated at compile-time; at execution time,
598 this form acts like a quoted constant of the resulting value. Used
599 at top-level, @code{eval-when-compile} is just like @samp{eval-when
600 (compile eval)}. In other contexts, @code{eval-when-compile}
601 allows code to be evaluated once at compile-time for efficiency
604 This form is similar to the @samp{#.} syntax of true Common Lisp.
607 @defmac cl-load-time-value form
608 The @var{form} is evaluated at load-time; at execution time,
609 this form acts like a quoted constant of the resulting value.
611 Early Common Lisp had a @samp{#,} syntax that was similar to
612 this, but ANSI Common Lisp replaced it with @code{load-time-value}
613 and gave it more well-defined semantics.
615 In a compiled file, @code{cl-load-time-value} arranges for @var{form}
616 to be evaluated when the @file{.elc} file is loaded and then used
617 as if it were a quoted constant. In code compiled by
618 @code{byte-compile} rather than @code{byte-compile-file}, the
619 effect is identical to @code{eval-when-compile}. In uncompiled
620 code, both @code{eval-when-compile} and @code{cl-load-time-value}
621 act exactly like @code{progn}.
625 (insert "This function was executed on: "
626 (current-time-string)
628 (eval-when-compile (current-time-string))
629 ;; or '#.(current-time-string) in real Common Lisp
631 (cl-load-time-value (current-time-string))))
635 Byte-compiled, the above defun will result in the following code
636 (or its compiled equivalent, of course) in the @file{.elc} file:
639 (setq --temp-- (current-time-string))
641 (insert "This function was executed on: "
642 (current-time-string)
644 '"Wed Oct 31 16:32:28 2012"
654 This section describes functions for testing whether various
655 facts are true or false.
658 * Type Predicates:: @code{cl-typep}, @code{cl-deftype}, and @code{cl-coerce}.
659 * Equality Predicates:: @code{cl-equalp}.
662 @node Type Predicates
663 @section Type Predicates
665 @defun cl-typep object type
666 Check if @var{object} is of type @var{type}, where @var{type} is a
667 (quoted) type name of the sort used by Common Lisp. For example,
668 @code{(cl-typep foo 'integer)} is equivalent to @code{(integerp foo)}.
671 The @var{type} argument to the above function is either a symbol
672 or a list beginning with a symbol.
676 If the type name is a symbol, Emacs appends @samp{-p} to the
677 symbol name to form the name of a predicate function for testing
678 the type. (Built-in predicates whose names end in @samp{p} rather
679 than @samp{-p} are used when appropriate.)
682 The type symbol @code{t} stands for the union of all types.
683 @code{(cl-typep @var{object} t)} is always true. Likewise, the
684 type symbol @code{nil} stands for nothing at all, and
685 @code{(cl-typep @var{object} nil)} is always false.
688 The type symbol @code{null} represents the symbol @code{nil}.
689 Thus @code{(cl-typep @var{object} 'null)} is equivalent to
690 @code{(null @var{object})}.
693 The type symbol @code{atom} represents all objects that are not cons
694 cells. Thus @code{(cl-typep @var{object} 'atom)} is equivalent to
695 @code{(atom @var{object})}.
698 The type symbol @code{real} is a synonym for @code{number}, and
699 @code{fixnum} is a synonym for @code{integer}.
702 The type symbols @code{character} and @code{string-char} match
703 integers in the range from 0 to 255.
706 The type symbol @code{float} uses the @code{cl-floatp-safe} predicate
707 defined by this package rather than @code{floatp}, so it will work
708 @c FIXME are any such platforms still relevant?
709 correctly even in Emacs versions without floating-point support.
712 The type list @code{(integer @var{low} @var{high})} represents all
713 integers between @var{low} and @var{high}, inclusive. Either bound
714 may be a list of a single integer to specify an exclusive limit,
715 or a @code{*} to specify no limit. The type @code{(integer * *)}
716 is thus equivalent to @code{integer}.
719 Likewise, lists beginning with @code{float}, @code{real}, or
720 @code{number} represent numbers of that type falling in a particular
724 Lists beginning with @code{and}, @code{or}, and @code{not} form
725 combinations of types. For example, @code{(or integer (float 0 *))}
726 represents all objects that are integers or non-negative floats.
729 Lists beginning with @code{member} or @code{cl-member} represent
730 objects @code{eql} to any of the following values. For example,
731 @code{(member 1 2 3 4)} is equivalent to @code{(integer 1 4)},
732 and @code{(member nil)} is equivalent to @code{null}.
735 Lists of the form @code{(satisfies @var{predicate})} represent
736 all objects for which @var{predicate} returns true when called
737 with that object as an argument.
740 The following function and macro (not technically predicates) are
741 related to @code{cl-typep}.
743 @defun cl-coerce object type
744 This function attempts to convert @var{object} to the specified
745 @var{type}. If @var{object} is already of that type as determined by
746 @code{cl-typep}, it is simply returned. Otherwise, certain types of
747 conversions will be made: If @var{type} is any sequence type
748 (@code{string}, @code{list}, etc.) then @var{object} will be
749 converted to that type if possible. If @var{type} is
750 @code{character}, then strings of length one and symbols with
751 one-character names can be coerced. If @var{type} is @code{float},
752 then integers can be coerced in versions of Emacs that support
753 floats. In all other circumstances, @code{cl-coerce} signals an
757 @defmac cl-deftype name arglist forms@dots{}
758 This macro defines a new type called @var{name}. It is similar
759 to @code{defmacro} in many ways; when @var{name} is encountered
760 as a type name, the body @var{forms} are evaluated and should
761 return a type specifier that is equivalent to the type. The
762 @var{arglist} is a Common Lisp argument list of the sort accepted
763 by @code{cl-defmacro}. The type specifier @samp{(@var{name} @var{args}@dots{})}
764 is expanded by calling the expander with those arguments; the type
765 symbol @samp{@var{name}} is expanded by calling the expander with
766 no arguments. The @var{arglist} is processed the same as for
767 @code{cl-defmacro} except that optional arguments without explicit
768 defaults use @code{*} instead of @code{nil} as the ``default''
769 default. Some examples:
772 (cl-deftype null () '(satisfies null)) ; predefined
773 (cl-deftype list () '(or null cons)) ; predefined
774 (cl-deftype unsigned-byte (&optional bits)
775 (list 'integer 0 (if (eq bits '*) bits (1- (lsh 1 bits)))))
776 (unsigned-byte 8) @equiv{} (integer 0 255)
777 (unsigned-byte) @equiv{} (integer 0 *)
778 unsigned-byte @equiv{} (integer 0 *)
782 The last example shows how the Common Lisp @code{unsigned-byte}
783 type specifier could be implemented if desired; this package does
784 not implement @code{unsigned-byte} by default.
787 The @code{cl-typecase} (@pxref{Conditionals}) and @code{cl-check-type}
788 (@pxref{Assertions}) macros also use type names. The @code{cl-map},
789 @code{cl-concatenate}, and @code{cl-merge} functions take type-name
790 arguments to specify the type of sequence to return. @xref{Sequences}.
792 @node Equality Predicates
793 @section Equality Predicates
796 This package defines the Common Lisp predicate @code{cl-equalp}.
799 This function is a more flexible version of @code{equal}. In
800 particular, it compares strings case-insensitively, and it compares
801 numbers without regard to type (so that @code{(cl-equalp 3 3.0)} is
802 true). Vectors and conses are compared recursively. All other
803 objects are compared as if by @code{equal}.
805 This function differs from Common Lisp @code{equalp} in several
806 respects. First, Common Lisp's @code{equalp} also compares
807 @emph{characters} case-insensitively, which would be impractical
808 in this package since Emacs does not distinguish between integers
809 and characters. In keeping with the idea that strings are less
810 vector-like in Emacs Lisp, this package's @code{cl-equalp} also will
811 not compare strings against vectors of integers.
814 Also note that the Common Lisp functions @code{member} and @code{assoc}
815 use @code{eql} to compare elements, whereas Emacs Lisp follows the
816 MacLisp tradition and uses @code{equal} for these two functions.
817 In Emacs, use @code{memq} (or @code{cl-member}) and @code{assq} (or
818 @code{cl-assoc}) to get functions which use @code{eql} for comparisons.
820 @node Control Structure
821 @chapter Control Structure
824 The features described in the following sections implement
825 various advanced control structures, including extensions to the
826 standard @code{setf} facility, and a number of looping and conditional
830 * Assignment:: The @code{cl-psetq} form.
831 * Generalized Variables:: Extensions to generalized variables.
832 * Variable Bindings:: @code{cl-progv}, @code{cl-flet}, @code{cl-macrolet}.
833 * Conditionals:: @code{cl-case}, @code{cl-typecase}.
834 * Blocks and Exits:: @code{cl-block}, @code{cl-return}, @code{cl-return-from}.
835 * Iteration:: @code{cl-do}, @code{cl-dotimes}, @code{cl-dolist}, @code{cl-do-symbols}.
836 * Loop Facility:: The Common Lisp @code{cl-loop} macro.
837 * Multiple Values:: @code{cl-values}, @code{cl-multiple-value-bind}, etc.
844 The @code{cl-psetq} form is just like @code{setq}, except that multiple
845 assignments are done in parallel rather than sequentially.
847 @defmac cl-psetq [symbol form]@dots{}
848 This special form (actually a macro) is used to assign to several
849 variables simultaneously. Given only one @var{symbol} and @var{form},
850 it has the same effect as @code{setq}. Given several @var{symbol}
851 and @var{form} pairs, it evaluates all the @var{form}s in advance
852 and then stores the corresponding variables afterwards.
856 (setq x (+ x y) y (* x y))
859 y ; @r{@code{y} was computed after @code{x} was set.}
862 (cl-psetq x (+ x y) y (* x y))
865 y ; @r{@code{y} was computed before @code{x} was set.}
869 The simplest use of @code{cl-psetq} is @code{(cl-psetq x y y x)}, which
870 exchanges the values of two variables. (The @code{cl-rotatef} form
871 provides an even more convenient way to swap two variables;
872 @pxref{Modify Macros}.)
874 @code{cl-psetq} always returns @code{nil}.
877 @node Generalized Variables
878 @section Generalized Variables
880 A @dfn{generalized variable} or @dfn{place form} is one of the many
881 places in Lisp memory where values can be stored. The simplest place
882 form is a regular Lisp variable. But the @sc{car}s and @sc{cdr}s of lists,
883 elements of arrays, properties of symbols, and many other locations
884 are also places where Lisp values are stored. For basic information,
885 @pxref{Generalized Variables,,,elisp,GNU Emacs Lisp Reference Manual}.
886 This package provides several additional features related to
887 generalized variables.
890 * Setf Extensions:: Additional @code{setf} places.
891 * Modify Macros:: @code{cl-incf}, @code{cl-rotatef}, @code{cl-letf}, @code{cl-callf}, etc.
894 @node Setf Extensions
895 @subsection Setf Extensions
897 Several standard (e.g.@: @code{car}) and Emacs-specific
898 (e.g.@: @code{window-point}) Lisp functions are @code{setf}-able by default.
899 This package defines @code{setf} handlers for several additional functions:
903 Functions from this package:
905 cl-rest cl-subseq cl-get cl-getf
906 cl-caaar@dots{}cl-cddddr cl-first@dots{}cl-tenth
910 Note that for @code{cl-getf} (as for @code{nthcdr}), the list argument
911 of the function must itself be a valid @var{place} form.
914 General Emacs Lisp functions:
916 buffer-file-name getenv
917 buffer-modified-p global-key-binding
918 buffer-name local-key-binding
920 buffer-substring mark-marker
921 current-buffer marker-position
922 current-case-table mouse-position
924 current-global-map point-marker
925 current-input-mode point-max
926 current-local-map point-min
927 current-window-configuration read-mouse-position
928 default-file-modes screen-height
929 documentation-property screen-width
930 face-background selected-window
931 face-background-pixmap selected-screen
932 face-font selected-frame
933 face-foreground standard-case-table
934 face-underline-p syntax-table
935 file-modes visited-file-modtime
936 frame-height window-height
937 frame-parameters window-width
938 frame-visible-p x-get-secondary-selection
939 frame-width x-get-selection
943 Most of these have directly corresponding ``set'' functions, like
944 @code{use-local-map} for @code{current-local-map}, or @code{goto-char}
945 for @code{point}. A few, like @code{point-min}, expand to longer
946 sequences of code when they are used with @code{setf}
947 (@code{(narrow-to-region x (point-max))} in this case).
950 A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])},
951 where @var{subplace} is itself a valid generalized variable whose
952 current value is a string, and where the value stored is also a
953 string. The new string is spliced into the specified part of the
954 destination string. For example:
957 (setq a (list "hello" "world"))
958 @result{} ("hello" "world")
961 (substring (cadr a) 2 4)
963 (setf (substring (cadr a) 2 4) "o")
968 @result{} ("hello" "wood")
971 The generalized variable @code{buffer-substring}, listed above,
972 also works in this way by replacing a portion of the current buffer.
974 @c FIXME? Also `eq'? (see cl-lib.el)
976 @c Currently commented out in cl.el.
979 A call of the form @code{(apply '@var{func} @dots{})} or
980 @code{(apply (function @var{func}) @dots{})}, where @var{func}
981 is a @code{setf}-able function whose store function is ``suitable''
982 in the sense described in Steele's book; since none of the standard
983 Emacs place functions are suitable in this sense, this feature is
984 only interesting when used with places you define yourself with
985 @code{define-setf-method} or the long form of @code{defsetf}.
986 @xref{Obsolete Setf Customization}.
990 A macro call, in which case the macro is expanded and @code{setf}
991 is applied to the resulting form.
994 Any form for which a @code{defsetf} or @code{define-setf-method}
995 has been made. @xref{Obsolete Setf Customization}.
998 @c FIXME should this be in lispref? It seems self-evident.
999 @c Contrast with the cl-incf example later on.
1000 @c Here it really only serves as a contrast to wrong-order.
1001 The @code{setf} macro takes care to evaluate all subforms in
1002 the proper left-to-right order; for example,
1005 (setf (aref vec (cl-incf i)) i)
1009 looks like it will evaluate @code{(cl-incf i)} exactly once, before the
1010 following access to @code{i}; the @code{setf} expander will insert
1011 temporary variables as necessary to ensure that it does in fact work
1012 this way no matter what setf-method is defined for @code{aref}.
1013 (In this case, @code{aset} would be used and no such steps would
1014 be necessary since @code{aset} takes its arguments in a convenient
1017 However, if the @var{place} form is a macro which explicitly
1018 evaluates its arguments in an unusual order, this unusual order
1019 will be preserved. Adapting an example from Steele, given
1022 (defmacro wrong-order (x y) (list 'aref y x))
1026 the form @code{(setf (wrong-order @var{a} @var{b}) 17)} will
1027 evaluate @var{b} first, then @var{a}, just as in an actual call
1028 to @code{wrong-order}.
1031 @subsection Modify Macros
1034 This package defines a number of macros that operate on generalized
1035 variables. Many are interesting and useful even when the @var{place}
1036 is just a variable name.
1038 @defmac cl-psetf [place form]@dots{}
1039 This macro is to @code{setf} what @code{cl-psetq} is to @code{setq}:
1040 When several @var{place}s and @var{form}s are involved, the
1041 assignments take place in parallel rather than sequentially.
1042 Specifically, all subforms are evaluated from left to right, then
1043 all the assignments are done (in an undefined order).
1046 @defmac cl-incf place &optional x
1047 This macro increments the number stored in @var{place} by one, or
1048 by @var{x} if specified. The incremented value is returned. For
1049 example, @code{(cl-incf i)} is equivalent to @code{(setq i (1+ i))}, and
1050 @code{(cl-incf (car x) 2)} is equivalent to @code{(setcar x (+ (car x) 2))}.
1052 As with @code{setf}, care is taken to preserve the ``apparent'' order
1053 of evaluation. For example,
1056 (cl-incf (aref vec (cl-incf i)))
1060 appears to increment @code{i} once, then increment the element of
1061 @code{vec} addressed by @code{i}; this is indeed exactly what it
1062 does, which means the above form is @emph{not} equivalent to the
1063 ``obvious'' expansion,
1066 (setf (aref vec (cl-incf i))
1067 (1+ (aref vec (cl-incf i)))) ; wrong!
1071 but rather to something more like
1074 (let ((temp (cl-incf i)))
1075 (setf (aref vec temp) (1+ (aref vec temp))))
1079 Again, all of this is taken care of automatically by @code{cl-incf} and
1080 the other generalized-variable macros.
1082 As a more Emacs-specific example of @code{cl-incf}, the expression
1083 @code{(cl-incf (point) @var{n})} is essentially equivalent to
1084 @code{(forward-char @var{n})}.
1087 @defmac cl-decf place &optional x
1088 This macro decrements the number stored in @var{place} by one, or
1089 by @var{x} if specified.
1092 @defmac cl-pushnew x place @t{&key :test :test-not :key}
1093 This macro inserts @var{x} at the front of the list stored in
1094 @var{place}, but only if @var{x} was not @code{eql} to any
1095 existing element of the list. The optional keyword arguments
1096 are interpreted in the same way as for @code{cl-adjoin}.
1097 @xref{Lists as Sets}.
1100 @defmac cl-shiftf place@dots{} newvalue
1101 This macro shifts the @var{place}s left by one, shifting in the
1102 value of @var{newvalue} (which may be any Lisp expression, not just
1103 a generalized variable), and returning the value shifted out of
1104 the first @var{place}. Thus, @code{(cl-shiftf @var{a} @var{b} @var{c}
1105 @var{d})} is equivalent to
1110 (cl-psetf @var{a} @var{b}
1116 except that the subforms of @var{a}, @var{b}, and @var{c} are actually
1117 evaluated only once each and in the apparent order.
1120 @defmac cl-rotatef place@dots{}
1121 This macro rotates the @var{place}s left by one in circular fashion.
1122 Thus, @code{(cl-rotatef @var{a} @var{b} @var{c} @var{d})} is equivalent to
1125 (cl-psetf @var{a} @var{b}
1132 except for the evaluation of subforms. @code{cl-rotatef} always
1133 returns @code{nil}. Note that @code{(cl-rotatef @var{a} @var{b})}
1134 conveniently exchanges @var{a} and @var{b}.
1137 The following macros were invented for this package; they have no
1138 analogues in Common Lisp.
1140 @defmac cl-letf (bindings@dots{}) forms@dots{}
1141 This macro is analogous to @code{let}, but for generalized variables
1142 rather than just symbols. Each @var{binding} should be of the form
1143 @code{(@var{place} @var{value})}; the original contents of the
1144 @var{place}s are saved, the @var{value}s are stored in them, and
1145 then the body @var{form}s are executed. Afterwards, the @var{places}
1146 are set back to their original saved contents. This cleanup happens
1147 even if the @var{form}s exit irregularly due to a @code{throw} or an
1153 (cl-letf (((point) (point-min))
1159 moves point in the current buffer to the beginning of the buffer,
1160 and also binds @code{a} to 17 (as if by a normal @code{let}, since
1161 @code{a} is just a regular variable). After the body exits, @code{a}
1162 is set back to its original value and point is moved back to its
1165 Note that @code{cl-letf} on @code{(point)} is not quite like a
1166 @code{save-excursion}, as the latter effectively saves a marker
1167 which tracks insertions and deletions in the buffer. Actually,
1168 a @code{cl-letf} of @code{(point-marker)} is much closer to this
1169 behavior. (@code{point} and @code{point-marker} are equivalent
1170 as @code{setf} places; each will accept either an integer or a
1171 marker as the stored value.)
1173 Since generalized variables look like lists, @code{let}'s shorthand
1174 of using @samp{foo} for @samp{(foo nil)} as a @var{binding} would
1175 be ambiguous in @code{cl-letf} and is not allowed.
1177 However, a @var{binding} specifier may be a one-element list
1178 @samp{(@var{place})}, which is similar to @samp{(@var{place}
1179 @var{place})}. In other words, the @var{place} is not disturbed
1180 on entry to the body, and the only effect of the @code{cl-letf} is
1181 to restore the original value of @var{place} afterwards.
1182 @c I suspect this may no longer be true; either way it's
1183 @c implementation detail and so not essential to document.
1185 (The redundant access-and-store suggested by the @code{(@var{place}
1186 @var{place})} example does not actually occur.)
1189 Note that in this case, and in fact almost every case, @var{place}
1190 must have a well-defined value outside the @code{cl-letf} body.
1191 There is essentially only one exception to this, which is @var{place}
1192 a plain variable with a specified @var{value} (such as @code{(a 17)}
1193 in the above example).
1194 @c See http://debbugs.gnu.org/12758
1195 @c Some or all of this was true for cl.el, but not for cl-lib.el.
1197 The only exceptions are plain variables and calls to
1198 @code{symbol-value} and @code{symbol-function}. If the symbol is not
1199 bound on entry, it is simply made unbound by @code{makunbound} or
1200 @code{fmakunbound} on exit.
1203 Note that the @file{cl.el} version of this macro behaves slightly
1204 differently. @xref{Obsolete Macros}.
1207 @defmac cl-letf* (bindings@dots{}) forms@dots{}
1208 This macro is to @code{cl-letf} what @code{let*} is to @code{let}:
1209 It does the bindings in sequential rather than parallel order.
1212 @defmac cl-callf @var{function} @var{place} @var{args}@dots{}
1213 This is the ``generic'' modify macro. It calls @var{function},
1214 which should be an unquoted function name, macro name, or lambda.
1215 It passes @var{place} and @var{args} as arguments, and assigns the
1216 result back to @var{place}. For example, @code{(cl-incf @var{place}
1217 @var{n})} is the same as @code{(cl-callf + @var{place} @var{n})}.
1221 (cl-callf abs my-number)
1222 (cl-callf concat (buffer-name) "<" (number-to-string n) ">")
1223 (cl-callf cl-union happy-people (list joe bob) :test 'same-person)
1226 Note again that @code{cl-callf} is an extension to standard Common Lisp.
1229 @defmac cl-callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{}
1230 This macro is like @code{cl-callf}, except that @var{place} is
1231 the @emph{second} argument of @var{function} rather than the
1232 first. For example, @code{(push @var{x} @var{place})} is
1233 equivalent to @code{(cl-callf2 cons @var{x} @var{place})}.
1236 The @code{cl-callf} and @code{cl-callf2} macros serve as building
1237 blocks for other macros like @code{cl-incf}, and @code{cl-pushnew}.
1238 The @code{cl-letf} and @code{cl-letf*} macros are used in the processing
1239 of symbol macros; @pxref{Macro Bindings}.
1242 @node Variable Bindings
1243 @section Variable Bindings
1246 These Lisp forms make bindings to variables and function names,
1247 analogous to Lisp's built-in @code{let} form.
1249 @xref{Modify Macros}, for the @code{cl-letf} and @code{cl-letf*} forms which
1250 are also related to variable bindings.
1253 * Dynamic Bindings:: The @code{cl-progv} form.
1254 * Function Bindings:: @code{cl-flet} and @code{cl-labels}.
1255 * Macro Bindings:: @code{cl-macrolet} and @code{cl-symbol-macrolet}.
1258 @node Dynamic Bindings
1259 @subsection Dynamic Bindings
1262 The standard @code{let} form binds variables whose names are known
1263 at compile-time. The @code{cl-progv} form provides an easy way to
1264 bind variables whose names are computed at run-time.
1266 @defmac cl-progv symbols values forms@dots{}
1267 This form establishes @code{let}-style variable bindings on a
1268 set of variables computed at run-time. The expressions
1269 @var{symbols} and @var{values} are evaluated, and must return lists
1270 of symbols and values, respectively. The symbols are bound to the
1271 corresponding values for the duration of the body @var{form}s.
1272 If @var{values} is shorter than @var{symbols}, the last few symbols
1273 are bound to @code{nil}.
1274 If @var{symbols} is shorter than @var{values}, the excess values
1278 @node Function Bindings
1279 @subsection Function Bindings
1282 These forms make @code{let}-like bindings to functions instead
1285 @defmac cl-flet (bindings@dots{}) forms@dots{}
1286 This form establishes @code{let}-style bindings on the function
1287 cells of symbols rather than on the value cells. Each @var{binding}
1288 must be a list of the form @samp{(@var{name} @var{arglist}
1289 @var{forms}@dots{})}, which defines a function exactly as if
1290 it were a @code{cl-defun} form. The function @var{name} is defined
1291 accordingly for the duration of the body of the @code{cl-flet}; then
1292 the old function definition, or lack thereof, is restored.
1294 You can use @code{cl-flet} to disable or modify the behavior of a
1295 function in a temporary fashion. (Compare this with the idea
1296 of advising functions.
1297 @xref{Advising Functions,,,elisp,GNU Emacs Lisp Reference Manual}.)
1298 This will even work on Emacs primitives, although note that some calls
1299 to primitive functions internal to Emacs are made without going
1300 through the symbol's function cell, and so will not be affected by
1301 @code{cl-flet}. For example,
1304 (cl-flet ((message (&rest args) (push args saved-msgs)))
1308 This code attempts to replace the built-in function @code{message}
1309 with a function that simply saves the messages in a list rather
1310 than displaying them. The original definition of @code{message}
1311 will be restored after @code{do-something} exits. This code will
1312 work fine on messages generated by other Lisp code, but messages
1313 generated directly inside Emacs will not be caught since they make
1314 direct C-language calls to the message routines rather than going
1315 through the Lisp @code{message} function.
1317 Functions defined by @code{cl-flet} may use the full Common Lisp
1318 argument notation supported by @code{cl-defun}; also, the function
1319 body is enclosed in an implicit block as if by @code{cl-defun}.
1320 @xref{Program Structure}.
1322 Note that the @file{cl.el} version of this macro behaves slightly
1323 differently. @xref{Obsolete Macros}.
1326 @defmac cl-labels (bindings@dots{}) forms@dots{}
1327 The @code{cl-labels} form is like @code{cl-flet}, except that
1328 the function bindings can be recursive. The scoping is lexical,
1329 but you can only capture functions in closures if
1330 @code{lexical-binding} is @code{t}.
1331 @xref{Closures,,,elisp,GNU Emacs Lisp Reference Manual}, and
1332 @ref{Using Lexical Binding,,,elisp,GNU Emacs Lisp Reference Manual}.
1334 Lexical scoping means that all references to the named
1335 functions must appear physically within the body of the
1336 @code{cl-labels} form. References may appear both in the body
1337 @var{forms} of @code{cl-labels} itself, and in the bodies of
1338 the functions themselves. Thus, @code{cl-labels} can define
1339 local recursive functions, or mutually-recursive sets of functions.
1341 A ``reference'' to a function name is either a call to that
1342 function, or a use of its name quoted by @code{quote} or
1343 @code{function} to be passed on to, say, @code{mapcar}.
1345 Note that the @file{cl.el} version of this macro behaves slightly
1346 differently. @xref{Obsolete Macros}.
1349 @node Macro Bindings
1350 @subsection Macro Bindings
1353 These forms create local macros and ``symbol macros''.
1355 @defmac cl-macrolet (bindings@dots{}) forms@dots{}
1356 This form is analogous to @code{cl-flet}, but for macros instead of
1357 functions. Each @var{binding} is a list of the same form as the
1358 arguments to @code{cl-defmacro} (i.e., a macro name, argument list,
1359 and macro-expander forms). The macro is defined accordingly for
1360 use within the body of the @code{cl-macrolet}.
1362 Because of the nature of macros, @code{cl-macrolet} is always lexically
1363 scoped. The @code{cl-macrolet} binding will
1364 affect only calls that appear physically within the body
1365 @var{forms}, possibly after expansion of other macros in the
1369 @defmac cl-symbol-macrolet (bindings@dots{}) forms@dots{}
1370 This form creates @dfn{symbol macros}, which are macros that look
1371 like variable references rather than function calls. Each
1372 @var{binding} is a list @samp{(@var{var} @var{expansion})};
1373 any reference to @var{var} within the body @var{forms} is
1374 replaced by @var{expansion}.
1378 (cl-symbol-macrolet ((foo (car bar)))
1384 A @code{setq} of a symbol macro is treated the same as a @code{setf}.
1385 I.e., @code{(setq foo 4)} in the above would be equivalent to
1386 @code{(setf foo 4)}, which in turn expands to @code{(setf (car bar) 4)}.
1388 Likewise, a @code{let} or @code{let*} binding a symbol macro is
1389 treated like a @code{cl-letf} or @code{cl-letf*}. This differs from true
1390 Common Lisp, where the rules of lexical scoping cause a @code{let}
1391 binding to shadow a @code{symbol-macrolet} binding. In this package,
1392 such shadowing does not occur, even when @code{lexical-binding} is
1393 @c See http://debbugs.gnu.org/12119
1394 @code{t}. (This behavior predates the addition of lexical binding to
1395 Emacs Lisp, and may change in future to respect @code{lexical-binding}.)
1396 At present in this package, only @code{lexical-let} and
1397 @code{lexical-let*} will shadow a symbol macro. @xref{Obsolete
1400 There is no analogue of @code{defmacro} for symbol macros; all symbol
1401 macros are local. A typical use of @code{cl-symbol-macrolet} is in the
1402 expansion of another macro:
1405 (cl-defmacro my-dolist ((x list) &rest body)
1406 (let ((var (cl-gensym)))
1407 (list 'cl-loop 'for var 'on list 'do
1408 (cl-list* 'cl-symbol-macrolet
1409 (list (list x (list 'car var)))
1412 (setq mylist '(1 2 3 4))
1413 (my-dolist (x mylist) (cl-incf x))
1419 In this example, the @code{my-dolist} macro is similar to @code{dolist}
1420 (@pxref{Iteration}) except that the variable @code{x} becomes a true
1421 reference onto the elements of the list. The @code{my-dolist} call
1422 shown here expands to
1425 (cl-loop for G1234 on mylist do
1426 (cl-symbol-macrolet ((x (car G1234)))
1431 which in turn expands to
1434 (cl-loop for G1234 on mylist do (cl-incf (car G1234)))
1437 @xref{Loop Facility}, for a description of the @code{cl-loop} macro.
1438 This package defines a nonstandard @code{in-ref} loop clause that
1439 works much like @code{my-dolist}.
1443 @section Conditionals
1446 These conditional forms augment Emacs Lisp's simple @code{if},
1447 @code{and}, @code{or}, and @code{cond} forms.
1449 @defmac cl-case keyform clause@dots{}
1450 This macro evaluates @var{keyform}, then compares it with the key
1451 values listed in the various @var{clause}s. Whichever clause matches
1452 the key is executed; comparison is done by @code{eql}. If no clause
1453 matches, the @code{cl-case} form returns @code{nil}. The clauses are
1457 (@var{keylist} @var{body-forms}@dots{})
1461 where @var{keylist} is a list of key values. If there is exactly
1462 one value, and it is not a cons cell or the symbol @code{nil} or
1463 @code{t}, then it can be used by itself as a @var{keylist} without
1464 being enclosed in a list. All key values in the @code{cl-case} form
1465 must be distinct. The final clauses may use @code{t} in place of
1466 a @var{keylist} to indicate a default clause that should be taken
1467 if none of the other clauses match. (The symbol @code{otherwise}
1468 is also recognized in place of @code{t}. To make a clause that
1469 matches the actual symbol @code{t}, @code{nil}, or @code{otherwise},
1470 enclose the symbol in a list.)
1472 For example, this expression reads a keystroke, then does one of
1473 four things depending on whether it is an @samp{a}, a @samp{b},
1474 a @key{RET} or @kbd{C-j}, or anything else.
1477 (cl-case (read-char)
1480 ((?\r ?\n) (do-ret-thing))
1481 (t (do-other-thing)))
1485 @defmac cl-ecase keyform clause@dots{}
1486 This macro is just like @code{cl-case}, except that if the key does
1487 not match any of the clauses, an error is signaled rather than
1488 simply returning @code{nil}.
1491 @defmac cl-typecase keyform clause@dots{}
1492 This macro is a version of @code{cl-case} that checks for types
1493 rather than values. Each @var{clause} is of the form
1494 @samp{(@var{type} @var{body}@dots{})}. @xref{Type Predicates},
1495 for a description of type specifiers. For example,
1499 (integer (munch-integer x))
1500 (float (munch-float x))
1501 (string (munch-integer (string-to-int x)))
1502 (t (munch-anything x)))
1505 The type specifier @code{t} matches any type of object; the word
1506 @code{otherwise} is also allowed. To make one clause match any of
1507 several types, use an @code{(or @dots{})} type specifier.
1510 @defmac cl-etypecase keyform clause@dots{}
1511 This macro is just like @code{cl-typecase}, except that if the key does
1512 not match any of the clauses, an error is signaled rather than
1513 simply returning @code{nil}.
1516 @node Blocks and Exits
1517 @section Blocks and Exits
1520 Common Lisp @dfn{blocks} provide a non-local exit mechanism very
1521 similar to @code{catch} and @code{throw}, with lexical scoping.
1522 This package actually implements @code{cl-block}
1523 in terms of @code{catch}; however, the lexical scoping allows the
1524 optimizing byte-compiler to omit the costly @code{catch} step if the
1525 body of the block does not actually @code{cl-return-from} the block.
1527 @defmac cl-block name forms@dots{}
1528 The @var{forms} are evaluated as if by a @code{progn}. However,
1529 if any of the @var{forms} execute @code{(cl-return-from @var{name})},
1530 they will jump out and return directly from the @code{cl-block} form.
1531 The @code{cl-block} returns the result of the last @var{form} unless
1532 a @code{cl-return-from} occurs.
1534 The @code{cl-block}/@code{cl-return-from} mechanism is quite similar to
1535 the @code{catch}/@code{throw} mechanism. The main differences are
1536 that block @var{name}s are unevaluated symbols, rather than forms
1537 (such as quoted symbols) that evaluate to a tag at run-time; and
1538 also that blocks are always lexically scoped.
1539 In a dynamically scoped @code{catch}, functions called from the
1540 @code{catch} body can also @code{throw} to the @code{catch}. This
1541 is not an option for @code{cl-block}, where
1542 the @code{cl-return-from} referring to a block name must appear
1543 physically within the @var{forms} that make up the body of the block.
1544 They may not appear within other called functions, although they may
1545 appear within macro expansions or @code{lambda}s in the body. Block
1546 names and @code{catch} names form independent name-spaces.
1548 In true Common Lisp, @code{defun} and @code{defmacro} surround
1549 the function or expander bodies with implicit blocks with the
1550 same name as the function or macro. This does not occur in Emacs
1551 Lisp, but this package provides @code{cl-defun} and @code{cl-defmacro}
1552 forms, which do create the implicit block.
1554 The Common Lisp looping constructs defined by this package,
1555 such as @code{cl-loop} and @code{cl-dolist}, also create implicit blocks
1556 just as in Common Lisp.
1558 Because they are implemented in terms of Emacs Lisp's @code{catch}
1559 and @code{throw}, blocks have the same overhead as actual
1560 @code{catch} constructs (roughly two function calls). However,
1561 the optimizing byte compiler will optimize away the @code{catch}
1563 not in fact contain any @code{cl-return} or @code{cl-return-from} calls
1564 that jump to it. This means that @code{cl-do} loops and @code{cl-defun}
1565 functions that don't use @code{cl-return} don't pay the overhead to
1569 @defmac cl-return-from name [result]
1570 This macro returns from the block named @var{name}, which must be
1571 an (unevaluated) symbol. If a @var{result} form is specified, it
1572 is evaluated to produce the result returned from the @code{block}.
1573 Otherwise, @code{nil} is returned.
1576 @defmac cl-return [result]
1577 This macro is exactly like @code{(cl-return-from nil @var{result})}.
1578 Common Lisp loops like @code{cl-do} and @code{cl-dolist} implicitly enclose
1579 themselves in @code{nil} blocks.
1586 The macros described here provide more sophisticated, high-level
1587 looping constructs to complement Emacs Lisp's basic loop forms
1588 (@pxref{Iteration,,,elisp,GNU Emacs Lisp Reference Manual}).
1590 @defmac cl-loop forms@dots{}
1591 This package supports both the simple, old-style meaning of
1592 @code{loop} and the extremely powerful and flexible feature known as
1593 the @dfn{Loop Facility} or @dfn{Loop Macro}. This more advanced
1594 facility is discussed in the following section; @pxref{Loop Facility}.
1595 The simple form of @code{loop} is described here.
1597 If @code{cl-loop} is followed by zero or more Lisp expressions,
1598 then @code{(cl-loop @var{exprs}@dots{})} simply creates an infinite
1599 loop executing the expressions over and over. The loop is
1600 enclosed in an implicit @code{nil} block. Thus,
1603 (cl-loop (foo) (if (no-more) (return 72)) (bar))
1607 is exactly equivalent to
1610 (cl-block nil (while t (foo) (if (no-more) (return 72)) (bar)))
1613 If any of the expressions are plain symbols, the loop is instead
1614 interpreted as a Loop Macro specification as described later.
1615 (This is not a restriction in practice, since a plain symbol
1616 in the above notation would simply access and throw away the
1617 value of a variable.)
1620 @defmac cl-do (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
1621 This macro creates a general iterative loop. Each @var{spec} is
1625 (@var{var} [@var{init} [@var{step}]])
1628 The loop works as follows: First, each @var{var} is bound to the
1629 associated @var{init} value as if by a @code{let} form. Then, in
1630 each iteration of the loop, the @var{end-test} is evaluated; if
1631 true, the loop is finished. Otherwise, the body @var{forms} are
1632 evaluated, then each @var{var} is set to the associated @var{step}
1633 expression (as if by a @code{cl-psetq} form) and the next iteration
1634 begins. Once the @var{end-test} becomes true, the @var{result}
1635 forms are evaluated (with the @var{var}s still bound to their
1636 values) to produce the result returned by @code{cl-do}.
1638 The entire @code{cl-do} loop is enclosed in an implicit @code{nil}
1639 block, so that you can use @code{(cl-return)} to break out of the
1642 If there are no @var{result} forms, the loop returns @code{nil}.
1643 If a given @var{var} has no @var{step} form, it is bound to its
1644 @var{init} value but not otherwise modified during the @code{cl-do}
1645 loop (unless the code explicitly modifies it); this case is just
1646 a shorthand for putting a @code{(let ((@var{var} @var{init})) @dots{})}
1647 around the loop. If @var{init} is also omitted it defaults to
1648 @code{nil}, and in this case a plain @samp{@var{var}} can be used
1649 in place of @samp{(@var{var})}, again following the analogy with
1652 This example (from Steele) illustrates a loop that applies the
1653 function @code{f} to successive pairs of values from the lists
1654 @code{foo} and @code{bar}; it is equivalent to the call
1655 @code{(cl-mapcar 'f foo bar)}. Note that this loop has no body
1656 @var{forms} at all, performing all its work as side effects of
1657 the rest of the loop.
1660 (cl-do ((x foo (cdr x))
1662 (z nil (cons (f (car x) (car y)) z)))
1663 ((or (null x) (null y))
1668 @defmac cl-do* (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
1669 This is to @code{cl-do} what @code{let*} is to @code{let}. In
1670 particular, the initial values are bound as if by @code{let*}
1671 rather than @code{let}, and the steps are assigned as if by
1672 @code{setq} rather than @code{cl-psetq}.
1674 Here is another way to write the above loop:
1677 (cl-do* ((xp foo (cdr xp))
1679 (x (car xp) (car xp))
1680 (y (car yp) (car yp))
1682 ((or (null xp) (null yp))
1688 @defmac cl-dolist (var list [result]) forms@dots{}
1689 This is exactly like the standard Emacs Lisp macro @code{dolist},
1690 but surrounds the loop with an implicit @code{nil} block.
1693 @defmac cl-dotimes (var count [result]) forms@dots{}
1694 This is exactly like the standard Emacs Lisp macro @code{dotimes},
1695 but surrounds the loop with an implicit @code{nil} block.
1696 The body is executed with @var{var} bound to the integers
1697 from zero (inclusive) to @var{count} (exclusive), in turn. Then
1698 @c FIXME lispref does not state this part explicitly, could move this there.
1699 the @code{result} form is evaluated with @var{var} bound to the total
1700 number of iterations that were done (i.e., @code{(max 0 @var{count})})
1701 to get the return value for the loop form.
1704 @defmac cl-do-symbols (var [obarray [result]]) forms@dots{}
1705 This loop iterates over all interned symbols. If @var{obarray}
1706 is specified and is not @code{nil}, it loops over all symbols in
1707 that obarray. For each symbol, the body @var{forms} are evaluated
1708 with @var{var} bound to that symbol. The symbols are visited in
1709 an unspecified order. Afterward the @var{result} form, if any,
1710 is evaluated (with @var{var} bound to @code{nil}) to get the return
1711 value. The loop is surrounded by an implicit @code{nil} block.
1714 @defmac cl-do-all-symbols (var [result]) forms@dots{}
1715 This is identical to @code{cl-do-symbols} except that the @var{obarray}
1716 argument is omitted; it always iterates over the default obarray.
1719 @xref{Mapping over Sequences}, for some more functions for
1720 iterating over vectors or lists.
1723 @section Loop Facility
1726 A common complaint with Lisp's traditional looping constructs is
1727 that they are either too simple and limited, such as Common Lisp's
1728 @code{dotimes} or Emacs Lisp's @code{while}, or too unreadable and
1729 obscure, like Common Lisp's @code{do} loop.
1731 To remedy this, recent versions of Common Lisp have added a new
1732 construct called the ``Loop Facility'' or ``@code{loop} macro'',
1733 with an easy-to-use but very powerful and expressive syntax.
1736 * Loop Basics:: @code{cl-loop} macro, basic clause structure.
1737 * Loop Examples:: Working examples of @code{cl-loop} macro.
1738 * For Clauses:: Clauses introduced by @code{for} or @code{as}.
1739 * Iteration Clauses:: @code{repeat}, @code{while}, @code{thereis}, etc.
1740 * Accumulation Clauses:: @code{collect}, @code{sum}, @code{maximize}, etc.
1741 * Other Clauses:: @code{with}, @code{if}, @code{initially}, @code{finally}.
1745 @subsection Loop Basics
1748 The @code{cl-loop} macro essentially creates a mini-language within
1749 Lisp that is specially tailored for describing loops. While this
1750 language is a little strange-looking by the standards of regular Lisp,
1751 it turns out to be very easy to learn and well-suited to its purpose.
1753 Since @code{cl-loop} is a macro, all parsing of the loop language
1754 takes place at byte-compile time; compiled @code{cl-loop}s are just
1755 as efficient as the equivalent @code{while} loops written longhand.
1757 @defmac cl-loop clauses@dots{}
1758 A loop construct consists of a series of @var{clause}s, each
1759 introduced by a symbol like @code{for} or @code{do}. Clauses
1760 are simply strung together in the argument list of @code{cl-loop},
1761 with minimal extra parentheses. The various types of clauses
1762 specify initializations, such as the binding of temporary
1763 variables, actions to be taken in the loop, stepping actions,
1766 Common Lisp specifies a certain general order of clauses in a
1770 (cl-loop @var{name-clause}
1771 @var{var-clauses}@dots{}
1772 @var{action-clauses}@dots{})
1775 The @var{name-clause} optionally gives a name to the implicit
1776 block that surrounds the loop. By default, the implicit block
1777 is named @code{nil}. The @var{var-clauses} specify what
1778 variables should be bound during the loop, and how they should
1779 be modified or iterated throughout the course of the loop. The
1780 @var{action-clauses} are things to be done during the loop, such
1781 as computing, collecting, and returning values.
1783 The Emacs version of the @code{cl-loop} macro is less restrictive about
1784 the order of clauses, but things will behave most predictably if
1785 you put the variable-binding clauses @code{with}, @code{for}, and
1786 @code{repeat} before the action clauses. As in Common Lisp,
1787 @code{initially} and @code{finally} clauses can go anywhere.
1789 Loops generally return @code{nil} by default, but you can cause
1790 them to return a value by using an accumulation clause like
1791 @code{collect}, an end-test clause like @code{always}, or an
1792 explicit @code{return} clause to jump out of the implicit block.
1793 (Because the loop body is enclosed in an implicit block, you can
1794 also use regular Lisp @code{cl-return} or @code{cl-return-from} to
1795 break out of the loop.)
1798 The following sections give some examples of the Loop Macro in
1799 action, and describe the particular loop clauses in great detail.
1800 Consult the second edition of Steele for additional discussion
1801 and examples of the @code{loop} macro.
1804 @subsection Loop Examples
1807 Before listing the full set of clauses that are allowed, let's
1808 look at a few example loops just to get a feel for the @code{cl-loop}
1812 (cl-loop for buf in (buffer-list)
1813 collect (buffer-file-name buf))
1817 This loop iterates over all Emacs buffers, using the list
1818 returned by @code{buffer-list}. For each buffer @var{buf},
1819 it calls @code{buffer-file-name} and collects the results into
1820 a list, which is then returned from the @code{cl-loop} construct.
1821 The result is a list of the file names of all the buffers in
1822 Emacs's memory. The words @code{for}, @code{in}, and @code{collect}
1823 are reserved words in the @code{cl-loop} language.
1826 (cl-loop repeat 20 do (insert "Yowsa\n"))
1830 This loop inserts the phrase ``Yowsa'' twenty times in the
1834 (cl-loop until (eobp) do (munch-line) (forward-line 1))
1838 This loop calls @code{munch-line} on every line until the end
1839 of the buffer. If point is already at the end of the buffer,
1840 the loop exits immediately.
1843 (cl-loop do (munch-line) until (eobp) do (forward-line 1))
1847 This loop is similar to the above one, except that @code{munch-line}
1848 is always called at least once.
1851 (cl-loop for x from 1 to 100
1854 finally return (list x (= y 729)))
1858 This more complicated loop searches for a number @code{x} whose
1859 square is 729. For safety's sake it only examines @code{x}
1860 values up to 100; dropping the phrase @samp{to 100} would
1861 cause the loop to count upwards with no limit. The second
1862 @code{for} clause defines @code{y} to be the square of @code{x}
1863 within the loop; the expression after the @code{=} sign is
1864 reevaluated each time through the loop. The @code{until}
1865 clause gives a condition for terminating the loop, and the
1866 @code{finally} clause says what to do when the loop finishes.
1867 (This particular example was written less concisely than it
1868 could have been, just for the sake of illustration.)
1870 Note that even though this loop contains three clauses (two
1871 @code{for}s and an @code{until}) that would have been enough to
1872 define loops all by themselves, it still creates a single loop
1873 rather than some sort of triple-nested loop. You must explicitly
1874 nest your @code{cl-loop} constructs if you want nested loops.
1877 @subsection For Clauses
1880 Most loops are governed by one or more @code{for} clauses.
1881 A @code{for} clause simultaneously describes variables to be
1882 bound, how those variables are to be stepped during the loop,
1883 and usually an end condition based on those variables.
1885 The word @code{as} is a synonym for the word @code{for}. This
1886 word is followed by a variable name, then a word like @code{from}
1887 or @code{across} that describes the kind of iteration desired.
1888 In Common Lisp, the phrase @code{being the} sometimes precedes
1889 the type of iteration; in this package both @code{being} and
1890 @code{the} are optional. The word @code{each} is a synonym
1891 for @code{the}, and the word that follows it may be singular
1892 or plural: @samp{for x being the elements of y} or
1893 @samp{for x being each element of y}. Which form you use
1894 is purely a matter of style.
1896 The variable is bound around the loop as if by @code{let}:
1900 (cl-loop for i from 1 to 10 do (do-something-with i))
1906 @item for @var{var} from @var{expr1} to @var{expr2} by @var{expr3}
1907 This type of @code{for} clause creates a counting loop. Each of
1908 the three sub-terms is optional, though there must be at least one
1909 term so that the clause is marked as a counting clause.
1911 The three expressions are the starting value, the ending value, and
1912 the step value, respectively, of the variable. The loop counts
1913 upwards by default (@var{expr3} must be positive), from @var{expr1}
1914 to @var{expr2} inclusively. If you omit the @code{from} term, the
1915 loop counts from zero; if you omit the @code{to} term, the loop
1916 counts forever without stopping (unless stopped by some other
1917 loop clause, of course); if you omit the @code{by} term, the loop
1918 counts in steps of one.
1920 You can replace the word @code{from} with @code{upfrom} or
1921 @code{downfrom} to indicate the direction of the loop. Likewise,
1922 you can replace @code{to} with @code{upto} or @code{downto}.
1923 For example, @samp{for x from 5 downto 1} executes five times
1924 with @code{x} taking on the integers from 5 down to 1 in turn.
1925 Also, you can replace @code{to} with @code{below} or @code{above},
1926 which are like @code{upto} and @code{downto} respectively except
1927 that they are exclusive rather than inclusive limits:
1930 (cl-loop for x to 10 collect x)
1931 @result{} (0 1 2 3 4 5 6 7 8 9 10)
1932 (cl-loop for x below 10 collect x)
1933 @result{} (0 1 2 3 4 5 6 7 8 9)
1936 The @code{by} value is always positive, even for downward-counting
1937 loops. Some sort of @code{from} value is required for downward
1938 loops; @samp{for x downto 5} is not a valid loop clause all by
1941 @item for @var{var} in @var{list} by @var{function}
1942 This clause iterates @var{var} over all the elements of @var{list},
1943 in turn. If you specify the @code{by} term, then @var{function}
1944 is used to traverse the list instead of @code{cdr}; it must be a
1945 function taking one argument. For example:
1948 (cl-loop for x in '(1 2 3 4 5 6) collect (* x x))
1949 @result{} (1 4 9 16 25 36)
1950 (cl-loop for x in '(1 2 3 4 5 6) by 'cddr collect (* x x))
1954 @item for @var{var} on @var{list} by @var{function}
1955 This clause iterates @var{var} over all the cons cells of @var{list}.
1958 (cl-loop for x on '(1 2 3 4) collect x)
1959 @result{} ((1 2 3 4) (2 3 4) (3 4) (4))
1962 With @code{by}, there is no real reason that the @code{on} expression
1963 must be a list. For example:
1966 (cl-loop for x on first-animal by 'next-animal collect x)
1970 where @code{(next-animal x)} takes an ``animal'' @var{x} and returns
1971 the next in the (assumed) sequence of animals, or @code{nil} if
1972 @var{x} was the last animal in the sequence.
1974 @item for @var{var} in-ref @var{list} by @var{function}
1975 This is like a regular @code{in} clause, but @var{var} becomes
1976 a @code{setf}-able ``reference'' onto the elements of the list
1977 rather than just a temporary variable. For example,
1980 (cl-loop for x in-ref my-list do (cl-incf x))
1984 increments every element of @code{my-list} in place. This clause
1985 is an extension to standard Common Lisp.
1987 @item for @var{var} across @var{array}
1988 This clause iterates @var{var} over all the elements of @var{array},
1989 which may be a vector or a string.
1992 (cl-loop for x across "aeiou"
1993 do (use-vowel (char-to-string x)))
1996 @item for @var{var} across-ref @var{array}
1997 This clause iterates over an array, with @var{var} a @code{setf}-able
1998 reference onto the elements; see @code{in-ref} above.
2000 @item for @var{var} being the elements of @var{sequence}
2001 This clause iterates over the elements of @var{sequence}, which may
2002 be a list, vector, or string. Since the type must be determined
2003 at run-time, this is somewhat less efficient than @code{in} or
2004 @code{across}. The clause may be followed by the additional term
2005 @samp{using (index @var{var2})} to cause @var{var2} to be bound to
2006 the successive indices (starting at 0) of the elements.
2008 This clause type is taken from older versions of the @code{loop} macro,
2009 and is not present in modern Common Lisp. The @samp{using (sequence @dots{})}
2010 term of the older macros is not supported.
2012 @item for @var{var} being the elements of-ref @var{sequence}
2013 This clause iterates over a sequence, with @var{var} a @code{setf}-able
2014 reference onto the elements; see @code{in-ref} above.
2016 @item for @var{var} being the symbols [of @var{obarray}]
2017 This clause iterates over symbols, either over all interned symbols
2018 or over all symbols in @var{obarray}. The loop is executed with
2019 @var{var} bound to each symbol in turn. The symbols are visited in
2020 an unspecified order.
2025 (cl-loop for sym being the symbols
2027 when (string-match "^map" (symbol-name sym))
2032 returns a list of all the functions whose names begin with @samp{map}.
2034 The Common Lisp words @code{external-symbols} and @code{present-symbols}
2035 are also recognized but are equivalent to @code{symbols} in Emacs Lisp.
2037 Due to a minor implementation restriction, it will not work to have
2038 more than one @code{for} clause iterating over symbols, hash tables,
2039 keymaps, overlays, or intervals in a given @code{cl-loop}. Fortunately,
2040 it would rarely if ever be useful to do so. It @emph{is} valid to mix
2041 one of these types of clauses with other clauses like @code{for @dots{} to}
2044 @item for @var{var} being the hash-keys of @var{hash-table}
2045 @itemx for @var{var} being the hash-values of @var{hash-table}
2046 This clause iterates over the entries in @var{hash-table} with
2047 @var{var} bound to each key, or value. A @samp{using} clause can bind
2048 a second variable to the opposite part.
2051 (cl-loop for k being the hash-keys of h
2052 using (hash-values v)
2054 (message "key %S -> value %S" k v))
2057 @item for @var{var} being the key-codes of @var{keymap}
2058 @itemx for @var{var} being the key-bindings of @var{keymap}
2059 This clause iterates over the entries in @var{keymap}.
2060 The iteration does not enter nested keymaps but does enter inherited
2062 A @code{using} clause can access both the codes and the bindings
2066 (cl-loop for c being the key-codes of (current-local-map)
2067 using (key-bindings b)
2069 (message "key %S -> binding %S" c b))
2073 @item for @var{var} being the key-seqs of @var{keymap}
2074 This clause iterates over all key sequences defined by @var{keymap}
2075 and its nested keymaps, where @var{var} takes on values which are
2076 vectors. The strings or vectors
2077 are reused for each iteration, so you must copy them if you wish to keep
2078 them permanently. You can add a @samp{using (key-bindings @dots{})}
2079 clause to get the command bindings as well.
2081 @item for @var{var} being the overlays [of @var{buffer}] @dots{}
2082 This clause iterates over the ``overlays'' of a buffer
2083 (the clause @code{extents} is synonymous
2084 with @code{overlays}). If the @code{of} term is omitted, the current
2086 This clause also accepts optional @samp{from @var{pos}} and
2087 @samp{to @var{pos}} terms, limiting the clause to overlays which
2088 overlap the specified region.
2090 @item for @var{var} being the intervals [of @var{buffer}] @dots{}
2091 This clause iterates over all intervals of a buffer with constant
2092 text properties. The variable @var{var} will be bound to conses
2093 of start and end positions, where one start position is always equal
2094 to the previous end position. The clause allows @code{of},
2095 @code{from}, @code{to}, and @code{property} terms, where the latter
2096 term restricts the search to just the specified property. The
2097 @code{of} term may specify either a buffer or a string.
2099 @item for @var{var} being the frames
2100 This clause iterates over all Emacs frames. The clause @code{screens} is
2101 a synonym for @code{frames}. The frames are visited in
2102 @code{next-frame} order starting from @code{selected-frame}.
2104 @item for @var{var} being the windows [of @var{frame}]
2105 This clause iterates over the windows (in the Emacs sense) of
2106 the current frame, or of the specified @var{frame}. It visits windows
2107 in @code{next-window} order starting from @code{selected-window}
2108 (or @code{frame-selected-window} if you specify @var{frame}).
2109 This clause treats the minibuffer window in the same way as
2110 @code{next-window} does. For greater flexibility, consider using
2111 @code{walk-windows} instead.
2113 @item for @var{var} being the buffers
2114 This clause iterates over all buffers in Emacs. It is equivalent
2115 to @samp{for @var{var} in (buffer-list)}.
2117 @item for @var{var} = @var{expr1} then @var{expr2}
2118 This clause does a general iteration. The first time through
2119 the loop, @var{var} will be bound to @var{expr1}. On the second
2120 and successive iterations it will be set by evaluating @var{expr2}
2121 (which may refer to the old value of @var{var}). For example,
2122 these two loops are effectively the same:
2125 (cl-loop for x on my-list by 'cddr do @dots{})
2126 (cl-loop for x = my-list then (cddr x) while x do @dots{})
2129 Note that this type of @code{for} clause does not imply any sort
2130 of terminating condition; the above example combines it with a
2131 @code{while} clause to tell when to end the loop.
2133 If you omit the @code{then} term, @var{expr1} is used both for
2134 the initial setting and for successive settings:
2137 (cl-loop for x = (random) when (> x 0) return x)
2141 This loop keeps taking random numbers from the @code{(random)}
2142 function until it gets a positive one, which it then returns.
2145 If you include several @code{for} clauses in a row, they are
2146 treated sequentially (as if by @code{let*} and @code{setq}).
2147 You can instead use the word @code{and} to link the clauses,
2148 in which case they are processed in parallel (as if by @code{let}
2149 and @code{cl-psetq}).
2152 (cl-loop for x below 5 for y = nil then x collect (list x y))
2153 @result{} ((0 nil) (1 1) (2 2) (3 3) (4 4))
2154 (cl-loop for x below 5 and y = nil then x collect (list x y))
2155 @result{} ((0 nil) (1 0) (2 1) (3 2) (4 3))
2159 In the first loop, @code{y} is set based on the value of @code{x}
2160 that was just set by the previous clause; in the second loop,
2161 @code{x} and @code{y} are set simultaneously so @code{y} is set
2162 based on the value of @code{x} left over from the previous time
2165 Another feature of the @code{cl-loop} macro is @dfn{destructuring},
2166 similar in concept to the destructuring provided by @code{defmacro}.
2167 The @var{var} part of any @code{for} clause can be given as a list
2168 of variables instead of a single variable. The values produced
2169 during loop execution must be lists; the values in the lists are
2170 stored in the corresponding variables.
2173 (cl-loop for (x y) in '((2 3) (4 5) (6 7)) collect (+ x y))
2177 In loop destructuring, if there are more values than variables
2178 the trailing values are ignored, and if there are more variables
2179 than values the trailing variables get the value @code{nil}.
2180 If @code{nil} is used as a variable name, the corresponding
2181 values are ignored. Destructuring may be nested, and dotted
2182 lists of variables like @code{(x . y)} are allowed, so for example
2186 (cl-loop for (key . value) in '((a . 1) (b . 2))
2191 @node Iteration Clauses
2192 @subsection Iteration Clauses
2195 Aside from @code{for} clauses, there are several other loop clauses
2196 that control the way the loop operates. They might be used by
2197 themselves, or in conjunction with one or more @code{for} clauses.
2200 @item repeat @var{integer}
2201 This clause simply counts up to the specified number using an
2202 internal temporary variable. The loops
2205 (cl-loop repeat (1+ n) do @dots{})
2206 (cl-loop for temp to n do @dots{})
2210 are identical except that the second one forces you to choose
2211 a name for a variable you aren't actually going to use.
2213 @item while @var{condition}
2214 This clause stops the loop when the specified condition (any Lisp
2215 expression) becomes @code{nil}. For example, the following two
2216 loops are equivalent, except for the implicit @code{nil} block
2217 that surrounds the second one:
2220 (while @var{cond} @var{forms}@dots{})
2221 (cl-loop while @var{cond} do @var{forms}@dots{})
2224 @item until @var{condition}
2225 This clause stops the loop when the specified condition is true,
2226 i.e., non-@code{nil}.
2228 @item always @var{condition}
2229 This clause stops the loop when the specified condition is @code{nil}.
2230 Unlike @code{while}, it stops the loop using @code{return nil} so that
2231 the @code{finally} clauses are not executed. If all the conditions
2232 were non-@code{nil}, the loop returns @code{t}:
2235 (if (cl-loop for size in size-list always (> size 10))
2240 @item never @var{condition}
2241 This clause is like @code{always}, except that the loop returns
2242 @code{t} if any conditions were false, or @code{nil} otherwise.
2244 @item thereis @var{condition}
2245 This clause stops the loop when the specified form is non-@code{nil};
2246 in this case, it returns that non-@code{nil} value. If all the
2247 values were @code{nil}, the loop returns @code{nil}.
2250 @node Accumulation Clauses
2251 @subsection Accumulation Clauses
2254 These clauses cause the loop to accumulate information about the
2255 specified Lisp @var{form}. The accumulated result is returned
2256 from the loop unless overridden, say, by a @code{return} clause.
2259 @item collect @var{form}
2260 This clause collects the values of @var{form} into a list. Several
2261 examples of @code{collect} appear elsewhere in this manual.
2263 The word @code{collecting} is a synonym for @code{collect}, and
2264 likewise for the other accumulation clauses.
2266 @item append @var{form}
2267 This clause collects lists of values into a result list using
2270 @item nconc @var{form}
2271 This clause collects lists of values into a result list by
2272 destructively modifying the lists rather than copying them.
2274 @item concat @var{form}
2275 This clause concatenates the values of the specified @var{form}
2276 into a string. (It and the following clause are extensions to
2277 standard Common Lisp.)
2279 @item vconcat @var{form}
2280 This clause concatenates the values of the specified @var{form}
2283 @item count @var{form}
2284 This clause counts the number of times the specified @var{form}
2285 evaluates to a non-@code{nil} value.
2287 @item sum @var{form}
2288 This clause accumulates the sum of the values of the specified
2289 @var{form}, which must evaluate to a number.
2291 @item maximize @var{form}
2292 This clause accumulates the maximum value of the specified @var{form},
2293 which must evaluate to a number. The return value is undefined if
2294 @code{maximize} is executed zero times.
2296 @item minimize @var{form}
2297 This clause accumulates the minimum value of the specified @var{form}.
2300 Accumulation clauses can be followed by @samp{into @var{var}} to
2301 cause the data to be collected into variable @var{var} (which is
2302 automatically @code{let}-bound during the loop) rather than an
2303 unnamed temporary variable. Also, @code{into} accumulations do
2304 not automatically imply a return value. The loop must use some
2305 explicit mechanism, such as @code{finally return}, to return
2306 the accumulated result.
2308 It is valid for several accumulation clauses of the same type to
2309 accumulate into the same place. From Steele:
2312 (cl-loop for name in '(fred sue alice joe june)
2313 for kids in '((bob ken) () () (kris sunshine) ())
2316 @result{} (fred bob ken sue alice joe kris sunshine june)
2320 @subsection Other Clauses
2323 This section describes the remaining loop clauses.
2326 @item with @var{var} = @var{value}
2327 This clause binds a variable to a value around the loop, but
2328 otherwise leaves the variable alone during the loop. The following
2329 loops are basically equivalent:
2332 (cl-loop with x = 17 do @dots{})
2333 (let ((x 17)) (cl-loop do @dots{}))
2334 (cl-loop for x = 17 then x do @dots{})
2337 Naturally, the variable @var{var} might be used for some purpose
2338 in the rest of the loop. For example:
2341 (cl-loop for x in my-list with res = nil do (push x res)
2345 This loop inserts the elements of @code{my-list} at the front of
2346 a new list being accumulated in @code{res}, then returns the
2347 list @code{res} at the end of the loop. The effect is similar
2348 to that of a @code{collect} clause, but the list gets reversed
2349 by virtue of the fact that elements are being pushed onto the
2350 front of @code{res} rather than the end.
2352 If you omit the @code{=} term, the variable is initialized to
2353 @code{nil}. (Thus the @samp{= nil} in the above example is
2356 Bindings made by @code{with} are sequential by default, as if
2357 by @code{let*}. Just like @code{for} clauses, @code{with} clauses
2358 can be linked with @code{and} to cause the bindings to be made by
2361 @item if @var{condition} @var{clause}
2362 This clause executes the following loop clause only if the specified
2363 condition is true. The following @var{clause} should be an accumulation,
2364 @code{do}, @code{return}, @code{if}, or @code{unless} clause.
2365 Several clauses may be linked by separating them with @code{and}.
2366 These clauses may be followed by @code{else} and a clause or clauses
2367 to execute if the condition was false. The whole construct may
2368 optionally be followed by the word @code{end} (which may be used to
2369 disambiguate an @code{else} or @code{and} in a nested @code{if}).
2371 The actual non-@code{nil} value of the condition form is available
2372 by the name @code{it} in the ``then'' part. For example:
2375 (setq funny-numbers '(6 13 -1))
2377 (cl-loop for x below 10
2380 and if (memq x funny-numbers) return (cdr it) end
2382 collect x into evens
2383 finally return (vector odds evens))
2384 @result{} [(1 3 5 7 9) (0 2 4 6 8)]
2385 (setq funny-numbers '(6 7 13 -1))
2386 @result{} (6 7 13 -1)
2387 (cl-loop <@r{same thing again}>)
2391 Note the use of @code{and} to put two clauses into the ``then''
2392 part, one of which is itself an @code{if} clause. Note also that
2393 @code{end}, while normally optional, was necessary here to make
2394 it clear that the @code{else} refers to the outermost @code{if}
2395 clause. In the first case, the loop returns a vector of lists
2396 of the odd and even values of @var{x}. In the second case, the
2397 odd number 7 is one of the @code{funny-numbers} so the loop
2398 returns early; the actual returned value is based on the result
2399 of the @code{memq} call.
2401 @item when @var{condition} @var{clause}
2402 This clause is just a synonym for @code{if}.
2404 @item unless @var{condition} @var{clause}
2405 The @code{unless} clause is just like @code{if} except that the
2406 sense of the condition is reversed.
2408 @item named @var{name}
2409 This clause gives a name other than @code{nil} to the implicit
2410 block surrounding the loop. The @var{name} is the symbol to be
2411 used as the block name.
2413 @item initially [do] @var{forms}@dots{}
2414 This keyword introduces one or more Lisp forms which will be
2415 executed before the loop itself begins (but after any variables
2416 requested by @code{for} or @code{with} have been bound to their
2417 initial values). @code{initially} clauses can appear anywhere;
2418 if there are several, they are executed in the order they appear
2419 in the loop. The keyword @code{do} is optional.
2421 @item finally [do] @var{forms}@dots{}
2422 This introduces Lisp forms which will be executed after the loop
2423 finishes (say, on request of a @code{for} or @code{while}).
2424 @code{initially} and @code{finally} clauses may appear anywhere
2425 in the loop construct, but they are executed (in the specified
2426 order) at the beginning or end, respectively, of the loop.
2428 @item finally return @var{form}
2429 This says that @var{form} should be executed after the loop
2430 is done to obtain a return value. (Without this, or some other
2431 clause like @code{collect} or @code{return}, the loop will simply
2432 return @code{nil}.) Variables bound by @code{for}, @code{with},
2433 or @code{into} will still contain their final values when @var{form}
2436 @item do @var{forms}@dots{}
2437 The word @code{do} may be followed by any number of Lisp expressions
2438 which are executed as an implicit @code{progn} in the body of the
2439 loop. Many of the examples in this section illustrate the use of
2442 @item return @var{form}
2443 This clause causes the loop to return immediately. The following
2444 Lisp form is evaluated to give the return value of the @code{loop}
2445 form. The @code{finally} clauses, if any, are not executed.
2446 Of course, @code{return} is generally used inside an @code{if} or
2447 @code{unless}, as its use in a top-level loop clause would mean
2448 the loop would never get to ``loop'' more than once.
2450 The clause @samp{return @var{form}} is equivalent to
2451 @c FIXME cl-do, cl-return?
2452 @samp{do (return @var{form})} (or @code{return-from} if the loop
2453 was named). The @code{return} clause is implemented a bit more
2454 efficiently, though.
2457 While there is no high-level way to add user extensions to @code{cl-loop},
2458 this package does offer two properties called @code{cl-loop-handler}
2459 and @code{cl-loop-for-handler} which are functions to be called when a
2460 given symbol is encountered as a top-level loop clause or @code{for}
2461 clause, respectively. Consult the source code in file
2462 @file{cl-macs.el} for details.
2464 This package's @code{cl-loop} macro is compatible with that of Common
2465 Lisp, except that a few features are not implemented: @code{loop-finish}
2466 and data-type specifiers. Naturally, the @code{for} clauses which
2467 iterate over keymaps, overlays, intervals, frames, windows, and
2468 buffers are Emacs-specific extensions.
2470 @node Multiple Values
2471 @section Multiple Values
2474 Common Lisp functions can return zero or more results. Emacs Lisp
2475 functions, by contrast, always return exactly one result. This
2476 package makes no attempt to emulate Common Lisp multiple return
2477 values; Emacs versions of Common Lisp functions that return more
2478 than one value either return just the first value (as in
2479 @code{cl-compiler-macroexpand}) or return a list of values.
2480 This package @emph{does} define placeholders
2481 for the Common Lisp functions that work with multiple values, but
2482 in Emacs Lisp these functions simply operate on lists instead.
2483 The @code{cl-values} form, for example, is a synonym for @code{list}
2486 @defmac cl-multiple-value-bind (var@dots{}) values-form forms@dots{}
2487 This form evaluates @var{values-form}, which must return a list of
2488 values. It then binds the @var{var}s to these respective values,
2489 as if by @code{let}, and then executes the body @var{forms}.
2490 If there are more @var{var}s than values, the extra @var{var}s
2491 are bound to @code{nil}. If there are fewer @var{var}s than
2492 values, the excess values are ignored.
2495 @defmac cl-multiple-value-setq (var@dots{}) form
2496 This form evaluates @var{form}, which must return a list of values.
2497 It then sets the @var{var}s to these respective values, as if by
2498 @code{setq}. Extra @var{var}s or values are treated the same as
2499 in @code{cl-multiple-value-bind}.
2502 Since a perfect emulation is not feasible in Emacs Lisp, this
2503 package opts to keep it as simple and predictable as possible.
2509 This package implements the various Common Lisp features of
2510 @code{defmacro}, such as destructuring, @code{&environment},
2511 and @code{&body}. Top-level @code{&whole} is not implemented
2512 for @code{defmacro} due to technical difficulties.
2513 @xref{Argument Lists}.
2515 Destructuring is made available to the user by way of the
2518 @defmac cl-destructuring-bind arglist expr forms@dots{}
2519 This macro expands to code which executes @var{forms}, with
2520 the variables in @var{arglist} bound to the list of values
2521 returned by @var{expr}. The @var{arglist} can include all
2522 the features allowed for @code{defmacro} argument lists,
2523 including destructuring. (The @code{&environment} keyword
2524 is not allowed.) The macro expansion will signal an error
2525 if @var{expr} returns a list of the wrong number of arguments
2526 or with incorrect keyword arguments.
2529 This package also includes the Common Lisp @code{cl-define-compiler-macro}
2530 facility, which allows you to define compile-time expansions and
2531 optimizations for your functions.
2533 @defmac cl-define-compiler-macro name arglist forms@dots{}
2534 This form is similar to @code{defmacro}, except that it only expands
2535 calls to @var{name} at compile-time; calls processed by the Lisp
2536 interpreter are not expanded, nor are they expanded by the
2537 @code{macroexpand} function.
2539 The argument list may begin with a @code{&whole} keyword and a
2540 variable. This variable is bound to the macro-call form itself,
2541 i.e., to a list of the form @samp{(@var{name} @var{args}@dots{})}.
2542 If the macro expander returns this form unchanged, then the
2543 compiler treats it as a normal function call. This allows
2544 compiler macros to work as optimizers for special cases of a
2545 function, leaving complicated cases alone.
2547 For example, here is a simplified version of a definition that
2548 appears as a standard part of this package:
2551 (cl-define-compiler-macro cl-member (&whole form a list &rest keys)
2552 (if (and (null keys)
2553 (eq (car-safe a) 'quote)
2554 (not (floatp-safe (cadr a))))
2560 This definition causes @code{(cl-member @var{a} @var{list})} to change
2561 to a call to the faster @code{memq} in the common case where @var{a}
2562 is a non-floating-point constant; if @var{a} is anything else, or
2563 if there are any keyword arguments in the call, then the original
2564 @code{cl-member} call is left intact. (The actual compiler macro
2565 for @code{cl-member} optimizes a number of other cases, including
2566 common @code{:test} predicates.)
2569 @defun cl-compiler-macroexpand form
2570 This function is analogous to @code{macroexpand}, except that it
2571 expands compiler macros rather than regular macros. It returns
2572 @var{form} unchanged if it is not a call to a function for which
2573 a compiler macro has been defined, or if that compiler macro
2574 decided to punt by returning its @code{&whole} argument. Like
2575 @code{macroexpand}, it expands repeatedly until it reaches a form
2576 for which no further expansion is possible.
2579 @xref{Macro Bindings}, for descriptions of the @code{cl-macrolet}
2580 and @code{cl-symbol-macrolet} forms for making ``local'' macro
2584 @chapter Declarations
2587 Common Lisp includes a complex and powerful ``declaration''
2588 mechanism that allows you to give the compiler special hints
2589 about the types of data that will be stored in particular variables,
2590 and about the ways those variables and functions will be used. This
2591 package defines versions of all the Common Lisp declaration forms:
2592 @code{cl-declare}, @code{cl-locally}, @code{cl-proclaim}, @code{cl-declaim},
2595 Most of the Common Lisp declarations are not currently useful in
2596 Emacs Lisp, as the byte-code system provides little opportunity
2597 to benefit from type information, and @code{special} declarations
2598 are redundant in a fully dynamically-scoped Lisp. A few
2599 declarations are meaningful when the optimizing byte
2600 compiler is being used, however. Under the earlier non-optimizing
2601 compiler, these declarations will effectively be ignored.
2603 @defun cl-proclaim decl-spec
2604 This function records a ``global'' declaration specified by
2605 @var{decl-spec}. Since @code{cl-proclaim} is a function, @var{decl-spec}
2606 is evaluated and thus should normally be quoted.
2609 @defmac cl-declaim decl-specs@dots{}
2610 This macro is like @code{cl-proclaim}, except that it takes any number
2611 of @var{decl-spec} arguments, and the arguments are unevaluated and
2612 unquoted. The @code{cl-declaim} macro also puts an @code{(cl-eval-when
2613 (compile load eval) @dots{})} around the declarations so that they will
2614 be registered at compile-time as well as at run-time. (This is vital,
2615 since normally the declarations are meant to influence the way the
2616 compiler treats the rest of the file that contains the @code{cl-declaim}
2620 @defmac cl-declare decl-specs@dots{}
2621 This macro is used to make declarations within functions and other
2622 code. Common Lisp allows declarations in various locations, generally
2623 at the beginning of any of the many ``implicit @code{progn}s''
2624 throughout Lisp syntax, such as function bodies, @code{let} bodies,
2625 etc. Currently the only declaration understood by @code{cl-declare}
2629 @defmac cl-locally declarations@dots{} forms@dots{}
2630 In this package, @code{cl-locally} is no different from @code{progn}.
2633 @defmac cl-the type form
2634 Type information provided by @code{cl-the} is ignored in this package;
2635 in other words, @code{(cl-the @var{type} @var{form})} is equivalent
2636 to @var{form}. Future versions of the optimizing byte-compiler may
2637 make use of this information.
2639 For example, @code{mapcar} can map over both lists and arrays. It is
2640 hard for the compiler to expand @code{mapcar} into an in-line loop
2641 unless it knows whether the sequence will be a list or an array ahead
2642 of time. With @code{(mapcar 'car (cl-the vector foo))}, a future
2643 compiler would have enough information to expand the loop in-line.
2644 For now, Emacs Lisp will treat the above code as exactly equivalent
2645 to @code{(mapcar 'car foo)}.
2648 Each @var{decl-spec} in a @code{cl-proclaim}, @code{cl-declaim}, or
2649 @code{cl-declare} should be a list beginning with a symbol that says
2650 what kind of declaration it is. This package currently understands
2651 @code{special}, @code{inline}, @code{notinline}, @code{optimize},
2652 and @code{warn} declarations. (The @code{warn} declaration is an
2653 extension of standard Common Lisp.) Other Common Lisp declarations,
2654 such as @code{type} and @code{ftype}, are silently ignored.
2658 Since all variables in Emacs Lisp are ``special'' (in the Common
2659 Lisp sense), @code{special} declarations are only advisory. They
2660 simply tell the optimizing byte compiler that the specified
2661 variables are intentionally being referred to without being
2662 bound in the body of the function. The compiler normally emits
2663 warnings for such references, since they could be typographical
2664 errors for references to local variables.
2666 The declaration @code{(cl-declare (special @var{var1} @var{var2}))} is
2667 equivalent to @code{(defvar @var{var1}) (defvar @var{var2})} in the
2668 optimizing compiler, or to nothing at all in older compilers (which
2669 do not warn for non-local references).
2671 In top-level contexts, it is generally better to write
2672 @code{(defvar @var{var})} than @code{(cl-declaim (special @var{var}))},
2673 since @code{defvar} makes your intentions clearer. But the older
2674 byte compilers can not handle @code{defvar}s appearing inside of
2675 functions, while @code{(cl-declare (special @var{var}))} takes care
2676 to work correctly with all compilers.
2679 The @code{inline} @var{decl-spec} lists one or more functions
2680 whose bodies should be expanded ``in-line'' into calling functions
2681 whenever the compiler is able to arrange for it. For example,
2682 the Common Lisp function @code{cadr} is declared @code{inline}
2683 by this package so that the form @code{(cadr @var{x})} will
2684 expand directly into @code{(car (cdr @var{x}))} when it is called
2685 in user functions, for a savings of one (relatively expensive)
2688 The following declarations are all equivalent. Note that the
2689 @code{defsubst} form is a convenient way to define a function
2690 and declare it inline all at once.
2693 (cl-declaim (inline foo bar))
2694 (cl-eval-when (compile load eval)
2695 (cl-proclaim '(inline foo bar)))
2696 (defsubst foo (@dots{}) @dots{}) ; instead of defun
2699 @strong{Please note:} this declaration remains in effect after the
2700 containing source file is done. It is correct to use it to
2701 request that a function you have defined should be inlined,
2702 but it is impolite to use it to request inlining of an external
2705 In Common Lisp, it is possible to use @code{(cl-declare (inline @dots{}))}
2706 before a particular call to a function to cause just that call to
2707 be inlined; the current byte compilers provide no way to implement
2708 this, so @code{(cl-declare (inline @dots{}))} is currently ignored by
2712 The @code{notinline} declaration lists functions which should
2713 not be inlined after all; it cancels a previous @code{inline}
2717 This declaration controls how much optimization is performed by
2718 the compiler. Naturally, it is ignored by the earlier non-optimizing
2721 The word @code{optimize} is followed by any number of lists like
2722 @code{(speed 3)} or @code{(safety 2)}. Common Lisp defines several
2723 optimization ``qualities''; this package ignores all but @code{speed}
2724 and @code{safety}. The value of a quality should be an integer from
2725 0 to 3, with 0 meaning ``unimportant'' and 3 meaning ``very important''.
2726 The default level for both qualities is 1.
2728 In this package, with the optimizing compiler, the
2729 @code{speed} quality is tied to the @code{byte-optimize}
2730 flag, which is set to @code{nil} for @code{(speed 0)} and to
2731 @code{t} for higher settings; and the @code{safety} quality is
2732 tied to the @code{byte-compile-delete-errors} flag, which is
2733 set to @code{nil} for @code{(safety 3)} and to @code{t} for all
2734 lower settings. (The latter flag controls whether the compiler
2735 is allowed to optimize out code whose only side-effect could
2736 be to signal an error, e.g., rewriting @code{(progn foo bar)} to
2737 @code{bar} when it is not known whether @code{foo} will be bound
2740 Note that even compiling with @code{(safety 0)}, the Emacs
2741 byte-code system provides sufficient checking to prevent real
2742 harm from being done. For example, barring serious bugs in
2743 Emacs itself, Emacs will not crash with a segmentation fault
2744 just because of an error in a fully-optimized Lisp program.
2746 The @code{optimize} declaration is normally used in a top-level
2747 @code{cl-proclaim} or @code{cl-declaim} in a file; Common Lisp allows
2748 it to be used with @code{cl-declare} to set the level of optimization
2749 locally for a given form, but this will not work correctly with the
2750 current version of the optimizing compiler. (The @code{cl-declare}
2751 will set the new optimization level, but that level will not
2752 automatically be unset after the enclosing form is done.)
2755 This declaration controls what sorts of warnings are generated
2756 by the byte compiler. Again, only the optimizing compiler
2757 generates warnings. The word @code{warn} is followed by any
2758 number of ``warning qualities'', similar in form to optimization
2759 qualities. The currently supported warning types are
2760 @code{redefine}, @code{callargs}, @code{unresolved}, and
2761 @code{free-vars}; in the current system, a value of 0 will
2762 disable these warnings and any higher value will enable them.
2763 See the documentation for the optimizing byte compiler for details.
2770 This package defines several symbol-related features that were
2771 missing from Emacs Lisp.
2774 * Property Lists:: @code{cl-get}, @code{cl-remprop}, @code{cl-getf}, @code{cl-remf}.
2775 * Creating Symbols:: @code{cl-gensym}, @code{cl-gentemp}.
2778 @node Property Lists
2779 @section Property Lists
2782 These functions augment the standard Emacs Lisp functions @code{get}
2783 and @code{put} for operating on properties attached to symbols.
2784 There are also functions for working with property lists as
2785 first-class data structures not attached to particular symbols.
2787 @defun cl-get symbol property &optional default
2788 This function is like @code{get}, except that if the property is
2789 not found, the @var{default} argument provides the return value.
2790 (The Emacs Lisp @code{get} function always uses @code{nil} as
2791 the default; this package's @code{cl-get} is equivalent to Common
2794 The @code{cl-get} function is @code{setf}-able; when used in this
2795 fashion, the @var{default} argument is allowed but ignored.
2798 @defun cl-remprop symbol property
2799 This function removes the entry for @var{property} from the property
2800 list of @var{symbol}. It returns a true value if the property was
2801 indeed found and removed, or @code{nil} if there was no such property.
2802 (This function was probably omitted from Emacs originally because,
2803 since @code{get} did not allow a @var{default}, it was very difficult
2804 to distinguish between a missing property and a property whose value
2805 was @code{nil}; thus, setting a property to @code{nil} was close
2806 enough to @code{cl-remprop} for most purposes.)
2809 @defun cl-getf place property &optional default
2810 This function scans the list @var{place} as if it were a property
2811 list, i.e., a list of alternating property names and values. If
2812 an even-numbered element of @var{place} is found which is @code{eq}
2813 to @var{property}, the following odd-numbered element is returned.
2814 Otherwise, @var{default} is returned (or @code{nil} if no default
2820 (get sym prop) @equiv{} (cl-getf (symbol-plist sym) prop)
2823 It is valid to use @code{cl-getf} as a @code{setf} place, in which case
2824 its @var{place} argument must itself be a valid @code{setf} place.
2825 The @var{default} argument, if any, is ignored in this context.
2826 The effect is to change (via @code{setcar}) the value cell in the
2827 list that corresponds to @var{property}, or to cons a new property-value
2828 pair onto the list if the property is not yet present.
2831 (put sym prop val) @equiv{} (setf (cl-getf (symbol-plist sym) prop) val)
2834 The @code{get} and @code{cl-get} functions are also @code{setf}-able.
2835 The fact that @code{default} is ignored can sometimes be useful:
2838 (cl-incf (cl-get 'foo 'usage-count 0))
2841 Here, symbol @code{foo}'s @code{usage-count} property is incremented
2842 if it exists, or set to 1 (an incremented 0) otherwise.
2844 When not used as a @code{setf} form, @code{cl-getf} is just a regular
2845 function and its @var{place} argument can actually be any Lisp
2849 @defmac cl-remf place property
2850 This macro removes the property-value pair for @var{property} from
2851 the property list stored at @var{place}, which is any @code{setf}-able
2852 place expression. It returns true if the property was found. Note
2853 that if @var{property} happens to be first on the list, this will
2854 effectively do a @code{(setf @var{place} (cddr @var{place}))},
2855 whereas if it occurs later, this simply uses @code{setcdr} to splice
2856 out the property and value cells.
2859 @node Creating Symbols
2860 @section Creating Symbols
2863 These functions create unique symbols, typically for use as
2864 temporary variables.
2866 @defun cl-gensym &optional x
2867 This function creates a new, uninterned symbol (using @code{make-symbol})
2868 with a unique name. (The name of an uninterned symbol is relevant
2869 only if the symbol is printed.) By default, the name is generated
2870 from an increasing sequence of numbers, @samp{G1000}, @samp{G1001},
2871 @samp{G1002}, etc. If the optional argument @var{x} is a string, that
2872 string is used as a prefix instead of @samp{G}. Uninterned symbols
2873 are used in macro expansions for temporary variables, to ensure that
2874 their names will not conflict with ``real'' variables in the user's
2878 @defvar cl--gensym-counter
2879 This variable holds the counter used to generate @code{cl-gensym} names.
2880 It is incremented after each use by @code{cl-gensym}. In Common Lisp
2881 this is initialized with 0, but this package initializes it with a
2882 random (time-dependent) value to avoid trouble when two files that
2883 each used @code{cl-gensym} in their compilation are loaded together.
2884 (Uninterned symbols become interned when the compiler writes them
2885 out to a file and the Emacs loader loads them, so their names have to
2886 be treated a bit more carefully than in Common Lisp where uninterned
2887 symbols remain uninterned after loading.)
2890 @defun cl-gentemp &optional x
2891 This function is like @code{cl-gensym}, except that it produces a new
2892 @emph{interned} symbol. If the symbol that is generated already
2893 exists, the function keeps incrementing the counter and trying
2894 again until a new symbol is generated.
2897 This package automatically creates all keywords that are called for by
2898 @code{&key} argument specifiers, and discourages the use of keywords
2899 as data unrelated to keyword arguments, so the related function
2900 @code{defkeyword} (to create self-quoting keyword symbols) is not
2907 This section defines a few simple Common Lisp operations on numbers
2908 which were left out of Emacs Lisp.
2911 * Predicates on Numbers:: @code{cl-plusp}, @code{cl-oddp}, @code{cl-floatp-safe}, etc.
2912 * Numerical Functions:: @code{abs}, @code{cl-floor}, etc.
2913 * Random Numbers:: @code{cl-random}, @code{cl-make-random-state}.
2914 * Implementation Parameters:: @code{cl-most-positive-float}.
2917 @node Predicates on Numbers
2918 @section Predicates on Numbers
2921 These functions return @code{t} if the specified condition is
2922 true of the numerical argument, or @code{nil} otherwise.
2924 @defun cl-plusp number
2925 This predicate tests whether @var{number} is positive. It is an
2926 error if the argument is not a number.
2929 @defun cl-minusp number
2930 This predicate tests whether @var{number} is negative. It is an
2931 error if the argument is not a number.
2934 @defun cl-oddp integer
2935 This predicate tests whether @var{integer} is odd. It is an
2936 error if the argument is not an integer.
2939 @defun cl-evenp integer
2940 This predicate tests whether @var{integer} is even. It is an
2941 error if the argument is not an integer.
2944 @defun cl-floatp-safe object
2945 This predicate tests whether @var{object} is a floating-point
2946 number. On systems that support floating-point, this is equivalent
2947 to @code{floatp}. On other systems, this always returns @code{nil}.
2950 @node Numerical Functions
2951 @section Numerical Functions
2954 These functions perform various arithmetic operations on numbers.
2956 @defun cl-gcd &rest integers
2957 This function returns the Greatest Common Divisor of the arguments.
2958 For one argument, it returns the absolute value of that argument.
2959 For zero arguments, it returns zero.
2962 @defun cl-lcm &rest integers
2963 This function returns the Least Common Multiple of the arguments.
2964 For one argument, it returns the absolute value of that argument.
2965 For zero arguments, it returns one.
2968 @defun cl-isqrt integer
2969 This function computes the ``integer square root'' of its integer
2970 argument, i.e., the greatest integer less than or equal to the true
2971 square root of the argument.
2974 @defun cl-floor number &optional divisor
2975 With one argument, @code{cl-floor} returns a list of two numbers:
2976 The argument rounded down (toward minus infinity) to an integer,
2977 and the ``remainder'' which would have to be added back to the
2978 first return value to yield the argument again. If the argument
2979 is an integer @var{x}, the result is always the list @code{(@var{x} 0)}.
2980 If the argument is a floating-point number, the first
2981 result is a Lisp integer and the second is a Lisp float between
2982 0 (inclusive) and 1 (exclusive).
2984 With two arguments, @code{cl-floor} divides @var{number} by
2985 @var{divisor}, and returns the floor of the quotient and the
2986 corresponding remainder as a list of two numbers. If
2987 @code{(cl-floor @var{x} @var{y})} returns @code{(@var{q} @var{r})},
2988 then @code{@var{q}*@var{y} + @var{r} = @var{x}}, with @var{r}
2989 between 0 (inclusive) and @var{r} (exclusive). Also, note
2990 that @code{(cl-floor @var{x})} is exactly equivalent to
2991 @code{(cl-floor @var{x} 1)}.
2993 This function is entirely compatible with Common Lisp's @code{floor}
2994 function, except that it returns the two results in a list since
2995 Emacs Lisp does not support multiple-valued functions.
2998 @defun cl-ceiling number &optional divisor
2999 This function implements the Common Lisp @code{ceiling} function,
3000 which is analogous to @code{floor} except that it rounds the
3001 argument or quotient of the arguments up toward plus infinity.
3002 The remainder will be between 0 and minus @var{r}.
3005 @defun cl-truncate number &optional divisor
3006 This function implements the Common Lisp @code{truncate} function,
3007 which is analogous to @code{floor} except that it rounds the
3008 argument or quotient of the arguments toward zero. Thus it is
3009 equivalent to @code{cl-floor} if the argument or quotient is
3010 positive, or to @code{cl-ceiling} otherwise. The remainder has
3011 the same sign as @var{number}.
3014 @defun cl-round number &optional divisor
3015 This function implements the Common Lisp @code{round} function,
3016 which is analogous to @code{floor} except that it rounds the
3017 argument or quotient of the arguments to the nearest integer.
3018 In the case of a tie (the argument or quotient is exactly
3019 halfway between two integers), it rounds to the even integer.
3022 @defun cl-mod number divisor
3023 This function returns the same value as the second return value
3027 @defun cl-rem number divisor
3028 This function returns the same value as the second return value
3029 of @code{cl-truncate}.
3032 @node Random Numbers
3033 @section Random Numbers
3036 This package also provides an implementation of the Common Lisp
3037 random number generator. It uses its own additive-congruential
3038 algorithm, which is much more likely to give statistically clean
3039 random numbers than the simple generators supplied by many
3042 @defun cl-random number &optional state
3043 This function returns a random nonnegative number less than
3044 @var{number}, and of the same type (either integer or floating-point).
3045 The @var{state} argument should be a @code{random-state} object
3046 which holds the state of the random number generator. The
3047 function modifies this state object as a side effect. If
3048 @var{state} is omitted, it defaults to the variable
3049 @code{cl--random-state}, which contains a pre-initialized
3050 @code{random-state} object.
3053 @defvar cl--random-state
3054 This variable contains the system ``default'' @code{random-state}
3055 object, used for calls to @code{cl-random} that do not specify an
3056 alternative state object. Since any number of programs in the
3057 Emacs process may be accessing @code{cl--random-state} in interleaved
3058 fashion, the sequence generated from this variable will be
3059 irreproducible for all intents and purposes.
3062 @defun cl-make-random-state &optional state
3063 This function creates or copies a @code{random-state} object.
3064 If @var{state} is omitted or @code{nil}, it returns a new copy of
3065 @code{cl--random-state}. This is a copy in the sense that future
3066 sequences of calls to @code{(cl-random @var{n})} and
3067 @code{(cl-random @var{n} @var{s})} (where @var{s} is the new
3068 random-state object) will return identical sequences of random
3071 If @var{state} is a @code{random-state} object, this function
3072 returns a copy of that object. If @var{state} is @code{t}, this
3073 function returns a new @code{random-state} object seeded from the
3074 date and time. As an extension to Common Lisp, @var{state} may also
3075 be an integer in which case the new object is seeded from that
3076 integer; each different integer seed will result in a completely
3077 different sequence of random numbers.
3079 It is valid to print a @code{random-state} object to a buffer or
3080 file and later read it back with @code{read}. If a program wishes
3081 to use a sequence of pseudo-random numbers which can be reproduced
3082 later for debugging, it can call @code{(cl-make-random-state t)} to
3083 get a new sequence, then print this sequence to a file. When the
3084 program is later rerun, it can read the original run's random-state
3088 @defun cl-random-state-p object
3089 This predicate returns @code{t} if @var{object} is a
3090 @code{random-state} object, or @code{nil} otherwise.
3093 @node Implementation Parameters
3094 @section Implementation Parameters
3097 This package defines several useful constants having to with numbers.
3099 The following parameters have to do with floating-point numbers.
3100 This package determines their values by exercising the computer's
3101 floating-point arithmetic in various ways. Because this operation
3102 might be slow, the code for initializing them is kept in a separate
3103 function that must be called before the parameters can be used.
3105 @defun cl-float-limits
3106 This function makes sure that the Common Lisp floating-point parameters
3107 like @code{cl-most-positive-float} have been initialized. Until it is
3108 called, these parameters will be @code{nil}. If this version of Emacs
3109 does not support floats, the parameters will remain @code{nil}. If the
3110 parameters have already been initialized, the function returns
3113 The algorithm makes assumptions that will be valid for most modern
3114 machines, but will fail if the machine's arithmetic is extremely
3115 unusual, e.g., decimal.
3118 Since true Common Lisp supports up to four different floating-point
3119 precisions, it has families of constants like
3120 @code{most-positive-single-float}, @code{most-positive-double-float},
3121 @code{most-positive-long-float}, and so on. Emacs has only one
3122 floating-point precision, so this package omits the precision word
3123 from the constants' names.
3125 @defvar cl-most-positive-float
3126 This constant equals the largest value a Lisp float can hold.
3127 For those systems whose arithmetic supports infinities, this is
3128 the largest @emph{finite} value. For IEEE machines, the value
3129 is approximately @code{1.79e+308}.
3132 @defvar cl-most-negative-float
3133 This constant equals the most-negative value a Lisp float can hold.
3134 (It is assumed to be equal to @code{(- cl-most-positive-float)}.)
3137 @defvar cl-least-positive-float
3138 This constant equals the smallest Lisp float value greater than zero.
3139 For IEEE machines, it is about @code{4.94e-324} if denormals are
3140 supported or @code{2.22e-308} if not.
3143 @defvar cl-least-positive-normalized-float
3144 This constant equals the smallest @emph{normalized} Lisp float greater
3145 than zero, i.e., the smallest value for which IEEE denormalization
3146 will not result in a loss of precision. For IEEE machines, this
3147 value is about @code{2.22e-308}. For machines that do not support
3148 the concept of denormalization and gradual underflow, this constant
3149 will always equal @code{cl-least-positive-float}.
3152 @defvar cl-least-negative-float
3153 This constant is the negative counterpart of @code{cl-least-positive-float}.
3156 @defvar cl-least-negative-normalized-float
3157 This constant is the negative counterpart of
3158 @code{cl-least-positive-normalized-float}.
3161 @defvar cl-float-epsilon
3162 This constant is the smallest positive Lisp float that can be added
3163 to 1.0 to produce a distinct value. Adding a smaller number to 1.0
3164 will yield 1.0 again due to roundoff. For IEEE machines, epsilon
3165 is about @code{2.22e-16}.
3168 @defvar cl-float-negative-epsilon
3169 This is the smallest positive value that can be subtracted from
3170 1.0 to produce a distinct value. For IEEE machines, it is about
3178 Common Lisp defines a number of functions that operate on
3179 @dfn{sequences}, which are either lists, strings, or vectors.
3180 Emacs Lisp includes a few of these, notably @code{elt} and
3181 @code{length}; this package defines most of the rest.
3184 * Sequence Basics:: Arguments shared by all sequence functions.
3185 * Mapping over Sequences:: @code{cl-mapcar}, @code{cl-map}, @code{cl-maplist}, etc.
3186 * Sequence Functions:: @code{cl-subseq}, @code{cl-remove}, @code{cl-substitute}, etc.
3187 * Searching Sequences:: @code{cl-find}, @code{cl-count}, @code{cl-search}, etc.
3188 * Sorting Sequences:: @code{cl-sort}, @code{cl-stable-sort}, @code{cl-merge}.
3191 @node Sequence Basics
3192 @section Sequence Basics
3195 Many of the sequence functions take keyword arguments; @pxref{Argument
3196 Lists}. All keyword arguments are optional and, if specified,
3197 may appear in any order.
3199 The @code{:key} argument should be passed either @code{nil}, or a
3200 function of one argument. This key function is used as a filter
3201 through which the elements of the sequence are seen; for example,
3202 @code{(cl-find x y :key 'car)} is similar to @code{(cl-assoc x y)}:
3203 It searches for an element of the list whose @sc{car} equals
3204 @code{x}, rather than for an element which equals @code{x} itself.
3205 If @code{:key} is omitted or @code{nil}, the filter is effectively
3206 the identity function.
3208 The @code{:test} and @code{:test-not} arguments should be either
3209 @code{nil}, or functions of two arguments. The test function is
3210 used to compare two sequence elements, or to compare a search value
3211 with sequence elements. (The two values are passed to the test
3212 function in the same order as the original sequence function
3213 arguments from which they are derived, or, if they both come from
3214 the same sequence, in the same order as they appear in that sequence.)
3215 The @code{:test} argument specifies a function which must return
3216 true (non-@code{nil}) to indicate a match; instead, you may use
3217 @code{:test-not} to give a function which returns @emph{false} to
3218 indicate a match. The default test function is @code{eql}.
3220 Many functions which take @var{item} and @code{:test} or @code{:test-not}
3221 arguments also come in @code{-if} and @code{-if-not} varieties,
3222 where a @var{predicate} function is passed instead of @var{item},
3223 and sequence elements match if the predicate returns true on them
3224 (or false in the case of @code{-if-not}). For example:
3227 (cl-remove 0 seq :test '=) @equiv{} (cl-remove-if 'zerop seq)
3231 to remove all zeros from sequence @code{seq}.
3233 Some operations can work on a subsequence of the argument sequence;
3234 these function take @code{:start} and @code{:end} arguments which
3235 default to zero and the length of the sequence, respectively.
3236 Only elements between @var{start} (inclusive) and @var{end}
3237 (exclusive) are affected by the operation. The @var{end} argument
3238 may be passed @code{nil} to signify the length of the sequence;
3239 otherwise, both @var{start} and @var{end} must be integers, with
3240 @code{0 <= @var{start} <= @var{end} <= (length @var{seq})}.
3241 If the function takes two sequence arguments, the limits are
3242 defined by keywords @code{:start1} and @code{:end1} for the first,
3243 and @code{:start2} and @code{:end2} for the second.
3245 A few functions accept a @code{:from-end} argument, which, if
3246 non-@code{nil}, causes the operation to go from right-to-left
3247 through the sequence instead of left-to-right, and a @code{:count}
3248 argument, which specifies an integer maximum number of elements
3249 to be removed or otherwise processed.
3251 The sequence functions make no guarantees about the order in
3252 which the @code{:test}, @code{:test-not}, and @code{:key} functions
3253 are called on various elements. Therefore, it is a bad idea to depend
3254 on side effects of these functions. For example, @code{:from-end}
3255 may cause the sequence to be scanned actually in reverse, or it may
3256 be scanned forwards but computing a result ``as if'' it were scanned
3257 backwards. (Some functions, like @code{cl-mapcar} and @code{cl-every},
3258 @emph{do} specify exactly the order in which the function is called
3259 so side effects are perfectly acceptable in those cases.)
3261 Strings may contain ``text properties'' as well
3262 as character data. Except as noted, it is undefined whether or
3263 not text properties are preserved by sequence functions. For
3264 example, @code{(cl-remove ?A @var{str})} may or may not preserve
3265 the properties of the characters copied from @var{str} into the
3268 @node Mapping over Sequences
3269 @section Mapping over Sequences
3272 These functions ``map'' the function you specify over the elements
3273 of lists or arrays. They are all variations on the theme of the
3274 built-in function @code{mapcar}.
3276 @defun cl-mapcar function seq &rest more-seqs
3277 This function calls @var{function} on successive parallel sets of
3278 elements from its argument sequences. Given a single @var{seq}
3279 argument it is equivalent to @code{mapcar}; given @var{n} sequences,
3280 it calls the function with the first elements of each of the sequences
3281 as the @var{n} arguments to yield the first element of the result
3282 list, then with the second elements, and so on. The mapping stops as
3283 soon as the shortest sequence runs out. The argument sequences may
3284 be any mixture of lists, strings, and vectors; the return sequence
3287 Common Lisp's @code{mapcar} accepts multiple arguments but works
3288 only on lists; Emacs Lisp's @code{mapcar} accepts a single sequence
3289 argument. This package's @code{cl-mapcar} works as a compatible
3293 @defun cl-map result-type function seq &rest more-seqs
3294 This function maps @var{function} over the argument sequences,
3295 just like @code{cl-mapcar}, but it returns a sequence of type
3296 @var{result-type} rather than a list. @var{result-type} must
3297 be one of the following symbols: @code{vector}, @code{string},
3298 @code{list} (in which case the effect is the same as for
3299 @code{cl-mapcar}), or @code{nil} (in which case the results are
3300 thrown away and @code{cl-map} returns @code{nil}).
3303 @defun cl-maplist function list &rest more-lists
3304 This function calls @var{function} on each of its argument lists,
3305 then on the @sc{cdr}s of those lists, and so on, until the
3306 shortest list runs out. The results are returned in the form
3307 of a list. Thus, @code{cl-maplist} is like @code{cl-mapcar} except
3308 that it passes in the list pointers themselves rather than the
3309 @sc{car}s of the advancing pointers.
3312 @defun cl-mapc function seq &rest more-seqs
3313 This function is like @code{cl-mapcar}, except that the values returned
3314 by @var{function} are ignored and thrown away rather than being
3315 collected into a list. The return value of @code{cl-mapc} is @var{seq},
3316 the first sequence. This function is more general than the Emacs
3317 primitive @code{mapc}. (Note that this function is called
3318 @code{cl-mapc} even in @file{cl.el}, rather than @code{mapc*} as you
3320 @c http://debbugs.gnu.org/6575
3323 @defun cl-mapl function list &rest more-lists
3324 This function is like @code{cl-maplist}, except that it throws away
3325 the values returned by @var{function}.
3328 @defun cl-mapcan function seq &rest more-seqs
3329 This function is like @code{cl-mapcar}, except that it concatenates
3330 the return values (which must be lists) using @code{nconc},
3331 rather than simply collecting them into a list.
3334 @defun cl-mapcon function list &rest more-lists
3335 This function is like @code{cl-maplist}, except that it concatenates
3336 the return values using @code{nconc}.
3339 @defun cl-some predicate seq &rest more-seqs
3340 This function calls @var{predicate} on each element of @var{seq}
3341 in turn; if @var{predicate} returns a non-@code{nil} value,
3342 @code{some} returns that value, otherwise it returns @code{nil}.
3343 Given several sequence arguments, it steps through the sequences
3344 in parallel until the shortest one runs out, just as in
3345 @code{cl-mapcar}. You can rely on the left-to-right order in which
3346 the elements are visited, and on the fact that mapping stops
3347 immediately as soon as @var{predicate} returns non-@code{nil}.
3350 @defun cl-every predicate seq &rest more-seqs
3351 This function calls @var{predicate} on each element of the sequence(s)
3352 in turn; it returns @code{nil} as soon as @var{predicate} returns
3353 @code{nil} for any element, or @code{t} if the predicate was true
3357 @defun cl-notany predicate seq &rest more-seqs
3358 This function calls @var{predicate} on each element of the sequence(s)
3359 in turn; it returns @code{nil} as soon as @var{predicate} returns
3360 a non-@code{nil} value for any element, or @code{t} if the predicate
3361 was @code{nil} for all elements.
3364 @defun cl-notevery predicate seq &rest more-seqs
3365 This function calls @var{predicate} on each element of the sequence(s)
3366 in turn; it returns a non-@code{nil} value as soon as @var{predicate}
3367 returns @code{nil} for any element, or @code{t} if the predicate was
3368 true for all elements.
3371 @defun cl-reduce function seq @t{&key :from-end :start :end :initial-value :key}
3372 This function combines the elements of @var{seq} using an associative
3373 binary operation. Suppose @var{function} is @code{*} and @var{seq} is
3374 the list @code{(2 3 4 5)}. The first two elements of the list are
3375 combined with @code{(* 2 3) = 6}; this is combined with the next
3376 element, @code{(* 6 4) = 24}, and that is combined with the final
3377 element: @code{(* 24 5) = 120}. Note that the @code{*} function happens
3378 to be self-reducing, so that @code{(* 2 3 4 5)} has the same effect as
3379 an explicit call to @code{cl-reduce}.
3381 If @code{:from-end} is true, the reduction is right-associative instead
3382 of left-associative:
3385 (cl-reduce '- '(1 2 3 4))
3386 @equiv{} (- (- (- 1 2) 3) 4) @result{} -8
3387 (cl-reduce '- '(1 2 3 4) :from-end t)
3388 @equiv{} (- 1 (- 2 (- 3 4))) @result{} -2
3391 If @code{:key} is specified, it is a function of one argument which
3392 is called on each of the sequence elements in turn.
3394 If @code{:initial-value} is specified, it is effectively added to the
3395 front (or rear in the case of @code{:from-end}) of the sequence.
3396 The @code{:key} function is @emph{not} applied to the initial value.
3398 If the sequence, including the initial value, has exactly one element
3399 then that element is returned without ever calling @var{function}.
3400 If the sequence is empty (and there is no initial value), then
3401 @var{function} is called with no arguments to obtain the return value.
3404 All of these mapping operations can be expressed conveniently in
3405 terms of the @code{cl-loop} macro. In compiled code, @code{cl-loop} will
3406 be faster since it generates the loop as in-line code with no
3409 @node Sequence Functions
3410 @section Sequence Functions
3413 This section describes a number of Common Lisp functions for
3414 operating on sequences.
3416 @defun cl-subseq sequence start &optional end
3417 This function returns a given subsequence of the argument
3418 @var{sequence}, which may be a list, string, or vector.
3419 The indices @var{start} and @var{end} must be in range, and
3420 @var{start} must be no greater than @var{end}. If @var{end}
3421 is omitted, it defaults to the length of the sequence. The
3422 return value is always a copy; it does not share structure
3423 with @var{sequence}.
3425 As an extension to Common Lisp, @var{start} and/or @var{end}
3426 may be negative, in which case they represent a distance back
3427 from the end of the sequence. This is for compatibility with
3428 Emacs's @code{substring} function. Note that @code{cl-subseq} is
3429 the @emph{only} sequence function that allows negative
3430 @var{start} and @var{end}.
3432 You can use @code{setf} on a @code{cl-subseq} form to replace a
3433 specified range of elements with elements from another sequence.
3434 The replacement is done as if by @code{cl-replace}, described below.
3437 @defun cl-concatenate result-type &rest seqs
3438 This function concatenates the argument sequences together to
3439 form a result sequence of type @var{result-type}, one of the
3440 symbols @code{vector}, @code{string}, or @code{list}. The
3441 arguments are always copied, even in cases such as
3442 @code{(cl-concatenate 'list '(1 2 3))} where the result is
3443 identical to an argument.
3446 @defun cl-fill seq item @t{&key :start :end}
3447 This function fills the elements of the sequence (or the specified
3448 part of the sequence) with the value @var{item}.
3451 @defun cl-replace seq1 seq2 @t{&key :start1 :end1 :start2 :end2}
3452 This function copies part of @var{seq2} into part of @var{seq1}.
3453 The sequence @var{seq1} is not stretched or resized; the amount
3454 of data copied is simply the shorter of the source and destination
3455 (sub)sequences. The function returns @var{seq1}.
3457 If @var{seq1} and @var{seq2} are @code{eq}, then the replacement
3458 will work correctly even if the regions indicated by the start
3459 and end arguments overlap. However, if @var{seq1} and @var{seq2}
3460 are lists which share storage but are not @code{eq}, and the
3461 start and end arguments specify overlapping regions, the effect
3465 @defun cl-remove item seq @t{&key :test :test-not :key :count :start :end :from-end}
3466 This returns a copy of @var{seq} with all elements matching
3467 @var{item} removed. The result may share storage with or be
3468 @code{eq} to @var{seq} in some circumstances, but the original
3469 @var{seq} will not be modified. The @code{:test}, @code{:test-not},
3470 and @code{:key} arguments define the matching test that is used;
3471 by default, elements @code{eql} to @var{item} are removed. The
3472 @code{:count} argument specifies the maximum number of matching
3473 elements that can be removed (only the leftmost @var{count} matches
3474 are removed). The @code{:start} and @code{:end} arguments specify
3475 a region in @var{seq} in which elements will be removed; elements
3476 outside that region are not matched or removed. The @code{:from-end}
3477 argument, if true, says that elements should be deleted from the
3478 end of the sequence rather than the beginning (this matters only
3479 if @var{count} was also specified).
3482 @defun cl-delete item seq @t{&key :test :test-not :key :count :start :end :from-end}
3483 This deletes all elements of @var{seq} which match @var{item}.
3484 It is a destructive operation. Since Emacs Lisp does not support
3485 stretchable strings or vectors, this is the same as @code{cl-remove}
3486 for those sequence types. On lists, @code{cl-remove} will copy the
3487 list if necessary to preserve the original list, whereas
3488 @code{cl-delete} will splice out parts of the argument list.
3489 Compare @code{append} and @code{nconc}, which are analogous
3490 non-destructive and destructive list operations in Emacs Lisp.
3493 @findex cl-remove-if
3494 @findex cl-remove-if-not
3495 @findex cl-delete-if
3496 @findex cl-delete-if-not
3497 The predicate-oriented functions @code{cl-remove-if}, @code{cl-remove-if-not},
3498 @code{cl-delete-if}, and @code{cl-delete-if-not} are defined similarly.
3500 @defun cl-remove-duplicates seq @t{&key :test :test-not :key :start :end :from-end}
3501 This function returns a copy of @var{seq} with duplicate elements
3502 removed. Specifically, if two elements from the sequence match
3503 according to the @code{:test}, @code{:test-not}, and @code{:key}
3504 arguments, only the rightmost one is retained. If @code{:from-end}
3505 is true, the leftmost one is retained instead. If @code{:start} or
3506 @code{:end} is specified, only elements within that subsequence are
3507 examined or removed.
3510 @defun cl-delete-duplicates seq @t{&key :test :test-not :key :start :end :from-end}
3511 This function deletes duplicate elements from @var{seq}. It is
3512 a destructive version of @code{cl-remove-duplicates}.
3515 @defun cl-substitute new old seq @t{&key :test :test-not :key :count :start :end :from-end}
3516 This function returns a copy of @var{seq}, with all elements
3517 matching @var{old} replaced with @var{new}. The @code{:count},
3518 @code{:start}, @code{:end}, and @code{:from-end} arguments may be
3519 used to limit the number of substitutions made.
3522 @defun cl-nsubstitute new old seq @t{&key :test :test-not :key :count :start :end :from-end}
3523 This is a destructive version of @code{cl-substitute}; it performs
3524 the substitution using @code{setcar} or @code{aset} rather than
3525 by returning a changed copy of the sequence.
3528 @findex cl-substitute-if
3529 @findex cl-substitute-if-not
3530 @findex cl-nsubstitute-if
3531 @findex cl-nsubstitute-if-not
3532 The functions @code{cl-substitute-if}, @code{cl-substitute-if-not},
3533 @code{cl-nsubstitute-if}, and @code{cl-nsubstitute-if-not} are defined
3534 similarly. For these, a @var{predicate} is given in place of the
3537 @node Searching Sequences
3538 @section Searching Sequences
3541 These functions search for elements or subsequences in a sequence.
3542 (See also @code{cl-member} and @code{cl-assoc}; @pxref{Lists}.)
3544 @defun cl-find item seq @t{&key :test :test-not :key :start :end :from-end}
3545 This function searches @var{seq} for an element matching @var{item}.
3546 If it finds a match, it returns the matching element. Otherwise,
3547 it returns @code{nil}. It returns the leftmost match, unless
3548 @code{:from-end} is true, in which case it returns the rightmost
3549 match. The @code{:start} and @code{:end} arguments may be used to
3550 limit the range of elements that are searched.
3553 @defun cl-position item seq @t{&key :test :test-not :key :start :end :from-end}
3554 This function is like @code{cl-find}, except that it returns the
3555 integer position in the sequence of the matching item rather than
3556 the item itself. The position is relative to the start of the
3557 sequence as a whole, even if @code{:start} is non-zero. The function
3558 returns @code{nil} if no matching element was found.
3561 @defun cl-count item seq @t{&key :test :test-not :key :start :end}
3562 This function returns the number of elements of @var{seq} which
3563 match @var{item}. The result is always a nonnegative integer.
3567 @findex cl-find-if-not
3568 @findex cl-position-if
3569 @findex cl-position-if-not
3571 @findex cl-count-if-not
3572 The @code{cl-find-if}, @code{cl-find-if-not}, @code{cl-position-if},
3573 @code{cl-position-if-not}, @code{cl-count-if}, and @code{cl-count-if-not}
3574 functions are defined similarly.
3576 @defun cl-mismatch seq1 seq2 @t{&key :test :test-not :key :start1 :end1 :start2 :end2 :from-end}
3577 This function compares the specified parts of @var{seq1} and
3578 @var{seq2}. If they are the same length and the corresponding
3579 elements match (according to @code{:test}, @code{:test-not},
3580 and @code{:key}), the function returns @code{nil}. If there is
3581 a mismatch, the function returns the index (relative to @var{seq1})
3582 of the first mismatching element. This will be the leftmost pair of
3583 elements which do not match, or the position at which the shorter of
3584 the two otherwise-matching sequences runs out.
3586 If @code{:from-end} is true, then the elements are compared from right
3587 to left starting at @code{(1- @var{end1})} and @code{(1- @var{end2})}.
3588 If the sequences differ, then one plus the index of the rightmost
3589 difference (relative to @var{seq1}) is returned.
3591 An interesting example is @code{(cl-mismatch str1 str2 :key 'upcase)},
3592 which compares two strings case-insensitively.
3595 @defun cl-search seq1 seq2 @t{&key :test :test-not :key :from-end :start1 :end1 :start2 :end2}
3596 This function searches @var{seq2} for a subsequence that matches
3597 @var{seq1} (or part of it specified by @code{:start1} and
3598 @code{:end1}.) Only matches which fall entirely within the region
3599 defined by @code{:start2} and @code{:end2} will be considered.
3600 The return value is the index of the leftmost element of the
3601 leftmost match, relative to the start of @var{seq2}, or @code{nil}
3602 if no matches were found. If @code{:from-end} is true, the
3603 function finds the @emph{rightmost} matching subsequence.
3606 @node Sorting Sequences
3607 @section Sorting Sequences
3609 @defun clsort seq predicate @t{&key :key}
3610 This function sorts @var{seq} into increasing order as determined
3611 by using @var{predicate} to compare pairs of elements. @var{predicate}
3612 should return true (non-@code{nil}) if and only if its first argument
3613 is less than (not equal to) its second argument. For example,
3614 @code{<} and @code{string-lessp} are suitable predicate functions
3615 for sorting numbers and strings, respectively; @code{>} would sort
3616 numbers into decreasing rather than increasing order.
3618 This function differs from Emacs's built-in @code{sort} in that it
3619 can operate on any type of sequence, not just lists. Also, it
3620 accepts a @code{:key} argument which is used to preprocess data
3621 fed to the @var{predicate} function. For example,
3624 (setq data (cl-sort data 'string-lessp :key 'downcase))
3628 sorts @var{data}, a sequence of strings, into increasing alphabetical
3629 order without regard to case. A @code{:key} function of @code{car}
3630 would be useful for sorting association lists. It should only be a
3631 simple accessor though, it's used heavily in the current
3634 The @code{cl-sort} function is destructive; it sorts lists by actually
3635 rearranging the @sc{cdr} pointers in suitable fashion.
3638 @defun cl-stable-sort seq predicate @t{&key :key}
3639 This function sorts @var{seq} @dfn{stably}, meaning two elements
3640 which are equal in terms of @var{predicate} are guaranteed not to
3641 be rearranged out of their original order by the sort.
3643 In practice, @code{cl-sort} and @code{cl-stable-sort} are equivalent
3644 in Emacs Lisp because the underlying @code{sort} function is
3645 stable by default. However, this package reserves the right to
3646 use non-stable methods for @code{cl-sort} in the future.
3649 @defun cl-merge type seq1 seq2 predicate @t{&key :key}
3650 This function merges two sequences @var{seq1} and @var{seq2} by
3651 interleaving their elements. The result sequence, of type @var{type}
3652 (in the sense of @code{cl-concatenate}), has length equal to the sum
3653 of the lengths of the two input sequences. The sequences may be
3654 modified destructively. Order of elements within @var{seq1} and
3655 @var{seq2} is preserved in the interleaving; elements of the two
3656 sequences are compared by @var{predicate} (in the sense of
3657 @code{sort}) and the lesser element goes first in the result.
3658 When elements are equal, those from @var{seq1} precede those from
3659 @var{seq2} in the result. Thus, if @var{seq1} and @var{seq2} are
3660 both sorted according to @var{predicate}, then the result will be
3661 a merged sequence which is (stably) sorted according to
3669 The functions described here operate on lists.
3672 * List Functions:: @code{cl-caddr}, @code{cl-first}, @code{cl-list*}, etc.
3673 * Substitution of Expressions:: @code{cl-subst}, @code{cl-sublis}, etc.
3674 * Lists as Sets:: @code{cl-member}, @code{cl-adjoin}, @code{cl-union}, etc.
3675 * Association Lists:: @code{cl-assoc}, @code{cl-acons}, @code{cl-pairlis}, etc.
3678 @node List Functions
3679 @section List Functions
3682 This section describes a number of simple operations on lists,
3683 i.e., chains of cons cells.
3686 This function is equivalent to @code{(car (cdr (cdr @var{x})))}.
3687 Likewise, this package defines all 28 @code{c@var{xxx}r} functions
3688 where @var{xxx} is up to four @samp{a}s and/or @samp{d}s.
3689 All of these functions are @code{setf}-able, and calls to them
3690 are expanded inline by the byte-compiler for maximum efficiency.
3694 This function is a synonym for @code{(car @var{x})}. Likewise,
3695 the functions @code{cl-second}, @code{cl-third}, @dots{}, through
3696 @code{cl-tenth} return the given element of the list @var{x}.
3700 This function is a synonym for @code{(cdr @var{x})}.
3704 Common Lisp defines this function to act like @code{null}, but
3705 signaling an error if @code{x} is neither a @code{nil} nor a
3706 cons cell. This package simply defines @code{cl-endp} as a synonym
3710 @defun cl-list-length x
3711 This function returns the length of list @var{x}, exactly like
3712 @code{(length @var{x})}, except that if @var{x} is a circular
3713 list (where the @sc{cdr}-chain forms a loop rather than terminating
3714 with @code{nil}), this function returns @code{nil}. (The regular
3715 @code{length} function would get stuck if given a circular list.)
3718 @defun cl-list* arg &rest others
3719 This function constructs a list of its arguments. The final
3720 argument becomes the @sc{cdr} of the last cell constructed.
3721 Thus, @code{(cl-list* @var{a} @var{b} @var{c})} is equivalent to
3722 @code{(cons @var{a} (cons @var{b} @var{c}))}, and
3723 @code{(cl-list* @var{a} @var{b} nil)} is equivalent to
3724 @code{(list @var{a} @var{b})}.
3727 @defun cl-ldiff list sublist
3728 If @var{sublist} is a sublist of @var{list}, i.e., is @code{eq} to
3729 one of the cons cells of @var{list}, then this function returns
3730 a copy of the part of @var{list} up to but not including
3731 @var{sublist}. For example, @code{(cl-ldiff x (cddr x))} returns
3732 the first two elements of the list @code{x}. The result is a
3733 copy; the original @var{list} is not modified. If @var{sublist}
3734 is not a sublist of @var{list}, a copy of the entire @var{list}
3738 @defun cl-copy-list list
3739 This function returns a copy of the list @var{list}. It copies
3740 dotted lists like @code{(1 2 . 3)} correctly.
3743 @defun copy-tree x &optional vecp
3744 This function returns a copy of the tree of cons cells @var{x}.
3745 @c FIXME? cl-copy-list is not an alias of copy-sequence.
3746 Unlike @code{copy-sequence} (and its alias @code{cl-copy-list}),
3747 which copies only along the @sc{cdr} direction, this function
3748 copies (recursively) along both the @sc{car} and the @sc{cdr}
3749 directions. If @var{x} is not a cons cell, the function simply
3750 returns @var{x} unchanged. If the optional @var{vecp} argument
3751 is true, this function copies vectors (recursively) as well as
3755 @defun cl-tree-equal x y @t{&key :test :test-not :key}
3756 This function compares two trees of cons cells. If @var{x} and
3757 @var{y} are both cons cells, their @sc{car}s and @sc{cdr}s are
3758 compared recursively. If neither @var{x} nor @var{y} is a cons
3759 cell, they are compared by @code{eql}, or according to the
3760 specified test. The @code{:key} function, if specified, is
3761 applied to the elements of both trees. @xref{Sequences}.
3764 @node Substitution of Expressions
3765 @section Substitution of Expressions
3768 These functions substitute elements throughout a tree of cons
3769 cells. (@xref{Sequence Functions}, for the @code{cl-substitute}
3770 function, which works on just the top-level elements of a list.)
3772 @defun cl-subst new old tree @t{&key :test :test-not :key}
3773 This function substitutes occurrences of @var{old} with @var{new}
3774 in @var{tree}, a tree of cons cells. It returns a substituted
3775 tree, which will be a copy except that it may share storage with
3776 the argument @var{tree} in parts where no substitutions occurred.
3777 The original @var{tree} is not modified. This function recurses
3778 on, and compares against @var{old}, both @sc{car}s and @sc{cdr}s
3779 of the component cons cells. If @var{old} is itself a cons cell,
3780 then matching cells in the tree are substituted as usual without
3781 recursively substituting in that cell. Comparisons with @var{old}
3782 are done according to the specified test (@code{eql} by default).
3783 The @code{:key} function is applied to the elements of the tree
3784 but not to @var{old}.
3787 @defun cl-nsubst new old tree @t{&key :test :test-not :key}
3788 This function is like @code{cl-subst}, except that it works by
3789 destructive modification (by @code{setcar} or @code{setcdr})
3790 rather than copying.
3794 @findex cl-subst-if-not
3795 @findex cl-nsubst-if
3796 @findex cl-nsubst-if-not
3797 The @code{cl-subst-if}, @code{cl-subst-if-not}, @code{cl-nsubst-if}, and
3798 @code{cl-nsubst-if-not} functions are defined similarly.
3800 @defun cl-sublis alist tree @t{&key :test :test-not :key}
3801 This function is like @code{cl-subst}, except that it takes an
3802 association list @var{alist} of @var{old}-@var{new} pairs.
3803 Each element of the tree (after applying the @code{:key}
3804 function, if any), is compared with the @sc{car}s of
3805 @var{alist}; if it matches, it is replaced by the corresponding
3809 @defun cl-nsublis alist tree @t{&key :test :test-not :key}
3810 This is a destructive version of @code{cl-sublis}.
3814 @section Lists as Sets
3817 These functions perform operations on lists which represent sets
3820 @defun cl-member item list @t{&key :test :test-not :key}
3821 This function searches @var{list} for an element matching @var{item}.
3822 If a match is found, it returns the cons cell whose @sc{car} was
3823 the matching element. Otherwise, it returns @code{nil}. Elements
3824 are compared by @code{eql} by default; you can use the @code{:test},
3825 @code{:test-not}, and @code{:key} arguments to modify this behavior.
3828 The standard Emacs lisp function @code{member} uses @code{equal} for
3829 comparisons; it is equivalent to @code{(cl-member @var{item} @var{list}
3833 @findex cl-member-if
3834 @findex cl-member-if-not
3835 The @code{cl-member-if} and @code{cl-member-if-not} functions
3836 analogously search for elements which satisfy a given predicate.
3838 @defun cl-tailp sublist list
3839 This function returns @code{t} if @var{sublist} is a sublist of
3840 @var{list}, i.e., if @var{sublist} is @code{eql} to @var{list} or to
3841 any of its @sc{cdr}s.
3844 @defun cl-adjoin item list @t{&key :test :test-not :key}
3845 This function conses @var{item} onto the front of @var{list},
3846 like @code{(cons @var{item} @var{list})}, but only if @var{item}
3847 is not already present on the list (as determined by @code{cl-member}).
3848 If a @code{:key} argument is specified, it is applied to
3849 @var{item} as well as to the elements of @var{list} during
3850 the search, on the reasoning that @var{item} is ``about'' to
3851 become part of the list.
3854 @defun cl-union list1 list2 @t{&key :test :test-not :key}
3855 This function combines two lists which represent sets of items,
3856 returning a list that represents the union of those two sets.
3857 The result list will contain all items which appear in @var{list1}
3858 or @var{list2}, and no others. If an item appears in both
3859 @var{list1} and @var{list2} it will be copied only once. If
3860 an item is duplicated in @var{list1} or @var{list2}, it is
3861 undefined whether or not that duplication will survive in the
3862 result list. The order of elements in the result list is also
3866 @defun cl-nunion list1 list2 @t{&key :test :test-not :key}
3867 This is a destructive version of @code{cl-union}; rather than copying,
3868 it tries to reuse the storage of the argument lists if possible.
3871 @defun cl-intersection list1 list2 @t{&key :test :test-not :key}
3872 This function computes the intersection of the sets represented
3873 by @var{list1} and @var{list2}. It returns the list of items
3874 which appear in both @var{list1} and @var{list2}.
3877 @defun cl-nintersection list1 list2 @t{&key :test :test-not :key}
3878 This is a destructive version of @code{cl-intersection}. It
3879 tries to reuse storage of @var{list1} rather than copying.
3880 It does @emph{not} reuse the storage of @var{list2}.
3883 @defun cl-set-difference list1 list2 @t{&key :test :test-not :key}
3884 This function computes the ``set difference'' of @var{list1}
3885 and @var{list2}, i.e., the set of elements that appear in
3886 @var{list1} but @emph{not} in @var{list2}.
3889 @defun cl-nset-difference list1 list2 @t{&key :test :test-not :key}
3890 This is a destructive @code{cl-set-difference}, which will try
3891 to reuse @var{list1} if possible.
3894 @defun cl-set-exclusive-or list1 list2 @t{&key :test :test-not :key}
3895 This function computes the ``set exclusive or'' of @var{list1}
3896 and @var{list2}, i.e., the set of elements that appear in
3897 exactly one of @var{list1} and @var{list2}.
3900 @defun cl-nset-exclusive-or list1 list2 @t{&key :test :test-not :key}
3901 This is a destructive @code{cl-set-exclusive-or}, which will try
3902 to reuse @var{list1} and @var{list2} if possible.
3905 @defun cl-subsetp list1 list2 @t{&key :test :test-not :key}
3906 This function checks whether @var{list1} represents a subset
3907 of @var{list2}, i.e., whether every element of @var{list1}
3908 also appears in @var{list2}.
3911 @node Association Lists
3912 @section Association Lists
3915 An @dfn{association list} is a list representing a mapping from
3916 one set of values to another; any list whose elements are cons
3917 cells is an association list.
3919 @defun cl-assoc item a-list @t{&key :test :test-not :key}
3920 This function searches the association list @var{a-list} for an
3921 element whose @sc{car} matches (in the sense of @code{:test},
3922 @code{:test-not}, and @code{:key}, or by comparison with @code{eql})
3923 a given @var{item}. It returns the matching element, if any,
3924 otherwise @code{nil}. It ignores elements of @var{a-list} which
3925 are not cons cells. (This corresponds to the behavior of
3926 @code{assq} and @code{assoc} in Emacs Lisp; Common Lisp's
3927 @code{assoc} ignores @code{nil}s but considers any other non-cons
3928 elements of @var{a-list} to be an error.)
3931 @defun cl-rassoc item a-list @t{&key :test :test-not :key}
3932 This function searches for an element whose @sc{cdr} matches
3933 @var{item}. If @var{a-list} represents a mapping, this applies
3934 the inverse of the mapping to @var{item}.
3938 @findex cl-assoc-if-not
3939 @findex cl-rassoc-if
3940 @findex cl-rassoc-if-not
3941 The @code{cl-assoc-if}, @code{cl-assoc-if-not}, @code{cl-rassoc-if},
3942 and @code{cl-rassoc-if-not} functions are defined similarly.
3944 Two simple functions for constructing association lists are:
3946 @defun cl-acons key value alist
3947 This is equivalent to @code{(cons (cons @var{key} @var{value}) @var{alist})}.
3950 @defun cl-pairlis keys values &optional alist
3951 This is equivalent to @code{(nconc (cl-mapcar 'cons @var{keys} @var{values})
3959 The Common Lisp @dfn{structure} mechanism provides a general way
3960 to define data types similar to C's @code{struct} types. A
3961 structure is a Lisp object containing some number of @dfn{slots},
3962 each of which can hold any Lisp data object. Functions are
3963 provided for accessing and setting the slots, creating or copying
3964 structure objects, and recognizing objects of a particular structure
3967 In true Common Lisp, each structure type is a new type distinct
3968 from all existing Lisp types. Since the underlying Emacs Lisp
3969 system provides no way to create new distinct types, this package
3970 implements structures as vectors (or lists upon request) with a
3971 special ``tag'' symbol to identify them.
3973 @defmac cl-defstruct name slots@dots{}
3974 The @code{cl-defstruct} form defines a new structure type called
3975 @var{name}, with the specified @var{slots}. (The @var{slots}
3976 may begin with a string which documents the structure type.)
3977 In the simplest case, @var{name} and each of the @var{slots}
3978 are symbols. For example,
3981 (cl-defstruct person name age sex)
3985 defines a struct type called @code{person} which contains three
3986 slots. Given a @code{person} object @var{p}, you can access those
3987 slots by calling @code{(person-name @var{p})}, @code{(person-age @var{p})},
3988 and @code{(person-sex @var{p})}. You can also change these slots by
3989 using @code{setf} on any of these place forms:
3992 (cl-incf (person-age birthday-boy))
3995 You can create a new @code{person} by calling @code{make-person},
3996 which takes keyword arguments @code{:name}, @code{:age}, and
3997 @code{:sex} to specify the initial values of these slots in the
3998 new object. (Omitting any of these arguments leaves the corresponding
3999 slot ``undefined'', according to the Common Lisp standard; in Emacs
4000 Lisp, such uninitialized slots are filled with @code{nil}.)
4002 Given a @code{person}, @code{(copy-person @var{p})} makes a new
4003 object of the same type whose slots are @code{eq} to those of @var{p}.
4005 Given any Lisp object @var{x}, @code{(person-p @var{x})} returns
4006 true if @var{x} looks like a @code{person}, false otherwise. (Again,
4007 in Common Lisp this predicate would be exact; in Emacs Lisp the
4008 best it can do is verify that @var{x} is a vector of the correct
4009 length which starts with the correct tag symbol.)
4011 Accessors like @code{person-name} normally check their arguments
4012 (effectively using @code{person-p}) and signal an error if the
4013 argument is the wrong type. This check is affected by
4014 @code{(optimize (safety @dots{}))} declarations. Safety level 1,
4015 the default, uses a somewhat optimized check that will detect all
4016 incorrect arguments, but may use an uninformative error message
4017 (e.g., ``expected a vector'' instead of ``expected a @code{person}'').
4018 Safety level 0 omits all checks except as provided by the underlying
4019 @code{aref} call; safety levels 2 and 3 do rigorous checking that will
4020 always print a descriptive error message for incorrect inputs.
4021 @xref{Declarations}.
4024 (setq dave (make-person :name "Dave" :sex 'male))
4025 @result{} [cl-struct-person "Dave" nil male]
4026 (setq other (copy-person dave))
4027 @result{} [cl-struct-person "Dave" nil male]
4030 (eq (person-name dave) (person-name other))
4034 (person-p [1 2 3 4])
4038 (person-p '[cl-struct-person counterfeit person object])
4042 In general, @var{name} is either a name symbol or a list of a name
4043 symbol followed by any number of @dfn{struct options}; each @var{slot}
4044 is either a slot symbol or a list of the form @samp{(@var{slot-name}
4045 @var{default-value} @var{slot-options}@dots{})}. The @var{default-value}
4046 is a Lisp form which is evaluated any time an instance of the
4047 structure type is created without specifying that slot's value.
4049 Common Lisp defines several slot options, but the only one
4050 implemented in this package is @code{:read-only}. A non-@code{nil}
4051 value for this option means the slot should not be @code{setf}-able;
4052 the slot's value is determined when the object is created and does
4053 not change afterward.
4056 (cl-defstruct person
4057 (name nil :read-only t)
4062 Any slot options other than @code{:read-only} are ignored.
4064 For obscure historical reasons, structure options take a different
4065 form than slot options. A structure option is either a keyword
4066 symbol, or a list beginning with a keyword symbol possibly followed
4067 by arguments. (By contrast, slot options are key-value pairs not
4071 (cl-defstruct (person (:constructor create-person)
4077 The following structure options are recognized.
4081 The argument is a symbol whose print name is used as the prefix for
4082 the names of slot accessor functions. The default is the name of
4083 the struct type followed by a hyphen. The option @code{(:conc-name p-)}
4084 would change this prefix to @code{p-}. Specifying @code{nil} as an
4085 argument means no prefix, so that the slot names themselves are used
4086 to name the accessor functions.
4089 In the simple case, this option takes one argument which is an
4090 alternate name to use for the constructor function. The default
4091 is @code{make-@var{name}}, e.g., @code{make-person}. The above
4092 example changes this to @code{create-person}. Specifying @code{nil}
4093 as an argument means that no standard constructor should be
4096 In the full form of this option, the constructor name is followed
4097 by an arbitrary argument list. @xref{Program Structure}, for a
4098 description of the format of Common Lisp argument lists. All
4099 options, such as @code{&rest} and @code{&key}, are supported.
4100 The argument names should match the slot names; each slot is
4101 initialized from the corresponding argument. Slots whose names
4102 do not appear in the argument list are initialized based on the
4103 @var{default-value} in their slot descriptor. Also, @code{&optional}
4104 and @code{&key} arguments which don't specify defaults take their
4105 defaults from the slot descriptor. It is valid to include arguments
4106 which don't correspond to slot names; these are useful if they are
4107 referred to in the defaults for optional, keyword, or @code{&aux}
4108 arguments which @emph{do} correspond to slots.
4110 You can specify any number of full-format @code{:constructor}
4111 options on a structure. The default constructor is still generated
4112 as well unless you disable it with a simple-format @code{:constructor}
4118 (:constructor nil) ; no default constructor
4119 (:constructor new-person
4120 (name sex &optional (age 0)))
4121 (:constructor new-hound (&key (name "Rover")
4123 &aux (age (* 7 dog-years))
4128 The first constructor here takes its arguments positionally rather
4129 than by keyword. (In official Common Lisp terminology, constructors
4130 that work By Order of Arguments instead of by keyword are called
4131 ``BOA constructors''. No, I'm not making this up.) For example,
4132 @code{(new-person "Jane" 'female)} generates a person whose slots
4133 are @code{"Jane"}, 0, and @code{female}, respectively.
4135 The second constructor takes two keyword arguments, @code{:name},
4136 which initializes the @code{name} slot and defaults to @code{"Rover"},
4137 and @code{:dog-years}, which does not itself correspond to a slot
4138 but which is used to initialize the @code{age} slot. The @code{sex}
4139 slot is forced to the symbol @code{canine} with no syntax for
4143 The argument is an alternate name for the copier function for
4144 this type. The default is @code{copy-@var{name}}. @code{nil}
4145 means not to generate a copier function. (In this implementation,
4146 all copier functions are simply synonyms for @code{copy-sequence}.)
4149 The argument is an alternate name for the predicate which recognizes
4150 objects of this type. The default is @code{@var{name}-p}. @code{nil}
4151 means not to generate a predicate function. (If the @code{:type}
4152 option is used without the @code{:named} option, no predicate is
4155 In true Common Lisp, @code{typep} is always able to recognize a
4156 structure object even if @code{:predicate} was used. In this
4157 package, @code{cl-typep} simply looks for a function called
4158 @code{@var{typename}-p}, so it will work for structure types
4159 only if they used the default predicate name.
4162 This option implements a very limited form of C++-style inheritance.
4163 The argument is the name of another structure type previously
4164 created with @code{cl-defstruct}. The effect is to cause the new
4165 structure type to inherit all of the included structure's slots
4166 (plus, of course, any new slots described by this struct's slot
4167 descriptors). The new structure is considered a ``specialization''
4168 of the included one. In fact, the predicate and slot accessors
4169 for the included type will also accept objects of the new type.
4171 If there are extra arguments to the @code{:include} option after
4172 the included-structure name, these options are treated as replacement
4173 slot descriptors for slots in the included structure, possibly with
4174 modified default values. Borrowing an example from Steele:
4177 (cl-defstruct person name (age 0) sex)
4179 (cl-defstruct (astronaut (:include person (age 45)))
4181 (favorite-beverage 'tang))
4184 (setq joe (make-person :name "Joe"))
4185 @result{} [cl-struct-person "Joe" 0 nil]
4186 (setq buzz (make-astronaut :name "Buzz"))
4187 @result{} [cl-struct-astronaut "Buzz" 45 nil nil tang]
4189 (list (person-p joe) (person-p buzz))
4191 (list (astronaut-p joe) (astronaut-p buzz))
4196 (astronaut-name joe)
4197 @result{} error: "astronaut-name accessing a non-astronaut"
4200 Thus, if @code{astronaut} is a specialization of @code{person},
4201 then every @code{astronaut} is also a @code{person} (but not the
4202 other way around). Every @code{astronaut} includes all the slots
4203 of a @code{person}, plus extra slots that are specific to
4204 astronauts. Operations that work on people (like @code{person-name})
4205 work on astronauts just like other people.
4207 @item :print-function
4208 In full Common Lisp, this option allows you to specify a function
4209 which is called to print an instance of the structure type. The
4210 Emacs Lisp system offers no hooks into the Lisp printer which would
4211 allow for such a feature, so this package simply ignores
4212 @code{:print-function}.
4215 The argument should be one of the symbols @code{vector} or @code{list}.
4216 This tells which underlying Lisp data type should be used to implement
4217 the new structure type. Vectors are used by default, but
4218 @code{(:type list)} will cause structure objects to be stored as
4221 The vector representation for structure objects has the advantage
4222 that all structure slots can be accessed quickly, although creating
4223 vectors is a bit slower in Emacs Lisp. Lists are easier to create,
4224 but take a relatively long time accessing the later slots.
4227 This option, which takes no arguments, causes a characteristic ``tag''
4228 symbol to be stored at the front of the structure object. Using
4229 @code{:type} without also using @code{:named} will result in a
4230 structure type stored as plain vectors or lists with no identifying
4233 The default, if you don't specify @code{:type} explicitly, is to
4234 use named vectors. Therefore, @code{:named} is only useful in
4235 conjunction with @code{:type}.
4238 (cl-defstruct (person1) name age sex)
4239 (cl-defstruct (person2 (:type list) :named) name age sex)
4240 (cl-defstruct (person3 (:type list)) name age sex)
4242 (setq p1 (make-person1))
4243 @result{} [cl-struct-person1 nil nil nil]
4244 (setq p2 (make-person2))
4245 @result{} (person2 nil nil nil)
4246 (setq p3 (make-person3))
4247 @result{} (nil nil nil)
4254 @result{} error: function person3-p undefined
4257 Since unnamed structures don't have tags, @code{cl-defstruct} is not
4258 able to make a useful predicate for recognizing them. Also,
4259 accessors like @code{person3-name} will be generated but they
4260 will not be able to do any type checking. The @code{person3-name}
4261 function, for example, will simply be a synonym for @code{car} in
4262 this case. By contrast, @code{person2-name} is able to verify
4263 that its argument is indeed a @code{person2} object before
4266 @item :initial-offset
4267 The argument must be a nonnegative integer. It specifies a
4268 number of slots to be left ``empty'' at the front of the
4269 structure. If the structure is named, the tag appears at the
4270 specified position in the list or vector; otherwise, the first
4271 slot appears at that position. Earlier positions are filled
4272 with @code{nil} by the constructors and ignored otherwise. If
4273 the type @code{:include}s another type, then @code{:initial-offset}
4274 specifies a number of slots to be skipped between the last slot
4275 of the included type and the first new slot.
4279 Except as noted, the @code{cl-defstruct} facility of this package is
4280 entirely compatible with that of Common Lisp.
4283 @chapter Assertions and Errors
4286 This section describes two macros that test @dfn{assertions}, i.e.,
4287 conditions which must be true if the program is operating correctly.
4288 Assertions never add to the behavior of a Lisp program; they simply
4289 make ``sanity checks'' to make sure everything is as it should be.
4291 If the optimization property @code{speed} has been set to 3, and
4292 @code{safety} is less than 3, then the byte-compiler will optimize
4293 away the following assertions. Because assertions might be optimized
4294 away, it is a bad idea for them to include side-effects.
4296 @defmac cl-assert test-form [show-args string args@dots{}]
4297 This form verifies that @var{test-form} is true (i.e., evaluates to
4298 a non-@code{nil} value). If so, it returns @code{nil}. If the test
4299 is not satisfied, @code{cl-assert} signals an error.
4301 A default error message will be supplied which includes @var{test-form}.
4302 You can specify a different error message by including a @var{string}
4303 argument plus optional extra arguments. Those arguments are simply
4304 passed to @code{error} to signal the error.
4306 If the optional second argument @var{show-args} is @code{t} instead
4307 of @code{nil}, then the error message (with or without @var{string})
4308 will also include all non-constant arguments of the top-level
4309 @var{form}. For example:
4312 (cl-assert (> x 10) t "x is too small: %d")
4315 This usage of @var{show-args} is an extension to Common Lisp. In
4316 true Common Lisp, the second argument gives a list of @var{places}
4317 which can be @code{setf}'d by the user before continuing from the
4318 error. Since Emacs Lisp does not support continuable errors, it
4319 makes no sense to specify @var{places}.
4322 @defmac cl-check-type form type [string]
4323 This form verifies that @var{form} evaluates to a value of type
4324 @var{type}. If so, it returns @code{nil}. If not, @code{cl-check-type}
4325 signals a @code{wrong-type-argument} error. The default error message
4326 lists the erroneous value along with @var{type} and @var{form}
4327 themselves. If @var{string} is specified, it is included in the
4328 error message in place of @var{type}. For example:
4331 (cl-check-type x (integer 1 *) "a positive integer")
4334 @xref{Type Predicates}, for a description of the type specifiers
4335 that may be used for @var{type}.
4337 Note that in Common Lisp, the first argument to @code{check-type}
4338 must be a @var{place} suitable for use by @code{setf}, because
4339 @code{check-type} signals a continuable error that allows the
4340 user to modify @var{place}.
4343 @node Efficiency Concerns
4344 @appendix Efficiency Concerns
4349 Many of the advanced features of this package, such as @code{cl-defun},
4350 @code{cl-loop}, etc., are implemented as Lisp macros. In
4351 byte-compiled code, these complex notations will be expanded into
4352 equivalent Lisp code which is simple and efficient. For example,
4360 is expanded at compile-time to the Lisp form
4367 which is the most efficient ways of doing this operation
4368 in Lisp. Thus, there is no performance penalty for using the more
4369 readable @code{cl-incf} form in your compiled code.
4371 @emph{Interpreted} code, on the other hand, must expand these macros
4372 every time they are executed. For this reason it is strongly
4373 recommended that code making heavy use of macros be compiled.
4374 A loop using @code{cl-incf} a hundred times will execute considerably
4375 faster if compiled, and will also garbage-collect less because the
4376 macro expansion will not have to be generated, used, and thrown away a
4379 You can find out how a macro expands by using the
4380 @code{cl-prettyexpand} function.
4382 @defun cl-prettyexpand form &optional full
4383 This function takes a single Lisp form as an argument and inserts
4384 a nicely formatted copy of it in the current buffer (which must be
4385 in Lisp mode so that indentation works properly). It also expands
4386 all Lisp macros which appear in the form. The easiest way to use
4387 this function is to go to the @file{*scratch*} buffer and type, say,
4390 (cl-prettyexpand '(cl-loop for x below 10 collect x))
4394 and type @kbd{C-x C-e} immediately after the closing parenthesis;
4402 (setq G1004 (cons x G1004))
4408 will be inserted into the buffer. (The @code{cl-block} macro is
4409 expanded differently in the interpreter and compiler, so
4410 @code{cl-prettyexpand} just leaves it alone. The temporary
4411 variable @code{G1004} was created by @code{cl-gensym}.)
4413 If the optional argument @var{full} is true, then @emph{all}
4414 macros are expanded, including @code{cl-block}, @code{cl-eval-when},
4415 and compiler macros. Expansion is done as if @var{form} were
4416 a top-level form in a file being compiled. For example,
4419 (cl-prettyexpand '(cl-pushnew 'x list))
4420 @print{} (setq list (cl-adjoin 'x list))
4421 (cl-prettyexpand '(cl-pushnew 'x list) t)
4422 @print{} (setq list (if (memq 'x list) list (cons 'x list)))
4423 (cl-prettyexpand '(caddr (cl-member 'a list)) t)
4424 @print{} (car (cdr (cdr (memq 'a list))))
4427 Note that @code{cl-adjoin}, @code{cl-caddr}, and @code{cl-member} all
4428 have built-in compiler macros to optimize them in common cases.
4436 @appendixsec Error Checking
4439 Common Lisp compliance has in general not been sacrificed for the
4440 sake of efficiency. A few exceptions have been made for cases
4441 where substantial gains were possible at the expense of marginal
4444 The Common Lisp standard (as embodied in Steele's book) uses the
4445 phrase ``it is an error if'' to indicate a situation which is not
4446 supposed to arise in complying programs; implementations are strongly
4447 encouraged but not required to signal an error in these situations.
4448 This package sometimes omits such error checking in the interest of
4449 compactness and efficiency. For example, @code{cl-do} variable
4450 specifiers are supposed to be lists of one, two, or three forms;
4451 extra forms are ignored by this package rather than signaling a
4452 syntax error. The @code{cl-endp} function is simply a synonym for
4453 @code{null} in this package. Functions taking keyword arguments
4454 will accept an odd number of arguments, treating the trailing
4455 keyword as if it were followed by the value @code{nil}.
4457 Argument lists (as processed by @code{cl-defun} and friends)
4458 @emph{are} checked rigorously except for the minor point just
4459 mentioned; in particular, keyword arguments are checked for
4460 validity, and @code{&allow-other-keys} and @code{:allow-other-keys}
4461 are fully implemented. Keyword validity checking is slightly
4462 time consuming (though not too bad in byte-compiled code);
4463 you can use @code{&allow-other-keys} to omit this check. Functions
4464 defined in this package such as @code{cl-find} and @code{cl-member}
4465 do check their keyword arguments for validity.
4472 @appendixsec Optimizing Compiler
4475 Use of the optimizing Emacs compiler is highly recommended; many of the Common
4477 code which can be improved by optimization. In particular,
4478 @code{cl-block}s (whether explicit or implicit in constructs like
4479 @code{cl-defun} and @code{cl-loop}) carry a fair run-time penalty; the
4480 optimizing compiler removes @code{cl-block}s which are not actually
4481 referenced by @code{cl-return} or @code{cl-return-from} inside the block.
4483 @node Common Lisp Compatibility
4484 @appendix Common Lisp Compatibility
4487 Following is a list of all known incompatibilities between this
4488 package and Common Lisp as documented in Steele (2nd edition).
4490 The word @code{cl-defun} is required instead of @code{defun} in order
4491 to use extended Common Lisp argument lists in a function. Likewise,
4492 @code{cl-defmacro} and @code{cl-function} are versions of those forms
4493 which understand full-featured argument lists. The @code{&whole}
4494 keyword does not work in @code{defmacro} argument lists (except
4495 inside recursive argument lists).
4497 The @code{equal} predicate does not distinguish
4498 between IEEE floating-point plus and minus zero. The @code{cl-equalp}
4499 predicate has several differences with Common Lisp; @pxref{Predicates}.
4501 @c FIXME no longer provided by cl.
4502 The @code{setf} mechanism is entirely compatible, except that
4503 setf-methods return a list of five values rather than five
4504 values directly. Also, the new ``@code{setf} function'' concept
4505 (typified by @code{(defun (setf foo) @dots{})}) is not implemented.
4507 The @code{cl-do-all-symbols} form is the same as @code{cl-do-symbols}
4508 with no @var{obarray} argument. In Common Lisp, this form would
4509 iterate over all symbols in all packages. Since Emacs obarrays
4510 are not a first-class package mechanism, there is no way for
4511 @code{cl-do-all-symbols} to locate any but the default obarray.
4513 The @code{cl-loop} macro is complete except that @code{loop-finish}
4514 and type specifiers are unimplemented.
4516 The multiple-value return facility treats lists as multiple
4517 values, since Emacs Lisp cannot support multiple return values
4518 directly. The macros will be compatible with Common Lisp if
4519 @code{cl-values} or @code{cl-values-list} is always used to return to
4520 a @code{cl-multiple-value-bind} or other multiple-value receiver;
4521 if @code{cl-values} is used without @code{cl-multiple-value-@dots{}}
4522 or vice-versa the effect will be different from Common Lisp.
4524 Many Common Lisp declarations are ignored, and others match
4525 the Common Lisp standard in concept but not in detail. For
4526 example, local @code{special} declarations, which are purely
4527 advisory in Emacs Lisp, do not rigorously obey the scoping rules
4528 set down in Steele's book.
4530 The variable @code{cl--gensym-counter} starts out with a pseudo-random
4531 value rather than with zero. This is to cope with the fact that
4532 generated symbols become interned when they are written to and
4533 loaded back from a file.
4535 The @code{cl-defstruct} facility is compatible, except that structures
4536 are of type @code{:type vector :named} by default rather than some
4537 special, distinct type. Also, the @code{:type} slot option is ignored.
4539 The second argument of @code{cl-check-type} is treated differently.
4541 @node Porting Common Lisp
4542 @appendix Porting Common Lisp
4545 This package is meant to be used as an extension to Emacs Lisp,
4546 not as an Emacs implementation of true Common Lisp. Some of the
4547 remaining differences between Emacs Lisp and Common Lisp make it
4548 difficult to port large Common Lisp applications to Emacs. For
4549 one, some of the features in this package are not fully compliant
4550 with ANSI or Steele; @pxref{Common Lisp Compatibility}. But there
4551 are also quite a few features that this package does not provide
4552 at all. Here are some major omissions that you will want to watch out
4553 for when bringing Common Lisp code into Emacs.
4557 Case-insensitivity. Symbols in Common Lisp are case-insensitive
4558 by default. Some programs refer to a function or variable as
4559 @code{foo} in one place and @code{Foo} or @code{FOO} in another.
4560 Emacs Lisp will treat these as three distinct symbols.
4562 Some Common Lisp code is written entirely in upper case. While Emacs
4563 is happy to let the program's own functions and variables use
4564 this convention, calls to Lisp builtins like @code{if} and
4565 @code{defun} will have to be changed to lower case.
4568 Lexical scoping. In Common Lisp, function arguments and @code{let}
4569 bindings apply only to references physically within their bodies (or
4570 within macro expansions in their bodies). Traditionally, Emacs Lisp
4571 uses @dfn{dynamic scoping} wherein a binding to a variable is visible
4572 even inside functions called from the body.
4573 @xref{Dynamic Binding,,,elisp,GNU Emacs Lisp Reference Manual}.
4574 Lexical binding is available since Emacs 24.1, so be sure to set
4575 @code{lexical-binding} to @code{t} if you need to emulate this aspect
4576 of Common Lisp. @xref{Lexical Binding,,,elisp,GNU Emacs Lisp Reference Manual}.
4578 Here is an example of a Common Lisp code fragment that would fail in
4579 Emacs Lisp if @code{lexical-binding} were set to @code{nil}:
4582 (defun map-odd-elements (func list)
4584 for flag = t then (not flag)
4585 collect (if flag x (funcall func x))))
4587 (defun add-odd-elements (list x)
4588 (map-odd-elements (lambda (a) (+ a x)) list))
4592 With lexical binding, the two functions' usages of @code{x} are
4593 completely independent. With dynamic binding, the binding to @code{x}
4594 made by @code{add-odd-elements} will have been hidden by the binding
4595 in @code{map-odd-elements} by the time the @code{(+ a x)} function is
4598 Internally, this package uses lexical binding so that such problems do
4599 not occur. @xref{Obsolete Lexical Binding}, for a description of the obsolete
4600 @code{lexical-let} form that emulates a Common Lisp-style lexical
4601 binding when dynamic binding is in use.
4604 Reader macros. Common Lisp includes a second type of macro that
4605 works at the level of individual characters. For example, Common
4606 Lisp implements the quote notation by a reader macro called @code{'},
4607 whereas Emacs Lisp's parser just treats quote as a special case.
4608 Some Lisp packages use reader macros to create special syntaxes
4609 for themselves, which the Emacs parser is incapable of reading.
4612 Other syntactic features. Common Lisp provides a number of
4613 notations beginning with @code{#} that the Emacs Lisp parser
4614 won't understand. For example, @samp{#| @dots{} |#} is an
4615 alternate comment notation, and @samp{#+lucid (foo)} tells
4616 the parser to ignore the @code{(foo)} except in Lucid Common
4620 Packages. In Common Lisp, symbols are divided into @dfn{packages}.
4621 Symbols that are Lisp built-ins are typically stored in one package;
4622 symbols that are vendor extensions are put in another, and each
4623 application program would have a package for its own symbols.
4624 Certain symbols are ``exported'' by a package and others are
4625 internal; certain packages ``use'' or import the exported symbols
4626 of other packages. To access symbols that would not normally be
4627 visible due to this importing and exporting, Common Lisp provides
4628 a syntax like @code{package:symbol} or @code{package::symbol}.
4630 Emacs Lisp has a single namespace for all interned symbols, and
4631 then uses a naming convention of putting a prefix like @code{cl-}
4632 in front of the name. Some Emacs packages adopt the Common Lisp-like
4633 convention of using @code{cl:} or @code{cl::} as the prefix.
4634 However, the Emacs parser does not understand colons and just
4635 treats them as part of the symbol name. Thus, while @code{mapcar}
4636 and @code{lisp:mapcar} may refer to the same symbol in Common
4637 Lisp, they are totally distinct in Emacs Lisp. Common Lisp
4638 programs which refer to a symbol by the full name sometimes
4639 and the short name other times will not port cleanly to Emacs.
4641 Emacs Lisp does have a concept of ``obarrays'', which are
4642 package-like collections of symbols, but this feature is not
4643 strong enough to be used as a true package mechanism.
4646 The @code{format} function is quite different between Common
4647 Lisp and Emacs Lisp. It takes an additional ``destination''
4648 argument before the format string. A destination of @code{nil}
4649 means to format to a string as in Emacs Lisp; a destination
4650 of @code{t} means to write to the terminal (similar to
4651 @code{message} in Emacs). Also, format control strings are
4652 utterly different; @code{~} is used instead of @code{%} to
4653 introduce format codes, and the set of available codes is
4654 much richer. There are no notations like @code{\n} for
4655 string literals; instead, @code{format} is used with the
4656 ``newline'' format code, @code{~%}. More advanced formatting
4657 codes provide such features as paragraph filling, case
4658 conversion, and even loops and conditionals.
4660 While it would have been possible to implement most of Common
4661 Lisp @code{format} in this package (under the name @code{cl-format},
4662 of course), it was not deemed worthwhile. It would have required
4663 a huge amount of code to implement even a decent subset of
4664 @code{format}, yet the functionality it would provide over
4665 Emacs Lisp's @code{format} would rarely be useful.
4668 Vector constants use square brackets in Emacs Lisp, but
4669 @code{#(a b c)} notation in Common Lisp. To further complicate
4670 matters, Emacs has its own @code{#(} notation for
4671 something entirely different---strings with properties.
4674 Characters are distinct from integers in Common Lisp. The notation
4675 for character constants is also different: @code{#\A} in Common Lisp
4676 where Emacs Lisp uses @code{?A}. Also, @code{string=} and
4677 @code{string-equal} are synonyms in Emacs Lisp, whereas the latter is
4678 case-insensitive in Common Lisp.
4681 Data types. Some Common Lisp data types do not exist in Emacs
4682 Lisp. Rational numbers and complex numbers are not present,
4683 nor are large integers (all integers are ``fixnums''). All
4684 arrays are one-dimensional. There are no readtables or pathnames;
4685 streams are a set of existing data types rather than a new data
4686 type of their own. Hash tables, random-states, structures, and
4687 packages (obarrays) are built from Lisp vectors or lists rather
4688 than being distinct types.
4691 The Common Lisp Object System (CLOS) is not implemented,
4692 nor is the Common Lisp Condition System. However, the EIEIO package
4693 (@pxref{Top, , Introduction, eieio, EIEIO}) does implement some
4697 Common Lisp features that are completely redundant with Emacs
4698 Lisp features of a different name generally have not been
4699 implemented. For example, Common Lisp writes @code{defconstant}
4700 where Emacs Lisp uses @code{defconst}. Similarly, @code{make-list}
4701 takes its arguments in different ways in the two Lisps but does
4702 exactly the same thing, so this package has not bothered to
4703 implement a Common Lisp-style @code{make-list}.
4706 A few more notable Common Lisp features not included in this
4707 package: @code{compiler-let}, @code{tagbody}, @code{prog},
4708 @code{ldb/dpb}, @code{parse-integer}, @code{cerror}.
4711 Recursion. While recursion works in Emacs Lisp just like it
4712 does in Common Lisp, various details of the Emacs Lisp system
4713 and compiler make recursion much less efficient than it is in
4714 most Lisps. Some schools of thought prefer to use recursion
4715 in Lisp over other techniques; they would sum a list of
4716 numbers using something like
4719 (defun sum-list (list)
4721 (+ (car list) (sum-list (cdr list)))
4726 where a more iteratively-minded programmer might write one of
4730 (let ((total 0)) (dolist (x my-list) (incf total x)) total)
4731 (loop for x in my-list sum x)
4734 While this would be mainly a stylistic choice in most Common Lisps,
4735 in Emacs Lisp you should be aware that the iterative forms are
4736 much faster than recursion. Also, Lisp programmers will want to
4737 note that the current Emacs Lisp compiler does not optimize tail
4741 @node Obsolete Features
4742 @appendix Obsolete Features
4744 This section describes some features of the package that are obsolete
4745 and should not be used in new code. They are either only provided by
4746 the old @file{cl.el} entry point, not by the newer @file{cl-lib.el};
4747 or where versions with a @samp{cl-} prefix do exist they do not behave
4748 in exactly the same way.
4751 * Obsolete Lexical Binding:: An approximation of lexical binding.
4752 * Obsolete Macros:: Obsolete macros.
4753 * Obsolete Setf Customization:: Obsolete ways to customize setf.
4756 @node Obsolete Lexical Binding
4757 @appendixsec Obsolete Lexical Binding
4759 The following macros are extensions to Common Lisp, where all bindings
4760 are lexical unless declared otherwise. These features are likewise
4761 obsolete since the introduction of true lexical binding in Emacs 24.1.
4763 @defmac lexical-let (bindings@dots{}) forms@dots{}
4764 This form is exactly like @code{let} except that the bindings it
4765 establishes are purely lexical.
4768 @c FIXME remove this and refer to elisp manual.
4769 @c Maybe merge some stuff from here to there?
4771 Lexical bindings are similar to local variables in a language like C:
4772 Only the code physically within the body of the @code{lexical-let}
4773 (after macro expansion) may refer to the bound variables.
4777 (defun foo (b) (+ a b))
4778 (let ((a 2)) (foo a))
4780 (lexical-let ((a 2)) (foo a))
4785 In this example, a regular @code{let} binding of @code{a} actually
4786 makes a temporary change to the global variable @code{a}, so @code{foo}
4787 is able to see the binding of @code{a} to 2. But @code{lexical-let}
4788 actually creates a distinct local variable @code{a} for use within its
4789 body, without any effect on the global variable of the same name.
4791 The most important use of lexical bindings is to create @dfn{closures}.
4792 A closure is a function object that refers to an outside lexical
4793 variable (@pxref{Closures,,,elisp,GNU Emacs Lisp Reference Manual}).
4797 (defun make-adder (n)
4798 (lexical-let ((n n))
4799 (function (lambda (m) (+ n m)))))
4800 (setq add17 (make-adder 17))
4806 The call @code{(make-adder 17)} returns a function object which adds
4807 17 to its argument. If @code{let} had been used instead of
4808 @code{lexical-let}, the function object would have referred to the
4809 global @code{n}, which would have been bound to 17 only during the
4810 call to @code{make-adder} itself.
4813 (defun make-counter ()
4814 (lexical-let ((n 0))
4815 (cl-function (lambda (&optional (m 1)) (cl-incf n m)))))
4816 (setq count-1 (make-counter))
4819 (funcall count-1 14)
4821 (setq count-2 (make-counter))
4831 Here we see that each call to @code{make-counter} creates a distinct
4832 local variable @code{n}, which serves as a private counter for the
4833 function object that is returned.
4835 Closed-over lexical variables persist until the last reference to
4836 them goes away, just like all other Lisp objects. For example,
4837 @code{count-2} refers to a function object which refers to an
4838 instance of the variable @code{n}; this is the only reference
4839 to that variable, so after @code{(setq count-2 nil)} the garbage
4840 collector would be able to delete this instance of @code{n}.
4841 Of course, if a @code{lexical-let} does not actually create any
4842 closures, then the lexical variables are free as soon as the
4843 @code{lexical-let} returns.
4845 Many closures are used only during the extent of the bindings they
4846 refer to; these are known as ``downward funargs'' in Lisp parlance.
4847 When a closure is used in this way, regular Emacs Lisp dynamic
4848 bindings suffice and will be more efficient than @code{lexical-let}
4852 (defun add-to-list (x list)
4853 (mapcar (lambda (y) (+ x y))) list)
4854 (add-to-list 7 '(1 2 5))
4859 Since this lambda is only used while @code{x} is still bound,
4860 it is not necessary to make a true closure out of it.
4862 You can use @code{defun} or @code{flet} inside a @code{lexical-let}
4863 to create a named closure. If several closures are created in the
4864 body of a single @code{lexical-let}, they all close over the same
4865 instance of the lexical variable.
4867 @defmac lexical-let* (bindings@dots{}) forms@dots{}
4868 This form is just like @code{lexical-let}, except that the bindings
4869 are made sequentially in the manner of @code{let*}.
4872 @node Obsolete Macros
4873 @appendixsec Obsolete Macros
4875 The following macros are obsolete, and are replaced by versions with
4876 a @samp{cl-} prefix that do not behave in exactly the same way.
4877 Consequently, the @file{cl.el} versions are not simply aliases to the
4878 @file{cl-lib.el} versions.
4880 @defmac flet (bindings@dots{}) forms@dots{}
4881 This macro is replaced by @code{cl-flet} (@pxref{Function Bindings}),
4882 which behaves the same way as Common Lisp's @code{flet}.
4883 This @code{flet} takes the same arguments as @code{cl-flet}, but does
4884 not behave in precisely the same way.
4886 While @code{flet} in Common Lisp establishes a lexical function
4887 binding, this @code{flet} makes a dynamic binding (it dates from a
4888 time before Emacs had lexical binding). The result is
4889 that @code{flet} affects indirect calls to a function as well as calls
4890 directly inside the @code{flet} form itself.
4893 Note that many primitives (e.g.@: @code{+}) have special byte-compile
4894 handling. Attempts to redefine such functions using @code{flet} will
4895 fail if byte-compiled.
4897 @c In such cases, use @code{labels} instead.
4900 @defmac labels (bindings@dots{}) forms@dots{}
4901 This macro is replaced by @code{cl-labels} (@pxref{Function Bindings}),
4902 which behaves the same way as Common Lisp's @code{labels}.
4903 This @code{labels} takes the same arguments as @code{cl-labels}, but
4904 does not behave in precisely the same way.
4906 This version of @code{labels} uses the obsolete @code{lexical-let}
4907 form (@pxref{Obsolete Lexical Binding}), rather than the true
4908 lexical binding that @code{cl-labels} uses.
4911 @defmac letf (bindings@dots{}) forms@dots{}
4912 This macro is almost exactly the same as @code{cl-letf}, which
4913 replaces it (@pxref{Modify Macros}). The only difference is in
4914 details that relate to some deprecated usage of @code{symbol-function}
4918 @node Obsolete Setf Customization
4919 @appendixsec Obsolete Ways to Customize Setf
4921 Common Lisp defines three macros, @code{define-modify-macro},
4922 @code{defsetf}, and @code{define-setf-method}, that allow the
4923 user to extend generalized variables in various ways.
4924 In Emacs, these are obsolete, replaced by various features of
4925 @file{gv.el} in Emacs 24.3.
4928 @defmac define-modify-macro name arglist function [doc-string]
4929 This macro defines a ``read-modify-write'' macro similar to
4930 @code{cl-incf} and @code{cl-decf}. The macro @var{name} is defined
4931 to take a @var{place} argument followed by additional arguments
4932 described by @var{arglist}. The call
4935 (@var{name} @var{place} @var{args}@dots{})
4942 (cl-callf @var{func} @var{place} @var{args}@dots{})
4946 which in turn is roughly equivalent to
4949 (setf @var{place} (@var{func} @var{place} @var{args}@dots{}))
4955 (define-modify-macro cl-incf (&optional (n 1)) +)
4956 (define-modify-macro cl-concatf (&rest args) concat)
4959 Note that @code{&key} is not allowed in @var{arglist}, but
4960 @code{&rest} is sufficient to pass keywords on to the function.
4962 Most of the modify macros defined by Common Lisp do not exactly
4963 follow the pattern of @code{define-modify-macro}. For example,
4964 @code{push} takes its arguments in the wrong order, and @code{pop}
4965 is completely irregular. You can define these macros ``by hand''
4966 using @code{get-setf-method}, or consult the source
4967 to see how to use the internal @code{setf} building blocks.
4970 @defmac defsetf access-fn update-fn
4971 This is the simpler of two @code{defsetf} forms. Where
4972 @var{access-fn} is the name of a function which accesses a place,
4973 this declares @var{update-fn} to be the corresponding store
4974 function. From now on,
4977 (setf (@var{access-fn} @var{arg1} @var{arg2} @var{arg3}) @var{value})
4984 (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} @var{value})
4988 The @var{update-fn} is required to be either a true function, or
4989 a macro which evaluates its arguments in a function-like way. Also,
4990 the @var{update-fn} is expected to return @var{value} as its result.
4991 Otherwise, the above expansion would not obey the rules for the way
4992 @code{setf} is supposed to behave.
4994 As a special (non-Common-Lisp) extension, a third argument of @code{t}
4995 to @code{defsetf} says that the @code{update-fn}'s return value is
4996 not suitable, so that the above @code{setf} should be expanded to
5000 (let ((temp @var{value}))
5001 (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} temp)
5005 Some examples of the use of @code{defsetf}, drawn from the standard
5006 suite of setf methods, are:
5009 (defsetf car setcar)
5010 (defsetf symbol-value set)
5011 (defsetf buffer-name rename-buffer t)
5015 @defmac defsetf access-fn arglist (store-var) forms@dots{}
5016 This is the second, more complex, form of @code{defsetf}. It is
5017 rather like @code{defmacro} except for the additional @var{store-var}
5018 argument. The @var{forms} should return a Lisp form which stores
5019 the value of @var{store-var} into the generalized variable formed
5020 by a call to @var{access-fn} with arguments described by @var{arglist}.
5021 The @var{forms} may begin with a string which documents the @code{setf}
5022 method (analogous to the doc string that appears at the front of a
5025 For example, the simple form of @code{defsetf} is shorthand for
5028 (defsetf @var{access-fn} (&rest args) (store)
5029 (append '(@var{update-fn}) args (list store)))
5032 The Lisp form that is returned can access the arguments from
5033 @var{arglist} and @var{store-var} in an unrestricted fashion;
5034 macros like @code{setf} and @code{cl-incf} which invoke this
5035 setf-method will insert temporary variables as needed to make
5036 sure the apparent order of evaluation is preserved.
5038 Another example drawn from the standard package:
5041 (defsetf nth (n x) (store)
5042 (list 'setcar (list 'nthcdr n x) store))
5046 @defmac define-setf-method access-fn arglist forms@dots{}
5047 This is the most general way to create new place forms. When
5048 a @code{setf} to @var{access-fn} with arguments described by
5049 @var{arglist} is expanded, the @var{forms} are evaluated and
5050 must return a list of five items:
5054 A list of @dfn{temporary variables}.
5057 A list of @dfn{value forms} corresponding to the temporary variables
5058 above. The temporary variables will be bound to these value forms
5059 as the first step of any operation on the generalized variable.
5062 A list of exactly one @dfn{store variable} (generally obtained
5063 from a call to @code{gensym}).
5066 A Lisp form which stores the contents of the store variable into
5067 the generalized variable, assuming the temporaries have been
5068 bound as described above.
5071 A Lisp form which accesses the contents of the generalized variable,
5072 assuming the temporaries have been bound.
5075 This is exactly like the Common Lisp macro of the same name,
5076 except that the method returns a list of five values rather
5077 than the five values themselves, since Emacs Lisp does not
5078 support Common Lisp's notion of multiple return values.
5080 Once again, the @var{forms} may begin with a documentation string.
5082 A setf-method should be maximally conservative with regard to
5083 temporary variables. In the setf-methods generated by
5084 @code{defsetf}, the second return value is simply the list of
5085 arguments in the place form, and the first return value is a
5086 list of a corresponding number of temporary variables generated
5087 by @code{cl-gensym}. Macros like @code{setf} and @code{cl-incf} which
5088 use this setf-method will optimize away most temporaries that
5089 turn out to be unnecessary, so there is little reason for the
5090 setf-method itself to optimize.
5093 @defun get-setf-method place &optional env
5094 This function returns the setf-method for @var{place}, by
5095 invoking the definition previously recorded by @code{defsetf}
5096 or @code{define-setf-method}. The result is a list of five
5097 values as described above. You can use this function to build
5098 your own @code{cl-incf}-like modify macros. (Actually, it is
5100 better to use the internal functions @code{cl-setf-do-modify}
5101 and @code{cl-setf-do-store}, which are a bit easier to use and
5102 which also do a number of optimizations; consult the source
5103 code for the @code{cl-incf} function for a simple example.)
5105 The argument @var{env} specifies the ``environment'' to be
5106 passed on to @code{macroexpand} if @code{get-setf-method} should
5107 need to expand a macro in @var{place}. It should come from
5108 an @code{&environment} argument to the macro or setf-method
5109 that called @code{get-setf-method}.
5111 See also the source code for the setf-method for
5112 @c Also @code{apply}, but that is commented out.
5113 @code{substring}, which works by calling @code{get-setf-method} on a
5114 simpler case, then massaging the result.
5117 Modern Common Lisp defines a second, independent way to specify
5118 the @code{setf} behavior of a function, namely ``@code{setf}
5119 functions'' whose names are lists @code{(setf @var{name})}
5120 rather than symbols. For example, @code{(defun (setf foo) @dots{})}
5121 defines the function that is used when @code{setf} is applied to
5122 @code{foo}. This package does not currently support @code{setf}
5123 functions. In particular, it is a compile-time error to use
5124 @code{setf} on a form which has not already been @code{defsetf}'d
5125 or otherwise declared; in newer Common Lisps, this would not be
5126 an error since the function @code{(setf @var{func})} might be
5130 @node GNU Free Documentation License
5131 @appendix GNU Free Documentation License
5132 @include doclicense.texi
5134 @node Function Index
5135 @unnumbered Function Index
5139 @node Variable Index
5140 @unnumbered Variable Index