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--2013 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.''
24 @dircategory Emacs lisp libraries
26 * CL: (cl). Partial Common Lisp support for Emacs Lisp.
33 @center @titlefont{Common Lisp Extensions}
35 @center For GNU Emacs Lisp
37 @center as distributed with Emacs @value{EMACSVER}
39 @center Dave Gillespie
40 @center daveg@@synaptics.com
42 @vskip 0pt plus 1filll
50 @top GNU Emacs Common Lisp Emulation
56 * Overview:: Basics, usage, organization, naming conventions.
57 * Program Structure:: Arglists, @code{cl-eval-when}.
58 * Predicates:: Type predicates and equality predicates.
59 * Control Structure:: Assignment, conditionals, blocks, looping.
60 * Macros:: Destructuring, compiler macros.
61 * Declarations:: @code{cl-proclaim}, @code{cl-declare}, etc.
62 * Symbols:: Property lists, creating symbols.
63 * Numbers:: Predicates, functions, random numbers.
64 * Sequences:: Mapping, functions, searching, sorting.
65 * Lists:: Functions, substitution, sets, associations.
66 * Structures:: @code{cl-defstruct}.
67 * Assertions:: Assertions and type checking.
70 * Efficiency Concerns:: Hints and techniques.
71 * Common Lisp Compatibility:: All known differences with Steele.
72 * Porting Common Lisp:: Hints for porting Common Lisp code.
73 * Obsolete Features:: Obsolete features.
74 * GNU Free Documentation License:: The license for this documentation.
77 * Function Index:: An entry for each documented function.
78 * Variable Index:: An entry for each documented variable.
85 This document describes a set of Emacs Lisp facilities borrowed from
86 Common Lisp. All the facilities are described here in detail. While
87 this document does not assume any prior knowledge of Common Lisp, it
88 does assume a basic familiarity with Emacs Lisp.
90 Common Lisp is a huge language, and Common Lisp systems tend to be
91 massive and extremely complex. Emacs Lisp, by contrast, is rather
92 minimalist in the choice of Lisp features it offers the programmer.
93 As Emacs Lisp programmers have grown in number, and the applications
94 they write have grown more ambitious, it has become clear that Emacs
95 Lisp could benefit from many of the conveniences of Common Lisp.
97 The @dfn{CL} package adds a number of Common Lisp functions and
98 control structures to Emacs Lisp. While not a 100% complete
99 implementation of Common Lisp, it adds enough functionality
100 to make Emacs Lisp programming significantly more convenient.
102 Some Common Lisp features have been omitted from this package
107 Some features are too complex or bulky relative to their benefit
108 to Emacs Lisp programmers. CLOS and Common Lisp streams are fine
109 examples of this group. (The separate package EIEIO implements
110 a subset of CLOS functionality. @xref{Top, , Introduction, eieio, EIEIO}.)
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
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-endp cl-subst
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
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
303 @c For some examples,
304 @c see http://lists.gnu.org/archive/html/emacs-devel/2012-11/msg00009.html
305 efficient inline expansions. In particular, @code{cl-defsubst}
306 arranges for the processing of keyword arguments, default values,
307 etc., to be done at compile-time whenever possible.
310 @defmac cl-defmacro name arglist body@dots{}
311 This is identical to the regular @code{defmacro} form,
312 except that @var{arglist} is allowed to be a full Common Lisp
313 argument list. The @code{&environment} keyword is supported as
314 described in Steele's book @cite{Common Lisp, the Language}.
315 The @code{&whole} keyword is supported only
316 within destructured lists (see below); top-level @code{&whole}
317 cannot be implemented with the current Emacs Lisp interpreter.
318 The macro expander body is enclosed in an implicit block called
322 @defmac cl-function symbol-or-lambda
323 This is identical to the regular @code{function} form,
324 except that if the argument is a @code{lambda} form then that
325 form may use a full Common Lisp argument list.
328 Also, all forms (such as @code{cl-flet} and @code{cl-labels}) defined
329 in this package that include @var{arglist}s in their syntax allow
330 full Common Lisp argument lists.
332 Note that it is @emph{not} necessary to use @code{cl-defun} in
333 order to have access to most CL features in your function.
334 These features are always present; @code{cl-defun}'s only
335 difference from @code{defun} is its more flexible argument
336 lists and its implicit block.
338 The full form of a Common Lisp argument list is
342 &optional (@var{var} @var{initform} @var{svar})@dots{}
344 &key ((@var{keyword} @var{var}) @var{initform} @var{svar})@dots{}
345 &aux (@var{var} @var{initform})@dots{})
348 Each of the five argument list sections is optional. The @var{svar},
349 @var{initform}, and @var{keyword} parts are optional; if they are
350 omitted, then @samp{(@var{var})} may be written simply @samp{@var{var}}.
352 The first section consists of zero or more @dfn{required} arguments.
353 These arguments must always be specified in a call to the function;
354 there is no difference between Emacs Lisp and Common Lisp as far as
355 required arguments are concerned.
357 The second section consists of @dfn{optional} arguments. These
358 arguments may be specified in the function call; if they are not,
359 @var{initform} specifies the default value used for the argument.
360 (No @var{initform} means to use @code{nil} as the default.) The
361 @var{initform} is evaluated with the bindings for the preceding
362 arguments already established; @code{(a &optional (b (1+ a)))}
363 matches one or two arguments, with the second argument defaulting
364 to one plus the first argument. If the @var{svar} is specified,
365 it is an auxiliary variable which is bound to @code{t} if the optional
366 argument was specified, or to @code{nil} if the argument was omitted.
367 If you don't use an @var{svar}, then there will be no way for your
368 function to tell whether it was called with no argument, or with
369 the default value passed explicitly as an argument.
371 The third section consists of a single @dfn{rest} argument. If
372 more arguments were passed to the function than are accounted for
373 by the required and optional arguments, those extra arguments are
374 collected into a list and bound to the ``rest'' argument variable.
375 Common Lisp's @code{&rest} is equivalent to that of Emacs Lisp.
376 Common Lisp accepts @code{&body} as a synonym for @code{&rest} in
377 macro contexts; this package accepts it all the time.
379 The fourth section consists of @dfn{keyword} arguments. These
380 are optional arguments which are specified by name rather than
381 positionally in the argument list. For example,
384 (cl-defun foo (a &optional b &key c d (e 17)))
388 defines a function which may be called with one, two, or more
389 arguments. The first two arguments are bound to @code{a} and
390 @code{b} in the usual way. The remaining arguments must be
391 pairs of the form @code{:c}, @code{:d}, or @code{:e} followed
392 by the value to be bound to the corresponding argument variable.
393 (Symbols whose names begin with a colon are called @dfn{keywords},
394 and they are self-quoting in the same way as @code{nil} and
397 For example, the call @code{(foo 1 2 :d 3 :c 4)} sets the five
398 arguments to 1, 2, 4, 3, and 17, respectively. If the same keyword
399 appears more than once in the function call, the first occurrence
400 takes precedence over the later ones. Note that it is not possible
401 to specify keyword arguments without specifying the optional
402 argument @code{b} as well, since @code{(foo 1 :c 2)} would bind
403 @code{b} to the keyword @code{:c}, then signal an error because
404 @code{2} is not a valid keyword.
406 You can also explicitly specify the keyword argument; it need not be
407 simply the variable name prefixed with a colon. For example,
410 (cl-defun bar (&key (a 1) ((baz b) 4)))
415 specifies a keyword @code{:a} that sets the variable @code{a} with
416 default value 1, as well as a keyword @code{baz} that sets the
417 variable @code{b} with default value 4. In this case, because
418 @code{baz} is not self-quoting, you must quote it explicitly in the
419 function call, like this:
425 Ordinarily, it is an error to pass an unrecognized keyword to
426 a function, e.g., @code{(foo 1 2 :c 3 :goober 4)}. You can ask
427 Lisp to ignore unrecognized keywords, either by adding the
428 marker @code{&allow-other-keys} after the keyword section
429 of the argument list, or by specifying an @code{:allow-other-keys}
430 argument in the call whose value is non-@code{nil}. If the
431 function uses both @code{&rest} and @code{&key} at the same time,
432 the ``rest'' argument is bound to the keyword list as it appears
433 in the call. For example:
436 (cl-defun find-thing (thing &rest rest &key need &allow-other-keys)
437 (or (apply 'cl-member thing thing-list :allow-other-keys t rest)
438 (if need (error "Thing not found"))))
442 This function takes a @code{:need} keyword argument, but also
443 accepts other keyword arguments which are passed on to the
444 @code{cl-member} function. @code{allow-other-keys} is used to
445 keep both @code{find-thing} and @code{cl-member} from complaining
446 about each others' keywords in the arguments.
448 The fifth section of the argument list consists of @dfn{auxiliary
449 variables}. These are not really arguments at all, but simply
450 variables which are bound to @code{nil} or to the specified
451 @var{initforms} during execution of the function. There is no
452 difference between the following two functions, except for a
453 matter of stylistic taste:
456 (cl-defun foo (a b &aux (c (+ a b)) d)
464 Argument lists support @dfn{destructuring}. In Common Lisp,
465 destructuring is only allowed with @code{defmacro}; this package
466 allows it with @code{cl-defun} and other argument lists as well.
467 In destructuring, any argument variable (@var{var} in the above
468 example) can be replaced by a list of variables, or more generally,
469 a recursive argument list. The corresponding argument value must
470 be a list whose elements match this recursive argument list.
474 (cl-defmacro dolist ((var listform &optional resultform)
479 This says that the first argument of @code{dolist} must be a list
480 of two or three items; if there are other arguments as well as this
481 list, they are stored in @code{body}. All features allowed in
482 regular argument lists are allowed in these recursive argument lists.
483 In addition, the clause @samp{&whole @var{var}} is allowed at the
484 front of a recursive argument list. It binds @var{var} to the
485 whole list being matched; thus @code{(&whole all a b)} matches
486 a list of two things, with @code{a} bound to the first thing,
487 @code{b} bound to the second thing, and @code{all} bound to the
488 list itself. (Common Lisp allows @code{&whole} in top-level
489 @code{defmacro} argument lists as well, but Emacs Lisp does not
492 One last feature of destructuring is that the argument list may be
493 dotted, so that the argument list @code{(a b . c)} is functionally
494 equivalent to @code{(a b &rest c)}.
496 If the optimization quality @code{safety} is set to 0
497 (@pxref{Declarations}), error checking for wrong number of
498 arguments and invalid keyword arguments is disabled. By default,
499 argument lists are rigorously checked.
501 @node Time of Evaluation
502 @section Time of Evaluation
505 Normally, the byte-compiler does not actually execute the forms in
506 a file it compiles. For example, if a file contains @code{(setq foo t)},
507 the act of compiling it will not actually set @code{foo} to @code{t}.
508 This is true even if the @code{setq} was a top-level form (i.e., not
509 enclosed in a @code{defun} or other form). Sometimes, though, you
510 would like to have certain top-level forms evaluated at compile-time.
511 For example, the compiler effectively evaluates @code{defmacro} forms
512 at compile-time so that later parts of the file can refer to the
513 macros that are defined.
515 @defmac cl-eval-when (situations@dots{}) forms@dots{}
516 This form controls when the body @var{forms} are evaluated.
517 The @var{situations} list may contain any set of the symbols
518 @code{compile}, @code{load}, and @code{eval} (or their long-winded
519 ANSI equivalents, @code{:compile-toplevel}, @code{:load-toplevel},
520 and @code{:execute}).
522 The @code{cl-eval-when} form is handled differently depending on
523 whether or not it is being compiled as a top-level form.
524 Specifically, it gets special treatment if it is being compiled
525 by a command such as @code{byte-compile-file} which compiles files
526 or buffers of code, and it appears either literally at the
527 top level of the file or inside a top-level @code{progn}.
529 For compiled top-level @code{cl-eval-when}s, the body @var{forms} are
530 executed at compile-time if @code{compile} is in the @var{situations}
531 list, and the @var{forms} are written out to the file (to be executed
532 at load-time) if @code{load} is in the @var{situations} list.
534 For non-compiled-top-level forms, only the @code{eval} situation is
535 relevant. (This includes forms executed by the interpreter, forms
536 compiled with @code{byte-compile} rather than @code{byte-compile-file},
537 and non-top-level forms.) The @code{cl-eval-when} acts like a
538 @code{progn} if @code{eval} is specified, and like @code{nil}
539 (ignoring the body @var{forms}) if not.
541 The rules become more subtle when @code{cl-eval-when}s are nested;
542 consult Steele (second edition) for the gruesome details (and
543 some gruesome examples).
545 Some simple examples:
548 ;; Top-level forms in foo.el:
549 (cl-eval-when (compile) (setq foo1 'bar))
550 (cl-eval-when (load) (setq foo2 'bar))
551 (cl-eval-when (compile load) (setq foo3 'bar))
552 (cl-eval-when (eval) (setq foo4 'bar))
553 (cl-eval-when (eval compile) (setq foo5 'bar))
554 (cl-eval-when (eval load) (setq foo6 'bar))
555 (cl-eval-when (eval compile load) (setq foo7 'bar))
558 When @file{foo.el} is compiled, these variables will be set during
559 the compilation itself:
562 foo1 foo3 foo5 foo7 ; `compile'
565 When @file{foo.elc} is loaded, these variables will be set:
568 foo2 foo3 foo6 foo7 ; `load'
571 And if @file{foo.el} is loaded uncompiled, these variables will
575 foo4 foo5 foo6 foo7 ; `eval'
578 If these seven @code{cl-eval-when}s had been, say, inside a @code{defun},
579 then the first three would have been equivalent to @code{nil} and the
580 last four would have been equivalent to the corresponding @code{setq}s.
582 Note that @code{(cl-eval-when (load eval) @dots{})} is equivalent
583 to @code{(progn @dots{})} in all contexts. The compiler treats
584 certain top-level forms, like @code{defmacro} (sort-of) and
585 @code{require}, as if they were wrapped in @code{(cl-eval-when
586 (compile load eval) @dots{})}.
589 Emacs includes two special forms related to @code{cl-eval-when}.
590 @xref{Eval During Compile,,,elisp,GNU Emacs Lisp Reference Manual}.
591 One of these, @code{eval-when-compile}, is not quite equivalent to
592 any @code{cl-eval-when} construct and is described below.
594 The other form, @code{(eval-and-compile @dots{})}, is exactly
595 equivalent to @samp{(cl-eval-when (compile load eval) @dots{})}.
597 @defmac eval-when-compile forms@dots{}
598 The @var{forms} are evaluated at compile-time; at execution time,
599 this form acts like a quoted constant of the resulting value. Used
600 at top-level, @code{eval-when-compile} is just like @samp{eval-when
601 (compile eval)}. In other contexts, @code{eval-when-compile}
602 allows code to be evaluated once at compile-time for efficiency
605 This form is similar to the @samp{#.} syntax of true Common Lisp.
608 @defmac cl-load-time-value form
609 The @var{form} is evaluated at load-time; at execution time,
610 this form acts like a quoted constant of the resulting value.
612 Early Common Lisp had a @samp{#,} syntax that was similar to
613 this, but ANSI Common Lisp replaced it with @code{load-time-value}
614 and gave it more well-defined semantics.
616 In a compiled file, @code{cl-load-time-value} arranges for @var{form}
617 to be evaluated when the @file{.elc} file is loaded and then used
618 as if it were a quoted constant. In code compiled by
619 @code{byte-compile} rather than @code{byte-compile-file}, the
620 effect is identical to @code{eval-when-compile}. In uncompiled
621 code, both @code{eval-when-compile} and @code{cl-load-time-value}
622 act exactly like @code{progn}.
626 (insert "This function was executed on: "
627 (current-time-string)
629 (eval-when-compile (current-time-string))
630 ;; or '#.(current-time-string) in real Common Lisp
632 (cl-load-time-value (current-time-string))))
636 Byte-compiled, the above defun will result in the following code
637 (or its compiled equivalent, of course) in the @file{.elc} file:
640 (setq --temp-- (current-time-string))
642 (insert "This function was executed on: "
643 (current-time-string)
645 '"Wed Oct 31 16:32:28 2012"
655 This section describes functions for testing whether various
656 facts are true or false.
659 * Type Predicates:: @code{cl-typep}, @code{cl-deftype}, and @code{cl-coerce}.
660 * Equality Predicates:: @code{cl-equalp}.
663 @node Type Predicates
664 @section Type Predicates
666 @defun cl-typep object type
667 Check if @var{object} is of type @var{type}, where @var{type} is a
668 (quoted) type name of the sort used by Common Lisp. For example,
669 @code{(cl-typep foo 'integer)} is equivalent to @code{(integerp foo)}.
672 The @var{type} argument to the above function is either a symbol
673 or a list beginning with a symbol.
677 If the type name is a symbol, Emacs appends @samp{-p} to the
678 symbol name to form the name of a predicate function for testing
679 the type. (Built-in predicates whose names end in @samp{p} rather
680 than @samp{-p} are used when appropriate.)
683 The type symbol @code{t} stands for the union of all types.
684 @code{(cl-typep @var{object} t)} is always true. Likewise, the
685 type symbol @code{nil} stands for nothing at all, and
686 @code{(cl-typep @var{object} nil)} is always false.
689 The type symbol @code{null} represents the symbol @code{nil}.
690 Thus @code{(cl-typep @var{object} 'null)} is equivalent to
691 @code{(null @var{object})}.
694 The type symbol @code{atom} represents all objects that are not cons
695 cells. Thus @code{(cl-typep @var{object} 'atom)} is equivalent to
696 @code{(atom @var{object})}.
699 The type symbol @code{real} is a synonym for @code{number}, and
700 @code{fixnum} is a synonym for @code{integer}.
703 The type symbols @code{character} and @code{string-char} match
704 integers in the range from 0 to 255.
707 The type list @code{(integer @var{low} @var{high})} represents all
708 integers between @var{low} and @var{high}, inclusive. Either bound
709 may be a list of a single integer to specify an exclusive limit,
710 or a @code{*} to specify no limit. The type @code{(integer * *)}
711 is thus equivalent to @code{integer}.
714 Likewise, lists beginning with @code{float}, @code{real}, or
715 @code{number} represent numbers of that type falling in a particular
719 Lists beginning with @code{and}, @code{or}, and @code{not} form
720 combinations of types. For example, @code{(or integer (float 0 *))}
721 represents all objects that are integers or non-negative floats.
724 Lists beginning with @code{member} or @code{cl-member} represent
725 objects @code{eql} to any of the following values. For example,
726 @code{(member 1 2 3 4)} is equivalent to @code{(integer 1 4)},
727 and @code{(member nil)} is equivalent to @code{null}.
730 Lists of the form @code{(satisfies @var{predicate})} represent
731 all objects for which @var{predicate} returns true when called
732 with that object as an argument.
735 The following function and macro (not technically predicates) are
736 related to @code{cl-typep}.
738 @defun cl-coerce object type
739 This function attempts to convert @var{object} to the specified
740 @var{type}. If @var{object} is already of that type as determined by
741 @code{cl-typep}, it is simply returned. Otherwise, certain types of
742 conversions will be made: If @var{type} is any sequence type
743 (@code{string}, @code{list}, etc.)@: then @var{object} will be
744 converted to that type if possible. If @var{type} is
745 @code{character}, then strings of length one and symbols with
746 one-character names can be coerced. If @var{type} is @code{float},
747 then integers can be coerced in versions of Emacs that support
748 floats. In all other circumstances, @code{cl-coerce} signals an
752 @defmac cl-deftype name arglist forms@dots{}
753 This macro defines a new type called @var{name}. It is similar
754 to @code{defmacro} in many ways; when @var{name} is encountered
755 as a type name, the body @var{forms} are evaluated and should
756 return a type specifier that is equivalent to the type. The
757 @var{arglist} is a Common Lisp argument list of the sort accepted
758 by @code{cl-defmacro}. The type specifier @samp{(@var{name} @var{args}@dots{})}
759 is expanded by calling the expander with those arguments; the type
760 symbol @samp{@var{name}} is expanded by calling the expander with
761 no arguments. The @var{arglist} is processed the same as for
762 @code{cl-defmacro} except that optional arguments without explicit
763 defaults use @code{*} instead of @code{nil} as the ``default''
764 default. Some examples:
767 (cl-deftype null () '(satisfies null)) ; predefined
768 (cl-deftype list () '(or null cons)) ; predefined
769 (cl-deftype unsigned-byte (&optional bits)
770 (list 'integer 0 (if (eq bits '*) bits (1- (lsh 1 bits)))))
771 (unsigned-byte 8) @equiv{} (integer 0 255)
772 (unsigned-byte) @equiv{} (integer 0 *)
773 unsigned-byte @equiv{} (integer 0 *)
777 The last example shows how the Common Lisp @code{unsigned-byte}
778 type specifier could be implemented if desired; this package does
779 not implement @code{unsigned-byte} by default.
782 The @code{cl-typecase} (@pxref{Conditionals}) and @code{cl-check-type}
783 (@pxref{Assertions}) macros also use type names. The @code{cl-map},
784 @code{cl-concatenate}, and @code{cl-merge} functions take type-name
785 arguments to specify the type of sequence to return. @xref{Sequences}.
787 @node Equality Predicates
788 @section Equality Predicates
791 This package defines the Common Lisp predicate @code{cl-equalp}.
794 This function is a more flexible version of @code{equal}. In
795 particular, it compares strings case-insensitively, and it compares
796 numbers without regard to type (so that @code{(cl-equalp 3 3.0)} is
797 true). Vectors and conses are compared recursively. All other
798 objects are compared as if by @code{equal}.
800 This function differs from Common Lisp @code{equalp} in several
801 respects. First, Common Lisp's @code{equalp} also compares
802 @emph{characters} case-insensitively, which would be impractical
803 in this package since Emacs does not distinguish between integers
804 and characters. In keeping with the idea that strings are less
805 vector-like in Emacs Lisp, this package's @code{cl-equalp} also will
806 not compare strings against vectors of integers.
809 Also note that the Common Lisp functions @code{member} and @code{assoc}
810 use @code{eql} to compare elements, whereas Emacs Lisp follows the
811 MacLisp tradition and uses @code{equal} for these two functions.
812 The functions @code{cl-member} and @code{cl-assoc} use @code{eql},
813 as in Common Lisp. The standard Emacs Lisp functions @code{memq} and
814 @code{assq} use @code{eq}, and the standard @code{memql} uses @code{eql}.
816 @node Control Structure
817 @chapter Control Structure
820 The features described in the following sections implement
821 various advanced control structures, including extensions to the
822 standard @code{setf} facility, and a number of looping and conditional
826 * Assignment:: The @code{cl-psetq} form.
827 * Generalized Variables:: Extensions to generalized variables.
828 * Variable Bindings:: @code{cl-progv}, @code{cl-flet}, @code{cl-macrolet}.
829 * Conditionals:: @code{cl-case}, @code{cl-typecase}.
830 * Blocks and Exits:: @code{cl-block}, @code{cl-return}, @code{cl-return-from}.
831 * Iteration:: @code{cl-do}, @code{cl-dotimes}, @code{cl-dolist}, @code{cl-do-symbols}.
832 * Loop Facility:: The Common Lisp @code{loop} macro.
833 * Multiple Values:: @code{cl-values}, @code{cl-multiple-value-bind}, etc.
840 The @code{cl-psetq} form is just like @code{setq}, except that multiple
841 assignments are done in parallel rather than sequentially.
843 @defmac cl-psetq [symbol form]@dots{}
844 This special form (actually a macro) is used to assign to several
845 variables simultaneously. Given only one @var{symbol} and @var{form},
846 it has the same effect as @code{setq}. Given several @var{symbol}
847 and @var{form} pairs, it evaluates all the @var{form}s in advance
848 and then stores the corresponding variables afterwards.
852 (setq x (+ x y) y (* x y))
855 y ; @r{@code{y} was computed after @code{x} was set.}
858 (cl-psetq x (+ x y) y (* x y))
861 y ; @r{@code{y} was computed before @code{x} was set.}
865 The simplest use of @code{cl-psetq} is @code{(cl-psetq x y y x)}, which
866 exchanges the values of two variables. (The @code{cl-rotatef} form
867 provides an even more convenient way to swap two variables;
868 @pxref{Modify Macros}.)
870 @code{cl-psetq} always returns @code{nil}.
873 @node Generalized Variables
874 @section Generalized Variables
876 A @dfn{generalized variable} or @dfn{place form} is one of the many
877 places in Lisp memory where values can be stored. The simplest place
878 form is a regular Lisp variable. But the @sc{car}s and @sc{cdr}s of lists,
879 elements of arrays, properties of symbols, and many other locations
880 are also places where Lisp values are stored. For basic information,
881 @pxref{Generalized Variables,,,elisp,GNU Emacs Lisp Reference Manual}.
882 This package provides several additional features related to
883 generalized variables.
886 * Setf Extensions:: Additional @code{setf} places.
887 * Modify Macros:: @code{cl-incf}, @code{cl-rotatef}, @code{cl-letf}, @code{cl-callf}, etc.
890 @node Setf Extensions
891 @subsection Setf Extensions
893 Several standard (e.g., @code{car}) and Emacs-specific
894 (e.g., @code{window-point}) Lisp functions are @code{setf}-able by default.
895 This package defines @code{setf} handlers for several additional functions:
899 Functions from this package:
901 cl-rest cl-subseq cl-get cl-getf
902 cl-caaar@dots{}cl-cddddr cl-first@dots{}cl-tenth
906 Note that for @code{cl-getf} (as for @code{nthcdr}), the list argument
907 of the function must itself be a valid @var{place} form.
910 General Emacs Lisp functions:
912 buffer-file-name getenv
913 buffer-modified-p global-key-binding
914 buffer-name local-key-binding
916 buffer-substring mark-marker
917 current-buffer marker-position
918 current-case-table mouse-position
920 current-global-map point-marker
921 current-input-mode point-max
922 current-local-map point-min
923 current-window-configuration read-mouse-position
924 default-file-modes screen-height
925 documentation-property screen-width
926 face-background selected-window
927 face-background-pixmap selected-screen
928 face-font selected-frame
929 face-foreground standard-case-table
930 face-underline-p syntax-table
931 file-modes visited-file-modtime
932 frame-height window-height
933 frame-parameters window-width
934 frame-visible-p x-get-secondary-selection
935 frame-width x-get-selection
939 Most of these have directly corresponding ``set'' functions, like
940 @code{use-local-map} for @code{current-local-map}, or @code{goto-char}
941 for @code{point}. A few, like @code{point-min}, expand to longer
942 sequences of code when they are used with @code{setf}
943 (@code{(narrow-to-region x (point-max))} in this case).
946 A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])},
947 where @var{subplace} is itself a valid generalized variable whose
948 current value is a string, and where the value stored is also a
949 string. The new string is spliced into the specified part of the
950 destination string. For example:
953 (setq a (list "hello" "world"))
954 @result{} ("hello" "world")
957 (substring (cadr a) 2 4)
959 (setf (substring (cadr a) 2 4) "o")
964 @result{} ("hello" "wood")
967 The generalized variable @code{buffer-substring}, listed above,
968 also works in this way by replacing a portion of the current buffer.
970 @c FIXME? Also `eq'? (see cl-lib.el)
972 @c Currently commented out in cl.el.
975 A call of the form @code{(apply '@var{func} @dots{})} or
976 @code{(apply (function @var{func}) @dots{})}, where @var{func}
977 is a @code{setf}-able function whose store function is ``suitable''
978 in the sense described in Steele's book; since none of the standard
979 Emacs place functions are suitable in this sense, this feature is
980 only interesting when used with places you define yourself with
981 @code{define-setf-method} or the long form of @code{defsetf}.
982 @xref{Obsolete Setf Customization}.
985 @c FIXME? Is this still true?
987 A macro call, in which case the macro is expanded and @code{setf}
988 is applied to the resulting form.
991 @c FIXME should this be in lispref? It seems self-evident.
992 @c Contrast with the cl-incf example later on.
993 @c Here it really only serves as a contrast to wrong-order.
994 The @code{setf} macro takes care to evaluate all subforms in
995 the proper left-to-right order; for example,
998 (setf (aref vec (cl-incf i)) i)
1002 looks like it will evaluate @code{(cl-incf i)} exactly once, before the
1003 following access to @code{i}; the @code{setf} expander will insert
1004 temporary variables as necessary to ensure that it does in fact work
1005 this way no matter what setf-method is defined for @code{aref}.
1006 (In this case, @code{aset} would be used and no such steps would
1007 be necessary since @code{aset} takes its arguments in a convenient
1010 However, if the @var{place} form is a macro which explicitly
1011 evaluates its arguments in an unusual order, this unusual order
1012 will be preserved. Adapting an example from Steele, given
1015 (defmacro wrong-order (x y) (list 'aref y x))
1019 the form @code{(setf (wrong-order @var{a} @var{b}) 17)} will
1020 evaluate @var{b} first, then @var{a}, just as in an actual call
1021 to @code{wrong-order}.
1024 @subsection Modify Macros
1027 This package defines a number of macros that operate on generalized
1028 variables. Many are interesting and useful even when the @var{place}
1029 is just a variable name.
1031 @defmac cl-psetf [place form]@dots{}
1032 This macro is to @code{setf} what @code{cl-psetq} is to @code{setq}:
1033 When several @var{place}s and @var{form}s are involved, the
1034 assignments take place in parallel rather than sequentially.
1035 Specifically, all subforms are evaluated from left to right, then
1036 all the assignments are done (in an undefined order).
1039 @defmac cl-incf place &optional x
1040 This macro increments the number stored in @var{place} by one, or
1041 by @var{x} if specified. The incremented value is returned. For
1042 example, @code{(cl-incf i)} is equivalent to @code{(setq i (1+ i))}, and
1043 @code{(cl-incf (car x) 2)} is equivalent to @code{(setcar x (+ (car x) 2))}.
1045 As with @code{setf}, care is taken to preserve the ``apparent'' order
1046 of evaluation. For example,
1049 (cl-incf (aref vec (cl-incf i)))
1053 appears to increment @code{i} once, then increment the element of
1054 @code{vec} addressed by @code{i}; this is indeed exactly what it
1055 does, which means the above form is @emph{not} equivalent to the
1056 ``obvious'' expansion,
1059 (setf (aref vec (cl-incf i))
1060 (1+ (aref vec (cl-incf i)))) ; wrong!
1064 but rather to something more like
1067 (let ((temp (cl-incf i)))
1068 (setf (aref vec temp) (1+ (aref vec temp))))
1072 Again, all of this is taken care of automatically by @code{cl-incf} and
1073 the other generalized-variable macros.
1075 As a more Emacs-specific example of @code{cl-incf}, the expression
1076 @code{(cl-incf (point) @var{n})} is essentially equivalent to
1077 @code{(forward-char @var{n})}.
1080 @defmac cl-decf place &optional x
1081 This macro decrements the number stored in @var{place} by one, or
1082 by @var{x} if specified.
1085 @defmac cl-pushnew x place @t{&key :test :test-not :key}
1086 This macro inserts @var{x} at the front of the list stored in
1087 @var{place}, but only if @var{x} was not @code{eql} to any
1088 existing element of the list. The optional keyword arguments
1089 are interpreted in the same way as for @code{cl-adjoin}.
1090 @xref{Lists as Sets}.
1093 @defmac cl-shiftf place@dots{} newvalue
1094 This macro shifts the @var{place}s left by one, shifting in the
1095 value of @var{newvalue} (which may be any Lisp expression, not just
1096 a generalized variable), and returning the value shifted out of
1097 the first @var{place}. Thus, @code{(cl-shiftf @var{a} @var{b} @var{c}
1098 @var{d})} is equivalent to
1103 (cl-psetf @var{a} @var{b}
1109 except that the subforms of @var{a}, @var{b}, and @var{c} are actually
1110 evaluated only once each and in the apparent order.
1113 @defmac cl-rotatef place@dots{}
1114 This macro rotates the @var{place}s left by one in circular fashion.
1115 Thus, @code{(cl-rotatef @var{a} @var{b} @var{c} @var{d})} is equivalent to
1118 (cl-psetf @var{a} @var{b}
1125 except for the evaluation of subforms. @code{cl-rotatef} always
1126 returns @code{nil}. Note that @code{(cl-rotatef @var{a} @var{b})}
1127 conveniently exchanges @var{a} and @var{b}.
1130 The following macros were invented for this package; they have no
1131 analogues in Common Lisp.
1133 @defmac cl-letf (bindings@dots{}) forms@dots{}
1134 This macro is analogous to @code{let}, but for generalized variables
1135 rather than just symbols. Each @var{binding} should be of the form
1136 @code{(@var{place} @var{value})}; the original contents of the
1137 @var{place}s are saved, the @var{value}s are stored in them, and
1138 then the body @var{form}s are executed. Afterwards, the @var{places}
1139 are set back to their original saved contents. This cleanup happens
1140 even if the @var{form}s exit irregularly due to a @code{throw} or an
1146 (cl-letf (((point) (point-min))
1152 moves point in the current buffer to the beginning of the buffer,
1153 and also binds @code{a} to 17 (as if by a normal @code{let}, since
1154 @code{a} is just a regular variable). After the body exits, @code{a}
1155 is set back to its original value and point is moved back to its
1158 Note that @code{cl-letf} on @code{(point)} is not quite like a
1159 @code{save-excursion}, as the latter effectively saves a marker
1160 which tracks insertions and deletions in the buffer. Actually,
1161 a @code{cl-letf} of @code{(point-marker)} is much closer to this
1162 behavior. (@code{point} and @code{point-marker} are equivalent
1163 as @code{setf} places; each will accept either an integer or a
1164 marker as the stored value.)
1166 Since generalized variables look like lists, @code{let}'s shorthand
1167 of using @samp{foo} for @samp{(foo nil)} as a @var{binding} would
1168 be ambiguous in @code{cl-letf} and is not allowed.
1170 However, a @var{binding} specifier may be a one-element list
1171 @samp{(@var{place})}, which is similar to @samp{(@var{place}
1172 @var{place})}. In other words, the @var{place} is not disturbed
1173 on entry to the body, and the only effect of the @code{cl-letf} is
1174 to restore the original value of @var{place} afterwards.
1175 @c I suspect this may no longer be true; either way it's
1176 @c implementation detail and so not essential to document.
1178 (The redundant access-and-store suggested by the @code{(@var{place}
1179 @var{place})} example does not actually occur.)
1182 Note that in this case, and in fact almost every case, @var{place}
1183 must have a well-defined value outside the @code{cl-letf} body.
1184 There is essentially only one exception to this, which is @var{place}
1185 a plain variable with a specified @var{value} (such as @code{(a 17)}
1186 in the above example).
1187 @c See http://debbugs.gnu.org/12758
1188 @c Some or all of this was true for cl.el, but not for cl-lib.el.
1190 The only exceptions are plain variables and calls to
1191 @code{symbol-value} and @code{symbol-function}. If the symbol is not
1192 bound on entry, it is simply made unbound by @code{makunbound} or
1193 @code{fmakunbound} on exit.
1197 @defmac cl-letf* (bindings@dots{}) forms@dots{}
1198 This macro is to @code{cl-letf} what @code{let*} is to @code{let}:
1199 It does the bindings in sequential rather than parallel order.
1202 @defmac cl-callf @var{function} @var{place} @var{args}@dots{}
1203 This is the ``generic'' modify macro. It calls @var{function},
1204 which should be an unquoted function name, macro name, or lambda.
1205 It passes @var{place} and @var{args} as arguments, and assigns the
1206 result back to @var{place}. For example, @code{(cl-incf @var{place}
1207 @var{n})} is the same as @code{(cl-callf + @var{place} @var{n})}.
1211 (cl-callf abs my-number)
1212 (cl-callf concat (buffer-name) "<" (number-to-string n) ">")
1213 (cl-callf cl-union happy-people (list joe bob) :test 'same-person)
1216 Note again that @code{cl-callf} is an extension to standard Common Lisp.
1219 @defmac cl-callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{}
1220 This macro is like @code{cl-callf}, except that @var{place} is
1221 the @emph{second} argument of @var{function} rather than the
1222 first. For example, @code{(push @var{x} @var{place})} is
1223 equivalent to @code{(cl-callf2 cons @var{x} @var{place})}.
1226 The @code{cl-callf} and @code{cl-callf2} macros serve as building
1227 blocks for other macros like @code{cl-incf}, and @code{cl-pushnew}.
1228 The @code{cl-letf} and @code{cl-letf*} macros are used in the processing
1229 of symbol macros; @pxref{Macro Bindings}.
1232 @node Variable Bindings
1233 @section Variable Bindings
1236 These Lisp forms make bindings to variables and function names,
1237 analogous to Lisp's built-in @code{let} form.
1239 @xref{Modify Macros}, for the @code{cl-letf} and @code{cl-letf*} forms which
1240 are also related to variable bindings.
1243 * Dynamic Bindings:: The @code{cl-progv} form.
1244 * Function Bindings:: @code{cl-flet} and @code{cl-labels}.
1245 * Macro Bindings:: @code{cl-macrolet} and @code{cl-symbol-macrolet}.
1248 @node Dynamic Bindings
1249 @subsection Dynamic Bindings
1252 The standard @code{let} form binds variables whose names are known
1253 at compile-time. The @code{cl-progv} form provides an easy way to
1254 bind variables whose names are computed at run-time.
1256 @defmac cl-progv symbols values forms@dots{}
1257 This form establishes @code{let}-style variable bindings on a
1258 set of variables computed at run-time. The expressions
1259 @var{symbols} and @var{values} are evaluated, and must return lists
1260 of symbols and values, respectively. The symbols are bound to the
1261 corresponding values for the duration of the body @var{form}s.
1262 If @var{values} is shorter than @var{symbols}, the last few symbols
1263 are bound to @code{nil}.
1264 If @var{symbols} is shorter than @var{values}, the excess values
1268 @node Function Bindings
1269 @subsection Function Bindings
1272 These forms make @code{let}-like bindings to functions instead
1275 @defmac cl-flet (bindings@dots{}) forms@dots{}
1276 This form establishes @code{let}-style bindings on the function
1277 cells of symbols rather than on the value cells. Each @var{binding}
1278 must be a list of the form @samp{(@var{name} @var{arglist}
1279 @var{forms}@dots{})}, which defines a function exactly as if
1280 it were a @code{cl-defun} form. The function @var{name} is defined
1281 accordingly for the duration of the body of the @code{cl-flet}; then
1282 the old function definition, or lack thereof, is restored.
1284 You can use @code{cl-flet} to disable or modify the behavior of
1285 functions (including Emacs primitives) in a temporary, localized fashion.
1286 (Compare this with the idea of advising functions.
1287 @xref{Advising Functions,,,elisp,GNU Emacs Lisp Reference Manual}.)
1289 The bindings are lexical in scope. This means that all references to
1290 the named functions must appear physically within the body of the
1291 @code{cl-flet} form.
1293 Functions defined by @code{cl-flet} may use the full Common Lisp
1294 argument notation supported by @code{cl-defun}; also, the function
1295 body is enclosed in an implicit block as if by @code{cl-defun}.
1296 @xref{Program Structure}.
1298 Note that the @file{cl.el} version of this macro behaves slightly
1299 differently. In particular, its binding is dynamic rather than
1300 lexical. @xref{Obsolete Macros}.
1303 @defmac cl-labels (bindings@dots{}) forms@dots{}
1304 The @code{cl-labels} form is like @code{cl-flet}, except that
1305 the function bindings can be recursive. The scoping is lexical,
1306 but you can only capture functions in closures if
1307 @code{lexical-binding} is @code{t}.
1308 @xref{Closures,,,elisp,GNU Emacs Lisp Reference Manual}, and
1309 @ref{Using Lexical Binding,,,elisp,GNU Emacs Lisp Reference Manual}.
1311 Lexical scoping means that all references to the named
1312 functions must appear physically within the body of the
1313 @code{cl-labels} form. References may appear both in the body
1314 @var{forms} of @code{cl-labels} itself, and in the bodies of
1315 the functions themselves. Thus, @code{cl-labels} can define
1316 local recursive functions, or mutually-recursive sets of functions.
1318 A ``reference'' to a function name is either a call to that
1319 function, or a use of its name quoted by @code{quote} or
1320 @code{function} to be passed on to, say, @code{mapcar}.
1322 Note that the @file{cl.el} version of this macro behaves slightly
1323 differently. @xref{Obsolete Macros}.
1326 @node Macro Bindings
1327 @subsection Macro Bindings
1330 These forms create local macros and ``symbol macros''.
1332 @defmac cl-macrolet (bindings@dots{}) forms@dots{}
1333 This form is analogous to @code{cl-flet}, but for macros instead of
1334 functions. Each @var{binding} is a list of the same form as the
1335 arguments to @code{cl-defmacro} (i.e., a macro name, argument list,
1336 and macro-expander forms). The macro is defined accordingly for
1337 use within the body of the @code{cl-macrolet}.
1339 Because of the nature of macros, @code{cl-macrolet} is always lexically
1340 scoped. The @code{cl-macrolet} binding will
1341 affect only calls that appear physically within the body
1342 @var{forms}, possibly after expansion of other macros in the
1346 @defmac cl-symbol-macrolet (bindings@dots{}) forms@dots{}
1347 This form creates @dfn{symbol macros}, which are macros that look
1348 like variable references rather than function calls. Each
1349 @var{binding} is a list @samp{(@var{var} @var{expansion})};
1350 any reference to @var{var} within the body @var{forms} is
1351 replaced by @var{expansion}.
1355 (cl-symbol-macrolet ((foo (car bar)))
1361 A @code{setq} of a symbol macro is treated the same as a @code{setf}.
1362 I.e., @code{(setq foo 4)} in the above would be equivalent to
1363 @code{(setf foo 4)}, which in turn expands to @code{(setf (car bar) 4)}.
1365 Likewise, a @code{let} or @code{let*} binding a symbol macro is
1366 treated like a @code{cl-letf} or @code{cl-letf*}. This differs from true
1367 Common Lisp, where the rules of lexical scoping cause a @code{let}
1368 binding to shadow a @code{symbol-macrolet} binding. In this package,
1369 such shadowing does not occur, even when @code{lexical-binding} is
1370 @c See http://debbugs.gnu.org/12119
1371 @code{t}. (This behavior predates the addition of lexical binding to
1372 Emacs Lisp, and may change in future to respect @code{lexical-binding}.)
1373 At present in this package, only @code{lexical-let} and
1374 @code{lexical-let*} will shadow a symbol macro. @xref{Obsolete
1377 There is no analogue of @code{defmacro} for symbol macros; all symbol
1378 macros are local. A typical use of @code{cl-symbol-macrolet} is in the
1379 expansion of another macro:
1382 (cl-defmacro my-dolist ((x list) &rest body)
1383 (let ((var (cl-gensym)))
1384 (list 'cl-loop 'for var 'on list 'do
1385 (cl-list* 'cl-symbol-macrolet
1386 (list (list x (list 'car var)))
1389 (setq mylist '(1 2 3 4))
1390 (my-dolist (x mylist) (cl-incf x))
1396 In this example, the @code{my-dolist} macro is similar to @code{dolist}
1397 (@pxref{Iteration}) except that the variable @code{x} becomes a true
1398 reference onto the elements of the list. The @code{my-dolist} call
1399 shown here expands to
1402 (cl-loop for G1234 on mylist do
1403 (cl-symbol-macrolet ((x (car G1234)))
1408 which in turn expands to
1411 (cl-loop for G1234 on mylist do (cl-incf (car G1234)))
1414 @xref{Loop Facility}, for a description of the @code{cl-loop} macro.
1415 This package defines a nonstandard @code{in-ref} loop clause that
1416 works much like @code{my-dolist}.
1420 @section Conditionals
1423 These conditional forms augment Emacs Lisp's simple @code{if},
1424 @code{and}, @code{or}, and @code{cond} forms.
1426 @defmac cl-case keyform clause@dots{}
1427 This macro evaluates @var{keyform}, then compares it with the key
1428 values listed in the various @var{clause}s. Whichever clause matches
1429 the key is executed; comparison is done by @code{eql}. If no clause
1430 matches, the @code{cl-case} form returns @code{nil}. The clauses are
1434 (@var{keylist} @var{body-forms}@dots{})
1438 where @var{keylist} is a list of key values. If there is exactly
1439 one value, and it is not a cons cell or the symbol @code{nil} or
1440 @code{t}, then it can be used by itself as a @var{keylist} without
1441 being enclosed in a list. All key values in the @code{cl-case} form
1442 must be distinct. The final clauses may use @code{t} in place of
1443 a @var{keylist} to indicate a default clause that should be taken
1444 if none of the other clauses match. (The symbol @code{otherwise}
1445 is also recognized in place of @code{t}. To make a clause that
1446 matches the actual symbol @code{t}, @code{nil}, or @code{otherwise},
1447 enclose the symbol in a list.)
1449 For example, this expression reads a keystroke, then does one of
1450 four things depending on whether it is an @samp{a}, a @samp{b},
1451 a @key{RET} or @kbd{C-j}, or anything else.
1454 (cl-case (read-char)
1457 ((?\r ?\n) (do-ret-thing))
1458 (t (do-other-thing)))
1462 @defmac cl-ecase keyform clause@dots{}
1463 This macro is just like @code{cl-case}, except that if the key does
1464 not match any of the clauses, an error is signaled rather than
1465 simply returning @code{nil}.
1468 @defmac cl-typecase keyform clause@dots{}
1469 This macro is a version of @code{cl-case} that checks for types
1470 rather than values. Each @var{clause} is of the form
1471 @samp{(@var{type} @var{body}@dots{})}. @xref{Type Predicates},
1472 for a description of type specifiers. For example,
1476 (integer (munch-integer x))
1477 (float (munch-float x))
1478 (string (munch-integer (string-to-int x)))
1479 (t (munch-anything x)))
1482 The type specifier @code{t} matches any type of object; the word
1483 @code{otherwise} is also allowed. To make one clause match any of
1484 several types, use an @code{(or @dots{})} type specifier.
1487 @defmac cl-etypecase keyform clause@dots{}
1488 This macro is just like @code{cl-typecase}, except that if the key does
1489 not match any of the clauses, an error is signaled rather than
1490 simply returning @code{nil}.
1493 @node Blocks and Exits
1494 @section Blocks and Exits
1498 Common Lisp @dfn{blocks} provide a non-local exit mechanism very
1499 similar to @code{catch} and @code{throw}, with lexical scoping.
1500 This package actually implements @code{cl-block}
1501 in terms of @code{catch}; however, the lexical scoping allows the
1502 byte-compiler to omit the costly @code{catch} step if the
1503 body of the block does not actually @code{cl-return-from} the block.
1505 @defmac cl-block name forms@dots{}
1506 The @var{forms} are evaluated as if by a @code{progn}. However,
1507 if any of the @var{forms} execute @code{(cl-return-from @var{name})},
1508 they will jump out and return directly from the @code{cl-block} form.
1509 The @code{cl-block} returns the result of the last @var{form} unless
1510 a @code{cl-return-from} occurs.
1512 The @code{cl-block}/@code{cl-return-from} mechanism is quite similar to
1513 the @code{catch}/@code{throw} mechanism. The main differences are
1514 that block @var{name}s are unevaluated symbols, rather than forms
1515 (such as quoted symbols) that evaluate to a tag at run-time; and
1516 also that blocks are always lexically scoped.
1517 In a dynamically scoped @code{catch}, functions called from the
1518 @code{catch} body can also @code{throw} to the @code{catch}. This
1519 is not an option for @code{cl-block}, where
1520 the @code{cl-return-from} referring to a block name must appear
1521 physically within the @var{forms} that make up the body of the block.
1522 They may not appear within other called functions, although they may
1523 appear within macro expansions or @code{lambda}s in the body. Block
1524 names and @code{catch} names form independent name-spaces.
1526 In true Common Lisp, @code{defun} and @code{defmacro} surround
1527 the function or expander bodies with implicit blocks with the
1528 same name as the function or macro. This does not occur in Emacs
1529 Lisp, but this package provides @code{cl-defun} and @code{cl-defmacro}
1530 forms, which do create the implicit block.
1532 The Common Lisp looping constructs defined by this package,
1533 such as @code{cl-loop} and @code{cl-dolist}, also create implicit blocks
1534 just as in Common Lisp.
1536 Because they are implemented in terms of Emacs Lisp's @code{catch}
1537 and @code{throw}, blocks have the same overhead as actual
1538 @code{catch} constructs (roughly two function calls). However,
1539 the byte compiler will optimize away the @code{catch}
1541 not in fact contain any @code{cl-return} or @code{cl-return-from} calls
1542 that jump to it. This means that @code{cl-do} loops and @code{cl-defun}
1543 functions that don't use @code{cl-return} don't pay the overhead to
1547 @defmac cl-return-from name [result]
1548 This macro returns from the block named @var{name}, which must be
1549 an (unevaluated) symbol. If a @var{result} form is specified, it
1550 is evaluated to produce the result returned from the @code{block}.
1551 Otherwise, @code{nil} is returned.
1554 @defmac cl-return [result]
1555 This macro is exactly like @code{(cl-return-from nil @var{result})}.
1556 Common Lisp loops like @code{cl-do} and @code{cl-dolist} implicitly enclose
1557 themselves in @code{nil} blocks.
1564 The macros described here provide more sophisticated, high-level
1565 looping constructs to complement Emacs Lisp's basic loop forms
1566 (@pxref{Iteration,,,elisp,GNU Emacs Lisp Reference Manual}).
1568 @defmac cl-loop forms@dots{}
1569 This package supports both the simple, old-style meaning of
1570 @code{loop} and the extremely powerful and flexible feature known as
1571 the @dfn{Loop Facility} or @dfn{Loop Macro}. This more advanced
1572 facility is discussed in the following section; @pxref{Loop Facility}.
1573 The simple form of @code{loop} is described here.
1575 If @code{cl-loop} is followed by zero or more Lisp expressions,
1576 then @code{(cl-loop @var{exprs}@dots{})} simply creates an infinite
1577 loop executing the expressions over and over. The loop is
1578 enclosed in an implicit @code{nil} block. Thus,
1581 (cl-loop (foo) (if (no-more) (return 72)) (bar))
1585 is exactly equivalent to
1588 (cl-block nil (while t (foo) (if (no-more) (return 72)) (bar)))
1591 If any of the expressions are plain symbols, the loop is instead
1592 interpreted as a Loop Macro specification as described later.
1593 (This is not a restriction in practice, since a plain symbol
1594 in the above notation would simply access and throw away the
1595 value of a variable.)
1598 @defmac cl-do (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
1599 This macro creates a general iterative loop. Each @var{spec} is
1603 (@var{var} [@var{init} [@var{step}]])
1606 The loop works as follows: First, each @var{var} is bound to the
1607 associated @var{init} value as if by a @code{let} form. Then, in
1608 each iteration of the loop, the @var{end-test} is evaluated; if
1609 true, the loop is finished. Otherwise, the body @var{forms} are
1610 evaluated, then each @var{var} is set to the associated @var{step}
1611 expression (as if by a @code{cl-psetq} form) and the next iteration
1612 begins. Once the @var{end-test} becomes true, the @var{result}
1613 forms are evaluated (with the @var{var}s still bound to their
1614 values) to produce the result returned by @code{cl-do}.
1616 The entire @code{cl-do} loop is enclosed in an implicit @code{nil}
1617 block, so that you can use @code{(cl-return)} to break out of the
1620 If there are no @var{result} forms, the loop returns @code{nil}.
1621 If a given @var{var} has no @var{step} form, it is bound to its
1622 @var{init} value but not otherwise modified during the @code{cl-do}
1623 loop (unless the code explicitly modifies it); this case is just
1624 a shorthand for putting a @code{(let ((@var{var} @var{init})) @dots{})}
1625 around the loop. If @var{init} is also omitted it defaults to
1626 @code{nil}, and in this case a plain @samp{@var{var}} can be used
1627 in place of @samp{(@var{var})}, again following the analogy with
1630 This example (from Steele) illustrates a loop that applies the
1631 function @code{f} to successive pairs of values from the lists
1632 @code{foo} and @code{bar}; it is equivalent to the call
1633 @code{(cl-mapcar 'f foo bar)}. Note that this loop has no body
1634 @var{forms} at all, performing all its work as side effects of
1635 the rest of the loop.
1638 (cl-do ((x foo (cdr x))
1640 (z nil (cons (f (car x) (car y)) z)))
1641 ((or (null x) (null y))
1646 @defmac cl-do* (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
1647 This is to @code{cl-do} what @code{let*} is to @code{let}. In
1648 particular, the initial values are bound as if by @code{let*}
1649 rather than @code{let}, and the steps are assigned as if by
1650 @code{setq} rather than @code{cl-psetq}.
1652 Here is another way to write the above loop:
1655 (cl-do* ((xp foo (cdr xp))
1657 (x (car xp) (car xp))
1658 (y (car yp) (car yp))
1660 ((or (null xp) (null yp))
1666 @defmac cl-dolist (var list [result]) forms@dots{}
1667 This is exactly like the standard Emacs Lisp macro @code{dolist},
1668 but surrounds the loop with an implicit @code{nil} block.
1671 @defmac cl-dotimes (var count [result]) forms@dots{}
1672 This is exactly like the standard Emacs Lisp macro @code{dotimes},
1673 but surrounds the loop with an implicit @code{nil} block.
1674 The body is executed with @var{var} bound to the integers
1675 from zero (inclusive) to @var{count} (exclusive), in turn. Then
1676 @c FIXME lispref does not state this part explicitly, could move this there.
1677 the @code{result} form is evaluated with @var{var} bound to the total
1678 number of iterations that were done (i.e., @code{(max 0 @var{count})})
1679 to get the return value for the loop form.
1682 @defmac cl-do-symbols (var [obarray [result]]) forms@dots{}
1683 This loop iterates over all interned symbols. If @var{obarray}
1684 is specified and is not @code{nil}, it loops over all symbols in
1685 that obarray. For each symbol, the body @var{forms} are evaluated
1686 with @var{var} bound to that symbol. The symbols are visited in
1687 an unspecified order. Afterward the @var{result} form, if any,
1688 is evaluated (with @var{var} bound to @code{nil}) to get the return
1689 value. The loop is surrounded by an implicit @code{nil} block.
1692 @defmac cl-do-all-symbols (var [result]) forms@dots{}
1693 This is identical to @code{cl-do-symbols} except that the @var{obarray}
1694 argument is omitted; it always iterates over the default obarray.
1697 @xref{Mapping over Sequences}, for some more functions for
1698 iterating over vectors or lists.
1701 @section Loop Facility
1704 A common complaint with Lisp's traditional looping constructs was
1705 that they were either too simple and limited, such as @code{dotimes}
1706 or @code{while}, or too unreadable and obscure, like Common Lisp's
1709 To remedy this, Common Lisp added a construct called the ``Loop
1710 Facility'' or ``@code{loop} macro'', with an easy-to-use but very
1711 powerful and expressive syntax.
1714 * Loop Basics:: The @code{cl-loop} macro, basic clause structure.
1715 * Loop Examples:: Working examples of the @code{cl-loop} macro.
1716 * For Clauses:: Clauses introduced by @code{for} or @code{as}.
1717 * Iteration Clauses:: @code{repeat}, @code{while}, @code{thereis}, etc.
1718 * Accumulation Clauses:: @code{collect}, @code{sum}, @code{maximize}, etc.
1719 * Other Clauses:: @code{with}, @code{if}, @code{initially}, @code{finally}.
1723 @subsection Loop Basics
1726 The @code{cl-loop} macro essentially creates a mini-language within
1727 Lisp that is specially tailored for describing loops. While this
1728 language is a little strange-looking by the standards of regular Lisp,
1729 it turns out to be very easy to learn and well-suited to its purpose.
1731 Since @code{cl-loop} is a macro, all parsing of the loop language
1732 takes place at byte-compile time; compiled @code{cl-loop}s are just
1733 as efficient as the equivalent @code{while} loops written longhand.
1735 @defmac cl-loop clauses@dots{}
1736 A loop construct consists of a series of @var{clause}s, each
1737 introduced by a symbol like @code{for} or @code{do}. Clauses
1738 are simply strung together in the argument list of @code{cl-loop},
1739 with minimal extra parentheses. The various types of clauses
1740 specify initializations, such as the binding of temporary
1741 variables, actions to be taken in the loop, stepping actions,
1744 Common Lisp specifies a certain general order of clauses in a
1748 (loop @var{name-clause}
1749 @var{var-clauses}@dots{}
1750 @var{action-clauses}@dots{})
1753 The @var{name-clause} optionally gives a name to the implicit
1754 block that surrounds the loop. By default, the implicit block
1755 is named @code{nil}. The @var{var-clauses} specify what
1756 variables should be bound during the loop, and how they should
1757 be modified or iterated throughout the course of the loop. The
1758 @var{action-clauses} are things to be done during the loop, such
1759 as computing, collecting, and returning values.
1761 The Emacs version of the @code{cl-loop} macro is less restrictive about
1762 the order of clauses, but things will behave most predictably if
1763 you put the variable-binding clauses @code{with}, @code{for}, and
1764 @code{repeat} before the action clauses. As in Common Lisp,
1765 @code{initially} and @code{finally} clauses can go anywhere.
1767 Loops generally return @code{nil} by default, but you can cause
1768 them to return a value by using an accumulation clause like
1769 @code{collect}, an end-test clause like @code{always}, or an
1770 explicit @code{return} clause to jump out of the implicit block.
1771 (Because the loop body is enclosed in an implicit block, you can
1772 also use regular Lisp @code{cl-return} or @code{cl-return-from} to
1773 break out of the loop.)
1776 The following sections give some examples of the loop macro in
1777 action, and describe the particular loop clauses in great detail.
1778 Consult the second edition of Steele for additional discussion
1782 @subsection Loop Examples
1785 Before listing the full set of clauses that are allowed, let's
1786 look at a few example loops just to get a feel for the @code{cl-loop}
1790 (cl-loop for buf in (buffer-list)
1791 collect (buffer-file-name buf))
1795 This loop iterates over all Emacs buffers, using the list
1796 returned by @code{buffer-list}. For each buffer @var{buf},
1797 it calls @code{buffer-file-name} and collects the results into
1798 a list, which is then returned from the @code{cl-loop} construct.
1799 The result is a list of the file names of all the buffers in
1800 Emacs's memory. The words @code{for}, @code{in}, and @code{collect}
1801 are reserved words in the @code{cl-loop} language.
1804 (cl-loop repeat 20 do (insert "Yowsa\n"))
1808 This loop inserts the phrase ``Yowsa'' twenty times in the
1812 (cl-loop until (eobp) do (munch-line) (forward-line 1))
1816 This loop calls @code{munch-line} on every line until the end
1817 of the buffer. If point is already at the end of the buffer,
1818 the loop exits immediately.
1821 (cl-loop do (munch-line) until (eobp) do (forward-line 1))
1825 This loop is similar to the above one, except that @code{munch-line}
1826 is always called at least once.
1829 (cl-loop for x from 1 to 100
1832 finally return (list x (= y 729)))
1836 This more complicated loop searches for a number @code{x} whose
1837 square is 729. For safety's sake it only examines @code{x}
1838 values up to 100; dropping the phrase @samp{to 100} would
1839 cause the loop to count upwards with no limit. The second
1840 @code{for} clause defines @code{y} to be the square of @code{x}
1841 within the loop; the expression after the @code{=} sign is
1842 reevaluated each time through the loop. The @code{until}
1843 clause gives a condition for terminating the loop, and the
1844 @code{finally} clause says what to do when the loop finishes.
1845 (This particular example was written less concisely than it
1846 could have been, just for the sake of illustration.)
1848 Note that even though this loop contains three clauses (two
1849 @code{for}s and an @code{until}) that would have been enough to
1850 define loops all by themselves, it still creates a single loop
1851 rather than some sort of triple-nested loop. You must explicitly
1852 nest your @code{cl-loop} constructs if you want nested loops.
1855 @subsection For Clauses
1858 Most loops are governed by one or more @code{for} clauses.
1859 A @code{for} clause simultaneously describes variables to be
1860 bound, how those variables are to be stepped during the loop,
1861 and usually an end condition based on those variables.
1863 The word @code{as} is a synonym for the word @code{for}. This
1864 word is followed by a variable name, then a word like @code{from}
1865 or @code{across} that describes the kind of iteration desired.
1866 In Common Lisp, the phrase @code{being the} sometimes precedes
1867 the type of iteration; in this package both @code{being} and
1868 @code{the} are optional. The word @code{each} is a synonym
1869 for @code{the}, and the word that follows it may be singular
1870 or plural: @samp{for x being the elements of y} or
1871 @samp{for x being each element of y}. Which form you use
1872 is purely a matter of style.
1874 The variable is bound around the loop as if by @code{let}:
1878 (cl-loop for i from 1 to 10 do (do-something-with i))
1884 @item for @var{var} from @var{expr1} to @var{expr2} by @var{expr3}
1885 This type of @code{for} clause creates a counting loop. Each of
1886 the three sub-terms is optional, though there must be at least one
1887 term so that the clause is marked as a counting clause.
1889 The three expressions are the starting value, the ending value, and
1890 the step value, respectively, of the variable. The loop counts
1891 upwards by default (@var{expr3} must be positive), from @var{expr1}
1892 to @var{expr2} inclusively. If you omit the @code{from} term, the
1893 loop counts from zero; if you omit the @code{to} term, the loop
1894 counts forever without stopping (unless stopped by some other
1895 loop clause, of course); if you omit the @code{by} term, the loop
1896 counts in steps of one.
1898 You can replace the word @code{from} with @code{upfrom} or
1899 @code{downfrom} to indicate the direction of the loop. Likewise,
1900 you can replace @code{to} with @code{upto} or @code{downto}.
1901 For example, @samp{for x from 5 downto 1} executes five times
1902 with @code{x} taking on the integers from 5 down to 1 in turn.
1903 Also, you can replace @code{to} with @code{below} or @code{above},
1904 which are like @code{upto} and @code{downto} respectively except
1905 that they are exclusive rather than inclusive limits:
1908 (cl-loop for x to 10 collect x)
1909 @result{} (0 1 2 3 4 5 6 7 8 9 10)
1910 (cl-loop for x below 10 collect x)
1911 @result{} (0 1 2 3 4 5 6 7 8 9)
1914 The @code{by} value is always positive, even for downward-counting
1915 loops. Some sort of @code{from} value is required for downward
1916 loops; @samp{for x downto 5} is not a valid loop clause all by
1919 @item for @var{var} in @var{list} by @var{function}
1920 This clause iterates @var{var} over all the elements of @var{list},
1921 in turn. If you specify the @code{by} term, then @var{function}
1922 is used to traverse the list instead of @code{cdr}; it must be a
1923 function taking one argument. For example:
1926 (cl-loop for x in '(1 2 3 4 5 6) collect (* x x))
1927 @result{} (1 4 9 16 25 36)
1928 (cl-loop for x in '(1 2 3 4 5 6) by 'cddr collect (* x x))
1932 @item for @var{var} on @var{list} by @var{function}
1933 This clause iterates @var{var} over all the cons cells of @var{list}.
1936 (cl-loop for x on '(1 2 3 4) collect x)
1937 @result{} ((1 2 3 4) (2 3 4) (3 4) (4))
1940 With @code{by}, there is no real reason that the @code{on} expression
1941 must be a list. For example:
1944 (cl-loop for x on first-animal by 'next-animal collect x)
1948 where @code{(next-animal x)} takes an ``animal'' @var{x} and returns
1949 the next in the (assumed) sequence of animals, or @code{nil} if
1950 @var{x} was the last animal in the sequence.
1952 @item for @var{var} in-ref @var{list} by @var{function}
1953 This is like a regular @code{in} clause, but @var{var} becomes
1954 a @code{setf}-able ``reference'' onto the elements of the list
1955 rather than just a temporary variable. For example,
1958 (cl-loop for x in-ref my-list do (cl-incf x))
1962 increments every element of @code{my-list} in place. This clause
1963 is an extension to standard Common Lisp.
1965 @item for @var{var} across @var{array}
1966 This clause iterates @var{var} over all the elements of @var{array},
1967 which may be a vector or a string.
1970 (cl-loop for x across "aeiou"
1971 do (use-vowel (char-to-string x)))
1974 @item for @var{var} across-ref @var{array}
1975 This clause iterates over an array, with @var{var} a @code{setf}-able
1976 reference onto the elements; see @code{in-ref} above.
1978 @item for @var{var} being the elements of @var{sequence}
1979 This clause iterates over the elements of @var{sequence}, which may
1980 be a list, vector, or string. Since the type must be determined
1981 at run-time, this is somewhat less efficient than @code{in} or
1982 @code{across}. The clause may be followed by the additional term
1983 @samp{using (index @var{var2})} to cause @var{var2} to be bound to
1984 the successive indices (starting at 0) of the elements.
1986 This clause type is taken from older versions of the @code{loop} macro,
1987 and is not present in modern Common Lisp. The @samp{using (sequence @dots{})}
1988 term of the older macros is not supported.
1990 @item for @var{var} being the elements of-ref @var{sequence}
1991 This clause iterates over a sequence, with @var{var} a @code{setf}-able
1992 reference onto the elements; see @code{in-ref} above.
1994 @item for @var{var} being the symbols [of @var{obarray}]
1995 This clause iterates over symbols, either over all interned symbols
1996 or over all symbols in @var{obarray}. The loop is executed with
1997 @var{var} bound to each symbol in turn. The symbols are visited in
1998 an unspecified order.
2003 (cl-loop for sym being the symbols
2005 when (string-match "^map" (symbol-name sym))
2010 returns a list of all the functions whose names begin with @samp{map}.
2012 The Common Lisp words @code{external-symbols} and @code{present-symbols}
2013 are also recognized but are equivalent to @code{symbols} in Emacs Lisp.
2015 Due to a minor implementation restriction, it will not work to have
2016 more than one @code{for} clause iterating over symbols, hash tables,
2017 keymaps, overlays, or intervals in a given @code{cl-loop}. Fortunately,
2018 it would rarely if ever be useful to do so. It @emph{is} valid to mix
2019 one of these types of clauses with other clauses like @code{for @dots{} to}
2022 @item for @var{var} being the hash-keys of @var{hash-table}
2023 @itemx for @var{var} being the hash-values of @var{hash-table}
2024 This clause iterates over the entries in @var{hash-table} with
2025 @var{var} bound to each key, or value. A @samp{using} clause can bind
2026 a second variable to the opposite part.
2029 (cl-loop for k being the hash-keys of h
2030 using (hash-values v)
2032 (message "key %S -> value %S" k v))
2035 @item for @var{var} being the key-codes of @var{keymap}
2036 @itemx for @var{var} being the key-bindings of @var{keymap}
2037 This clause iterates over the entries in @var{keymap}.
2038 The iteration does not enter nested keymaps but does enter inherited
2040 A @code{using} clause can access both the codes and the bindings
2044 (cl-loop for c being the key-codes of (current-local-map)
2045 using (key-bindings b)
2047 (message "key %S -> binding %S" c b))
2051 @item for @var{var} being the key-seqs of @var{keymap}
2052 This clause iterates over all key sequences defined by @var{keymap}
2053 and its nested keymaps, where @var{var} takes on values which are
2054 vectors. The strings or vectors
2055 are reused for each iteration, so you must copy them if you wish to keep
2056 them permanently. You can add a @samp{using (key-bindings @dots{})}
2057 clause to get the command bindings as well.
2059 @item for @var{var} being the overlays [of @var{buffer}] @dots{}
2060 This clause iterates over the ``overlays'' of a buffer
2061 (the clause @code{extents} is synonymous
2062 with @code{overlays}). If the @code{of} term is omitted, the current
2064 This clause also accepts optional @samp{from @var{pos}} and
2065 @samp{to @var{pos}} terms, limiting the clause to overlays which
2066 overlap the specified region.
2068 @item for @var{var} being the intervals [of @var{buffer}] @dots{}
2069 This clause iterates over all intervals of a buffer with constant
2070 text properties. The variable @var{var} will be bound to conses
2071 of start and end positions, where one start position is always equal
2072 to the previous end position. The clause allows @code{of},
2073 @code{from}, @code{to}, and @code{property} terms, where the latter
2074 term restricts the search to just the specified property. The
2075 @code{of} term may specify either a buffer or a string.
2077 @item for @var{var} being the frames
2078 This clause iterates over all Emacs frames. The clause @code{screens} is
2079 a synonym for @code{frames}. The frames are visited in
2080 @code{next-frame} order starting from @code{selected-frame}.
2082 @item for @var{var} being the windows [of @var{frame}]
2083 This clause iterates over the windows (in the Emacs sense) of
2084 the current frame, or of the specified @var{frame}. It visits windows
2085 in @code{next-window} order starting from @code{selected-window}
2086 (or @code{frame-selected-window} if you specify @var{frame}).
2087 This clause treats the minibuffer window in the same way as
2088 @code{next-window} does. For greater flexibility, consider using
2089 @code{walk-windows} instead.
2091 @item for @var{var} being the buffers
2092 This clause iterates over all buffers in Emacs. It is equivalent
2093 to @samp{for @var{var} in (buffer-list)}.
2095 @item for @var{var} = @var{expr1} then @var{expr2}
2096 This clause does a general iteration. The first time through
2097 the loop, @var{var} will be bound to @var{expr1}. On the second
2098 and successive iterations it will be set by evaluating @var{expr2}
2099 (which may refer to the old value of @var{var}). For example,
2100 these two loops are effectively the same:
2103 (cl-loop for x on my-list by 'cddr do @dots{})
2104 (cl-loop for x = my-list then (cddr x) while x do @dots{})
2107 Note that this type of @code{for} clause does not imply any sort
2108 of terminating condition; the above example combines it with a
2109 @code{while} clause to tell when to end the loop.
2111 If you omit the @code{then} term, @var{expr1} is used both for
2112 the initial setting and for successive settings:
2115 (cl-loop for x = (random) when (> x 0) return x)
2119 This loop keeps taking random numbers from the @code{(random)}
2120 function until it gets a positive one, which it then returns.
2123 If you include several @code{for} clauses in a row, they are
2124 treated sequentially (as if by @code{let*} and @code{setq}).
2125 You can instead use the word @code{and} to link the clauses,
2126 in which case they are processed in parallel (as if by @code{let}
2127 and @code{cl-psetq}).
2130 (cl-loop for x below 5 for y = nil then x collect (list x y))
2131 @result{} ((0 nil) (1 1) (2 2) (3 3) (4 4))
2132 (cl-loop for x below 5 and y = nil then x collect (list x y))
2133 @result{} ((0 nil) (1 0) (2 1) (3 2) (4 3))
2137 In the first loop, @code{y} is set based on the value of @code{x}
2138 that was just set by the previous clause; in the second loop,
2139 @code{x} and @code{y} are set simultaneously so @code{y} is set
2140 based on the value of @code{x} left over from the previous time
2143 Another feature of the @code{cl-loop} macro is @emph{destructuring},
2144 similar in concept to the destructuring provided by @code{defmacro}
2145 (@pxref{Argument Lists}).
2146 The @var{var} part of any @code{for} clause can be given as a list
2147 of variables instead of a single variable. The values produced
2148 during loop execution must be lists; the values in the lists are
2149 stored in the corresponding variables.
2152 (cl-loop for (x y) in '((2 3) (4 5) (6 7)) collect (+ x y))
2156 In loop destructuring, if there are more values than variables
2157 the trailing values are ignored, and if there are more variables
2158 than values the trailing variables get the value @code{nil}.
2159 If @code{nil} is used as a variable name, the corresponding
2160 values are ignored. Destructuring may be nested, and dotted
2161 lists of variables like @code{(x . y)} are allowed, so for example
2165 (cl-loop for (key . value) in '((a . 1) (b . 2))
2170 @node Iteration Clauses
2171 @subsection Iteration Clauses
2174 Aside from @code{for} clauses, there are several other loop clauses
2175 that control the way the loop operates. They might be used by
2176 themselves, or in conjunction with one or more @code{for} clauses.
2179 @item repeat @var{integer}
2180 This clause simply counts up to the specified number using an
2181 internal temporary variable. The loops
2184 (cl-loop repeat (1+ n) do @dots{})
2185 (cl-loop for temp to n do @dots{})
2189 are identical except that the second one forces you to choose
2190 a name for a variable you aren't actually going to use.
2192 @item while @var{condition}
2193 This clause stops the loop when the specified condition (any Lisp
2194 expression) becomes @code{nil}. For example, the following two
2195 loops are equivalent, except for the implicit @code{nil} block
2196 that surrounds the second one:
2199 (while @var{cond} @var{forms}@dots{})
2200 (cl-loop while @var{cond} do @var{forms}@dots{})
2203 @item until @var{condition}
2204 This clause stops the loop when the specified condition is true,
2205 i.e., non-@code{nil}.
2207 @item always @var{condition}
2208 This clause stops the loop when the specified condition is @code{nil}.
2209 Unlike @code{while}, it stops the loop using @code{return nil} so that
2210 the @code{finally} clauses are not executed. If all the conditions
2211 were non-@code{nil}, the loop returns @code{t}:
2214 (if (cl-loop for size in size-list always (> size 10))
2219 @item never @var{condition}
2220 This clause is like @code{always}, except that the loop returns
2221 @code{t} if any conditions were false, or @code{nil} otherwise.
2223 @item thereis @var{condition}
2224 This clause stops the loop when the specified form is non-@code{nil};
2225 in this case, it returns that non-@code{nil} value. If all the
2226 values were @code{nil}, the loop returns @code{nil}.
2229 @node Accumulation Clauses
2230 @subsection Accumulation Clauses
2233 These clauses cause the loop to accumulate information about the
2234 specified Lisp @var{form}. The accumulated result is returned
2235 from the loop unless overridden, say, by a @code{return} clause.
2238 @item collect @var{form}
2239 This clause collects the values of @var{form} into a list. Several
2240 examples of @code{collect} appear elsewhere in this manual.
2242 The word @code{collecting} is a synonym for @code{collect}, and
2243 likewise for the other accumulation clauses.
2245 @item append @var{form}
2246 This clause collects lists of values into a result list using
2249 @item nconc @var{form}
2250 This clause collects lists of values into a result list by
2251 destructively modifying the lists rather than copying them.
2253 @item concat @var{form}
2254 This clause concatenates the values of the specified @var{form}
2255 into a string. (It and the following clause are extensions to
2256 standard Common Lisp.)
2258 @item vconcat @var{form}
2259 This clause concatenates the values of the specified @var{form}
2262 @item count @var{form}
2263 This clause counts the number of times the specified @var{form}
2264 evaluates to a non-@code{nil} value.
2266 @item sum @var{form}
2267 This clause accumulates the sum of the values of the specified
2268 @var{form}, which must evaluate to a number.
2270 @item maximize @var{form}
2271 This clause accumulates the maximum value of the specified @var{form},
2272 which must evaluate to a number. The return value is undefined if
2273 @code{maximize} is executed zero times.
2275 @item minimize @var{form}
2276 This clause accumulates the minimum value of the specified @var{form}.
2279 Accumulation clauses can be followed by @samp{into @var{var}} to
2280 cause the data to be collected into variable @var{var} (which is
2281 automatically @code{let}-bound during the loop) rather than an
2282 unnamed temporary variable. Also, @code{into} accumulations do
2283 not automatically imply a return value. The loop must use some
2284 explicit mechanism, such as @code{finally return}, to return
2285 the accumulated result.
2287 It is valid for several accumulation clauses of the same type to
2288 accumulate into the same place. From Steele:
2291 (cl-loop for name in '(fred sue alice joe june)
2292 for kids in '((bob ken) () () (kris sunshine) ())
2295 @result{} (fred bob ken sue alice joe kris sunshine june)
2299 @subsection Other Clauses
2302 This section describes the remaining loop clauses.
2305 @item with @var{var} = @var{value}
2306 This clause binds a variable to a value around the loop, but
2307 otherwise leaves the variable alone during the loop. The following
2308 loops are basically equivalent:
2311 (cl-loop with x = 17 do @dots{})
2312 (let ((x 17)) (cl-loop do @dots{}))
2313 (cl-loop for x = 17 then x do @dots{})
2316 Naturally, the variable @var{var} might be used for some purpose
2317 in the rest of the loop. For example:
2320 (cl-loop for x in my-list with res = nil do (push x res)
2324 This loop inserts the elements of @code{my-list} at the front of
2325 a new list being accumulated in @code{res}, then returns the
2326 list @code{res} at the end of the loop. The effect is similar
2327 to that of a @code{collect} clause, but the list gets reversed
2328 by virtue of the fact that elements are being pushed onto the
2329 front of @code{res} rather than the end.
2331 If you omit the @code{=} term, the variable is initialized to
2332 @code{nil}. (Thus the @samp{= nil} in the above example is
2335 Bindings made by @code{with} are sequential by default, as if
2336 by @code{let*}. Just like @code{for} clauses, @code{with} clauses
2337 can be linked with @code{and} to cause the bindings to be made by
2340 @item if @var{condition} @var{clause}
2341 This clause executes the following loop clause only if the specified
2342 condition is true. The following @var{clause} should be an accumulation,
2343 @code{do}, @code{return}, @code{if}, or @code{unless} clause.
2344 Several clauses may be linked by separating them with @code{and}.
2345 These clauses may be followed by @code{else} and a clause or clauses
2346 to execute if the condition was false. The whole construct may
2347 optionally be followed by the word @code{end} (which may be used to
2348 disambiguate an @code{else} or @code{and} in a nested @code{if}).
2350 The actual non-@code{nil} value of the condition form is available
2351 by the name @code{it} in the ``then'' part. For example:
2354 (setq funny-numbers '(6 13 -1))
2356 (cl-loop for x below 10
2359 and if (memq x funny-numbers) return (cdr it) end
2361 collect x into evens
2362 finally return (vector odds evens))
2363 @result{} [(1 3 5 7 9) (0 2 4 6 8)]
2364 (setq funny-numbers '(6 7 13 -1))
2365 @result{} (6 7 13 -1)
2366 (cl-loop <@r{same thing again}>)
2370 Note the use of @code{and} to put two clauses into the ``then''
2371 part, one of which is itself an @code{if} clause. Note also that
2372 @code{end}, while normally optional, was necessary here to make
2373 it clear that the @code{else} refers to the outermost @code{if}
2374 clause. In the first case, the loop returns a vector of lists
2375 of the odd and even values of @var{x}. In the second case, the
2376 odd number 7 is one of the @code{funny-numbers} so the loop
2377 returns early; the actual returned value is based on the result
2378 of the @code{memq} call.
2380 @item when @var{condition} @var{clause}
2381 This clause is just a synonym for @code{if}.
2383 @item unless @var{condition} @var{clause}
2384 The @code{unless} clause is just like @code{if} except that the
2385 sense of the condition is reversed.
2387 @item named @var{name}
2388 This clause gives a name other than @code{nil} to the implicit
2389 block surrounding the loop. The @var{name} is the symbol to be
2390 used as the block name.
2392 @item initially [do] @var{forms}@dots{}
2393 This keyword introduces one or more Lisp forms which will be
2394 executed before the loop itself begins (but after any variables
2395 requested by @code{for} or @code{with} have been bound to their
2396 initial values). @code{initially} clauses can appear anywhere;
2397 if there are several, they are executed in the order they appear
2398 in the loop. The keyword @code{do} is optional.
2400 @item finally [do] @var{forms}@dots{}
2401 This introduces Lisp forms which will be executed after the loop
2402 finishes (say, on request of a @code{for} or @code{while}).
2403 @code{initially} and @code{finally} clauses may appear anywhere
2404 in the loop construct, but they are executed (in the specified
2405 order) at the beginning or end, respectively, of the loop.
2407 @item finally return @var{form}
2408 This says that @var{form} should be executed after the loop
2409 is done to obtain a return value. (Without this, or some other
2410 clause like @code{collect} or @code{return}, the loop will simply
2411 return @code{nil}.) Variables bound by @code{for}, @code{with},
2412 or @code{into} will still contain their final values when @var{form}
2415 @item do @var{forms}@dots{}
2416 The word @code{do} may be followed by any number of Lisp expressions
2417 which are executed as an implicit @code{progn} in the body of the
2418 loop. Many of the examples in this section illustrate the use of
2421 @item return @var{form}
2422 This clause causes the loop to return immediately. The following
2423 Lisp form is evaluated to give the return value of the loop
2424 form. The @code{finally} clauses, if any, are not executed.
2425 Of course, @code{return} is generally used inside an @code{if} or
2426 @code{unless}, as its use in a top-level loop clause would mean
2427 the loop would never get to ``loop'' more than once.
2429 The clause @samp{return @var{form}} is equivalent to
2430 @samp{do (cl-return @var{form})} (or @code{cl-return-from} if the loop
2431 was named). The @code{return} clause is implemented a bit more
2432 efficiently, though.
2435 While there is no high-level way to add user extensions to @code{cl-loop},
2436 this package does offer two properties called @code{cl-loop-handler}
2437 and @code{cl-loop-for-handler} which are functions to be called when a
2438 given symbol is encountered as a top-level loop clause or @code{for}
2439 clause, respectively. Consult the source code in file
2440 @file{cl-macs.el} for details.
2442 This package's @code{cl-loop} macro is compatible with that of Common
2443 Lisp, except that a few features are not implemented: @code{loop-finish}
2444 and data-type specifiers. Naturally, the @code{for} clauses that
2445 iterate over keymaps, overlays, intervals, frames, windows, and
2446 buffers are Emacs-specific extensions.
2448 @node Multiple Values
2449 @section Multiple Values
2452 Common Lisp functions can return zero or more results. Emacs Lisp
2453 functions, by contrast, always return exactly one result. This
2454 package makes no attempt to emulate Common Lisp multiple return
2455 values; Emacs versions of Common Lisp functions that return more
2456 than one value either return just the first value (as in
2457 @code{cl-compiler-macroexpand}) or return a list of values.
2458 This package @emph{does} define placeholders
2459 for the Common Lisp functions that work with multiple values, but
2460 in Emacs Lisp these functions simply operate on lists instead.
2461 The @code{cl-values} form, for example, is a synonym for @code{list}
2464 @defmac cl-multiple-value-bind (var@dots{}) values-form forms@dots{}
2465 This form evaluates @var{values-form}, which must return a list of
2466 values. It then binds the @var{var}s to these respective values,
2467 as if by @code{let}, and then executes the body @var{forms}.
2468 If there are more @var{var}s than values, the extra @var{var}s
2469 are bound to @code{nil}. If there are fewer @var{var}s than
2470 values, the excess values are ignored.
2473 @defmac cl-multiple-value-setq (var@dots{}) form
2474 This form evaluates @var{form}, which must return a list of values.
2475 It then sets the @var{var}s to these respective values, as if by
2476 @code{setq}. Extra @var{var}s or values are treated the same as
2477 in @code{cl-multiple-value-bind}.
2480 Since a perfect emulation is not feasible in Emacs Lisp, this
2481 package opts to keep it as simple and predictable as possible.
2487 This package implements the various Common Lisp features of
2488 @code{defmacro}, such as destructuring, @code{&environment},
2489 and @code{&body}. Top-level @code{&whole} is not implemented
2490 for @code{defmacro} due to technical difficulties.
2491 @xref{Argument Lists}.
2493 Destructuring is made available to the user by way of the
2496 @defmac cl-destructuring-bind arglist expr forms@dots{}
2497 This macro expands to code that executes @var{forms}, with
2498 the variables in @var{arglist} bound to the list of values
2499 returned by @var{expr}. The @var{arglist} can include all
2500 the features allowed for @code{cl-defmacro} argument lists,
2501 including destructuring. (The @code{&environment} keyword
2502 is not allowed.) The macro expansion will signal an error
2503 if @var{expr} returns a list of the wrong number of arguments
2504 or with incorrect keyword arguments.
2507 This package also includes the Common Lisp @code{define-compiler-macro}
2508 facility, which allows you to define compile-time expansions and
2509 optimizations for your functions.
2511 @defmac cl-define-compiler-macro name arglist forms@dots{}
2512 This form is similar to @code{defmacro}, except that it only expands
2513 calls to @var{name} at compile-time; calls processed by the Lisp
2514 interpreter are not expanded, nor are they expanded by the
2515 @code{macroexpand} function.
2517 The argument list may begin with a @code{&whole} keyword and a
2518 variable. This variable is bound to the macro-call form itself,
2519 i.e., to a list of the form @samp{(@var{name} @var{args}@dots{})}.
2520 If the macro expander returns this form unchanged, then the
2521 compiler treats it as a normal function call. This allows
2522 compiler macros to work as optimizers for special cases of a
2523 function, leaving complicated cases alone.
2525 For example, here is a simplified version of a definition that
2526 appears as a standard part of this package:
2529 (cl-define-compiler-macro cl-member (&whole form a list &rest keys)
2530 (if (and (null keys)
2531 (eq (car-safe a) 'quote)
2532 (not (floatp (cadr a))))
2538 This definition causes @code{(cl-member @var{a} @var{list})} to change
2539 to a call to the faster @code{memq} in the common case where @var{a}
2540 is a non-floating-point constant; if @var{a} is anything else, or
2541 if there are any keyword arguments in the call, then the original
2542 @code{cl-member} call is left intact. (The actual compiler macro
2543 for @code{cl-member} optimizes a number of other cases, including
2544 common @code{:test} predicates.)
2547 @defun cl-compiler-macroexpand form
2548 This function is analogous to @code{macroexpand}, except that it
2549 expands compiler macros rather than regular macros. It returns
2550 @var{form} unchanged if it is not a call to a function for which
2551 a compiler macro has been defined, or if that compiler macro
2552 decided to punt by returning its @code{&whole} argument. Like
2553 @code{macroexpand}, it expands repeatedly until it reaches a form
2554 for which no further expansion is possible.
2557 @xref{Macro Bindings}, for descriptions of the @code{cl-macrolet}
2558 and @code{cl-symbol-macrolet} forms for making ``local'' macro
2562 @chapter Declarations
2565 Common Lisp includes a complex and powerful ``declaration''
2566 mechanism that allows you to give the compiler special hints
2567 about the types of data that will be stored in particular variables,
2568 and about the ways those variables and functions will be used. This
2569 package defines versions of all the Common Lisp declaration forms:
2570 @code{declare}, @code{locally}, @code{proclaim}, @code{declaim},
2573 Most of the Common Lisp declarations are not currently useful in Emacs
2574 Lisp. For example, the byte-code system provides little
2575 opportunity to benefit from type information.
2577 and @code{special} declarations are redundant in a fully
2578 dynamically-scoped Lisp.
2580 A few declarations are meaningful when byte compiler optimizations
2581 are enabled, as they are by the default. Otherwise these
2582 declarations will effectively be ignored.
2584 @defun cl-proclaim decl-spec
2585 This function records a ``global'' declaration specified by
2586 @var{decl-spec}. Since @code{cl-proclaim} is a function, @var{decl-spec}
2587 is evaluated and thus should normally be quoted.
2590 @defmac cl-declaim decl-specs@dots{}
2591 This macro is like @code{cl-proclaim}, except that it takes any number
2592 of @var{decl-spec} arguments, and the arguments are unevaluated and
2593 unquoted. The @code{cl-declaim} macro also puts @code{(cl-eval-when
2594 (compile load eval) @dots{})} around the declarations so that they will
2595 be registered at compile-time as well as at run-time. (This is vital,
2596 since normally the declarations are meant to influence the way the
2597 compiler treats the rest of the file that contains the @code{cl-declaim}
2601 @defmac cl-declare decl-specs@dots{}
2602 This macro is used to make declarations within functions and other
2603 code. Common Lisp allows declarations in various locations, generally
2604 at the beginning of any of the many ``implicit @code{progn}s''
2605 throughout Lisp syntax, such as function bodies, @code{let} bodies,
2606 etc. Currently the only declaration understood by @code{cl-declare}
2610 @defmac cl-locally declarations@dots{} forms@dots{}
2611 In this package, @code{cl-locally} is no different from @code{progn}.
2614 @defmac cl-the type form
2615 Type information provided by @code{cl-the} is ignored in this package;
2616 in other words, @code{(cl-the @var{type} @var{form})} is equivalent to
2617 @var{form}. Future byte-compiler optimizations may make use of this
2620 For example, @code{mapcar} can map over both lists and arrays. It is
2621 hard for the compiler to expand @code{mapcar} into an in-line loop
2622 unless it knows whether the sequence will be a list or an array ahead
2623 of time. With @code{(mapcar 'car (cl-the vector foo))}, a future
2624 compiler would have enough information to expand the loop in-line.
2625 For now, Emacs Lisp will treat the above code as exactly equivalent
2626 to @code{(mapcar 'car foo)}.
2629 Each @var{decl-spec} in a @code{cl-proclaim}, @code{cl-declaim}, or
2630 @code{cl-declare} should be a list beginning with a symbol that says
2631 what kind of declaration it is. This package currently understands
2632 @code{special}, @code{inline}, @code{notinline}, @code{optimize},
2633 and @code{warn} declarations. (The @code{warn} declaration is an
2634 extension of standard Common Lisp.) Other Common Lisp declarations,
2635 such as @code{type} and @code{ftype}, are silently ignored.
2640 Since all variables in Emacs Lisp are ``special'' (in the Common
2641 Lisp sense), @code{special} declarations are only advisory. They
2642 simply tell the byte compiler that the specified
2643 variables are intentionally being referred to without being
2644 bound in the body of the function. The compiler normally emits
2645 warnings for such references, since they could be typographical
2646 errors for references to local variables.
2648 The declaration @code{(cl-declare (special @var{var1} @var{var2}))} is
2649 equivalent to @code{(defvar @var{var1}) (defvar @var{var2})}.
2651 In top-level contexts, it is generally better to write
2652 @code{(defvar @var{var})} than @code{(cl-declaim (special @var{var}))},
2653 since @code{defvar} makes your intentions clearer.
2656 The @code{inline} @var{decl-spec} lists one or more functions
2657 whose bodies should be expanded ``in-line'' into calling functions
2658 whenever the compiler is able to arrange for it. For example,
2659 the function @code{cl-acons} is declared @code{inline}
2660 by this package so that the form @code{(cl-acons @var{key} @var{value}
2662 expand directly into @code{(cons (cons @var{key} @var{value}) @var{alist})}
2663 when it is called in user functions, so as to save function calls.
2665 The following declarations are all equivalent. Note that the
2666 @code{defsubst} form is a convenient way to define a function
2667 and declare it inline all at once.
2670 (cl-declaim (inline foo bar))
2671 (cl-eval-when (compile load eval)
2672 (cl-proclaim '(inline foo bar)))
2673 (defsubst foo (@dots{}) @dots{}) ; instead of defun
2676 @strong{Please note:} this declaration remains in effect after the
2677 containing source file is done. It is correct to use it to
2678 request that a function you have defined should be inlined,
2679 but it is impolite to use it to request inlining of an external
2682 In Common Lisp, it is possible to use @code{(declare (inline @dots{}))}
2683 before a particular call to a function to cause just that call to
2684 be inlined; the current byte compilers provide no way to implement
2685 this, so @code{(cl-declare (inline @dots{}))} is currently ignored by
2689 The @code{notinline} declaration lists functions which should
2690 not be inlined after all; it cancels a previous @code{inline}
2694 This declaration controls how much optimization is performed by
2697 The word @code{optimize} is followed by any number of lists like
2698 @code{(speed 3)} or @code{(safety 2)}. Common Lisp defines several
2699 optimization ``qualities''; this package ignores all but @code{speed}
2700 and @code{safety}. The value of a quality should be an integer from
2701 0 to 3, with 0 meaning ``unimportant'' and 3 meaning ``very important''.
2702 The default level for both qualities is 1.
2704 In this package, the @code{speed} quality is tied to the @code{byte-optimize}
2705 flag, which is set to @code{nil} for @code{(speed 0)} and to
2706 @code{t} for higher settings; and the @code{safety} quality is
2707 tied to the @code{byte-compile-delete-errors} flag, which is
2708 set to @code{nil} for @code{(safety 3)} and to @code{t} for all
2709 lower settings. (The latter flag controls whether the compiler
2710 is allowed to optimize out code whose only side-effect could
2711 be to signal an error, e.g., rewriting @code{(progn foo bar)} to
2712 @code{bar} when it is not known whether @code{foo} will be bound
2715 Note that even compiling with @code{(safety 0)}, the Emacs
2716 byte-code system provides sufficient checking to prevent real
2717 harm from being done. For example, barring serious bugs in
2718 Emacs itself, Emacs will not crash with a segmentation fault
2719 just because of an error in a fully-optimized Lisp program.
2721 The @code{optimize} declaration is normally used in a top-level
2722 @code{cl-proclaim} or @code{cl-declaim} in a file; Common Lisp allows
2723 it to be used with @code{declare} to set the level of optimization
2724 locally for a given form, but this will not work correctly with the
2725 current byte-compiler. (The @code{cl-declare}
2726 will set the new optimization level, but that level will not
2727 automatically be unset after the enclosing form is done.)
2730 This declaration controls what sorts of warnings are generated
2731 by the byte compiler. The word @code{warn} is followed by any
2732 number of ``warning qualities'', similar in form to optimization
2733 qualities. The currently supported warning types are
2734 @code{redefine}, @code{callargs}, @code{unresolved}, and
2735 @code{free-vars}; in the current system, a value of 0 will
2736 disable these warnings and any higher value will enable them.
2737 See the documentation of the variable @code{byte-compile-warnings}
2745 This package defines several symbol-related features that were
2746 missing from Emacs Lisp.
2749 * Property Lists:: @code{cl-get}, @code{cl-remprop}, @code{cl-getf}, @code{cl-remf}.
2750 * Creating Symbols:: @code{cl-gensym}, @code{cl-gentemp}.
2753 @node Property Lists
2754 @section Property Lists
2757 These functions augment the standard Emacs Lisp functions @code{get}
2758 and @code{put} for operating on properties attached to symbols.
2759 There are also functions for working with property lists as
2760 first-class data structures not attached to particular symbols.
2762 @defun cl-get symbol property &optional default
2763 This function is like @code{get}, except that if the property is
2764 not found, the @var{default} argument provides the return value.
2765 (The Emacs Lisp @code{get} function always uses @code{nil} as
2766 the default; this package's @code{cl-get} is equivalent to Common
2769 The @code{cl-get} function is @code{setf}-able; when used in this
2770 fashion, the @var{default} argument is allowed but ignored.
2773 @defun cl-remprop symbol property
2774 This function removes the entry for @var{property} from the property
2775 list of @var{symbol}. It returns a true value if the property was
2776 indeed found and removed, or @code{nil} if there was no such property.
2777 (This function was probably omitted from Emacs originally because,
2778 since @code{get} did not allow a @var{default}, it was very difficult
2779 to distinguish between a missing property and a property whose value
2780 was @code{nil}; thus, setting a property to @code{nil} was close
2781 enough to @code{cl-remprop} for most purposes.)
2784 @defun cl-getf place property &optional default
2785 This function scans the list @var{place} as if it were a property
2786 list, i.e., a list of alternating property names and values. If
2787 an even-numbered element of @var{place} is found which is @code{eq}
2788 to @var{property}, the following odd-numbered element is returned.
2789 Otherwise, @var{default} is returned (or @code{nil} if no default
2795 (get sym prop) @equiv{} (cl-getf (symbol-plist sym) prop)
2798 It is valid to use @code{cl-getf} as a @code{setf} place, in which case
2799 its @var{place} argument must itself be a valid @code{setf} place.
2800 The @var{default} argument, if any, is ignored in this context.
2801 The effect is to change (via @code{setcar}) the value cell in the
2802 list that corresponds to @var{property}, or to cons a new property-value
2803 pair onto the list if the property is not yet present.
2806 (put sym prop val) @equiv{} (setf (cl-getf (symbol-plist sym) prop) val)
2809 The @code{get} and @code{cl-get} functions are also @code{setf}-able.
2810 The fact that @code{default} is ignored can sometimes be useful:
2813 (cl-incf (cl-get 'foo 'usage-count 0))
2816 Here, symbol @code{foo}'s @code{usage-count} property is incremented
2817 if it exists, or set to 1 (an incremented 0) otherwise.
2819 When not used as a @code{setf} form, @code{cl-getf} is just a regular
2820 function and its @var{place} argument can actually be any Lisp
2824 @defmac cl-remf place property
2825 This macro removes the property-value pair for @var{property} from
2826 the property list stored at @var{place}, which is any @code{setf}-able
2827 place expression. It returns true if the property was found. Note
2828 that if @var{property} happens to be first on the list, this will
2829 effectively do a @code{(setf @var{place} (cddr @var{place}))},
2830 whereas if it occurs later, this simply uses @code{setcdr} to splice
2831 out the property and value cells.
2834 @node Creating Symbols
2835 @section Creating Symbols
2838 These functions create unique symbols, typically for use as
2839 temporary variables.
2841 @defun cl-gensym &optional x
2842 This function creates a new, uninterned symbol (using @code{make-symbol})
2843 with a unique name. (The name of an uninterned symbol is relevant
2844 only if the symbol is printed.) By default, the name is generated
2845 from an increasing sequence of numbers, @samp{G1000}, @samp{G1001},
2846 @samp{G1002}, etc. If the optional argument @var{x} is a string, that
2847 string is used as a prefix instead of @samp{G}. Uninterned symbols
2848 are used in macro expansions for temporary variables, to ensure that
2849 their names will not conflict with ``real'' variables in the user's
2852 (Internally, the variable @code{cl--gensym-counter} holds the counter
2853 used to generate names. It is incremented after each use. In Common
2854 Lisp this is initialized with 0, but this package initializes it with
2855 a random time-dependent value to avoid trouble when two files that
2856 each used @code{cl-gensym} in their compilation are loaded together.
2857 Uninterned symbols become interned when the compiler writes them out
2858 to a file and the Emacs loader loads them, so their names have to be
2859 treated a bit more carefully than in Common Lisp where uninterned
2860 symbols remain uninterned after loading.)
2863 @defun cl-gentemp &optional x
2864 This function is like @code{cl-gensym}, except that it produces a new
2865 @emph{interned} symbol. If the symbol that is generated already
2866 exists, the function keeps incrementing the counter and trying
2867 again until a new symbol is generated.
2870 This package automatically creates all keywords that are called for by
2871 @code{&key} argument specifiers, and discourages the use of keywords
2872 as data unrelated to keyword arguments, so the related function
2873 @code{defkeyword} (to create self-quoting keyword symbols) is not
2880 This section defines a few simple Common Lisp operations on numbers
2881 that were left out of Emacs Lisp.
2884 * Predicates on Numbers:: @code{cl-plusp}, @code{cl-oddp}, etc.
2885 * Numerical Functions:: @code{cl-floor}, @code{cl-ceiling}, etc.
2886 * Random Numbers:: @code{cl-random}, @code{cl-make-random-state}.
2887 * Implementation Parameters:: @code{cl-most-positive-float}, etc.
2890 @node Predicates on Numbers
2891 @section Predicates on Numbers
2894 These functions return @code{t} if the specified condition is
2895 true of the numerical argument, or @code{nil} otherwise.
2897 @defun cl-plusp number
2898 This predicate tests whether @var{number} is positive. It is an
2899 error if the argument is not a number.
2902 @defun cl-minusp number
2903 This predicate tests whether @var{number} is negative. It is an
2904 error if the argument is not a number.
2907 @defun cl-oddp integer
2908 This predicate tests whether @var{integer} is odd. It is an
2909 error if the argument is not an integer.
2912 @defun cl-evenp integer
2913 This predicate tests whether @var{integer} is even. It is an
2914 error if the argument is not an integer.
2917 @node Numerical Functions
2918 @section Numerical Functions
2921 These functions perform various arithmetic operations on numbers.
2923 @defun cl-gcd &rest integers
2924 This function returns the Greatest Common Divisor of the arguments.
2925 For one argument, it returns the absolute value of that argument.
2926 For zero arguments, it returns zero.
2929 @defun cl-lcm &rest integers
2930 This function returns the Least Common Multiple of the arguments.
2931 For one argument, it returns the absolute value of that argument.
2932 For zero arguments, it returns one.
2935 @defun cl-isqrt integer
2936 This function computes the ``integer square root'' of its integer
2937 argument, i.e., the greatest integer less than or equal to the true
2938 square root of the argument.
2941 @defun cl-floor number &optional divisor
2942 With one argument, @code{cl-floor} returns a list of two numbers:
2943 The argument rounded down (toward minus infinity) to an integer,
2944 and the ``remainder'' which would have to be added back to the
2945 first return value to yield the argument again. If the argument
2946 is an integer @var{x}, the result is always the list @code{(@var{x} 0)}.
2947 If the argument is a floating-point number, the first
2948 result is a Lisp integer and the second is a Lisp float between
2949 0 (inclusive) and 1 (exclusive).
2951 With two arguments, @code{cl-floor} divides @var{number} by
2952 @var{divisor}, and returns the floor of the quotient and the
2953 corresponding remainder as a list of two numbers. If
2954 @code{(cl-floor @var{x} @var{y})} returns @code{(@var{q} @var{r})},
2955 then @code{@var{q}*@var{y} + @var{r} = @var{x}}, with @var{r}
2956 between 0 (inclusive) and @var{r} (exclusive). Also, note
2957 that @code{(cl-floor @var{x})} is exactly equivalent to
2958 @code{(cl-floor @var{x} 1)}.
2960 This function is entirely compatible with Common Lisp's @code{floor}
2961 function, except that it returns the two results in a list since
2962 Emacs Lisp does not support multiple-valued functions.
2965 @defun cl-ceiling number &optional divisor
2966 This function implements the Common Lisp @code{ceiling} function,
2967 which is analogous to @code{floor} except that it rounds the
2968 argument or quotient of the arguments up toward plus infinity.
2969 The remainder will be between 0 and minus @var{r}.
2972 @defun cl-truncate number &optional divisor
2973 This function implements the Common Lisp @code{truncate} function,
2974 which is analogous to @code{floor} except that it rounds the
2975 argument or quotient of the arguments toward zero. Thus it is
2976 equivalent to @code{cl-floor} if the argument or quotient is
2977 positive, or to @code{cl-ceiling} otherwise. The remainder has
2978 the same sign as @var{number}.
2981 @defun cl-round number &optional divisor
2982 This function implements the Common Lisp @code{round} function,
2983 which is analogous to @code{floor} except that it rounds the
2984 argument or quotient of the arguments to the nearest integer.
2985 In the case of a tie (the argument or quotient is exactly
2986 halfway between two integers), it rounds to the even integer.
2989 @defun cl-mod number divisor
2990 This function returns the same value as the second return value
2994 @defun cl-rem number divisor
2995 This function returns the same value as the second return value
2996 of @code{cl-truncate}.
2999 @node Random Numbers
3000 @section Random Numbers
3003 This package also provides an implementation of the Common Lisp
3004 random number generator. It uses its own additive-congruential
3005 algorithm, which is much more likely to give statistically clean
3006 @c FIXME? Still true?
3007 random numbers than the simple generators supplied by many
3010 @defun cl-random number &optional state
3011 This function returns a random nonnegative number less than
3012 @var{number}, and of the same type (either integer or floating-point).
3013 The @var{state} argument should be a @code{random-state} object
3014 that holds the state of the random number generator. The
3015 function modifies this state object as a side effect. If
3016 @var{state} is omitted, it defaults to the internal variable
3017 @code{cl--random-state}, which contains a pre-initialized
3018 default @code{random-state} object. (Since any number of programs in
3019 the Emacs process may be accessing @code{cl--random-state} in
3020 interleaved fashion, the sequence generated from this will be
3021 irreproducible for all intents and purposes.)
3024 @defun cl-make-random-state &optional state
3025 This function creates or copies a @code{random-state} object.
3026 If @var{state} is omitted or @code{nil}, it returns a new copy of
3027 @code{cl--random-state}. This is a copy in the sense that future
3028 sequences of calls to @code{(cl-random @var{n})} and
3029 @code{(cl-random @var{n} @var{s})} (where @var{s} is the new
3030 random-state object) will return identical sequences of random
3033 If @var{state} is a @code{random-state} object, this function
3034 returns a copy of that object. If @var{state} is @code{t}, this
3035 function returns a new @code{random-state} object seeded from the
3036 date and time. As an extension to Common Lisp, @var{state} may also
3037 be an integer in which case the new object is seeded from that
3038 integer; each different integer seed will result in a completely
3039 different sequence of random numbers.
3041 It is valid to print a @code{random-state} object to a buffer or
3042 file and later read it back with @code{read}. If a program wishes
3043 to use a sequence of pseudo-random numbers which can be reproduced
3044 later for debugging, it can call @code{(cl-make-random-state t)} to
3045 get a new sequence, then print this sequence to a file. When the
3046 program is later rerun, it can read the original run's random-state
3050 @defun cl-random-state-p object
3051 This predicate returns @code{t} if @var{object} is a
3052 @code{random-state} object, or @code{nil} otherwise.
3055 @node Implementation Parameters
3056 @section Implementation Parameters
3059 This package defines several useful constants having to do with
3060 floating-point numbers.
3062 It determines their values by exercising the computer's
3063 floating-point arithmetic in various ways. Because this operation
3064 might be slow, the code for initializing them is kept in a separate
3065 function that must be called before the parameters can be used.
3067 @defun cl-float-limits
3068 This function makes sure that the Common Lisp floating-point parameters
3069 like @code{cl-most-positive-float} have been initialized. Until it is
3070 called, these parameters will be @code{nil}.
3071 @c If this version of Emacs does not support floats, the parameters will
3072 @c remain @code{nil}.
3073 If the parameters have already been initialized, the function returns
3076 The algorithm makes assumptions that will be valid for almost all
3077 machines, but will fail if the machine's arithmetic is extremely
3078 unusual, e.g., decimal.
3081 Since true Common Lisp supports up to four different floating-point
3082 precisions, it has families of constants like
3083 @code{most-positive-single-float}, @code{most-positive-double-float},
3084 @code{most-positive-long-float}, and so on. Emacs has only one
3085 floating-point precision, so this package omits the precision word
3086 from the constants' names.
3088 @defvar cl-most-positive-float
3089 This constant equals the largest value a Lisp float can hold.
3090 For those systems whose arithmetic supports infinities, this is
3091 the largest @emph{finite} value. For IEEE machines, the value
3092 is approximately @code{1.79e+308}.
3095 @defvar cl-most-negative-float
3096 This constant equals the most negative value a Lisp float can hold.
3097 (It is assumed to be equal to @code{(- cl-most-positive-float)}.)
3100 @defvar cl-least-positive-float
3101 This constant equals the smallest Lisp float value greater than zero.
3102 For IEEE machines, it is about @code{4.94e-324} if denormals are
3103 supported or @code{2.22e-308} if not.
3106 @defvar cl-least-positive-normalized-float
3107 This constant equals the smallest @emph{normalized} Lisp float greater
3108 than zero, i.e., the smallest value for which IEEE denormalization
3109 will not result in a loss of precision. For IEEE machines, this
3110 value is about @code{2.22e-308}. For machines that do not support
3111 the concept of denormalization and gradual underflow, this constant
3112 will always equal @code{cl-least-positive-float}.
3115 @defvar cl-least-negative-float
3116 This constant is the negative counterpart of @code{cl-least-positive-float}.
3119 @defvar cl-least-negative-normalized-float
3120 This constant is the negative counterpart of
3121 @code{cl-least-positive-normalized-float}.
3124 @defvar cl-float-epsilon
3125 This constant is the smallest positive Lisp float that can be added
3126 to 1.0 to produce a distinct value. Adding a smaller number to 1.0
3127 will yield 1.0 again due to roundoff. For IEEE machines, epsilon
3128 is about @code{2.22e-16}.
3131 @defvar cl-float-negative-epsilon
3132 This is the smallest positive value that can be subtracted from
3133 1.0 to produce a distinct value. For IEEE machines, it is about
3141 Common Lisp defines a number of functions that operate on
3142 @dfn{sequences}, which are either lists, strings, or vectors.
3143 Emacs Lisp includes a few of these, notably @code{elt} and
3144 @code{length}; this package defines most of the rest.
3147 * Sequence Basics:: Arguments shared by all sequence functions.
3148 * Mapping over Sequences:: @code{cl-mapcar}, @code{cl-map}, @code{cl-maplist}, etc.
3149 * Sequence Functions:: @code{cl-subseq}, @code{cl-remove}, @code{cl-substitute}, etc.
3150 * Searching Sequences:: @code{cl-find}, @code{cl-count}, @code{cl-search}, etc.
3151 * Sorting Sequences:: @code{cl-sort}, @code{cl-stable-sort}, @code{cl-merge}.
3154 @node Sequence Basics
3155 @section Sequence Basics
3158 Many of the sequence functions take keyword arguments; @pxref{Argument
3159 Lists}. All keyword arguments are optional and, if specified,
3160 may appear in any order.
3162 The @code{:key} argument should be passed either @code{nil}, or a
3163 function of one argument. This key function is used as a filter
3164 through which the elements of the sequence are seen; for example,
3165 @code{(cl-find x y :key 'car)} is similar to @code{(cl-assoc x y)}.
3166 It searches for an element of the list whose @sc{car} equals
3167 @code{x}, rather than for an element which equals @code{x} itself.
3168 If @code{:key} is omitted or @code{nil}, the filter is effectively
3169 the identity function.
3171 The @code{:test} and @code{:test-not} arguments should be either
3172 @code{nil}, or functions of two arguments. The test function is
3173 used to compare two sequence elements, or to compare a search value
3174 with sequence elements. (The two values are passed to the test
3175 function in the same order as the original sequence function
3176 arguments from which they are derived, or, if they both come from
3177 the same sequence, in the same order as they appear in that sequence.)
3178 The @code{:test} argument specifies a function which must return
3179 true (non-@code{nil}) to indicate a match; instead, you may use
3180 @code{:test-not} to give a function which returns @emph{false} to
3181 indicate a match. The default test function is @code{eql}.
3183 Many functions that take @var{item} and @code{:test} or @code{:test-not}
3184 arguments also come in @code{-if} and @code{-if-not} varieties,
3185 where a @var{predicate} function is passed instead of @var{item},
3186 and sequence elements match if the predicate returns true on them
3187 (or false in the case of @code{-if-not}). For example:
3190 (cl-remove 0 seq :test '=) @equiv{} (cl-remove-if 'zerop seq)
3194 to remove all zeros from sequence @code{seq}.
3196 Some operations can work on a subsequence of the argument sequence;
3197 these function take @code{:start} and @code{:end} arguments, which
3198 default to zero and the length of the sequence, respectively.
3199 Only elements between @var{start} (inclusive) and @var{end}
3200 (exclusive) are affected by the operation. The @var{end} argument
3201 may be passed @code{nil} to signify the length of the sequence;
3202 otherwise, both @var{start} and @var{end} must be integers, with
3203 @code{0 <= @var{start} <= @var{end} <= (length @var{seq})}.
3204 If the function takes two sequence arguments, the limits are
3205 defined by keywords @code{:start1} and @code{:end1} for the first,
3206 and @code{:start2} and @code{:end2} for the second.
3208 A few functions accept a @code{:from-end} argument, which, if
3209 non-@code{nil}, causes the operation to go from right-to-left
3210 through the sequence instead of left-to-right, and a @code{:count}
3211 argument, which specifies an integer maximum number of elements
3212 to be removed or otherwise processed.
3214 The sequence functions make no guarantees about the order in
3215 which the @code{:test}, @code{:test-not}, and @code{:key} functions
3216 are called on various elements. Therefore, it is a bad idea to depend
3217 on side effects of these functions. For example, @code{:from-end}
3218 may cause the sequence to be scanned actually in reverse, or it may
3219 be scanned forwards but computing a result ``as if'' it were scanned
3220 backwards. (Some functions, like @code{cl-mapcar} and @code{cl-every},
3221 @emph{do} specify exactly the order in which the function is called
3222 so side effects are perfectly acceptable in those cases.)
3224 Strings may contain ``text properties'' as well
3225 as character data. Except as noted, it is undefined whether or
3226 not text properties are preserved by sequence functions. For
3227 example, @code{(cl-remove ?A @var{str})} may or may not preserve
3228 the properties of the characters copied from @var{str} into the
3231 @node Mapping over Sequences
3232 @section Mapping over Sequences
3235 These functions ``map'' the function you specify over the elements
3236 of lists or arrays. They are all variations on the theme of the
3237 built-in function @code{mapcar}.
3239 @defun cl-mapcar function seq &rest more-seqs
3240 This function calls @var{function} on successive parallel sets of
3241 elements from its argument sequences. Given a single @var{seq}
3242 argument it is equivalent to @code{mapcar}; given @var{n} sequences,
3243 it calls the function with the first elements of each of the sequences
3244 as the @var{n} arguments to yield the first element of the result
3245 list, then with the second elements, and so on. The mapping stops as
3246 soon as the shortest sequence runs out. The argument sequences may
3247 be any mixture of lists, strings, and vectors; the return sequence
3250 Common Lisp's @code{mapcar} accepts multiple arguments but works
3251 only on lists; Emacs Lisp's @code{mapcar} accepts a single sequence
3252 argument. This package's @code{cl-mapcar} works as a compatible
3256 @defun cl-map result-type function seq &rest more-seqs
3257 This function maps @var{function} over the argument sequences,
3258 just like @code{cl-mapcar}, but it returns a sequence of type
3259 @var{result-type} rather than a list. @var{result-type} must
3260 be one of the following symbols: @code{vector}, @code{string},
3261 @code{list} (in which case the effect is the same as for
3262 @code{cl-mapcar}), or @code{nil} (in which case the results are
3263 thrown away and @code{cl-map} returns @code{nil}).
3266 @defun cl-maplist function list &rest more-lists
3267 This function calls @var{function} on each of its argument lists,
3268 then on the @sc{cdr}s of those lists, and so on, until the
3269 shortest list runs out. The results are returned in the form
3270 of a list. Thus, @code{cl-maplist} is like @code{cl-mapcar} except
3271 that it passes in the list pointers themselves rather than the
3272 @sc{car}s of the advancing pointers.
3275 @defun cl-mapc function seq &rest more-seqs
3276 This function is like @code{cl-mapcar}, except that the values returned
3277 by @var{function} are ignored and thrown away rather than being
3278 collected into a list. The return value of @code{cl-mapc} is @var{seq},
3279 the first sequence. This function is more general than the Emacs
3280 primitive @code{mapc}. (Note that this function is called
3281 @code{cl-mapc} even in @file{cl.el}, rather than @code{mapc*} as you
3283 @c http://debbugs.gnu.org/6575
3286 @defun cl-mapl function list &rest more-lists
3287 This function is like @code{cl-maplist}, except that it throws away
3288 the values returned by @var{function}.
3291 @defun cl-mapcan function seq &rest more-seqs
3292 This function is like @code{cl-mapcar}, except that it concatenates
3293 the return values (which must be lists) using @code{nconc},
3294 rather than simply collecting them into a list.
3297 @defun cl-mapcon function list &rest more-lists
3298 This function is like @code{cl-maplist}, except that it concatenates
3299 the return values using @code{nconc}.
3302 @defun cl-some predicate seq &rest more-seqs
3303 This function calls @var{predicate} on each element of @var{seq}
3304 in turn; if @var{predicate} returns a non-@code{nil} value,
3305 @code{cl-some} returns that value, otherwise it returns @code{nil}.
3306 Given several sequence arguments, it steps through the sequences
3307 in parallel until the shortest one runs out, just as in
3308 @code{cl-mapcar}. You can rely on the left-to-right order in which
3309 the elements are visited, and on the fact that mapping stops
3310 immediately as soon as @var{predicate} returns non-@code{nil}.
3313 @defun cl-every predicate seq &rest more-seqs
3314 This function calls @var{predicate} on each element of the sequence(s)
3315 in turn; it returns @code{nil} as soon as @var{predicate} returns
3316 @code{nil} for any element, or @code{t} if the predicate was true
3320 @defun cl-notany predicate seq &rest more-seqs
3321 This function calls @var{predicate} on each element of the sequence(s)
3322 in turn; it returns @code{nil} as soon as @var{predicate} returns
3323 a non-@code{nil} value for any element, or @code{t} if the predicate
3324 was @code{nil} for all elements.
3327 @defun cl-notevery predicate seq &rest more-seqs
3328 This function calls @var{predicate} on each element of the sequence(s)
3329 in turn; it returns a non-@code{nil} value as soon as @var{predicate}
3330 returns @code{nil} for any element, or @code{t} if the predicate was
3331 true for all elements.
3334 @defun cl-reduce function seq @t{&key :from-end :start :end :initial-value :key}
3335 This function combines the elements of @var{seq} using an associative
3336 binary operation. Suppose @var{function} is @code{*} and @var{seq} is
3337 the list @code{(2 3 4 5)}. The first two elements of the list are
3338 combined with @code{(* 2 3) = 6}; this is combined with the next
3339 element, @code{(* 6 4) = 24}, and that is combined with the final
3340 element: @code{(* 24 5) = 120}. Note that the @code{*} function happens
3341 to be self-reducing, so that @code{(* 2 3 4 5)} has the same effect as
3342 an explicit call to @code{cl-reduce}.
3344 If @code{:from-end} is true, the reduction is right-associative instead
3345 of left-associative:
3348 (cl-reduce '- '(1 2 3 4))
3349 @equiv{} (- (- (- 1 2) 3) 4) @result{} -8
3350 (cl-reduce '- '(1 2 3 4) :from-end t)
3351 @equiv{} (- 1 (- 2 (- 3 4))) @result{} -2
3354 If @code{:key} is specified, it is a function of one argument, which
3355 is called on each of the sequence elements in turn.
3357 If @code{:initial-value} is specified, it is effectively added to the
3358 front (or rear in the case of @code{:from-end}) of the sequence.
3359 The @code{:key} function is @emph{not} applied to the initial value.
3361 If the sequence, including the initial value, has exactly one element
3362 then that element is returned without ever calling @var{function}.
3363 If the sequence is empty (and there is no initial value), then
3364 @var{function} is called with no arguments to obtain the return value.
3367 All of these mapping operations can be expressed conveniently in
3368 terms of the @code{cl-loop} macro. In compiled code, @code{cl-loop} will
3369 be faster since it generates the loop as in-line code with no
3372 @node Sequence Functions
3373 @section Sequence Functions
3376 This section describes a number of Common Lisp functions for
3377 operating on sequences.
3379 @defun cl-subseq sequence start &optional end
3380 This function returns a given subsequence of the argument
3381 @var{sequence}, which may be a list, string, or vector.
3382 The indices @var{start} and @var{end} must be in range, and
3383 @var{start} must be no greater than @var{end}. If @var{end}
3384 is omitted, it defaults to the length of the sequence. The
3385 return value is always a copy; it does not share structure
3386 with @var{sequence}.
3388 As an extension to Common Lisp, @var{start} and/or @var{end}
3389 may be negative, in which case they represent a distance back
3390 from the end of the sequence. This is for compatibility with
3391 Emacs's @code{substring} function. Note that @code{cl-subseq} is
3392 the @emph{only} sequence function that allows negative
3393 @var{start} and @var{end}.
3395 You can use @code{setf} on a @code{cl-subseq} form to replace a
3396 specified range of elements with elements from another sequence.
3397 The replacement is done as if by @code{cl-replace}, described below.
3400 @defun cl-concatenate result-type &rest seqs
3401 This function concatenates the argument sequences together to
3402 form a result sequence of type @var{result-type}, one of the
3403 symbols @code{vector}, @code{string}, or @code{list}. The
3404 arguments are always copied, even in cases such as
3405 @code{(cl-concatenate 'list '(1 2 3))} where the result is
3406 identical to an argument.
3409 @defun cl-fill seq item @t{&key :start :end}
3410 This function fills the elements of the sequence (or the specified
3411 part of the sequence) with the value @var{item}.
3414 @defun cl-replace seq1 seq2 @t{&key :start1 :end1 :start2 :end2}
3415 This function copies part of @var{seq2} into part of @var{seq1}.
3416 The sequence @var{seq1} is not stretched or resized; the amount
3417 of data copied is simply the shorter of the source and destination
3418 (sub)sequences. The function returns @var{seq1}.
3420 If @var{seq1} and @var{seq2} are @code{eq}, then the replacement
3421 will work correctly even if the regions indicated by the start
3422 and end arguments overlap. However, if @var{seq1} and @var{seq2}
3423 are lists that share storage but are not @code{eq}, and the
3424 start and end arguments specify overlapping regions, the effect
3428 @defun cl-remove item seq @t{&key :test :test-not :key :count :start :end :from-end}
3429 This returns a copy of @var{seq} with all elements matching
3430 @var{item} removed. The result may share storage with or be
3431 @code{eq} to @var{seq} in some circumstances, but the original
3432 @var{seq} will not be modified. The @code{:test}, @code{:test-not},
3433 and @code{:key} arguments define the matching test that is used;
3434 by default, elements @code{eql} to @var{item} are removed. The
3435 @code{:count} argument specifies the maximum number of matching
3436 elements that can be removed (only the leftmost @var{count} matches
3437 are removed). The @code{:start} and @code{:end} arguments specify
3438 a region in @var{seq} in which elements will be removed; elements
3439 outside that region are not matched or removed. The @code{:from-end}
3440 argument, if true, says that elements should be deleted from the
3441 end of the sequence rather than the beginning (this matters only
3442 if @var{count} was also specified).
3445 @defun cl-delete item seq @t{&key :test :test-not :key :count :start :end :from-end}
3446 This deletes all elements of @var{seq} that match @var{item}.
3447 It is a destructive operation. Since Emacs Lisp does not support
3448 stretchable strings or vectors, this is the same as @code{cl-remove}
3449 for those sequence types. On lists, @code{cl-remove} will copy the
3450 list if necessary to preserve the original list, whereas
3451 @code{cl-delete} will splice out parts of the argument list.
3452 Compare @code{append} and @code{nconc}, which are analogous
3453 non-destructive and destructive list operations in Emacs Lisp.
3456 @findex cl-remove-if
3457 @findex cl-remove-if-not
3458 @findex cl-delete-if
3459 @findex cl-delete-if-not
3460 The predicate-oriented functions @code{cl-remove-if}, @code{cl-remove-if-not},
3461 @code{cl-delete-if}, and @code{cl-delete-if-not} are defined similarly.
3463 @defun cl-remove-duplicates seq @t{&key :test :test-not :key :start :end :from-end}
3464 This function returns a copy of @var{seq} with duplicate elements
3465 removed. Specifically, if two elements from the sequence match
3466 according to the @code{:test}, @code{:test-not}, and @code{:key}
3467 arguments, only the rightmost one is retained. If @code{:from-end}
3468 is true, the leftmost one is retained instead. If @code{:start} or
3469 @code{:end} is specified, only elements within that subsequence are
3470 examined or removed.
3473 @defun cl-delete-duplicates seq @t{&key :test :test-not :key :start :end :from-end}
3474 This function deletes duplicate elements from @var{seq}. It is
3475 a destructive version of @code{cl-remove-duplicates}.
3478 @defun cl-substitute new old seq @t{&key :test :test-not :key :count :start :end :from-end}
3479 This function returns a copy of @var{seq}, with all elements
3480 matching @var{old} replaced with @var{new}. The @code{:count},
3481 @code{:start}, @code{:end}, and @code{:from-end} arguments may be
3482 used to limit the number of substitutions made.
3485 @defun cl-nsubstitute new old seq @t{&key :test :test-not :key :count :start :end :from-end}
3486 This is a destructive version of @code{cl-substitute}; it performs
3487 the substitution using @code{setcar} or @code{aset} rather than
3488 by returning a changed copy of the sequence.
3491 @findex cl-substitute-if
3492 @findex cl-substitute-if-not
3493 @findex cl-nsubstitute-if
3494 @findex cl-nsubstitute-if-not
3495 The functions @code{cl-substitute-if}, @code{cl-substitute-if-not},
3496 @code{cl-nsubstitute-if}, and @code{cl-nsubstitute-if-not} are defined
3497 similarly. For these, a @var{predicate} is given in place of the
3500 @node Searching Sequences
3501 @section Searching Sequences
3504 These functions search for elements or subsequences in a sequence.
3505 (See also @code{cl-member} and @code{cl-assoc}; @pxref{Lists}.)
3507 @defun cl-find item seq @t{&key :test :test-not :key :start :end :from-end}
3508 This function searches @var{seq} for an element matching @var{item}.
3509 If it finds a match, it returns the matching element. Otherwise,
3510 it returns @code{nil}. It returns the leftmost match, unless
3511 @code{:from-end} is true, in which case it returns the rightmost
3512 match. The @code{:start} and @code{:end} arguments may be used to
3513 limit the range of elements that are searched.
3516 @defun cl-position item seq @t{&key :test :test-not :key :start :end :from-end}
3517 This function is like @code{cl-find}, except that it returns the
3518 integer position in the sequence of the matching item rather than
3519 the item itself. The position is relative to the start of the
3520 sequence as a whole, even if @code{:start} is non-zero. The function
3521 returns @code{nil} if no matching element was found.
3524 @defun cl-count item seq @t{&key :test :test-not :key :start :end}
3525 This function returns the number of elements of @var{seq} which
3526 match @var{item}. The result is always a nonnegative integer.
3530 @findex cl-find-if-not
3531 @findex cl-position-if
3532 @findex cl-position-if-not
3534 @findex cl-count-if-not
3535 The @code{cl-find-if}, @code{cl-find-if-not}, @code{cl-position-if},
3536 @code{cl-position-if-not}, @code{cl-count-if}, and @code{cl-count-if-not}
3537 functions are defined similarly.
3539 @defun cl-mismatch seq1 seq2 @t{&key :test :test-not :key :start1 :end1 :start2 :end2 :from-end}
3540 This function compares the specified parts of @var{seq1} and
3541 @var{seq2}. If they are the same length and the corresponding
3542 elements match (according to @code{:test}, @code{:test-not},
3543 and @code{:key}), the function returns @code{nil}. If there is
3544 a mismatch, the function returns the index (relative to @var{seq1})
3545 of the first mismatching element. This will be the leftmost pair of
3546 elements that do not match, or the position at which the shorter of
3547 the two otherwise-matching sequences runs out.
3549 If @code{:from-end} is true, then the elements are compared from right
3550 to left starting at @code{(1- @var{end1})} and @code{(1- @var{end2})}.
3551 If the sequences differ, then one plus the index of the rightmost
3552 difference (relative to @var{seq1}) is returned.
3554 An interesting example is @code{(cl-mismatch str1 str2 :key 'upcase)},
3555 which compares two strings case-insensitively.
3558 @defun cl-search seq1 seq2 @t{&key :test :test-not :key :from-end :start1 :end1 :start2 :end2}
3559 This function searches @var{seq2} for a subsequence that matches
3560 @var{seq1} (or part of it specified by @code{:start1} and
3561 @code{:end1}). Only matches that fall entirely within the region
3562 defined by @code{:start2} and @code{:end2} will be considered.
3563 The return value is the index of the leftmost element of the
3564 leftmost match, relative to the start of @var{seq2}, or @code{nil}
3565 if no matches were found. If @code{:from-end} is true, the
3566 function finds the @emph{rightmost} matching subsequence.
3569 @node Sorting Sequences
3570 @section Sorting Sequences
3572 @defun cl-sort seq predicate @t{&key :key}
3573 This function sorts @var{seq} into increasing order as determined
3574 by using @var{predicate} to compare pairs of elements. @var{predicate}
3575 should return true (non-@code{nil}) if and only if its first argument
3576 is less than (not equal to) its second argument. For example,
3577 @code{<} and @code{string-lessp} are suitable predicate functions
3578 for sorting numbers and strings, respectively; @code{>} would sort
3579 numbers into decreasing rather than increasing order.
3581 This function differs from Emacs's built-in @code{sort} in that it
3582 can operate on any type of sequence, not just lists. Also, it
3583 accepts a @code{:key} argument, which is used to preprocess data
3584 fed to the @var{predicate} function. For example,
3587 (setq data (cl-sort data 'string-lessp :key 'downcase))
3591 sorts @var{data}, a sequence of strings, into increasing alphabetical
3592 order without regard to case. A @code{:key} function of @code{car}
3593 would be useful for sorting association lists. It should only be a
3594 simple accessor though, since it's used heavily in the current
3597 The @code{cl-sort} function is destructive; it sorts lists by actually
3598 rearranging the @sc{cdr} pointers in suitable fashion.
3601 @defun cl-stable-sort seq predicate @t{&key :key}
3602 This function sorts @var{seq} @dfn{stably}, meaning two elements
3603 which are equal in terms of @var{predicate} are guaranteed not to
3604 be rearranged out of their original order by the sort.
3606 In practice, @code{cl-sort} and @code{cl-stable-sort} are equivalent
3607 in Emacs Lisp because the underlying @code{sort} function is
3608 stable by default. However, this package reserves the right to
3609 use non-stable methods for @code{cl-sort} in the future.
3612 @defun cl-merge type seq1 seq2 predicate @t{&key :key}
3613 This function merges two sequences @var{seq1} and @var{seq2} by
3614 interleaving their elements. The result sequence, of type @var{type}
3615 (in the sense of @code{cl-concatenate}), has length equal to the sum
3616 of the lengths of the two input sequences. The sequences may be
3617 modified destructively. Order of elements within @var{seq1} and
3618 @var{seq2} is preserved in the interleaving; elements of the two
3619 sequences are compared by @var{predicate} (in the sense of
3620 @code{sort}) and the lesser element goes first in the result.
3621 When elements are equal, those from @var{seq1} precede those from
3622 @var{seq2} in the result. Thus, if @var{seq1} and @var{seq2} are
3623 both sorted according to @var{predicate}, then the result will be
3624 a merged sequence which is (stably) sorted according to
3632 The functions described here operate on lists.
3635 * List Functions:: @code{cl-caddr}, @code{cl-first}, @code{cl-list*}, etc.
3636 * Substitution of Expressions:: @code{cl-subst}, @code{cl-sublis}, etc.
3637 * Lists as Sets:: @code{cl-member}, @code{cl-adjoin}, @code{cl-union}, etc.
3638 * Association Lists:: @code{cl-assoc}, @code{cl-acons}, @code{cl-pairlis}, etc.
3641 @node List Functions
3642 @section List Functions
3645 This section describes a number of simple operations on lists,
3646 i.e., chains of cons cells.
3649 This function is equivalent to @code{(car (cdr (cdr @var{x})))}.
3650 Likewise, this package defines all 24 @code{c@var{xxx}r} functions
3651 where @var{xxx} is up to four @samp{a}s and/or @samp{d}s.
3652 All of these functions are @code{setf}-able, and calls to them
3653 are expanded inline by the byte-compiler for maximum efficiency.
3657 This function is a synonym for @code{(car @var{x})}. Likewise,
3658 the functions @code{cl-second}, @code{cl-third}, @dots{}, through
3659 @code{cl-tenth} return the given element of the list @var{x}.
3663 This function is a synonym for @code{(cdr @var{x})}.
3667 Common Lisp defines this function to act like @code{null}, but
3668 signaling an error if @code{x} is neither a @code{nil} nor a
3669 cons cell. This package simply defines @code{cl-endp} as a synonym
3673 @defun cl-list-length x
3674 This function returns the length of list @var{x}, exactly like
3675 @code{(length @var{x})}, except that if @var{x} is a circular
3676 list (where the @sc{cdr}-chain forms a loop rather than terminating
3677 with @code{nil}), this function returns @code{nil}. (The regular
3678 @code{length} function would get stuck if given a circular list.
3679 See also the @code{safe-length} function.)
3682 @defun cl-list* arg &rest others
3683 This function constructs a list of its arguments. The final
3684 argument becomes the @sc{cdr} of the last cell constructed.
3685 Thus, @code{(cl-list* @var{a} @var{b} @var{c})} is equivalent to
3686 @code{(cons @var{a} (cons @var{b} @var{c}))}, and
3687 @code{(cl-list* @var{a} @var{b} nil)} is equivalent to
3688 @code{(list @var{a} @var{b})}.
3691 @defun cl-ldiff list sublist
3692 If @var{sublist} is a sublist of @var{list}, i.e., is @code{eq} to
3693 one of the cons cells of @var{list}, then this function returns
3694 a copy of the part of @var{list} up to but not including
3695 @var{sublist}. For example, @code{(cl-ldiff x (cddr x))} returns
3696 the first two elements of the list @code{x}. The result is a
3697 copy; the original @var{list} is not modified. If @var{sublist}
3698 is not a sublist of @var{list}, a copy of the entire @var{list}
3702 @defun cl-copy-list list
3703 This function returns a copy of the list @var{list}. It copies
3704 dotted lists like @code{(1 2 . 3)} correctly.
3707 @defun cl-tree-equal x y @t{&key :test :test-not :key}
3708 This function compares two trees of cons cells. If @var{x} and
3709 @var{y} are both cons cells, their @sc{car}s and @sc{cdr}s are
3710 compared recursively. If neither @var{x} nor @var{y} is a cons
3711 cell, they are compared by @code{eql}, or according to the
3712 specified test. The @code{:key} function, if specified, is
3713 applied to the elements of both trees. @xref{Sequences}.
3716 @node Substitution of Expressions
3717 @section Substitution of Expressions
3720 These functions substitute elements throughout a tree of cons
3721 cells. (@xref{Sequence Functions}, for the @code{cl-substitute}
3722 function, which works on just the top-level elements of a list.)
3724 @defun cl-subst new old tree @t{&key :test :test-not :key}
3725 This function substitutes occurrences of @var{old} with @var{new}
3726 in @var{tree}, a tree of cons cells. It returns a substituted
3727 tree, which will be a copy except that it may share storage with
3728 the argument @var{tree} in parts where no substitutions occurred.
3729 The original @var{tree} is not modified. This function recurses
3730 on, and compares against @var{old}, both @sc{car}s and @sc{cdr}s
3731 of the component cons cells. If @var{old} is itself a cons cell,
3732 then matching cells in the tree are substituted as usual without
3733 recursively substituting in that cell. Comparisons with @var{old}
3734 are done according to the specified test (@code{eql} by default).
3735 The @code{:key} function is applied to the elements of the tree
3736 but not to @var{old}.
3739 @defun cl-nsubst new old tree @t{&key :test :test-not :key}
3740 This function is like @code{cl-subst}, except that it works by
3741 destructive modification (by @code{setcar} or @code{setcdr})
3742 rather than copying.
3746 @findex cl-subst-if-not
3747 @findex cl-nsubst-if
3748 @findex cl-nsubst-if-not
3749 The @code{cl-subst-if}, @code{cl-subst-if-not}, @code{cl-nsubst-if}, and
3750 @code{cl-nsubst-if-not} functions are defined similarly.
3752 @defun cl-sublis alist tree @t{&key :test :test-not :key}
3753 This function is like @code{cl-subst}, except that it takes an
3754 association list @var{alist} of @var{old}-@var{new} pairs.
3755 Each element of the tree (after applying the @code{:key}
3756 function, if any), is compared with the @sc{car}s of
3757 @var{alist}; if it matches, it is replaced by the corresponding
3761 @defun cl-nsublis alist tree @t{&key :test :test-not :key}
3762 This is a destructive version of @code{cl-sublis}.
3766 @section Lists as Sets
3769 These functions perform operations on lists that represent sets
3772 @defun cl-member item list @t{&key :test :test-not :key}
3773 This function searches @var{list} for an element matching @var{item}.
3774 If a match is found, it returns the cons cell whose @sc{car} was
3775 the matching element. Otherwise, it returns @code{nil}. Elements
3776 are compared by @code{eql} by default; you can use the @code{:test},
3777 @code{:test-not}, and @code{:key} arguments to modify this behavior.
3780 The standard Emacs lisp function @code{member} uses @code{equal} for
3781 comparisons; it is equivalent to @code{(cl-member @var{item} @var{list}
3782 :test 'equal)}. With no keyword arguments, @code{cl-member} is
3783 equivalent to @code{memq}.
3786 @findex cl-member-if
3787 @findex cl-member-if-not
3788 The @code{cl-member-if} and @code{cl-member-if-not} functions
3789 analogously search for elements that satisfy a given predicate.
3791 @defun cl-tailp sublist list
3792 This function returns @code{t} if @var{sublist} is a sublist of
3793 @var{list}, i.e., if @var{sublist} is @code{eql} to @var{list} or to
3794 any of its @sc{cdr}s.
3797 @defun cl-adjoin item list @t{&key :test :test-not :key}
3798 This function conses @var{item} onto the front of @var{list},
3799 like @code{(cons @var{item} @var{list})}, but only if @var{item}
3800 is not already present on the list (as determined by @code{cl-member}).
3801 If a @code{:key} argument is specified, it is applied to
3802 @var{item} as well as to the elements of @var{list} during
3803 the search, on the reasoning that @var{item} is ``about'' to
3804 become part of the list.
3807 @defun cl-union list1 list2 @t{&key :test :test-not :key}
3808 This function combines two lists that represent sets of items,
3809 returning a list that represents the union of those two sets.
3810 The resulting list contains all items that appear in @var{list1}
3811 or @var{list2}, and no others. If an item appears in both
3812 @var{list1} and @var{list2} it is copied only once. If
3813 an item is duplicated in @var{list1} or @var{list2}, it is
3814 undefined whether or not that duplication will survive in the
3815 result list. The order of elements in the result list is also
3819 @defun cl-nunion list1 list2 @t{&key :test :test-not :key}
3820 This is a destructive version of @code{cl-union}; rather than copying,
3821 it tries to reuse the storage of the argument lists if possible.
3824 @defun cl-intersection list1 list2 @t{&key :test :test-not :key}
3825 This function computes the intersection of the sets represented
3826 by @var{list1} and @var{list2}. It returns the list of items
3827 that appear in both @var{list1} and @var{list2}.
3830 @defun cl-nintersection list1 list2 @t{&key :test :test-not :key}
3831 This is a destructive version of @code{cl-intersection}. It
3832 tries to reuse storage of @var{list1} rather than copying.
3833 It does @emph{not} reuse the storage of @var{list2}.
3836 @defun cl-set-difference list1 list2 @t{&key :test :test-not :key}
3837 This function computes the ``set difference'' of @var{list1}
3838 and @var{list2}, i.e., the set of elements that appear in
3839 @var{list1} but @emph{not} in @var{list2}.
3842 @defun cl-nset-difference list1 list2 @t{&key :test :test-not :key}
3843 This is a destructive @code{cl-set-difference}, which will try
3844 to reuse @var{list1} if possible.
3847 @defun cl-set-exclusive-or list1 list2 @t{&key :test :test-not :key}
3848 This function computes the ``set exclusive or'' of @var{list1}
3849 and @var{list2}, i.e., the set of elements that appear in
3850 exactly one of @var{list1} and @var{list2}.
3853 @defun cl-nset-exclusive-or list1 list2 @t{&key :test :test-not :key}
3854 This is a destructive @code{cl-set-exclusive-or}, which will try
3855 to reuse @var{list1} and @var{list2} if possible.
3858 @defun cl-subsetp list1 list2 @t{&key :test :test-not :key}
3859 This function checks whether @var{list1} represents a subset
3860 of @var{list2}, i.e., whether every element of @var{list1}
3861 also appears in @var{list2}.
3864 @node Association Lists
3865 @section Association Lists
3868 An @dfn{association list} is a list representing a mapping from
3869 one set of values to another; any list whose elements are cons
3870 cells is an association list.
3872 @defun cl-assoc item a-list @t{&key :test :test-not :key}
3873 This function searches the association list @var{a-list} for an
3874 element whose @sc{car} matches (in the sense of @code{:test},
3875 @code{:test-not}, and @code{:key}, or by comparison with @code{eql})
3876 a given @var{item}. It returns the matching element, if any,
3877 otherwise @code{nil}. It ignores elements of @var{a-list} that
3878 are not cons cells. (This corresponds to the behavior of
3879 @code{assq} and @code{assoc} in Emacs Lisp; Common Lisp's
3880 @code{assoc} ignores @code{nil}s but considers any other non-cons
3881 elements of @var{a-list} to be an error.)
3884 @defun cl-rassoc item a-list @t{&key :test :test-not :key}
3885 This function searches for an element whose @sc{cdr} matches
3886 @var{item}. If @var{a-list} represents a mapping, this applies
3887 the inverse of the mapping to @var{item}.
3891 @findex cl-assoc-if-not
3892 @findex cl-rassoc-if
3893 @findex cl-rassoc-if-not
3894 The @code{cl-assoc-if}, @code{cl-assoc-if-not}, @code{cl-rassoc-if},
3895 and @code{cl-rassoc-if-not} functions are defined similarly.
3897 Two simple functions for constructing association lists are:
3899 @defun cl-acons key value alist
3900 This is equivalent to @code{(cons (cons @var{key} @var{value}) @var{alist})}.
3903 @defun cl-pairlis keys values &optional alist
3904 This is equivalent to @code{(nconc (cl-mapcar 'cons @var{keys} @var{values})
3912 The Common Lisp @dfn{structure} mechanism provides a general way
3913 to define data types similar to C's @code{struct} types. A
3914 structure is a Lisp object containing some number of @dfn{slots},
3915 each of which can hold any Lisp data object. Functions are
3916 provided for accessing and setting the slots, creating or copying
3917 structure objects, and recognizing objects of a particular structure
3920 In true Common Lisp, each structure type is a new type distinct
3921 from all existing Lisp types. Since the underlying Emacs Lisp
3922 system provides no way to create new distinct types, this package
3923 implements structures as vectors (or lists upon request) with a
3924 special ``tag'' symbol to identify them.
3926 @defmac cl-defstruct name slots@dots{}
3927 The @code{cl-defstruct} form defines a new structure type called
3928 @var{name}, with the specified @var{slots}. (The @var{slots}
3929 may begin with a string which documents the structure type.)
3930 In the simplest case, @var{name} and each of the @var{slots}
3931 are symbols. For example,
3934 (cl-defstruct person name age sex)
3938 defines a struct type called @code{person} that contains three
3939 slots. Given a @code{person} object @var{p}, you can access those
3940 slots by calling @code{(person-name @var{p})}, @code{(person-age @var{p})},
3941 and @code{(person-sex @var{p})}. You can also change these slots by
3942 using @code{setf} on any of these place forms, for example:
3945 (cl-incf (person-age birthday-boy))
3948 You can create a new @code{person} by calling @code{make-person},
3949 which takes keyword arguments @code{:name}, @code{:age}, and
3950 @code{:sex} to specify the initial values of these slots in the
3951 new object. (Omitting any of these arguments leaves the corresponding
3952 slot ``undefined'', according to the Common Lisp standard; in Emacs
3953 Lisp, such uninitialized slots are filled with @code{nil}.)
3955 Given a @code{person}, @code{(copy-person @var{p})} makes a new
3956 object of the same type whose slots are @code{eq} to those of @var{p}.
3958 Given any Lisp object @var{x}, @code{(person-p @var{x})} returns
3959 true if @var{x} looks like a @code{person}, and false otherwise. (Again,
3960 in Common Lisp this predicate would be exact; in Emacs Lisp the
3961 best it can do is verify that @var{x} is a vector of the correct
3962 length that starts with the correct tag symbol.)
3964 Accessors like @code{person-name} normally check their arguments
3965 (effectively using @code{person-p}) and signal an error if the
3966 argument is the wrong type. This check is affected by
3967 @code{(optimize (safety @dots{}))} declarations. Safety level 1,
3968 the default, uses a somewhat optimized check that will detect all
3969 incorrect arguments, but may use an uninformative error message
3970 (e.g., ``expected a vector'' instead of ``expected a @code{person}'').
3971 Safety level 0 omits all checks except as provided by the underlying
3972 @code{aref} call; safety levels 2 and 3 do rigorous checking that will
3973 always print a descriptive error message for incorrect inputs.
3974 @xref{Declarations}.
3977 (setq dave (make-person :name "Dave" :sex 'male))
3978 @result{} [cl-struct-person "Dave" nil male]
3979 (setq other (copy-person dave))
3980 @result{} [cl-struct-person "Dave" nil male]
3983 (eq (person-name dave) (person-name other))
3987 (person-p [1 2 3 4])
3991 (person-p '[cl-struct-person counterfeit person object])
3995 In general, @var{name} is either a name symbol or a list of a name
3996 symbol followed by any number of @dfn{struct options}; each @var{slot}
3997 is either a slot symbol or a list of the form @samp{(@var{slot-name}
3998 @var{default-value} @var{slot-options}@dots{})}. The @var{default-value}
3999 is a Lisp form that is evaluated any time an instance of the
4000 structure type is created without specifying that slot's value.
4002 Common Lisp defines several slot options, but the only one
4003 implemented in this package is @code{:read-only}. A non-@code{nil}
4004 value for this option means the slot should not be @code{setf}-able;
4005 the slot's value is determined when the object is created and does
4006 not change afterward.
4009 (cl-defstruct person
4010 (name nil :read-only t)
4015 Any slot options other than @code{:read-only} are ignored.
4017 For obscure historical reasons, structure options take a different
4018 form than slot options. A structure option is either a keyword
4019 symbol, or a list beginning with a keyword symbol possibly followed
4020 by arguments. (By contrast, slot options are key-value pairs not
4024 (cl-defstruct (person (:constructor create-person)
4030 The following structure options are recognized.
4034 The argument is a symbol whose print name is used as the prefix for
4035 the names of slot accessor functions. The default is the name of
4036 the struct type followed by a hyphen. The option @code{(:conc-name p-)}
4037 would change this prefix to @code{p-}. Specifying @code{nil} as an
4038 argument means no prefix, so that the slot names themselves are used
4039 to name the accessor functions.
4042 In the simple case, this option takes one argument which is an
4043 alternate name to use for the constructor function. The default
4044 is @code{make-@var{name}}, e.g., @code{make-person}. The above
4045 example changes this to @code{create-person}. Specifying @code{nil}
4046 as an argument means that no standard constructor should be
4049 In the full form of this option, the constructor name is followed
4050 by an arbitrary argument list. @xref{Program Structure}, for a
4051 description of the format of Common Lisp argument lists. All
4052 options, such as @code{&rest} and @code{&key}, are supported.
4053 The argument names should match the slot names; each slot is
4054 initialized from the corresponding argument. Slots whose names
4055 do not appear in the argument list are initialized based on the
4056 @var{default-value} in their slot descriptor. Also, @code{&optional}
4057 and @code{&key} arguments that don't specify defaults take their
4058 defaults from the slot descriptor. It is valid to include arguments
4059 that don't correspond to slot names; these are useful if they are
4060 referred to in the defaults for optional, keyword, or @code{&aux}
4061 arguments that @emph{do} correspond to slots.
4063 You can specify any number of full-format @code{:constructor}
4064 options on a structure. The default constructor is still generated
4065 as well unless you disable it with a simple-format @code{:constructor}
4071 (:constructor nil) ; no default constructor
4072 (:constructor new-person
4073 (name sex &optional (age 0)))
4074 (:constructor new-hound (&key (name "Rover")
4076 &aux (age (* 7 dog-years))
4081 The first constructor here takes its arguments positionally rather
4082 than by keyword. (In official Common Lisp terminology, constructors
4083 that work By Order of Arguments instead of by keyword are called
4084 ``BOA constructors''. No, I'm not making this up.) For example,
4085 @code{(new-person "Jane" 'female)} generates a person whose slots
4086 are @code{"Jane"}, 0, and @code{female}, respectively.
4088 The second constructor takes two keyword arguments, @code{:name},
4089 which initializes the @code{name} slot and defaults to @code{"Rover"},
4090 and @code{:dog-years}, which does not itself correspond to a slot
4091 but which is used to initialize the @code{age} slot. The @code{sex}
4092 slot is forced to the symbol @code{canine} with no syntax for
4096 The argument is an alternate name for the copier function for
4097 this type. The default is @code{copy-@var{name}}. @code{nil}
4098 means not to generate a copier function. (In this implementation,
4099 all copier functions are simply synonyms for @code{copy-sequence}.)
4102 The argument is an alternate name for the predicate that recognizes
4103 objects of this type. The default is @code{@var{name}-p}. @code{nil}
4104 means not to generate a predicate function. (If the @code{:type}
4105 option is used without the @code{:named} option, no predicate is
4108 In true Common Lisp, @code{typep} is always able to recognize a
4109 structure object even if @code{:predicate} was used. In this
4110 package, @code{cl-typep} simply looks for a function called
4111 @code{@var{typename}-p}, so it will work for structure types
4112 only if they used the default predicate name.
4115 This option implements a very limited form of C++-style inheritance.
4116 The argument is the name of another structure type previously
4117 created with @code{cl-defstruct}. The effect is to cause the new
4118 structure type to inherit all of the included structure's slots
4119 (plus, of course, any new slots described by this struct's slot
4120 descriptors). The new structure is considered a ``specialization''
4121 of the included one. In fact, the predicate and slot accessors
4122 for the included type will also accept objects of the new type.
4124 If there are extra arguments to the @code{:include} option after
4125 the included-structure name, these options are treated as replacement
4126 slot descriptors for slots in the included structure, possibly with
4127 modified default values. Borrowing an example from Steele:
4130 (cl-defstruct person name (age 0) sex)
4132 (cl-defstruct (astronaut (:include person (age 45)))
4134 (favorite-beverage 'tang))
4137 (setq joe (make-person :name "Joe"))
4138 @result{} [cl-struct-person "Joe" 0 nil]
4139 (setq buzz (make-astronaut :name "Buzz"))
4140 @result{} [cl-struct-astronaut "Buzz" 45 nil nil tang]
4142 (list (person-p joe) (person-p buzz))
4144 (list (astronaut-p joe) (astronaut-p buzz))
4149 (astronaut-name joe)
4150 @result{} error: "astronaut-name accessing a non-astronaut"
4153 Thus, if @code{astronaut} is a specialization of @code{person},
4154 then every @code{astronaut} is also a @code{person} (but not the
4155 other way around). Every @code{astronaut} includes all the slots
4156 of a @code{person}, plus extra slots that are specific to
4157 astronauts. Operations that work on people (like @code{person-name})
4158 work on astronauts just like other people.
4160 @item :print-function
4161 In full Common Lisp, this option allows you to specify a function
4162 that is called to print an instance of the structure type. The
4163 Emacs Lisp system offers no hooks into the Lisp printer which would
4164 allow for such a feature, so this package simply ignores
4165 @code{:print-function}.
4168 The argument should be one of the symbols @code{vector} or @code{list}.
4169 This tells which underlying Lisp data type should be used to implement
4170 the new structure type. Vectors are used by default, but
4171 @code{(:type list)} will cause structure objects to be stored as
4174 The vector representation for structure objects has the advantage
4175 that all structure slots can be accessed quickly, although creating
4176 vectors is a bit slower in Emacs Lisp. Lists are easier to create,
4177 but take a relatively long time accessing the later slots.
4180 This option, which takes no arguments, causes a characteristic ``tag''
4181 symbol to be stored at the front of the structure object. Using
4182 @code{:type} without also using @code{:named} will result in a
4183 structure type stored as plain vectors or lists with no identifying
4186 The default, if you don't specify @code{:type} explicitly, is to
4187 use named vectors. Therefore, @code{:named} is only useful in
4188 conjunction with @code{:type}.
4191 (cl-defstruct (person1) name age sex)
4192 (cl-defstruct (person2 (:type list) :named) name age sex)
4193 (cl-defstruct (person3 (:type list)) name age sex)
4195 (setq p1 (make-person1))
4196 @result{} [cl-struct-person1 nil nil nil]
4197 (setq p2 (make-person2))
4198 @result{} (person2 nil nil nil)
4199 (setq p3 (make-person3))
4200 @result{} (nil nil nil)
4207 @result{} error: function person3-p undefined
4210 Since unnamed structures don't have tags, @code{cl-defstruct} is not
4211 able to make a useful predicate for recognizing them. Also,
4212 accessors like @code{person3-name} will be generated but they
4213 will not be able to do any type checking. The @code{person3-name}
4214 function, for example, will simply be a synonym for @code{car} in
4215 this case. By contrast, @code{person2-name} is able to verify
4216 that its argument is indeed a @code{person2} object before
4219 @item :initial-offset
4220 The argument must be a nonnegative integer. It specifies a
4221 number of slots to be left ``empty'' at the front of the
4222 structure. If the structure is named, the tag appears at the
4223 specified position in the list or vector; otherwise, the first
4224 slot appears at that position. Earlier positions are filled
4225 with @code{nil} by the constructors and ignored otherwise. If
4226 the type @code{:include}s another type, then @code{:initial-offset}
4227 specifies a number of slots to be skipped between the last slot
4228 of the included type and the first new slot.
4232 Except as noted, the @code{cl-defstruct} facility of this package is
4233 entirely compatible with that of Common Lisp.
4236 @chapter Assertions and Errors
4239 This section describes two macros that test @dfn{assertions}, i.e.,
4240 conditions which must be true if the program is operating correctly.
4241 Assertions never add to the behavior of a Lisp program; they simply
4242 make ``sanity checks'' to make sure everything is as it should be.
4244 If the optimization property @code{speed} has been set to 3, and
4245 @code{safety} is less than 3, then the byte-compiler will optimize
4246 away the following assertions. Because assertions might be optimized
4247 away, it is a bad idea for them to include side-effects.
4249 @defmac cl-assert test-form [show-args string args@dots{}]
4250 This form verifies that @var{test-form} is true (i.e., evaluates to
4251 a non-@code{nil} value). If so, it returns @code{nil}. If the test
4252 is not satisfied, @code{cl-assert} signals an error.
4254 A default error message will be supplied which includes @var{test-form}.
4255 You can specify a different error message by including a @var{string}
4256 argument plus optional extra arguments. Those arguments are simply
4257 passed to @code{error} to signal the error.
4259 If the optional second argument @var{show-args} is @code{t} instead
4260 of @code{nil}, then the error message (with or without @var{string})
4261 will also include all non-constant arguments of the top-level
4262 @var{form}. For example:
4265 (cl-assert (> x 10) t "x is too small: %d")
4268 This usage of @var{show-args} is an extension to Common Lisp. In
4269 true Common Lisp, the second argument gives a list of @var{places}
4270 which can be @code{setf}'d by the user before continuing from the
4271 error. Since Emacs Lisp does not support continuable errors, it
4272 makes no sense to specify @var{places}.
4275 @defmac cl-check-type form type [string]
4276 This form verifies that @var{form} evaluates to a value of type
4277 @var{type}. If so, it returns @code{nil}. If not, @code{cl-check-type}
4278 signals a @code{wrong-type-argument} error. The default error message
4279 lists the erroneous value along with @var{type} and @var{form}
4280 themselves. If @var{string} is specified, it is included in the
4281 error message in place of @var{type}. For example:
4284 (cl-check-type x (integer 1 *) "a positive integer")
4287 @xref{Type Predicates}, for a description of the type specifiers
4288 that may be used for @var{type}.
4290 Note that in Common Lisp, the first argument to @code{check-type}
4291 must be a @var{place} suitable for use by @code{setf}, because
4292 @code{check-type} signals a continuable error that allows the
4293 user to modify @var{place}.
4296 @node Efficiency Concerns
4297 @appendix Efficiency Concerns
4302 Many of the advanced features of this package, such as @code{cl-defun},
4303 @code{cl-loop}, etc., are implemented as Lisp macros. In
4304 byte-compiled code, these complex notations will be expanded into
4305 equivalent Lisp code which is simple and efficient. For example,
4313 is expanded at compile-time to the Lisp form
4320 which is the most efficient ways of doing this operation
4321 in Lisp. Thus, there is no performance penalty for using the more
4322 readable @code{cl-incf} form in your compiled code.
4324 @emph{Interpreted} code, on the other hand, must expand these macros
4325 every time they are executed. For this reason it is strongly
4326 recommended that code making heavy use of macros be compiled.
4327 A loop using @code{cl-incf} a hundred times will execute considerably
4328 faster if compiled, and will also garbage-collect less because the
4329 macro expansion will not have to be generated, used, and thrown away a
4332 You can find out how a macro expands by using the
4333 @code{cl-prettyexpand} function.
4335 @defun cl-prettyexpand form &optional full
4336 This function takes a single Lisp form as an argument and inserts
4337 a nicely formatted copy of it in the current buffer (which must be
4338 in Lisp mode so that indentation works properly). It also expands
4339 all Lisp macros that appear in the form. The easiest way to use
4340 this function is to go to the @file{*scratch*} buffer and type, say,
4343 (cl-prettyexpand '(cl-loop for x below 10 collect x))
4347 and type @kbd{C-x C-e} immediately after the closing parenthesis;
4348 an expansion similar to:
4355 (setq G1004 (cons x G1004))
4361 will be inserted into the buffer. (The @code{cl-block} macro is
4362 expanded differently in the interpreter and compiler, so
4363 @code{cl-prettyexpand} just leaves it alone. The temporary
4364 variable @code{G1004} was created by @code{cl-gensym}.)
4366 If the optional argument @var{full} is true, then @emph{all}
4367 macros are expanded, including @code{cl-block}, @code{cl-eval-when},
4368 and compiler macros. Expansion is done as if @var{form} were
4369 a top-level form in a file being compiled.
4371 @c FIXME none of these examples are still applicable.
4376 (cl-prettyexpand '(cl-pushnew 'x list))
4377 @print{} (setq list (cl-adjoin 'x list))
4378 (cl-prettyexpand '(cl-pushnew 'x list) t)
4379 @print{} (setq list (if (memq 'x list) list (cons 'x list)))
4380 (cl-prettyexpand '(caddr (cl-member 'a list)) t)
4381 @print{} (car (cdr (cdr (memq 'a list))))
4385 Note that @code{cl-adjoin}, @code{cl-caddr}, and @code{cl-member} all
4386 have built-in compiler macros to optimize them in common cases.
4389 @appendixsec Error Checking
4392 Common Lisp compliance has in general not been sacrificed for the
4393 sake of efficiency. A few exceptions have been made for cases
4394 where substantial gains were possible at the expense of marginal
4397 The Common Lisp standard (as embodied in Steele's book) uses the
4398 phrase ``it is an error if'' to indicate a situation that is not
4399 supposed to arise in complying programs; implementations are strongly
4400 encouraged but not required to signal an error in these situations.
4401 This package sometimes omits such error checking in the interest of
4402 compactness and efficiency. For example, @code{cl-do} variable
4403 specifiers are supposed to be lists of one, two, or three forms;
4404 extra forms are ignored by this package rather than signaling a
4405 syntax error. The @code{cl-endp} function is simply a synonym for
4406 @code{null} in this package. Functions taking keyword arguments
4407 will accept an odd number of arguments, treating the trailing
4408 keyword as if it were followed by the value @code{nil}.
4410 Argument lists (as processed by @code{cl-defun} and friends)
4411 @emph{are} checked rigorously except for the minor point just
4412 mentioned; in particular, keyword arguments are checked for
4413 validity, and @code{&allow-other-keys} and @code{:allow-other-keys}
4414 are fully implemented. Keyword validity checking is slightly
4415 time consuming (though not too bad in byte-compiled code);
4416 you can use @code{&allow-other-keys} to omit this check. Functions
4417 defined in this package such as @code{cl-find} and @code{cl-member}
4418 do check their keyword arguments for validity.
4420 @appendixsec Compiler Optimizations
4423 Changing the value of @code{byte-optimize} from the default @code{t}
4424 is highly discouraged; many of the Common
4426 code that can be improved by optimization. In particular,
4427 @code{cl-block}s (whether explicit or implicit in constructs like
4428 @code{cl-defun} and @code{cl-loop}) carry a fair run-time penalty; the
4429 byte-compiler removes @code{cl-block}s that are not actually
4430 referenced by @code{cl-return} or @code{cl-return-from} inside the block.
4432 @node Common Lisp Compatibility
4433 @appendix Common Lisp Compatibility
4436 The following is a list of all known incompatibilities between this
4437 package and Common Lisp as documented in Steele (2nd edition).
4439 The word @code{cl-defun} is required instead of @code{defun} in order
4440 to use extended Common Lisp argument lists in a function. Likewise,
4441 @code{cl-defmacro} and @code{cl-function} are versions of those forms
4442 which understand full-featured argument lists. The @code{&whole}
4443 keyword does not work in @code{cl-defmacro} argument lists (except
4444 inside recursive argument lists).
4446 The @code{equal} predicate does not distinguish
4447 between IEEE floating-point plus and minus zero. The @code{cl-equalp}
4448 predicate has several differences with Common Lisp; @pxref{Predicates}.
4450 The @code{cl-do-all-symbols} form is the same as @code{cl-do-symbols}
4451 with no @var{obarray} argument. In Common Lisp, this form would
4452 iterate over all symbols in all packages. Since Emacs obarrays
4453 are not a first-class package mechanism, there is no way for
4454 @code{cl-do-all-symbols} to locate any but the default obarray.
4456 The @code{cl-loop} macro is complete except that @code{loop-finish}
4457 and type specifiers are unimplemented.
4459 The multiple-value return facility treats lists as multiple
4460 values, since Emacs Lisp cannot support multiple return values
4461 directly. The macros will be compatible with Common Lisp if
4462 @code{cl-values} or @code{cl-values-list} is always used to return to
4463 a @code{cl-multiple-value-bind} or other multiple-value receiver;
4464 if @code{cl-values} is used without @code{cl-multiple-value-@dots{}}
4465 or vice-versa the effect will be different from Common Lisp.
4467 Many Common Lisp declarations are ignored, and others match
4468 the Common Lisp standard in concept but not in detail. For
4469 example, local @code{special} declarations, which are purely
4470 advisory in Emacs Lisp, do not rigorously obey the scoping rules
4471 set down in Steele's book.
4473 The variable @code{cl--gensym-counter} starts out with a pseudo-random
4474 value rather than with zero. This is to cope with the fact that
4475 generated symbols become interned when they are written to and
4476 loaded back from a file.
4478 The @code{cl-defstruct} facility is compatible, except that structures
4479 are of type @code{:type vector :named} by default rather than some
4480 special, distinct type. Also, the @code{:type} slot option is ignored.
4482 The second argument of @code{cl-check-type} is treated differently.
4484 @node Porting Common Lisp
4485 @appendix Porting Common Lisp
4488 This package is meant to be used as an extension to Emacs Lisp,
4489 not as an Emacs implementation of true Common Lisp. Some of the
4490 remaining differences between Emacs Lisp and Common Lisp make it
4491 difficult to port large Common Lisp applications to Emacs. For
4492 one, some of the features in this package are not fully compliant
4493 with ANSI or Steele; @pxref{Common Lisp Compatibility}. But there
4494 are also quite a few features that this package does not provide
4495 at all. Here are some major omissions that you will want to watch out
4496 for when bringing Common Lisp code into Emacs.
4500 Case-insensitivity. Symbols in Common Lisp are case-insensitive
4501 by default. Some programs refer to a function or variable as
4502 @code{foo} in one place and @code{Foo} or @code{FOO} in another.
4503 Emacs Lisp will treat these as three distinct symbols.
4505 Some Common Lisp code is written entirely in upper case. While Emacs
4506 is happy to let the program's own functions and variables use
4507 this convention, calls to Lisp builtins like @code{if} and
4508 @code{defun} will have to be changed to lower case.
4511 Lexical scoping. In Common Lisp, function arguments and @code{let}
4512 bindings apply only to references physically within their bodies (or
4513 within macro expansions in their bodies). Traditionally, Emacs Lisp
4514 uses @dfn{dynamic scoping} wherein a binding to a variable is visible
4515 even inside functions called from the body.
4516 @xref{Dynamic Binding,,,elisp,GNU Emacs Lisp Reference Manual}.
4517 Lexical binding is available since Emacs 24.1, so be sure to set
4518 @code{lexical-binding} to @code{t} if you need to emulate this aspect
4519 of Common Lisp. @xref{Lexical Binding,,,elisp,GNU Emacs Lisp Reference Manual}.
4521 Here is an example of a Common Lisp code fragment that would fail in
4522 Emacs Lisp if @code{lexical-binding} were set to @code{nil}:
4525 (defun map-odd-elements (func list)
4527 for flag = t then (not flag)
4528 collect (if flag x (funcall func x))))
4530 (defun add-odd-elements (list x)
4531 (map-odd-elements (lambda (a) (+ a x)) list))
4535 With lexical binding, the two functions' usages of @code{x} are
4536 completely independent. With dynamic binding, the binding to @code{x}
4537 made by @code{add-odd-elements} will have been hidden by the binding
4538 in @code{map-odd-elements} by the time the @code{(+ a x)} function is
4541 Internally, this package uses lexical binding so that such problems do
4542 not occur. @xref{Obsolete Lexical Binding}, for a description of the obsolete
4543 @code{lexical-let} form that emulates a Common Lisp-style lexical
4544 binding when dynamic binding is in use.
4547 Reader macros. Common Lisp includes a second type of macro that
4548 works at the level of individual characters. For example, Common
4549 Lisp implements the quote notation by a reader macro called @code{'},
4550 whereas Emacs Lisp's parser just treats quote as a special case.
4551 Some Lisp packages use reader macros to create special syntaxes
4552 for themselves, which the Emacs parser is incapable of reading.
4555 Other syntactic features. Common Lisp provides a number of
4556 notations beginning with @code{#} that the Emacs Lisp parser
4557 won't understand. For example, @samp{#| @dots{} |#} is an
4558 alternate comment notation, and @samp{#+lucid (foo)} tells
4559 the parser to ignore the @code{(foo)} except in Lucid Common
4563 Packages. In Common Lisp, symbols are divided into @dfn{packages}.
4564 Symbols that are Lisp built-ins are typically stored in one package;
4565 symbols that are vendor extensions are put in another, and each
4566 application program would have a package for its own symbols.
4567 Certain symbols are ``exported'' by a package and others are
4568 internal; certain packages ``use'' or import the exported symbols
4569 of other packages. To access symbols that would not normally be
4570 visible due to this importing and exporting, Common Lisp provides
4571 a syntax like @code{package:symbol} or @code{package::symbol}.
4573 Emacs Lisp has a single namespace for all interned symbols, and
4574 then uses a naming convention of putting a prefix like @code{cl-}
4575 in front of the name. Some Emacs packages adopt the Common Lisp-like
4576 convention of using @code{cl:} or @code{cl::} as the prefix.
4577 However, the Emacs parser does not understand colons and just
4578 treats them as part of the symbol name. Thus, while @code{mapcar}
4579 and @code{lisp:mapcar} may refer to the same symbol in Common
4580 Lisp, they are totally distinct in Emacs Lisp. Common Lisp
4581 programs that refer to a symbol by the full name sometimes
4582 and the short name other times will not port cleanly to Emacs.
4584 Emacs Lisp does have a concept of ``obarrays'', which are
4585 package-like collections of symbols, but this feature is not
4586 strong enough to be used as a true package mechanism.
4589 The @code{format} function is quite different between Common
4590 Lisp and Emacs Lisp. It takes an additional ``destination''
4591 argument before the format string. A destination of @code{nil}
4592 means to format to a string as in Emacs Lisp; a destination
4593 of @code{t} means to write to the terminal (similar to
4594 @code{message} in Emacs). Also, format control strings are
4595 utterly different; @code{~} is used instead of @code{%} to
4596 introduce format codes, and the set of available codes is
4597 much richer. There are no notations like @code{\n} for
4598 string literals; instead, @code{format} is used with the
4599 ``newline'' format code, @code{~%}. More advanced formatting
4600 codes provide such features as paragraph filling, case
4601 conversion, and even loops and conditionals.
4603 While it would have been possible to implement most of Common
4604 Lisp @code{format} in this package (under the name @code{cl-format},
4605 of course), it was not deemed worthwhile. It would have required
4606 a huge amount of code to implement even a decent subset of
4607 @code{format}, yet the functionality it would provide over
4608 Emacs Lisp's @code{format} would rarely be useful.
4611 Vector constants use square brackets in Emacs Lisp, but
4612 @code{#(a b c)} notation in Common Lisp. To further complicate
4613 matters, Emacs has its own @code{#(} notation for
4614 something entirely different---strings with properties.
4617 Characters are distinct from integers in Common Lisp. The notation
4618 for character constants is also different: @code{#\A} in Common Lisp
4619 where Emacs Lisp uses @code{?A}. Also, @code{string=} and
4620 @code{string-equal} are synonyms in Emacs Lisp, whereas the latter is
4621 case-insensitive in Common Lisp.
4624 Data types. Some Common Lisp data types do not exist in Emacs
4625 Lisp. Rational numbers and complex numbers are not present,
4626 nor are large integers (all integers are ``fixnums''). All
4627 arrays are one-dimensional. There are no readtables or pathnames;
4628 streams are a set of existing data types rather than a new data
4629 type of their own. Hash tables, random-states, structures, and
4630 packages (obarrays) are built from Lisp vectors or lists rather
4631 than being distinct types.
4634 The Common Lisp Object System (CLOS) is not implemented,
4635 nor is the Common Lisp Condition System. However, the EIEIO package
4636 (@pxref{Top, , Introduction, eieio, EIEIO}) does implement some
4640 Common Lisp features that are completely redundant with Emacs
4641 Lisp features of a different name generally have not been
4642 implemented. For example, Common Lisp writes @code{defconstant}
4643 where Emacs Lisp uses @code{defconst}. Similarly, @code{make-list}
4644 takes its arguments in different ways in the two Lisps but does
4645 exactly the same thing, so this package has not bothered to
4646 implement a Common Lisp-style @code{make-list}.
4649 A few more notable Common Lisp features not included in this
4650 package: @code{compiler-let}, @code{tagbody}, @code{prog},
4651 @code{ldb/dpb}, @code{parse-integer}, @code{cerror}.
4654 Recursion. While recursion works in Emacs Lisp just like it
4655 does in Common Lisp, various details of the Emacs Lisp system
4656 and compiler make recursion much less efficient than it is in
4657 most Lisps. Some schools of thought prefer to use recursion
4658 in Lisp over other techniques; they would sum a list of
4659 numbers using something like
4662 (defun sum-list (list)
4664 (+ (car list) (sum-list (cdr list)))
4669 where a more iteratively-minded programmer might write one of
4673 (let ((total 0)) (dolist (x my-list) (incf total x)) total)
4674 (loop for x in my-list sum x)
4677 While this would be mainly a stylistic choice in most Common Lisps,
4678 in Emacs Lisp you should be aware that the iterative forms are
4679 much faster than recursion. Also, Lisp programmers will want to
4680 note that the current Emacs Lisp compiler does not optimize tail
4684 @node Obsolete Features
4685 @appendix Obsolete Features
4687 This section describes some features of the package that are obsolete
4688 and should not be used in new code. They are either only provided by
4689 the old @file{cl.el} entry point, not by the newer @file{cl-lib.el};
4690 or where versions with a @samp{cl-} prefix do exist they do not behave
4691 in exactly the same way.
4694 * Obsolete Lexical Binding:: An approximation of lexical binding.
4695 * Obsolete Macros:: Obsolete macros.
4696 * Obsolete Setf Customization:: Obsolete ways to customize setf.
4699 @node Obsolete Lexical Binding
4700 @appendixsec Obsolete Lexical Binding
4702 The following macros are extensions to Common Lisp, where all bindings
4703 are lexical unless declared otherwise. These features are likewise
4704 obsolete since the introduction of true lexical binding in Emacs 24.1.
4706 @defmac lexical-let (bindings@dots{}) forms@dots{}
4707 This form is exactly like @code{let} except that the bindings it
4708 establishes are purely lexical.
4711 @c FIXME remove this and refer to elisp manual.
4712 @c Maybe merge some stuff from here to there?
4714 Lexical bindings are similar to local variables in a language like C:
4715 Only the code physically within the body of the @code{lexical-let}
4716 (after macro expansion) may refer to the bound variables.
4720 (defun foo (b) (+ a b))
4721 (let ((a 2)) (foo a))
4723 (lexical-let ((a 2)) (foo a))
4728 In this example, a regular @code{let} binding of @code{a} actually
4729 makes a temporary change to the global variable @code{a}, so @code{foo}
4730 is able to see the binding of @code{a} to 2. But @code{lexical-let}
4731 actually creates a distinct local variable @code{a} for use within its
4732 body, without any effect on the global variable of the same name.
4734 The most important use of lexical bindings is to create @dfn{closures}.
4735 A closure is a function object that refers to an outside lexical
4736 variable (@pxref{Closures,,,elisp,GNU Emacs Lisp Reference Manual}).
4740 (defun make-adder (n)
4741 (lexical-let ((n n))
4742 (function (lambda (m) (+ n m)))))
4743 (setq add17 (make-adder 17))
4749 The call @code{(make-adder 17)} returns a function object which adds
4750 17 to its argument. If @code{let} had been used instead of
4751 @code{lexical-let}, the function object would have referred to the
4752 global @code{n}, which would have been bound to 17 only during the
4753 call to @code{make-adder} itself.
4756 (defun make-counter ()
4757 (lexical-let ((n 0))
4758 (cl-function (lambda (&optional (m 1)) (cl-incf n m)))))
4759 (setq count-1 (make-counter))
4762 (funcall count-1 14)
4764 (setq count-2 (make-counter))
4774 Here we see that each call to @code{make-counter} creates a distinct
4775 local variable @code{n}, which serves as a private counter for the
4776 function object that is returned.
4778 Closed-over lexical variables persist until the last reference to
4779 them goes away, just like all other Lisp objects. For example,
4780 @code{count-2} refers to a function object which refers to an
4781 instance of the variable @code{n}; this is the only reference
4782 to that variable, so after @code{(setq count-2 nil)} the garbage
4783 collector would be able to delete this instance of @code{n}.
4784 Of course, if a @code{lexical-let} does not actually create any
4785 closures, then the lexical variables are free as soon as the
4786 @code{lexical-let} returns.
4788 Many closures are used only during the extent of the bindings they
4789 refer to; these are known as ``downward funargs'' in Lisp parlance.
4790 When a closure is used in this way, regular Emacs Lisp dynamic
4791 bindings suffice and will be more efficient than @code{lexical-let}
4795 (defun add-to-list (x list)
4796 (mapcar (lambda (y) (+ x y))) list)
4797 (add-to-list 7 '(1 2 5))
4802 Since this lambda is only used while @code{x} is still bound,
4803 it is not necessary to make a true closure out of it.
4805 You can use @code{defun} or @code{flet} inside a @code{lexical-let}
4806 to create a named closure. If several closures are created in the
4807 body of a single @code{lexical-let}, they all close over the same
4808 instance of the lexical variable.
4810 @defmac lexical-let* (bindings@dots{}) forms@dots{}
4811 This form is just like @code{lexical-let}, except that the bindings
4812 are made sequentially in the manner of @code{let*}.
4815 @node Obsolete Macros
4816 @appendixsec Obsolete Macros
4818 The following macros are obsolete, and are replaced by versions with
4819 a @samp{cl-} prefix that do not behave in exactly the same way.
4820 Consequently, the @file{cl.el} versions are not simply aliases to the
4821 @file{cl-lib.el} versions.
4823 @defmac flet (bindings@dots{}) forms@dots{}
4824 This macro is replaced by @code{cl-flet} (@pxref{Function Bindings}),
4825 which behaves the same way as Common Lisp's @code{flet}.
4826 This @code{flet} takes the same arguments as @code{cl-flet}, but does
4827 not behave in precisely the same way.
4829 While @code{flet} in Common Lisp establishes a lexical function
4830 binding, this @code{flet} makes a dynamic binding (it dates from a
4831 time before Emacs had lexical binding). The result is
4832 that @code{flet} affects indirect calls to a function as well as calls
4833 directly inside the @code{flet} form itself.
4835 This will even work on Emacs primitives, although note that some calls
4836 to primitive functions internal to Emacs are made without going
4837 through the symbol's function cell, and so will not be affected by
4838 @code{flet}. For example,
4841 (flet ((message (&rest args) (push args saved-msgs)))
4845 This code attempts to replace the built-in function @code{message}
4846 with a function that simply saves the messages in a list rather
4847 than displaying them. The original definition of @code{message}
4848 will be restored after @code{do-something} exits. This code will
4849 work fine on messages generated by other Lisp code, but messages
4850 generated directly inside Emacs will not be caught since they make
4851 direct C-language calls to the message routines rather than going
4852 through the Lisp @code{message} function.
4854 For those cases where the dynamic scoping of @code{flet} is desired,
4855 @code{cl-flet} is clearly not a substitute. The most direct replacement would
4856 be instead to use @code{cl-letf} to temporarily rebind @code{(symbol-function
4857 '@var{fun})}. But in most cases, a better substitute is to use an advice, such
4861 (defvar my-fun-advice-enable nil)
4862 (add-advice '@var{fun} :around
4863 (lambda (orig &rest args)
4864 (if my-fun-advice-enable (do-something)
4865 (apply orig args))))
4868 so that you can then replace the @code{flet} with a simple dynamically scoped
4869 binding of @code{my-fun-advice-enable}.
4872 Note that many primitives (e.g., @code{+}) have special byte-compile handling.
4873 Attempts to redefine such functions using @code{flet}, @code{cl-letf}, or an
4874 advice will fail when byte-compiled.
4876 @c In such cases, use @code{labels} instead.
4879 @defmac labels (bindings@dots{}) forms@dots{}
4880 This macro is replaced by @code{cl-labels} (@pxref{Function Bindings}),
4881 which behaves the same way as Common Lisp's @code{labels}.
4882 This @code{labels} takes the same arguments as @code{cl-labels}, but
4883 does not behave in precisely the same way.
4885 This version of @code{labels} uses the obsolete @code{lexical-let}
4886 form (@pxref{Obsolete Lexical Binding}), rather than the true
4887 lexical binding that @code{cl-labels} uses.
4890 @node Obsolete Setf Customization
4891 @appendixsec Obsolete Ways to Customize Setf
4893 Common Lisp defines three macros, @code{define-modify-macro},
4894 @code{defsetf}, and @code{define-setf-method}, that allow the
4895 user to extend generalized variables in various ways.
4896 In Emacs, these are obsolete, replaced by various features of
4897 @file{gv.el} in Emacs 24.3.
4898 @xref{Adding Generalized Variables,,,elisp,GNU Emacs Lisp Reference Manual}.
4901 @defmac define-modify-macro name arglist function [doc-string]
4902 This macro defines a ``read-modify-write'' macro similar to
4903 @code{cl-incf} and @code{cl-decf}. You can replace this macro
4904 with @code{gv-letplace}.
4906 The macro @var{name} is defined to take a @var{place} argument
4907 followed by additional arguments described by @var{arglist}. The call
4910 (@var{name} @var{place} @var{args}@dots{})
4917 (cl-callf @var{func} @var{place} @var{args}@dots{})
4921 which in turn is roughly equivalent to
4924 (setf @var{place} (@var{func} @var{place} @var{args}@dots{}))
4930 (define-modify-macro incf (&optional (n 1)) +)
4931 (define-modify-macro concatf (&rest args) concat)
4934 Note that @code{&key} is not allowed in @var{arglist}, but
4935 @code{&rest} is sufficient to pass keywords on to the function.
4937 Most of the modify macros defined by Common Lisp do not exactly
4938 follow the pattern of @code{define-modify-macro}. For example,
4939 @code{push} takes its arguments in the wrong order, and @code{pop}
4940 is completely irregular.
4942 The above @code{incf} example could be written using
4943 @code{gv-letplace} as:
4945 (defmacro incf (place &optional n)
4946 (gv-letplace (getter setter) place
4947 (macroexp-let2 nil v (or n 1)
4948 (funcall setter `(+ ,v ,getter)))))
4951 (defmacro concatf (place &rest args)
4952 (gv-letplace (getter setter) place
4953 (macroexp-let2 nil v (mapconcat 'identity args "")
4954 (funcall setter `(concat ,getter ,v)))))
4958 @defmac defsetf access-fn update-fn
4959 This is the simpler of two @code{defsetf} forms, and is
4960 replaced by @code{gv-define-simple-setter}.
4962 With @var{access-fn} the name of a function that accesses a place,
4963 this declares @var{update-fn} to be the corresponding store function.
4967 (setf (@var{access-fn} @var{arg1} @var{arg2} @var{arg3}) @var{value})
4974 (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} @var{value})
4978 The @var{update-fn} is required to be either a true function, or
4979 a macro that evaluates its arguments in a function-like way. Also,
4980 the @var{update-fn} is expected to return @var{value} as its result.
4981 Otherwise, the above expansion would not obey the rules for the way
4982 @code{setf} is supposed to behave.
4984 As a special (non-Common-Lisp) extension, a third argument of @code{t}
4985 to @code{defsetf} says that the return value of @code{update-fn} is
4986 not suitable, so that the above @code{setf} should be expanded to
4990 (let ((temp @var{value}))
4991 (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} temp)
4998 (defsetf car setcar)
4999 (defsetf buffer-name rename-buffer t)
5002 These translate directly to @code{gv-define-simple-setter}:
5005 (gv-define-simple-setter car setcar)
5006 (gv-define-simple-setter buffer-name rename-buffer t)
5010 @defmac defsetf access-fn arglist (store-var) forms@dots{}
5011 This is the second, more complex, form of @code{defsetf}.
5012 It can be replaced by @code{gv-define-setter}.
5014 This form of @code{defsetf} is rather like @code{defmacro} except for
5015 the additional @var{store-var} argument. The @var{forms} should
5016 return a Lisp form that stores the value of @var{store-var} into the
5017 generalized variable formed by a call to @var{access-fn} with
5018 arguments described by @var{arglist}. The @var{forms} may begin with
5019 a string which documents the @code{setf} method (analogous to the doc
5020 string that appears at the front of a function).
5022 For example, the simple form of @code{defsetf} is shorthand for
5025 (defsetf @var{access-fn} (&rest args) (store)
5026 (append '(@var{update-fn}) args (list store)))
5029 The Lisp form that is returned can access the arguments from
5030 @var{arglist} and @var{store-var} in an unrestricted fashion;
5031 macros like @code{cl-incf} that invoke this
5032 setf-method will insert temporary variables as needed to make
5033 sure the apparent order of evaluation is preserved.
5035 Another standard example:
5038 (defsetf nth (n x) (store)
5039 `(setcar (nthcdr ,n ,x) ,store))
5042 You could write this using @code{gv-define-setter} as:
5045 (gv-define-setter nth (store n x)
5046 `(setcar (nthcdr ,n ,x) ,store))
5050 @defmac define-setf-method access-fn arglist forms@dots{}
5051 This is the most general way to create new place forms. You can
5052 replace this by @code{gv-define-setter} or @code{gv-define-expander}.
5054 When a @code{setf} to @var{access-fn} with arguments described by
5055 @var{arglist} is expanded, the @var{forms} are evaluated and must
5056 return a list of five items:
5060 A list of @dfn{temporary variables}.
5063 A list of @dfn{value forms} corresponding to the temporary variables
5064 above. The temporary variables will be bound to these value forms
5065 as the first step of any operation on the generalized variable.
5068 A list of exactly one @dfn{store variable} (generally obtained
5069 from a call to @code{gensym}).
5072 A Lisp form that stores the contents of the store variable into
5073 the generalized variable, assuming the temporaries have been
5074 bound as described above.
5077 A Lisp form that accesses the contents of the generalized variable,
5078 assuming the temporaries have been bound.
5081 This is exactly like the Common Lisp macro of the same name,
5082 except that the method returns a list of five values rather
5083 than the five values themselves, since Emacs Lisp does not
5084 support Common Lisp's notion of multiple return values.
5085 (Note that the @code{setf} implementation provided by @file{gv.el}
5086 does not use this five item format. Its use here is only for
5087 backwards compatibility.)
5089 Once again, the @var{forms} may begin with a documentation string.
5091 A setf-method should be maximally conservative with regard to
5092 temporary variables. In the setf-methods generated by
5093 @code{defsetf}, the second return value is simply the list of
5094 arguments in the place form, and the first return value is a
5095 list of a corresponding number of temporary variables generated
5096 @c FIXME I don't think this is true anymore.
5097 by @code{cl-gensym}. Macros like @code{cl-incf} that
5098 use this setf-method will optimize away most temporaries that
5099 turn out to be unnecessary, so there is little reason for the
5100 setf-method itself to optimize.
5103 @c Removed in Emacs 24.3, not possible to make a compatible replacement.
5105 @defun get-setf-method place &optional env
5106 This function returns the setf-method for @var{place}, by
5107 invoking the definition previously recorded by @code{defsetf}
5108 or @code{define-setf-method}. The result is a list of five
5109 values as described above. You can use this function to build
5110 your own @code{cl-incf}-like modify macros.
5112 The argument @var{env} specifies the ``environment'' to be
5113 passed on to @code{macroexpand} if @code{get-setf-method} should
5114 need to expand a macro in @var{place}. It should come from
5115 an @code{&environment} argument to the macro or setf-method
5116 that called @code{get-setf-method}.
5121 @node GNU Free Documentation License
5122 @appendix GNU Free Documentation License
5123 @include doclicense.texi
5125 @node Function Index
5126 @unnumbered Function Index
5130 @node Variable Index
5131 @unnumbered Variable Index