1 \input texinfo @c -*-texinfo-*-
2 @setfilename ../../info/cl.info
3 @settitle Common Lisp Extensions
8 This file documents the GNU Emacs Common Lisp emulation package.
10 Copyright @copyright{} 1993, 2001--2018 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.
80 * Concept Index:: An entry for each concept.
87 This document describes a set of Emacs Lisp facilities borrowed from
88 Common Lisp. All the facilities are described here in detail. While
89 this document does not assume any prior knowledge of Common Lisp, it
90 does assume a basic familiarity with Emacs Lisp.
92 Common Lisp is a huge language, and Common Lisp systems tend to be
93 massive and extremely complex. Emacs Lisp, by contrast, is rather
94 minimalist in the choice of Lisp features it offers the programmer.
95 As Emacs Lisp programmers have grown in number, and the applications
96 they write have grown more ambitious, it has become clear that Emacs
97 Lisp could benefit from many of the conveniences of Common Lisp.
99 The @dfn{CL} package adds a number of Common Lisp functions and
100 control structures to Emacs Lisp. While not a 100% complete
101 implementation of Common Lisp, it adds enough functionality
102 to make Emacs Lisp programming significantly more convenient.
104 Some Common Lisp features have been omitted from this package
109 Some features are too complex or bulky relative to their benefit
110 to Emacs Lisp programmers. CLOS and Common Lisp streams are fine
111 examples of this group. (The separate package EIEIO implements
112 a subset of CLOS functionality. @xref{Top, , Introduction, eieio, EIEIO}.)
115 Other features cannot be implemented without modification to the
116 Emacs Lisp interpreter itself, such as multiple return values,
117 case-insensitive symbols, and complex numbers.
118 This package generally makes no attempt to emulate these features.
122 This package was originally written by Dave Gillespie,
123 @file{daveg@@synaptics.com}, as a total rewrite of an earlier 1986
124 @file{cl.el} package by Cesar Quiroz. Care has been taken to ensure
125 that each function is defined efficiently, concisely, and with minimal
126 impact on the rest of the Emacs environment. Stefan Monnier added the
127 file @file{cl-lib.el} and rationalized the namespace for Emacs 24.3.
130 * Usage:: How to use this package.
131 * Organization:: The package's component files.
132 * Naming Conventions:: Notes on function names.
139 This package is distributed with Emacs, so there is no need
140 to install any additional files in order to start using it. Lisp code
141 that uses features from this package should simply include at
149 You may wish to add such a statement to your init file, if you
150 make frequent use of features from this package.
152 Code that only uses macros from this package can enclose the above in
153 @code{eval-when-compile}. Internally, this library is divided into
154 several files, @pxref{Organization}. Your code should only ever load
155 the main @file{cl-lib} file, which will load the others as needed.
158 @section Organization
161 The Common Lisp package is organized into four main files:
165 This is the main file, which contains basic functions
166 and information about the package. This file is relatively compact.
169 This file contains the larger, more complex or unusual functions.
170 It is kept separate so that packages which only want to use Common
171 Lisp fundamentals like the @code{cl-incf} function won't need to pay
172 the overhead of loading the more advanced functions.
175 This file contains most of the advanced functions for operating
176 on sequences or lists, such as @code{cl-delete-if} and @code{cl-assoc}.
179 This file contains the features that are macros instead of functions.
180 Macros expand when the caller is compiled, not when it is run, so the
181 macros generally only need to be present when the byte-compiler is
182 running (or when the macros are used in uncompiled code). Most of the
183 macros of this package are isolated in @file{cl-macs.el} so that they
184 won't take up memory unless you are compiling.
187 The file @file{cl-lib.el} includes all necessary @code{autoload}
188 commands for the functions and macros in the other three files.
189 All you have to do is @code{(require 'cl-lib)}, and @file{cl-lib.el}
190 will take care of pulling in the other files when they are
193 There is another file, @file{cl.el}, which was the main entry point to
194 this package prior to Emacs 24.3. Nowadays, it is replaced by
195 @file{cl-lib.el}. The two provide the same features (in most cases),
196 but use different function names (in fact, @file{cl.el} mainly just
197 defines aliases to the @file{cl-lib.el} definitions). Where
198 @file{cl-lib.el} defines a function called, for example,
199 @code{cl-incf}, @file{cl.el} uses the same name but without the
200 @samp{cl-} prefix, e.g., @code{incf} in this example. There are a few
201 exceptions to this. First, functions such as @code{cl-defun} where
202 the unprefixed version was already used for a standard Emacs Lisp
203 function. In such cases, the @file{cl.el} version adds a @samp{*}
204 suffix, e.g., @code{defun*}. Second, there are some obsolete features
205 that are only implemented in @file{cl.el}, not in @file{cl-lib.el},
206 because they are replaced by other standard Emacs Lisp features.
207 Finally, in a very few cases the old @file{cl.el} versions do not
208 behave in exactly the same way as the @file{cl-lib.el} versions.
209 @xref{Obsolete Features}.
210 @c There is also cl-mapc, which was called cl-mapc even before cl-lib.el.
211 @c But not autoloaded, so maybe not much used?
213 Since the old @file{cl.el} does not use a clean namespace, Emacs has a
214 policy that packages distributed with Emacs must not load @code{cl} at
215 run time. (It is ok for them to load @code{cl} at @emph{compile}
216 time, with @code{eval-when-compile}, and use the macros it provides.)
217 There is no such restriction on the use of @code{cl-lib}. New code
218 should use @code{cl-lib} rather than @code{cl}.
220 There is one more file, @file{cl-compat.el}, which defines some
221 routines from the older Quiroz @file{cl.el} package that are not otherwise
222 present in the new package. This file is obsolete and should not be
225 @node Naming Conventions
226 @section Naming Conventions
229 Except where noted, all functions defined by this package have the
230 same calling conventions as their Common Lisp counterparts, and
231 names that are those of Common Lisp plus a @samp{cl-} prefix.
233 Internal function and variable names in the package are prefixed
234 by @code{cl--}. Here is a complete list of functions prefixed by
235 @code{cl-} that were @emph{not} taken from Common Lisp:
238 cl-callf cl-callf2 cl-defsubst
242 @c This is not uninteresting I suppose, but is of zero practical relevance
243 @c to the user, and seems like a hostage to changing implementation details.
244 The following simple functions and macros are defined in @file{cl-lib.el};
245 they do not cause other components like @file{cl-extra} to be loaded.
248 cl-evenp cl-oddp cl-minusp
249 cl-plusp cl-endp cl-subst
250 cl-copy-list cl-list* cl-ldiff
251 cl-rest cl-decf [1] cl-incf [1]
252 cl-acons cl-adjoin [2] cl-pairlis
253 cl-pushnew [1,2] cl-declaim cl-proclaim
254 cl-caaar@dots{}cl-cddddr cl-first@dots{}cl-tenth
259 [1] Only when @var{place} is a plain variable name.
262 [2] Only if @code{:test} is @code{eq}, @code{equal}, or unspecified,
263 and @code{:key} is not used.
266 [3] Only for one sequence argument or two list arguments.
268 @node Program Structure
269 @chapter Program Structure
272 This section describes features of this package that have to
273 do with programs as a whole: advanced argument lists for functions,
274 and the @code{cl-eval-when} construct.
277 * Argument Lists:: @code{&key}, @code{&aux}, @code{cl-defun}, @code{cl-defmacro}.
278 * Time of Evaluation:: The @code{cl-eval-when} construct.
282 @section Argument Lists
287 Emacs Lisp's notation for argument lists of functions is a subset of
288 the Common Lisp notation. As well as the familiar @code{&optional}
289 and @code{&rest} markers, Common Lisp allows you to specify default
290 values for optional arguments, and it provides the additional markers
291 @code{&key} and @code{&aux}.
293 Since argument parsing is built-in to Emacs, there is no way for
294 this package to implement Common Lisp argument lists seamlessly.
295 Instead, this package defines alternates for several Lisp forms
296 which you must use if you need Common Lisp argument lists.
298 @defmac cl-defun name arglist body@dots{}
299 This form is identical to the regular @code{defun} form, except
300 that @var{arglist} is allowed to be a full Common Lisp argument
301 list. Also, the function body is enclosed in an implicit block
302 called @var{name}; @pxref{Blocks and Exits}.
305 @defmac cl-iter-defun name arglist body@dots{}
306 This form is identical to the regular @code{iter-defun} form, except
307 that @var{arglist} is allowed to be a full Common Lisp argument
308 list. Also, the function body is enclosed in an implicit block
309 called @var{name}; @pxref{Blocks and Exits}.
312 @defmac cl-defsubst name arglist body@dots{}
313 This is just like @code{cl-defun}, except that the function that
314 is defined is automatically proclaimed @code{inline}, i.e.,
315 calls to it may be expanded into in-line code by the byte compiler.
316 This is analogous to the @code{defsubst} form;
317 @code{cl-defsubst} uses a different method (compiler macros) which
318 works in all versions of Emacs, and also generates somewhat more
319 @c For some examples,
320 @c see https://lists.gnu.org/r/emacs-devel/2012-11/msg00009.html
321 efficient inline expansions. In particular, @code{cl-defsubst}
322 arranges for the processing of keyword arguments, default values,
323 etc., to be done at compile-time whenever possible.
326 @defmac cl-defmacro name arglist body@dots{}
327 This is identical to the regular @code{defmacro} form,
328 except that @var{arglist} is allowed to be a full Common Lisp
329 argument list. The @code{&environment} keyword is supported as
330 described in Steele's book @cite{Common Lisp, the Language}.
331 The @code{&whole} keyword is supported only
332 within destructured lists (see below); top-level @code{&whole}
333 cannot be implemented with the current Emacs Lisp interpreter.
334 The macro expander body is enclosed in an implicit block called
338 @defmac cl-function symbol-or-lambda
339 This is identical to the regular @code{function} form,
340 except that if the argument is a @code{lambda} form then that
341 form may use a full Common Lisp argument list.
344 Also, all forms (such as @code{cl-flet} and @code{cl-labels}) defined
345 in this package that include @var{arglist}s in their syntax allow
346 full Common Lisp argument lists.
348 Note that it is @emph{not} necessary to use @code{cl-defun} in
349 order to have access to most CL features in your function.
350 These features are always present; @code{cl-defun}'s only
351 difference from @code{defun} is its more flexible argument
352 lists and its implicit block.
354 The full form of a Common Lisp argument list is
358 &optional (@var{var} @var{initform} @var{svar})@dots{}
360 &key ((@var{keyword} @var{var}) @var{initform} @var{svar})@dots{}
361 &aux (@var{var} @var{initform})@dots{})
364 Each of the five argument list sections is optional. The @var{svar},
365 @var{initform}, and @var{keyword} parts are optional; if they are
366 omitted, then @samp{(@var{var})} may be written simply @samp{@var{var}}.
368 The first section consists of zero or more @dfn{required} arguments.
369 These arguments must always be specified in a call to the function;
370 there is no difference between Emacs Lisp and Common Lisp as far as
371 required arguments are concerned.
373 The second section consists of @dfn{optional} arguments. These
374 arguments may be specified in the function call; if they are not,
375 @var{initform} specifies the default value used for the argument.
376 (No @var{initform} means to use @code{nil} as the default.) The
377 @var{initform} is evaluated with the bindings for the preceding
378 arguments already established; @code{(a &optional (b (1+ a)))}
379 matches one or two arguments, with the second argument defaulting
380 to one plus the first argument. If the @var{svar} is specified,
381 it is an auxiliary variable which is bound to @code{t} if the optional
382 argument was specified, or to @code{nil} if the argument was omitted.
383 If you don't use an @var{svar}, then there will be no way for your
384 function to tell whether it was called with no argument, or with
385 the default value passed explicitly as an argument.
387 The third section consists of a single @dfn{rest} argument. If
388 more arguments were passed to the function than are accounted for
389 by the required and optional arguments, those extra arguments are
390 collected into a list and bound to the ``rest'' argument variable.
391 Common Lisp's @code{&rest} is equivalent to that of Emacs Lisp.
392 Common Lisp accepts @code{&body} as a synonym for @code{&rest} in
393 macro contexts; this package accepts it all the time.
395 The fourth section consists of @dfn{keyword} arguments. These
396 are optional arguments which are specified by name rather than
397 positionally in the argument list. For example,
400 (cl-defun foo (a &optional b &key c d (e 17)))
404 defines a function which may be called with one, two, or more
405 arguments. The first two arguments are bound to @code{a} and
406 @code{b} in the usual way. The remaining arguments must be
407 pairs of the form @code{:c}, @code{:d}, or @code{:e} followed
408 by the value to be bound to the corresponding argument variable.
409 (Symbols whose names begin with a colon are called @dfn{keywords},
410 and they are self-quoting in the same way as @code{nil} and
413 For example, the call @code{(foo 1 2 :d 3 :c 4)} sets the five
414 arguments to 1, 2, 4, 3, and 17, respectively. If the same keyword
415 appears more than once in the function call, the first occurrence
416 takes precedence over the later ones. Note that it is not possible
417 to specify keyword arguments without specifying the optional
418 argument @code{b} as well, since @code{(foo 1 :c 2)} would bind
419 @code{b} to the keyword @code{:c}, then signal an error because
420 @code{2} is not a valid keyword.
422 You can also explicitly specify the keyword argument; it need not be
423 simply the variable name prefixed with a colon. For example,
426 (cl-defun bar (&key (a 1) ((baz b) 4)))
431 specifies a keyword @code{:a} that sets the variable @code{a} with
432 default value 1, as well as a keyword @code{baz} that sets the
433 variable @code{b} with default value 4. In this case, because
434 @code{baz} is not self-quoting, you must quote it explicitly in the
435 function call, like this:
441 Ordinarily, it is an error to pass an unrecognized keyword to
442 a function, e.g., @code{(foo 1 2 :c 3 :goober 4)}. You can ask
443 Lisp to ignore unrecognized keywords, either by adding the
444 marker @code{&allow-other-keys} after the keyword section
445 of the argument list, or by specifying an @code{:allow-other-keys}
446 argument in the call whose value is non-@code{nil}. If the
447 function uses both @code{&rest} and @code{&key} at the same time,
448 the ``rest'' argument is bound to the keyword list as it appears
449 in the call. For example:
452 (cl-defun find-thing (thing &rest rest &key need &allow-other-keys)
453 (or (apply 'cl-member thing thing-list :allow-other-keys t rest)
454 (if need (error "Thing not found"))))
458 This function takes a @code{:need} keyword argument, but also
459 accepts other keyword arguments which are passed on to the
460 @code{cl-member} function. @code{allow-other-keys} is used to
461 keep both @code{find-thing} and @code{cl-member} from complaining
462 about each others' keywords in the arguments.
464 The fifth section of the argument list consists of @dfn{auxiliary
465 variables}. These are not really arguments at all, but simply
466 variables which are bound to @code{nil} or to the specified
467 @var{initforms} during execution of the function. There is no
468 difference between the following two functions, except for a
469 matter of stylistic taste:
472 (cl-defun foo (a b &aux (c (+ a b)) d)
480 @cindex destructuring, in argument list
481 Argument lists support @dfn{destructuring}. In Common Lisp,
482 destructuring is only allowed with @code{defmacro}; this package
483 allows it with @code{cl-defun} and other argument lists as well.
484 In destructuring, any argument variable (@var{var} in the above
485 example) can be replaced by a list of variables, or more generally,
486 a recursive argument list. The corresponding argument value must
487 be a list whose elements match this recursive argument list.
491 (cl-defmacro dolist ((var listform &optional resultform)
496 This says that the first argument of @code{dolist} must be a list
497 of two or three items; if there are other arguments as well as this
498 list, they are stored in @code{body}. All features allowed in
499 regular argument lists are allowed in these recursive argument lists.
500 In addition, the clause @samp{&whole @var{var}} is allowed at the
501 front of a recursive argument list. It binds @var{var} to the
502 whole list being matched; thus @code{(&whole all a b)} matches
503 a list of two things, with @code{a} bound to the first thing,
504 @code{b} bound to the second thing, and @code{all} bound to the
505 list itself. (Common Lisp allows @code{&whole} in top-level
506 @code{defmacro} argument lists as well, but Emacs Lisp does not
509 One last feature of destructuring is that the argument list may be
510 dotted, so that the argument list @code{(a b . c)} is functionally
511 equivalent to @code{(a b &rest c)}.
513 If the optimization quality @code{safety} is set to 0
514 (@pxref{Declarations}), error checking for wrong number of
515 arguments and invalid keyword arguments is disabled. By default,
516 argument lists are rigorously checked.
518 @node Time of Evaluation
519 @section Time of Evaluation
522 Normally, the byte-compiler does not actually execute the forms in
523 a file it compiles. For example, if a file contains @code{(setq foo t)},
524 the act of compiling it will not actually set @code{foo} to @code{t}.
525 This is true even if the @code{setq} was a top-level form (i.e., not
526 enclosed in a @code{defun} or other form). Sometimes, though, you
527 would like to have certain top-level forms evaluated at compile-time.
528 For example, the compiler effectively evaluates @code{defmacro} forms
529 at compile-time so that later parts of the file can refer to the
530 macros that are defined.
532 @defmac cl-eval-when (situations@dots{}) forms@dots{}
533 This form controls when the body @var{forms} are evaluated.
534 The @var{situations} list may contain any set of the symbols
535 @code{compile}, @code{load}, and @code{eval} (or their long-winded
536 ANSI equivalents, @code{:compile-toplevel}, @code{:load-toplevel},
537 and @code{:execute}).
539 The @code{cl-eval-when} form is handled differently depending on
540 whether or not it is being compiled as a top-level form.
541 Specifically, it gets special treatment if it is being compiled
542 by a command such as @code{byte-compile-file} which compiles files
543 or buffers of code, and it appears either literally at the
544 top level of the file or inside a top-level @code{progn}.
546 For compiled top-level @code{cl-eval-when}s, the body @var{forms} are
547 executed at compile-time if @code{compile} is in the @var{situations}
548 list, and the @var{forms} are written out to the file (to be executed
549 at load-time) if @code{load} is in the @var{situations} list.
551 For non-compiled-top-level forms, only the @code{eval} situation is
552 relevant. (This includes forms executed by the interpreter, forms
553 compiled with @code{byte-compile} rather than @code{byte-compile-file},
554 and non-top-level forms.) The @code{cl-eval-when} acts like a
555 @code{progn} if @code{eval} is specified, and like @code{nil}
556 (ignoring the body @var{forms}) if not.
558 The rules become more subtle when @code{cl-eval-when}s are nested;
559 consult Steele (second edition) for the gruesome details (and
560 some gruesome examples).
562 Some simple examples:
565 ;; Top-level forms in foo.el:
566 (cl-eval-when (compile) (setq foo1 'bar))
567 (cl-eval-when (load) (setq foo2 'bar))
568 (cl-eval-when (compile load) (setq foo3 'bar))
569 (cl-eval-when (eval) (setq foo4 'bar))
570 (cl-eval-when (eval compile) (setq foo5 'bar))
571 (cl-eval-when (eval load) (setq foo6 'bar))
572 (cl-eval-when (eval compile load) (setq foo7 'bar))
575 When @file{foo.el} is compiled, these variables will be set during
576 the compilation itself:
579 foo1 foo3 foo5 foo7 ; 'compile'
582 When @file{foo.elc} is loaded, these variables will be set:
585 foo2 foo3 foo6 foo7 ; 'load'
588 And if @file{foo.el} is loaded uncompiled, these variables will
592 foo4 foo5 foo6 foo7 ; 'eval'
595 If these seven @code{cl-eval-when}s had been, say, inside a @code{defun},
596 then the first three would have been equivalent to @code{nil} and the
597 last four would have been equivalent to the corresponding @code{setq}s.
599 Note that @code{(cl-eval-when (load eval) @dots{})} is equivalent
600 to @code{(progn @dots{})} in all contexts. The compiler treats
601 certain top-level forms, like @code{defmacro} (sort-of) and
602 @code{require}, as if they were wrapped in @code{(cl-eval-when
603 (compile load eval) @dots{})}.
606 Emacs includes two special forms related to @code{cl-eval-when}.
607 @xref{Eval During Compile,,,elisp,GNU Emacs Lisp Reference Manual}.
608 One of these, @code{eval-when-compile}, is not quite equivalent to
609 any @code{cl-eval-when} construct and is described below.
611 The other form, @code{(eval-and-compile @dots{})}, is exactly
612 equivalent to @samp{(cl-eval-when (compile load eval) @dots{})}.
614 @defmac eval-when-compile forms@dots{}
615 The @var{forms} are evaluated at compile-time; at execution time,
616 this form acts like a quoted constant of the resulting value. Used
617 at top-level, @code{eval-when-compile} is just like @samp{eval-when
618 (compile eval)}. In other contexts, @code{eval-when-compile}
619 allows code to be evaluated once at compile-time for efficiency
622 This form is similar to the @samp{#.} syntax of true Common Lisp.
625 @defmac cl-load-time-value form
626 The @var{form} is evaluated at load-time; at execution time,
627 this form acts like a quoted constant of the resulting value.
629 Early Common Lisp had a @samp{#,} syntax that was similar to
630 this, but ANSI Common Lisp replaced it with @code{load-time-value}
631 and gave it more well-defined semantics.
633 In a compiled file, @code{cl-load-time-value} arranges for @var{form}
634 to be evaluated when the @file{.elc} file is loaded and then used
635 as if it were a quoted constant. In code compiled by
636 @code{byte-compile} rather than @code{byte-compile-file}, the
637 effect is identical to @code{eval-when-compile}. In uncompiled
638 code, both @code{eval-when-compile} and @code{cl-load-time-value}
639 act exactly like @code{progn}.
643 (insert "This function was executed on: "
644 (current-time-string)
646 (eval-when-compile (current-time-string))
647 ;; or '#.(current-time-string) in real Common Lisp
649 (cl-load-time-value (current-time-string))))
653 Byte-compiled, the above defun will result in the following code
654 (or its compiled equivalent, of course) in the @file{.elc} file:
657 (setq --temp-- (current-time-string))
659 (insert "This function was executed on: "
660 (current-time-string)
662 '"Wed Oct 31 16:32:28 2012"
672 This section describes functions for testing whether various
673 facts are true or false.
676 * Type Predicates:: @code{cl-typep}, @code{cl-deftype}, and @code{cl-coerce}.
677 * Equality Predicates:: @code{cl-equalp}.
680 @node Type Predicates
681 @section Type Predicates
683 @defun cl-typep object type
684 Check if @var{object} is of type @var{type}, where @var{type} is a
685 (quoted) type name of the sort used by Common Lisp. For example,
686 @code{(cl-typep foo 'integer)} is equivalent to @code{(integerp foo)}.
689 The @var{type} argument to the above function is either a symbol
690 or a list beginning with a symbol.
694 If the type name is a symbol, Emacs appends @samp{-p} to the
695 symbol name to form the name of a predicate function for testing
696 the type. (Built-in predicates whose names end in @samp{p} rather
697 than @samp{-p} are used when appropriate.)
700 The type symbol @code{t} stands for the union of all types.
701 @code{(cl-typep @var{object} t)} is always true. Likewise, the
702 type symbol @code{nil} stands for nothing at all, and
703 @code{(cl-typep @var{object} nil)} is always false.
706 The type symbol @code{null} represents the symbol @code{nil}.
707 Thus @code{(cl-typep @var{object} 'null)} is equivalent to
708 @code{(null @var{object})}.
711 The type symbol @code{atom} represents all objects that are not cons
712 cells. Thus @code{(cl-typep @var{object} 'atom)} is equivalent to
713 @code{(atom @var{object})}.
716 The type symbol @code{real} is a synonym for @code{number}, and
717 @code{fixnum} is a synonym for @code{integer}.
720 The type symbols @code{character} and @code{string-char} match
721 integers in the range from 0 to 255.
724 The type list @code{(integer @var{low} @var{high})} represents all
725 integers between @var{low} and @var{high}, inclusive. Either bound
726 may be a list of a single integer to specify an exclusive limit,
727 or a @code{*} to specify no limit. The type @code{(integer * *)}
728 is thus equivalent to @code{integer}.
731 Likewise, lists beginning with @code{float}, @code{real}, or
732 @code{number} represent numbers of that type falling in a particular
736 Lists beginning with @code{and}, @code{or}, and @code{not} form
737 combinations of types. For example, @code{(or integer (float 0 *))}
738 represents all objects that are integers or non-negative floats.
741 Lists beginning with @code{member} or @code{cl-member} represent
742 objects @code{eql} to any of the following values. For example,
743 @code{(member 1 2 3 4)} is equivalent to @code{(integer 1 4)},
744 and @code{(member nil)} is equivalent to @code{null}.
747 Lists of the form @code{(satisfies @var{predicate})} represent
748 all objects for which @var{predicate} returns true when called
749 with that object as an argument.
752 The following function and macro (not technically predicates) are
753 related to @code{cl-typep}.
755 @defun cl-coerce object type
756 This function attempts to convert @var{object} to the specified
757 @var{type}. If @var{object} is already of that type as determined by
758 @code{cl-typep}, it is simply returned. Otherwise, certain types of
759 conversions will be made: If @var{type} is any sequence type
760 (@code{string}, @code{list}, etc.)@: then @var{object} will be
761 converted to that type if possible. If @var{type} is
762 @code{character}, then strings of length one and symbols with
763 one-character names can be coerced. If @var{type} is @code{float},
764 then integers can be coerced in versions of Emacs that support
765 floats. In all other circumstances, @code{cl-coerce} signals an
769 @defmac cl-deftype name arglist forms@dots{}
770 This macro defines a new type called @var{name}. It is similar
771 to @code{defmacro} in many ways; when @var{name} is encountered
772 as a type name, the body @var{forms} are evaluated and should
773 return a type specifier that is equivalent to the type. The
774 @var{arglist} is a Common Lisp argument list of the sort accepted
775 by @code{cl-defmacro}. The type specifier @samp{(@var{name} @var{args}@dots{})}
776 is expanded by calling the expander with those arguments; the type
777 symbol @samp{@var{name}} is expanded by calling the expander with
778 no arguments. The @var{arglist} is processed the same as for
779 @code{cl-defmacro} except that optional arguments without explicit
780 defaults use @code{*} instead of @code{nil} as the ``default''
781 default. Some examples:
784 (cl-deftype null () '(satisfies null)) ; predefined
785 (cl-deftype list () '(or null cons)) ; predefined
786 (cl-deftype unsigned-byte (&optional bits)
787 (list 'integer 0 (if (eq bits '*) bits (1- (lsh 1 bits)))))
788 (unsigned-byte 8) @equiv{} (integer 0 255)
789 (unsigned-byte) @equiv{} (integer 0 *)
790 unsigned-byte @equiv{} (integer 0 *)
794 The last example shows how the Common Lisp @code{unsigned-byte}
795 type specifier could be implemented if desired; this package does
796 not implement @code{unsigned-byte} by default.
799 The @code{cl-typecase} (@pxref{Conditionals}) and @code{cl-check-type}
800 (@pxref{Assertions}) macros also use type names. The @code{cl-map},
801 @code{cl-concatenate}, and @code{cl-merge} functions take type-name
802 arguments to specify the type of sequence to return. @xref{Sequences}.
804 @node Equality Predicates
805 @section Equality Predicates
808 This package defines the Common Lisp predicate @code{cl-equalp}.
811 This function is a more flexible version of @code{equal}. In
812 particular, it compares strings case-insensitively, and it compares
813 numbers without regard to type (so that @code{(cl-equalp 3 3.0)} is
814 true). Vectors and conses are compared recursively. All other
815 objects are compared as if by @code{equal}.
817 This function differs from Common Lisp @code{equalp} in several
818 respects. First, Common Lisp's @code{equalp} also compares
819 @emph{characters} case-insensitively, which would be impractical
820 in this package since Emacs does not distinguish between integers
821 and characters. In keeping with the idea that strings are less
822 vector-like in Emacs Lisp, this package's @code{cl-equalp} also will
823 not compare strings against vectors of integers.
826 Also note that the Common Lisp functions @code{member} and @code{assoc}
827 use @code{eql} to compare elements, whereas Emacs Lisp follows the
828 MacLisp tradition and uses @code{equal} for these two functions.
829 The functions @code{cl-member} and @code{cl-assoc} use @code{eql},
830 as in Common Lisp. The standard Emacs Lisp functions @code{memq} and
831 @code{assq} use @code{eq}, and the standard @code{memql} uses @code{eql}.
833 @node Control Structure
834 @chapter Control Structure
837 The features described in the following sections implement
838 various advanced control structures, including extensions to the
839 standard @code{setf} facility, and a number of looping and conditional
843 * Assignment:: The @code{cl-psetq} form.
844 * Generalized Variables:: Extensions to generalized variables.
845 * Variable Bindings:: @code{cl-progv}, @code{cl-flet}, @code{cl-macrolet}.
846 * Conditionals:: @code{cl-case}, @code{cl-typecase}.
847 * Blocks and Exits:: @code{cl-block}, @code{cl-return}, @code{cl-return-from}.
848 * Iteration:: @code{cl-do}, @code{cl-dotimes}, @code{cl-dolist}, @code{cl-do-symbols}.
849 * Loop Facility:: The Common Lisp @code{loop} macro.
850 * Multiple Values:: @code{cl-values}, @code{cl-multiple-value-bind}, etc.
857 The @code{cl-psetq} form is just like @code{setq}, except that multiple
858 assignments are done in parallel rather than sequentially.
860 @defmac cl-psetq [symbol form]@dots{}
861 This special form (actually a macro) is used to assign to several
862 variables simultaneously. Given only one @var{symbol} and @var{form},
863 it has the same effect as @code{setq}. Given several @var{symbol}
864 and @var{form} pairs, it evaluates all the @var{form}s in advance
865 and then stores the corresponding variables afterwards.
869 (setq x (+ x y) y (* x y))
872 y ; @r{@code{y} was computed after @code{x} was set.}
875 (cl-psetq x (+ x y) y (* x y))
878 y ; @r{@code{y} was computed before @code{x} was set.}
882 The simplest use of @code{cl-psetq} is @code{(cl-psetq x y y x)}, which
883 exchanges the values of two variables. (The @code{cl-rotatef} form
884 provides an even more convenient way to swap two variables;
885 @pxref{Modify Macros}.)
887 @code{cl-psetq} always returns @code{nil}.
890 @node Generalized Variables
891 @section Generalized Variables
892 @cindex generalized variable
894 A @dfn{generalized variable} or @dfn{place form} is one of the many
895 places in Lisp memory where values can be stored. The simplest place
896 form is a regular Lisp variable. But the @sc{car}s and @sc{cdr}s of lists,
897 elements of arrays, properties of symbols, and many other locations
898 are also places where Lisp values are stored. For basic information,
899 @pxref{Generalized Variables,,,elisp,GNU Emacs Lisp Reference Manual}.
900 This package provides several additional features related to
901 generalized variables.
904 * Setf Extensions:: Additional @code{setf} places.
905 * Modify Macros:: @code{cl-incf}, @code{cl-rotatef}, @code{cl-letf}, @code{cl-callf}, etc.
908 @node Setf Extensions
909 @subsection Setf Extensions
911 Several standard (e.g., @code{car}) and Emacs-specific
912 (e.g., @code{window-point}) Lisp functions are @code{setf}-able by default.
913 This package defines @code{setf} handlers for several additional functions:
917 Functions from this package:
919 cl-rest cl-subseq cl-get cl-getf
920 cl-caaar@dots{}cl-cddddr cl-first@dots{}cl-tenth
924 Note that for @code{cl-getf} (as for @code{nthcdr}), the list argument
925 of the function must itself be a valid @var{place} form.
928 General Emacs Lisp functions:
930 buffer-file-name getenv
931 buffer-modified-p global-key-binding
932 buffer-name local-key-binding
934 buffer-substring mark-marker
935 current-buffer marker-position
936 current-case-table mouse-position
938 current-global-map point-marker
939 current-input-mode point-max
940 current-local-map point-min
941 current-window-configuration read-mouse-position
942 default-file-modes screen-height
943 documentation-property screen-width
944 face-background selected-window
945 face-background-pixmap selected-screen
946 face-font selected-frame
947 face-foreground standard-case-table
948 face-underline-p syntax-table
949 file-modes visited-file-modtime
950 frame-height window-height
951 frame-parameters window-width
952 frame-visible-p x-get-secondary-selection
953 frame-width x-get-selection
957 Most of these have directly corresponding ``set'' functions, like
958 @code{use-local-map} for @code{current-local-map}, or @code{goto-char}
959 for @code{point}. A few, like @code{point-min}, expand to longer
960 sequences of code when they are used with @code{setf}
961 (@code{(narrow-to-region x (point-max))} in this case).
964 A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])},
965 where @var{subplace} is itself a valid generalized variable whose
966 current value is a string, and where the value stored is also a
967 string. The new string is spliced into the specified part of the
968 destination string. For example:
971 (setq a (list "hello" "world"))
972 @result{} ("hello" "world")
975 (substring (cadr a) 2 4)
977 (setf (substring (cadr a) 2 4) "o")
982 @result{} ("hello" "wood")
985 The generalized variable @code{buffer-substring}, listed above,
986 also works in this way by replacing a portion of the current buffer.
988 @c FIXME? Also 'eq'? (see cl-lib.el)
990 @c Currently commented out in cl.el.
993 A call of the form @code{(apply '@var{func} @dots{})} or
994 @code{(apply (function @var{func}) @dots{})}, where @var{func}
995 is a @code{setf}-able function whose store function is ``suitable''
996 in the sense described in Steele's book; since none of the standard
997 Emacs place functions are suitable in this sense, this feature is
998 only interesting when used with places you define yourself with
999 @code{define-setf-method} or the long form of @code{defsetf}.
1000 @xref{Obsolete Setf Customization}.
1003 @c FIXME? Is this still true?
1005 A macro call, in which case the macro is expanded and @code{setf}
1006 is applied to the resulting form.
1009 @c FIXME should this be in lispref? It seems self-evident.
1010 @c Contrast with the cl-incf example later on.
1011 @c Here it really only serves as a contrast to wrong-order.
1012 The @code{setf} macro takes care to evaluate all subforms in
1013 the proper left-to-right order; for example,
1016 (setf (aref vec (cl-incf i)) i)
1020 looks like it will evaluate @code{(cl-incf i)} exactly once, before the
1021 following access to @code{i}; the @code{setf} expander will insert
1022 temporary variables as necessary to ensure that it does in fact work
1023 this way no matter what setf-method is defined for @code{aref}.
1024 (In this case, @code{aset} would be used and no such steps would
1025 be necessary since @code{aset} takes its arguments in a convenient
1028 However, if the @var{place} form is a macro which explicitly
1029 evaluates its arguments in an unusual order, this unusual order
1030 will be preserved. Adapting an example from Steele, given
1033 (defmacro wrong-order (x y) (list 'aref y x))
1037 the form @code{(setf (wrong-order @var{a} @var{b}) 17)} will
1038 evaluate @var{b} first, then @var{a}, just as in an actual call
1039 to @code{wrong-order}.
1042 @subsection Modify Macros
1045 This package defines a number of macros that operate on generalized
1046 variables. Many are interesting and useful even when the @var{place}
1047 is just a variable name.
1049 @defmac cl-psetf [place form]@dots{}
1050 This macro is to @code{setf} what @code{cl-psetq} is to @code{setq}:
1051 When several @var{place}s and @var{form}s are involved, the
1052 assignments take place in parallel rather than sequentially.
1053 Specifically, all subforms are evaluated from left to right, then
1054 all the assignments are done (in an undefined order).
1057 @defmac cl-incf place &optional x
1058 This macro increments the number stored in @var{place} by one, or
1059 by @var{x} if specified. The incremented value is returned. For
1060 example, @code{(cl-incf i)} is equivalent to @code{(setq i (1+ i))}, and
1061 @code{(cl-incf (car x) 2)} is equivalent to @code{(setcar x (+ (car x) 2))}.
1063 As with @code{setf}, care is taken to preserve the ``apparent'' order
1064 of evaluation. For example,
1067 (cl-incf (aref vec (cl-incf i)))
1071 appears to increment @code{i} once, then increment the element of
1072 @code{vec} addressed by @code{i}; this is indeed exactly what it
1073 does, which means the above form is @emph{not} equivalent to the
1074 ``obvious'' expansion,
1077 (setf (aref vec (cl-incf i))
1078 (1+ (aref vec (cl-incf i)))) ; wrong!
1082 but rather to something more like
1085 (let ((temp (cl-incf i)))
1086 (setf (aref vec temp) (1+ (aref vec temp))))
1090 Again, all of this is taken care of automatically by @code{cl-incf} and
1091 the other generalized-variable macros.
1093 As a more Emacs-specific example of @code{cl-incf}, the expression
1094 @code{(cl-incf (point) @var{n})} is essentially equivalent to
1095 @code{(forward-char @var{n})}.
1098 @defmac cl-decf place &optional x
1099 This macro decrements the number stored in @var{place} by one, or
1100 by @var{x} if specified.
1103 @defmac cl-pushnew x place @t{&key :test :test-not :key}
1104 This macro inserts @var{x} at the front of the list stored in
1105 @var{place}, but only if @var{x} was not @code{eql} to any
1106 existing element of the list. The optional keyword arguments
1107 are interpreted in the same way as for @code{cl-adjoin}.
1108 @xref{Lists as Sets}.
1111 @defmac cl-shiftf place@dots{} newvalue
1112 This macro shifts the @var{place}s left by one, shifting in the
1113 value of @var{newvalue} (which may be any Lisp expression, not just
1114 a generalized variable), and returning the value shifted out of
1115 the first @var{place}. Thus, @code{(cl-shiftf @var{a} @var{b} @var{c}
1116 @var{d})} is equivalent to
1121 (cl-psetf @var{a} @var{b}
1127 except that the subforms of @var{a}, @var{b}, and @var{c} are actually
1128 evaluated only once each and in the apparent order.
1131 @defmac cl-rotatef place@dots{}
1132 This macro rotates the @var{place}s left by one in circular fashion.
1133 Thus, @code{(cl-rotatef @var{a} @var{b} @var{c} @var{d})} is equivalent to
1136 (cl-psetf @var{a} @var{b}
1143 except for the evaluation of subforms. @code{cl-rotatef} always
1144 returns @code{nil}. Note that @code{(cl-rotatef @var{a} @var{b})}
1145 conveniently exchanges @var{a} and @var{b}.
1148 The following macros were invented for this package; they have no
1149 analogues in Common Lisp.
1151 @defmac cl-letf (bindings@dots{}) forms@dots{}
1152 This macro is analogous to @code{let}, but for generalized variables
1153 rather than just symbols. Each @var{binding} should be of the form
1154 @code{(@var{place} @var{value})}; the original contents of the
1155 @var{place}s are saved, the @var{value}s are stored in them, and
1156 then the body @var{form}s are executed. Afterwards, the @var{places}
1157 are set back to their original saved contents. This cleanup happens
1158 even if the @var{form}s exit irregularly due to a @code{throw} or an
1164 (cl-letf (((point) (point-min))
1170 moves point in the current buffer to the beginning of the buffer,
1171 and also binds @code{a} to 17 (as if by a normal @code{let}, since
1172 @code{a} is just a regular variable). After the body exits, @code{a}
1173 is set back to its original value and point is moved back to its
1176 Note that @code{cl-letf} on @code{(point)} is not quite like a
1177 @code{save-excursion}, as the latter effectively saves a marker
1178 which tracks insertions and deletions in the buffer. Actually,
1179 a @code{cl-letf} of @code{(point-marker)} is much closer to this
1180 behavior. (@code{point} and @code{point-marker} are equivalent
1181 as @code{setf} places; each will accept either an integer or a
1182 marker as the stored value.)
1184 Like in the case of @code{let}, the @var{value} forms are evaluated in
1185 the order they appear, but the order of bindings is unspecified.
1186 Therefore, avoid binding the same @var{place} more than once in a
1187 single @code{cl-letf} form.
1189 Since generalized variables look like lists, @code{let}'s shorthand
1190 of using @samp{foo} for @samp{(foo nil)} as a @var{binding} would
1191 be ambiguous in @code{cl-letf} and is not allowed.
1193 However, a @var{binding} specifier may be a one-element list
1194 @samp{(@var{place})}, which is similar to @samp{(@var{place}
1195 @var{place})}. In other words, the @var{place} is not disturbed
1196 on entry to the body, and the only effect of the @code{cl-letf} is
1197 to restore the original value of @var{place} afterwards.
1198 @c I suspect this may no longer be true; either way it's
1199 @c implementation detail and so not essential to document.
1201 (The redundant access-and-store suggested by the @code{(@var{place}
1202 @var{place})} example does not actually occur.)
1205 Note that in this case, and in fact almost every case, @var{place}
1206 must have a well-defined value outside the @code{cl-letf} body.
1207 There is essentially only one exception to this, which is @var{place}
1208 a plain variable with a specified @var{value} (such as @code{(a 17)}
1209 in the above example).
1210 @c See https://debbugs.gnu.org/12758
1211 @c Some or all of this was true for cl.el, but not for cl-lib.el.
1213 The only exceptions are plain variables and calls to
1214 @code{symbol-value} and @code{symbol-function}. If the symbol is not
1215 bound on entry, it is simply made unbound by @code{makunbound} or
1216 @code{fmakunbound} on exit.
1220 @defmac cl-letf* (bindings@dots{}) forms@dots{}
1221 This macro is to @code{cl-letf} what @code{let*} is to @code{let}:
1222 It does the bindings in sequential rather than parallel order.
1225 @defmac cl-callf @var{function} @var{place} @var{args}@dots{}
1226 This is the ``generic'' modify macro. It calls @var{function},
1227 which should be an unquoted function name, macro name, or lambda.
1228 It passes @var{place} and @var{args} as arguments, and assigns the
1229 result back to @var{place}. For example, @code{(cl-incf @var{place}
1230 @var{n})} is the same as @code{(cl-callf + @var{place} @var{n})}.
1234 (cl-callf abs my-number)
1235 (cl-callf concat (buffer-name) "<" (number-to-string n) ">")
1236 (cl-callf cl-union happy-people (list joe bob) :test 'same-person)
1239 Note again that @code{cl-callf} is an extension to standard Common Lisp.
1242 @defmac cl-callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{}
1243 This macro is like @code{cl-callf}, except that @var{place} is
1244 the @emph{second} argument of @var{function} rather than the
1245 first. For example, @code{(push @var{x} @var{place})} is
1246 equivalent to @code{(cl-callf2 cons @var{x} @var{place})}.
1249 The @code{cl-callf} and @code{cl-callf2} macros serve as building
1250 blocks for other macros like @code{cl-incf}, and @code{cl-pushnew}.
1251 The @code{cl-letf} and @code{cl-letf*} macros are used in the processing
1252 of symbol macros; @pxref{Macro Bindings}.
1255 @node Variable Bindings
1256 @section Variable Bindings
1257 @cindex variable binding
1260 These Lisp forms make bindings to variables and function names,
1261 analogous to Lisp's built-in @code{let} form.
1263 @xref{Modify Macros}, for the @code{cl-letf} and @code{cl-letf*} forms which
1264 are also related to variable bindings.
1267 * Dynamic Bindings:: The @code{cl-progv} form.
1268 * Function Bindings:: @code{cl-flet} and @code{cl-labels}.
1269 * Macro Bindings:: @code{cl-macrolet} and @code{cl-symbol-macrolet}.
1272 @node Dynamic Bindings
1273 @subsection Dynamic Bindings
1274 @cindex dynamic binding
1277 The standard @code{let} form binds variables whose names are known
1278 at compile-time. The @code{cl-progv} form provides an easy way to
1279 bind variables whose names are computed at run-time.
1281 @defmac cl-progv symbols values forms@dots{}
1282 This form establishes @code{let}-style variable bindings on a
1283 set of variables computed at run-time. The expressions
1284 @var{symbols} and @var{values} are evaluated, and must return lists
1285 of symbols and values, respectively. The symbols are bound to the
1286 corresponding values for the duration of the body @var{form}s.
1287 If @var{values} is shorter than @var{symbols}, the last few symbols
1288 are bound to @code{nil}.
1289 If @var{symbols} is shorter than @var{values}, the excess values
1293 @node Function Bindings
1294 @subsection Function Bindings
1295 @cindex function binding
1298 These forms make @code{let}-like bindings to functions instead
1301 @defmac cl-flet (bindings@dots{}) forms@dots{}
1302 This form establishes @code{let}-style bindings on the function
1303 cells of symbols rather than on the value cells. Each @var{binding}
1304 must be a list of the form @samp{(@var{name} @var{arglist}
1305 @var{forms}@dots{})}, which defines a function exactly as if
1306 it were a @code{cl-defun} form. The function @var{name} is defined
1307 accordingly but only within the body of the @code{cl-flet}, hiding any external
1308 definition if applicable.
1310 The bindings are lexical in scope. This means that all references to
1311 the named functions must appear physically within the body of the
1312 @code{cl-flet} form.
1314 Functions defined by @code{cl-flet} may use the full Common Lisp
1315 argument notation supported by @code{cl-defun}; also, the function
1316 body is enclosed in an implicit block as if by @code{cl-defun}.
1317 @xref{Program Structure}.
1319 Note that the @file{cl.el} version of this macro behaves slightly
1320 differently. In particular, its binding is dynamic rather than
1321 lexical. @xref{Obsolete Macros}.
1324 @defmac cl-labels (bindings@dots{}) forms@dots{}
1325 The @code{cl-labels} form is like @code{cl-flet}, except that
1326 the function bindings can be recursive. The scoping is lexical,
1327 but you can only capture functions in closures if
1328 @code{lexical-binding} is @code{t}.
1329 @xref{Closures,,,elisp,GNU Emacs Lisp Reference Manual}, and
1330 @ref{Using Lexical Binding,,,elisp,GNU Emacs Lisp Reference Manual}.
1332 Lexical scoping means that all references to the named
1333 functions must appear physically within the body of the
1334 @code{cl-labels} form. References may appear both in the body
1335 @var{forms} of @code{cl-labels} itself, and in the bodies of
1336 the functions themselves. Thus, @code{cl-labels} can define
1337 local recursive functions, or mutually-recursive sets of functions.
1339 A ``reference'' to a function name is either a call to that
1340 function, or a use of its name quoted by @code{quote} or
1341 @code{function} to be passed on to, say, @code{mapcar}.
1343 Note that the @file{cl.el} version of this macro behaves slightly
1344 differently. @xref{Obsolete Macros}.
1347 @node Macro Bindings
1348 @subsection Macro Bindings
1349 @cindex macro binding
1352 These forms create local macros and ``symbol macros''.
1354 @defmac cl-macrolet (bindings@dots{}) forms@dots{}
1355 This form is analogous to @code{cl-flet}, but for macros instead of
1356 functions. Each @var{binding} is a list of the same form as the
1357 arguments to @code{cl-defmacro} (i.e., a macro name, argument list,
1358 and macro-expander forms). The macro is defined accordingly for
1359 use within the body of the @code{cl-macrolet}.
1361 Because of the nature of macros, @code{cl-macrolet} is always lexically
1362 scoped. The @code{cl-macrolet} binding will
1363 affect only calls that appear physically within the body
1364 @var{forms}, possibly after expansion of other macros in the
1368 @defmac cl-symbol-macrolet (bindings@dots{}) forms@dots{}
1369 This form creates @dfn{symbol macros}, which are macros that look
1370 like variable references rather than function calls. Each
1371 @var{binding} is a list @samp{(@var{var} @var{expansion})};
1372 any reference to @var{var} within the body @var{forms} is
1373 replaced by @var{expansion}.
1377 (cl-symbol-macrolet ((foo (car bar)))
1383 A @code{setq} of a symbol macro is treated the same as a @code{setf}.
1384 I.e., @code{(setq foo 4)} in the above would be equivalent to
1385 @code{(setf foo 4)}, which in turn expands to @code{(setf (car bar) 4)}.
1387 Likewise, a @code{let} or @code{let*} binding a symbol macro is
1388 treated like a @code{cl-letf} or @code{cl-letf*}. This differs from true
1389 Common Lisp, where the rules of lexical scoping cause a @code{let}
1390 binding to shadow a @code{symbol-macrolet} binding. In this package,
1391 such shadowing does not occur, even when @code{lexical-binding} is
1392 @c See https://debbugs.gnu.org/12119
1393 @code{t}. (This behavior predates the addition of lexical binding to
1394 Emacs Lisp, and may change in future to respect @code{lexical-binding}.)
1395 At present in this package, only @code{lexical-let} and
1396 @code{lexical-let*} will shadow a symbol macro. @xref{Obsolete
1399 There is no analogue of @code{defmacro} for symbol macros; all symbol
1400 macros are local. A typical use of @code{cl-symbol-macrolet} is in the
1401 expansion of another macro:
1404 (cl-defmacro my-dolist ((x list) &rest body)
1405 (let ((var (cl-gensym)))
1406 (list 'cl-loop 'for var 'on list 'do
1407 (cl-list* 'cl-symbol-macrolet
1408 (list (list x (list 'car var)))
1411 (setq mylist '(1 2 3 4))
1412 (my-dolist (x mylist) (cl-incf x))
1418 In this example, the @code{my-dolist} macro is similar to @code{dolist}
1419 (@pxref{Iteration}) except that the variable @code{x} becomes a true
1420 reference onto the elements of the list. The @code{my-dolist} call
1421 shown here expands to
1424 (cl-loop for G1234 on mylist do
1425 (cl-symbol-macrolet ((x (car G1234)))
1430 which in turn expands to
1433 (cl-loop for G1234 on mylist do (cl-incf (car G1234)))
1436 @xref{Loop Facility}, for a description of the @code{cl-loop} macro.
1437 This package defines a nonstandard @code{in-ref} loop clause that
1438 works much like @code{my-dolist}.
1442 @section Conditionals
1443 @cindex conditionals
1446 These conditional forms augment Emacs Lisp's simple @code{if},
1447 @code{and}, @code{or}, and @code{cond} forms.
1449 @defmac cl-case keyform clause@dots{}
1450 This macro evaluates @var{keyform}, then compares it with the key
1451 values listed in the various @var{clause}s. Whichever clause matches
1452 the key is executed; comparison is done by @code{eql}. If no clause
1453 matches, the @code{cl-case} form returns @code{nil}. The clauses are
1457 (@var{keylist} @var{body-forms}@dots{})
1461 where @var{keylist} is a list of key values. If there is exactly
1462 one value, and it is not a cons cell or the symbol @code{nil} or
1463 @code{t}, then it can be used by itself as a @var{keylist} without
1464 being enclosed in a list. All key values in the @code{cl-case} form
1465 must be distinct. The final clauses may use @code{t} in place of
1466 a @var{keylist} to indicate a default clause that should be taken
1467 if none of the other clauses match. (The symbol @code{otherwise}
1468 is also recognized in place of @code{t}. To make a clause that
1469 matches the actual symbol @code{t}, @code{nil}, or @code{otherwise},
1470 enclose the symbol in a list.)
1472 For example, this expression reads a keystroke, then does one of
1473 four things depending on whether it is an @samp{a}, a @samp{b},
1474 a @key{RET} or @kbd{C-j}, or anything else.
1477 (cl-case (read-char)
1480 ((?\r ?\n) (do-ret-thing))
1481 (t (do-other-thing)))
1485 @defmac cl-ecase keyform clause@dots{}
1486 This macro is just like @code{cl-case}, except that if the key does
1487 not match any of the clauses, an error is signaled rather than
1488 simply returning @code{nil}.
1491 @defmac cl-typecase keyform clause@dots{}
1492 This macro is a version of @code{cl-case} that checks for types
1493 rather than values. Each @var{clause} is of the form
1494 @samp{(@var{type} @var{body}@dots{})}. @xref{Type Predicates},
1495 for a description of type specifiers. For example,
1499 (integer (munch-integer x))
1500 (float (munch-float x))
1501 (string (munch-integer (string-to-number x)))
1502 (t (munch-anything x)))
1505 The type specifier @code{t} matches any type of object; the word
1506 @code{otherwise} is also allowed. To make one clause match any of
1507 several types, use an @code{(or @dots{})} type specifier.
1510 @defmac cl-etypecase keyform clause@dots{}
1511 This macro is just like @code{cl-typecase}, except that if the key does
1512 not match any of the clauses, an error is signaled rather than
1513 simply returning @code{nil}.
1516 @node Blocks and Exits
1517 @section Blocks and Exits
1522 Common Lisp @dfn{blocks} provide a non-local exit mechanism very
1523 similar to @code{catch} and @code{throw}, with lexical scoping.
1524 This package actually implements @code{cl-block}
1525 in terms of @code{catch}; however, the lexical scoping allows the
1526 byte-compiler to omit the costly @code{catch} step if the
1527 body of the block does not actually @code{cl-return-from} the block.
1529 @defmac cl-block name forms@dots{}
1530 The @var{forms} are evaluated as if by a @code{progn}. However,
1531 if any of the @var{forms} execute @code{(cl-return-from @var{name})},
1532 they will jump out and return directly from the @code{cl-block} form.
1533 The @code{cl-block} returns the result of the last @var{form} unless
1534 a @code{cl-return-from} occurs.
1536 The @code{cl-block}/@code{cl-return-from} mechanism is quite similar to
1537 the @code{catch}/@code{throw} mechanism. The main differences are
1538 that block @var{name}s are unevaluated symbols, rather than forms
1539 (such as quoted symbols) that evaluate to a tag at run-time; and
1540 also that blocks are always lexically scoped.
1541 In a dynamically scoped @code{catch}, functions called from the
1542 @code{catch} body can also @code{throw} to the @code{catch}. This
1543 is not an option for @code{cl-block}, where
1544 the @code{cl-return-from} referring to a block name must appear
1545 physically within the @var{forms} that make up the body of the block.
1546 They may not appear within other called functions, although they may
1547 appear within macro expansions or @code{lambda}s in the body. Block
1548 names and @code{catch} names form independent name-spaces.
1550 In true Common Lisp, @code{defun} and @code{defmacro} surround
1551 the function or expander bodies with implicit blocks with the
1552 same name as the function or macro. This does not occur in Emacs
1553 Lisp, but this package provides @code{cl-defun} and @code{cl-defmacro}
1554 forms, which do create the implicit block.
1556 The Common Lisp looping constructs defined by this package,
1557 such as @code{cl-loop} and @code{cl-dolist}, also create implicit blocks
1558 just as in Common Lisp.
1560 Because they are implemented in terms of Emacs Lisp's @code{catch}
1561 and @code{throw}, blocks have the same overhead as actual
1562 @code{catch} constructs (roughly two function calls). However,
1563 the byte compiler will optimize away the @code{catch}
1565 not in fact contain any @code{cl-return} or @code{cl-return-from} calls
1566 that jump to it. This means that @code{cl-do} loops and @code{cl-defun}
1567 functions that don't use @code{cl-return} don't pay the overhead to
1571 @defmac cl-return-from name [result]
1572 This macro returns from the block named @var{name}, which must be
1573 an (unevaluated) symbol. If a @var{result} form is specified, it
1574 is evaluated to produce the result returned from the @code{block}.
1575 Otherwise, @code{nil} is returned.
1578 @defmac cl-return [result]
1579 This macro is exactly like @code{(cl-return-from nil @var{result})}.
1580 Common Lisp loops like @code{cl-do} and @code{cl-dolist} implicitly enclose
1581 themselves in @code{nil} blocks.
1584 @c FIXME? Maybe this should be in a separate section?
1585 @defmac cl-tagbody &rest labels-or-statements
1586 This macro executes statements while allowing for control transfer to
1587 user-defined labels. Each element of @var{labels-or-statements} can
1588 be either a label (an integer or a symbol), or a cons-cell
1589 (a statement). This distinction is made before macroexpansion.
1590 Statements are executed in sequence, discarding any return value.
1591 Any statement can transfer control at any time to the statements that follow
1592 one of the labels with the special form @code{(go @var{label})}.
1593 Labels have lexical scope and dynamic extent.
1602 The macros described here provide more sophisticated, high-level
1603 looping constructs to complement Emacs Lisp's basic loop forms
1604 (@pxref{Iteration,,,elisp,GNU Emacs Lisp Reference Manual}).
1606 @defmac cl-loop forms@dots{}
1607 This package supports both the simple, old-style meaning of
1608 @code{loop} and the extremely powerful and flexible feature known as
1609 the @dfn{Loop Facility} or @dfn{Loop Macro}. This more advanced
1610 facility is discussed in the following section; @pxref{Loop Facility}.
1611 The simple form of @code{loop} is described here.
1613 If @code{cl-loop} is followed by zero or more Lisp expressions,
1614 then @code{(cl-loop @var{exprs}@dots{})} simply creates an infinite
1615 loop executing the expressions over and over. The loop is
1616 enclosed in an implicit @code{nil} block. Thus,
1619 (cl-loop (foo) (if (no-more) (return 72)) (bar))
1623 is exactly equivalent to
1626 (cl-block nil (while t (foo) (if (no-more) (return 72)) (bar)))
1629 If any of the expressions are plain symbols, the loop is instead
1630 interpreted as a Loop Macro specification as described later.
1631 (This is not a restriction in practice, since a plain symbol
1632 in the above notation would simply access and throw away the
1633 value of a variable.)
1636 @defmac cl-do (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
1637 This macro creates a general iterative loop. Each @var{spec} is
1641 (@var{var} [@var{init} [@var{step}]])
1644 The loop works as follows: First, each @var{var} is bound to the
1645 associated @var{init} value as if by a @code{let} form. Then, in
1646 each iteration of the loop, the @var{end-test} is evaluated; if
1647 true, the loop is finished. Otherwise, the body @var{forms} are
1648 evaluated, then each @var{var} is set to the associated @var{step}
1649 expression (as if by a @code{cl-psetq} form) and the next iteration
1650 begins. Once the @var{end-test} becomes true, the @var{result}
1651 forms are evaluated (with the @var{var}s still bound to their
1652 values) to produce the result returned by @code{cl-do}.
1654 The entire @code{cl-do} loop is enclosed in an implicit @code{nil}
1655 block, so that you can use @code{(cl-return)} to break out of the
1658 If there are no @var{result} forms, the loop returns @code{nil}.
1659 If a given @var{var} has no @var{step} form, it is bound to its
1660 @var{init} value but not otherwise modified during the @code{cl-do}
1661 loop (unless the code explicitly modifies it); this case is just
1662 a shorthand for putting a @code{(let ((@var{var} @var{init})) @dots{})}
1663 around the loop. If @var{init} is also omitted it defaults to
1664 @code{nil}, and in this case a plain @samp{@var{var}} can be used
1665 in place of @samp{(@var{var})}, again following the analogy with
1668 This example (from Steele) illustrates a loop that applies the
1669 function @code{f} to successive pairs of values from the lists
1670 @code{foo} and @code{bar}; it is equivalent to the call
1671 @code{(cl-mapcar 'f foo bar)}. Note that this loop has no body
1672 @var{forms} at all, performing all its work as side effects of
1673 the rest of the loop.
1676 (cl-do ((x foo (cdr x))
1678 (z nil (cons (f (car x) (car y)) z)))
1679 ((or (null x) (null y))
1684 @defmac cl-do* (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
1685 This is to @code{cl-do} what @code{let*} is to @code{let}. In
1686 particular, the initial values are bound as if by @code{let*}
1687 rather than @code{let}, and the steps are assigned as if by
1688 @code{setq} rather than @code{cl-psetq}.
1690 Here is another way to write the above loop:
1693 (cl-do* ((xp foo (cdr xp))
1695 (x (car xp) (car xp))
1696 (y (car yp) (car yp))
1698 ((or (null xp) (null yp))
1704 @defmac cl-dolist (var list [result]) forms@dots{}
1705 This is exactly like the standard Emacs Lisp macro @code{dolist},
1706 but surrounds the loop with an implicit @code{nil} block.
1709 @defmac cl-dotimes (var count [result]) forms@dots{}
1710 This is exactly like the standard Emacs Lisp macro @code{dotimes},
1711 but surrounds the loop with an implicit @code{nil} block.
1712 The body is executed with @var{var} bound to the integers
1713 from zero (inclusive) to @var{count} (exclusive), in turn. Then
1714 @c FIXME lispref does not state this part explicitly, could move this there.
1715 the @code{result} form is evaluated with @var{var} bound to the total
1716 number of iterations that were done (i.e., @code{(max 0 @var{count})})
1717 to get the return value for the loop form.
1720 @defmac cl-do-symbols (var [obarray [result]]) forms@dots{}
1721 This loop iterates over all interned symbols. If @var{obarray}
1722 is specified and is not @code{nil}, it loops over all symbols in
1723 that obarray. For each symbol, the body @var{forms} are evaluated
1724 with @var{var} bound to that symbol. The symbols are visited in
1725 an unspecified order. Afterward the @var{result} form, if any,
1726 is evaluated (with @var{var} bound to @code{nil}) to get the return
1727 value. The loop is surrounded by an implicit @code{nil} block.
1730 @defmac cl-do-all-symbols (var [result]) forms@dots{}
1731 This is identical to @code{cl-do-symbols} except that the @var{obarray}
1732 argument is omitted; it always iterates over the default obarray.
1735 @xref{Mapping over Sequences}, for some more functions for
1736 iterating over vectors or lists.
1739 @section Loop Facility
1740 @cindex loop facility
1743 A common complaint with Lisp's traditional looping constructs was
1744 that they were either too simple and limited, such as @code{dotimes}
1745 or @code{while}, or too unreadable and obscure, like Common Lisp's
1748 To remedy this, Common Lisp added a construct called the ``Loop
1749 Facility'' or ``@code{loop} macro'', with an easy-to-use but very
1750 powerful and expressive syntax.
1753 * Loop Basics:: The @code{cl-loop} macro, basic clause structure.
1754 * Loop Examples:: Working examples of the @code{cl-loop} macro.
1755 * For Clauses:: Clauses introduced by @code{for} or @code{as}.
1756 * Iteration Clauses:: @code{repeat}, @code{while}, @code{thereis}, etc.
1757 * Accumulation Clauses:: @code{collect}, @code{sum}, @code{maximize}, etc.
1758 * Other Clauses:: @code{with}, @code{if}, @code{initially}, @code{finally}.
1762 @subsection Loop Basics
1765 The @code{cl-loop} macro essentially creates a mini-language within
1766 Lisp that is specially tailored for describing loops. While this
1767 language is a little strange-looking by the standards of regular Lisp,
1768 it turns out to be very easy to learn and well-suited to its purpose.
1770 Since @code{cl-loop} is a macro, all parsing of the loop language
1771 takes place at byte-compile time; compiled @code{cl-loop}s are just
1772 as efficient as the equivalent @code{while} loops written longhand.
1774 @defmac cl-loop clauses@dots{}
1775 A loop construct consists of a series of @var{clause}s, each
1776 introduced by a symbol like @code{for} or @code{do}. Clauses
1777 are simply strung together in the argument list of @code{cl-loop},
1778 with minimal extra parentheses. The various types of clauses
1779 specify initializations, such as the binding of temporary
1780 variables, actions to be taken in the loop, stepping actions,
1783 Common Lisp specifies a certain general order of clauses in a
1787 (loop @var{name-clause}
1788 @var{var-clauses}@dots{}
1789 @var{action-clauses}@dots{})
1792 The @var{name-clause} optionally gives a name to the implicit
1793 block that surrounds the loop. By default, the implicit block
1794 is named @code{nil}. The @var{var-clauses} specify what
1795 variables should be bound during the loop, and how they should
1796 be modified or iterated throughout the course of the loop. The
1797 @var{action-clauses} are things to be done during the loop, such
1798 as computing, collecting, and returning values.
1800 The Emacs version of the @code{cl-loop} macro is less restrictive about
1801 the order of clauses, but things will behave most predictably if
1802 you put the variable-binding clauses @code{with}, @code{for}, and
1803 @code{repeat} before the action clauses. As in Common Lisp,
1804 @code{initially} and @code{finally} clauses can go anywhere.
1806 Loops generally return @code{nil} by default, but you can cause
1807 them to return a value by using an accumulation clause like
1808 @code{collect}, an end-test clause like @code{always}, or an
1809 explicit @code{return} clause to jump out of the implicit block.
1810 (Because the loop body is enclosed in an implicit block, you can
1811 also use regular Lisp @code{cl-return} or @code{cl-return-from} to
1812 break out of the loop.)
1815 The following sections give some examples of the loop macro in
1816 action, and describe the particular loop clauses in great detail.
1817 Consult the second edition of Steele for additional discussion
1821 @subsection Loop Examples
1824 Before listing the full set of clauses that are allowed, let's
1825 look at a few example loops just to get a feel for the @code{cl-loop}
1829 (cl-loop for buf in (buffer-list)
1830 collect (buffer-file-name buf))
1834 This loop iterates over all Emacs buffers, using the list
1835 returned by @code{buffer-list}. For each buffer @var{buf},
1836 it calls @code{buffer-file-name} and collects the results into
1837 a list, which is then returned from the @code{cl-loop} construct.
1838 The result is a list of the file names of all the buffers in
1839 Emacs's memory. The words @code{for}, @code{in}, and @code{collect}
1840 are reserved words in the @code{cl-loop} language.
1843 (cl-loop repeat 20 do (insert "Yowsa\n"))
1847 This loop inserts the phrase ``Yowsa'' twenty times in the
1851 (cl-loop until (eobp) do (munch-line) (forward-line 1))
1855 This loop calls @code{munch-line} on every line until the end
1856 of the buffer. If point is already at the end of the buffer,
1857 the loop exits immediately.
1860 (cl-loop do (munch-line) until (eobp) do (forward-line 1))
1864 This loop is similar to the above one, except that @code{munch-line}
1865 is always called at least once.
1868 (cl-loop for x from 1 to 100
1871 finally return (list x (= y 729)))
1875 This more complicated loop searches for a number @code{x} whose
1876 square is 729. For safety's sake it only examines @code{x}
1877 values up to 100; dropping the phrase @samp{to 100} would
1878 cause the loop to count upwards with no limit. The second
1879 @code{for} clause defines @code{y} to be the square of @code{x}
1880 within the loop; the expression after the @code{=} sign is
1881 reevaluated each time through the loop. The @code{until}
1882 clause gives a condition for terminating the loop, and the
1883 @code{finally} clause says what to do when the loop finishes.
1884 (This particular example was written less concisely than it
1885 could have been, just for the sake of illustration.)
1887 Note that even though this loop contains three clauses (two
1888 @code{for}s and an @code{until}) that would have been enough to
1889 define loops all by themselves, it still creates a single loop
1890 rather than some sort of triple-nested loop. You must explicitly
1891 nest your @code{cl-loop} constructs if you want nested loops.
1894 @subsection For Clauses
1897 Most loops are governed by one or more @code{for} clauses.
1898 A @code{for} clause simultaneously describes variables to be
1899 bound, how those variables are to be stepped during the loop,
1900 and usually an end condition based on those variables.
1902 The word @code{as} is a synonym for the word @code{for}. This
1903 word is followed by a variable name, then a word like @code{from}
1904 or @code{across} that describes the kind of iteration desired.
1905 In Common Lisp, the phrase @code{being the} sometimes precedes
1906 the type of iteration; in this package both @code{being} and
1907 @code{the} are optional. The word @code{each} is a synonym
1908 for @code{the}, and the word that follows it may be singular
1909 or plural: @samp{for x being the elements of y} or
1910 @samp{for x being each element of y}. Which form you use
1911 is purely a matter of style.
1913 The variable is bound around the loop as if by @code{let}:
1917 (cl-loop for i from 1 to 10 do (do-something-with i))
1923 @item for @var{var} from @var{expr1} to @var{expr2} by @var{expr3}
1924 This type of @code{for} clause creates a counting loop. Each of
1925 the three sub-terms is optional, though there must be at least one
1926 term so that the clause is marked as a counting clause.
1928 The three expressions are the starting value, the ending value, and
1929 the step value, respectively, of the variable. The loop counts
1930 upwards by default (@var{expr3} must be positive), from @var{expr1}
1931 to @var{expr2} inclusively. If you omit the @code{from} term, the
1932 loop counts from zero; if you omit the @code{to} term, the loop
1933 counts forever without stopping (unless stopped by some other
1934 loop clause, of course); if you omit the @code{by} term, the loop
1935 counts in steps of one.
1937 You can replace the word @code{from} with @code{upfrom} or
1938 @code{downfrom} to indicate the direction of the loop. Likewise,
1939 you can replace @code{to} with @code{upto} or @code{downto}.
1940 For example, @samp{for x from 5 downto 1} executes five times
1941 with @code{x} taking on the integers from 5 down to 1 in turn.
1942 Also, you can replace @code{to} with @code{below} or @code{above},
1943 which are like @code{upto} and @code{downto} respectively except
1944 that they are exclusive rather than inclusive limits:
1947 (cl-loop for x to 10 collect x)
1948 @result{} (0 1 2 3 4 5 6 7 8 9 10)
1949 (cl-loop for x below 10 collect x)
1950 @result{} (0 1 2 3 4 5 6 7 8 9)
1953 The @code{by} value is always positive, even for downward-counting
1954 loops. Some sort of @code{from} value is required for downward
1955 loops; @samp{for x downto 5} is not a valid loop clause all by
1958 @item for @var{var} in @var{list} by @var{function}
1959 This clause iterates @var{var} over all the elements of @var{list},
1960 in turn. If you specify the @code{by} term, then @var{function}
1961 is used to traverse the list instead of @code{cdr}; it must be a
1962 function taking one argument. For example:
1965 (cl-loop for x in '(1 2 3 4 5 6) collect (* x x))
1966 @result{} (1 4 9 16 25 36)
1967 (cl-loop for x in '(1 2 3 4 5 6) by 'cddr collect (* x x))
1971 @item for @var{var} on @var{list} by @var{function}
1972 This clause iterates @var{var} over all the cons cells of @var{list}.
1975 (cl-loop for x on '(1 2 3 4) collect x)
1976 @result{} ((1 2 3 4) (2 3 4) (3 4) (4))
1979 @item for @var{var} in-ref @var{list} by @var{function}
1980 This is like a regular @code{in} clause, but @var{var} becomes
1981 a @code{setf}-able ``reference'' onto the elements of the list
1982 rather than just a temporary variable. For example,
1985 (cl-loop for x in-ref my-list do (cl-incf x))
1989 increments every element of @code{my-list} in place. This clause
1990 is an extension to standard Common Lisp.
1992 @item for @var{var} across @var{array}
1993 This clause iterates @var{var} over all the elements of @var{array},
1994 which may be a vector or a string.
1997 (cl-loop for x across "aeiou"
1998 do (use-vowel (char-to-string x)))
2001 @item for @var{var} across-ref @var{array}
2002 This clause iterates over an array, with @var{var} a @code{setf}-able
2003 reference onto the elements; see @code{in-ref} above.
2005 @item for @var{var} being the elements of @var{sequence}
2006 This clause iterates over the elements of @var{sequence}, which may
2007 be a list, vector, or string. Since the type must be determined
2008 at run-time, this is somewhat less efficient than @code{in} or
2009 @code{across}. The clause may be followed by the additional term
2010 @samp{using (index @var{var2})} to cause @var{var2} to be bound to
2011 the successive indices (starting at 0) of the elements.
2013 This clause type is taken from older versions of the @code{loop} macro,
2014 and is not present in modern Common Lisp. The @samp{using (sequence @dots{})}
2015 term of the older macros is not supported.
2017 @item for @var{var} being the elements of-ref @var{sequence}
2018 This clause iterates over a sequence, with @var{var} a @code{setf}-able
2019 reference onto the elements; see @code{in-ref} above.
2021 @item for @var{var} being the symbols [of @var{obarray}]
2022 This clause iterates over symbols, either over all interned symbols
2023 or over all symbols in @var{obarray}. The loop is executed with
2024 @var{var} bound to each symbol in turn. The symbols are visited in
2025 an unspecified order.
2030 (cl-loop for sym being the symbols
2032 when (string-match "^map" (symbol-name sym))
2037 returns a list of all the functions whose names begin with @samp{map}.
2039 The Common Lisp words @code{external-symbols} and @code{present-symbols}
2040 are also recognized but are equivalent to @code{symbols} in Emacs Lisp.
2042 Due to a minor implementation restriction, it will not work to have
2043 more than one @code{for} clause iterating over symbols, hash tables,
2044 keymaps, overlays, or intervals in a given @code{cl-loop}. Fortunately,
2045 it would rarely if ever be useful to do so. It @emph{is} valid to mix
2046 one of these types of clauses with other clauses like @code{for @dots{} to}
2049 @item for @var{var} being the hash-keys of @var{hash-table}
2050 @itemx for @var{var} being the hash-values of @var{hash-table}
2051 This clause iterates over the entries in @var{hash-table} with
2052 @var{var} bound to each key, or value. A @samp{using} clause can bind
2053 a second variable to the opposite part.
2056 (cl-loop for k being the hash-keys of h
2057 using (hash-values v)
2059 (message "key %S -> value %S" k v))
2062 @item for @var{var} being the key-codes of @var{keymap}
2063 @itemx for @var{var} being the key-bindings of @var{keymap}
2064 This clause iterates over the entries in @var{keymap}.
2065 The iteration does not enter nested keymaps but does enter inherited
2067 A @code{using} clause can access both the codes and the bindings
2071 (cl-loop for c being the key-codes of (current-local-map)
2072 using (key-bindings b)
2074 (message "key %S -> binding %S" c b))
2078 @item for @var{var} being the key-seqs of @var{keymap}
2079 This clause iterates over all key sequences defined by @var{keymap}
2080 and its nested keymaps, where @var{var} takes on values which are
2081 vectors. The strings or vectors
2082 are reused for each iteration, so you must copy them if you wish to keep
2083 them permanently. You can add a @samp{using (key-bindings @dots{})}
2084 clause to get the command bindings as well.
2086 @item for @var{var} being the overlays [of @var{buffer}] @dots{}
2087 This clause iterates over the ``overlays'' of a buffer
2088 (the clause @code{extents} is synonymous
2089 with @code{overlays}). If the @code{of} term is omitted, the current
2091 This clause also accepts optional @samp{from @var{pos}} and
2092 @samp{to @var{pos}} terms, limiting the clause to overlays which
2093 overlap the specified region.
2095 @item for @var{var} being the intervals [of @var{buffer}] @dots{}
2096 This clause iterates over all intervals of a buffer with constant
2097 text properties. The variable @var{var} will be bound to conses
2098 of start and end positions, where one start position is always equal
2099 to the previous end position. The clause allows @code{of},
2100 @code{from}, @code{to}, and @code{property} terms, where the latter
2101 term restricts the search to just the specified property. The
2102 @code{of} term may specify either a buffer or a string.
2104 @item for @var{var} being the frames
2105 This clause iterates over all Emacs frames. The clause @code{screens} is
2106 a synonym for @code{frames}. The frames are visited in
2107 @code{next-frame} order starting from @code{selected-frame}.
2109 @item for @var{var} being the windows [of @var{frame}]
2110 This clause iterates over the windows (in the Emacs sense) of
2111 the current frame, or of the specified @var{frame}. It visits windows
2112 in @code{next-window} order starting from @code{selected-window}
2113 (or @code{frame-selected-window} if you specify @var{frame}).
2114 This clause treats the minibuffer window in the same way as
2115 @code{next-window} does. For greater flexibility, consider using
2116 @code{walk-windows} instead.
2118 @item for @var{var} being the buffers
2119 This clause iterates over all buffers in Emacs. It is equivalent
2120 to @samp{for @var{var} in (buffer-list)}.
2122 @item for @var{var} = @var{expr1} then @var{expr2}
2123 This clause does a general iteration. The first time through
2124 the loop, @var{var} will be bound to @var{expr1}. On the second
2125 and successive iterations it will be set by evaluating @var{expr2}
2126 (which may refer to the old value of @var{var}). For example,
2127 these two loops are effectively the same:
2130 (cl-loop for x on my-list by 'cddr do @dots{})
2131 (cl-loop for x = my-list then (cddr x) while x do @dots{})
2134 Note that this type of @code{for} clause does not imply any sort
2135 of terminating condition; the above example combines it with a
2136 @code{while} clause to tell when to end the loop.
2138 If you omit the @code{then} term, @var{expr1} is used both for
2139 the initial setting and for successive settings:
2142 (cl-loop for x = (random) when (> x 0) return x)
2146 This loop keeps taking random numbers from the @code{(random)}
2147 function until it gets a positive one, which it then returns.
2150 If you include several @code{for} clauses in a row, they are
2151 treated sequentially (as if by @code{let*} and @code{setq}).
2152 You can instead use the word @code{and} to link the clauses,
2153 in which case they are processed in parallel (as if by @code{let}
2154 and @code{cl-psetq}).
2157 (cl-loop for x below 5 for y = nil then x collect (list x y))
2158 @result{} ((0 nil) (1 1) (2 2) (3 3) (4 4))
2159 (cl-loop for x below 5 and y = nil then x collect (list x y))
2160 @result{} ((0 nil) (1 0) (2 1) (3 2) (4 3))
2164 In the first loop, @code{y} is set based on the value of @code{x}
2165 that was just set by the previous clause; in the second loop,
2166 @code{x} and @code{y} are set simultaneously so @code{y} is set
2167 based on the value of @code{x} left over from the previous time
2170 @cindex destructuring, in cl-loop
2171 Another feature of the @code{cl-loop} macro is @emph{destructuring},
2172 similar in concept to the destructuring provided by @code{defmacro}
2173 (@pxref{Argument Lists}).
2174 The @var{var} part of any @code{for} clause can be given as a list
2175 of variables instead of a single variable. The values produced
2176 during loop execution must be lists; the values in the lists are
2177 stored in the corresponding variables.
2180 (cl-loop for (x y) in '((2 3) (4 5) (6 7)) collect (+ x y))
2184 In loop destructuring, if there are more values than variables
2185 the trailing values are ignored, and if there are more variables
2186 than values the trailing variables get the value @code{nil}.
2187 If @code{nil} is used as a variable name, the corresponding
2188 values are ignored. Destructuring may be nested, and dotted
2189 lists of variables like @code{(x . y)} are allowed, so for example
2193 (cl-loop for (key . value) in '((a . 1) (b . 2))
2198 @node Iteration Clauses
2199 @subsection Iteration Clauses
2202 Aside from @code{for} clauses, there are several other loop clauses
2203 that control the way the loop operates. They might be used by
2204 themselves, or in conjunction with one or more @code{for} clauses.
2207 @item repeat @var{integer}
2208 This clause simply counts up to the specified number using an
2209 internal temporary variable. The loops
2212 (cl-loop repeat (1+ n) do @dots{})
2213 (cl-loop for temp to n do @dots{})
2217 are identical except that the second one forces you to choose
2218 a name for a variable you aren't actually going to use.
2220 @item while @var{condition}
2221 This clause stops the loop when the specified condition (any Lisp
2222 expression) becomes @code{nil}. For example, the following two
2223 loops are equivalent, except for the implicit @code{nil} block
2224 that surrounds the second one:
2227 (while @var{cond} @var{forms}@dots{})
2228 (cl-loop while @var{cond} do @var{forms}@dots{})
2231 @item until @var{condition}
2232 This clause stops the loop when the specified condition is true,
2233 i.e., non-@code{nil}.
2235 @item always @var{condition}
2236 This clause stops the loop when the specified condition is @code{nil}.
2237 Unlike @code{while}, it stops the loop using @code{return nil} so that
2238 the @code{finally} clauses are not executed. If all the conditions
2239 were non-@code{nil}, the loop returns @code{t}:
2242 (if (cl-loop for size in size-list always (> size 10))
2247 @item never @var{condition}
2248 This clause is like @code{always}, except that the loop returns
2249 @code{t} if any conditions were false, or @code{nil} otherwise.
2251 @item thereis @var{condition}
2252 This clause stops the loop when the specified form is non-@code{nil};
2253 in this case, it returns that non-@code{nil} value. If all the
2254 values were @code{nil}, the loop returns @code{nil}.
2256 @item iter-by @var{iterator}
2257 This clause iterates over the values from the specified form, an
2258 iterator object. See (@pxref{Generators,,,elisp,GNU Emacs Lisp
2262 @node Accumulation Clauses
2263 @subsection Accumulation Clauses
2266 These clauses cause the loop to accumulate information about the
2267 specified Lisp @var{form}. The accumulated result is returned
2268 from the loop unless overridden, say, by a @code{return} clause.
2271 @item collect @var{form}
2272 This clause collects the values of @var{form} into a list. Several
2273 examples of @code{collect} appear elsewhere in this manual.
2275 The word @code{collecting} is a synonym for @code{collect}, and
2276 likewise for the other accumulation clauses.
2278 @item append @var{form}
2279 This clause collects lists of values into a result list using
2282 @item nconc @var{form}
2283 This clause collects lists of values into a result list by
2284 destructively modifying the lists rather than copying them.
2286 @item concat @var{form}
2287 This clause concatenates the values of the specified @var{form}
2288 into a string. (It and the following clause are extensions to
2289 standard Common Lisp.)
2291 @item vconcat @var{form}
2292 This clause concatenates the values of the specified @var{form}
2295 @item count @var{form}
2296 This clause counts the number of times the specified @var{form}
2297 evaluates to a non-@code{nil} value.
2299 @item sum @var{form}
2300 This clause accumulates the sum of the values of the specified
2301 @var{form}, which must evaluate to a number.
2303 @item maximize @var{form}
2304 This clause accumulates the maximum value of the specified @var{form},
2305 which must evaluate to a number. The return value is undefined if
2306 @code{maximize} is executed zero times.
2308 @item minimize @var{form}
2309 This clause accumulates the minimum value of the specified @var{form}.
2312 Accumulation clauses can be followed by @samp{into @var{var}} to
2313 cause the data to be collected into variable @var{var} (which is
2314 automatically @code{let}-bound during the loop) rather than an
2315 unnamed temporary variable. Also, @code{into} accumulations do
2316 not automatically imply a return value. The loop must use some
2317 explicit mechanism, such as @code{finally return}, to return
2318 the accumulated result.
2320 It is valid for several accumulation clauses of the same type to
2321 accumulate into the same place. From Steele:
2324 (cl-loop for name in '(fred sue alice joe june)
2325 for kids in '((bob ken) () () (kris sunshine) ())
2328 @result{} (fred bob ken sue alice joe kris sunshine june)
2332 @subsection Other Clauses
2335 This section describes the remaining loop clauses.
2338 @item with @var{var} = @var{value}
2339 This clause binds a variable to a value around the loop, but
2340 otherwise leaves the variable alone during the loop. The following
2341 loops are basically equivalent:
2344 (cl-loop with x = 17 do @dots{})
2345 (let ((x 17)) (cl-loop do @dots{}))
2346 (cl-loop for x = 17 then x do @dots{})
2349 Naturally, the variable @var{var} might be used for some purpose
2350 in the rest of the loop. For example:
2353 (cl-loop for x in my-list with res = nil do (push x res)
2357 This loop inserts the elements of @code{my-list} at the front of
2358 a new list being accumulated in @code{res}, then returns the
2359 list @code{res} at the end of the loop. The effect is similar
2360 to that of a @code{collect} clause, but the list gets reversed
2361 by virtue of the fact that elements are being pushed onto the
2362 front of @code{res} rather than the end.
2364 If you omit the @code{=} term, the variable is initialized to
2365 @code{nil}. (Thus the @samp{= nil} in the above example is
2368 Bindings made by @code{with} are sequential by default, as if
2369 by @code{let*}. Just like @code{for} clauses, @code{with} clauses
2370 can be linked with @code{and} to cause the bindings to be made by
2373 @item if @var{condition} @var{clause}
2374 This clause executes the following loop clause only if the specified
2375 condition is true. The following @var{clause} should be an accumulation,
2376 @code{do}, @code{return}, @code{if}, or @code{unless} clause.
2377 Several clauses may be linked by separating them with @code{and}.
2378 These clauses may be followed by @code{else} and a clause or clauses
2379 to execute if the condition was false. The whole construct may
2380 optionally be followed by the word @code{end} (which may be used to
2381 disambiguate an @code{else} or @code{and} in a nested @code{if}).
2383 The actual non-@code{nil} value of the condition form is available
2384 by the name @code{it} in the ``then'' part. For example:
2387 (setq funny-numbers '(6 13 -1))
2389 (cl-loop for x below 10
2392 and if (memq x funny-numbers) return (cdr it) end
2394 collect x into evens
2395 finally return (vector odds evens))
2396 @result{} [(1 3 5 7 9) (0 2 4 6 8)]
2397 (setq funny-numbers '(6 7 13 -1))
2398 @result{} (6 7 13 -1)
2399 (cl-loop <@r{same thing again}>)
2403 Note the use of @code{and} to put two clauses into the ``then''
2404 part, one of which is itself an @code{if} clause. Note also that
2405 @code{end}, while normally optional, was necessary here to make
2406 it clear that the @code{else} refers to the outermost @code{if}
2407 clause. In the first case, the loop returns a vector of lists
2408 of the odd and even values of @var{x}. In the second case, the
2409 odd number 7 is one of the @code{funny-numbers} so the loop
2410 returns early; the actual returned value is based on the result
2411 of the @code{memq} call.
2413 @item when @var{condition} @var{clause}
2414 This clause is just a synonym for @code{if}.
2416 @item unless @var{condition} @var{clause}
2417 The @code{unless} clause is just like @code{if} except that the
2418 sense of the condition is reversed.
2420 @item named @var{name}
2421 This clause gives a name other than @code{nil} to the implicit
2422 block surrounding the loop. The @var{name} is the symbol to be
2423 used as the block name.
2425 @item initially [do] @var{forms}@dots{}
2426 This keyword introduces one or more Lisp forms which will be
2427 executed before the loop itself begins (but after any variables
2428 requested by @code{for} or @code{with} have been bound to their
2429 initial values). @code{initially} clauses can appear anywhere;
2430 if there are several, they are executed in the order they appear
2431 in the loop. The keyword @code{do} is optional.
2433 @item finally [do] @var{forms}@dots{}
2434 This introduces Lisp forms which will be executed after the loop
2435 finishes (say, on request of a @code{for} or @code{while}).
2436 @code{initially} and @code{finally} clauses may appear anywhere
2437 in the loop construct, but they are executed (in the specified
2438 order) at the beginning or end, respectively, of the loop.
2440 @item finally return @var{form}
2441 This says that @var{form} should be executed after the loop
2442 is done to obtain a return value. (Without this, or some other
2443 clause like @code{collect} or @code{return}, the loop will simply
2444 return @code{nil}.) Variables bound by @code{for}, @code{with},
2445 or @code{into} will still contain their final values when @var{form}
2448 @item do @var{forms}@dots{}
2449 The word @code{do} may be followed by any number of Lisp expressions
2450 which are executed as an implicit @code{progn} in the body of the
2451 loop. Many of the examples in this section illustrate the use of
2454 @item return @var{form}
2455 This clause causes the loop to return immediately. The following
2456 Lisp form is evaluated to give the return value of the loop
2457 form. The @code{finally} clauses, if any, are not executed.
2458 Of course, @code{return} is generally used inside an @code{if} or
2459 @code{unless}, as its use in a top-level loop clause would mean
2460 the loop would never get to ``loop'' more than once.
2462 The clause @samp{return @var{form}} is equivalent to
2463 @samp{do (cl-return @var{form})} (or @code{cl-return-from} if the loop
2464 was named). The @code{return} clause is implemented a bit more
2465 efficiently, though.
2468 While there is no high-level way to add user extensions to @code{cl-loop},
2469 this package does offer two properties called @code{cl-loop-handler}
2470 and @code{cl-loop-for-handler} which are functions to be called when a
2471 given symbol is encountered as a top-level loop clause or @code{for}
2472 clause, respectively. Consult the source code in file
2473 @file{cl-macs.el} for details.
2475 This package's @code{cl-loop} macro is compatible with that of Common
2476 Lisp, except that a few features are not implemented: @code{loop-finish}
2477 and data-type specifiers. Naturally, the @code{for} clauses that
2478 iterate over keymaps, overlays, intervals, frames, windows, and
2479 buffers are Emacs-specific extensions.
2481 @node Multiple Values
2482 @section Multiple Values
2483 @cindex multiple values
2486 Common Lisp functions can return zero or more results. Emacs Lisp
2487 functions, by contrast, always return exactly one result. This
2488 package makes no attempt to emulate Common Lisp multiple return
2489 values; Emacs versions of Common Lisp functions that return more
2490 than one value either return just the first value (as in
2491 @code{cl-compiler-macroexpand}) or return a list of values.
2492 This package @emph{does} define placeholders
2493 for the Common Lisp functions that work with multiple values, but
2494 in Emacs Lisp these functions simply operate on lists instead.
2495 The @code{cl-values} form, for example, is a synonym for @code{list}
2498 @defmac cl-multiple-value-bind (var@dots{}) values-form forms@dots{}
2499 This form evaluates @var{values-form}, which must return a list of
2500 values. It then binds the @var{var}s to these respective values,
2501 as if by @code{let}, and then executes the body @var{forms}.
2502 If there are more @var{var}s than values, the extra @var{var}s
2503 are bound to @code{nil}. If there are fewer @var{var}s than
2504 values, the excess values are ignored.
2507 @defmac cl-multiple-value-setq (var@dots{}) form
2508 This form evaluates @var{form}, which must return a list of values.
2509 It then sets the @var{var}s to these respective values, as if by
2510 @code{setq}. Extra @var{var}s or values are treated the same as
2511 in @code{cl-multiple-value-bind}.
2514 Since a perfect emulation is not feasible in Emacs Lisp, this
2515 package opts to keep it as simple and predictable as possible.
2521 This package implements the various Common Lisp features of
2522 @code{defmacro}, such as destructuring, @code{&environment},
2523 and @code{&body}. Top-level @code{&whole} is not implemented
2524 for @code{defmacro} due to technical difficulties.
2525 @xref{Argument Lists}.
2527 Destructuring is made available to the user by way of the
2530 @defmac cl-destructuring-bind arglist expr forms@dots{}
2531 This macro expands to code that executes @var{forms}, with
2532 the variables in @var{arglist} bound to the list of values
2533 returned by @var{expr}. The @var{arglist} can include all
2534 the features allowed for @code{cl-defmacro} argument lists,
2535 including destructuring. (The @code{&environment} keyword
2536 is not allowed.) The macro expansion will signal an error
2537 if @var{expr} returns a list of the wrong number of arguments
2538 or with incorrect keyword arguments.
2541 @cindex compiler macros
2542 @cindex define compiler macros
2543 This package also includes the Common Lisp @code{define-compiler-macro}
2544 facility, which allows you to define compile-time expansions and
2545 optimizations for your functions.
2547 @defmac cl-define-compiler-macro name arglist forms@dots{}
2548 This form is similar to @code{defmacro}, except that it only expands
2549 calls to @var{name} at compile-time; calls processed by the Lisp
2550 interpreter are not expanded, nor are they expanded by the
2551 @code{macroexpand} function.
2553 The argument list may begin with a @code{&whole} keyword and a
2554 variable. This variable is bound to the macro-call form itself,
2555 i.e., to a list of the form @samp{(@var{name} @var{args}@dots{})}.
2556 If the macro expander returns this form unchanged, then the
2557 compiler treats it as a normal function call. This allows
2558 compiler macros to work as optimizers for special cases of a
2559 function, leaving complicated cases alone.
2561 For example, here is a simplified version of a definition that
2562 appears as a standard part of this package:
2565 (cl-define-compiler-macro cl-member (&whole form a list &rest keys)
2566 (if (and (null keys)
2567 (eq (car-safe a) 'quote)
2568 (not (floatp (cadr a))))
2574 This definition causes @code{(cl-member @var{a} @var{list})} to change
2575 to a call to the faster @code{memq} in the common case where @var{a}
2576 is a non-floating-point constant; if @var{a} is anything else, or
2577 if there are any keyword arguments in the call, then the original
2578 @code{cl-member} call is left intact. (The actual compiler macro
2579 for @code{cl-member} optimizes a number of other cases, including
2580 common @code{:test} predicates.)
2583 @defun cl-compiler-macroexpand form
2584 This function is analogous to @code{macroexpand}, except that it
2585 expands compiler macros rather than regular macros. It returns
2586 @var{form} unchanged if it is not a call to a function for which
2587 a compiler macro has been defined, or if that compiler macro
2588 decided to punt by returning its @code{&whole} argument. Like
2589 @code{macroexpand}, it expands repeatedly until it reaches a form
2590 for which no further expansion is possible.
2593 @xref{Macro Bindings}, for descriptions of the @code{cl-macrolet}
2594 and @code{cl-symbol-macrolet} forms for making ``local'' macro
2598 @chapter Declarations
2601 Common Lisp includes a complex and powerful ``declaration''
2602 mechanism that allows you to give the compiler special hints
2603 about the types of data that will be stored in particular variables,
2604 and about the ways those variables and functions will be used. This
2605 package defines versions of all the Common Lisp declaration forms:
2606 @code{declare}, @code{locally}, @code{proclaim}, @code{declaim},
2609 Most of the Common Lisp declarations are not currently useful in Emacs
2610 Lisp. For example, the byte-code system provides little
2611 opportunity to benefit from type information.
2613 and @code{special} declarations are redundant in a fully
2614 dynamically-scoped Lisp.
2616 A few declarations are meaningful when byte compiler optimizations
2617 are enabled, as they are by the default. Otherwise these
2618 declarations will effectively be ignored.
2620 @defun cl-proclaim decl-spec
2621 This function records a ``global'' declaration specified by
2622 @var{decl-spec}. Since @code{cl-proclaim} is a function, @var{decl-spec}
2623 is evaluated and thus should normally be quoted.
2626 @defmac cl-declaim decl-specs@dots{}
2627 This macro is like @code{cl-proclaim}, except that it takes any number
2628 of @var{decl-spec} arguments, and the arguments are unevaluated and
2629 unquoted. The @code{cl-declaim} macro also puts @code{(cl-eval-when
2630 (compile load eval) @dots{})} around the declarations so that they will
2631 be registered at compile-time as well as at run-time. (This is vital,
2632 since normally the declarations are meant to influence the way the
2633 compiler treats the rest of the file that contains the @code{cl-declaim}
2637 @defmac cl-declare decl-specs@dots{}
2638 This macro is used to make declarations within functions and other
2639 code. Common Lisp allows declarations in various locations, generally
2640 at the beginning of any of the many ``implicit @code{progn}s''
2641 throughout Lisp syntax, such as function bodies, @code{let} bodies,
2642 etc. Currently the only declaration understood by @code{cl-declare}
2646 @defmac cl-locally declarations@dots{} forms@dots{}
2647 In this package, @code{cl-locally} is no different from @code{progn}.
2650 @defmac cl-the type form
2651 @code{cl-the} returns the value of @code{form}, first checking (if
2652 optimization settings permit) that it is of type @code{type}. Future
2653 byte-compiler optimizations may also make use of this information to
2654 improve runtime efficiency.
2656 For example, @code{mapcar} can map over both lists and arrays. It is
2657 hard for the compiler to expand @code{mapcar} into an in-line loop
2658 unless it knows whether the sequence will be a list or an array ahead
2659 of time. With @code{(mapcar 'car (cl-the vector foo))}, a future
2660 compiler would have enough information to expand the loop in-line.
2661 For now, Emacs Lisp will treat the above code as exactly equivalent
2662 to @code{(mapcar 'car foo)}.
2665 Each @var{decl-spec} in a @code{cl-proclaim}, @code{cl-declaim}, or
2666 @code{cl-declare} should be a list beginning with a symbol that says
2667 what kind of declaration it is. This package currently understands
2668 @code{special}, @code{inline}, @code{notinline}, @code{optimize},
2669 and @code{warn} declarations. (The @code{warn} declaration is an
2670 extension of standard Common Lisp.) Other Common Lisp declarations,
2671 such as @code{type} and @code{ftype}, are silently ignored.
2676 Since all variables in Emacs Lisp are ``special'' (in the Common
2677 Lisp sense), @code{special} declarations are only advisory. They
2678 simply tell the byte compiler that the specified
2679 variables are intentionally being referred to without being
2680 bound in the body of the function. The compiler normally emits
2681 warnings for such references, since they could be typographical
2682 errors for references to local variables.
2684 The declaration @code{(cl-declare (special @var{var1} @var{var2}))} is
2685 equivalent to @code{(defvar @var{var1}) (defvar @var{var2})}.
2687 In top-level contexts, it is generally better to write
2688 @code{(defvar @var{var})} than @code{(cl-declaim (special @var{var}))},
2689 since @code{defvar} makes your intentions clearer.
2692 The @code{inline} @var{decl-spec} lists one or more functions
2693 whose bodies should be expanded ``in-line'' into calling functions
2694 whenever the compiler is able to arrange for it. For example,
2695 the function @code{cl-acons} is declared @code{inline}
2696 by this package so that the form @code{(cl-acons @var{key} @var{value}
2698 expand directly into @code{(cons (cons @var{key} @var{value}) @var{alist})}
2699 when it is called in user functions, so as to save function calls.
2701 The following declarations are all equivalent. Note that the
2702 @code{defsubst} form is a convenient way to define a function
2703 and declare it inline all at once.
2706 (cl-declaim (inline foo bar))
2707 (cl-eval-when (compile load eval)
2708 (cl-proclaim '(inline foo bar)))
2709 (defsubst foo (@dots{}) @dots{}) ; instead of defun
2712 @strong{Please note:} this declaration remains in effect after the
2713 containing source file is done. It is correct to use it to
2714 request that a function you have defined should be inlined,
2715 but it is impolite to use it to request inlining of an external
2718 In Common Lisp, it is possible to use @code{(declare (inline @dots{}))}
2719 before a particular call to a function to cause just that call to
2720 be inlined; the current byte compilers provide no way to implement
2721 this, so @code{(cl-declare (inline @dots{}))} is currently ignored by
2725 The @code{notinline} declaration lists functions which should
2726 not be inlined after all; it cancels a previous @code{inline}
2730 This declaration controls how much optimization is performed by
2733 The word @code{optimize} is followed by any number of lists like
2734 @code{(speed 3)} or @code{(safety 2)}. Common Lisp defines several
2735 optimization ``qualities''; this package ignores all but @code{speed}
2736 and @code{safety}. The value of a quality should be an integer from
2737 0 to 3, with 0 meaning ``unimportant'' and 3 meaning ``very important''.
2738 The default level for both qualities is 1.
2740 In this package, the @code{speed} quality is tied to the @code{byte-optimize}
2741 flag, which is set to @code{nil} for @code{(speed 0)} and to
2742 @code{t} for higher settings; and the @code{safety} quality is
2743 tied to the @code{byte-compile-delete-errors} flag, which is
2744 set to @code{nil} for @code{(safety 3)} and to @code{t} for all
2745 lower settings. (The latter flag controls whether the compiler
2746 is allowed to optimize out code whose only side-effect could
2747 be to signal an error, e.g., rewriting @code{(progn foo bar)} to
2748 @code{bar} when it is not known whether @code{foo} will be bound
2751 Note that even compiling with @code{(safety 0)}, the Emacs
2752 byte-code system provides sufficient checking to prevent real
2753 harm from being done. For example, barring serious bugs in
2754 Emacs itself, Emacs will not crash with a segmentation fault
2755 just because of an error in a fully-optimized Lisp program.
2757 The @code{optimize} declaration is normally used in a top-level
2758 @code{cl-proclaim} or @code{cl-declaim} in a file; Common Lisp allows
2759 it to be used with @code{declare} to set the level of optimization
2760 locally for a given form, but this will not work correctly with the
2761 current byte-compiler. (The @code{cl-declare}
2762 will set the new optimization level, but that level will not
2763 automatically be unset after the enclosing form is done.)
2766 This declaration controls what sorts of warnings are generated
2767 by the byte compiler. The word @code{warn} is followed by any
2768 number of ``warning qualities'', similar in form to optimization
2769 qualities. The currently supported warning types are
2770 @code{redefine}, @code{callargs}, @code{unresolved}, and
2771 @code{free-vars}; in the current system, a value of 0 will
2772 disable these warnings and any higher value will enable them.
2773 See the documentation of the variable @code{byte-compile-warnings}
2781 This package defines several symbol-related features that were
2782 missing from Emacs Lisp.
2785 * Property Lists:: @code{cl-get}, @code{cl-remprop}, @code{cl-getf}, @code{cl-remf}.
2786 * Creating Symbols:: @code{cl-gensym}, @code{cl-gentemp}.
2789 @node Property Lists
2790 @section Property Lists
2793 These functions augment the standard Emacs Lisp functions @code{get}
2794 and @code{put} for operating on properties attached to symbols.
2795 There are also functions for working with property lists as
2796 first-class data structures not attached to particular symbols.
2798 @defun cl-get symbol property &optional default
2799 This function is like @code{get}, except that if the property is
2800 not found, the @var{default} argument provides the return value.
2801 (The Emacs Lisp @code{get} function always uses @code{nil} as
2802 the default; this package's @code{cl-get} is equivalent to Common
2805 The @code{cl-get} function is @code{setf}-able; when used in this
2806 fashion, the @var{default} argument is allowed but ignored.
2809 @defun cl-remprop symbol property
2810 This function removes the entry for @var{property} from the property
2811 list of @var{symbol}. It returns a true value if the property was
2812 indeed found and removed, or @code{nil} if there was no such property.
2813 (This function was probably omitted from Emacs originally because,
2814 since @code{get} did not allow a @var{default}, it was very difficult
2815 to distinguish between a missing property and a property whose value
2816 was @code{nil}; thus, setting a property to @code{nil} was close
2817 enough to @code{cl-remprop} for most purposes.)
2820 @defun cl-getf place property &optional default
2821 This function scans the list @var{place} as if it were a property
2822 list, i.e., a list of alternating property names and values. If
2823 an even-numbered element of @var{place} is found which is @code{eq}
2824 to @var{property}, the following odd-numbered element is returned.
2825 Otherwise, @var{default} is returned (or @code{nil} if no default
2831 (get sym prop) @equiv{} (cl-getf (symbol-plist sym) prop)
2834 It is valid to use @code{cl-getf} as a @code{setf} place, in which case
2835 its @var{place} argument must itself be a valid @code{setf} place.
2836 The @var{default} argument, if any, is ignored in this context.
2837 The effect is to change (via @code{setcar}) the value cell in the
2838 list that corresponds to @var{property}, or to cons a new property-value
2839 pair onto the list if the property is not yet present.
2842 (put sym prop val) @equiv{} (setf (cl-getf (symbol-plist sym) prop) val)
2845 The @code{get} and @code{cl-get} functions are also @code{setf}-able.
2846 The fact that @code{default} is ignored can sometimes be useful:
2849 (cl-incf (cl-get 'foo 'usage-count 0))
2852 Here, symbol @code{foo}'s @code{usage-count} property is incremented
2853 if it exists, or set to 1 (an incremented 0) otherwise.
2855 When not used as a @code{setf} form, @code{cl-getf} is just a regular
2856 function and its @var{place} argument can actually be any Lisp
2860 @defmac cl-remf place property
2861 This macro removes the property-value pair for @var{property} from
2862 the property list stored at @var{place}, which is any @code{setf}-able
2863 place expression. It returns true if the property was found. Note
2864 that if @var{property} happens to be first on the list, this will
2865 effectively do a @code{(setf @var{place} (cddr @var{place}))},
2866 whereas if it occurs later, this simply uses @code{setcdr} to splice
2867 out the property and value cells.
2870 @node Creating Symbols
2871 @section Creating Symbols
2874 These functions create unique symbols, typically for use as
2875 temporary variables.
2877 @defun cl-gensym &optional x
2878 This function creates a new, uninterned symbol (using @code{make-symbol})
2879 with a unique name. (The name of an uninterned symbol is relevant
2880 only if the symbol is printed.) By default, the name is generated
2881 from an increasing sequence of numbers, @samp{G1000}, @samp{G1001},
2882 @samp{G1002}, etc. If the optional argument @var{x} is a string, that
2883 string is used as a prefix instead of @samp{G}. Uninterned symbols
2884 are used in macro expansions for temporary variables, to ensure that
2885 their names will not conflict with ``real'' variables in the user's
2888 (Internally, the variable @code{cl--gensym-counter} holds the counter
2889 used to generate names. It is initialized with zero and incremented
2893 @defun cl-gentemp &optional x
2894 This function is like @code{cl-gensym}, except that it produces a new
2895 @emph{interned} symbol. If the symbol that is generated already
2896 exists, the function keeps incrementing the counter and trying
2897 again until a new symbol is generated.
2900 This package automatically creates all keywords that are called for by
2901 @code{&key} argument specifiers, and discourages the use of keywords
2902 as data unrelated to keyword arguments, so the related function
2903 @code{defkeyword} (to create self-quoting keyword symbols) is not
2910 This section defines a few simple Common Lisp operations on numbers
2911 that were left out of Emacs Lisp.
2914 * Predicates on Numbers:: @code{cl-plusp}, @code{cl-oddp}, etc.
2915 * Numerical Functions:: @code{cl-floor}, @code{cl-ceiling}, etc.
2916 * Random Numbers:: @code{cl-random}, @code{cl-make-random-state}.
2917 * Implementation Parameters:: @code{cl-most-positive-float}, etc.
2920 @node Predicates on Numbers
2921 @section Predicates on Numbers
2924 These functions return @code{t} if the specified condition is
2925 true of the numerical argument, or @code{nil} otherwise.
2927 @defun cl-plusp number
2928 This predicate tests whether @var{number} is positive. It is an
2929 error if the argument is not a number.
2932 @defun cl-minusp number
2933 This predicate tests whether @var{number} is negative. It is an
2934 error if the argument is not a number.
2937 @defun cl-oddp integer
2938 This predicate tests whether @var{integer} is odd. It is an
2939 error if the argument is not an integer.
2942 @defun cl-evenp integer
2943 This predicate tests whether @var{integer} is even. It is an
2944 error if the argument is not an integer.
2947 @defun cl-digit-char-p char radix
2948 Test if @var{char} is a digit in the specified @var{radix} (default is
2949 10). If it is, return the numerical value of digit @var{char} in
2953 @node Numerical Functions
2954 @section Numerical Functions
2957 These functions perform various arithmetic operations on numbers.
2959 @defun cl-gcd &rest integers
2960 This function returns the Greatest Common Divisor of the arguments.
2961 For one argument, it returns the absolute value of that argument.
2962 For zero arguments, it returns zero.
2965 @defun cl-lcm &rest integers
2966 This function returns the Least Common Multiple of the arguments.
2967 For one argument, it returns the absolute value of that argument.
2968 For zero arguments, it returns one.
2971 @defun cl-isqrt integer
2972 This function computes the ``integer square root'' of its integer
2973 argument, i.e., the greatest integer less than or equal to the true
2974 square root of the argument.
2977 @defun cl-floor number &optional divisor
2978 With one argument, @code{cl-floor} returns a list of two numbers:
2979 The argument rounded down (toward minus infinity) to an integer,
2980 and the ``remainder'' which would have to be added back to the
2981 first return value to yield the argument again. If the argument
2982 is an integer @var{x}, the result is always the list @code{(@var{x} 0)}.
2983 If the argument is a floating-point number, the first
2984 result is a Lisp integer and the second is a Lisp float between
2985 0 (inclusive) and 1 (exclusive).
2987 With two arguments, @code{cl-floor} divides @var{number} by
2988 @var{divisor}, and returns the floor of the quotient and the
2989 corresponding remainder as a list of two numbers. If
2990 @code{(cl-floor @var{x} @var{y})} returns @code{(@var{q} @var{r})},
2991 then @code{@var{q}*@var{y} + @var{r} = @var{x}}, with @var{r}
2992 between 0 (inclusive) and @var{r} (exclusive). Also, note
2993 that @code{(cl-floor @var{x})} is exactly equivalent to
2994 @code{(cl-floor @var{x} 1)}.
2996 This function is entirely compatible with Common Lisp's @code{floor}
2997 function, except that it returns the two results in a list since
2998 Emacs Lisp does not support multiple-valued functions.
3001 @defun cl-ceiling number &optional divisor
3002 This function implements the Common Lisp @code{ceiling} function,
3003 which is analogous to @code{floor} except that it rounds the
3004 argument or quotient of the arguments up toward plus infinity.
3005 The remainder will be between 0 and minus @var{r}.
3008 @defun cl-truncate number &optional divisor
3009 This function implements the Common Lisp @code{truncate} function,
3010 which is analogous to @code{floor} except that it rounds the
3011 argument or quotient of the arguments toward zero. Thus it is
3012 equivalent to @code{cl-floor} if the argument or quotient is
3013 positive, or to @code{cl-ceiling} otherwise. The remainder has
3014 the same sign as @var{number}.
3017 @defun cl-round number &optional divisor
3018 This function implements the Common Lisp @code{round} function,
3019 which is analogous to @code{floor} except that it rounds the
3020 argument or quotient of the arguments to the nearest integer.
3021 In the case of a tie (the argument or quotient is exactly
3022 halfway between two integers), it rounds to the even integer.
3025 @defun cl-mod number divisor
3026 This function returns the same value as the second return value
3030 @defun cl-rem number divisor
3031 This function returns the same value as the second return value
3032 of @code{cl-truncate}.
3035 @defun cl-parse-integer string &key start end radix junk-allowed
3036 This function implements the Common Lisp @code{parse-integer}
3037 function. It parses an integer in the specified @var{radix} from the
3038 substring of @var{string} between @var{start} and @var{end}. Any
3039 leading and trailing whitespace chars are ignored. The function
3040 signals an error if the substring between @var{start} and @var{end}
3041 cannot be parsed as an integer, unless @var{junk-allowed} is
3045 @node Random Numbers
3046 @section Random Numbers
3049 This package also provides an implementation of the Common Lisp
3050 random number generator. It uses its own additive-congruential
3051 algorithm, which is much more likely to give statistically clean
3052 @c FIXME? Still true?
3053 random numbers than the simple generators supplied by many
3056 @defun cl-random number &optional state
3057 This function returns a random nonnegative number less than
3058 @var{number}, and of the same type (either integer or floating-point).
3059 The @var{state} argument should be a @code{random-state} object
3060 that holds the state of the random number generator. The
3061 function modifies this state object as a side effect. If
3062 @var{state} is omitted, it defaults to the internal variable
3063 @code{cl--random-state}, which contains a pre-initialized
3064 default @code{random-state} object. (Since any number of programs in
3065 the Emacs process may be accessing @code{cl--random-state} in
3066 interleaved fashion, the sequence generated from this will be
3067 irreproducible for all intents and purposes.)
3070 @defun cl-make-random-state &optional state
3071 This function creates or copies a @code{random-state} object.
3072 If @var{state} is omitted or @code{nil}, it returns a new copy of
3073 @code{cl--random-state}. This is a copy in the sense that future
3074 sequences of calls to @code{(cl-random @var{n})} and
3075 @code{(cl-random @var{n} @var{s})} (where @var{s} is the new
3076 random-state object) will return identical sequences of random
3079 If @var{state} is a @code{random-state} object, this function
3080 returns a copy of that object. If @var{state} is @code{t}, this
3081 function returns a new @code{random-state} object seeded from the
3082 date and time. As an extension to Common Lisp, @var{state} may also
3083 be an integer in which case the new object is seeded from that
3084 integer; each different integer seed will result in a completely
3085 different sequence of random numbers.
3087 It is valid to print a @code{random-state} object to a buffer or
3088 file and later read it back with @code{read}. If a program wishes
3089 to use a sequence of pseudo-random numbers which can be reproduced
3090 later for debugging, it can call @code{(cl-make-random-state t)} to
3091 get a new sequence, then print this sequence to a file. When the
3092 program is later rerun, it can read the original run's random-state
3096 @defun cl-random-state-p object
3097 This predicate returns @code{t} if @var{object} is a
3098 @code{random-state} object, or @code{nil} otherwise.
3101 @node Implementation Parameters
3102 @section Implementation Parameters
3105 This package defines several useful constants having to do with
3106 floating-point numbers.
3108 It determines their values by exercising the computer's
3109 floating-point arithmetic in various ways. Because this operation
3110 might be slow, the code for initializing them is kept in a separate
3111 function that must be called before the parameters can be used.
3113 @defun cl-float-limits
3114 This function makes sure that the Common Lisp floating-point parameters
3115 like @code{cl-most-positive-float} have been initialized. Until it is
3116 called, these parameters will be @code{nil}.
3117 @c If this version of Emacs does not support floats, the parameters will
3118 @c remain @code{nil}.
3119 If the parameters have already been initialized, the function returns
3122 The algorithm makes assumptions that will be valid for almost all
3123 machines, but will fail if the machine's arithmetic is extremely
3124 unusual, e.g., decimal.
3127 Since true Common Lisp supports up to four different floating-point
3128 precisions, it has families of constants like
3129 @code{most-positive-single-float}, @code{most-positive-double-float},
3130 @code{most-positive-long-float}, and so on. Emacs has only one
3131 floating-point precision, so this package omits the precision word
3132 from the constants' names.
3134 @defvar cl-most-positive-float
3135 This constant equals the largest value a Lisp float can hold.
3136 For those systems whose arithmetic supports infinities, this is
3137 the largest @emph{finite} value. For IEEE machines, the value
3138 is approximately @code{1.79e+308}.
3141 @defvar cl-most-negative-float
3142 This constant equals the most negative value a Lisp float can hold.
3143 (It is assumed to be equal to @code{(- cl-most-positive-float)}.)
3146 @defvar cl-least-positive-float
3147 This constant equals the smallest Lisp float value greater than zero.
3148 For IEEE machines, it is about @code{4.94e-324} if denormals are
3149 supported or @code{2.22e-308} if not.
3152 @defvar cl-least-positive-normalized-float
3153 This constant equals the smallest @emph{normalized} Lisp float greater
3154 than zero, i.e., the smallest value for which IEEE denormalization
3155 will not result in a loss of precision. For IEEE machines, this
3156 value is about @code{2.22e-308}. For machines that do not support
3157 the concept of denormalization and gradual underflow, this constant
3158 will always equal @code{cl-least-positive-float}.
3161 @defvar cl-least-negative-float
3162 This constant is the negative counterpart of @code{cl-least-positive-float}.
3165 @defvar cl-least-negative-normalized-float
3166 This constant is the negative counterpart of
3167 @code{cl-least-positive-normalized-float}.
3170 @defvar cl-float-epsilon
3171 This constant is the smallest positive Lisp float that can be added
3172 to 1.0 to produce a distinct value. Adding a smaller number to 1.0
3173 will yield 1.0 again due to roundoff. For IEEE machines, epsilon
3174 is about @code{2.22e-16}.
3177 @defvar cl-float-negative-epsilon
3178 This is the smallest positive value that can be subtracted from
3179 1.0 to produce a distinct value. For IEEE machines, it is about
3187 Common Lisp defines a number of functions that operate on
3188 @dfn{sequences}, which are either lists, strings, or vectors.
3189 Emacs Lisp includes a few of these, notably @code{elt} and
3190 @code{length}; this package defines most of the rest.
3193 * Sequence Basics:: Arguments shared by all sequence functions.
3194 * Mapping over Sequences:: @code{cl-mapcar}, @code{cl-map}, @code{cl-maplist}, etc.
3195 * Sequence Functions:: @code{cl-subseq}, @code{cl-remove}, @code{cl-substitute}, etc.
3196 * Searching Sequences:: @code{cl-find}, @code{cl-count}, @code{cl-search}, etc.
3197 * Sorting Sequences:: @code{cl-sort}, @code{cl-stable-sort}, @code{cl-merge}.
3200 @node Sequence Basics
3201 @section Sequence Basics
3204 Many of the sequence functions take keyword arguments; @pxref{Argument
3205 Lists}. All keyword arguments are optional and, if specified,
3206 may appear in any order.
3208 The @code{:key} argument should be passed either @code{nil}, or a
3209 function of one argument. This key function is used as a filter
3210 through which the elements of the sequence are seen; for example,
3211 @code{(cl-find x y :key 'car)} is similar to @code{(cl-assoc x y)}.
3212 It searches for an element of the list whose @sc{car} equals
3213 @code{x}, rather than for an element which equals @code{x} itself.
3214 If @code{:key} is omitted or @code{nil}, the filter is effectively
3215 the identity function.
3217 The @code{:test} and @code{:test-not} arguments should be either
3218 @code{nil}, or functions of two arguments. The test function is
3219 used to compare two sequence elements, or to compare a search value
3220 with sequence elements. (The two values are passed to the test
3221 function in the same order as the original sequence function
3222 arguments from which they are derived, or, if they both come from
3223 the same sequence, in the same order as they appear in that sequence.)
3224 The @code{:test} argument specifies a function which must return
3225 true (non-@code{nil}) to indicate a match; instead, you may use
3226 @code{:test-not} to give a function which returns @emph{false} to
3227 indicate a match. The default test function is @code{eql}.
3229 Many functions that take @var{item} and @code{:test} or @code{:test-not}
3230 arguments also come in @code{-if} and @code{-if-not} varieties,
3231 where a @var{predicate} function is passed instead of @var{item},
3232 and sequence elements match if the predicate returns true on them
3233 (or false in the case of @code{-if-not}). For example:
3236 (cl-remove 0 seq :test '=) @equiv{} (cl-remove-if 'zerop seq)
3240 to remove all zeros from sequence @code{seq}.
3242 Some operations can work on a subsequence of the argument sequence;
3243 these function take @code{:start} and @code{:end} arguments, which
3244 default to zero and the length of the sequence, respectively.
3245 Only elements between @var{start} (inclusive) and @var{end}
3246 (exclusive) are affected by the operation. The @var{end} argument
3247 may be passed @code{nil} to signify the length of the sequence;
3248 otherwise, both @var{start} and @var{end} must be integers, with
3249 @code{0 <= @var{start} <= @var{end} <= (length @var{seq})}.
3250 If the function takes two sequence arguments, the limits are
3251 defined by keywords @code{:start1} and @code{:end1} for the first,
3252 and @code{:start2} and @code{:end2} for the second.
3254 A few functions accept a @code{:from-end} argument, which, if
3255 non-@code{nil}, causes the operation to go from right-to-left
3256 through the sequence instead of left-to-right, and a @code{:count}
3257 argument, which specifies an integer maximum number of elements
3258 to be removed or otherwise processed.
3260 The sequence functions make no guarantees about the order in
3261 which the @code{:test}, @code{:test-not}, and @code{:key} functions
3262 are called on various elements. Therefore, it is a bad idea to depend
3263 on side effects of these functions. For example, @code{:from-end}
3264 may cause the sequence to be scanned actually in reverse, or it may
3265 be scanned forwards but computing a result ``as if'' it were scanned
3266 backwards. (Some functions, like @code{cl-mapcar} and @code{cl-every},
3267 @emph{do} specify exactly the order in which the function is called
3268 so side effects are perfectly acceptable in those cases.)
3270 Strings may contain ``text properties'' as well
3271 as character data. Except as noted, it is undefined whether or
3272 not text properties are preserved by sequence functions. For
3273 example, @code{(cl-remove ?A @var{str})} may or may not preserve
3274 the properties of the characters copied from @var{str} into the
3277 @node Mapping over Sequences
3278 @section Mapping over Sequences
3281 These functions ``map'' the function you specify over the elements
3282 of lists or arrays. They are all variations on the theme of the
3283 built-in function @code{mapcar}.
3285 @defun cl-mapcar function seq &rest more-seqs
3286 This function calls @var{function} on successive parallel sets of
3287 elements from its argument sequences. Given a single @var{seq}
3288 argument it is equivalent to @code{mapcar}; given @var{n} sequences,
3289 it calls the function with the first elements of each of the sequences
3290 as the @var{n} arguments to yield the first element of the result
3291 list, then with the second elements, and so on. The mapping stops as
3292 soon as the shortest sequence runs out. The argument sequences may
3293 be any mixture of lists, strings, and vectors; the return sequence
3296 Common Lisp's @code{mapcar} accepts multiple arguments but works
3297 only on lists; Emacs Lisp's @code{mapcar} accepts a single sequence
3298 argument. This package's @code{cl-mapcar} works as a compatible
3302 @defun cl-map result-type function seq &rest more-seqs
3303 This function maps @var{function} over the argument sequences,
3304 just like @code{cl-mapcar}, but it returns a sequence of type
3305 @var{result-type} rather than a list. @var{result-type} must
3306 be one of the following symbols: @code{vector}, @code{string},
3307 @code{list} (in which case the effect is the same as for
3308 @code{cl-mapcar}), or @code{nil} (in which case the results are
3309 thrown away and @code{cl-map} returns @code{nil}).
3312 @defun cl-maplist function list &rest more-lists
3313 This function calls @var{function} on each of its argument lists,
3314 then on the @sc{cdr}s of those lists, and so on, until the
3315 shortest list runs out. The results are returned in the form
3316 of a list. Thus, @code{cl-maplist} is like @code{cl-mapcar} except
3317 that it passes in the list pointers themselves rather than the
3318 @sc{car}s of the advancing pointers.
3321 @defun cl-mapc function seq &rest more-seqs
3322 This function is like @code{cl-mapcar}, except that the values returned
3323 by @var{function} are ignored and thrown away rather than being
3324 collected into a list. The return value of @code{cl-mapc} is @var{seq},
3325 the first sequence. This function is more general than the Emacs
3326 primitive @code{mapc}. (Note that this function is called
3327 @code{cl-mapc} even in @file{cl.el}, rather than @code{mapc*} as you
3329 @c https://debbugs.gnu.org/6575
3332 @defun cl-mapl function list &rest more-lists
3333 This function is like @code{cl-maplist}, except that it throws away
3334 the values returned by @var{function}.
3337 @defun cl-mapcan function seq &rest more-seqs
3338 This function is like @code{cl-mapcar}, except that it concatenates
3339 the return values (which must be lists) using @code{nconc},
3340 rather than simply collecting them into a list.
3343 @defun cl-mapcon function list &rest more-lists
3344 This function is like @code{cl-maplist}, except that it concatenates
3345 the return values using @code{nconc}.
3348 @defun cl-some predicate seq &rest more-seqs
3349 This function calls @var{predicate} on each element of @var{seq}
3350 in turn; if @var{predicate} returns a non-@code{nil} value,
3351 @code{cl-some} returns that value, otherwise it returns @code{nil}.
3352 Given several sequence arguments, it steps through the sequences
3353 in parallel until the shortest one runs out, just as in
3354 @code{cl-mapcar}. You can rely on the left-to-right order in which
3355 the elements are visited, and on the fact that mapping stops
3356 immediately as soon as @var{predicate} returns non-@code{nil}.
3359 @defun cl-every predicate seq &rest more-seqs
3360 This function calls @var{predicate} on each element of the sequence(s)
3361 in turn; it returns @code{nil} as soon as @var{predicate} returns
3362 @code{nil} for any element, or @code{t} if the predicate was true
3366 @defun cl-notany predicate seq &rest more-seqs
3367 This function calls @var{predicate} on each element of the sequence(s)
3368 in turn; it returns @code{nil} as soon as @var{predicate} returns
3369 a non-@code{nil} value for any element, or @code{t} if the predicate
3370 was @code{nil} for all elements.
3373 @defun cl-notevery predicate seq &rest more-seqs
3374 This function calls @var{predicate} on each element of the sequence(s)
3375 in turn; it returns a non-@code{nil} value as soon as @var{predicate}
3376 returns @code{nil} for any element, or @code{nil} if the predicate was
3377 true for all elements.
3380 @defun cl-reduce function seq @t{&key :from-end :start :end :initial-value :key}
3381 This function combines the elements of @var{seq} using an associative
3382 binary operation. Suppose @var{function} is @code{*} and @var{seq} is
3383 the list @code{(2 3 4 5)}. The first two elements of the list are
3384 combined with @code{(* 2 3) = 6}; this is combined with the next
3385 element, @code{(* 6 4) = 24}, and that is combined with the final
3386 element: @code{(* 24 5) = 120}. Note that the @code{*} function happens
3387 to be self-reducing, so that @code{(* 2 3 4 5)} has the same effect as
3388 an explicit call to @code{cl-reduce}.
3390 If @code{:from-end} is true, the reduction is right-associative instead
3391 of left-associative:
3394 (cl-reduce '- '(1 2 3 4))
3395 @equiv{} (- (- (- 1 2) 3) 4) @result{} -8
3396 (cl-reduce '- '(1 2 3 4) :from-end t)
3397 @equiv{} (- 1 (- 2 (- 3 4))) @result{} -2
3400 If @code{:key} is specified, it is a function of one argument, which
3401 is called on each of the sequence elements in turn.
3403 If @code{:initial-value} is specified, it is effectively added to the
3404 front (or rear in the case of @code{:from-end}) of the sequence.
3405 The @code{:key} function is @emph{not} applied to the initial value.
3407 If the sequence, including the initial value, has exactly one element
3408 then that element is returned without ever calling @var{function}.
3409 If the sequence is empty (and there is no initial value), then
3410 @var{function} is called with no arguments to obtain the return value.
3413 All of these mapping operations can be expressed conveniently in
3414 terms of the @code{cl-loop} macro. In compiled code, @code{cl-loop} will
3415 be faster since it generates the loop as in-line code with no
3418 @node Sequence Functions
3419 @section Sequence Functions
3422 This section describes a number of Common Lisp functions for
3423 operating on sequences.
3425 @defun cl-subseq sequence start &optional end
3426 This function returns a given subsequence of the argument
3427 @var{sequence}, which may be a list, string, or vector.
3428 The indices @var{start} and @var{end} must be in range, and
3429 @var{start} must be no greater than @var{end}. If @var{end}
3430 is omitted, it defaults to the length of the sequence. The
3431 return value is always a copy; it does not share structure
3432 with @var{sequence}.
3434 As an extension to Common Lisp, @var{start} and/or @var{end}
3435 may be negative, in which case they represent a distance back
3436 from the end of the sequence. This is for compatibility with
3437 Emacs's @code{substring} function. Note that @code{cl-subseq} is
3438 the @emph{only} sequence function that allows negative
3439 @var{start} and @var{end}.
3441 You can use @code{setf} on a @code{cl-subseq} form to replace a
3442 specified range of elements with elements from another sequence.
3443 The replacement is done as if by @code{cl-replace}, described below.
3446 @defun cl-concatenate result-type &rest seqs
3447 This function concatenates the argument sequences together to
3448 form a result sequence of type @var{result-type}, one of the
3449 symbols @code{vector}, @code{string}, or @code{list}. The
3450 arguments are always copied, even in cases such as
3451 @code{(cl-concatenate 'list '(1 2 3))} where the result is
3452 identical to an argument.
3455 @defun cl-fill seq item @t{&key :start :end}
3456 This function fills the elements of the sequence (or the specified
3457 part of the sequence) with the value @var{item}.
3460 @defun cl-replace seq1 seq2 @t{&key :start1 :end1 :start2 :end2}
3461 This function copies part of @var{seq2} into part of @var{seq1}.
3462 The sequence @var{seq1} is not stretched or resized; the amount
3463 of data copied is simply the shorter of the source and destination
3464 (sub)sequences. The function returns @var{seq1}.
3466 If @var{seq1} and @var{seq2} are @code{eq}, then the replacement
3467 will work correctly even if the regions indicated by the start
3468 and end arguments overlap. However, if @var{seq1} and @var{seq2}
3469 are lists that share storage but are not @code{eq}, and the
3470 start and end arguments specify overlapping regions, the effect
3474 @defun cl-remove item seq @t{&key :test :test-not :key :count :start :end :from-end}
3475 This returns a copy of @var{seq} with all elements matching
3476 @var{item} removed. The result may share storage with or be
3477 @code{eq} to @var{seq} in some circumstances, but the original
3478 @var{seq} will not be modified. The @code{:test}, @code{:test-not},
3479 and @code{:key} arguments define the matching test that is used;
3480 by default, elements @code{eql} to @var{item} are removed. The
3481 @code{:count} argument specifies the maximum number of matching
3482 elements that can be removed (only the leftmost @var{count} matches
3483 are removed). The @code{:start} and @code{:end} arguments specify
3484 a region in @var{seq} in which elements will be removed; elements
3485 outside that region are not matched or removed. The @code{:from-end}
3486 argument, if true, says that elements should be deleted from the
3487 end of the sequence rather than the beginning (this matters only
3488 if @var{count} was also specified).
3491 @defun cl-delete item seq @t{&key :test :test-not :key :count :start :end :from-end}
3492 This deletes all elements of @var{seq} that match @var{item}.
3493 It is a destructive operation. Since Emacs Lisp does not support
3494 stretchable strings or vectors, this is the same as @code{cl-remove}
3495 for those sequence types. On lists, @code{cl-remove} will copy the
3496 list if necessary to preserve the original list, whereas
3497 @code{cl-delete} will splice out parts of the argument list.
3498 Compare @code{append} and @code{nconc}, which are analogous
3499 non-destructive and destructive list operations in Emacs Lisp.
3502 @findex cl-remove-if
3503 @findex cl-remove-if-not
3504 @findex cl-delete-if
3505 @findex cl-delete-if-not
3506 The predicate-oriented functions @code{cl-remove-if}, @code{cl-remove-if-not},
3507 @code{cl-delete-if}, and @code{cl-delete-if-not} are defined similarly.
3509 @defun cl-remove-duplicates seq @t{&key :test :test-not :key :start :end :from-end}
3510 This function returns a copy of @var{seq} with duplicate elements
3511 removed. Specifically, if two elements from the sequence match
3512 according to the @code{:test}, @code{:test-not}, and @code{:key}
3513 arguments, only the rightmost one is retained. If @code{:from-end}
3514 is true, the leftmost one is retained instead. If @code{:start} or
3515 @code{:end} is specified, only elements within that subsequence are
3516 examined or removed.
3519 @defun cl-delete-duplicates seq @t{&key :test :test-not :key :start :end :from-end}
3520 This function deletes duplicate elements from @var{seq}. It is
3521 a destructive version of @code{cl-remove-duplicates}.
3524 @defun cl-substitute new old seq @t{&key :test :test-not :key :count :start :end :from-end}
3525 This function returns a copy of @var{seq}, with all elements
3526 matching @var{old} replaced with @var{new}. The @code{:count},
3527 @code{:start}, @code{:end}, and @code{:from-end} arguments may be
3528 used to limit the number of substitutions made.
3531 @defun cl-nsubstitute new old seq @t{&key :test :test-not :key :count :start :end :from-end}
3532 This is a destructive version of @code{cl-substitute}; it performs
3533 the substitution using @code{setcar} or @code{aset} rather than
3534 by returning a changed copy of the sequence.
3537 @findex cl-substitute-if
3538 @findex cl-substitute-if-not
3539 @findex cl-nsubstitute-if
3540 @findex cl-nsubstitute-if-not
3541 The functions @code{cl-substitute-if}, @code{cl-substitute-if-not},
3542 @code{cl-nsubstitute-if}, and @code{cl-nsubstitute-if-not} are defined
3543 similarly. For these, a @var{predicate} is given in place of the
3546 @node Searching Sequences
3547 @section Searching Sequences
3550 These functions search for elements or subsequences in a sequence.
3551 (See also @code{cl-member} and @code{cl-assoc}; @pxref{Lists}.)
3553 @defun cl-find item seq @t{&key :test :test-not :key :start :end :from-end}
3554 This function searches @var{seq} for an element matching @var{item}.
3555 If it finds a match, it returns the matching element. Otherwise,
3556 it returns @code{nil}. It returns the leftmost match, unless
3557 @code{:from-end} is true, in which case it returns the rightmost
3558 match. The @code{:start} and @code{:end} arguments may be used to
3559 limit the range of elements that are searched.
3562 @defun cl-position item seq @t{&key :test :test-not :key :start :end :from-end}
3563 This function is like @code{cl-find}, except that it returns the
3564 integer position in the sequence of the matching item rather than
3565 the item itself. The position is relative to the start of the
3566 sequence as a whole, even if @code{:start} is non-zero. The function
3567 returns @code{nil} if no matching element was found.
3570 @defun cl-count item seq @t{&key :test :test-not :key :start :end}
3571 This function returns the number of elements of @var{seq} which
3572 match @var{item}. The result is always a nonnegative integer.
3576 @findex cl-find-if-not
3577 @findex cl-position-if
3578 @findex cl-position-if-not
3580 @findex cl-count-if-not
3581 The @code{cl-find-if}, @code{cl-find-if-not}, @code{cl-position-if},
3582 @code{cl-position-if-not}, @code{cl-count-if}, and @code{cl-count-if-not}
3583 functions are defined similarly.
3585 @defun cl-mismatch seq1 seq2 @t{&key :test :test-not :key :start1 :end1 :start2 :end2 :from-end}
3586 This function compares the specified parts of @var{seq1} and
3587 @var{seq2}. If they are the same length and the corresponding
3588 elements match (according to @code{:test}, @code{:test-not},
3589 and @code{:key}), the function returns @code{nil}. If there is
3590 a mismatch, the function returns the index (relative to @var{seq1})
3591 of the first mismatching element. This will be the leftmost pair of
3592 elements that do not match, or the position at which the shorter of
3593 the two otherwise-matching sequences runs out.
3595 If @code{:from-end} is true, then the elements are compared from right
3596 to left starting at @code{(1- @var{end1})} and @code{(1- @var{end2})}.
3597 If the sequences differ, then one plus the index of the rightmost
3598 difference (relative to @var{seq1}) is returned.
3600 An interesting example is @code{(cl-mismatch str1 str2 :key 'upcase)},
3601 which compares two strings case-insensitively.
3604 @defun cl-search seq1 seq2 @t{&key :test :test-not :key :from-end :start1 :end1 :start2 :end2}
3605 This function searches @var{seq2} for a subsequence that matches
3606 @var{seq1} (or part of it specified by @code{:start1} and
3607 @code{:end1}). Only matches that fall entirely within the region
3608 defined by @code{:start2} and @code{:end2} will be considered.
3609 The return value is the index of the leftmost element of the
3610 leftmost match, relative to the start of @var{seq2}, or @code{nil}
3611 if no matches were found. If @code{:from-end} is true, the
3612 function finds the @emph{rightmost} matching subsequence.
3615 @node Sorting Sequences
3616 @section Sorting Sequences
3618 @defun cl-sort seq predicate @t{&key :key}
3619 This function sorts @var{seq} into increasing order as determined
3620 by using @var{predicate} to compare pairs of elements. @var{predicate}
3621 should return true (non-@code{nil}) if and only if its first argument
3622 is less than (not equal to) its second argument. For example,
3623 @code{<} and @code{string-lessp} are suitable predicate functions
3624 for sorting numbers and strings, respectively; @code{>} would sort
3625 numbers into decreasing rather than increasing order.
3627 This function differs from Emacs's built-in @code{sort} in that it
3628 can operate on any type of sequence, not just lists. Also, it
3629 accepts a @code{:key} argument, which is used to preprocess data
3630 fed to the @var{predicate} function. For example,
3633 (setq data (cl-sort data 'string-lessp :key 'downcase))
3637 sorts @var{data}, a sequence of strings, into increasing alphabetical
3638 order without regard to case. A @code{:key} function of @code{car}
3639 would be useful for sorting association lists. It should only be a
3640 simple accessor though, since it's used heavily in the current
3643 The @code{cl-sort} function is destructive; it sorts lists by actually
3644 rearranging the @sc{cdr} pointers in suitable fashion.
3647 @defun cl-stable-sort seq predicate @t{&key :key}
3648 This function sorts @var{seq} @dfn{stably}, meaning two elements
3649 which are equal in terms of @var{predicate} are guaranteed not to
3650 be rearranged out of their original order by the sort.
3652 In practice, @code{cl-sort} and @code{cl-stable-sort} are equivalent
3653 in Emacs Lisp because the underlying @code{sort} function is
3654 stable by default. However, this package reserves the right to
3655 use non-stable methods for @code{cl-sort} in the future.
3658 @defun cl-merge type seq1 seq2 predicate @t{&key :key}
3659 This function merges two sequences @var{seq1} and @var{seq2} by
3660 interleaving their elements. The result sequence, of type @var{type}
3661 (in the sense of @code{cl-concatenate}), has length equal to the sum
3662 of the lengths of the two input sequences. The sequences may be
3663 modified destructively. Order of elements within @var{seq1} and
3664 @var{seq2} is preserved in the interleaving; elements of the two
3665 sequences are compared by @var{predicate} (in the sense of
3666 @code{sort}) and the lesser element goes first in the result.
3667 When elements are equal, those from @var{seq1} precede those from
3668 @var{seq2} in the result. Thus, if @var{seq1} and @var{seq2} are
3669 both sorted according to @var{predicate}, then the result will be
3670 a merged sequence which is (stably) sorted according to
3678 The functions described here operate on lists.
3681 * List Functions:: @code{cl-caddr}, @code{cl-first}, @code{cl-list*}, etc.
3682 * Substitution of Expressions:: @code{cl-subst}, @code{cl-sublis}, etc.
3683 * Lists as Sets:: @code{cl-member}, @code{cl-adjoin}, @code{cl-union}, etc.
3684 * Association Lists:: @code{cl-assoc}, @code{cl-acons}, @code{cl-pairlis}, etc.
3687 @node List Functions
3688 @section List Functions
3691 This section describes a number of simple operations on lists,
3692 i.e., chains of cons cells.
3695 This function is equivalent to @code{(car (cdr (cdr @var{x})))}.
3696 Likewise, this package aliases all 24 @code{c@var{xxx}r} functions
3697 where @var{xxx} is up to four @samp{a}s and/or @samp{d}s.
3698 All of these functions are @code{setf}-able, and calls to them
3699 are expanded inline by the byte-compiler for maximum efficiency.
3703 This function is a synonym for @code{(car @var{x})}. Likewise,
3704 the functions @code{cl-second}, @code{cl-third}, @dots{}, through
3705 @code{cl-tenth} return the given element of the list @var{x}.
3709 This function is a synonym for @code{(cdr @var{x})}.
3713 This function acts like @code{null}, but signals an error if @code{x}
3714 is neither a @code{nil} nor a cons cell.
3717 @defun cl-list-length x
3718 This function returns the length of list @var{x}, exactly like
3719 @code{(length @var{x})}, except that if @var{x} is a circular
3720 list (where the @sc{cdr}-chain forms a loop rather than terminating
3721 with @code{nil}), this function returns @code{nil}. (The regular
3722 @code{length} function would get stuck if given a circular list.
3723 See also the @code{safe-length} function.)
3726 @defun cl-list* arg &rest others
3727 This function constructs a list of its arguments. The final
3728 argument becomes the @sc{cdr} of the last cell constructed.
3729 Thus, @code{(cl-list* @var{a} @var{b} @var{c})} is equivalent to
3730 @code{(cons @var{a} (cons @var{b} @var{c}))}, and
3731 @code{(cl-list* @var{a} @var{b} nil)} is equivalent to
3732 @code{(list @var{a} @var{b})}.
3735 @defun cl-ldiff list sublist
3736 If @var{sublist} is a sublist of @var{list}, i.e., is @code{eq} to
3737 one of the cons cells of @var{list}, then this function returns
3738 a copy of the part of @var{list} up to but not including
3739 @var{sublist}. For example, @code{(cl-ldiff x (cddr x))} returns
3740 the first two elements of the list @code{x}. The result is a
3741 copy; the original @var{list} is not modified. If @var{sublist}
3742 is not a sublist of @var{list}, a copy of the entire @var{list}
3746 @defun cl-copy-list list
3747 This function returns a copy of the list @var{list}. It copies
3748 dotted lists like @code{(1 2 . 3)} correctly.
3751 @defun cl-tree-equal x y @t{&key :test :test-not :key}
3752 This function compares two trees of cons cells. If @var{x} and
3753 @var{y} are both cons cells, their @sc{car}s and @sc{cdr}s are
3754 compared recursively. If neither @var{x} nor @var{y} is a cons
3755 cell, they are compared by @code{eql}, or according to the
3756 specified test. The @code{:key} function, if specified, is
3757 applied to the elements of both trees. @xref{Sequences}.
3760 @node Substitution of Expressions
3761 @section Substitution of Expressions
3764 These functions substitute elements throughout a tree of cons
3765 cells. (@xref{Sequence Functions}, for the @code{cl-substitute}
3766 function, which works on just the top-level elements of a list.)
3768 @defun cl-subst new old tree @t{&key :test :test-not :key}
3769 This function substitutes occurrences of @var{old} with @var{new}
3770 in @var{tree}, a tree of cons cells. It returns a substituted
3771 tree, which will be a copy except that it may share storage with
3772 the argument @var{tree} in parts where no substitutions occurred.
3773 The original @var{tree} is not modified. This function recurses
3774 on, and compares against @var{old}, both @sc{car}s and @sc{cdr}s
3775 of the component cons cells. If @var{old} is itself a cons cell,
3776 then matching cells in the tree are substituted as usual without
3777 recursively substituting in that cell. Comparisons with @var{old}
3778 are done according to the specified test (@code{eql} by default).
3779 The @code{:key} function is applied to the elements of the tree
3780 but not to @var{old}.
3783 @defun cl-nsubst new old tree @t{&key :test :test-not :key}
3784 This function is like @code{cl-subst}, except that it works by
3785 destructive modification (by @code{setcar} or @code{setcdr})
3786 rather than copying.
3790 @findex cl-subst-if-not
3791 @findex cl-nsubst-if
3792 @findex cl-nsubst-if-not
3793 The @code{cl-subst-if}, @code{cl-subst-if-not}, @code{cl-nsubst-if}, and
3794 @code{cl-nsubst-if-not} functions are defined similarly.
3796 @defun cl-sublis alist tree @t{&key :test :test-not :key}
3797 This function is like @code{cl-subst}, except that it takes an
3798 association list @var{alist} of @var{old}-@var{new} pairs.
3799 Each element of the tree (after applying the @code{:key}
3800 function, if any), is compared with the @sc{car}s of
3801 @var{alist}; if it matches, it is replaced by the corresponding
3805 @defun cl-nsublis alist tree @t{&key :test :test-not :key}
3806 This is a destructive version of @code{cl-sublis}.
3810 @section Lists as Sets
3813 These functions perform operations on lists that represent sets
3816 @defun cl-member item list @t{&key :test :test-not :key}
3817 This function searches @var{list} for an element matching @var{item}.
3818 If a match is found, it returns the cons cell whose @sc{car} was
3819 the matching element. Otherwise, it returns @code{nil}. Elements
3820 are compared by @code{eql} by default; you can use the @code{:test},
3821 @code{:test-not}, and @code{:key} arguments to modify this behavior.
3824 The standard Emacs lisp function @code{member} uses @code{equal} for
3825 comparisons; it is equivalent to @code{(cl-member @var{item} @var{list}
3826 :test 'equal)}. With no keyword arguments, @code{cl-member} is
3827 equivalent to @code{memq}.
3830 @findex cl-member-if
3831 @findex cl-member-if-not
3832 The @code{cl-member-if} and @code{cl-member-if-not} functions
3833 analogously search for elements that satisfy a given predicate.
3835 @defun cl-tailp sublist list
3836 This function returns @code{t} if @var{sublist} is a sublist of
3837 @var{list}, i.e., if @var{sublist} is @code{eql} to @var{list} or to
3838 any of its @sc{cdr}s.
3841 @defun cl-adjoin item list @t{&key :test :test-not :key}
3842 This function conses @var{item} onto the front of @var{list},
3843 like @code{(cons @var{item} @var{list})}, but only if @var{item}
3844 is not already present on the list (as determined by @code{cl-member}).
3845 If a @code{:key} argument is specified, it is applied to
3846 @var{item} as well as to the elements of @var{list} during
3847 the search, on the reasoning that @var{item} is ``about'' to
3848 become part of the list.
3851 @defun cl-union list1 list2 @t{&key :test :test-not :key}
3852 This function combines two lists that represent sets of items,
3853 returning a list that represents the union of those two sets.
3854 The resulting list contains all items that appear in @var{list1}
3855 or @var{list2}, and no others. If an item appears in both
3856 @var{list1} and @var{list2} it is copied only once. If
3857 an item is duplicated in @var{list1} or @var{list2}, it is
3858 undefined whether or not that duplication will survive in the
3859 result list. The order of elements in the result list is also
3863 @defun cl-nunion list1 list2 @t{&key :test :test-not :key}
3864 This is a destructive version of @code{cl-union}; rather than copying,
3865 it tries to reuse the storage of the argument lists if possible.
3868 @defun cl-intersection list1 list2 @t{&key :test :test-not :key}
3869 This function computes the intersection of the sets represented
3870 by @var{list1} and @var{list2}. It returns the list of items
3871 that appear in both @var{list1} and @var{list2}.
3874 @defun cl-nintersection list1 list2 @t{&key :test :test-not :key}
3875 This is a destructive version of @code{cl-intersection}. It
3876 tries to reuse storage of @var{list1} rather than copying.
3877 It does @emph{not} reuse the storage of @var{list2}.
3880 @defun cl-set-difference list1 list2 @t{&key :test :test-not :key}
3881 This function computes the ``set difference'' of @var{list1}
3882 and @var{list2}, i.e., the set of elements that appear in
3883 @var{list1} but @emph{not} in @var{list2}.
3886 @defun cl-nset-difference list1 list2 @t{&key :test :test-not :key}
3887 This is a destructive @code{cl-set-difference}, which will try
3888 to reuse @var{list1} if possible.
3891 @defun cl-set-exclusive-or list1 list2 @t{&key :test :test-not :key}
3892 This function computes the ``set exclusive or'' of @var{list1}
3893 and @var{list2}, i.e., the set of elements that appear in
3894 exactly one of @var{list1} and @var{list2}.
3897 @defun cl-nset-exclusive-or list1 list2 @t{&key :test :test-not :key}
3898 This is a destructive @code{cl-set-exclusive-or}, which will try
3899 to reuse @var{list1} and @var{list2} if possible.
3902 @defun cl-subsetp list1 list2 @t{&key :test :test-not :key}
3903 This function checks whether @var{list1} represents a subset
3904 of @var{list2}, i.e., whether every element of @var{list1}
3905 also appears in @var{list2}.
3908 @node Association Lists
3909 @section Association Lists
3912 An @dfn{association list} is a list representing a mapping from
3913 one set of values to another; any list whose elements are cons
3914 cells is an association list.
3916 @defun cl-assoc item a-list @t{&key :test :test-not :key}
3917 This function searches the association list @var{a-list} for an
3918 element whose @sc{car} matches (in the sense of @code{:test},
3919 @code{:test-not}, and @code{:key}, or by comparison with @code{eql})
3920 a given @var{item}. It returns the matching element, if any,
3921 otherwise @code{nil}. It ignores elements of @var{a-list} that
3922 are not cons cells. (This corresponds to the behavior of
3923 @code{assq} and @code{assoc} in Emacs Lisp; Common Lisp's
3924 @code{assoc} ignores @code{nil}s but considers any other non-cons
3925 elements of @var{a-list} to be an error.)
3928 @defun cl-rassoc item a-list @t{&key :test :test-not :key}
3929 This function searches for an element whose @sc{cdr} matches
3930 @var{item}. If @var{a-list} represents a mapping, this applies
3931 the inverse of the mapping to @var{item}.
3935 @findex cl-assoc-if-not
3936 @findex cl-rassoc-if
3937 @findex cl-rassoc-if-not
3938 The @code{cl-assoc-if}, @code{cl-assoc-if-not}, @code{cl-rassoc-if},
3939 and @code{cl-rassoc-if-not} functions are defined similarly.
3941 Two simple functions for constructing association lists are:
3943 @defun cl-acons key value alist
3944 This is equivalent to @code{(cons (cons @var{key} @var{value}) @var{alist})}.
3947 @defun cl-pairlis keys values &optional alist
3948 This is equivalent to @code{(nconc (cl-mapcar 'cons @var{keys} @var{values})
3956 The Common Lisp @dfn{structure} mechanism provides a general way
3957 to define data types similar to C's @code{struct} types. A
3958 structure is a Lisp object containing some number of @dfn{slots},
3959 each of which can hold any Lisp data object. Functions are
3960 provided for accessing and setting the slots, creating or copying
3961 structure objects, and recognizing objects of a particular structure
3964 In true Common Lisp, each structure type is a new type distinct
3965 from all existing Lisp types. Since the underlying Emacs Lisp
3966 system provides no way to create new distinct types, this package
3967 implements structures as vectors (or lists upon request) with a
3968 special ``tag'' symbol to identify them.
3970 @defmac cl-defstruct name slots@dots{}
3971 The @code{cl-defstruct} form defines a new structure type called
3972 @var{name}, with the specified @var{slots}. (The @var{slots}
3973 may begin with a string which documents the structure type.)
3974 In the simplest case, @var{name} and each of the @var{slots}
3975 are symbols. For example,
3978 (cl-defstruct person name age sex)
3982 defines a struct type called @code{person} that contains three
3983 slots. Given a @code{person} object @var{p}, you can access those
3984 slots by calling @code{(person-name @var{p})}, @code{(person-age @var{p})},
3985 and @code{(person-sex @var{p})}. You can also change these slots by
3986 using @code{setf} on any of these place forms, for example:
3989 (cl-incf (person-age birthday-boy))
3992 You can create a new @code{person} by calling @code{make-person},
3993 which takes keyword arguments @code{:name}, @code{:age}, and
3994 @code{:sex} to specify the initial values of these slots in the
3995 new object. (Omitting any of these arguments leaves the corresponding
3996 slot ``undefined'', according to the Common Lisp standard; in Emacs
3997 Lisp, such uninitialized slots are filled with @code{nil}.)
3999 Given a @code{person}, @code{(copy-person @var{p})} makes a new
4000 object of the same type whose slots are @code{eq} to those of @var{p}.
4002 Given any Lisp object @var{x}, @code{(person-p @var{x})} returns
4003 true if @var{x} is a @code{person}, and false otherwise.
4005 Accessors like @code{person-name} normally check their arguments
4006 (effectively using @code{person-p}) and signal an error if the
4007 argument is the wrong type. This check is affected by
4008 @code{(optimize (safety @dots{}))} declarations. Safety level 1,
4009 the default, uses a somewhat optimized check that will detect all
4010 incorrect arguments, but may use an uninformative error message
4011 (e.g., ``expected a vector'' instead of ``expected a @code{person}'').
4012 Safety level 0 omits all checks except as provided by the underlying
4013 @code{aref} call; safety levels 2 and 3 do rigorous checking that will
4014 always print a descriptive error message for incorrect inputs.
4015 @xref{Declarations}.
4018 (setq dave (make-person :name "Dave" :sex 'male))
4019 @result{} [cl-struct-person "Dave" nil male]
4020 (setq other (copy-person dave))
4021 @result{} [cl-struct-person "Dave" nil male]
4024 (eq (person-name dave) (person-name other))
4028 (person-p [1 2 3 4])
4032 (person-p '[cl-struct-person counterfeit person object])
4036 In general, @var{name} is either a name symbol or a list of a name
4037 symbol followed by any number of @dfn{struct options}; each @var{slot}
4038 is either a slot symbol or a list of the form @samp{(@var{slot-name}
4039 @var{default-value} @var{slot-options}@dots{})}. The @var{default-value}
4040 is a Lisp form that is evaluated any time an instance of the
4041 structure type is created without specifying that slot's value.
4043 Common Lisp defines several slot options, but the only one
4044 implemented in this package is @code{:read-only}. A non-@code{nil}
4045 value for this option means the slot should not be @code{setf}-able;
4046 the slot's value is determined when the object is created and does
4047 not change afterward.
4050 (cl-defstruct person
4051 (name nil :read-only t)
4056 Any slot options other than @code{:read-only} are ignored.
4058 For obscure historical reasons, structure options take a different
4059 form than slot options. A structure option is either a keyword
4060 symbol, or a list beginning with a keyword symbol possibly followed
4061 by arguments. (By contrast, slot options are key-value pairs not
4065 (cl-defstruct (person (:constructor create-person)
4071 The following structure options are recognized.
4075 The argument is a symbol whose print name is used as the prefix for
4076 the names of slot accessor functions. The default is the name of
4077 the struct type followed by a hyphen. The option @code{(:conc-name p-)}
4078 would change this prefix to @code{p-}. Specifying @code{nil} as an
4079 argument means no prefix, so that the slot names themselves are used
4080 to name the accessor functions.
4083 In the simple case, this option takes one argument which is an
4084 alternate name to use for the constructor function. The default
4085 is @code{make-@var{name}}, e.g., @code{make-person}. The above
4086 example changes this to @code{create-person}. Specifying @code{nil}
4087 as an argument means that no standard constructor should be
4090 In the full form of this option, the constructor name is followed
4091 by an arbitrary argument list. @xref{Program Structure}, for a
4092 description of the format of Common Lisp argument lists. All
4093 options, such as @code{&rest} and @code{&key}, are supported.
4094 The argument names should match the slot names; each slot is
4095 initialized from the corresponding argument. Slots whose names
4096 do not appear in the argument list are initialized based on the
4097 @var{default-value} in their slot descriptor. Also, @code{&optional}
4098 and @code{&key} arguments that don't specify defaults take their
4099 defaults from the slot descriptor. It is valid to include arguments
4100 that don't correspond to slot names; these are useful if they are
4101 referred to in the defaults for optional, keyword, or @code{&aux}
4102 arguments that @emph{do} correspond to slots.
4104 You can specify any number of full-format @code{:constructor}
4105 options on a structure. The default constructor is still generated
4106 as well unless you disable it with a simple-format @code{:constructor}
4112 (:constructor nil) ; no default constructor
4113 (:constructor new-person
4114 (name sex &optional (age 0)))
4115 (:constructor new-hound (&key (name "Rover")
4117 &aux (age (* 7 dog-years))
4122 The first constructor here takes its arguments positionally rather
4123 than by keyword. (In official Common Lisp terminology, constructors
4124 that work By Order of Arguments instead of by keyword are called
4125 ``BOA constructors''. No, I'm not making this up.) For example,
4126 @code{(new-person "Jane" 'female)} generates a person whose slots
4127 are @code{"Jane"}, 0, and @code{female}, respectively.
4129 The second constructor takes two keyword arguments, @code{:name},
4130 which initializes the @code{name} slot and defaults to @code{"Rover"},
4131 and @code{:dog-years}, which does not itself correspond to a slot
4132 but which is used to initialize the @code{age} slot. The @code{sex}
4133 slot is forced to the symbol @code{canine} with no syntax for
4137 The argument is an alternate name for the copier function for
4138 this type. The default is @code{copy-@var{name}}. @code{nil}
4139 means not to generate a copier function. (In this implementation,
4140 all copier functions are simply synonyms for @code{copy-sequence}.)
4143 The argument is an alternate name for the predicate that recognizes
4144 objects of this type. The default is @code{@var{name}-p}. @code{nil}
4145 means not to generate a predicate function. (If the @code{:type}
4146 option is used without the @code{:named} option, no predicate is
4149 In true Common Lisp, @code{typep} is always able to recognize a
4150 structure object even if @code{:predicate} was used. In this
4151 package, @code{cl-typep} simply looks for a function called
4152 @code{@var{typename}-p}, so it will work for structure types
4153 only if they used the default predicate name.
4156 This option implements a very limited form of C++-style inheritance.
4157 The argument is the name of another structure type previously
4158 created with @code{cl-defstruct}. The effect is to cause the new
4159 structure type to inherit all of the included structure's slots
4160 (plus, of course, any new slots described by this struct's slot
4161 descriptors). The new structure is considered a ``specialization''
4162 of the included one. In fact, the predicate and slot accessors
4163 for the included type will also accept objects of the new type.
4165 If there are extra arguments to the @code{:include} option after
4166 the included-structure name, these options are treated as replacement
4167 slot descriptors for slots in the included structure, possibly with
4168 modified default values. Borrowing an example from Steele:
4171 (cl-defstruct person name (age 0) sex)
4173 (cl-defstruct (astronaut (:include person (age 45)))
4175 (favorite-beverage 'tang))
4178 (setq joe (make-person :name "Joe"))
4179 @result{} [cl-struct-person "Joe" 0 nil]
4180 (setq buzz (make-astronaut :name "Buzz"))
4181 @result{} [cl-struct-astronaut "Buzz" 45 nil nil tang]
4183 (list (person-p joe) (person-p buzz))
4185 (list (astronaut-p joe) (astronaut-p buzz))
4190 (astronaut-name joe)
4191 @result{} error: "astronaut-name accessing a non-astronaut"
4194 Thus, if @code{astronaut} is a specialization of @code{person},
4195 then every @code{astronaut} is also a @code{person} (but not the
4196 other way around). Every @code{astronaut} includes all the slots
4197 of a @code{person}, plus extra slots that are specific to
4198 astronauts. Operations that work on people (like @code{person-name})
4199 work on astronauts just like other people.
4201 @item :print-function
4202 In full Common Lisp, this option allows you to specify a function
4203 that is called to print an instance of the structure type. The
4204 Emacs Lisp system offers no hooks into the Lisp printer which would
4205 allow for such a feature, so this package simply ignores
4206 @code{:print-function}.
4209 The argument should be one of the symbols @code{vector} or
4210 @code{list}. This tells which underlying Lisp data type should be
4211 used to implement the new structure type. Records are used by
4212 default, but @code{(:type vector)} will cause structure objects to be
4213 stored as vectors and @code{(:type list)} lists instead.
4215 The record and vector representations for structure objects have the
4216 advantage that all structure slots can be accessed quickly, although
4217 creating them are a bit slower in Emacs Lisp. Lists are easier to
4218 create, but take a relatively long time accessing the later slots.
4221 This option, which takes no arguments, causes a characteristic ``tag''
4222 symbol to be stored at the front of the structure object. Using
4223 @code{:type} without also using @code{:named} will result in a
4224 structure type stored as plain vectors or lists with no identifying
4227 The default, if you don't specify @code{:type} explicitly, is to use
4228 records, which are always tagged. Therefore, @code{:named} is only
4229 useful in conjunction with @code{:type}.
4232 (cl-defstruct (person1) name age sex)
4233 (cl-defstruct (person2 (:type list) :named) name age sex)
4234 (cl-defstruct (person3 (:type list)) name age sex)
4235 (cl-defstruct (person4 (:type vector)) name age sex)
4237 (setq p1 (make-person1))
4238 @result{} #s(person1 nil nil nil)
4239 (setq p2 (make-person2))
4240 @result{} (person2 nil nil nil)
4241 (setq p3 (make-person3))
4242 @result{} (nil nil nil)
4243 (setq p4 (make-person4))
4244 @result{} [nil nil nil]
4251 @result{} error: function person3-p undefined
4254 Since unnamed structures don't have tags, @code{cl-defstruct} is not
4255 able to make a useful predicate for recognizing them. Also,
4256 accessors like @code{person3-name} will be generated but they
4257 will not be able to do any type checking. The @code{person3-name}
4258 function, for example, will simply be a synonym for @code{car} in
4259 this case. By contrast, @code{person2-name} is able to verify
4260 that its argument is indeed a @code{person2} object before
4263 @item :initial-offset
4264 The argument must be a nonnegative integer. It specifies a
4265 number of slots to be left ``empty'' at the front of the
4266 structure. If the structure is named, the tag appears at the
4267 specified position in the list or vector; otherwise, the first
4268 slot appears at that position. Earlier positions are filled
4269 with @code{nil} by the constructors and ignored otherwise. If
4270 the type @code{:include}s another type, then @code{:initial-offset}
4271 specifies a number of slots to be skipped between the last slot
4272 of the included type and the first new slot.
4276 Except as noted, the @code{cl-defstruct} facility of this package is
4277 entirely compatible with that of Common Lisp.
4279 The @code{cl-defstruct} package also provides a few structure
4280 introspection functions.
4282 @defun cl-struct-sequence-type struct-type
4283 This function returns the underlying data structure for
4284 @code{struct-type}, which is a symbol. It returns @code{record},
4285 @code{vector} or @code{list}, or @code{nil} if @code{struct-type} is
4286 not actually a structure.
4289 @defun cl-struct-slot-info struct-type
4290 This function returns a list of slot descriptors for structure
4291 @code{struct-type}. Each entry in the list is @code{(name . opts)},
4292 where @code{name} is the name of the slot and @code{opts} is the list
4293 of slot options given to @code{defstruct}. Dummy entries represent
4294 the slots used for the struct name and that are skipped to implement
4295 @code{:initial-offset}.
4298 @defun cl-struct-slot-offset struct-type slot-name
4299 Return the offset of slot @code{slot-name} in @code{struct-type}. The
4300 returned zero-based slot index is relative to the start of the
4301 structure data type and is adjusted for any structure name and
4302 :initial-offset slots. Signal error if struct @code{struct-type} does
4303 not contain @code{slot-name}.
4306 @defun cl-struct-slot-value struct-type slot-name inst
4307 Return the value of slot @code{slot-name} in @code{inst} of
4308 @code{struct-type}. @code{struct} and @code{slot-name} are symbols.
4309 @code{inst} is a structure instance. This routine is also a
4310 @code{setf} place. Can signal the same errors as @code{cl-struct-slot-offset}.
4314 @chapter Assertions and Errors
4317 This section describes two macros that test @dfn{assertions}, i.e.,
4318 conditions which must be true if the program is operating correctly.
4319 Assertions never add to the behavior of a Lisp program; they simply
4320 make ``sanity checks'' to make sure everything is as it should be.
4322 If the optimization property @code{speed} has been set to 3, and
4323 @code{safety} is less than 3, then the byte-compiler will optimize
4324 away the following assertions. Because assertions might be optimized
4325 away, it is a bad idea for them to include side-effects.
4327 @defmac cl-assert test-form [show-args string args@dots{}]
4328 This form verifies that @var{test-form} is true (i.e., evaluates to
4329 a non-@code{nil} value). If so, it returns @code{nil}. If the test
4330 is not satisfied, @code{cl-assert} signals an error.
4332 A default error message will be supplied which includes @var{test-form}.
4333 You can specify a different error message by including a @var{string}
4334 argument plus optional extra arguments. Those arguments are simply
4335 passed to @code{error} to signal the error.
4337 If the optional second argument @var{show-args} is @code{t} instead
4338 of @code{nil}, then the error message (with or without @var{string})
4339 will also include all non-constant arguments of the top-level
4340 @var{form}. For example:
4343 (cl-assert (> x 10) t "x is too small: %d")
4346 This usage of @var{show-args} is an extension to Common Lisp. In
4347 true Common Lisp, the second argument gives a list of @var{places}
4348 which can be @code{setf}'d by the user before continuing from the
4349 error. Since Emacs Lisp does not support continuable errors, it
4350 makes no sense to specify @var{places}.
4353 @defmac cl-check-type form type [string]
4354 This form verifies that @var{form} evaluates to a value of type
4355 @var{type}. If so, it returns @code{nil}. If not, @code{cl-check-type}
4356 signals a @code{wrong-type-argument} error. The default error message
4357 lists the erroneous value along with @var{type} and @var{form}
4358 themselves. If @var{string} is specified, it is included in the
4359 error message in place of @var{type}. For example:
4362 (cl-check-type x (integer 1 *) "a positive integer")
4365 @xref{Type Predicates}, for a description of the type specifiers
4366 that may be used for @var{type}.
4368 Note that in Common Lisp, the first argument to @code{check-type}
4369 must be a @var{place} suitable for use by @code{setf}, because
4370 @code{check-type} signals a continuable error that allows the
4371 user to modify @var{place}.
4374 @node Efficiency Concerns
4375 @appendix Efficiency Concerns
4380 Many of the advanced features of this package, such as @code{cl-defun},
4381 @code{cl-loop}, etc., are implemented as Lisp macros. In
4382 byte-compiled code, these complex notations will be expanded into
4383 equivalent Lisp code which is simple and efficient. For example,
4391 is expanded at compile-time to the Lisp form
4398 which is the most efficient way of doing this operation
4399 in Lisp. Thus, there is no performance penalty for using the more
4400 readable @code{cl-incf} form in your compiled code.
4402 @emph{Interpreted} code, on the other hand, must expand these macros
4403 every time they are executed. For this reason it is strongly
4404 recommended that code making heavy use of macros be compiled.
4405 A loop using @code{cl-incf} a hundred times will execute considerably
4406 faster if compiled, and will also garbage-collect less because the
4407 macro expansion will not have to be generated, used, and thrown away a
4410 You can find out how a macro expands by using the
4411 @code{cl-prettyexpand} function.
4413 @defun cl-prettyexpand form &optional full
4414 This function takes a single Lisp form as an argument and inserts
4415 a nicely formatted copy of it in the current buffer (which must be
4416 in Lisp mode so that indentation works properly). It also expands
4417 all Lisp macros that appear in the form. The easiest way to use
4418 this function is to go to the @file{*scratch*} buffer and type, say,
4421 (cl-prettyexpand '(cl-loop for x below 10 collect x))
4425 and type @kbd{C-x C-e} immediately after the closing parenthesis;
4426 an expansion similar to:
4433 (setq G1004 (cons x G1004))
4439 will be inserted into the buffer. (The @code{cl-block} macro is
4440 expanded differently in the interpreter and compiler, so
4441 @code{cl-prettyexpand} just leaves it alone. The temporary
4442 variable @code{G1004} was created by @code{cl-gensym}.)
4444 If the optional argument @var{full} is true, then @emph{all}
4445 macros are expanded, including @code{cl-block}, @code{cl-eval-when},
4446 and compiler macros. Expansion is done as if @var{form} were
4447 a top-level form in a file being compiled.
4449 @c FIXME none of these examples are still applicable.
4454 (cl-prettyexpand '(cl-pushnew 'x list))
4455 @print{} (setq list (cl-adjoin 'x list))
4456 (cl-prettyexpand '(cl-pushnew 'x list) t)
4457 @print{} (setq list (if (memq 'x list) list (cons 'x list)))
4458 (cl-prettyexpand '(caddr (cl-member 'a list)) t)
4459 @print{} (car (cdr (cdr (memq 'a list))))
4463 Note that @code{cl-adjoin}, @code{cl-caddr}, and @code{cl-member} all
4464 have built-in compiler macros to optimize them in common cases.
4467 @appendixsec Error Checking
4470 Common Lisp compliance has in general not been sacrificed for the
4471 sake of efficiency. A few exceptions have been made for cases
4472 where substantial gains were possible at the expense of marginal
4475 The Common Lisp standard (as embodied in Steele's book) uses the
4476 phrase ``it is an error if'' to indicate a situation that is not
4477 supposed to arise in complying programs; implementations are strongly
4478 encouraged but not required to signal an error in these situations.
4479 This package sometimes omits such error checking in the interest of
4480 compactness and efficiency. For example, @code{cl-do} variable
4481 specifiers are supposed to be lists of one, two, or three forms; extra
4482 forms are ignored by this package rather than signaling a syntax
4483 error. Functions taking keyword arguments will accept an odd number
4484 of arguments, treating the trailing keyword as if it were followed by
4485 the value @code{nil}.
4487 Argument lists (as processed by @code{cl-defun} and friends)
4488 @emph{are} checked rigorously except for the minor point just
4489 mentioned; in particular, keyword arguments are checked for
4490 validity, and @code{&allow-other-keys} and @code{:allow-other-keys}
4491 are fully implemented. Keyword validity checking is slightly
4492 time consuming (though not too bad in byte-compiled code);
4493 you can use @code{&allow-other-keys} to omit this check. Functions
4494 defined in this package such as @code{cl-find} and @code{cl-member}
4495 do check their keyword arguments for validity.
4497 @appendixsec Compiler Optimizations
4500 Changing the value of @code{byte-optimize} from the default @code{t}
4501 is highly discouraged; many of the Common
4503 code that can be improved by optimization. In particular,
4504 @code{cl-block}s (whether explicit or implicit in constructs like
4505 @code{cl-defun} and @code{cl-loop}) carry a fair run-time penalty; the
4506 byte-compiler removes @code{cl-block}s that are not actually
4507 referenced by @code{cl-return} or @code{cl-return-from} inside the block.
4509 @node Common Lisp Compatibility
4510 @appendix Common Lisp Compatibility
4513 The following is a list of some of the most important
4514 incompatibilities between this package and Common Lisp as documented
4515 in Steele (2nd edition).
4517 The word @code{cl-defun} is required instead of @code{defun} in order
4518 to use extended Common Lisp argument lists in a function. Likewise,
4519 @code{cl-defmacro} and @code{cl-function} are versions of those forms
4520 which understand full-featured argument lists. The @code{&whole}
4521 keyword does not work in @code{cl-defmacro} argument lists (except
4522 inside recursive argument lists).
4524 The @code{equal} predicate does not distinguish
4525 between IEEE floating-point plus and minus zero. The @code{cl-equalp}
4526 predicate has several differences with Common Lisp; @pxref{Predicates}.
4528 The @code{cl-do-all-symbols} form is the same as @code{cl-do-symbols}
4529 with no @var{obarray} argument. In Common Lisp, this form would
4530 iterate over all symbols in all packages. Since Emacs obarrays
4531 are not a first-class package mechanism, there is no way for
4532 @code{cl-do-all-symbols} to locate any but the default obarray.
4534 The @code{cl-loop} macro is complete except that @code{loop-finish}
4535 and type specifiers are unimplemented.
4537 The multiple-value return facility treats lists as multiple
4538 values, since Emacs Lisp cannot support multiple return values
4539 directly. The macros will be compatible with Common Lisp if
4540 @code{cl-values} or @code{cl-values-list} is always used to return to
4541 a @code{cl-multiple-value-bind} or other multiple-value receiver;
4542 if @code{cl-values} is used without @code{cl-multiple-value-@dots{}}
4543 or vice-versa the effect will be different from Common Lisp.
4545 Many Common Lisp declarations are ignored, and others match
4546 the Common Lisp standard in concept but not in detail. For
4547 example, local @code{special} declarations, which are purely
4548 advisory in Emacs Lisp, do not rigorously obey the scoping rules
4549 set down in Steele's book.
4551 The variable @code{cl--gensym-counter} starts out with zero.
4553 The @code{cl-defstruct} facility is compatible, except that the
4554 @code{:type} slot option is ignored.
4556 The second argument of @code{cl-check-type} is treated differently.
4558 @node Porting Common Lisp
4559 @appendix Porting Common Lisp
4562 This package is meant to be used as an extension to Emacs Lisp,
4563 not as an Emacs implementation of true Common Lisp. Some of the
4564 remaining differences between Emacs Lisp and Common Lisp make it
4565 difficult to port large Common Lisp applications to Emacs. For
4566 one, some of the features in this package are not fully compliant
4567 with ANSI or Steele; @pxref{Common Lisp Compatibility}. But there
4568 are also quite a few features that this package does not provide
4569 at all. Here are some major omissions that you will want to watch out
4570 for when bringing Common Lisp code into Emacs.
4574 Case-insensitivity. Symbols in Common Lisp are case-insensitive
4575 by default. Some programs refer to a function or variable as
4576 @code{foo} in one place and @code{Foo} or @code{FOO} in another.
4577 Emacs Lisp will treat these as three distinct symbols.
4579 Some Common Lisp code is written entirely in upper case. While Emacs
4580 is happy to let the program's own functions and variables use
4581 this convention, calls to Lisp builtins like @code{if} and
4582 @code{defun} will have to be changed to lower case.
4585 Lexical scoping. In Common Lisp, function arguments and @code{let}
4586 bindings apply only to references physically within their bodies (or
4587 within macro expansions in their bodies). Traditionally, Emacs Lisp
4588 uses @dfn{dynamic scoping} wherein a binding to a variable is visible
4589 even inside functions called from the body.
4590 @xref{Dynamic Binding,,,elisp,GNU Emacs Lisp Reference Manual}.
4591 Lexical binding is available since Emacs 24.1, so be sure to set
4592 @code{lexical-binding} to @code{t} if you need to emulate this aspect
4593 of Common Lisp. @xref{Lexical Binding,,,elisp,GNU Emacs Lisp Reference Manual}.
4595 Here is an example of a Common Lisp code fragment that would fail in
4596 Emacs Lisp if @code{lexical-binding} were set to @code{nil}:
4599 (defun map-odd-elements (func list)
4601 for flag = t then (not flag)
4602 collect (if flag x (funcall func x))))
4604 (defun add-odd-elements (list x)
4605 (map-odd-elements (lambda (a) (+ a x)) list))
4609 With lexical binding, the two functions' usages of @code{x} are
4610 completely independent. With dynamic binding, the binding to @code{x}
4611 made by @code{add-odd-elements} will have been hidden by the binding
4612 in @code{map-odd-elements} by the time the @code{(+ a x)} function is
4615 Internally, this package uses lexical binding so that such problems do
4616 not occur. @xref{Obsolete Lexical Binding}, for a description of the obsolete
4617 @code{lexical-let} form that emulates a Common Lisp-style lexical
4618 binding when dynamic binding is in use.
4621 Reader macros. Common Lisp includes a second type of macro that
4622 works at the level of individual characters. For example, Common
4623 Lisp implements the quote notation by a reader macro called @code{'},
4624 whereas Emacs Lisp's parser just treats quote as a special case.
4625 Some Lisp packages use reader macros to create special syntaxes
4626 for themselves, which the Emacs parser is incapable of reading.
4629 Other syntactic features. Common Lisp provides a number of
4630 notations beginning with @code{#} that the Emacs Lisp parser
4631 won't understand. For example, @samp{#| @dots{} |#} is an
4632 alternate comment notation, and @samp{#+lucid (foo)} tells
4633 the parser to ignore the @code{(foo)} except in Lucid Common
4637 Packages. In Common Lisp, symbols are divided into @dfn{packages}.
4638 Symbols that are Lisp built-ins are typically stored in one package;
4639 symbols that are vendor extensions are put in another, and each
4640 application program would have a package for its own symbols.
4641 Certain symbols are ``exported'' by a package and others are
4642 internal; certain packages ``use'' or import the exported symbols
4643 of other packages. To access symbols that would not normally be
4644 visible due to this importing and exporting, Common Lisp provides
4645 a syntax like @code{package:symbol} or @code{package::symbol}.
4647 Emacs Lisp has a single namespace for all interned symbols, and
4648 then uses a naming convention of putting a prefix like @code{cl-}
4649 in front of the name. Some Emacs packages adopt the Common Lisp-like
4650 convention of using @code{cl:} or @code{cl::} as the prefix.
4651 However, the Emacs parser does not understand colons and just
4652 treats them as part of the symbol name. Thus, while @code{mapcar}
4653 and @code{lisp:mapcar} may refer to the same symbol in Common
4654 Lisp, they are totally distinct in Emacs Lisp. Common Lisp
4655 programs that refer to a symbol by the full name sometimes
4656 and the short name other times will not port cleanly to Emacs.
4658 Emacs Lisp does have a concept of ``obarrays'', which are
4659 package-like collections of symbols, but this feature is not
4660 strong enough to be used as a true package mechanism.
4663 The @code{format} function is quite different between Common
4664 Lisp and Emacs Lisp. It takes an additional ``destination''
4665 argument before the format string. A destination of @code{nil}
4666 means to format to a string as in Emacs Lisp; a destination
4667 of @code{t} means to write to the terminal (similar to
4668 @code{message} in Emacs). Also, format control strings are
4669 utterly different; @code{~} is used instead of @code{%} to
4670 introduce format codes, and the set of available codes is
4671 much richer. There are no notations like @code{\n} for
4672 string literals; instead, @code{format} is used with the
4673 ``newline'' format code, @code{~%}. More advanced formatting
4674 codes provide such features as paragraph filling, case
4675 conversion, and even loops and conditionals.
4677 While it would have been possible to implement most of Common
4678 Lisp @code{format} in this package (under the name @code{cl-format},
4679 of course), it was not deemed worthwhile. It would have required
4680 a huge amount of code to implement even a decent subset of
4681 @code{format}, yet the functionality it would provide over
4682 Emacs Lisp's @code{format} would rarely be useful.
4685 Vector constants use square brackets in Emacs Lisp, but
4686 @code{#(a b c)} notation in Common Lisp. To further complicate
4687 matters, Emacs has its own @code{#(} notation for
4688 something entirely different---strings with properties.
4691 Characters are distinct from integers in Common Lisp. The notation
4692 for character constants is also different: @code{#\A} in Common Lisp
4693 where Emacs Lisp uses @code{?A}. Also, @code{string=} and
4694 @code{string-equal} are synonyms in Emacs Lisp, whereas the latter is
4695 case-insensitive in Common Lisp.
4698 Data types. Some Common Lisp data types do not exist in Emacs
4699 Lisp. Rational numbers and complex numbers are not present,
4700 nor are large integers (all integers are ``fixnums''). All
4701 arrays are one-dimensional. There are no readtables or pathnames;
4702 streams are a set of existing data types rather than a new data
4703 type of their own. Hash tables, random-states, and packages
4704 (obarrays) are built from Lisp vectors or lists rather than being
4708 The Common Lisp Object System (CLOS) is not implemented,
4709 nor is the Common Lisp Condition System. However, the EIEIO package
4710 (@pxref{Top, , Introduction, eieio, EIEIO}) does implement some
4714 Common Lisp features that are completely redundant with Emacs
4715 Lisp features of a different name generally have not been
4716 implemented. For example, Common Lisp writes @code{defconstant}
4717 where Emacs Lisp uses @code{defconst}. Similarly, @code{make-list}
4718 takes its arguments in different ways in the two Lisps but does
4719 exactly the same thing, so this package has not bothered to
4720 implement a Common Lisp-style @code{make-list}.
4723 A few more notable Common Lisp features not included in this package:
4724 @code{compiler-let}, @code{prog}, @code{ldb/dpb}, @code{cerror}.
4727 Recursion. While recursion works in Emacs Lisp just like it
4728 does in Common Lisp, various details of the Emacs Lisp system
4729 and compiler make recursion much less efficient than it is in
4730 most Lisps. Some schools of thought prefer to use recursion
4731 in Lisp over other techniques; they would sum a list of
4732 numbers using something like
4735 (defun sum-list (list)
4737 (+ (car list) (sum-list (cdr list)))
4742 where a more iteratively-minded programmer might write one of
4746 (let ((total 0)) (dolist (x my-list) (incf total x)) total)
4747 (loop for x in my-list sum x)
4750 While this would be mainly a stylistic choice in most Common Lisps,
4751 in Emacs Lisp you should be aware that the iterative forms are
4752 much faster than recursion. Also, Lisp programmers will want to
4753 note that the current Emacs Lisp compiler does not optimize tail
4757 @node Obsolete Features
4758 @appendix Obsolete Features
4760 This section describes some features of the package that are obsolete
4761 and should not be used in new code. They are either only provided by
4762 the old @file{cl.el} entry point, not by the newer @file{cl-lib.el};
4763 or where versions with a @samp{cl-} prefix do exist they do not behave
4764 in exactly the same way.
4767 * Obsolete Lexical Binding:: An approximation of lexical binding.
4768 * Obsolete Macros:: Obsolete macros.
4769 * Obsolete Setf Customization:: Obsolete ways to customize setf.
4772 @node Obsolete Lexical Binding
4773 @appendixsec Obsolete Lexical Binding
4775 The following macros are extensions to Common Lisp, where all bindings
4776 are lexical unless declared otherwise. These features are likewise
4777 obsolete since the introduction of true lexical binding in Emacs 24.1.
4779 @defmac lexical-let (bindings@dots{}) forms@dots{}
4780 This form is exactly like @code{let} except that the bindings it
4781 establishes are purely lexical.
4784 @c FIXME remove this and refer to elisp manual.
4785 @c Maybe merge some stuff from here to there?
4787 Lexical bindings are similar to local variables in a language like C:
4788 Only the code physically within the body of the @code{lexical-let}
4789 (after macro expansion) may refer to the bound variables.
4793 (defun foo (b) (+ a b))
4794 (let ((a 2)) (foo a))
4796 (lexical-let ((a 2)) (foo a))
4801 In this example, a regular @code{let} binding of @code{a} actually
4802 makes a temporary change to the global variable @code{a}, so @code{foo}
4803 is able to see the binding of @code{a} to 2. But @code{lexical-let}
4804 actually creates a distinct local variable @code{a} for use within its
4805 body, without any effect on the global variable of the same name.
4807 The most important use of lexical bindings is to create @dfn{closures}.
4808 A closure is a function object that refers to an outside lexical
4809 variable (@pxref{Closures,,,elisp,GNU Emacs Lisp Reference Manual}).
4813 (defun make-adder (n)
4814 (lexical-let ((n n))
4815 (function (lambda (m) (+ n m)))))
4816 (setq add17 (make-adder 17))
4822 The call @code{(make-adder 17)} returns a function object which adds
4823 17 to its argument. If @code{let} had been used instead of
4824 @code{lexical-let}, the function object would have referred to the
4825 global @code{n}, which would have been bound to 17 only during the
4826 call to @code{make-adder} itself.
4829 (defun make-counter ()
4830 (lexical-let ((n 0))
4831 (cl-function (lambda (&optional (m 1)) (cl-incf n m)))))
4832 (setq count-1 (make-counter))
4835 (funcall count-1 14)
4837 (setq count-2 (make-counter))
4847 Here we see that each call to @code{make-counter} creates a distinct
4848 local variable @code{n}, which serves as a private counter for the
4849 function object that is returned.
4851 Closed-over lexical variables persist until the last reference to
4852 them goes away, just like all other Lisp objects. For example,
4853 @code{count-2} refers to a function object which refers to an
4854 instance of the variable @code{n}; this is the only reference
4855 to that variable, so after @code{(setq count-2 nil)} the garbage
4856 collector would be able to delete this instance of @code{n}.
4857 Of course, if a @code{lexical-let} does not actually create any
4858 closures, then the lexical variables are free as soon as the
4859 @code{lexical-let} returns.
4861 Many closures are used only during the extent of the bindings they
4862 refer to; these are known as ``downward funargs'' in Lisp parlance.
4863 When a closure is used in this way, regular Emacs Lisp dynamic
4864 bindings suffice and will be more efficient than @code{lexical-let}
4868 (defun add-to-list (x list)
4869 (mapcar (lambda (y) (+ x y))) list)
4870 (add-to-list 7 '(1 2 5))
4875 Since this lambda is only used while @code{x} is still bound,
4876 it is not necessary to make a true closure out of it.
4878 You can use @code{defun} or @code{flet} inside a @code{lexical-let}
4879 to create a named closure. If several closures are created in the
4880 body of a single @code{lexical-let}, they all close over the same
4881 instance of the lexical variable.
4883 @defmac lexical-let* (bindings@dots{}) forms@dots{}
4884 This form is just like @code{lexical-let}, except that the bindings
4885 are made sequentially in the manner of @code{let*}.
4888 @node Obsolete Macros
4889 @appendixsec Obsolete Macros
4891 The following macros are obsolete, and are replaced by versions with
4892 a @samp{cl-} prefix that do not behave in exactly the same way.
4893 Consequently, the @file{cl.el} versions are not simply aliases to the
4894 @file{cl-lib.el} versions.
4896 @defmac flet (bindings@dots{}) forms@dots{}
4897 This macro is replaced by @code{cl-flet} (@pxref{Function Bindings}),
4898 which behaves the same way as Common Lisp's @code{flet}.
4899 This @code{flet} takes the same arguments as @code{cl-flet}, but does
4900 not behave in precisely the same way.
4902 While @code{flet} in Common Lisp establishes a lexical function
4903 binding, this @code{flet} makes a dynamic binding (it dates from a
4904 time before Emacs had lexical binding). The result is
4905 that @code{flet} affects indirect calls to a function as well as calls
4906 directly inside the @code{flet} form itself.
4908 This will even work on Emacs primitives, although note that some calls
4909 to primitive functions internal to Emacs are made without going
4910 through the symbol's function cell, and so will not be affected by
4911 @code{flet}. For example,
4914 (flet ((message (&rest args) (push args saved-msgs)))
4918 This code attempts to replace the built-in function @code{message}
4919 with a function that simply saves the messages in a list rather
4920 than displaying them. The original definition of @code{message}
4921 will be restored after @code{do-something} exits. This code will
4922 work fine on messages generated by other Lisp code, but messages
4923 generated directly inside Emacs will not be caught since they make
4924 direct C-language calls to the message routines rather than going
4925 through the Lisp @code{message} function.
4927 For those cases where the dynamic scoping of @code{flet} is desired,
4928 @code{cl-flet} is clearly not a substitute. The most direct replacement would
4929 be instead to use @code{cl-letf} to temporarily rebind @code{(symbol-function
4930 '@var{fun})}. But in most cases, a better substitute is to use advice, such
4934 (defvar my-fun-advice-enable nil)
4935 (add-advice '@var{fun} :around
4936 (lambda (orig &rest args)
4937 (if my-fun-advice-enable (do-something)
4938 (apply orig args))))
4941 so that you can then replace the @code{flet} with a simple dynamically scoped
4942 binding of @code{my-fun-advice-enable}.
4945 Note that many primitives (e.g., @code{+}) have special byte-compile handling.
4946 Attempts to redefine such functions using @code{flet}, @code{cl-letf}, or
4947 advice will fail when byte-compiled.
4949 @c In such cases, use @code{labels} instead.
4952 @defmac labels (bindings@dots{}) forms@dots{}
4953 This macro is replaced by @code{cl-labels} (@pxref{Function Bindings}),
4954 which behaves the same way as Common Lisp's @code{labels}.
4955 This @code{labels} takes the same arguments as @code{cl-labels}, but
4956 does not behave in precisely the same way.
4958 This version of @code{labels} uses the obsolete @code{lexical-let}
4959 form (@pxref{Obsolete Lexical Binding}), rather than the true
4960 lexical binding that @code{cl-labels} uses.
4963 @node Obsolete Setf Customization
4964 @appendixsec Obsolete Ways to Customize Setf
4966 Common Lisp defines three macros, @code{define-modify-macro},
4967 @code{defsetf}, and @code{define-setf-method}, that allow the
4968 user to extend generalized variables in various ways.
4969 In Emacs, these are obsolete, replaced by various features of
4970 @file{gv.el} in Emacs 24.3.
4971 @xref{Adding Generalized Variables,,,elisp,GNU Emacs Lisp Reference Manual}.
4974 @defmac define-modify-macro name arglist function [doc-string]
4975 This macro defines a ``read-modify-write'' macro similar to
4976 @code{cl-incf} and @code{cl-decf}. You can replace this macro
4977 with @code{gv-letplace}.
4979 The macro @var{name} is defined to take a @var{place} argument
4980 followed by additional arguments described by @var{arglist}. The call
4983 (@var{name} @var{place} @var{args}@dots{})
4990 (cl-callf @var{func} @var{place} @var{args}@dots{})
4994 which in turn is roughly equivalent to
4997 (setf @var{place} (@var{func} @var{place} @var{args}@dots{}))
5003 (define-modify-macro incf (&optional (n 1)) +)
5004 (define-modify-macro concatf (&rest args) concat)
5007 Note that @code{&key} is not allowed in @var{arglist}, but
5008 @code{&rest} is sufficient to pass keywords on to the function.
5010 Most of the modify macros defined by Common Lisp do not exactly
5011 follow the pattern of @code{define-modify-macro}. For example,
5012 @code{push} takes its arguments in the wrong order, and @code{pop}
5013 is completely irregular.
5015 The above @code{incf} example could be written using
5016 @code{gv-letplace} as:
5018 (defmacro incf (place &optional n)
5019 (gv-letplace (getter setter) place
5020 (macroexp-let2 nil v (or n 1)
5021 (funcall setter `(+ ,v ,getter)))))
5024 (defmacro concatf (place &rest args)
5025 (gv-letplace (getter setter) place
5026 (macroexp-let2 nil v (mapconcat 'identity args "")
5027 (funcall setter `(concat ,getter ,v)))))
5031 @defmac defsetf access-fn update-fn
5032 This is the simpler of two @code{defsetf} forms, and is
5033 replaced by @code{gv-define-simple-setter}.
5035 With @var{access-fn} the name of a function that accesses a place,
5036 this declares @var{update-fn} to be the corresponding store function.
5040 (setf (@var{access-fn} @var{arg1} @var{arg2} @var{arg3}) @var{value})
5047 (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} @var{value})
5051 The @var{update-fn} is required to be either a true function, or
5052 a macro that evaluates its arguments in a function-like way. Also,
5053 the @var{update-fn} is expected to return @var{value} as its result.
5054 Otherwise, the above expansion would not obey the rules for the way
5055 @code{setf} is supposed to behave.
5057 As a special (non-Common-Lisp) extension, a third argument of @code{t}
5058 to @code{defsetf} says that the return value of @code{update-fn} is
5059 not suitable, so that the above @code{setf} should be expanded to
5063 (let ((temp @var{value}))
5064 (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} temp)
5071 (defsetf car setcar)
5072 (defsetf buffer-name rename-buffer t)
5075 These translate directly to @code{gv-define-simple-setter}:
5078 (gv-define-simple-setter car setcar)
5079 (gv-define-simple-setter buffer-name rename-buffer t)
5083 @defmac defsetf access-fn arglist (store-var) forms@dots{}
5084 This is the second, more complex, form of @code{defsetf}.
5085 It can be replaced by @code{gv-define-setter}.
5087 This form of @code{defsetf} is rather like @code{defmacro} except for
5088 the additional @var{store-var} argument. The @var{forms} should
5089 return a Lisp form that stores the value of @var{store-var} into the
5090 generalized variable formed by a call to @var{access-fn} with
5091 arguments described by @var{arglist}. The @var{forms} may begin with
5092 a string which documents the @code{setf} method (analogous to the doc
5093 string that appears at the front of a function).
5095 For example, the simple form of @code{defsetf} is shorthand for
5098 (defsetf @var{access-fn} (&rest args) (store)
5099 (append '(@var{update-fn}) args (list store)))
5102 The Lisp form that is returned can access the arguments from
5103 @var{arglist} and @var{store-var} in an unrestricted fashion;
5104 macros like @code{cl-incf} that invoke this
5105 setf-method will insert temporary variables as needed to make
5106 sure the apparent order of evaluation is preserved.
5108 Another standard example:
5111 (defsetf nth (n x) (store)
5112 `(setcar (nthcdr ,n ,x) ,store))
5115 You could write this using @code{gv-define-setter} as:
5118 (gv-define-setter nth (store n x)
5119 `(setcar (nthcdr ,n ,x) ,store))
5123 @defmac define-setf-method access-fn arglist forms@dots{}
5124 This is the most general way to create new place forms. You can
5125 replace this by @code{gv-define-setter} or @code{gv-define-expander}.
5127 When a @code{setf} to @var{access-fn} with arguments described by
5128 @var{arglist} is expanded, the @var{forms} are evaluated and must
5129 return a list of five items:
5133 A list of @dfn{temporary variables}.
5136 A list of @dfn{value forms} corresponding to the temporary variables
5137 above. The temporary variables will be bound to these value forms
5138 as the first step of any operation on the generalized variable.
5141 A list of exactly one @dfn{store variable} (generally obtained
5142 from a call to @code{gensym}).
5145 A Lisp form that stores the contents of the store variable into
5146 the generalized variable, assuming the temporaries have been
5147 bound as described above.
5150 A Lisp form that accesses the contents of the generalized variable,
5151 assuming the temporaries have been bound.
5154 This is exactly like the Common Lisp macro of the same name,
5155 except that the method returns a list of five values rather
5156 than the five values themselves, since Emacs Lisp does not
5157 support Common Lisp's notion of multiple return values.
5158 (Note that the @code{setf} implementation provided by @file{gv.el}
5159 does not use this five item format. Its use here is only for
5160 backwards compatibility.)
5162 Once again, the @var{forms} may begin with a documentation string.
5164 A setf-method should be maximally conservative with regard to
5165 temporary variables. In the setf-methods generated by
5166 @code{defsetf}, the second return value is simply the list of
5167 arguments in the place form, and the first return value is a
5168 list of a corresponding number of temporary variables generated
5169 @c FIXME I don't think this is true anymore.
5170 by @code{cl-gensym}. Macros like @code{cl-incf} that
5171 use this setf-method will optimize away most temporaries that
5172 turn out to be unnecessary, so there is little reason for the
5173 setf-method itself to optimize.
5176 @c Removed in Emacs 24.3, not possible to make a compatible replacement.
5178 @defun get-setf-method place &optional env
5179 This function returns the setf-method for @var{place}, by
5180 invoking the definition previously recorded by @code{defsetf}
5181 or @code{define-setf-method}. The result is a list of five
5182 values as described above. You can use this function to build
5183 your own @code{cl-incf}-like modify macros.
5185 The argument @var{env} specifies the ``environment'' to be
5186 passed on to @code{macroexpand} if @code{get-setf-method} should
5187 need to expand a macro in @var{place}. It should come from
5188 an @code{&environment} argument to the macro or setf-method
5189 that called @code{get-setf-method}.
5194 @node GNU Free Documentation License
5195 @appendix GNU Free Documentation License
5196 @include doclicense.texi
5198 @node Function Index
5199 @unnumbered Function Index
5202 @node Variable Index
5203 @unnumbered Variable Index
5207 @unnumbered Concept Index