1 \input texinfo @c -*-texinfo-*-
2 @setfilename ../../info/cl
3 @settitle Common Lisp Extensions
4 @documentencoding UTF-8
8 This file documents the GNU Emacs Common Lisp emulation package.
10 Copyright @copyright{} 1993, 2001--2014 Free Software Foundation, Inc.
13 Permission is granted to copy, distribute and/or modify this document
14 under the terms of the GNU Free Documentation License, Version 1.3 or
15 any later version published by the Free Software Foundation; with no
16 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
17 and with the Back-Cover Texts as in (a) below. A copy of the license
18 is included in the section entitled ``GNU Free Documentation License''.
20 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
21 modify this GNU manual.''
25 @dircategory Emacs lisp libraries
27 * CL: (cl). Partial Common Lisp support for Emacs Lisp.
34 @center @titlefont{Common Lisp Extensions}
36 @center For GNU Emacs Lisp
38 @center as distributed with Emacs @value{EMACSVER}
40 @center Dave Gillespie
41 @center daveg@@synaptics.com
43 @vskip 0pt plus 1filll
51 @top GNU Emacs Common Lisp Emulation
57 * Overview:: Basics, usage, organization, naming conventions.
58 * Program Structure:: Arglists, @code{cl-eval-when}.
59 * Predicates:: Type predicates and equality predicates.
60 * Control Structure:: Assignment, conditionals, blocks, looping.
61 * Macros:: Destructuring, compiler macros.
62 * Declarations:: @code{cl-proclaim}, @code{cl-declare}, etc.
63 * Symbols:: Property lists, creating symbols.
64 * Numbers:: Predicates, functions, random numbers.
65 * Sequences:: Mapping, functions, searching, sorting.
66 * Lists:: Functions, substitution, sets, associations.
67 * Structures:: @code{cl-defstruct}.
68 * Assertions:: Assertions and type checking.
71 * Efficiency Concerns:: Hints and techniques.
72 * Common Lisp Compatibility:: All known differences with Steele.
73 * Porting Common Lisp:: Hints for porting Common Lisp code.
74 * Obsolete Features:: Obsolete features.
75 * GNU Free Documentation License:: The license for this documentation.
78 * Function Index:: An entry for each documented function.
79 * Variable Index:: An entry for each documented variable.
86 This document describes a set of Emacs Lisp facilities borrowed from
87 Common Lisp. All the facilities are described here in detail. While
88 this document does not assume any prior knowledge of Common Lisp, it
89 does assume a basic familiarity with Emacs Lisp.
91 Common Lisp is a huge language, and Common Lisp systems tend to be
92 massive and extremely complex. Emacs Lisp, by contrast, is rather
93 minimalist in the choice of Lisp features it offers the programmer.
94 As Emacs Lisp programmers have grown in number, and the applications
95 they write have grown more ambitious, it has become clear that Emacs
96 Lisp could benefit from many of the conveniences of Common Lisp.
98 The @dfn{CL} package adds a number of Common Lisp functions and
99 control structures to Emacs Lisp. While not a 100% complete
100 implementation of Common Lisp, it adds enough functionality
101 to make Emacs Lisp programming significantly more convenient.
103 Some Common Lisp features have been omitted from this package
108 Some features are too complex or bulky relative to their benefit
109 to Emacs Lisp programmers. CLOS and Common Lisp streams are fine
110 examples of this group. (The separate package EIEIO implements
111 a subset of CLOS functionality. @xref{Top, , Introduction, eieio, EIEIO}.)
114 Other features cannot be implemented without modification to the
115 Emacs Lisp interpreter itself, such as multiple return values,
116 case-insensitive symbols, and complex numbers.
117 This package generally makes no attempt to emulate these features.
121 This package was originally written by Dave Gillespie,
122 @file{daveg@@synaptics.com}, as a total rewrite of an earlier 1986
123 @file{cl.el} package by Cesar Quiroz. Care has been taken to ensure
124 that each function is defined efficiently, concisely, and with minimal
125 impact on the rest of the Emacs environment. Stefan Monnier added the
126 file @file{cl-lib.el} and rationalized the namespace for Emacs 24.3.
129 * Usage:: How to use this package.
130 * Organization:: The package's component files.
131 * Naming Conventions:: Notes on function names.
138 This package is distributed with Emacs, so there is no need
139 to install any additional files in order to start using it. Lisp code
140 that uses features from this package should simply include at
148 You may wish to add such a statement to your init file, if you
149 make frequent use of features from this package.
152 @section Organization
155 The Common Lisp package is organized into four main files:
159 This is the main file, which contains basic functions
160 and information about the package. This file is relatively compact.
163 This file contains the larger, more complex or unusual functions.
164 It is kept separate so that packages which only want to use Common
165 Lisp fundamentals like the @code{cl-incf} function won't need to pay
166 the overhead of loading the more advanced functions.
169 This file contains most of the advanced functions for operating
170 on sequences or lists, such as @code{cl-delete-if} and @code{cl-assoc}.
173 This file contains the features that are macros instead of functions.
174 Macros expand when the caller is compiled, not when it is run, so the
175 macros generally only need to be present when the byte-compiler is
176 running (or when the macros are used in uncompiled code). Most of the
177 macros of this package are isolated in @file{cl-macs.el} so that they
178 won't take up memory unless you are compiling.
181 The file @file{cl-lib.el} includes all necessary @code{autoload}
182 commands for the functions and macros in the other three files.
183 All you have to do is @code{(require 'cl-lib)}, and @file{cl-lib.el}
184 will take care of pulling in the other files when they are
187 There is another file, @file{cl.el}, which was the main entry point to
188 this package prior to Emacs 24.3. Nowadays, it is replaced by
189 @file{cl-lib.el}. The two provide the same features (in most cases),
190 but use different function names (in fact, @file{cl.el} mainly just
191 defines aliases to the @file{cl-lib.el} definitions). Where
192 @file{cl-lib.el} defines a function called, for example,
193 @code{cl-incf}, @file{cl.el} uses the same name but without the
194 @samp{cl-} prefix, e.g., @code{incf} in this example. There are a few
195 exceptions to this. First, functions such as @code{cl-defun} where
196 the unprefixed version was already used for a standard Emacs Lisp
197 function. In such cases, the @file{cl.el} version adds a @samp{*}
198 suffix, e.g., @code{defun*}. Second, there are some obsolete features
199 that are only implemented in @file{cl.el}, not in @file{cl-lib.el},
200 because they are replaced by other standard Emacs Lisp features.
201 Finally, in a very few cases the old @file{cl.el} versions do not
202 behave in exactly the same way as the @file{cl-lib.el} versions.
203 @xref{Obsolete Features}.
204 @c There is also cl-mapc, which was called cl-mapc even before cl-lib.el.
205 @c But not autoloaded, so maybe not much used?
207 Since the old @file{cl.el} does not use a clean namespace, Emacs has a
208 policy that packages distributed with Emacs must not load @code{cl} at
209 run time. (It is ok for them to load @code{cl} at @emph{compile}
210 time, with @code{eval-when-compile}, and use the macros it provides.)
211 There is no such restriction on the use of @code{cl-lib}. New code
212 should use @code{cl-lib} rather than @code{cl}.
214 There is one more file, @file{cl-compat.el}, which defines some
215 routines from the older Quiroz @file{cl.el} package that are not otherwise
216 present in the new package. This file is obsolete and should not be
219 @node Naming Conventions
220 @section Naming Conventions
223 Except where noted, all functions defined by this package have the
224 same calling conventions as their Common Lisp counterparts, and
225 names that are those of Common Lisp plus a @samp{cl-} prefix.
227 Internal function and variable names in the package are prefixed
228 by @code{cl--}. Here is a complete list of functions prefixed by
229 @code{cl-} that were @emph{not} taken from Common Lisp:
232 cl-callf cl-callf2 cl-defsubst
236 @c This is not uninteresting I suppose, but is of zero practical relevance
237 @c to the user, and seems like a hostage to changing implementation details.
238 The following simple functions and macros are defined in @file{cl-lib.el};
239 they do not cause other components like @file{cl-extra} to be loaded.
242 cl-evenp cl-oddp cl-minusp
243 cl-plusp cl-endp cl-subst
244 cl-copy-list cl-list* cl-ldiff
245 cl-rest cl-decf [1] cl-incf [1]
246 cl-acons cl-adjoin [2] cl-pairlis
247 cl-pushnew [1,2] cl-declaim cl-proclaim
248 cl-caaar@dots{}cl-cddddr cl-first@dots{}cl-tenth
253 [1] Only when @var{place} is a plain variable name.
256 [2] Only if @code{:test} is @code{eq}, @code{equal}, or unspecified,
257 and @code{:key} is not used.
260 [3] Only for one sequence argument or two list arguments.
262 @node Program Structure
263 @chapter Program Structure
266 This section describes features of this package that have to
267 do with programs as a whole: advanced argument lists for functions,
268 and the @code{cl-eval-when} construct.
271 * Argument Lists:: @code{&key}, @code{&aux}, @code{cl-defun}, @code{cl-defmacro}.
272 * Time of Evaluation:: The @code{cl-eval-when} construct.
276 @section Argument Lists
281 Emacs Lisp's notation for argument lists of functions is a subset of
282 the Common Lisp notation. As well as the familiar @code{&optional}
283 and @code{&rest} markers, Common Lisp allows you to specify default
284 values for optional arguments, and it provides the additional markers
285 @code{&key} and @code{&aux}.
287 Since argument parsing is built-in to Emacs, there is no way for
288 this package to implement Common Lisp argument lists seamlessly.
289 Instead, this package defines alternates for several Lisp forms
290 which you must use if you need Common Lisp argument lists.
292 @defmac cl-defun name arglist body@dots{}
293 This form is identical to the regular @code{defun} form, except
294 that @var{arglist} is allowed to be a full Common Lisp argument
295 list. Also, the function body is enclosed in an implicit block
296 called @var{name}; @pxref{Blocks and Exits}.
299 @defmac cl-defsubst name arglist body@dots{}
300 This is just like @code{cl-defun}, except that the function that
301 is defined is automatically proclaimed @code{inline}, i.e.,
302 calls to it may be expanded into in-line code by the byte compiler.
303 This is analogous to the @code{defsubst} form;
304 @code{cl-defsubst} uses a different method (compiler macros) which
305 works in all versions of Emacs, and also generates somewhat more
306 @c For some examples,
307 @c see http://lists.gnu.org/archive/html/emacs-devel/2012-11/msg00009.html
308 efficient inline expansions. In particular, @code{cl-defsubst}
309 arranges for the processing of keyword arguments, default values,
310 etc., to be done at compile-time whenever possible.
313 @defmac cl-defmacro name arglist body@dots{}
314 This is identical to the regular @code{defmacro} form,
315 except that @var{arglist} is allowed to be a full Common Lisp
316 argument list. The @code{&environment} keyword is supported as
317 described in Steele's book @cite{Common Lisp, the Language}.
318 The @code{&whole} keyword is supported only
319 within destructured lists (see below); top-level @code{&whole}
320 cannot be implemented with the current Emacs Lisp interpreter.
321 The macro expander body is enclosed in an implicit block called
325 @defmac cl-function symbol-or-lambda
326 This is identical to the regular @code{function} form,
327 except that if the argument is a @code{lambda} form then that
328 form may use a full Common Lisp argument list.
331 Also, all forms (such as @code{cl-flet} and @code{cl-labels}) defined
332 in this package that include @var{arglist}s in their syntax allow
333 full Common Lisp argument lists.
335 Note that it is @emph{not} necessary to use @code{cl-defun} in
336 order to have access to most CL features in your function.
337 These features are always present; @code{cl-defun}'s only
338 difference from @code{defun} is its more flexible argument
339 lists and its implicit block.
341 The full form of a Common Lisp argument list is
345 &optional (@var{var} @var{initform} @var{svar})@dots{}
347 &key ((@var{keyword} @var{var}) @var{initform} @var{svar})@dots{}
348 &aux (@var{var} @var{initform})@dots{})
351 Each of the five argument list sections is optional. The @var{svar},
352 @var{initform}, and @var{keyword} parts are optional; if they are
353 omitted, then @samp{(@var{var})} may be written simply @samp{@var{var}}.
355 The first section consists of zero or more @dfn{required} arguments.
356 These arguments must always be specified in a call to the function;
357 there is no difference between Emacs Lisp and Common Lisp as far as
358 required arguments are concerned.
360 The second section consists of @dfn{optional} arguments. These
361 arguments may be specified in the function call; if they are not,
362 @var{initform} specifies the default value used for the argument.
363 (No @var{initform} means to use @code{nil} as the default.) The
364 @var{initform} is evaluated with the bindings for the preceding
365 arguments already established; @code{(a &optional (b (1+ a)))}
366 matches one or two arguments, with the second argument defaulting
367 to one plus the first argument. If the @var{svar} is specified,
368 it is an auxiliary variable which is bound to @code{t} if the optional
369 argument was specified, or to @code{nil} if the argument was omitted.
370 If you don't use an @var{svar}, then there will be no way for your
371 function to tell whether it was called with no argument, or with
372 the default value passed explicitly as an argument.
374 The third section consists of a single @dfn{rest} argument. If
375 more arguments were passed to the function than are accounted for
376 by the required and optional arguments, those extra arguments are
377 collected into a list and bound to the ``rest'' argument variable.
378 Common Lisp's @code{&rest} is equivalent to that of Emacs Lisp.
379 Common Lisp accepts @code{&body} as a synonym for @code{&rest} in
380 macro contexts; this package accepts it all the time.
382 The fourth section consists of @dfn{keyword} arguments. These
383 are optional arguments which are specified by name rather than
384 positionally in the argument list. For example,
387 (cl-defun foo (a &optional b &key c d (e 17)))
391 defines a function which may be called with one, two, or more
392 arguments. The first two arguments are bound to @code{a} and
393 @code{b} in the usual way. The remaining arguments must be
394 pairs of the form @code{:c}, @code{:d}, or @code{:e} followed
395 by the value to be bound to the corresponding argument variable.
396 (Symbols whose names begin with a colon are called @dfn{keywords},
397 and they are self-quoting in the same way as @code{nil} and
400 For example, the call @code{(foo 1 2 :d 3 :c 4)} sets the five
401 arguments to 1, 2, 4, 3, and 17, respectively. If the same keyword
402 appears more than once in the function call, the first occurrence
403 takes precedence over the later ones. Note that it is not possible
404 to specify keyword arguments without specifying the optional
405 argument @code{b} as well, since @code{(foo 1 :c 2)} would bind
406 @code{b} to the keyword @code{:c}, then signal an error because
407 @code{2} is not a valid keyword.
409 You can also explicitly specify the keyword argument; it need not be
410 simply the variable name prefixed with a colon. For example,
413 (cl-defun bar (&key (a 1) ((baz b) 4)))
418 specifies a keyword @code{:a} that sets the variable @code{a} with
419 default value 1, as well as a keyword @code{baz} that sets the
420 variable @code{b} with default value 4. In this case, because
421 @code{baz} is not self-quoting, you must quote it explicitly in the
422 function call, like this:
428 Ordinarily, it is an error to pass an unrecognized keyword to
429 a function, e.g., @code{(foo 1 2 :c 3 :goober 4)}. You can ask
430 Lisp to ignore unrecognized keywords, either by adding the
431 marker @code{&allow-other-keys} after the keyword section
432 of the argument list, or by specifying an @code{:allow-other-keys}
433 argument in the call whose value is non-@code{nil}. If the
434 function uses both @code{&rest} and @code{&key} at the same time,
435 the ``rest'' argument is bound to the keyword list as it appears
436 in the call. For example:
439 (cl-defun find-thing (thing &rest rest &key need &allow-other-keys)
440 (or (apply 'cl-member thing thing-list :allow-other-keys t rest)
441 (if need (error "Thing not found"))))
445 This function takes a @code{:need} keyword argument, but also
446 accepts other keyword arguments which are passed on to the
447 @code{cl-member} function. @code{allow-other-keys} is used to
448 keep both @code{find-thing} and @code{cl-member} from complaining
449 about each others' keywords in the arguments.
451 The fifth section of the argument list consists of @dfn{auxiliary
452 variables}. These are not really arguments at all, but simply
453 variables which are bound to @code{nil} or to the specified
454 @var{initforms} during execution of the function. There is no
455 difference between the following two functions, except for a
456 matter of stylistic taste:
459 (cl-defun foo (a b &aux (c (+ a b)) d)
467 @cindex destructuring, in argument list
468 Argument lists support @dfn{destructuring}. In Common Lisp,
469 destructuring is only allowed with @code{defmacro}; this package
470 allows it with @code{cl-defun} and other argument lists as well.
471 In destructuring, any argument variable (@var{var} in the above
472 example) can be replaced by a list of variables, or more generally,
473 a recursive argument list. The corresponding argument value must
474 be a list whose elements match this recursive argument list.
478 (cl-defmacro dolist ((var listform &optional resultform)
483 This says that the first argument of @code{dolist} must be a list
484 of two or three items; if there are other arguments as well as this
485 list, they are stored in @code{body}. All features allowed in
486 regular argument lists are allowed in these recursive argument lists.
487 In addition, the clause @samp{&whole @var{var}} is allowed at the
488 front of a recursive argument list. It binds @var{var} to the
489 whole list being matched; thus @code{(&whole all a b)} matches
490 a list of two things, with @code{a} bound to the first thing,
491 @code{b} bound to the second thing, and @code{all} bound to the
492 list itself. (Common Lisp allows @code{&whole} in top-level
493 @code{defmacro} argument lists as well, but Emacs Lisp does not
496 One last feature of destructuring is that the argument list may be
497 dotted, so that the argument list @code{(a b . c)} is functionally
498 equivalent to @code{(a b &rest c)}.
500 If the optimization quality @code{safety} is set to 0
501 (@pxref{Declarations}), error checking for wrong number of
502 arguments and invalid keyword arguments is disabled. By default,
503 argument lists are rigorously checked.
505 @node Time of Evaluation
506 @section Time of Evaluation
509 Normally, the byte-compiler does not actually execute the forms in
510 a file it compiles. For example, if a file contains @code{(setq foo t)},
511 the act of compiling it will not actually set @code{foo} to @code{t}.
512 This is true even if the @code{setq} was a top-level form (i.e., not
513 enclosed in a @code{defun} or other form). Sometimes, though, you
514 would like to have certain top-level forms evaluated at compile-time.
515 For example, the compiler effectively evaluates @code{defmacro} forms
516 at compile-time so that later parts of the file can refer to the
517 macros that are defined.
519 @defmac cl-eval-when (situations@dots{}) forms@dots{}
520 This form controls when the body @var{forms} are evaluated.
521 The @var{situations} list may contain any set of the symbols
522 @code{compile}, @code{load}, and @code{eval} (or their long-winded
523 ANSI equivalents, @code{:compile-toplevel}, @code{:load-toplevel},
524 and @code{:execute}).
526 The @code{cl-eval-when} form is handled differently depending on
527 whether or not it is being compiled as a top-level form.
528 Specifically, it gets special treatment if it is being compiled
529 by a command such as @code{byte-compile-file} which compiles files
530 or buffers of code, and it appears either literally at the
531 top level of the file or inside a top-level @code{progn}.
533 For compiled top-level @code{cl-eval-when}s, the body @var{forms} are
534 executed at compile-time if @code{compile} is in the @var{situations}
535 list, and the @var{forms} are written out to the file (to be executed
536 at load-time) if @code{load} is in the @var{situations} list.
538 For non-compiled-top-level forms, only the @code{eval} situation is
539 relevant. (This includes forms executed by the interpreter, forms
540 compiled with @code{byte-compile} rather than @code{byte-compile-file},
541 and non-top-level forms.) The @code{cl-eval-when} acts like a
542 @code{progn} if @code{eval} is specified, and like @code{nil}
543 (ignoring the body @var{forms}) if not.
545 The rules become more subtle when @code{cl-eval-when}s are nested;
546 consult Steele (second edition) for the gruesome details (and
547 some gruesome examples).
549 Some simple examples:
552 ;; Top-level forms in foo.el:
553 (cl-eval-when (compile) (setq foo1 'bar))
554 (cl-eval-when (load) (setq foo2 'bar))
555 (cl-eval-when (compile load) (setq foo3 'bar))
556 (cl-eval-when (eval) (setq foo4 'bar))
557 (cl-eval-when (eval compile) (setq foo5 'bar))
558 (cl-eval-when (eval load) (setq foo6 'bar))
559 (cl-eval-when (eval compile load) (setq foo7 'bar))
562 When @file{foo.el} is compiled, these variables will be set during
563 the compilation itself:
566 foo1 foo3 foo5 foo7 ; `compile'
569 When @file{foo.elc} is loaded, these variables will be set:
572 foo2 foo3 foo6 foo7 ; `load'
575 And if @file{foo.el} is loaded uncompiled, these variables will
579 foo4 foo5 foo6 foo7 ; `eval'
582 If these seven @code{cl-eval-when}s had been, say, inside a @code{defun},
583 then the first three would have been equivalent to @code{nil} and the
584 last four would have been equivalent to the corresponding @code{setq}s.
586 Note that @code{(cl-eval-when (load eval) @dots{})} is equivalent
587 to @code{(progn @dots{})} in all contexts. The compiler treats
588 certain top-level forms, like @code{defmacro} (sort-of) and
589 @code{require}, as if they were wrapped in @code{(cl-eval-when
590 (compile load eval) @dots{})}.
593 Emacs includes two special forms related to @code{cl-eval-when}.
594 @xref{Eval During Compile,,,elisp,GNU Emacs Lisp Reference Manual}.
595 One of these, @code{eval-when-compile}, is not quite equivalent to
596 any @code{cl-eval-when} construct and is described below.
598 The other form, @code{(eval-and-compile @dots{})}, is exactly
599 equivalent to @samp{(cl-eval-when (compile load eval) @dots{})}.
601 @defmac eval-when-compile forms@dots{}
602 The @var{forms} are evaluated at compile-time; at execution time,
603 this form acts like a quoted constant of the resulting value. Used
604 at top-level, @code{eval-when-compile} is just like @samp{eval-when
605 (compile eval)}. In other contexts, @code{eval-when-compile}
606 allows code to be evaluated once at compile-time for efficiency
609 This form is similar to the @samp{#.} syntax of true Common Lisp.
612 @defmac cl-load-time-value form
613 The @var{form} is evaluated at load-time; at execution time,
614 this form acts like a quoted constant of the resulting value.
616 Early Common Lisp had a @samp{#,} syntax that was similar to
617 this, but ANSI Common Lisp replaced it with @code{load-time-value}
618 and gave it more well-defined semantics.
620 In a compiled file, @code{cl-load-time-value} arranges for @var{form}
621 to be evaluated when the @file{.elc} file is loaded and then used
622 as if it were a quoted constant. In code compiled by
623 @code{byte-compile} rather than @code{byte-compile-file}, the
624 effect is identical to @code{eval-when-compile}. In uncompiled
625 code, both @code{eval-when-compile} and @code{cl-load-time-value}
626 act exactly like @code{progn}.
630 (insert "This function was executed on: "
631 (current-time-string)
633 (eval-when-compile (current-time-string))
634 ;; or '#.(current-time-string) in real Common Lisp
636 (cl-load-time-value (current-time-string))))
640 Byte-compiled, the above defun will result in the following code
641 (or its compiled equivalent, of course) in the @file{.elc} file:
644 (setq --temp-- (current-time-string))
646 (insert "This function was executed on: "
647 (current-time-string)
649 '"Wed Oct 31 16:32:28 2012"
659 This section describes functions for testing whether various
660 facts are true or false.
663 * Type Predicates:: @code{cl-typep}, @code{cl-deftype}, and @code{cl-coerce}.
664 * Equality Predicates:: @code{cl-equalp}.
667 @node Type Predicates
668 @section Type Predicates
670 @defun cl-typep object type
671 Check if @var{object} is of type @var{type}, where @var{type} is a
672 (quoted) type name of the sort used by Common Lisp. For example,
673 @code{(cl-typep foo 'integer)} is equivalent to @code{(integerp foo)}.
676 The @var{type} argument to the above function is either a symbol
677 or a list beginning with a symbol.
681 If the type name is a symbol, Emacs appends @samp{-p} to the
682 symbol name to form the name of a predicate function for testing
683 the type. (Built-in predicates whose names end in @samp{p} rather
684 than @samp{-p} are used when appropriate.)
687 The type symbol @code{t} stands for the union of all types.
688 @code{(cl-typep @var{object} t)} is always true. Likewise, the
689 type symbol @code{nil} stands for nothing at all, and
690 @code{(cl-typep @var{object} nil)} is always false.
693 The type symbol @code{null} represents the symbol @code{nil}.
694 Thus @code{(cl-typep @var{object} 'null)} is equivalent to
695 @code{(null @var{object})}.
698 The type symbol @code{atom} represents all objects that are not cons
699 cells. Thus @code{(cl-typep @var{object} 'atom)} is equivalent to
700 @code{(atom @var{object})}.
703 The type symbol @code{real} is a synonym for @code{number}, and
704 @code{fixnum} is a synonym for @code{integer}.
707 The type symbols @code{character} and @code{string-char} match
708 integers in the range from 0 to 255.
711 The type list @code{(integer @var{low} @var{high})} represents all
712 integers between @var{low} and @var{high}, inclusive. Either bound
713 may be a list of a single integer to specify an exclusive limit,
714 or a @code{*} to specify no limit. The type @code{(integer * *)}
715 is thus equivalent to @code{integer}.
718 Likewise, lists beginning with @code{float}, @code{real}, or
719 @code{number} represent numbers of that type falling in a particular
723 Lists beginning with @code{and}, @code{or}, and @code{not} form
724 combinations of types. For example, @code{(or integer (float 0 *))}
725 represents all objects that are integers or non-negative floats.
728 Lists beginning with @code{member} or @code{cl-member} represent
729 objects @code{eql} to any of the following values. For example,
730 @code{(member 1 2 3 4)} is equivalent to @code{(integer 1 4)},
731 and @code{(member nil)} is equivalent to @code{null}.
734 Lists of the form @code{(satisfies @var{predicate})} represent
735 all objects for which @var{predicate} returns true when called
736 with that object as an argument.
739 The following function and macro (not technically predicates) are
740 related to @code{cl-typep}.
742 @defun cl-coerce object type
743 This function attempts to convert @var{object} to the specified
744 @var{type}. If @var{object} is already of that type as determined by
745 @code{cl-typep}, it is simply returned. Otherwise, certain types of
746 conversions will be made: If @var{type} is any sequence type
747 (@code{string}, @code{list}, etc.)@: then @var{object} will be
748 converted to that type if possible. If @var{type} is
749 @code{character}, then strings of length one and symbols with
750 one-character names can be coerced. If @var{type} is @code{float},
751 then integers can be coerced in versions of Emacs that support
752 floats. In all other circumstances, @code{cl-coerce} signals an
756 @defmac cl-deftype name arglist forms@dots{}
757 This macro defines a new type called @var{name}. It is similar
758 to @code{defmacro} in many ways; when @var{name} is encountered
759 as a type name, the body @var{forms} are evaluated and should
760 return a type specifier that is equivalent to the type. The
761 @var{arglist} is a Common Lisp argument list of the sort accepted
762 by @code{cl-defmacro}. The type specifier @samp{(@var{name} @var{args}@dots{})}
763 is expanded by calling the expander with those arguments; the type
764 symbol @samp{@var{name}} is expanded by calling the expander with
765 no arguments. The @var{arglist} is processed the same as for
766 @code{cl-defmacro} except that optional arguments without explicit
767 defaults use @code{*} instead of @code{nil} as the ``default''
768 default. Some examples:
771 (cl-deftype null () '(satisfies null)) ; predefined
772 (cl-deftype list () '(or null cons)) ; predefined
773 (cl-deftype unsigned-byte (&optional bits)
774 (list 'integer 0 (if (eq bits '*) bits (1- (lsh 1 bits)))))
775 (unsigned-byte 8) @equiv{} (integer 0 255)
776 (unsigned-byte) @equiv{} (integer 0 *)
777 unsigned-byte @equiv{} (integer 0 *)
781 The last example shows how the Common Lisp @code{unsigned-byte}
782 type specifier could be implemented if desired; this package does
783 not implement @code{unsigned-byte} by default.
786 The @code{cl-typecase} (@pxref{Conditionals}) and @code{cl-check-type}
787 (@pxref{Assertions}) macros also use type names. The @code{cl-map},
788 @code{cl-concatenate}, and @code{cl-merge} functions take type-name
789 arguments to specify the type of sequence to return. @xref{Sequences}.
791 @node Equality Predicates
792 @section Equality Predicates
795 This package defines the Common Lisp predicate @code{cl-equalp}.
798 This function is a more flexible version of @code{equal}. In
799 particular, it compares strings case-insensitively, and it compares
800 numbers without regard to type (so that @code{(cl-equalp 3 3.0)} is
801 true). Vectors and conses are compared recursively. All other
802 objects are compared as if by @code{equal}.
804 This function differs from Common Lisp @code{equalp} in several
805 respects. First, Common Lisp's @code{equalp} also compares
806 @emph{characters} case-insensitively, which would be impractical
807 in this package since Emacs does not distinguish between integers
808 and characters. In keeping with the idea that strings are less
809 vector-like in Emacs Lisp, this package's @code{cl-equalp} also will
810 not compare strings against vectors of integers.
813 Also note that the Common Lisp functions @code{member} and @code{assoc}
814 use @code{eql} to compare elements, whereas Emacs Lisp follows the
815 MacLisp tradition and uses @code{equal} for these two functions.
816 The functions @code{cl-member} and @code{cl-assoc} use @code{eql},
817 as in Common Lisp. The standard Emacs Lisp functions @code{memq} and
818 @code{assq} use @code{eq}, and the standard @code{memql} uses @code{eql}.
820 @node Control Structure
821 @chapter Control Structure
824 The features described in the following sections implement
825 various advanced control structures, including extensions to the
826 standard @code{setf} facility, and a number of looping and conditional
830 * Assignment:: The @code{cl-psetq} form.
831 * Generalized Variables:: Extensions to generalized variables.
832 * Variable Bindings:: @code{cl-progv}, @code{cl-flet}, @code{cl-macrolet}.
833 * Conditionals:: @code{cl-case}, @code{cl-typecase}.
834 * Blocks and Exits:: @code{cl-block}, @code{cl-return}, @code{cl-return-from}.
835 * Iteration:: @code{cl-do}, @code{cl-dotimes}, @code{cl-dolist}, @code{cl-do-symbols}.
836 * Loop Facility:: The Common Lisp @code{loop} macro.
837 * Multiple Values:: @code{cl-values}, @code{cl-multiple-value-bind}, etc.
844 The @code{cl-psetq} form is just like @code{setq}, except that multiple
845 assignments are done in parallel rather than sequentially.
847 @defmac cl-psetq [symbol form]@dots{}
848 This special form (actually a macro) is used to assign to several
849 variables simultaneously. Given only one @var{symbol} and @var{form},
850 it has the same effect as @code{setq}. Given several @var{symbol}
851 and @var{form} pairs, it evaluates all the @var{form}s in advance
852 and then stores the corresponding variables afterwards.
856 (setq x (+ x y) y (* x y))
859 y ; @r{@code{y} was computed after @code{x} was set.}
862 (cl-psetq x (+ x y) y (* x y))
865 y ; @r{@code{y} was computed before @code{x} was set.}
869 The simplest use of @code{cl-psetq} is @code{(cl-psetq x y y x)}, which
870 exchanges the values of two variables. (The @code{cl-rotatef} form
871 provides an even more convenient way to swap two variables;
872 @pxref{Modify Macros}.)
874 @code{cl-psetq} always returns @code{nil}.
877 @node Generalized Variables
878 @section Generalized Variables
880 A @dfn{generalized variable} or @dfn{place form} is one of the many
881 places in Lisp memory where values can be stored. The simplest place
882 form is a regular Lisp variable. But the @sc{car}s and @sc{cdr}s of lists,
883 elements of arrays, properties of symbols, and many other locations
884 are also places where Lisp values are stored. For basic information,
885 @pxref{Generalized Variables,,,elisp,GNU Emacs Lisp Reference Manual}.
886 This package provides several additional features related to
887 generalized variables.
890 * Setf Extensions:: Additional @code{setf} places.
891 * Modify Macros:: @code{cl-incf}, @code{cl-rotatef}, @code{cl-letf}, @code{cl-callf}, etc.
894 @node Setf Extensions
895 @subsection Setf Extensions
897 Several standard (e.g., @code{car}) and Emacs-specific
898 (e.g., @code{window-point}) Lisp functions are @code{setf}-able by default.
899 This package defines @code{setf} handlers for several additional functions:
903 Functions from this package:
905 cl-rest cl-subseq cl-get cl-getf
906 cl-caaar@dots{}cl-cddddr cl-first@dots{}cl-tenth
910 Note that for @code{cl-getf} (as for @code{nthcdr}), the list argument
911 of the function must itself be a valid @var{place} form.
914 General Emacs Lisp functions:
916 buffer-file-name getenv
917 buffer-modified-p global-key-binding
918 buffer-name local-key-binding
920 buffer-substring mark-marker
921 current-buffer marker-position
922 current-case-table mouse-position
924 current-global-map point-marker
925 current-input-mode point-max
926 current-local-map point-min
927 current-window-configuration read-mouse-position
928 default-file-modes screen-height
929 documentation-property screen-width
930 face-background selected-window
931 face-background-pixmap selected-screen
932 face-font selected-frame
933 face-foreground standard-case-table
934 face-underline-p syntax-table
935 file-modes visited-file-modtime
936 frame-height window-height
937 frame-parameters window-width
938 frame-visible-p x-get-secondary-selection
939 frame-width x-get-selection
943 Most of these have directly corresponding ``set'' functions, like
944 @code{use-local-map} for @code{current-local-map}, or @code{goto-char}
945 for @code{point}. A few, like @code{point-min}, expand to longer
946 sequences of code when they are used with @code{setf}
947 (@code{(narrow-to-region x (point-max))} in this case).
950 A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])},
951 where @var{subplace} is itself a valid generalized variable whose
952 current value is a string, and where the value stored is also a
953 string. The new string is spliced into the specified part of the
954 destination string. For example:
957 (setq a (list "hello" "world"))
958 @result{} ("hello" "world")
961 (substring (cadr a) 2 4)
963 (setf (substring (cadr a) 2 4) "o")
968 @result{} ("hello" "wood")
971 The generalized variable @code{buffer-substring}, listed above,
972 also works in this way by replacing a portion of the current buffer.
974 @c FIXME? Also `eq'? (see cl-lib.el)
976 @c Currently commented out in cl.el.
979 A call of the form @code{(apply '@var{func} @dots{})} or
980 @code{(apply (function @var{func}) @dots{})}, where @var{func}
981 is a @code{setf}-able function whose store function is ``suitable''
982 in the sense described in Steele's book; since none of the standard
983 Emacs place functions are suitable in this sense, this feature is
984 only interesting when used with places you define yourself with
985 @code{define-setf-method} or the long form of @code{defsetf}.
986 @xref{Obsolete Setf Customization}.
989 @c FIXME? Is this still true?
991 A macro call, in which case the macro is expanded and @code{setf}
992 is applied to the resulting form.
995 @c FIXME should this be in lispref? It seems self-evident.
996 @c Contrast with the cl-incf example later on.
997 @c Here it really only serves as a contrast to wrong-order.
998 The @code{setf} macro takes care to evaluate all subforms in
999 the proper left-to-right order; for example,
1002 (setf (aref vec (cl-incf i)) i)
1006 looks like it will evaluate @code{(cl-incf i)} exactly once, before the
1007 following access to @code{i}; the @code{setf} expander will insert
1008 temporary variables as necessary to ensure that it does in fact work
1009 this way no matter what setf-method is defined for @code{aref}.
1010 (In this case, @code{aset} would be used and no such steps would
1011 be necessary since @code{aset} takes its arguments in a convenient
1014 However, if the @var{place} form is a macro which explicitly
1015 evaluates its arguments in an unusual order, this unusual order
1016 will be preserved. Adapting an example from Steele, given
1019 (defmacro wrong-order (x y) (list 'aref y x))
1023 the form @code{(setf (wrong-order @var{a} @var{b}) 17)} will
1024 evaluate @var{b} first, then @var{a}, just as in an actual call
1025 to @code{wrong-order}.
1028 @subsection Modify Macros
1031 This package defines a number of macros that operate on generalized
1032 variables. Many are interesting and useful even when the @var{place}
1033 is just a variable name.
1035 @defmac cl-psetf [place form]@dots{}
1036 This macro is to @code{setf} what @code{cl-psetq} is to @code{setq}:
1037 When several @var{place}s and @var{form}s are involved, the
1038 assignments take place in parallel rather than sequentially.
1039 Specifically, all subforms are evaluated from left to right, then
1040 all the assignments are done (in an undefined order).
1043 @defmac cl-incf place &optional x
1044 This macro increments the number stored in @var{place} by one, or
1045 by @var{x} if specified. The incremented value is returned. For
1046 example, @code{(cl-incf i)} is equivalent to @code{(setq i (1+ i))}, and
1047 @code{(cl-incf (car x) 2)} is equivalent to @code{(setcar x (+ (car x) 2))}.
1049 As with @code{setf}, care is taken to preserve the ``apparent'' order
1050 of evaluation. For example,
1053 (cl-incf (aref vec (cl-incf i)))
1057 appears to increment @code{i} once, then increment the element of
1058 @code{vec} addressed by @code{i}; this is indeed exactly what it
1059 does, which means the above form is @emph{not} equivalent to the
1060 ``obvious'' expansion,
1063 (setf (aref vec (cl-incf i))
1064 (1+ (aref vec (cl-incf i)))) ; wrong!
1068 but rather to something more like
1071 (let ((temp (cl-incf i)))
1072 (setf (aref vec temp) (1+ (aref vec temp))))
1076 Again, all of this is taken care of automatically by @code{cl-incf} and
1077 the other generalized-variable macros.
1079 As a more Emacs-specific example of @code{cl-incf}, the expression
1080 @code{(cl-incf (point) @var{n})} is essentially equivalent to
1081 @code{(forward-char @var{n})}.
1084 @defmac cl-decf place &optional x
1085 This macro decrements the number stored in @var{place} by one, or
1086 by @var{x} if specified.
1089 @defmac cl-pushnew x place @t{&key :test :test-not :key}
1090 This macro inserts @var{x} at the front of the list stored in
1091 @var{place}, but only if @var{x} was not @code{eql} to any
1092 existing element of the list. The optional keyword arguments
1093 are interpreted in the same way as for @code{cl-adjoin}.
1094 @xref{Lists as Sets}.
1097 @defmac cl-shiftf place@dots{} newvalue
1098 This macro shifts the @var{place}s left by one, shifting in the
1099 value of @var{newvalue} (which may be any Lisp expression, not just
1100 a generalized variable), and returning the value shifted out of
1101 the first @var{place}. Thus, @code{(cl-shiftf @var{a} @var{b} @var{c}
1102 @var{d})} is equivalent to
1107 (cl-psetf @var{a} @var{b}
1113 except that the subforms of @var{a}, @var{b}, and @var{c} are actually
1114 evaluated only once each and in the apparent order.
1117 @defmac cl-rotatef place@dots{}
1118 This macro rotates the @var{place}s left by one in circular fashion.
1119 Thus, @code{(cl-rotatef @var{a} @var{b} @var{c} @var{d})} is equivalent to
1122 (cl-psetf @var{a} @var{b}
1129 except for the evaluation of subforms. @code{cl-rotatef} always
1130 returns @code{nil}. Note that @code{(cl-rotatef @var{a} @var{b})}
1131 conveniently exchanges @var{a} and @var{b}.
1134 The following macros were invented for this package; they have no
1135 analogues in Common Lisp.
1137 @defmac cl-letf (bindings@dots{}) forms@dots{}
1138 This macro is analogous to @code{let}, but for generalized variables
1139 rather than just symbols. Each @var{binding} should be of the form
1140 @code{(@var{place} @var{value})}; the original contents of the
1141 @var{place}s are saved, the @var{value}s are stored in them, and
1142 then the body @var{form}s are executed. Afterwards, the @var{places}
1143 are set back to their original saved contents. This cleanup happens
1144 even if the @var{form}s exit irregularly due to a @code{throw} or an
1150 (cl-letf (((point) (point-min))
1156 moves point in the current buffer to the beginning of the buffer,
1157 and also binds @code{a} to 17 (as if by a normal @code{let}, since
1158 @code{a} is just a regular variable). After the body exits, @code{a}
1159 is set back to its original value and point is moved back to its
1162 Note that @code{cl-letf} on @code{(point)} is not quite like a
1163 @code{save-excursion}, as the latter effectively saves a marker
1164 which tracks insertions and deletions in the buffer. Actually,
1165 a @code{cl-letf} of @code{(point-marker)} is much closer to this
1166 behavior. (@code{point} and @code{point-marker} are equivalent
1167 as @code{setf} places; each will accept either an integer or a
1168 marker as the stored value.)
1170 Since generalized variables look like lists, @code{let}'s shorthand
1171 of using @samp{foo} for @samp{(foo nil)} as a @var{binding} would
1172 be ambiguous in @code{cl-letf} and is not allowed.
1174 However, a @var{binding} specifier may be a one-element list
1175 @samp{(@var{place})}, which is similar to @samp{(@var{place}
1176 @var{place})}. In other words, the @var{place} is not disturbed
1177 on entry to the body, and the only effect of the @code{cl-letf} is
1178 to restore the original value of @var{place} afterwards.
1179 @c I suspect this may no longer be true; either way it's
1180 @c implementation detail and so not essential to document.
1182 (The redundant access-and-store suggested by the @code{(@var{place}
1183 @var{place})} example does not actually occur.)
1186 Note that in this case, and in fact almost every case, @var{place}
1187 must have a well-defined value outside the @code{cl-letf} body.
1188 There is essentially only one exception to this, which is @var{place}
1189 a plain variable with a specified @var{value} (such as @code{(a 17)}
1190 in the above example).
1191 @c See http://debbugs.gnu.org/12758
1192 @c Some or all of this was true for cl.el, but not for cl-lib.el.
1194 The only exceptions are plain variables and calls to
1195 @code{symbol-value} and @code{symbol-function}. If the symbol is not
1196 bound on entry, it is simply made unbound by @code{makunbound} or
1197 @code{fmakunbound} on exit.
1201 @defmac cl-letf* (bindings@dots{}) forms@dots{}
1202 This macro is to @code{cl-letf} what @code{let*} is to @code{let}:
1203 It does the bindings in sequential rather than parallel order.
1206 @defmac cl-callf @var{function} @var{place} @var{args}@dots{}
1207 This is the ``generic'' modify macro. It calls @var{function},
1208 which should be an unquoted function name, macro name, or lambda.
1209 It passes @var{place} and @var{args} as arguments, and assigns the
1210 result back to @var{place}. For example, @code{(cl-incf @var{place}
1211 @var{n})} is the same as @code{(cl-callf + @var{place} @var{n})}.
1215 (cl-callf abs my-number)
1216 (cl-callf concat (buffer-name) "<" (number-to-string n) ">")
1217 (cl-callf cl-union happy-people (list joe bob) :test 'same-person)
1220 Note again that @code{cl-callf} is an extension to standard Common Lisp.
1223 @defmac cl-callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{}
1224 This macro is like @code{cl-callf}, except that @var{place} is
1225 the @emph{second} argument of @var{function} rather than the
1226 first. For example, @code{(push @var{x} @var{place})} is
1227 equivalent to @code{(cl-callf2 cons @var{x} @var{place})}.
1230 The @code{cl-callf} and @code{cl-callf2} macros serve as building
1231 blocks for other macros like @code{cl-incf}, and @code{cl-pushnew}.
1232 The @code{cl-letf} and @code{cl-letf*} macros are used in the processing
1233 of symbol macros; @pxref{Macro Bindings}.
1236 @node Variable Bindings
1237 @section Variable Bindings
1240 These Lisp forms make bindings to variables and function names,
1241 analogous to Lisp's built-in @code{let} form.
1243 @xref{Modify Macros}, for the @code{cl-letf} and @code{cl-letf*} forms which
1244 are also related to variable bindings.
1247 * Dynamic Bindings:: The @code{cl-progv} form.
1248 * Function Bindings:: @code{cl-flet} and @code{cl-labels}.
1249 * Macro Bindings:: @code{cl-macrolet} and @code{cl-symbol-macrolet}.
1252 @node Dynamic Bindings
1253 @subsection Dynamic Bindings
1256 The standard @code{let} form binds variables whose names are known
1257 at compile-time. The @code{cl-progv} form provides an easy way to
1258 bind variables whose names are computed at run-time.
1260 @defmac cl-progv symbols values forms@dots{}
1261 This form establishes @code{let}-style variable bindings on a
1262 set of variables computed at run-time. The expressions
1263 @var{symbols} and @var{values} are evaluated, and must return lists
1264 of symbols and values, respectively. The symbols are bound to the
1265 corresponding values for the duration of the body @var{form}s.
1266 If @var{values} is shorter than @var{symbols}, the last few symbols
1267 are bound to @code{nil}.
1268 If @var{symbols} is shorter than @var{values}, the excess values
1272 @node Function Bindings
1273 @subsection Function Bindings
1276 These forms make @code{let}-like bindings to functions instead
1279 @defmac cl-flet (bindings@dots{}) forms@dots{}
1280 This form establishes @code{let}-style bindings on the function
1281 cells of symbols rather than on the value cells. Each @var{binding}
1282 must be a list of the form @samp{(@var{name} @var{arglist}
1283 @var{forms}@dots{})}, which defines a function exactly as if
1284 it were a @code{cl-defun} form. The function @var{name} is defined
1285 accordingly but only within the body of the @code{cl-flet}, hiding any external
1286 definition if applicable.
1288 The bindings are lexical in scope. This means that all references to
1289 the named functions must appear physically within the body of the
1290 @code{cl-flet} form.
1292 Functions defined by @code{cl-flet} may use the full Common Lisp
1293 argument notation supported by @code{cl-defun}; also, the function
1294 body is enclosed in an implicit block as if by @code{cl-defun}.
1295 @xref{Program Structure}.
1297 Note that the @file{cl.el} version of this macro behaves slightly
1298 differently. In particular, its binding is dynamic rather than
1299 lexical. @xref{Obsolete Macros}.
1302 @defmac cl-labels (bindings@dots{}) forms@dots{}
1303 The @code{cl-labels} form is like @code{cl-flet}, except that
1304 the function bindings can be recursive. The scoping is lexical,
1305 but you can only capture functions in closures if
1306 @code{lexical-binding} is @code{t}.
1307 @xref{Closures,,,elisp,GNU Emacs Lisp Reference Manual}, and
1308 @ref{Using Lexical Binding,,,elisp,GNU Emacs Lisp Reference Manual}.
1310 Lexical scoping means that all references to the named
1311 functions must appear physically within the body of the
1312 @code{cl-labels} form. References may appear both in the body
1313 @var{forms} of @code{cl-labels} itself, and in the bodies of
1314 the functions themselves. Thus, @code{cl-labels} can define
1315 local recursive functions, or mutually-recursive sets of functions.
1317 A ``reference'' to a function name is either a call to that
1318 function, or a use of its name quoted by @code{quote} or
1319 @code{function} to be passed on to, say, @code{mapcar}.
1321 Note that the @file{cl.el} version of this macro behaves slightly
1322 differently. @xref{Obsolete Macros}.
1325 @node Macro Bindings
1326 @subsection Macro Bindings
1329 These forms create local macros and ``symbol macros''.
1331 @defmac cl-macrolet (bindings@dots{}) forms@dots{}
1332 This form is analogous to @code{cl-flet}, but for macros instead of
1333 functions. Each @var{binding} is a list of the same form as the
1334 arguments to @code{cl-defmacro} (i.e., a macro name, argument list,
1335 and macro-expander forms). The macro is defined accordingly for
1336 use within the body of the @code{cl-macrolet}.
1338 Because of the nature of macros, @code{cl-macrolet} is always lexically
1339 scoped. The @code{cl-macrolet} binding will
1340 affect only calls that appear physically within the body
1341 @var{forms}, possibly after expansion of other macros in the
1345 @defmac cl-symbol-macrolet (bindings@dots{}) forms@dots{}
1346 This form creates @dfn{symbol macros}, which are macros that look
1347 like variable references rather than function calls. Each
1348 @var{binding} is a list @samp{(@var{var} @var{expansion})};
1349 any reference to @var{var} within the body @var{forms} is
1350 replaced by @var{expansion}.
1354 (cl-symbol-macrolet ((foo (car bar)))
1360 A @code{setq} of a symbol macro is treated the same as a @code{setf}.
1361 I.e., @code{(setq foo 4)} in the above would be equivalent to
1362 @code{(setf foo 4)}, which in turn expands to @code{(setf (car bar) 4)}.
1364 Likewise, a @code{let} or @code{let*} binding a symbol macro is
1365 treated like a @code{cl-letf} or @code{cl-letf*}. This differs from true
1366 Common Lisp, where the rules of lexical scoping cause a @code{let}
1367 binding to shadow a @code{symbol-macrolet} binding. In this package,
1368 such shadowing does not occur, even when @code{lexical-binding} is
1369 @c See http://debbugs.gnu.org/12119
1370 @code{t}. (This behavior predates the addition of lexical binding to
1371 Emacs Lisp, and may change in future to respect @code{lexical-binding}.)
1372 At present in this package, only @code{lexical-let} and
1373 @code{lexical-let*} will shadow a symbol macro. @xref{Obsolete
1376 There is no analogue of @code{defmacro} for symbol macros; all symbol
1377 macros are local. A typical use of @code{cl-symbol-macrolet} is in the
1378 expansion of another macro:
1381 (cl-defmacro my-dolist ((x list) &rest body)
1382 (let ((var (cl-gensym)))
1383 (list 'cl-loop 'for var 'on list 'do
1384 (cl-list* 'cl-symbol-macrolet
1385 (list (list x (list 'car var)))
1388 (setq mylist '(1 2 3 4))
1389 (my-dolist (x mylist) (cl-incf x))
1395 In this example, the @code{my-dolist} macro is similar to @code{dolist}
1396 (@pxref{Iteration}) except that the variable @code{x} becomes a true
1397 reference onto the elements of the list. The @code{my-dolist} call
1398 shown here expands to
1401 (cl-loop for G1234 on mylist do
1402 (cl-symbol-macrolet ((x (car G1234)))
1407 which in turn expands to
1410 (cl-loop for G1234 on mylist do (cl-incf (car G1234)))
1413 @xref{Loop Facility}, for a description of the @code{cl-loop} macro.
1414 This package defines a nonstandard @code{in-ref} loop clause that
1415 works much like @code{my-dolist}.
1419 @section Conditionals
1422 These conditional forms augment Emacs Lisp's simple @code{if},
1423 @code{and}, @code{or}, and @code{cond} forms.
1425 @defmac cl-case keyform clause@dots{}
1426 This macro evaluates @var{keyform}, then compares it with the key
1427 values listed in the various @var{clause}s. Whichever clause matches
1428 the key is executed; comparison is done by @code{eql}. If no clause
1429 matches, the @code{cl-case} form returns @code{nil}. The clauses are
1433 (@var{keylist} @var{body-forms}@dots{})
1437 where @var{keylist} is a list of key values. If there is exactly
1438 one value, and it is not a cons cell or the symbol @code{nil} or
1439 @code{t}, then it can be used by itself as a @var{keylist} without
1440 being enclosed in a list. All key values in the @code{cl-case} form
1441 must be distinct. The final clauses may use @code{t} in place of
1442 a @var{keylist} to indicate a default clause that should be taken
1443 if none of the other clauses match. (The symbol @code{otherwise}
1444 is also recognized in place of @code{t}. To make a clause that
1445 matches the actual symbol @code{t}, @code{nil}, or @code{otherwise},
1446 enclose the symbol in a list.)
1448 For example, this expression reads a keystroke, then does one of
1449 four things depending on whether it is an @samp{a}, a @samp{b},
1450 a @key{RET} or @kbd{C-j}, or anything else.
1453 (cl-case (read-char)
1456 ((?\r ?\n) (do-ret-thing))
1457 (t (do-other-thing)))
1461 @defmac cl-ecase keyform clause@dots{}
1462 This macro is just like @code{cl-case}, except that if the key does
1463 not match any of the clauses, an error is signaled rather than
1464 simply returning @code{nil}.
1467 @defmac cl-typecase keyform clause@dots{}
1468 This macro is a version of @code{cl-case} that checks for types
1469 rather than values. Each @var{clause} is of the form
1470 @samp{(@var{type} @var{body}@dots{})}. @xref{Type Predicates},
1471 for a description of type specifiers. For example,
1475 (integer (munch-integer x))
1476 (float (munch-float x))
1477 (string (munch-integer (string-to-int x)))
1478 (t (munch-anything x)))
1481 The type specifier @code{t} matches any type of object; the word
1482 @code{otherwise} is also allowed. To make one clause match any of
1483 several types, use an @code{(or @dots{})} type specifier.
1486 @defmac cl-etypecase keyform clause@dots{}
1487 This macro is just like @code{cl-typecase}, except that if the key does
1488 not match any of the clauses, an error is signaled rather than
1489 simply returning @code{nil}.
1492 @node Blocks and Exits
1493 @section Blocks and Exits
1497 Common Lisp @dfn{blocks} provide a non-local exit mechanism very
1498 similar to @code{catch} and @code{throw}, with lexical scoping.
1499 This package actually implements @code{cl-block}
1500 in terms of @code{catch}; however, the lexical scoping allows the
1501 byte-compiler to omit the costly @code{catch} step if the
1502 body of the block does not actually @code{cl-return-from} the block.
1504 @defmac cl-block name forms@dots{}
1505 The @var{forms} are evaluated as if by a @code{progn}. However,
1506 if any of the @var{forms} execute @code{(cl-return-from @var{name})},
1507 they will jump out and return directly from the @code{cl-block} form.
1508 The @code{cl-block} returns the result of the last @var{form} unless
1509 a @code{cl-return-from} occurs.
1511 The @code{cl-block}/@code{cl-return-from} mechanism is quite similar to
1512 the @code{catch}/@code{throw} mechanism. The main differences are
1513 that block @var{name}s are unevaluated symbols, rather than forms
1514 (such as quoted symbols) that evaluate to a tag at run-time; and
1515 also that blocks are always lexically scoped.
1516 In a dynamically scoped @code{catch}, functions called from the
1517 @code{catch} body can also @code{throw} to the @code{catch}. This
1518 is not an option for @code{cl-block}, where
1519 the @code{cl-return-from} referring to a block name must appear
1520 physically within the @var{forms} that make up the body of the block.
1521 They may not appear within other called functions, although they may
1522 appear within macro expansions or @code{lambda}s in the body. Block
1523 names and @code{catch} names form independent name-spaces.
1525 In true Common Lisp, @code{defun} and @code{defmacro} surround
1526 the function or expander bodies with implicit blocks with the
1527 same name as the function or macro. This does not occur in Emacs
1528 Lisp, but this package provides @code{cl-defun} and @code{cl-defmacro}
1529 forms, which do create the implicit block.
1531 The Common Lisp looping constructs defined by this package,
1532 such as @code{cl-loop} and @code{cl-dolist}, also create implicit blocks
1533 just as in Common Lisp.
1535 Because they are implemented in terms of Emacs Lisp's @code{catch}
1536 and @code{throw}, blocks have the same overhead as actual
1537 @code{catch} constructs (roughly two function calls). However,
1538 the byte compiler will optimize away the @code{catch}
1540 not in fact contain any @code{cl-return} or @code{cl-return-from} calls
1541 that jump to it. This means that @code{cl-do} loops and @code{cl-defun}
1542 functions that don't use @code{cl-return} don't pay the overhead to
1546 @defmac cl-return-from name [result]
1547 This macro returns from the block named @var{name}, which must be
1548 an (unevaluated) symbol. If a @var{result} form is specified, it
1549 is evaluated to produce the result returned from the @code{block}.
1550 Otherwise, @code{nil} is returned.
1553 @defmac cl-return [result]
1554 This macro is exactly like @code{(cl-return-from nil @var{result})}.
1555 Common Lisp loops like @code{cl-do} and @code{cl-dolist} implicitly enclose
1556 themselves in @code{nil} blocks.
1559 @c FIXME? Maybe this should be in a separate section?
1560 @defmac cl-tagbody &rest labels-or-statements
1561 This macro executes statements while allowing for control transfer to
1562 user-defined labels. Each element of @var{labels-or-statements} can
1563 be either a label (an integer or a symbol), or a cons-cell
1564 (a statement). This distinction is made before macroexpansion.
1565 Statements are executed in sequence, discarding any return value.
1566 Any statement can transfer control at any time to the statements that follow
1567 one of the labels with the special form @code{(go @var{label})}.
1568 Labels have lexical scope and dynamic extent.
1576 The macros described here provide more sophisticated, high-level
1577 looping constructs to complement Emacs Lisp's basic loop forms
1578 (@pxref{Iteration,,,elisp,GNU Emacs Lisp Reference Manual}).
1580 @defmac cl-loop forms@dots{}
1581 This package supports both the simple, old-style meaning of
1582 @code{loop} and the extremely powerful and flexible feature known as
1583 the @dfn{Loop Facility} or @dfn{Loop Macro}. This more advanced
1584 facility is discussed in the following section; @pxref{Loop Facility}.
1585 The simple form of @code{loop} is described here.
1587 If @code{cl-loop} is followed by zero or more Lisp expressions,
1588 then @code{(cl-loop @var{exprs}@dots{})} simply creates an infinite
1589 loop executing the expressions over and over. The loop is
1590 enclosed in an implicit @code{nil} block. Thus,
1593 (cl-loop (foo) (if (no-more) (return 72)) (bar))
1597 is exactly equivalent to
1600 (cl-block nil (while t (foo) (if (no-more) (return 72)) (bar)))
1603 If any of the expressions are plain symbols, the loop is instead
1604 interpreted as a Loop Macro specification as described later.
1605 (This is not a restriction in practice, since a plain symbol
1606 in the above notation would simply access and throw away the
1607 value of a variable.)
1610 @defmac cl-do (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
1611 This macro creates a general iterative loop. Each @var{spec} is
1615 (@var{var} [@var{init} [@var{step}]])
1618 The loop works as follows: First, each @var{var} is bound to the
1619 associated @var{init} value as if by a @code{let} form. Then, in
1620 each iteration of the loop, the @var{end-test} is evaluated; if
1621 true, the loop is finished. Otherwise, the body @var{forms} are
1622 evaluated, then each @var{var} is set to the associated @var{step}
1623 expression (as if by a @code{cl-psetq} form) and the next iteration
1624 begins. Once the @var{end-test} becomes true, the @var{result}
1625 forms are evaluated (with the @var{var}s still bound to their
1626 values) to produce the result returned by @code{cl-do}.
1628 The entire @code{cl-do} loop is enclosed in an implicit @code{nil}
1629 block, so that you can use @code{(cl-return)} to break out of the
1632 If there are no @var{result} forms, the loop returns @code{nil}.
1633 If a given @var{var} has no @var{step} form, it is bound to its
1634 @var{init} value but not otherwise modified during the @code{cl-do}
1635 loop (unless the code explicitly modifies it); this case is just
1636 a shorthand for putting a @code{(let ((@var{var} @var{init})) @dots{})}
1637 around the loop. If @var{init} is also omitted it defaults to
1638 @code{nil}, and in this case a plain @samp{@var{var}} can be used
1639 in place of @samp{(@var{var})}, again following the analogy with
1642 This example (from Steele) illustrates a loop that applies the
1643 function @code{f} to successive pairs of values from the lists
1644 @code{foo} and @code{bar}; it is equivalent to the call
1645 @code{(cl-mapcar 'f foo bar)}. Note that this loop has no body
1646 @var{forms} at all, performing all its work as side effects of
1647 the rest of the loop.
1650 (cl-do ((x foo (cdr x))
1652 (z nil (cons (f (car x) (car y)) z)))
1653 ((or (null x) (null y))
1658 @defmac cl-do* (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
1659 This is to @code{cl-do} what @code{let*} is to @code{let}. In
1660 particular, the initial values are bound as if by @code{let*}
1661 rather than @code{let}, and the steps are assigned as if by
1662 @code{setq} rather than @code{cl-psetq}.
1664 Here is another way to write the above loop:
1667 (cl-do* ((xp foo (cdr xp))
1669 (x (car xp) (car xp))
1670 (y (car yp) (car yp))
1672 ((or (null xp) (null yp))
1678 @defmac cl-dolist (var list [result]) forms@dots{}
1679 This is exactly like the standard Emacs Lisp macro @code{dolist},
1680 but surrounds the loop with an implicit @code{nil} block.
1683 @defmac cl-dotimes (var count [result]) forms@dots{}
1684 This is exactly like the standard Emacs Lisp macro @code{dotimes},
1685 but surrounds the loop with an implicit @code{nil} block.
1686 The body is executed with @var{var} bound to the integers
1687 from zero (inclusive) to @var{count} (exclusive), in turn. Then
1688 @c FIXME lispref does not state this part explicitly, could move this there.
1689 the @code{result} form is evaluated with @var{var} bound to the total
1690 number of iterations that were done (i.e., @code{(max 0 @var{count})})
1691 to get the return value for the loop form.
1694 @defmac cl-do-symbols (var [obarray [result]]) forms@dots{}
1695 This loop iterates over all interned symbols. If @var{obarray}
1696 is specified and is not @code{nil}, it loops over all symbols in
1697 that obarray. For each symbol, the body @var{forms} are evaluated
1698 with @var{var} bound to that symbol. The symbols are visited in
1699 an unspecified order. Afterward the @var{result} form, if any,
1700 is evaluated (with @var{var} bound to @code{nil}) to get the return
1701 value. The loop is surrounded by an implicit @code{nil} block.
1704 @defmac cl-do-all-symbols (var [result]) forms@dots{}
1705 This is identical to @code{cl-do-symbols} except that the @var{obarray}
1706 argument is omitted; it always iterates over the default obarray.
1709 @xref{Mapping over Sequences}, for some more functions for
1710 iterating over vectors or lists.
1713 @section Loop Facility
1716 A common complaint with Lisp's traditional looping constructs was
1717 that they were either too simple and limited, such as @code{dotimes}
1718 or @code{while}, or too unreadable and obscure, like Common Lisp's
1721 To remedy this, Common Lisp added a construct called the ``Loop
1722 Facility'' or ``@code{loop} macro'', with an easy-to-use but very
1723 powerful and expressive syntax.
1726 * Loop Basics:: The @code{cl-loop} macro, basic clause structure.
1727 * Loop Examples:: Working examples of the @code{cl-loop} macro.
1728 * For Clauses:: Clauses introduced by @code{for} or @code{as}.
1729 * Iteration Clauses:: @code{repeat}, @code{while}, @code{thereis}, etc.
1730 * Accumulation Clauses:: @code{collect}, @code{sum}, @code{maximize}, etc.
1731 * Other Clauses:: @code{with}, @code{if}, @code{initially}, @code{finally}.
1735 @subsection Loop Basics
1738 The @code{cl-loop} macro essentially creates a mini-language within
1739 Lisp that is specially tailored for describing loops. While this
1740 language is a little strange-looking by the standards of regular Lisp,
1741 it turns out to be very easy to learn and well-suited to its purpose.
1743 Since @code{cl-loop} is a macro, all parsing of the loop language
1744 takes place at byte-compile time; compiled @code{cl-loop}s are just
1745 as efficient as the equivalent @code{while} loops written longhand.
1747 @defmac cl-loop clauses@dots{}
1748 A loop construct consists of a series of @var{clause}s, each
1749 introduced by a symbol like @code{for} or @code{do}. Clauses
1750 are simply strung together in the argument list of @code{cl-loop},
1751 with minimal extra parentheses. The various types of clauses
1752 specify initializations, such as the binding of temporary
1753 variables, actions to be taken in the loop, stepping actions,
1756 Common Lisp specifies a certain general order of clauses in a
1760 (loop @var{name-clause}
1761 @var{var-clauses}@dots{}
1762 @var{action-clauses}@dots{})
1765 The @var{name-clause} optionally gives a name to the implicit
1766 block that surrounds the loop. By default, the implicit block
1767 is named @code{nil}. The @var{var-clauses} specify what
1768 variables should be bound during the loop, and how they should
1769 be modified or iterated throughout the course of the loop. The
1770 @var{action-clauses} are things to be done during the loop, such
1771 as computing, collecting, and returning values.
1773 The Emacs version of the @code{cl-loop} macro is less restrictive about
1774 the order of clauses, but things will behave most predictably if
1775 you put the variable-binding clauses @code{with}, @code{for}, and
1776 @code{repeat} before the action clauses. As in Common Lisp,
1777 @code{initially} and @code{finally} clauses can go anywhere.
1779 Loops generally return @code{nil} by default, but you can cause
1780 them to return a value by using an accumulation clause like
1781 @code{collect}, an end-test clause like @code{always}, or an
1782 explicit @code{return} clause to jump out of the implicit block.
1783 (Because the loop body is enclosed in an implicit block, you can
1784 also use regular Lisp @code{cl-return} or @code{cl-return-from} to
1785 break out of the loop.)
1788 The following sections give some examples of the loop macro in
1789 action, and describe the particular loop clauses in great detail.
1790 Consult the second edition of Steele for additional discussion
1794 @subsection Loop Examples
1797 Before listing the full set of clauses that are allowed, let's
1798 look at a few example loops just to get a feel for the @code{cl-loop}
1802 (cl-loop for buf in (buffer-list)
1803 collect (buffer-file-name buf))
1807 This loop iterates over all Emacs buffers, using the list
1808 returned by @code{buffer-list}. For each buffer @var{buf},
1809 it calls @code{buffer-file-name} and collects the results into
1810 a list, which is then returned from the @code{cl-loop} construct.
1811 The result is a list of the file names of all the buffers in
1812 Emacs's memory. The words @code{for}, @code{in}, and @code{collect}
1813 are reserved words in the @code{cl-loop} language.
1816 (cl-loop repeat 20 do (insert "Yowsa\n"))
1820 This loop inserts the phrase ``Yowsa'' twenty times in the
1824 (cl-loop until (eobp) do (munch-line) (forward-line 1))
1828 This loop calls @code{munch-line} on every line until the end
1829 of the buffer. If point is already at the end of the buffer,
1830 the loop exits immediately.
1833 (cl-loop do (munch-line) until (eobp) do (forward-line 1))
1837 This loop is similar to the above one, except that @code{munch-line}
1838 is always called at least once.
1841 (cl-loop for x from 1 to 100
1844 finally return (list x (= y 729)))
1848 This more complicated loop searches for a number @code{x} whose
1849 square is 729. For safety's sake it only examines @code{x}
1850 values up to 100; dropping the phrase @samp{to 100} would
1851 cause the loop to count upwards with no limit. The second
1852 @code{for} clause defines @code{y} to be the square of @code{x}
1853 within the loop; the expression after the @code{=} sign is
1854 reevaluated each time through the loop. The @code{until}
1855 clause gives a condition for terminating the loop, and the
1856 @code{finally} clause says what to do when the loop finishes.
1857 (This particular example was written less concisely than it
1858 could have been, just for the sake of illustration.)
1860 Note that even though this loop contains three clauses (two
1861 @code{for}s and an @code{until}) that would have been enough to
1862 define loops all by themselves, it still creates a single loop
1863 rather than some sort of triple-nested loop. You must explicitly
1864 nest your @code{cl-loop} constructs if you want nested loops.
1867 @subsection For Clauses
1870 Most loops are governed by one or more @code{for} clauses.
1871 A @code{for} clause simultaneously describes variables to be
1872 bound, how those variables are to be stepped during the loop,
1873 and usually an end condition based on those variables.
1875 The word @code{as} is a synonym for the word @code{for}. This
1876 word is followed by a variable name, then a word like @code{from}
1877 or @code{across} that describes the kind of iteration desired.
1878 In Common Lisp, the phrase @code{being the} sometimes precedes
1879 the type of iteration; in this package both @code{being} and
1880 @code{the} are optional. The word @code{each} is a synonym
1881 for @code{the}, and the word that follows it may be singular
1882 or plural: @samp{for x being the elements of y} or
1883 @samp{for x being each element of y}. Which form you use
1884 is purely a matter of style.
1886 The variable is bound around the loop as if by @code{let}:
1890 (cl-loop for i from 1 to 10 do (do-something-with i))
1896 @item for @var{var} from @var{expr1} to @var{expr2} by @var{expr3}
1897 This type of @code{for} clause creates a counting loop. Each of
1898 the three sub-terms is optional, though there must be at least one
1899 term so that the clause is marked as a counting clause.
1901 The three expressions are the starting value, the ending value, and
1902 the step value, respectively, of the variable. The loop counts
1903 upwards by default (@var{expr3} must be positive), from @var{expr1}
1904 to @var{expr2} inclusively. If you omit the @code{from} term, the
1905 loop counts from zero; if you omit the @code{to} term, the loop
1906 counts forever without stopping (unless stopped by some other
1907 loop clause, of course); if you omit the @code{by} term, the loop
1908 counts in steps of one.
1910 You can replace the word @code{from} with @code{upfrom} or
1911 @code{downfrom} to indicate the direction of the loop. Likewise,
1912 you can replace @code{to} with @code{upto} or @code{downto}.
1913 For example, @samp{for x from 5 downto 1} executes five times
1914 with @code{x} taking on the integers from 5 down to 1 in turn.
1915 Also, you can replace @code{to} with @code{below} or @code{above},
1916 which are like @code{upto} and @code{downto} respectively except
1917 that they are exclusive rather than inclusive limits:
1920 (cl-loop for x to 10 collect x)
1921 @result{} (0 1 2 3 4 5 6 7 8 9 10)
1922 (cl-loop for x below 10 collect x)
1923 @result{} (0 1 2 3 4 5 6 7 8 9)
1926 The @code{by} value is always positive, even for downward-counting
1927 loops. Some sort of @code{from} value is required for downward
1928 loops; @samp{for x downto 5} is not a valid loop clause all by
1931 @item for @var{var} in @var{list} by @var{function}
1932 This clause iterates @var{var} over all the elements of @var{list},
1933 in turn. If you specify the @code{by} term, then @var{function}
1934 is used to traverse the list instead of @code{cdr}; it must be a
1935 function taking one argument. For example:
1938 (cl-loop for x in '(1 2 3 4 5 6) collect (* x x))
1939 @result{} (1 4 9 16 25 36)
1940 (cl-loop for x in '(1 2 3 4 5 6) by 'cddr collect (* x x))
1944 @item for @var{var} on @var{list} by @var{function}
1945 This clause iterates @var{var} over all the cons cells of @var{list}.
1948 (cl-loop for x on '(1 2 3 4) collect x)
1949 @result{} ((1 2 3 4) (2 3 4) (3 4) (4))
1952 With @code{by}, there is no real reason that the @code{on} expression
1953 must be a list. For example:
1956 (cl-loop for x on first-animal by 'next-animal collect x)
1960 where @code{(next-animal x)} takes an ``animal'' @var{x} and returns
1961 the next in the (assumed) sequence of animals, or @code{nil} if
1962 @var{x} was the last animal in the sequence.
1964 @item for @var{var} in-ref @var{list} by @var{function}
1965 This is like a regular @code{in} clause, but @var{var} becomes
1966 a @code{setf}-able ``reference'' onto the elements of the list
1967 rather than just a temporary variable. For example,
1970 (cl-loop for x in-ref my-list do (cl-incf x))
1974 increments every element of @code{my-list} in place. This clause
1975 is an extension to standard Common Lisp.
1977 @item for @var{var} across @var{array}
1978 This clause iterates @var{var} over all the elements of @var{array},
1979 which may be a vector or a string.
1982 (cl-loop for x across "aeiou"
1983 do (use-vowel (char-to-string x)))
1986 @item for @var{var} across-ref @var{array}
1987 This clause iterates over an array, with @var{var} a @code{setf}-able
1988 reference onto the elements; see @code{in-ref} above.
1990 @item for @var{var} being the elements of @var{sequence}
1991 This clause iterates over the elements of @var{sequence}, which may
1992 be a list, vector, or string. Since the type must be determined
1993 at run-time, this is somewhat less efficient than @code{in} or
1994 @code{across}. The clause may be followed by the additional term
1995 @samp{using (index @var{var2})} to cause @var{var2} to be bound to
1996 the successive indices (starting at 0) of the elements.
1998 This clause type is taken from older versions of the @code{loop} macro,
1999 and is not present in modern Common Lisp. The @samp{using (sequence @dots{})}
2000 term of the older macros is not supported.
2002 @item for @var{var} being the elements of-ref @var{sequence}
2003 This clause iterates over a sequence, with @var{var} a @code{setf}-able
2004 reference onto the elements; see @code{in-ref} above.
2006 @item for @var{var} being the symbols [of @var{obarray}]
2007 This clause iterates over symbols, either over all interned symbols
2008 or over all symbols in @var{obarray}. The loop is executed with
2009 @var{var} bound to each symbol in turn. The symbols are visited in
2010 an unspecified order.
2015 (cl-loop for sym being the symbols
2017 when (string-match "^map" (symbol-name sym))
2022 returns a list of all the functions whose names begin with @samp{map}.
2024 The Common Lisp words @code{external-symbols} and @code{present-symbols}
2025 are also recognized but are equivalent to @code{symbols} in Emacs Lisp.
2027 Due to a minor implementation restriction, it will not work to have
2028 more than one @code{for} clause iterating over symbols, hash tables,
2029 keymaps, overlays, or intervals in a given @code{cl-loop}. Fortunately,
2030 it would rarely if ever be useful to do so. It @emph{is} valid to mix
2031 one of these types of clauses with other clauses like @code{for @dots{} to}
2034 @item for @var{var} being the hash-keys of @var{hash-table}
2035 @itemx for @var{var} being the hash-values of @var{hash-table}
2036 This clause iterates over the entries in @var{hash-table} with
2037 @var{var} bound to each key, or value. A @samp{using} clause can bind
2038 a second variable to the opposite part.
2041 (cl-loop for k being the hash-keys of h
2042 using (hash-values v)
2044 (message "key %S -> value %S" k v))
2047 @item for @var{var} being the key-codes of @var{keymap}
2048 @itemx for @var{var} being the key-bindings of @var{keymap}
2049 This clause iterates over the entries in @var{keymap}.
2050 The iteration does not enter nested keymaps but does enter inherited
2052 A @code{using} clause can access both the codes and the bindings
2056 (cl-loop for c being the key-codes of (current-local-map)
2057 using (key-bindings b)
2059 (message "key %S -> binding %S" c b))
2063 @item for @var{var} being the key-seqs of @var{keymap}
2064 This clause iterates over all key sequences defined by @var{keymap}
2065 and its nested keymaps, where @var{var} takes on values which are
2066 vectors. The strings or vectors
2067 are reused for each iteration, so you must copy them if you wish to keep
2068 them permanently. You can add a @samp{using (key-bindings @dots{})}
2069 clause to get the command bindings as well.
2071 @item for @var{var} being the overlays [of @var{buffer}] @dots{}
2072 This clause iterates over the ``overlays'' of a buffer
2073 (the clause @code{extents} is synonymous
2074 with @code{overlays}). If the @code{of} term is omitted, the current
2076 This clause also accepts optional @samp{from @var{pos}} and
2077 @samp{to @var{pos}} terms, limiting the clause to overlays which
2078 overlap the specified region.
2080 @item for @var{var} being the intervals [of @var{buffer}] @dots{}
2081 This clause iterates over all intervals of a buffer with constant
2082 text properties. The variable @var{var} will be bound to conses
2083 of start and end positions, where one start position is always equal
2084 to the previous end position. The clause allows @code{of},
2085 @code{from}, @code{to}, and @code{property} terms, where the latter
2086 term restricts the search to just the specified property. The
2087 @code{of} term may specify either a buffer or a string.
2089 @item for @var{var} being the frames
2090 This clause iterates over all Emacs frames. The clause @code{screens} is
2091 a synonym for @code{frames}. The frames are visited in
2092 @code{next-frame} order starting from @code{selected-frame}.
2094 @item for @var{var} being the windows [of @var{frame}]
2095 This clause iterates over the windows (in the Emacs sense) of
2096 the current frame, or of the specified @var{frame}. It visits windows
2097 in @code{next-window} order starting from @code{selected-window}
2098 (or @code{frame-selected-window} if you specify @var{frame}).
2099 This clause treats the minibuffer window in the same way as
2100 @code{next-window} does. For greater flexibility, consider using
2101 @code{walk-windows} instead.
2103 @item for @var{var} being the buffers
2104 This clause iterates over all buffers in Emacs. It is equivalent
2105 to @samp{for @var{var} in (buffer-list)}.
2107 @item for @var{var} = @var{expr1} then @var{expr2}
2108 This clause does a general iteration. The first time through
2109 the loop, @var{var} will be bound to @var{expr1}. On the second
2110 and successive iterations it will be set by evaluating @var{expr2}
2111 (which may refer to the old value of @var{var}). For example,
2112 these two loops are effectively the same:
2115 (cl-loop for x on my-list by 'cddr do @dots{})
2116 (cl-loop for x = my-list then (cddr x) while x do @dots{})
2119 Note that this type of @code{for} clause does not imply any sort
2120 of terminating condition; the above example combines it with a
2121 @code{while} clause to tell when to end the loop.
2123 If you omit the @code{then} term, @var{expr1} is used both for
2124 the initial setting and for successive settings:
2127 (cl-loop for x = (random) when (> x 0) return x)
2131 This loop keeps taking random numbers from the @code{(random)}
2132 function until it gets a positive one, which it then returns.
2135 If you include several @code{for} clauses in a row, they are
2136 treated sequentially (as if by @code{let*} and @code{setq}).
2137 You can instead use the word @code{and} to link the clauses,
2138 in which case they are processed in parallel (as if by @code{let}
2139 and @code{cl-psetq}).
2142 (cl-loop for x below 5 for y = nil then x collect (list x y))
2143 @result{} ((0 nil) (1 1) (2 2) (3 3) (4 4))
2144 (cl-loop for x below 5 and y = nil then x collect (list x y))
2145 @result{} ((0 nil) (1 0) (2 1) (3 2) (4 3))
2149 In the first loop, @code{y} is set based on the value of @code{x}
2150 that was just set by the previous clause; in the second loop,
2151 @code{x} and @code{y} are set simultaneously so @code{y} is set
2152 based on the value of @code{x} left over from the previous time
2155 @cindex destructuring, in cl-loop
2156 Another feature of the @code{cl-loop} macro is @emph{destructuring},
2157 similar in concept to the destructuring provided by @code{defmacro}
2158 (@pxref{Argument Lists}).
2159 The @var{var} part of any @code{for} clause can be given as a list
2160 of variables instead of a single variable. The values produced
2161 during loop execution must be lists; the values in the lists are
2162 stored in the corresponding variables.
2165 (cl-loop for (x y) in '((2 3) (4 5) (6 7)) collect (+ x y))
2169 In loop destructuring, if there are more values than variables
2170 the trailing values are ignored, and if there are more variables
2171 than values the trailing variables get the value @code{nil}.
2172 If @code{nil} is used as a variable name, the corresponding
2173 values are ignored. Destructuring may be nested, and dotted
2174 lists of variables like @code{(x . y)} are allowed, so for example
2178 (cl-loop for (key . value) in '((a . 1) (b . 2))
2183 @node Iteration Clauses
2184 @subsection Iteration Clauses
2187 Aside from @code{for} clauses, there are several other loop clauses
2188 that control the way the loop operates. They might be used by
2189 themselves, or in conjunction with one or more @code{for} clauses.
2192 @item repeat @var{integer}
2193 This clause simply counts up to the specified number using an
2194 internal temporary variable. The loops
2197 (cl-loop repeat (1+ n) do @dots{})
2198 (cl-loop for temp to n do @dots{})
2202 are identical except that the second one forces you to choose
2203 a name for a variable you aren't actually going to use.
2205 @item while @var{condition}
2206 This clause stops the loop when the specified condition (any Lisp
2207 expression) becomes @code{nil}. For example, the following two
2208 loops are equivalent, except for the implicit @code{nil} block
2209 that surrounds the second one:
2212 (while @var{cond} @var{forms}@dots{})
2213 (cl-loop while @var{cond} do @var{forms}@dots{})
2216 @item until @var{condition}
2217 This clause stops the loop when the specified condition is true,
2218 i.e., non-@code{nil}.
2220 @item always @var{condition}
2221 This clause stops the loop when the specified condition is @code{nil}.
2222 Unlike @code{while}, it stops the loop using @code{return nil} so that
2223 the @code{finally} clauses are not executed. If all the conditions
2224 were non-@code{nil}, the loop returns @code{t}:
2227 (if (cl-loop for size in size-list always (> size 10))
2232 @item never @var{condition}
2233 This clause is like @code{always}, except that the loop returns
2234 @code{t} if any conditions were false, or @code{nil} otherwise.
2236 @item thereis @var{condition}
2237 This clause stops the loop when the specified form is non-@code{nil};
2238 in this case, it returns that non-@code{nil} value. If all the
2239 values were @code{nil}, the loop returns @code{nil}.
2242 @node Accumulation Clauses
2243 @subsection Accumulation Clauses
2246 These clauses cause the loop to accumulate information about the
2247 specified Lisp @var{form}. The accumulated result is returned
2248 from the loop unless overridden, say, by a @code{return} clause.
2251 @item collect @var{form}
2252 This clause collects the values of @var{form} into a list. Several
2253 examples of @code{collect} appear elsewhere in this manual.
2255 The word @code{collecting} is a synonym for @code{collect}, and
2256 likewise for the other accumulation clauses.
2258 @item append @var{form}
2259 This clause collects lists of values into a result list using
2262 @item nconc @var{form}
2263 This clause collects lists of values into a result list by
2264 destructively modifying the lists rather than copying them.
2266 @item concat @var{form}
2267 This clause concatenates the values of the specified @var{form}
2268 into a string. (It and the following clause are extensions to
2269 standard Common Lisp.)
2271 @item vconcat @var{form}
2272 This clause concatenates the values of the specified @var{form}
2275 @item count @var{form}
2276 This clause counts the number of times the specified @var{form}
2277 evaluates to a non-@code{nil} value.
2279 @item sum @var{form}
2280 This clause accumulates the sum of the values of the specified
2281 @var{form}, which must evaluate to a number.
2283 @item maximize @var{form}
2284 This clause accumulates the maximum value of the specified @var{form},
2285 which must evaluate to a number. The return value is undefined if
2286 @code{maximize} is executed zero times.
2288 @item minimize @var{form}
2289 This clause accumulates the minimum value of the specified @var{form}.
2292 Accumulation clauses can be followed by @samp{into @var{var}} to
2293 cause the data to be collected into variable @var{var} (which is
2294 automatically @code{let}-bound during the loop) rather than an
2295 unnamed temporary variable. Also, @code{into} accumulations do
2296 not automatically imply a return value. The loop must use some
2297 explicit mechanism, such as @code{finally return}, to return
2298 the accumulated result.
2300 It is valid for several accumulation clauses of the same type to
2301 accumulate into the same place. From Steele:
2304 (cl-loop for name in '(fred sue alice joe june)
2305 for kids in '((bob ken) () () (kris sunshine) ())
2308 @result{} (fred bob ken sue alice joe kris sunshine june)
2312 @subsection Other Clauses
2315 This section describes the remaining loop clauses.
2318 @item with @var{var} = @var{value}
2319 This clause binds a variable to a value around the loop, but
2320 otherwise leaves the variable alone during the loop. The following
2321 loops are basically equivalent:
2324 (cl-loop with x = 17 do @dots{})
2325 (let ((x 17)) (cl-loop do @dots{}))
2326 (cl-loop for x = 17 then x do @dots{})
2329 Naturally, the variable @var{var} might be used for some purpose
2330 in the rest of the loop. For example:
2333 (cl-loop for x in my-list with res = nil do (push x res)
2337 This loop inserts the elements of @code{my-list} at the front of
2338 a new list being accumulated in @code{res}, then returns the
2339 list @code{res} at the end of the loop. The effect is similar
2340 to that of a @code{collect} clause, but the list gets reversed
2341 by virtue of the fact that elements are being pushed onto the
2342 front of @code{res} rather than the end.
2344 If you omit the @code{=} term, the variable is initialized to
2345 @code{nil}. (Thus the @samp{= nil} in the above example is
2348 Bindings made by @code{with} are sequential by default, as if
2349 by @code{let*}. Just like @code{for} clauses, @code{with} clauses
2350 can be linked with @code{and} to cause the bindings to be made by
2353 @item if @var{condition} @var{clause}
2354 This clause executes the following loop clause only if the specified
2355 condition is true. The following @var{clause} should be an accumulation,
2356 @code{do}, @code{return}, @code{if}, or @code{unless} clause.
2357 Several clauses may be linked by separating them with @code{and}.
2358 These clauses may be followed by @code{else} and a clause or clauses
2359 to execute if the condition was false. The whole construct may
2360 optionally be followed by the word @code{end} (which may be used to
2361 disambiguate an @code{else} or @code{and} in a nested @code{if}).
2363 The actual non-@code{nil} value of the condition form is available
2364 by the name @code{it} in the ``then'' part. For example:
2367 (setq funny-numbers '(6 13 -1))
2369 (cl-loop for x below 10
2372 and if (memq x funny-numbers) return (cdr it) end
2374 collect x into evens
2375 finally return (vector odds evens))
2376 @result{} [(1 3 5 7 9) (0 2 4 6 8)]
2377 (setq funny-numbers '(6 7 13 -1))
2378 @result{} (6 7 13 -1)
2379 (cl-loop <@r{same thing again}>)
2383 Note the use of @code{and} to put two clauses into the ``then''
2384 part, one of which is itself an @code{if} clause. Note also that
2385 @code{end}, while normally optional, was necessary here to make
2386 it clear that the @code{else} refers to the outermost @code{if}
2387 clause. In the first case, the loop returns a vector of lists
2388 of the odd and even values of @var{x}. In the second case, the
2389 odd number 7 is one of the @code{funny-numbers} so the loop
2390 returns early; the actual returned value is based on the result
2391 of the @code{memq} call.
2393 @item when @var{condition} @var{clause}
2394 This clause is just a synonym for @code{if}.
2396 @item unless @var{condition} @var{clause}
2397 The @code{unless} clause is just like @code{if} except that the
2398 sense of the condition is reversed.
2400 @item named @var{name}
2401 This clause gives a name other than @code{nil} to the implicit
2402 block surrounding the loop. The @var{name} is the symbol to be
2403 used as the block name.
2405 @item initially [do] @var{forms}@dots{}
2406 This keyword introduces one or more Lisp forms which will be
2407 executed before the loop itself begins (but after any variables
2408 requested by @code{for} or @code{with} have been bound to their
2409 initial values). @code{initially} clauses can appear anywhere;
2410 if there are several, they are executed in the order they appear
2411 in the loop. The keyword @code{do} is optional.
2413 @item finally [do] @var{forms}@dots{}
2414 This introduces Lisp forms which will be executed after the loop
2415 finishes (say, on request of a @code{for} or @code{while}).
2416 @code{initially} and @code{finally} clauses may appear anywhere
2417 in the loop construct, but they are executed (in the specified
2418 order) at the beginning or end, respectively, of the loop.
2420 @item finally return @var{form}
2421 This says that @var{form} should be executed after the loop
2422 is done to obtain a return value. (Without this, or some other
2423 clause like @code{collect} or @code{return}, the loop will simply
2424 return @code{nil}.) Variables bound by @code{for}, @code{with},
2425 or @code{into} will still contain their final values when @var{form}
2428 @item do @var{forms}@dots{}
2429 The word @code{do} may be followed by any number of Lisp expressions
2430 which are executed as an implicit @code{progn} in the body of the
2431 loop. Many of the examples in this section illustrate the use of
2434 @item return @var{form}
2435 This clause causes the loop to return immediately. The following
2436 Lisp form is evaluated to give the return value of the loop
2437 form. The @code{finally} clauses, if any, are not executed.
2438 Of course, @code{return} is generally used inside an @code{if} or
2439 @code{unless}, as its use in a top-level loop clause would mean
2440 the loop would never get to ``loop'' more than once.
2442 The clause @samp{return @var{form}} is equivalent to
2443 @samp{do (cl-return @var{form})} (or @code{cl-return-from} if the loop
2444 was named). The @code{return} clause is implemented a bit more
2445 efficiently, though.
2448 While there is no high-level way to add user extensions to @code{cl-loop},
2449 this package does offer two properties called @code{cl-loop-handler}
2450 and @code{cl-loop-for-handler} which are functions to be called when a
2451 given symbol is encountered as a top-level loop clause or @code{for}
2452 clause, respectively. Consult the source code in file
2453 @file{cl-macs.el} for details.
2455 This package's @code{cl-loop} macro is compatible with that of Common
2456 Lisp, except that a few features are not implemented: @code{loop-finish}
2457 and data-type specifiers. Naturally, the @code{for} clauses that
2458 iterate over keymaps, overlays, intervals, frames, windows, and
2459 buffers are Emacs-specific extensions.
2461 @node Multiple Values
2462 @section Multiple Values
2465 Common Lisp functions can return zero or more results. Emacs Lisp
2466 functions, by contrast, always return exactly one result. This
2467 package makes no attempt to emulate Common Lisp multiple return
2468 values; Emacs versions of Common Lisp functions that return more
2469 than one value either return just the first value (as in
2470 @code{cl-compiler-macroexpand}) or return a list of values.
2471 This package @emph{does} define placeholders
2472 for the Common Lisp functions that work with multiple values, but
2473 in Emacs Lisp these functions simply operate on lists instead.
2474 The @code{cl-values} form, for example, is a synonym for @code{list}
2477 @defmac cl-multiple-value-bind (var@dots{}) values-form forms@dots{}
2478 This form evaluates @var{values-form}, which must return a list of
2479 values. It then binds the @var{var}s to these respective values,
2480 as if by @code{let}, and then executes the body @var{forms}.
2481 If there are more @var{var}s than values, the extra @var{var}s
2482 are bound to @code{nil}. If there are fewer @var{var}s than
2483 values, the excess values are ignored.
2486 @defmac cl-multiple-value-setq (var@dots{}) form
2487 This form evaluates @var{form}, which must return a list of values.
2488 It then sets the @var{var}s to these respective values, as if by
2489 @code{setq}. Extra @var{var}s or values are treated the same as
2490 in @code{cl-multiple-value-bind}.
2493 Since a perfect emulation is not feasible in Emacs Lisp, this
2494 package opts to keep it as simple and predictable as possible.
2500 This package implements the various Common Lisp features of
2501 @code{defmacro}, such as destructuring, @code{&environment},
2502 and @code{&body}. Top-level @code{&whole} is not implemented
2503 for @code{defmacro} due to technical difficulties.
2504 @xref{Argument Lists}.
2506 Destructuring is made available to the user by way of the
2509 @defmac cl-destructuring-bind arglist expr forms@dots{}
2510 This macro expands to code that executes @var{forms}, with
2511 the variables in @var{arglist} bound to the list of values
2512 returned by @var{expr}. The @var{arglist} can include all
2513 the features allowed for @code{cl-defmacro} argument lists,
2514 including destructuring. (The @code{&environment} keyword
2515 is not allowed.) The macro expansion will signal an error
2516 if @var{expr} returns a list of the wrong number of arguments
2517 or with incorrect keyword arguments.
2520 @cindex compiler macros
2521 @cindex define compiler macros
2522 This package also includes the Common Lisp @code{define-compiler-macro}
2523 facility, which allows you to define compile-time expansions and
2524 optimizations for your functions.
2526 @defmac cl-define-compiler-macro name arglist forms@dots{}
2527 This form is similar to @code{defmacro}, except that it only expands
2528 calls to @var{name} at compile-time; calls processed by the Lisp
2529 interpreter are not expanded, nor are they expanded by the
2530 @code{macroexpand} function.
2532 The argument list may begin with a @code{&whole} keyword and a
2533 variable. This variable is bound to the macro-call form itself,
2534 i.e., to a list of the form @samp{(@var{name} @var{args}@dots{})}.
2535 If the macro expander returns this form unchanged, then the
2536 compiler treats it as a normal function call. This allows
2537 compiler macros to work as optimizers for special cases of a
2538 function, leaving complicated cases alone.
2540 For example, here is a simplified version of a definition that
2541 appears as a standard part of this package:
2544 (cl-define-compiler-macro cl-member (&whole form a list &rest keys)
2545 (if (and (null keys)
2546 (eq (car-safe a) 'quote)
2547 (not (floatp (cadr a))))
2553 This definition causes @code{(cl-member @var{a} @var{list})} to change
2554 to a call to the faster @code{memq} in the common case where @var{a}
2555 is a non-floating-point constant; if @var{a} is anything else, or
2556 if there are any keyword arguments in the call, then the original
2557 @code{cl-member} call is left intact. (The actual compiler macro
2558 for @code{cl-member} optimizes a number of other cases, including
2559 common @code{:test} predicates.)
2562 @defun cl-compiler-macroexpand form
2563 This function is analogous to @code{macroexpand}, except that it
2564 expands compiler macros rather than regular macros. It returns
2565 @var{form} unchanged if it is not a call to a function for which
2566 a compiler macro has been defined, or if that compiler macro
2567 decided to punt by returning its @code{&whole} argument. Like
2568 @code{macroexpand}, it expands repeatedly until it reaches a form
2569 for which no further expansion is possible.
2572 @xref{Macro Bindings}, for descriptions of the @code{cl-macrolet}
2573 and @code{cl-symbol-macrolet} forms for making ``local'' macro
2577 @chapter Declarations
2580 Common Lisp includes a complex and powerful ``declaration''
2581 mechanism that allows you to give the compiler special hints
2582 about the types of data that will be stored in particular variables,
2583 and about the ways those variables and functions will be used. This
2584 package defines versions of all the Common Lisp declaration forms:
2585 @code{declare}, @code{locally}, @code{proclaim}, @code{declaim},
2588 Most of the Common Lisp declarations are not currently useful in Emacs
2589 Lisp. For example, the byte-code system provides little
2590 opportunity to benefit from type information.
2592 and @code{special} declarations are redundant in a fully
2593 dynamically-scoped Lisp.
2595 A few declarations are meaningful when byte compiler optimizations
2596 are enabled, as they are by the default. Otherwise these
2597 declarations will effectively be ignored.
2599 @defun cl-proclaim decl-spec
2600 This function records a ``global'' declaration specified by
2601 @var{decl-spec}. Since @code{cl-proclaim} is a function, @var{decl-spec}
2602 is evaluated and thus should normally be quoted.
2605 @defmac cl-declaim decl-specs@dots{}
2606 This macro is like @code{cl-proclaim}, except that it takes any number
2607 of @var{decl-spec} arguments, and the arguments are unevaluated and
2608 unquoted. The @code{cl-declaim} macro also puts @code{(cl-eval-when
2609 (compile load eval) @dots{})} around the declarations so that they will
2610 be registered at compile-time as well as at run-time. (This is vital,
2611 since normally the declarations are meant to influence the way the
2612 compiler treats the rest of the file that contains the @code{cl-declaim}
2616 @defmac cl-declare decl-specs@dots{}
2617 This macro is used to make declarations within functions and other
2618 code. Common Lisp allows declarations in various locations, generally
2619 at the beginning of any of the many ``implicit @code{progn}s''
2620 throughout Lisp syntax, such as function bodies, @code{let} bodies,
2621 etc. Currently the only declaration understood by @code{cl-declare}
2625 @defmac cl-locally declarations@dots{} forms@dots{}
2626 In this package, @code{cl-locally} is no different from @code{progn}.
2629 @defmac cl-the type form
2630 @code{cl-the} returns the value of @code{form}, first checking (if
2631 optimization settings permit) that it is of type @code{type}. Future
2632 byte-compiler optimizations may also make use of this information to
2633 improve runtime efficiency.
2635 For example, @code{mapcar} can map over both lists and arrays. It is
2636 hard for the compiler to expand @code{mapcar} into an in-line loop
2637 unless it knows whether the sequence will be a list or an array ahead
2638 of time. With @code{(mapcar 'car (cl-the vector foo))}, a future
2639 compiler would have enough information to expand the loop in-line.
2640 For now, Emacs Lisp will treat the above code as exactly equivalent
2641 to @code{(mapcar 'car foo)}.
2644 Each @var{decl-spec} in a @code{cl-proclaim}, @code{cl-declaim}, or
2645 @code{cl-declare} should be a list beginning with a symbol that says
2646 what kind of declaration it is. This package currently understands
2647 @code{special}, @code{inline}, @code{notinline}, @code{optimize},
2648 and @code{warn} declarations. (The @code{warn} declaration is an
2649 extension of standard Common Lisp.) Other Common Lisp declarations,
2650 such as @code{type} and @code{ftype}, are silently ignored.
2655 Since all variables in Emacs Lisp are ``special'' (in the Common
2656 Lisp sense), @code{special} declarations are only advisory. They
2657 simply tell the byte compiler that the specified
2658 variables are intentionally being referred to without being
2659 bound in the body of the function. The compiler normally emits
2660 warnings for such references, since they could be typographical
2661 errors for references to local variables.
2663 The declaration @code{(cl-declare (special @var{var1} @var{var2}))} is
2664 equivalent to @code{(defvar @var{var1}) (defvar @var{var2})}.
2666 In top-level contexts, it is generally better to write
2667 @code{(defvar @var{var})} than @code{(cl-declaim (special @var{var}))},
2668 since @code{defvar} makes your intentions clearer.
2671 The @code{inline} @var{decl-spec} lists one or more functions
2672 whose bodies should be expanded ``in-line'' into calling functions
2673 whenever the compiler is able to arrange for it. For example,
2674 the function @code{cl-acons} is declared @code{inline}
2675 by this package so that the form @code{(cl-acons @var{key} @var{value}
2677 expand directly into @code{(cons (cons @var{key} @var{value}) @var{alist})}
2678 when it is called in user functions, so as to save function calls.
2680 The following declarations are all equivalent. Note that the
2681 @code{defsubst} form is a convenient way to define a function
2682 and declare it inline all at once.
2685 (cl-declaim (inline foo bar))
2686 (cl-eval-when (compile load eval)
2687 (cl-proclaim '(inline foo bar)))
2688 (defsubst foo (@dots{}) @dots{}) ; instead of defun
2691 @strong{Please note:} this declaration remains in effect after the
2692 containing source file is done. It is correct to use it to
2693 request that a function you have defined should be inlined,
2694 but it is impolite to use it to request inlining of an external
2697 In Common Lisp, it is possible to use @code{(declare (inline @dots{}))}
2698 before a particular call to a function to cause just that call to
2699 be inlined; the current byte compilers provide no way to implement
2700 this, so @code{(cl-declare (inline @dots{}))} is currently ignored by
2704 The @code{notinline} declaration lists functions which should
2705 not be inlined after all; it cancels a previous @code{inline}
2709 This declaration controls how much optimization is performed by
2712 The word @code{optimize} is followed by any number of lists like
2713 @code{(speed 3)} or @code{(safety 2)}. Common Lisp defines several
2714 optimization ``qualities''; this package ignores all but @code{speed}
2715 and @code{safety}. The value of a quality should be an integer from
2716 0 to 3, with 0 meaning ``unimportant'' and 3 meaning ``very important''.
2717 The default level for both qualities is 1.
2719 In this package, the @code{speed} quality is tied to the @code{byte-optimize}
2720 flag, which is set to @code{nil} for @code{(speed 0)} and to
2721 @code{t} for higher settings; and the @code{safety} quality is
2722 tied to the @code{byte-compile-delete-errors} flag, which is
2723 set to @code{nil} for @code{(safety 3)} and to @code{t} for all
2724 lower settings. (The latter flag controls whether the compiler
2725 is allowed to optimize out code whose only side-effect could
2726 be to signal an error, e.g., rewriting @code{(progn foo bar)} to
2727 @code{bar} when it is not known whether @code{foo} will be bound
2730 Note that even compiling with @code{(safety 0)}, the Emacs
2731 byte-code system provides sufficient checking to prevent real
2732 harm from being done. For example, barring serious bugs in
2733 Emacs itself, Emacs will not crash with a segmentation fault
2734 just because of an error in a fully-optimized Lisp program.
2736 The @code{optimize} declaration is normally used in a top-level
2737 @code{cl-proclaim} or @code{cl-declaim} in a file; Common Lisp allows
2738 it to be used with @code{declare} to set the level of optimization
2739 locally for a given form, but this will not work correctly with the
2740 current byte-compiler. (The @code{cl-declare}
2741 will set the new optimization level, but that level will not
2742 automatically be unset after the enclosing form is done.)
2745 This declaration controls what sorts of warnings are generated
2746 by the byte compiler. The word @code{warn} is followed by any
2747 number of ``warning qualities'', similar in form to optimization
2748 qualities. The currently supported warning types are
2749 @code{redefine}, @code{callargs}, @code{unresolved}, and
2750 @code{free-vars}; in the current system, a value of 0 will
2751 disable these warnings and any higher value will enable them.
2752 See the documentation of the variable @code{byte-compile-warnings}
2760 This package defines several symbol-related features that were
2761 missing from Emacs Lisp.
2764 * Property Lists:: @code{cl-get}, @code{cl-remprop}, @code{cl-getf}, @code{cl-remf}.
2765 * Creating Symbols:: @code{cl-gensym}, @code{cl-gentemp}.
2768 @node Property Lists
2769 @section Property Lists
2772 These functions augment the standard Emacs Lisp functions @code{get}
2773 and @code{put} for operating on properties attached to symbols.
2774 There are also functions for working with property lists as
2775 first-class data structures not attached to particular symbols.
2777 @defun cl-get symbol property &optional default
2778 This function is like @code{get}, except that if the property is
2779 not found, the @var{default} argument provides the return value.
2780 (The Emacs Lisp @code{get} function always uses @code{nil} as
2781 the default; this package's @code{cl-get} is equivalent to Common
2784 The @code{cl-get} function is @code{setf}-able; when used in this
2785 fashion, the @var{default} argument is allowed but ignored.
2788 @defun cl-remprop symbol property
2789 This function removes the entry for @var{property} from the property
2790 list of @var{symbol}. It returns a true value if the property was
2791 indeed found and removed, or @code{nil} if there was no such property.
2792 (This function was probably omitted from Emacs originally because,
2793 since @code{get} did not allow a @var{default}, it was very difficult
2794 to distinguish between a missing property and a property whose value
2795 was @code{nil}; thus, setting a property to @code{nil} was close
2796 enough to @code{cl-remprop} for most purposes.)
2799 @defun cl-getf place property &optional default
2800 This function scans the list @var{place} as if it were a property
2801 list, i.e., a list of alternating property names and values. If
2802 an even-numbered element of @var{place} is found which is @code{eq}
2803 to @var{property}, the following odd-numbered element is returned.
2804 Otherwise, @var{default} is returned (or @code{nil} if no default
2810 (get sym prop) @equiv{} (cl-getf (symbol-plist sym) prop)
2813 It is valid to use @code{cl-getf} as a @code{setf} place, in which case
2814 its @var{place} argument must itself be a valid @code{setf} place.
2815 The @var{default} argument, if any, is ignored in this context.
2816 The effect is to change (via @code{setcar}) the value cell in the
2817 list that corresponds to @var{property}, or to cons a new property-value
2818 pair onto the list if the property is not yet present.
2821 (put sym prop val) @equiv{} (setf (cl-getf (symbol-plist sym) prop) val)
2824 The @code{get} and @code{cl-get} functions are also @code{setf}-able.
2825 The fact that @code{default} is ignored can sometimes be useful:
2828 (cl-incf (cl-get 'foo 'usage-count 0))
2831 Here, symbol @code{foo}'s @code{usage-count} property is incremented
2832 if it exists, or set to 1 (an incremented 0) otherwise.
2834 When not used as a @code{setf} form, @code{cl-getf} is just a regular
2835 function and its @var{place} argument can actually be any Lisp
2839 @defmac cl-remf place property
2840 This macro removes the property-value pair for @var{property} from
2841 the property list stored at @var{place}, which is any @code{setf}-able
2842 place expression. It returns true if the property was found. Note
2843 that if @var{property} happens to be first on the list, this will
2844 effectively do a @code{(setf @var{place} (cddr @var{place}))},
2845 whereas if it occurs later, this simply uses @code{setcdr} to splice
2846 out the property and value cells.
2849 @node Creating Symbols
2850 @section Creating Symbols
2853 These functions create unique symbols, typically for use as
2854 temporary variables.
2856 @defun cl-gensym &optional x
2857 This function creates a new, uninterned symbol (using @code{make-symbol})
2858 with a unique name. (The name of an uninterned symbol is relevant
2859 only if the symbol is printed.) By default, the name is generated
2860 from an increasing sequence of numbers, @samp{G1000}, @samp{G1001},
2861 @samp{G1002}, etc. If the optional argument @var{x} is a string, that
2862 string is used as a prefix instead of @samp{G}. Uninterned symbols
2863 are used in macro expansions for temporary variables, to ensure that
2864 their names will not conflict with ``real'' variables in the user's
2867 (Internally, the variable @code{cl--gensym-counter} holds the counter
2868 used to generate names. It is incremented after each use. In Common
2869 Lisp this is initialized with 0, but this package initializes it with
2870 a random time-dependent value to avoid trouble when two files that
2871 each used @code{cl-gensym} in their compilation are loaded together.
2872 Uninterned symbols become interned when the compiler writes them out
2873 to a file and the Emacs loader loads them, so their names have to be
2874 treated a bit more carefully than in Common Lisp where uninterned
2875 symbols remain uninterned after loading.)
2878 @defun cl-gentemp &optional x
2879 This function is like @code{cl-gensym}, except that it produces a new
2880 @emph{interned} symbol. If the symbol that is generated already
2881 exists, the function keeps incrementing the counter and trying
2882 again until a new symbol is generated.
2885 This package automatically creates all keywords that are called for by
2886 @code{&key} argument specifiers, and discourages the use of keywords
2887 as data unrelated to keyword arguments, so the related function
2888 @code{defkeyword} (to create self-quoting keyword symbols) is not
2895 This section defines a few simple Common Lisp operations on numbers
2896 that were left out of Emacs Lisp.
2899 * Predicates on Numbers:: @code{cl-plusp}, @code{cl-oddp}, etc.
2900 * Numerical Functions:: @code{cl-floor}, @code{cl-ceiling}, etc.
2901 * Random Numbers:: @code{cl-random}, @code{cl-make-random-state}.
2902 * Implementation Parameters:: @code{cl-most-positive-float}, etc.
2905 @node Predicates on Numbers
2906 @section Predicates on Numbers
2909 These functions return @code{t} if the specified condition is
2910 true of the numerical argument, or @code{nil} otherwise.
2912 @defun cl-plusp number
2913 This predicate tests whether @var{number} is positive. It is an
2914 error if the argument is not a number.
2917 @defun cl-minusp number
2918 This predicate tests whether @var{number} is negative. It is an
2919 error if the argument is not a number.
2922 @defun cl-oddp integer
2923 This predicate tests whether @var{integer} is odd. It is an
2924 error if the argument is not an integer.
2927 @defun cl-evenp integer
2928 This predicate tests whether @var{integer} is even. It is an
2929 error if the argument is not an integer.
2932 @node Numerical Functions
2933 @section Numerical Functions
2936 These functions perform various arithmetic operations on numbers.
2938 @defun cl-gcd &rest integers
2939 This function returns the Greatest Common Divisor of the arguments.
2940 For one argument, it returns the absolute value of that argument.
2941 For zero arguments, it returns zero.
2944 @defun cl-lcm &rest integers
2945 This function returns the Least Common Multiple of the arguments.
2946 For one argument, it returns the absolute value of that argument.
2947 For zero arguments, it returns one.
2950 @defun cl-isqrt integer
2951 This function computes the ``integer square root'' of its integer
2952 argument, i.e., the greatest integer less than or equal to the true
2953 square root of the argument.
2956 @defun cl-floor number &optional divisor
2957 With one argument, @code{cl-floor} returns a list of two numbers:
2958 The argument rounded down (toward minus infinity) to an integer,
2959 and the ``remainder'' which would have to be added back to the
2960 first return value to yield the argument again. If the argument
2961 is an integer @var{x}, the result is always the list @code{(@var{x} 0)}.
2962 If the argument is a floating-point number, the first
2963 result is a Lisp integer and the second is a Lisp float between
2964 0 (inclusive) and 1 (exclusive).
2966 With two arguments, @code{cl-floor} divides @var{number} by
2967 @var{divisor}, and returns the floor of the quotient and the
2968 corresponding remainder as a list of two numbers. If
2969 @code{(cl-floor @var{x} @var{y})} returns @code{(@var{q} @var{r})},
2970 then @code{@var{q}*@var{y} + @var{r} = @var{x}}, with @var{r}
2971 between 0 (inclusive) and @var{r} (exclusive). Also, note
2972 that @code{(cl-floor @var{x})} is exactly equivalent to
2973 @code{(cl-floor @var{x} 1)}.
2975 This function is entirely compatible with Common Lisp's @code{floor}
2976 function, except that it returns the two results in a list since
2977 Emacs Lisp does not support multiple-valued functions.
2980 @defun cl-ceiling number &optional divisor
2981 This function implements the Common Lisp @code{ceiling} function,
2982 which is analogous to @code{floor} except that it rounds the
2983 argument or quotient of the arguments up toward plus infinity.
2984 The remainder will be between 0 and minus @var{r}.
2987 @defun cl-truncate number &optional divisor
2988 This function implements the Common Lisp @code{truncate} function,
2989 which is analogous to @code{floor} except that it rounds the
2990 argument or quotient of the arguments toward zero. Thus it is
2991 equivalent to @code{cl-floor} if the argument or quotient is
2992 positive, or to @code{cl-ceiling} otherwise. The remainder has
2993 the same sign as @var{number}.
2996 @defun cl-round number &optional divisor
2997 This function implements the Common Lisp @code{round} function,
2998 which is analogous to @code{floor} except that it rounds the
2999 argument or quotient of the arguments to the nearest integer.
3000 In the case of a tie (the argument or quotient is exactly
3001 halfway between two integers), it rounds to the even integer.
3004 @defun cl-mod number divisor
3005 This function returns the same value as the second return value
3009 @defun cl-rem number divisor
3010 This function returns the same value as the second return value
3011 of @code{cl-truncate}.
3014 @node Random Numbers
3015 @section Random Numbers
3018 This package also provides an implementation of the Common Lisp
3019 random number generator. It uses its own additive-congruential
3020 algorithm, which is much more likely to give statistically clean
3021 @c FIXME? Still true?
3022 random numbers than the simple generators supplied by many
3025 @defun cl-random number &optional state
3026 This function returns a random nonnegative number less than
3027 @var{number}, and of the same type (either integer or floating-point).
3028 The @var{state} argument should be a @code{random-state} object
3029 that holds the state of the random number generator. The
3030 function modifies this state object as a side effect. If
3031 @var{state} is omitted, it defaults to the internal variable
3032 @code{cl--random-state}, which contains a pre-initialized
3033 default @code{random-state} object. (Since any number of programs in
3034 the Emacs process may be accessing @code{cl--random-state} in
3035 interleaved fashion, the sequence generated from this will be
3036 irreproducible for all intents and purposes.)
3039 @defun cl-make-random-state &optional state
3040 This function creates or copies a @code{random-state} object.
3041 If @var{state} is omitted or @code{nil}, it returns a new copy of
3042 @code{cl--random-state}. This is a copy in the sense that future
3043 sequences of calls to @code{(cl-random @var{n})} and
3044 @code{(cl-random @var{n} @var{s})} (where @var{s} is the new
3045 random-state object) will return identical sequences of random
3048 If @var{state} is a @code{random-state} object, this function
3049 returns a copy of that object. If @var{state} is @code{t}, this
3050 function returns a new @code{random-state} object seeded from the
3051 date and time. As an extension to Common Lisp, @var{state} may also
3052 be an integer in which case the new object is seeded from that
3053 integer; each different integer seed will result in a completely
3054 different sequence of random numbers.
3056 It is valid to print a @code{random-state} object to a buffer or
3057 file and later read it back with @code{read}. If a program wishes
3058 to use a sequence of pseudo-random numbers which can be reproduced
3059 later for debugging, it can call @code{(cl-make-random-state t)} to
3060 get a new sequence, then print this sequence to a file. When the
3061 program is later rerun, it can read the original run's random-state
3065 @defun cl-random-state-p object
3066 This predicate returns @code{t} if @var{object} is a
3067 @code{random-state} object, or @code{nil} otherwise.
3070 @node Implementation Parameters
3071 @section Implementation Parameters
3074 This package defines several useful constants having to do with
3075 floating-point numbers.
3077 It determines their values by exercising the computer's
3078 floating-point arithmetic in various ways. Because this operation
3079 might be slow, the code for initializing them is kept in a separate
3080 function that must be called before the parameters can be used.
3082 @defun cl-float-limits
3083 This function makes sure that the Common Lisp floating-point parameters
3084 like @code{cl-most-positive-float} have been initialized. Until it is
3085 called, these parameters will be @code{nil}.
3086 @c If this version of Emacs does not support floats, the parameters will
3087 @c remain @code{nil}.
3088 If the parameters have already been initialized, the function returns
3091 The algorithm makes assumptions that will be valid for almost all
3092 machines, but will fail if the machine's arithmetic is extremely
3093 unusual, e.g., decimal.
3096 Since true Common Lisp supports up to four different floating-point
3097 precisions, it has families of constants like
3098 @code{most-positive-single-float}, @code{most-positive-double-float},
3099 @code{most-positive-long-float}, and so on. Emacs has only one
3100 floating-point precision, so this package omits the precision word
3101 from the constants' names.
3103 @defvar cl-most-positive-float
3104 This constant equals the largest value a Lisp float can hold.
3105 For those systems whose arithmetic supports infinities, this is
3106 the largest @emph{finite} value. For IEEE machines, the value
3107 is approximately @code{1.79e+308}.
3110 @defvar cl-most-negative-float
3111 This constant equals the most negative value a Lisp float can hold.
3112 (It is assumed to be equal to @code{(- cl-most-positive-float)}.)
3115 @defvar cl-least-positive-float
3116 This constant equals the smallest Lisp float value greater than zero.
3117 For IEEE machines, it is about @code{4.94e-324} if denormals are
3118 supported or @code{2.22e-308} if not.
3121 @defvar cl-least-positive-normalized-float
3122 This constant equals the smallest @emph{normalized} Lisp float greater
3123 than zero, i.e., the smallest value for which IEEE denormalization
3124 will not result in a loss of precision. For IEEE machines, this
3125 value is about @code{2.22e-308}. For machines that do not support
3126 the concept of denormalization and gradual underflow, this constant
3127 will always equal @code{cl-least-positive-float}.
3130 @defvar cl-least-negative-float
3131 This constant is the negative counterpart of @code{cl-least-positive-float}.
3134 @defvar cl-least-negative-normalized-float
3135 This constant is the negative counterpart of
3136 @code{cl-least-positive-normalized-float}.
3139 @defvar cl-float-epsilon
3140 This constant is the smallest positive Lisp float that can be added
3141 to 1.0 to produce a distinct value. Adding a smaller number to 1.0
3142 will yield 1.0 again due to roundoff. For IEEE machines, epsilon
3143 is about @code{2.22e-16}.
3146 @defvar cl-float-negative-epsilon
3147 This is the smallest positive value that can be subtracted from
3148 1.0 to produce a distinct value. For IEEE machines, it is about
3156 Common Lisp defines a number of functions that operate on
3157 @dfn{sequences}, which are either lists, strings, or vectors.
3158 Emacs Lisp includes a few of these, notably @code{elt} and
3159 @code{length}; this package defines most of the rest.
3162 * Sequence Basics:: Arguments shared by all sequence functions.
3163 * Mapping over Sequences:: @code{cl-mapcar}, @code{cl-map}, @code{cl-maplist}, etc.
3164 * Sequence Functions:: @code{cl-subseq}, @code{cl-remove}, @code{cl-substitute}, etc.
3165 * Searching Sequences:: @code{cl-find}, @code{cl-count}, @code{cl-search}, etc.
3166 * Sorting Sequences:: @code{cl-sort}, @code{cl-stable-sort}, @code{cl-merge}.
3169 @node Sequence Basics
3170 @section Sequence Basics
3173 Many of the sequence functions take keyword arguments; @pxref{Argument
3174 Lists}. All keyword arguments are optional and, if specified,
3175 may appear in any order.
3177 The @code{:key} argument should be passed either @code{nil}, or a
3178 function of one argument. This key function is used as a filter
3179 through which the elements of the sequence are seen; for example,
3180 @code{(cl-find x y :key 'car)} is similar to @code{(cl-assoc x y)}.
3181 It searches for an element of the list whose @sc{car} equals
3182 @code{x}, rather than for an element which equals @code{x} itself.
3183 If @code{:key} is omitted or @code{nil}, the filter is effectively
3184 the identity function.
3186 The @code{:test} and @code{:test-not} arguments should be either
3187 @code{nil}, or functions of two arguments. The test function is
3188 used to compare two sequence elements, or to compare a search value
3189 with sequence elements. (The two values are passed to the test
3190 function in the same order as the original sequence function
3191 arguments from which they are derived, or, if they both come from
3192 the same sequence, in the same order as they appear in that sequence.)
3193 The @code{:test} argument specifies a function which must return
3194 true (non-@code{nil}) to indicate a match; instead, you may use
3195 @code{:test-not} to give a function which returns @emph{false} to
3196 indicate a match. The default test function is @code{eql}.
3198 Many functions that take @var{item} and @code{:test} or @code{:test-not}
3199 arguments also come in @code{-if} and @code{-if-not} varieties,
3200 where a @var{predicate} function is passed instead of @var{item},
3201 and sequence elements match if the predicate returns true on them
3202 (or false in the case of @code{-if-not}). For example:
3205 (cl-remove 0 seq :test '=) @equiv{} (cl-remove-if 'zerop seq)
3209 to remove all zeros from sequence @code{seq}.
3211 Some operations can work on a subsequence of the argument sequence;
3212 these function take @code{:start} and @code{:end} arguments, which
3213 default to zero and the length of the sequence, respectively.
3214 Only elements between @var{start} (inclusive) and @var{end}
3215 (exclusive) are affected by the operation. The @var{end} argument
3216 may be passed @code{nil} to signify the length of the sequence;
3217 otherwise, both @var{start} and @var{end} must be integers, with
3218 @code{0 <= @var{start} <= @var{end} <= (length @var{seq})}.
3219 If the function takes two sequence arguments, the limits are
3220 defined by keywords @code{:start1} and @code{:end1} for the first,
3221 and @code{:start2} and @code{:end2} for the second.
3223 A few functions accept a @code{:from-end} argument, which, if
3224 non-@code{nil}, causes the operation to go from right-to-left
3225 through the sequence instead of left-to-right, and a @code{:count}
3226 argument, which specifies an integer maximum number of elements
3227 to be removed or otherwise processed.
3229 The sequence functions make no guarantees about the order in
3230 which the @code{:test}, @code{:test-not}, and @code{:key} functions
3231 are called on various elements. Therefore, it is a bad idea to depend
3232 on side effects of these functions. For example, @code{:from-end}
3233 may cause the sequence to be scanned actually in reverse, or it may
3234 be scanned forwards but computing a result ``as if'' it were scanned
3235 backwards. (Some functions, like @code{cl-mapcar} and @code{cl-every},
3236 @emph{do} specify exactly the order in which the function is called
3237 so side effects are perfectly acceptable in those cases.)
3239 Strings may contain ``text properties'' as well
3240 as character data. Except as noted, it is undefined whether or
3241 not text properties are preserved by sequence functions. For
3242 example, @code{(cl-remove ?A @var{str})} may or may not preserve
3243 the properties of the characters copied from @var{str} into the
3246 @node Mapping over Sequences
3247 @section Mapping over Sequences
3250 These functions ``map'' the function you specify over the elements
3251 of lists or arrays. They are all variations on the theme of the
3252 built-in function @code{mapcar}.
3254 @defun cl-mapcar function seq &rest more-seqs
3255 This function calls @var{function} on successive parallel sets of
3256 elements from its argument sequences. Given a single @var{seq}
3257 argument it is equivalent to @code{mapcar}; given @var{n} sequences,
3258 it calls the function with the first elements of each of the sequences
3259 as the @var{n} arguments to yield the first element of the result
3260 list, then with the second elements, and so on. The mapping stops as
3261 soon as the shortest sequence runs out. The argument sequences may
3262 be any mixture of lists, strings, and vectors; the return sequence
3265 Common Lisp's @code{mapcar} accepts multiple arguments but works
3266 only on lists; Emacs Lisp's @code{mapcar} accepts a single sequence
3267 argument. This package's @code{cl-mapcar} works as a compatible
3271 @defun cl-map result-type function seq &rest more-seqs
3272 This function maps @var{function} over the argument sequences,
3273 just like @code{cl-mapcar}, but it returns a sequence of type
3274 @var{result-type} rather than a list. @var{result-type} must
3275 be one of the following symbols: @code{vector}, @code{string},
3276 @code{list} (in which case the effect is the same as for
3277 @code{cl-mapcar}), or @code{nil} (in which case the results are
3278 thrown away and @code{cl-map} returns @code{nil}).
3281 @defun cl-maplist function list &rest more-lists
3282 This function calls @var{function} on each of its argument lists,
3283 then on the @sc{cdr}s of those lists, and so on, until the
3284 shortest list runs out. The results are returned in the form
3285 of a list. Thus, @code{cl-maplist} is like @code{cl-mapcar} except
3286 that it passes in the list pointers themselves rather than the
3287 @sc{car}s of the advancing pointers.
3290 @defun cl-mapc function seq &rest more-seqs
3291 This function is like @code{cl-mapcar}, except that the values returned
3292 by @var{function} are ignored and thrown away rather than being
3293 collected into a list. The return value of @code{cl-mapc} is @var{seq},
3294 the first sequence. This function is more general than the Emacs
3295 primitive @code{mapc}. (Note that this function is called
3296 @code{cl-mapc} even in @file{cl.el}, rather than @code{mapc*} as you
3298 @c http://debbugs.gnu.org/6575
3301 @defun cl-mapl function list &rest more-lists
3302 This function is like @code{cl-maplist}, except that it throws away
3303 the values returned by @var{function}.
3306 @defun cl-mapcan function seq &rest more-seqs
3307 This function is like @code{cl-mapcar}, except that it concatenates
3308 the return values (which must be lists) using @code{nconc},
3309 rather than simply collecting them into a list.
3312 @defun cl-mapcon function list &rest more-lists
3313 This function is like @code{cl-maplist}, except that it concatenates
3314 the return values using @code{nconc}.
3317 @defun cl-some predicate seq &rest more-seqs
3318 This function calls @var{predicate} on each element of @var{seq}
3319 in turn; if @var{predicate} returns a non-@code{nil} value,
3320 @code{cl-some} returns that value, otherwise it returns @code{nil}.
3321 Given several sequence arguments, it steps through the sequences
3322 in parallel until the shortest one runs out, just as in
3323 @code{cl-mapcar}. You can rely on the left-to-right order in which
3324 the elements are visited, and on the fact that mapping stops
3325 immediately as soon as @var{predicate} returns non-@code{nil}.
3328 @defun cl-every predicate seq &rest more-seqs
3329 This function calls @var{predicate} on each element of the sequence(s)
3330 in turn; it returns @code{nil} as soon as @var{predicate} returns
3331 @code{nil} for any element, or @code{t} if the predicate was true
3335 @defun cl-notany predicate seq &rest more-seqs
3336 This function calls @var{predicate} on each element of the sequence(s)
3337 in turn; it returns @code{nil} as soon as @var{predicate} returns
3338 a non-@code{nil} value for any element, or @code{t} if the predicate
3339 was @code{nil} for all elements.
3342 @defun cl-notevery predicate seq &rest more-seqs
3343 This function calls @var{predicate} on each element of the sequence(s)
3344 in turn; it returns a non-@code{nil} value as soon as @var{predicate}
3345 returns @code{nil} for any element, or @code{t} if the predicate was
3346 true for all elements.
3349 @defun cl-reduce function seq @t{&key :from-end :start :end :initial-value :key}
3350 This function combines the elements of @var{seq} using an associative
3351 binary operation. Suppose @var{function} is @code{*} and @var{seq} is
3352 the list @code{(2 3 4 5)}. The first two elements of the list are
3353 combined with @code{(* 2 3) = 6}; this is combined with the next
3354 element, @code{(* 6 4) = 24}, and that is combined with the final
3355 element: @code{(* 24 5) = 120}. Note that the @code{*} function happens
3356 to be self-reducing, so that @code{(* 2 3 4 5)} has the same effect as
3357 an explicit call to @code{cl-reduce}.
3359 If @code{:from-end} is true, the reduction is right-associative instead
3360 of left-associative:
3363 (cl-reduce '- '(1 2 3 4))
3364 @equiv{} (- (- (- 1 2) 3) 4) @result{} -8
3365 (cl-reduce '- '(1 2 3 4) :from-end t)
3366 @equiv{} (- 1 (- 2 (- 3 4))) @result{} -2
3369 If @code{:key} is specified, it is a function of one argument, which
3370 is called on each of the sequence elements in turn.
3372 If @code{:initial-value} is specified, it is effectively added to the
3373 front (or rear in the case of @code{:from-end}) of the sequence.
3374 The @code{:key} function is @emph{not} applied to the initial value.
3376 If the sequence, including the initial value, has exactly one element
3377 then that element is returned without ever calling @var{function}.
3378 If the sequence is empty (and there is no initial value), then
3379 @var{function} is called with no arguments to obtain the return value.
3382 All of these mapping operations can be expressed conveniently in
3383 terms of the @code{cl-loop} macro. In compiled code, @code{cl-loop} will
3384 be faster since it generates the loop as in-line code with no
3387 @node Sequence Functions
3388 @section Sequence Functions
3391 This section describes a number of Common Lisp functions for
3392 operating on sequences.
3394 @defun cl-subseq sequence start &optional end
3395 This function returns a given subsequence of the argument
3396 @var{sequence}, which may be a list, string, or vector.
3397 The indices @var{start} and @var{end} must be in range, and
3398 @var{start} must be no greater than @var{end}. If @var{end}
3399 is omitted, it defaults to the length of the sequence. The
3400 return value is always a copy; it does not share structure
3401 with @var{sequence}.
3403 As an extension to Common Lisp, @var{start} and/or @var{end}
3404 may be negative, in which case they represent a distance back
3405 from the end of the sequence. This is for compatibility with
3406 Emacs's @code{substring} function. Note that @code{cl-subseq} is
3407 the @emph{only} sequence function that allows negative
3408 @var{start} and @var{end}.
3410 You can use @code{setf} on a @code{cl-subseq} form to replace a
3411 specified range of elements with elements from another sequence.
3412 The replacement is done as if by @code{cl-replace}, described below.
3415 @defun cl-concatenate result-type &rest seqs
3416 This function concatenates the argument sequences together to
3417 form a result sequence of type @var{result-type}, one of the
3418 symbols @code{vector}, @code{string}, or @code{list}. The
3419 arguments are always copied, even in cases such as
3420 @code{(cl-concatenate 'list '(1 2 3))} where the result is
3421 identical to an argument.
3424 @defun cl-fill seq item @t{&key :start :end}
3425 This function fills the elements of the sequence (or the specified
3426 part of the sequence) with the value @var{item}.
3429 @defun cl-replace seq1 seq2 @t{&key :start1 :end1 :start2 :end2}
3430 This function copies part of @var{seq2} into part of @var{seq1}.
3431 The sequence @var{seq1} is not stretched or resized; the amount
3432 of data copied is simply the shorter of the source and destination
3433 (sub)sequences. The function returns @var{seq1}.
3435 If @var{seq1} and @var{seq2} are @code{eq}, then the replacement
3436 will work correctly even if the regions indicated by the start
3437 and end arguments overlap. However, if @var{seq1} and @var{seq2}
3438 are lists that share storage but are not @code{eq}, and the
3439 start and end arguments specify overlapping regions, the effect
3443 @defun cl-remove item seq @t{&key :test :test-not :key :count :start :end :from-end}
3444 This returns a copy of @var{seq} with all elements matching
3445 @var{item} removed. The result may share storage with or be
3446 @code{eq} to @var{seq} in some circumstances, but the original
3447 @var{seq} will not be modified. The @code{:test}, @code{:test-not},
3448 and @code{:key} arguments define the matching test that is used;
3449 by default, elements @code{eql} to @var{item} are removed. The
3450 @code{:count} argument specifies the maximum number of matching
3451 elements that can be removed (only the leftmost @var{count} matches
3452 are removed). The @code{:start} and @code{:end} arguments specify
3453 a region in @var{seq} in which elements will be removed; elements
3454 outside that region are not matched or removed. The @code{:from-end}
3455 argument, if true, says that elements should be deleted from the
3456 end of the sequence rather than the beginning (this matters only
3457 if @var{count} was also specified).
3460 @defun cl-delete item seq @t{&key :test :test-not :key :count :start :end :from-end}
3461 This deletes all elements of @var{seq} that match @var{item}.
3462 It is a destructive operation. Since Emacs Lisp does not support
3463 stretchable strings or vectors, this is the same as @code{cl-remove}
3464 for those sequence types. On lists, @code{cl-remove} will copy the
3465 list if necessary to preserve the original list, whereas
3466 @code{cl-delete} will splice out parts of the argument list.
3467 Compare @code{append} and @code{nconc}, which are analogous
3468 non-destructive and destructive list operations in Emacs Lisp.
3471 @findex cl-remove-if
3472 @findex cl-remove-if-not
3473 @findex cl-delete-if
3474 @findex cl-delete-if-not
3475 The predicate-oriented functions @code{cl-remove-if}, @code{cl-remove-if-not},
3476 @code{cl-delete-if}, and @code{cl-delete-if-not} are defined similarly.
3478 @defun cl-remove-duplicates seq @t{&key :test :test-not :key :start :end :from-end}
3479 This function returns a copy of @var{seq} with duplicate elements
3480 removed. Specifically, if two elements from the sequence match
3481 according to the @code{:test}, @code{:test-not}, and @code{:key}
3482 arguments, only the rightmost one is retained. If @code{:from-end}
3483 is true, the leftmost one is retained instead. If @code{:start} or
3484 @code{:end} is specified, only elements within that subsequence are
3485 examined or removed.
3488 @defun cl-delete-duplicates seq @t{&key :test :test-not :key :start :end :from-end}
3489 This function deletes duplicate elements from @var{seq}. It is
3490 a destructive version of @code{cl-remove-duplicates}.
3493 @defun cl-substitute new old seq @t{&key :test :test-not :key :count :start :end :from-end}
3494 This function returns a copy of @var{seq}, with all elements
3495 matching @var{old} replaced with @var{new}. The @code{:count},
3496 @code{:start}, @code{:end}, and @code{:from-end} arguments may be
3497 used to limit the number of substitutions made.
3500 @defun cl-nsubstitute new old seq @t{&key :test :test-not :key :count :start :end :from-end}
3501 This is a destructive version of @code{cl-substitute}; it performs
3502 the substitution using @code{setcar} or @code{aset} rather than
3503 by returning a changed copy of the sequence.
3506 @findex cl-substitute-if
3507 @findex cl-substitute-if-not
3508 @findex cl-nsubstitute-if
3509 @findex cl-nsubstitute-if-not
3510 The functions @code{cl-substitute-if}, @code{cl-substitute-if-not},
3511 @code{cl-nsubstitute-if}, and @code{cl-nsubstitute-if-not} are defined
3512 similarly. For these, a @var{predicate} is given in place of the
3515 @node Searching Sequences
3516 @section Searching Sequences
3519 These functions search for elements or subsequences in a sequence.
3520 (See also @code{cl-member} and @code{cl-assoc}; @pxref{Lists}.)
3522 @defun cl-find item seq @t{&key :test :test-not :key :start :end :from-end}
3523 This function searches @var{seq} for an element matching @var{item}.
3524 If it finds a match, it returns the matching element. Otherwise,
3525 it returns @code{nil}. It returns the leftmost match, unless
3526 @code{:from-end} is true, in which case it returns the rightmost
3527 match. The @code{:start} and @code{:end} arguments may be used to
3528 limit the range of elements that are searched.
3531 @defun cl-position item seq @t{&key :test :test-not :key :start :end :from-end}
3532 This function is like @code{cl-find}, except that it returns the
3533 integer position in the sequence of the matching item rather than
3534 the item itself. The position is relative to the start of the
3535 sequence as a whole, even if @code{:start} is non-zero. The function
3536 returns @code{nil} if no matching element was found.
3539 @defun cl-count item seq @t{&key :test :test-not :key :start :end}
3540 This function returns the number of elements of @var{seq} which
3541 match @var{item}. The result is always a nonnegative integer.
3545 @findex cl-find-if-not
3546 @findex cl-position-if
3547 @findex cl-position-if-not
3549 @findex cl-count-if-not
3550 The @code{cl-find-if}, @code{cl-find-if-not}, @code{cl-position-if},
3551 @code{cl-position-if-not}, @code{cl-count-if}, and @code{cl-count-if-not}
3552 functions are defined similarly.
3554 @defun cl-mismatch seq1 seq2 @t{&key :test :test-not :key :start1 :end1 :start2 :end2 :from-end}
3555 This function compares the specified parts of @var{seq1} and
3556 @var{seq2}. If they are the same length and the corresponding
3557 elements match (according to @code{:test}, @code{:test-not},
3558 and @code{:key}), the function returns @code{nil}. If there is
3559 a mismatch, the function returns the index (relative to @var{seq1})
3560 of the first mismatching element. This will be the leftmost pair of
3561 elements that do not match, or the position at which the shorter of
3562 the two otherwise-matching sequences runs out.
3564 If @code{:from-end} is true, then the elements are compared from right
3565 to left starting at @code{(1- @var{end1})} and @code{(1- @var{end2})}.
3566 If the sequences differ, then one plus the index of the rightmost
3567 difference (relative to @var{seq1}) is returned.
3569 An interesting example is @code{(cl-mismatch str1 str2 :key 'upcase)},
3570 which compares two strings case-insensitively.
3573 @defun cl-search seq1 seq2 @t{&key :test :test-not :key :from-end :start1 :end1 :start2 :end2}
3574 This function searches @var{seq2} for a subsequence that matches
3575 @var{seq1} (or part of it specified by @code{:start1} and
3576 @code{:end1}). Only matches that fall entirely within the region
3577 defined by @code{:start2} and @code{:end2} will be considered.
3578 The return value is the index of the leftmost element of the
3579 leftmost match, relative to the start of @var{seq2}, or @code{nil}
3580 if no matches were found. If @code{:from-end} is true, the
3581 function finds the @emph{rightmost} matching subsequence.
3584 @node Sorting Sequences
3585 @section Sorting Sequences
3587 @defun cl-sort seq predicate @t{&key :key}
3588 This function sorts @var{seq} into increasing order as determined
3589 by using @var{predicate} to compare pairs of elements. @var{predicate}
3590 should return true (non-@code{nil}) if and only if its first argument
3591 is less than (not equal to) its second argument. For example,
3592 @code{<} and @code{string-lessp} are suitable predicate functions
3593 for sorting numbers and strings, respectively; @code{>} would sort
3594 numbers into decreasing rather than increasing order.
3596 This function differs from Emacs's built-in @code{sort} in that it
3597 can operate on any type of sequence, not just lists. Also, it
3598 accepts a @code{:key} argument, which is used to preprocess data
3599 fed to the @var{predicate} function. For example,
3602 (setq data (cl-sort data 'string-lessp :key 'downcase))
3606 sorts @var{data}, a sequence of strings, into increasing alphabetical
3607 order without regard to case. A @code{:key} function of @code{car}
3608 would be useful for sorting association lists. It should only be a
3609 simple accessor though, since it's used heavily in the current
3612 The @code{cl-sort} function is destructive; it sorts lists by actually
3613 rearranging the @sc{cdr} pointers in suitable fashion.
3616 @defun cl-stable-sort seq predicate @t{&key :key}
3617 This function sorts @var{seq} @dfn{stably}, meaning two elements
3618 which are equal in terms of @var{predicate} are guaranteed not to
3619 be rearranged out of their original order by the sort.
3621 In practice, @code{cl-sort} and @code{cl-stable-sort} are equivalent
3622 in Emacs Lisp because the underlying @code{sort} function is
3623 stable by default. However, this package reserves the right to
3624 use non-stable methods for @code{cl-sort} in the future.
3627 @defun cl-merge type seq1 seq2 predicate @t{&key :key}
3628 This function merges two sequences @var{seq1} and @var{seq2} by
3629 interleaving their elements. The result sequence, of type @var{type}
3630 (in the sense of @code{cl-concatenate}), has length equal to the sum
3631 of the lengths of the two input sequences. The sequences may be
3632 modified destructively. Order of elements within @var{seq1} and
3633 @var{seq2} is preserved in the interleaving; elements of the two
3634 sequences are compared by @var{predicate} (in the sense of
3635 @code{sort}) and the lesser element goes first in the result.
3636 When elements are equal, those from @var{seq1} precede those from
3637 @var{seq2} in the result. Thus, if @var{seq1} and @var{seq2} are
3638 both sorted according to @var{predicate}, then the result will be
3639 a merged sequence which is (stably) sorted according to
3647 The functions described here operate on lists.
3650 * List Functions:: @code{cl-caddr}, @code{cl-first}, @code{cl-list*}, etc.
3651 * Substitution of Expressions:: @code{cl-subst}, @code{cl-sublis}, etc.
3652 * Lists as Sets:: @code{cl-member}, @code{cl-adjoin}, @code{cl-union}, etc.
3653 * Association Lists:: @code{cl-assoc}, @code{cl-acons}, @code{cl-pairlis}, etc.
3656 @node List Functions
3657 @section List Functions
3660 This section describes a number of simple operations on lists,
3661 i.e., chains of cons cells.
3664 This function is equivalent to @code{(car (cdr (cdr @var{x})))}.
3665 Likewise, this package defines all 24 @code{c@var{xxx}r} functions
3666 where @var{xxx} is up to four @samp{a}s and/or @samp{d}s.
3667 All of these functions are @code{setf}-able, and calls to them
3668 are expanded inline by the byte-compiler for maximum efficiency.
3672 This function is a synonym for @code{(car @var{x})}. Likewise,
3673 the functions @code{cl-second}, @code{cl-third}, @dots{}, through
3674 @code{cl-tenth} return the given element of the list @var{x}.
3678 This function is a synonym for @code{(cdr @var{x})}.
3682 Common Lisp defines this function to act like @code{null}, but
3683 signaling an error if @code{x} is neither a @code{nil} nor a
3684 cons cell. This package simply defines @code{cl-endp} as a synonym
3688 @defun cl-list-length x
3689 This function returns the length of list @var{x}, exactly like
3690 @code{(length @var{x})}, except that if @var{x} is a circular
3691 list (where the @sc{cdr}-chain forms a loop rather than terminating
3692 with @code{nil}), this function returns @code{nil}. (The regular
3693 @code{length} function would get stuck if given a circular list.
3694 See also the @code{safe-length} function.)
3697 @defun cl-list* arg &rest others
3698 This function constructs a list of its arguments. The final
3699 argument becomes the @sc{cdr} of the last cell constructed.
3700 Thus, @code{(cl-list* @var{a} @var{b} @var{c})} is equivalent to
3701 @code{(cons @var{a} (cons @var{b} @var{c}))}, and
3702 @code{(cl-list* @var{a} @var{b} nil)} is equivalent to
3703 @code{(list @var{a} @var{b})}.
3706 @defun cl-ldiff list sublist
3707 If @var{sublist} is a sublist of @var{list}, i.e., is @code{eq} to
3708 one of the cons cells of @var{list}, then this function returns
3709 a copy of the part of @var{list} up to but not including
3710 @var{sublist}. For example, @code{(cl-ldiff x (cddr x))} returns
3711 the first two elements of the list @code{x}. The result is a
3712 copy; the original @var{list} is not modified. If @var{sublist}
3713 is not a sublist of @var{list}, a copy of the entire @var{list}
3717 @defun cl-copy-list list
3718 This function returns a copy of the list @var{list}. It copies
3719 dotted lists like @code{(1 2 . 3)} correctly.
3722 @defun cl-tree-equal x y @t{&key :test :test-not :key}
3723 This function compares two trees of cons cells. If @var{x} and
3724 @var{y} are both cons cells, their @sc{car}s and @sc{cdr}s are
3725 compared recursively. If neither @var{x} nor @var{y} is a cons
3726 cell, they are compared by @code{eql}, or according to the
3727 specified test. The @code{:key} function, if specified, is
3728 applied to the elements of both trees. @xref{Sequences}.
3731 @node Substitution of Expressions
3732 @section Substitution of Expressions
3735 These functions substitute elements throughout a tree of cons
3736 cells. (@xref{Sequence Functions}, for the @code{cl-substitute}
3737 function, which works on just the top-level elements of a list.)
3739 @defun cl-subst new old tree @t{&key :test :test-not :key}
3740 This function substitutes occurrences of @var{old} with @var{new}
3741 in @var{tree}, a tree of cons cells. It returns a substituted
3742 tree, which will be a copy except that it may share storage with
3743 the argument @var{tree} in parts where no substitutions occurred.
3744 The original @var{tree} is not modified. This function recurses
3745 on, and compares against @var{old}, both @sc{car}s and @sc{cdr}s
3746 of the component cons cells. If @var{old} is itself a cons cell,
3747 then matching cells in the tree are substituted as usual without
3748 recursively substituting in that cell. Comparisons with @var{old}
3749 are done according to the specified test (@code{eql} by default).
3750 The @code{:key} function is applied to the elements of the tree
3751 but not to @var{old}.
3754 @defun cl-nsubst new old tree @t{&key :test :test-not :key}
3755 This function is like @code{cl-subst}, except that it works by
3756 destructive modification (by @code{setcar} or @code{setcdr})
3757 rather than copying.
3761 @findex cl-subst-if-not
3762 @findex cl-nsubst-if
3763 @findex cl-nsubst-if-not
3764 The @code{cl-subst-if}, @code{cl-subst-if-not}, @code{cl-nsubst-if}, and
3765 @code{cl-nsubst-if-not} functions are defined similarly.
3767 @defun cl-sublis alist tree @t{&key :test :test-not :key}
3768 This function is like @code{cl-subst}, except that it takes an
3769 association list @var{alist} of @var{old}-@var{new} pairs.
3770 Each element of the tree (after applying the @code{:key}
3771 function, if any), is compared with the @sc{car}s of
3772 @var{alist}; if it matches, it is replaced by the corresponding
3776 @defun cl-nsublis alist tree @t{&key :test :test-not :key}
3777 This is a destructive version of @code{cl-sublis}.
3781 @section Lists as Sets
3784 These functions perform operations on lists that represent sets
3787 @defun cl-member item list @t{&key :test :test-not :key}
3788 This function searches @var{list} for an element matching @var{item}.
3789 If a match is found, it returns the cons cell whose @sc{car} was
3790 the matching element. Otherwise, it returns @code{nil}. Elements
3791 are compared by @code{eql} by default; you can use the @code{:test},
3792 @code{:test-not}, and @code{:key} arguments to modify this behavior.
3795 The standard Emacs lisp function @code{member} uses @code{equal} for
3796 comparisons; it is equivalent to @code{(cl-member @var{item} @var{list}
3797 :test 'equal)}. With no keyword arguments, @code{cl-member} is
3798 equivalent to @code{memq}.
3801 @findex cl-member-if
3802 @findex cl-member-if-not
3803 The @code{cl-member-if} and @code{cl-member-if-not} functions
3804 analogously search for elements that satisfy a given predicate.
3806 @defun cl-tailp sublist list
3807 This function returns @code{t} if @var{sublist} is a sublist of
3808 @var{list}, i.e., if @var{sublist} is @code{eql} to @var{list} or to
3809 any of its @sc{cdr}s.
3812 @defun cl-adjoin item list @t{&key :test :test-not :key}
3813 This function conses @var{item} onto the front of @var{list},
3814 like @code{(cons @var{item} @var{list})}, but only if @var{item}
3815 is not already present on the list (as determined by @code{cl-member}).
3816 If a @code{:key} argument is specified, it is applied to
3817 @var{item} as well as to the elements of @var{list} during
3818 the search, on the reasoning that @var{item} is ``about'' to
3819 become part of the list.
3822 @defun cl-union list1 list2 @t{&key :test :test-not :key}
3823 This function combines two lists that represent sets of items,
3824 returning a list that represents the union of those two sets.
3825 The resulting list contains all items that appear in @var{list1}
3826 or @var{list2}, and no others. If an item appears in both
3827 @var{list1} and @var{list2} it is copied only once. If
3828 an item is duplicated in @var{list1} or @var{list2}, it is
3829 undefined whether or not that duplication will survive in the
3830 result list. The order of elements in the result list is also
3834 @defun cl-nunion list1 list2 @t{&key :test :test-not :key}
3835 This is a destructive version of @code{cl-union}; rather than copying,
3836 it tries to reuse the storage of the argument lists if possible.
3839 @defun cl-intersection list1 list2 @t{&key :test :test-not :key}
3840 This function computes the intersection of the sets represented
3841 by @var{list1} and @var{list2}. It returns the list of items
3842 that appear in both @var{list1} and @var{list2}.
3845 @defun cl-nintersection list1 list2 @t{&key :test :test-not :key}
3846 This is a destructive version of @code{cl-intersection}. It
3847 tries to reuse storage of @var{list1} rather than copying.
3848 It does @emph{not} reuse the storage of @var{list2}.
3851 @defun cl-set-difference list1 list2 @t{&key :test :test-not :key}
3852 This function computes the ``set difference'' of @var{list1}
3853 and @var{list2}, i.e., the set of elements that appear in
3854 @var{list1} but @emph{not} in @var{list2}.
3857 @defun cl-nset-difference list1 list2 @t{&key :test :test-not :key}
3858 This is a destructive @code{cl-set-difference}, which will try
3859 to reuse @var{list1} if possible.
3862 @defun cl-set-exclusive-or list1 list2 @t{&key :test :test-not :key}
3863 This function computes the ``set exclusive or'' of @var{list1}
3864 and @var{list2}, i.e., the set of elements that appear in
3865 exactly one of @var{list1} and @var{list2}.
3868 @defun cl-nset-exclusive-or list1 list2 @t{&key :test :test-not :key}
3869 This is a destructive @code{cl-set-exclusive-or}, which will try
3870 to reuse @var{list1} and @var{list2} if possible.
3873 @defun cl-subsetp list1 list2 @t{&key :test :test-not :key}
3874 This function checks whether @var{list1} represents a subset
3875 of @var{list2}, i.e., whether every element of @var{list1}
3876 also appears in @var{list2}.
3879 @node Association Lists
3880 @section Association Lists
3883 An @dfn{association list} is a list representing a mapping from
3884 one set of values to another; any list whose elements are cons
3885 cells is an association list.
3887 @defun cl-assoc item a-list @t{&key :test :test-not :key}
3888 This function searches the association list @var{a-list} for an
3889 element whose @sc{car} matches (in the sense of @code{:test},
3890 @code{:test-not}, and @code{:key}, or by comparison with @code{eql})
3891 a given @var{item}. It returns the matching element, if any,
3892 otherwise @code{nil}. It ignores elements of @var{a-list} that
3893 are not cons cells. (This corresponds to the behavior of
3894 @code{assq} and @code{assoc} in Emacs Lisp; Common Lisp's
3895 @code{assoc} ignores @code{nil}s but considers any other non-cons
3896 elements of @var{a-list} to be an error.)
3899 @defun cl-rassoc item a-list @t{&key :test :test-not :key}
3900 This function searches for an element whose @sc{cdr} matches
3901 @var{item}. If @var{a-list} represents a mapping, this applies
3902 the inverse of the mapping to @var{item}.
3906 @findex cl-assoc-if-not
3907 @findex cl-rassoc-if
3908 @findex cl-rassoc-if-not
3909 The @code{cl-assoc-if}, @code{cl-assoc-if-not}, @code{cl-rassoc-if},
3910 and @code{cl-rassoc-if-not} functions are defined similarly.
3912 Two simple functions for constructing association lists are:
3914 @defun cl-acons key value alist
3915 This is equivalent to @code{(cons (cons @var{key} @var{value}) @var{alist})}.
3918 @defun cl-pairlis keys values &optional alist
3919 This is equivalent to @code{(nconc (cl-mapcar 'cons @var{keys} @var{values})
3927 The Common Lisp @dfn{structure} mechanism provides a general way
3928 to define data types similar to C's @code{struct} types. A
3929 structure is a Lisp object containing some number of @dfn{slots},
3930 each of which can hold any Lisp data object. Functions are
3931 provided for accessing and setting the slots, creating or copying
3932 structure objects, and recognizing objects of a particular structure
3935 In true Common Lisp, each structure type is a new type distinct
3936 from all existing Lisp types. Since the underlying Emacs Lisp
3937 system provides no way to create new distinct types, this package
3938 implements structures as vectors (or lists upon request) with a
3939 special ``tag'' symbol to identify them.
3941 @defmac cl-defstruct name slots@dots{}
3942 The @code{cl-defstruct} form defines a new structure type called
3943 @var{name}, with the specified @var{slots}. (The @var{slots}
3944 may begin with a string which documents the structure type.)
3945 In the simplest case, @var{name} and each of the @var{slots}
3946 are symbols. For example,
3949 (cl-defstruct person name age sex)
3953 defines a struct type called @code{person} that contains three
3954 slots. Given a @code{person} object @var{p}, you can access those
3955 slots by calling @code{(person-name @var{p})}, @code{(person-age @var{p})},
3956 and @code{(person-sex @var{p})}. You can also change these slots by
3957 using @code{setf} on any of these place forms, for example:
3960 (cl-incf (person-age birthday-boy))
3963 You can create a new @code{person} by calling @code{make-person},
3964 which takes keyword arguments @code{:name}, @code{:age}, and
3965 @code{:sex} to specify the initial values of these slots in the
3966 new object. (Omitting any of these arguments leaves the corresponding
3967 slot ``undefined'', according to the Common Lisp standard; in Emacs
3968 Lisp, such uninitialized slots are filled with @code{nil}.)
3970 Given a @code{person}, @code{(copy-person @var{p})} makes a new
3971 object of the same type whose slots are @code{eq} to those of @var{p}.
3973 Given any Lisp object @var{x}, @code{(person-p @var{x})} returns
3974 true if @var{x} looks like a @code{person}, and false otherwise. (Again,
3975 in Common Lisp this predicate would be exact; in Emacs Lisp the
3976 best it can do is verify that @var{x} is a vector of the correct
3977 length that starts with the correct tag symbol.)
3979 Accessors like @code{person-name} normally check their arguments
3980 (effectively using @code{person-p}) and signal an error if the
3981 argument is the wrong type. This check is affected by
3982 @code{(optimize (safety @dots{}))} declarations. Safety level 1,
3983 the default, uses a somewhat optimized check that will detect all
3984 incorrect arguments, but may use an uninformative error message
3985 (e.g., ``expected a vector'' instead of ``expected a @code{person}'').
3986 Safety level 0 omits all checks except as provided by the underlying
3987 @code{aref} call; safety levels 2 and 3 do rigorous checking that will
3988 always print a descriptive error message for incorrect inputs.
3989 @xref{Declarations}.
3992 (setq dave (make-person :name "Dave" :sex 'male))
3993 @result{} [cl-struct-person "Dave" nil male]
3994 (setq other (copy-person dave))
3995 @result{} [cl-struct-person "Dave" nil male]
3998 (eq (person-name dave) (person-name other))
4002 (person-p [1 2 3 4])
4006 (person-p '[cl-struct-person counterfeit person object])
4010 In general, @var{name} is either a name symbol or a list of a name
4011 symbol followed by any number of @dfn{struct options}; each @var{slot}
4012 is either a slot symbol or a list of the form @samp{(@var{slot-name}
4013 @var{default-value} @var{slot-options}@dots{})}. The @var{default-value}
4014 is a Lisp form that is evaluated any time an instance of the
4015 structure type is created without specifying that slot's value.
4017 Common Lisp defines several slot options, but the only one
4018 implemented in this package is @code{:read-only}. A non-@code{nil}
4019 value for this option means the slot should not be @code{setf}-able;
4020 the slot's value is determined when the object is created and does
4021 not change afterward.
4024 (cl-defstruct person
4025 (name nil :read-only t)
4030 Any slot options other than @code{:read-only} are ignored.
4032 For obscure historical reasons, structure options take a different
4033 form than slot options. A structure option is either a keyword
4034 symbol, or a list beginning with a keyword symbol possibly followed
4035 by arguments. (By contrast, slot options are key-value pairs not
4039 (cl-defstruct (person (:constructor create-person)
4045 The following structure options are recognized.
4049 The argument is a symbol whose print name is used as the prefix for
4050 the names of slot accessor functions. The default is the name of
4051 the struct type followed by a hyphen. The option @code{(:conc-name p-)}
4052 would change this prefix to @code{p-}. Specifying @code{nil} as an
4053 argument means no prefix, so that the slot names themselves are used
4054 to name the accessor functions.
4057 In the simple case, this option takes one argument which is an
4058 alternate name to use for the constructor function. The default
4059 is @code{make-@var{name}}, e.g., @code{make-person}. The above
4060 example changes this to @code{create-person}. Specifying @code{nil}
4061 as an argument means that no standard constructor should be
4064 In the full form of this option, the constructor name is followed
4065 by an arbitrary argument list. @xref{Program Structure}, for a
4066 description of the format of Common Lisp argument lists. All
4067 options, such as @code{&rest} and @code{&key}, are supported.
4068 The argument names should match the slot names; each slot is
4069 initialized from the corresponding argument. Slots whose names
4070 do not appear in the argument list are initialized based on the
4071 @var{default-value} in their slot descriptor. Also, @code{&optional}
4072 and @code{&key} arguments that don't specify defaults take their
4073 defaults from the slot descriptor. It is valid to include arguments
4074 that don't correspond to slot names; these are useful if they are
4075 referred to in the defaults for optional, keyword, or @code{&aux}
4076 arguments that @emph{do} correspond to slots.
4078 You can specify any number of full-format @code{:constructor}
4079 options on a structure. The default constructor is still generated
4080 as well unless you disable it with a simple-format @code{:constructor}
4086 (:constructor nil) ; no default constructor
4087 (:constructor new-person
4088 (name sex &optional (age 0)))
4089 (:constructor new-hound (&key (name "Rover")
4091 &aux (age (* 7 dog-years))
4096 The first constructor here takes its arguments positionally rather
4097 than by keyword. (In official Common Lisp terminology, constructors
4098 that work By Order of Arguments instead of by keyword are called
4099 ``BOA constructors''. No, I'm not making this up.) For example,
4100 @code{(new-person "Jane" 'female)} generates a person whose slots
4101 are @code{"Jane"}, 0, and @code{female}, respectively.
4103 The second constructor takes two keyword arguments, @code{:name},
4104 which initializes the @code{name} slot and defaults to @code{"Rover"},
4105 and @code{:dog-years}, which does not itself correspond to a slot
4106 but which is used to initialize the @code{age} slot. The @code{sex}
4107 slot is forced to the symbol @code{canine} with no syntax for
4111 The argument is an alternate name for the copier function for
4112 this type. The default is @code{copy-@var{name}}. @code{nil}
4113 means not to generate a copier function. (In this implementation,
4114 all copier functions are simply synonyms for @code{copy-sequence}.)
4117 The argument is an alternate name for the predicate that recognizes
4118 objects of this type. The default is @code{@var{name}-p}. @code{nil}
4119 means not to generate a predicate function. (If the @code{:type}
4120 option is used without the @code{:named} option, no predicate is
4123 In true Common Lisp, @code{typep} is always able to recognize a
4124 structure object even if @code{:predicate} was used. In this
4125 package, @code{cl-typep} simply looks for a function called
4126 @code{@var{typename}-p}, so it will work for structure types
4127 only if they used the default predicate name.
4130 This option implements a very limited form of C++-style inheritance.
4131 The argument is the name of another structure type previously
4132 created with @code{cl-defstruct}. The effect is to cause the new
4133 structure type to inherit all of the included structure's slots
4134 (plus, of course, any new slots described by this struct's slot
4135 descriptors). The new structure is considered a ``specialization''
4136 of the included one. In fact, the predicate and slot accessors
4137 for the included type will also accept objects of the new type.
4139 If there are extra arguments to the @code{:include} option after
4140 the included-structure name, these options are treated as replacement
4141 slot descriptors for slots in the included structure, possibly with
4142 modified default values. Borrowing an example from Steele:
4145 (cl-defstruct person name (age 0) sex)
4147 (cl-defstruct (astronaut (:include person (age 45)))
4149 (favorite-beverage 'tang))
4152 (setq joe (make-person :name "Joe"))
4153 @result{} [cl-struct-person "Joe" 0 nil]
4154 (setq buzz (make-astronaut :name "Buzz"))
4155 @result{} [cl-struct-astronaut "Buzz" 45 nil nil tang]
4157 (list (person-p joe) (person-p buzz))
4159 (list (astronaut-p joe) (astronaut-p buzz))
4164 (astronaut-name joe)
4165 @result{} error: "astronaut-name accessing a non-astronaut"
4168 Thus, if @code{astronaut} is a specialization of @code{person},
4169 then every @code{astronaut} is also a @code{person} (but not the
4170 other way around). Every @code{astronaut} includes all the slots
4171 of a @code{person}, plus extra slots that are specific to
4172 astronauts. Operations that work on people (like @code{person-name})
4173 work on astronauts just like other people.
4175 @item :print-function
4176 In full Common Lisp, this option allows you to specify a function
4177 that is called to print an instance of the structure type. The
4178 Emacs Lisp system offers no hooks into the Lisp printer which would
4179 allow for such a feature, so this package simply ignores
4180 @code{:print-function}.
4183 The argument should be one of the symbols @code{vector} or @code{list}.
4184 This tells which underlying Lisp data type should be used to implement
4185 the new structure type. Vectors are used by default, but
4186 @code{(:type list)} will cause structure objects to be stored as
4189 The vector representation for structure objects has the advantage
4190 that all structure slots can be accessed quickly, although creating
4191 vectors is a bit slower in Emacs Lisp. Lists are easier to create,
4192 but take a relatively long time accessing the later slots.
4195 This option, which takes no arguments, causes a characteristic ``tag''
4196 symbol to be stored at the front of the structure object. Using
4197 @code{:type} without also using @code{:named} will result in a
4198 structure type stored as plain vectors or lists with no identifying
4201 The default, if you don't specify @code{:type} explicitly, is to
4202 use named vectors. Therefore, @code{:named} is only useful in
4203 conjunction with @code{:type}.
4206 (cl-defstruct (person1) name age sex)
4207 (cl-defstruct (person2 (:type list) :named) name age sex)
4208 (cl-defstruct (person3 (:type list)) name age sex)
4210 (setq p1 (make-person1))
4211 @result{} [cl-struct-person1 nil nil nil]
4212 (setq p2 (make-person2))
4213 @result{} (person2 nil nil nil)
4214 (setq p3 (make-person3))
4215 @result{} (nil nil nil)
4222 @result{} error: function person3-p undefined
4225 Since unnamed structures don't have tags, @code{cl-defstruct} is not
4226 able to make a useful predicate for recognizing them. Also,
4227 accessors like @code{person3-name} will be generated but they
4228 will not be able to do any type checking. The @code{person3-name}
4229 function, for example, will simply be a synonym for @code{car} in
4230 this case. By contrast, @code{person2-name} is able to verify
4231 that its argument is indeed a @code{person2} object before
4234 @item :initial-offset
4235 The argument must be a nonnegative integer. It specifies a
4236 number of slots to be left ``empty'' at the front of the
4237 structure. If the structure is named, the tag appears at the
4238 specified position in the list or vector; otherwise, the first
4239 slot appears at that position. Earlier positions are filled
4240 with @code{nil} by the constructors and ignored otherwise. If
4241 the type @code{:include}s another type, then @code{:initial-offset}
4242 specifies a number of slots to be skipped between the last slot
4243 of the included type and the first new slot.
4247 Except as noted, the @code{cl-defstruct} facility of this package is
4248 entirely compatible with that of Common Lisp.
4250 The @code{cl-defstruct} package also provides a few structure
4251 introspection functions.
4253 @defun cl-struct-sequence-type struct-type
4254 This function returns the underlying data structure for
4255 @code{struct-type}, which is a symbol. It returns @code{vector} or
4256 @code{list}, or @code{nil} if @code{struct-type} is not actually a
4260 @defun cl-struct-slot-info struct-type
4261 This function returns a list of slot descriptors for structure
4262 @code{struct-type}. Each entry in the list is @code{(name . opts)},
4263 where @code{name} is the name of the slot and @code{opts} is the list
4264 of slot options given to @code{defstruct}. Dummy entries represent
4265 the slots used for the struct name and that are skipped to implement
4266 @code{:initial-offset}.
4269 @defun cl-struct-slot-offset struct-type slot-name
4270 Return the offset of slot @code{slot-name} in @code{struct-type}. The
4271 returned zero-based slot index is relative to the start of the
4272 structure data type and is adjusted for any structure name and
4273 :initial-offset slots. Signal error if struct @code{struct-type} does
4274 not contain @code{slot-name}.
4277 @defun cl-struct-slot-value struct-type slot-name inst
4278 Return the value of slot @code{slot-name} in @code{inst} of
4279 @code{struct-type}. @code{struct} and @code{slot-name} are symbols.
4280 @code{inst} is a structure instance. This routine is also a
4281 @code{setf} place. Can signal the same errors as @code{cl-struct-slot-offset}.
4285 @chapter Assertions and Errors
4288 This section describes two macros that test @dfn{assertions}, i.e.,
4289 conditions which must be true if the program is operating correctly.
4290 Assertions never add to the behavior of a Lisp program; they simply
4291 make ``sanity checks'' to make sure everything is as it should be.
4293 If the optimization property @code{speed} has been set to 3, and
4294 @code{safety} is less than 3, then the byte-compiler will optimize
4295 away the following assertions. Because assertions might be optimized
4296 away, it is a bad idea for them to include side-effects.
4298 @defmac cl-assert test-form [show-args string args@dots{}]
4299 This form verifies that @var{test-form} is true (i.e., evaluates to
4300 a non-@code{nil} value). If so, it returns @code{nil}. If the test
4301 is not satisfied, @code{cl-assert} signals an error.
4303 A default error message will be supplied which includes @var{test-form}.
4304 You can specify a different error message by including a @var{string}
4305 argument plus optional extra arguments. Those arguments are simply
4306 passed to @code{error} to signal the error.
4308 If the optional second argument @var{show-args} is @code{t} instead
4309 of @code{nil}, then the error message (with or without @var{string})
4310 will also include all non-constant arguments of the top-level
4311 @var{form}. For example:
4314 (cl-assert (> x 10) t "x is too small: %d")
4317 This usage of @var{show-args} is an extension to Common Lisp. In
4318 true Common Lisp, the second argument gives a list of @var{places}
4319 which can be @code{setf}'d by the user before continuing from the
4320 error. Since Emacs Lisp does not support continuable errors, it
4321 makes no sense to specify @var{places}.
4324 @defmac cl-check-type form type [string]
4325 This form verifies that @var{form} evaluates to a value of type
4326 @var{type}. If so, it returns @code{nil}. If not, @code{cl-check-type}
4327 signals a @code{wrong-type-argument} error. The default error message
4328 lists the erroneous value along with @var{type} and @var{form}
4329 themselves. If @var{string} is specified, it is included in the
4330 error message in place of @var{type}. For example:
4333 (cl-check-type x (integer 1 *) "a positive integer")
4336 @xref{Type Predicates}, for a description of the type specifiers
4337 that may be used for @var{type}.
4339 Note that in Common Lisp, the first argument to @code{check-type}
4340 must be a @var{place} suitable for use by @code{setf}, because
4341 @code{check-type} signals a continuable error that allows the
4342 user to modify @var{place}.
4345 @node Efficiency Concerns
4346 @appendix Efficiency Concerns
4351 Many of the advanced features of this package, such as @code{cl-defun},
4352 @code{cl-loop}, etc., are implemented as Lisp macros. In
4353 byte-compiled code, these complex notations will be expanded into
4354 equivalent Lisp code which is simple and efficient. For example,
4362 is expanded at compile-time to the Lisp form
4369 which is the most efficient ways of doing this operation
4370 in Lisp. Thus, there is no performance penalty for using the more
4371 readable @code{cl-incf} form in your compiled code.
4373 @emph{Interpreted} code, on the other hand, must expand these macros
4374 every time they are executed. For this reason it is strongly
4375 recommended that code making heavy use of macros be compiled.
4376 A loop using @code{cl-incf} a hundred times will execute considerably
4377 faster if compiled, and will also garbage-collect less because the
4378 macro expansion will not have to be generated, used, and thrown away a
4381 You can find out how a macro expands by using the
4382 @code{cl-prettyexpand} function.
4384 @defun cl-prettyexpand form &optional full
4385 This function takes a single Lisp form as an argument and inserts
4386 a nicely formatted copy of it in the current buffer (which must be
4387 in Lisp mode so that indentation works properly). It also expands
4388 all Lisp macros that appear in the form. The easiest way to use
4389 this function is to go to the @file{*scratch*} buffer and type, say,
4392 (cl-prettyexpand '(cl-loop for x below 10 collect x))
4396 and type @kbd{C-x C-e} immediately after the closing parenthesis;
4397 an expansion similar to:
4404 (setq G1004 (cons x G1004))
4410 will be inserted into the buffer. (The @code{cl-block} macro is
4411 expanded differently in the interpreter and compiler, so
4412 @code{cl-prettyexpand} just leaves it alone. The temporary
4413 variable @code{G1004} was created by @code{cl-gensym}.)
4415 If the optional argument @var{full} is true, then @emph{all}
4416 macros are expanded, including @code{cl-block}, @code{cl-eval-when},
4417 and compiler macros. Expansion is done as if @var{form} were
4418 a top-level form in a file being compiled.
4420 @c FIXME none of these examples are still applicable.
4425 (cl-prettyexpand '(cl-pushnew 'x list))
4426 @print{} (setq list (cl-adjoin 'x list))
4427 (cl-prettyexpand '(cl-pushnew 'x list) t)
4428 @print{} (setq list (if (memq 'x list) list (cons 'x list)))
4429 (cl-prettyexpand '(caddr (cl-member 'a list)) t)
4430 @print{} (car (cdr (cdr (memq 'a list))))
4434 Note that @code{cl-adjoin}, @code{cl-caddr}, and @code{cl-member} all
4435 have built-in compiler macros to optimize them in common cases.
4438 @appendixsec Error Checking
4441 Common Lisp compliance has in general not been sacrificed for the
4442 sake of efficiency. A few exceptions have been made for cases
4443 where substantial gains were possible at the expense of marginal
4446 The Common Lisp standard (as embodied in Steele's book) uses the
4447 phrase ``it is an error if'' to indicate a situation that is not
4448 supposed to arise in complying programs; implementations are strongly
4449 encouraged but not required to signal an error in these situations.
4450 This package sometimes omits such error checking in the interest of
4451 compactness and efficiency. For example, @code{cl-do} variable
4452 specifiers are supposed to be lists of one, two, or three forms;
4453 extra forms are ignored by this package rather than signaling a
4454 syntax error. The @code{cl-endp} function is simply a synonym for
4455 @code{null} in this package. Functions taking keyword arguments
4456 will accept an odd number of arguments, treating the trailing
4457 keyword as if it were followed by the value @code{nil}.
4459 Argument lists (as processed by @code{cl-defun} and friends)
4460 @emph{are} checked rigorously except for the minor point just
4461 mentioned; in particular, keyword arguments are checked for
4462 validity, and @code{&allow-other-keys} and @code{:allow-other-keys}
4463 are fully implemented. Keyword validity checking is slightly
4464 time consuming (though not too bad in byte-compiled code);
4465 you can use @code{&allow-other-keys} to omit this check. Functions
4466 defined in this package such as @code{cl-find} and @code{cl-member}
4467 do check their keyword arguments for validity.
4469 @appendixsec Compiler Optimizations
4472 Changing the value of @code{byte-optimize} from the default @code{t}
4473 is highly discouraged; many of the Common
4475 code that can be improved by optimization. In particular,
4476 @code{cl-block}s (whether explicit or implicit in constructs like
4477 @code{cl-defun} and @code{cl-loop}) carry a fair run-time penalty; the
4478 byte-compiler removes @code{cl-block}s that are not actually
4479 referenced by @code{cl-return} or @code{cl-return-from} inside the block.
4481 @node Common Lisp Compatibility
4482 @appendix Common Lisp Compatibility
4485 The following is a list of all known incompatibilities between this
4486 package and Common Lisp as documented in Steele (2nd edition).
4488 The word @code{cl-defun} is required instead of @code{defun} in order
4489 to use extended Common Lisp argument lists in a function. Likewise,
4490 @code{cl-defmacro} and @code{cl-function} are versions of those forms
4491 which understand full-featured argument lists. The @code{&whole}
4492 keyword does not work in @code{cl-defmacro} argument lists (except
4493 inside recursive argument lists).
4495 The @code{equal} predicate does not distinguish
4496 between IEEE floating-point plus and minus zero. The @code{cl-equalp}
4497 predicate has several differences with Common Lisp; @pxref{Predicates}.
4499 The @code{cl-do-all-symbols} form is the same as @code{cl-do-symbols}
4500 with no @var{obarray} argument. In Common Lisp, this form would
4501 iterate over all symbols in all packages. Since Emacs obarrays
4502 are not a first-class package mechanism, there is no way for
4503 @code{cl-do-all-symbols} to locate any but the default obarray.
4505 The @code{cl-loop} macro is complete except that @code{loop-finish}
4506 and type specifiers are unimplemented.
4508 The multiple-value return facility treats lists as multiple
4509 values, since Emacs Lisp cannot support multiple return values
4510 directly. The macros will be compatible with Common Lisp if
4511 @code{cl-values} or @code{cl-values-list} is always used to return to
4512 a @code{cl-multiple-value-bind} or other multiple-value receiver;
4513 if @code{cl-values} is used without @code{cl-multiple-value-@dots{}}
4514 or vice-versa the effect will be different from Common Lisp.
4516 Many Common Lisp declarations are ignored, and others match
4517 the Common Lisp standard in concept but not in detail. For
4518 example, local @code{special} declarations, which are purely
4519 advisory in Emacs Lisp, do not rigorously obey the scoping rules
4520 set down in Steele's book.
4522 The variable @code{cl--gensym-counter} starts out with a pseudo-random
4523 value rather than with zero. This is to cope with the fact that
4524 generated symbols become interned when they are written to and
4525 loaded back from a file.
4527 The @code{cl-defstruct} facility is compatible, except that structures
4528 are of type @code{:type vector :named} by default rather than some
4529 special, distinct type. Also, the @code{:type} slot option is ignored.
4531 The second argument of @code{cl-check-type} is treated differently.
4533 @node Porting Common Lisp
4534 @appendix Porting Common Lisp
4537 This package is meant to be used as an extension to Emacs Lisp,
4538 not as an Emacs implementation of true Common Lisp. Some of the
4539 remaining differences between Emacs Lisp and Common Lisp make it
4540 difficult to port large Common Lisp applications to Emacs. For
4541 one, some of the features in this package are not fully compliant
4542 with ANSI or Steele; @pxref{Common Lisp Compatibility}. But there
4543 are also quite a few features that this package does not provide
4544 at all. Here are some major omissions that you will want to watch out
4545 for when bringing Common Lisp code into Emacs.
4549 Case-insensitivity. Symbols in Common Lisp are case-insensitive
4550 by default. Some programs refer to a function or variable as
4551 @code{foo} in one place and @code{Foo} or @code{FOO} in another.
4552 Emacs Lisp will treat these as three distinct symbols.
4554 Some Common Lisp code is written entirely in upper case. While Emacs
4555 is happy to let the program's own functions and variables use
4556 this convention, calls to Lisp builtins like @code{if} and
4557 @code{defun} will have to be changed to lower case.
4560 Lexical scoping. In Common Lisp, function arguments and @code{let}
4561 bindings apply only to references physically within their bodies (or
4562 within macro expansions in their bodies). Traditionally, Emacs Lisp
4563 uses @dfn{dynamic scoping} wherein a binding to a variable is visible
4564 even inside functions called from the body.
4565 @xref{Dynamic Binding,,,elisp,GNU Emacs Lisp Reference Manual}.
4566 Lexical binding is available since Emacs 24.1, so be sure to set
4567 @code{lexical-binding} to @code{t} if you need to emulate this aspect
4568 of Common Lisp. @xref{Lexical Binding,,,elisp,GNU Emacs Lisp Reference Manual}.
4570 Here is an example of a Common Lisp code fragment that would fail in
4571 Emacs Lisp if @code{lexical-binding} were set to @code{nil}:
4574 (defun map-odd-elements (func list)
4576 for flag = t then (not flag)
4577 collect (if flag x (funcall func x))))
4579 (defun add-odd-elements (list x)
4580 (map-odd-elements (lambda (a) (+ a x)) list))
4584 With lexical binding, the two functions' usages of @code{x} are
4585 completely independent. With dynamic binding, the binding to @code{x}
4586 made by @code{add-odd-elements} will have been hidden by the binding
4587 in @code{map-odd-elements} by the time the @code{(+ a x)} function is
4590 Internally, this package uses lexical binding so that such problems do
4591 not occur. @xref{Obsolete Lexical Binding}, for a description of the obsolete
4592 @code{lexical-let} form that emulates a Common Lisp-style lexical
4593 binding when dynamic binding is in use.
4596 Reader macros. Common Lisp includes a second type of macro that
4597 works at the level of individual characters. For example, Common
4598 Lisp implements the quote notation by a reader macro called @code{'},
4599 whereas Emacs Lisp's parser just treats quote as a special case.
4600 Some Lisp packages use reader macros to create special syntaxes
4601 for themselves, which the Emacs parser is incapable of reading.
4604 Other syntactic features. Common Lisp provides a number of
4605 notations beginning with @code{#} that the Emacs Lisp parser
4606 won't understand. For example, @samp{#| @dots{} |#} is an
4607 alternate comment notation, and @samp{#+lucid (foo)} tells
4608 the parser to ignore the @code{(foo)} except in Lucid Common
4612 Packages. In Common Lisp, symbols are divided into @dfn{packages}.
4613 Symbols that are Lisp built-ins are typically stored in one package;
4614 symbols that are vendor extensions are put in another, and each
4615 application program would have a package for its own symbols.
4616 Certain symbols are ``exported'' by a package and others are
4617 internal; certain packages ``use'' or import the exported symbols
4618 of other packages. To access symbols that would not normally be
4619 visible due to this importing and exporting, Common Lisp provides
4620 a syntax like @code{package:symbol} or @code{package::symbol}.
4622 Emacs Lisp has a single namespace for all interned symbols, and
4623 then uses a naming convention of putting a prefix like @code{cl-}
4624 in front of the name. Some Emacs packages adopt the Common Lisp-like
4625 convention of using @code{cl:} or @code{cl::} as the prefix.
4626 However, the Emacs parser does not understand colons and just
4627 treats them as part of the symbol name. Thus, while @code{mapcar}
4628 and @code{lisp:mapcar} may refer to the same symbol in Common
4629 Lisp, they are totally distinct in Emacs Lisp. Common Lisp
4630 programs that refer to a symbol by the full name sometimes
4631 and the short name other times will not port cleanly to Emacs.
4633 Emacs Lisp does have a concept of ``obarrays'', which are
4634 package-like collections of symbols, but this feature is not
4635 strong enough to be used as a true package mechanism.
4638 The @code{format} function is quite different between Common
4639 Lisp and Emacs Lisp. It takes an additional ``destination''
4640 argument before the format string. A destination of @code{nil}
4641 means to format to a string as in Emacs Lisp; a destination
4642 of @code{t} means to write to the terminal (similar to
4643 @code{message} in Emacs). Also, format control strings are
4644 utterly different; @code{~} is used instead of @code{%} to
4645 introduce format codes, and the set of available codes is
4646 much richer. There are no notations like @code{\n} for
4647 string literals; instead, @code{format} is used with the
4648 ``newline'' format code, @code{~%}. More advanced formatting
4649 codes provide such features as paragraph filling, case
4650 conversion, and even loops and conditionals.
4652 While it would have been possible to implement most of Common
4653 Lisp @code{format} in this package (under the name @code{cl-format},
4654 of course), it was not deemed worthwhile. It would have required
4655 a huge amount of code to implement even a decent subset of
4656 @code{format}, yet the functionality it would provide over
4657 Emacs Lisp's @code{format} would rarely be useful.
4660 Vector constants use square brackets in Emacs Lisp, but
4661 @code{#(a b c)} notation in Common Lisp. To further complicate
4662 matters, Emacs has its own @code{#(} notation for
4663 something entirely different---strings with properties.
4666 Characters are distinct from integers in Common Lisp. The notation
4667 for character constants is also different: @code{#\A} in Common Lisp
4668 where Emacs Lisp uses @code{?A}. Also, @code{string=} and
4669 @code{string-equal} are synonyms in Emacs Lisp, whereas the latter is
4670 case-insensitive in Common Lisp.
4673 Data types. Some Common Lisp data types do not exist in Emacs
4674 Lisp. Rational numbers and complex numbers are not present,
4675 nor are large integers (all integers are ``fixnums''). All
4676 arrays are one-dimensional. There are no readtables or pathnames;
4677 streams are a set of existing data types rather than a new data
4678 type of their own. Hash tables, random-states, structures, and
4679 packages (obarrays) are built from Lisp vectors or lists rather
4680 than being distinct types.
4683 The Common Lisp Object System (CLOS) is not implemented,
4684 nor is the Common Lisp Condition System. However, the EIEIO package
4685 (@pxref{Top, , Introduction, eieio, EIEIO}) does implement some
4689 Common Lisp features that are completely redundant with Emacs
4690 Lisp features of a different name generally have not been
4691 implemented. For example, Common Lisp writes @code{defconstant}
4692 where Emacs Lisp uses @code{defconst}. Similarly, @code{make-list}
4693 takes its arguments in different ways in the two Lisps but does
4694 exactly the same thing, so this package has not bothered to
4695 implement a Common Lisp-style @code{make-list}.
4698 A few more notable Common Lisp features not included in this
4699 package: @code{compiler-let}, @code{tagbody}, @code{prog},
4700 @code{ldb/dpb}, @code{parse-integer}, @code{cerror}.
4703 Recursion. While recursion works in Emacs Lisp just like it
4704 does in Common Lisp, various details of the Emacs Lisp system
4705 and compiler make recursion much less efficient than it is in
4706 most Lisps. Some schools of thought prefer to use recursion
4707 in Lisp over other techniques; they would sum a list of
4708 numbers using something like
4711 (defun sum-list (list)
4713 (+ (car list) (sum-list (cdr list)))
4718 where a more iteratively-minded programmer might write one of
4722 (let ((total 0)) (dolist (x my-list) (incf total x)) total)
4723 (loop for x in my-list sum x)
4726 While this would be mainly a stylistic choice in most Common Lisps,
4727 in Emacs Lisp you should be aware that the iterative forms are
4728 much faster than recursion. Also, Lisp programmers will want to
4729 note that the current Emacs Lisp compiler does not optimize tail
4733 @node Obsolete Features
4734 @appendix Obsolete Features
4736 This section describes some features of the package that are obsolete
4737 and should not be used in new code. They are either only provided by
4738 the old @file{cl.el} entry point, not by the newer @file{cl-lib.el};
4739 or where versions with a @samp{cl-} prefix do exist they do not behave
4740 in exactly the same way.
4743 * Obsolete Lexical Binding:: An approximation of lexical binding.
4744 * Obsolete Macros:: Obsolete macros.
4745 * Obsolete Setf Customization:: Obsolete ways to customize setf.
4748 @node Obsolete Lexical Binding
4749 @appendixsec Obsolete Lexical Binding
4751 The following macros are extensions to Common Lisp, where all bindings
4752 are lexical unless declared otherwise. These features are likewise
4753 obsolete since the introduction of true lexical binding in Emacs 24.1.
4755 @defmac lexical-let (bindings@dots{}) forms@dots{}
4756 This form is exactly like @code{let} except that the bindings it
4757 establishes are purely lexical.
4760 @c FIXME remove this and refer to elisp manual.
4761 @c Maybe merge some stuff from here to there?
4763 Lexical bindings are similar to local variables in a language like C:
4764 Only the code physically within the body of the @code{lexical-let}
4765 (after macro expansion) may refer to the bound variables.
4769 (defun foo (b) (+ a b))
4770 (let ((a 2)) (foo a))
4772 (lexical-let ((a 2)) (foo a))
4777 In this example, a regular @code{let} binding of @code{a} actually
4778 makes a temporary change to the global variable @code{a}, so @code{foo}
4779 is able to see the binding of @code{a} to 2. But @code{lexical-let}
4780 actually creates a distinct local variable @code{a} for use within its
4781 body, without any effect on the global variable of the same name.
4783 The most important use of lexical bindings is to create @dfn{closures}.
4784 A closure is a function object that refers to an outside lexical
4785 variable (@pxref{Closures,,,elisp,GNU Emacs Lisp Reference Manual}).
4789 (defun make-adder (n)
4790 (lexical-let ((n n))
4791 (function (lambda (m) (+ n m)))))
4792 (setq add17 (make-adder 17))
4798 The call @code{(make-adder 17)} returns a function object which adds
4799 17 to its argument. If @code{let} had been used instead of
4800 @code{lexical-let}, the function object would have referred to the
4801 global @code{n}, which would have been bound to 17 only during the
4802 call to @code{make-adder} itself.
4805 (defun make-counter ()
4806 (lexical-let ((n 0))
4807 (cl-function (lambda (&optional (m 1)) (cl-incf n m)))))
4808 (setq count-1 (make-counter))
4811 (funcall count-1 14)
4813 (setq count-2 (make-counter))
4823 Here we see that each call to @code{make-counter} creates a distinct
4824 local variable @code{n}, which serves as a private counter for the
4825 function object that is returned.
4827 Closed-over lexical variables persist until the last reference to
4828 them goes away, just like all other Lisp objects. For example,
4829 @code{count-2} refers to a function object which refers to an
4830 instance of the variable @code{n}; this is the only reference
4831 to that variable, so after @code{(setq count-2 nil)} the garbage
4832 collector would be able to delete this instance of @code{n}.
4833 Of course, if a @code{lexical-let} does not actually create any
4834 closures, then the lexical variables are free as soon as the
4835 @code{lexical-let} returns.
4837 Many closures are used only during the extent of the bindings they
4838 refer to; these are known as ``downward funargs'' in Lisp parlance.
4839 When a closure is used in this way, regular Emacs Lisp dynamic
4840 bindings suffice and will be more efficient than @code{lexical-let}
4844 (defun add-to-list (x list)
4845 (mapcar (lambda (y) (+ x y))) list)
4846 (add-to-list 7 '(1 2 5))
4851 Since this lambda is only used while @code{x} is still bound,
4852 it is not necessary to make a true closure out of it.
4854 You can use @code{defun} or @code{flet} inside a @code{lexical-let}
4855 to create a named closure. If several closures are created in the
4856 body of a single @code{lexical-let}, they all close over the same
4857 instance of the lexical variable.
4859 @defmac lexical-let* (bindings@dots{}) forms@dots{}
4860 This form is just like @code{lexical-let}, except that the bindings
4861 are made sequentially in the manner of @code{let*}.
4864 @node Obsolete Macros
4865 @appendixsec Obsolete Macros
4867 The following macros are obsolete, and are replaced by versions with
4868 a @samp{cl-} prefix that do not behave in exactly the same way.
4869 Consequently, the @file{cl.el} versions are not simply aliases to the
4870 @file{cl-lib.el} versions.
4872 @defmac flet (bindings@dots{}) forms@dots{}
4873 This macro is replaced by @code{cl-flet} (@pxref{Function Bindings}),
4874 which behaves the same way as Common Lisp's @code{flet}.
4875 This @code{flet} takes the same arguments as @code{cl-flet}, but does
4876 not behave in precisely the same way.
4878 While @code{flet} in Common Lisp establishes a lexical function
4879 binding, this @code{flet} makes a dynamic binding (it dates from a
4880 time before Emacs had lexical binding). The result is
4881 that @code{flet} affects indirect calls to a function as well as calls
4882 directly inside the @code{flet} form itself.
4884 This will even work on Emacs primitives, although note that some calls
4885 to primitive functions internal to Emacs are made without going
4886 through the symbol's function cell, and so will not be affected by
4887 @code{flet}. For example,
4890 (flet ((message (&rest args) (push args saved-msgs)))
4894 This code attempts to replace the built-in function @code{message}
4895 with a function that simply saves the messages in a list rather
4896 than displaying them. The original definition of @code{message}
4897 will be restored after @code{do-something} exits. This code will
4898 work fine on messages generated by other Lisp code, but messages
4899 generated directly inside Emacs will not be caught since they make
4900 direct C-language calls to the message routines rather than going
4901 through the Lisp @code{message} function.
4903 For those cases where the dynamic scoping of @code{flet} is desired,
4904 @code{cl-flet} is clearly not a substitute. The most direct replacement would
4905 be instead to use @code{cl-letf} to temporarily rebind @code{(symbol-function
4906 '@var{fun})}. But in most cases, a better substitute is to use an advice, such
4910 (defvar my-fun-advice-enable nil)
4911 (add-advice '@var{fun} :around
4912 (lambda (orig &rest args)
4913 (if my-fun-advice-enable (do-something)
4914 (apply orig args))))
4917 so that you can then replace the @code{flet} with a simple dynamically scoped
4918 binding of @code{my-fun-advice-enable}.
4921 Note that many primitives (e.g., @code{+}) have special byte-compile handling.
4922 Attempts to redefine such functions using @code{flet}, @code{cl-letf}, or an
4923 advice will fail when byte-compiled.
4925 @c In such cases, use @code{labels} instead.
4928 @defmac labels (bindings@dots{}) forms@dots{}
4929 This macro is replaced by @code{cl-labels} (@pxref{Function Bindings}),
4930 which behaves the same way as Common Lisp's @code{labels}.
4931 This @code{labels} takes the same arguments as @code{cl-labels}, but
4932 does not behave in precisely the same way.
4934 This version of @code{labels} uses the obsolete @code{lexical-let}
4935 form (@pxref{Obsolete Lexical Binding}), rather than the true
4936 lexical binding that @code{cl-labels} uses.
4939 @node Obsolete Setf Customization
4940 @appendixsec Obsolete Ways to Customize Setf
4942 Common Lisp defines three macros, @code{define-modify-macro},
4943 @code{defsetf}, and @code{define-setf-method}, that allow the
4944 user to extend generalized variables in various ways.
4945 In Emacs, these are obsolete, replaced by various features of
4946 @file{gv.el} in Emacs 24.3.
4947 @xref{Adding Generalized Variables,,,elisp,GNU Emacs Lisp Reference Manual}.
4950 @defmac define-modify-macro name arglist function [doc-string]
4951 This macro defines a ``read-modify-write'' macro similar to
4952 @code{cl-incf} and @code{cl-decf}. You can replace this macro
4953 with @code{gv-letplace}.
4955 The macro @var{name} is defined to take a @var{place} argument
4956 followed by additional arguments described by @var{arglist}. The call
4959 (@var{name} @var{place} @var{args}@dots{})
4966 (cl-callf @var{func} @var{place} @var{args}@dots{})
4970 which in turn is roughly equivalent to
4973 (setf @var{place} (@var{func} @var{place} @var{args}@dots{}))
4979 (define-modify-macro incf (&optional (n 1)) +)
4980 (define-modify-macro concatf (&rest args) concat)
4983 Note that @code{&key} is not allowed in @var{arglist}, but
4984 @code{&rest} is sufficient to pass keywords on to the function.
4986 Most of the modify macros defined by Common Lisp do not exactly
4987 follow the pattern of @code{define-modify-macro}. For example,
4988 @code{push} takes its arguments in the wrong order, and @code{pop}
4989 is completely irregular.
4991 The above @code{incf} example could be written using
4992 @code{gv-letplace} as:
4994 (defmacro incf (place &optional n)
4995 (gv-letplace (getter setter) place
4996 (macroexp-let2 nil v (or n 1)
4997 (funcall setter `(+ ,v ,getter)))))
5000 (defmacro concatf (place &rest args)
5001 (gv-letplace (getter setter) place
5002 (macroexp-let2 nil v (mapconcat 'identity args "")
5003 (funcall setter `(concat ,getter ,v)))))
5007 @defmac defsetf access-fn update-fn
5008 This is the simpler of two @code{defsetf} forms, and is
5009 replaced by @code{gv-define-simple-setter}.
5011 With @var{access-fn} the name of a function that accesses a place,
5012 this declares @var{update-fn} to be the corresponding store function.
5016 (setf (@var{access-fn} @var{arg1} @var{arg2} @var{arg3}) @var{value})
5023 (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} @var{value})
5027 The @var{update-fn} is required to be either a true function, or
5028 a macro that evaluates its arguments in a function-like way. Also,
5029 the @var{update-fn} is expected to return @var{value} as its result.
5030 Otherwise, the above expansion would not obey the rules for the way
5031 @code{setf} is supposed to behave.
5033 As a special (non-Common-Lisp) extension, a third argument of @code{t}
5034 to @code{defsetf} says that the return value of @code{update-fn} is
5035 not suitable, so that the above @code{setf} should be expanded to
5039 (let ((temp @var{value}))
5040 (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} temp)
5047 (defsetf car setcar)
5048 (defsetf buffer-name rename-buffer t)
5051 These translate directly to @code{gv-define-simple-setter}:
5054 (gv-define-simple-setter car setcar)
5055 (gv-define-simple-setter buffer-name rename-buffer t)
5059 @defmac defsetf access-fn arglist (store-var) forms@dots{}
5060 This is the second, more complex, form of @code{defsetf}.
5061 It can be replaced by @code{gv-define-setter}.
5063 This form of @code{defsetf} is rather like @code{defmacro} except for
5064 the additional @var{store-var} argument. The @var{forms} should
5065 return a Lisp form that stores the value of @var{store-var} into the
5066 generalized variable formed by a call to @var{access-fn} with
5067 arguments described by @var{arglist}. The @var{forms} may begin with
5068 a string which documents the @code{setf} method (analogous to the doc
5069 string that appears at the front of a function).
5071 For example, the simple form of @code{defsetf} is shorthand for
5074 (defsetf @var{access-fn} (&rest args) (store)
5075 (append '(@var{update-fn}) args (list store)))
5078 The Lisp form that is returned can access the arguments from
5079 @var{arglist} and @var{store-var} in an unrestricted fashion;
5080 macros like @code{cl-incf} that invoke this
5081 setf-method will insert temporary variables as needed to make
5082 sure the apparent order of evaluation is preserved.
5084 Another standard example:
5087 (defsetf nth (n x) (store)
5088 `(setcar (nthcdr ,n ,x) ,store))
5091 You could write this using @code{gv-define-setter} as:
5094 (gv-define-setter nth (store n x)
5095 `(setcar (nthcdr ,n ,x) ,store))
5099 @defmac define-setf-method access-fn arglist forms@dots{}
5100 This is the most general way to create new place forms. You can
5101 replace this by @code{gv-define-setter} or @code{gv-define-expander}.
5103 When a @code{setf} to @var{access-fn} with arguments described by
5104 @var{arglist} is expanded, the @var{forms} are evaluated and must
5105 return a list of five items:
5109 A list of @dfn{temporary variables}.
5112 A list of @dfn{value forms} corresponding to the temporary variables
5113 above. The temporary variables will be bound to these value forms
5114 as the first step of any operation on the generalized variable.
5117 A list of exactly one @dfn{store variable} (generally obtained
5118 from a call to @code{gensym}).
5121 A Lisp form that stores the contents of the store variable into
5122 the generalized variable, assuming the temporaries have been
5123 bound as described above.
5126 A Lisp form that accesses the contents of the generalized variable,
5127 assuming the temporaries have been bound.
5130 This is exactly like the Common Lisp macro of the same name,
5131 except that the method returns a list of five values rather
5132 than the five values themselves, since Emacs Lisp does not
5133 support Common Lisp's notion of multiple return values.
5134 (Note that the @code{setf} implementation provided by @file{gv.el}
5135 does not use this five item format. Its use here is only for
5136 backwards compatibility.)
5138 Once again, the @var{forms} may begin with a documentation string.
5140 A setf-method should be maximally conservative with regard to
5141 temporary variables. In the setf-methods generated by
5142 @code{defsetf}, the second return value is simply the list of
5143 arguments in the place form, and the first return value is a
5144 list of a corresponding number of temporary variables generated
5145 @c FIXME I don't think this is true anymore.
5146 by @code{cl-gensym}. Macros like @code{cl-incf} that
5147 use this setf-method will optimize away most temporaries that
5148 turn out to be unnecessary, so there is little reason for the
5149 setf-method itself to optimize.
5152 @c Removed in Emacs 24.3, not possible to make a compatible replacement.
5154 @defun get-setf-method place &optional env
5155 This function returns the setf-method for @var{place}, by
5156 invoking the definition previously recorded by @code{defsetf}
5157 or @code{define-setf-method}. The result is a list of five
5158 values as described above. You can use this function to build
5159 your own @code{cl-incf}-like modify macros.
5161 The argument @var{env} specifies the ``environment'' to be
5162 passed on to @code{macroexpand} if @code{get-setf-method} should
5163 need to expand a macro in @var{place}. It should come from
5164 an @code{&environment} argument to the macro or setf-method
5165 that called @code{get-setf-method}.
5170 @node GNU Free Documentation License
5171 @appendix GNU Free Documentation License
5172 @include doclicense.texi
5174 @node Function Index
5175 @unnumbered Function Index
5179 @node Variable Index
5180 @unnumbered Variable Index