1 \input texinfo @c -*-texinfo-*-
2 @setfilename ../../info/cl
3 @settitle Common Lisp Extensions
7 This file documents the GNU Emacs Common Lisp emulation package.
9 Copyright @copyright{} 1993, 2001-2012 Free Software Foundation, Inc.
12 Permission is granted to copy, distribute and/or modify this document
13 under the terms of the GNU Free Documentation License, Version 1.3 or
14 any later version published by the Free Software Foundation; with no
15 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
16 and with the Back-Cover Texts as in (a) below. A copy of the license
17 is included in the section entitled ``GNU Free Documentation License''.
19 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
20 modify this GNU manual. Buying copies from the FSF supports it in
21 developing GNU and promoting software freedom.''
25 @dircategory Emacs lisp libraries
27 * CL: (cl). Partial Common Lisp support for Emacs Lisp.
34 @center @titlefont{Common Lisp Extensions}
36 @center For GNU Emacs Lisp
38 @center as distributed with Emacs @value{EMACSVER}
40 @center Dave Gillespie
41 @center daveg@@synaptics.com
43 @vskip 0pt plus 1filll
51 @top GNU Emacs Common Lisp Emulation
57 * Overview:: Basics, usage, etc.
58 * Program Structure:: Arglists, @code{cl-eval-when}, @code{defalias}.
59 * Predicates:: @code{cl-typep} and @code{cl-equalp}.
60 * Control Structure:: @code{cl-do}, @code{cl-loop}, etc.
61 * Macros:: Destructuring, @code{cl-define-compiler-macro}.
62 * Declarations:: @code{cl-proclaim}, @code{cl-declare}, etc.
63 * Symbols:: Property lists, @code{cl-gensym}.
64 * Numbers:: Predicates, functions, random numbers.
65 * Sequences:: Mapping, functions, searching, sorting.
66 * Lists:: @code{cl-caddr}, @code{cl-sublis}, @code{cl-member}, @code{cl-assoc}, etc.
67 * Structures:: @code{cl-defstruct}.
68 * Assertions:: @code{cl-check-type}, @code{cl-assert}.
70 * Efficiency Concerns:: Hints and techniques.
71 * Common Lisp Compatibility:: All known differences with Steele.
72 * Porting Common Lisp:: Hints for porting Common Lisp code.
73 * Obsolete Features:: Obsolete features.
75 * GNU Free Documentation License:: The license for this documentation.
84 This document describes a set of Emacs Lisp facilities borrowed from
85 Common Lisp. All the facilities are described here in detail. While
86 this document does not assume any prior knowledge of Common Lisp, it
87 does assume a basic familiarity with Emacs Lisp.
89 Common Lisp is a huge language, and Common Lisp systems tend to be
90 massive and extremely complex. Emacs Lisp, by contrast, is rather
91 minimalist in the choice of Lisp features it offers the programmer.
92 As Emacs Lisp programmers have grown in number, and the applications
93 they write have grown more ambitious, it has become clear that Emacs
94 Lisp could benefit from many of the conveniences of Common Lisp.
96 The @code{CL} package adds a number of Common Lisp functions and
97 control structures to Emacs Lisp. While not a 100% complete
98 implementation of Common Lisp, @code{CL} adds enough functionality
99 to make Emacs Lisp programming significantly more convenient.
101 Some Common Lisp features have been omitted from this package
106 Some features are too complex or bulky relative to their benefit
107 to Emacs Lisp programmers. CLOS and Common Lisp streams are fine
108 examples of this group.
111 Other features cannot be implemented without modification to the
112 Emacs Lisp interpreter itself, such as multiple return values,
113 case-insensitive symbols, and complex numbers.
114 The @code{CL} package generally makes no attempt to emulate these
119 This package was originally written by Dave Gillespie,
120 @file{daveg@@synaptics.com}, as a total rewrite of an earlier 1986
121 @file{cl.el} package by Cesar Quiroz. Care has been taken to ensure
122 that each function is defined efficiently, concisely, and with minimal
123 impact on the rest of the Emacs environment. Stefan Monnier added the
124 file @file{cl-lib.el} and rationalized the namespace for Emacs 24.3.
127 * Usage:: How to use the CL package.
128 * Organization:: The package's component files.
129 * Naming Conventions:: Notes on CL function names.
136 The @code{CL} package is distributed with Emacs, so there is no need
137 to install any additional files in order to start using it. Lisp code
138 that uses features from the @code{CL} package should simply include at
146 You may wish to add such a statement to your init file, if you
147 make frequent use of CL features.
150 @section Organization
153 The Common Lisp package is organized into four main files:
157 This is the main file, which contains basic functions
158 and information about the package. This file is relatively compact.
161 This file contains the larger, more complex or unusual functions.
162 It is kept separate so that packages which only want to use Common
163 Lisp fundamentals like the @code{cl-incf} function won't need to pay
164 the overhead of loading the more advanced functions.
167 This file contains most of the advanced functions for operating
168 on sequences or lists, such as @code{cl-delete-if} and @code{cl-assoc}.
171 This file contains the features that are macros instead of functions.
172 Macros expand when the caller is compiled, not when it is run, so the
173 macros generally only need to be present when the byte-compiler is
174 running (or when the macros are used in uncompiled code). Most of the
175 macros of this package are isolated in @file{cl-macs.el} so that they
176 won't take up memory unless you are compiling.
179 The file @file{cl-lib.el} includes all necessary @code{autoload}
180 commands for the functions and macros in the other three files.
181 All you have to do is @code{(require 'cl-lib)}, and @file{cl-lib.el}
182 will take care of pulling in the other files when they are
185 There is another file, @file{cl.el}, which was the main entry point to
186 the CL package prior to Emacs 24.3. Nowadays, it is replaced by
187 @file{cl-lib.el}. The two provide the same features (in most cases),
188 but use different function names (in fact, @file{cl.el} mainly just
189 defines aliases to the @file{cl-lib.el} definitions). Where
190 @file{cl-lib.el} defines a function called, for example,
191 @code{cl-incf}, @file{cl.el} uses the same name but without the
192 @samp{cl-} prefix, e.g. @code{incf} in this example. There are a few
193 exceptions to this. First, functions such as @code{cl-defun} where
194 the unprefixed version was already used for a standard Emacs Lisp
195 function. In such cases, the @file{cl.el} version adds a @samp{*}
196 suffix, e.g. @code{defun*}. Second, there are some obsolete features
197 that are only implemented in @file{cl.el}, not in @file{cl-lib.el},
198 because they are replaced by other standard Emacs Lisp features.
199 Finally, in a very few cases the old @file{cl.el} versions do not
200 behave in exactly the same way as the @file{cl-lib.el} versions.
201 @xref{Obsolete Features}.
202 @c There is also cl-mapc, which was called cl-mapc even before cl-lib.el.
203 @c But not autoloaded, so maybe not much used?
205 Since the old @file{cl.el} does not use a clean namespace, Emacs has a
206 policy that packages distributed with Emacs must not load @code{cl} at
207 run time. (It is ok for them to load @code{cl} at @emph{compile}
208 time, with @code{eval-when-compile}, and use the macros it provides.)
209 There is no such restriction on the use of @code{cl-lib}. New code
210 should use @code{cl-lib} rather than @code{cl}.
212 There is one more file, @file{cl-compat.el}, which defines some
213 routines from the older Quiroz CL package that are not otherwise
214 present in the new package. This file is obsolete and should not be
217 @node Naming Conventions
218 @section Naming Conventions
221 Except where noted, all functions defined by this package have the
222 same calling conventions as their Common Lisp counterparts, and
223 names that are those of Common Lisp plus a @samp{cl-} prefix.
225 Internal function and variable names in the package are prefixed
226 by @code{cl--}. Here is a complete list of functions prefixed by
227 @code{cl-} that were not taken from Common Lisp:
230 cl-callf cl-callf2 cl-defsubst
231 cl-floatp-safe cl-letf cl-letf*
234 The following simple functions and macros are defined in @file{cl-lib.el};
235 they do not cause other components like @file{cl-extra} to be loaded.
238 cl-floatp-safe cl-endp
239 cl-evenp cl-oddp cl-plusp cl-minusp
240 cl-caaar .. cl-cddddr
241 cl-list* cl-ldiff cl-rest cl-first .. cl-tenth
242 cl-copy-list cl-subst cl-mapcar [2]
243 cl-adjoin [3] cl-acons cl-pairlis
244 cl-pushnew [3,4] cl-incf [4] cl-decf [4]
245 cl-proclaim cl-declaim
249 [2] Only for one sequence argument or two list arguments.
252 [3] Only if @code{:test} is @code{eq}, @code{equal}, or unspecified,
253 and @code{:key} is not used.
256 [4] Only when @var{place} is a plain variable name.
258 @node Program Structure
259 @chapter Program Structure
262 This section describes features of the @code{CL} package that have to
263 do with programs as a whole: advanced argument lists for functions,
264 and the @code{cl-eval-when} construct.
267 * Argument Lists:: @code{&key}, @code{&aux}, @code{cl-defun}, @code{cl-defmacro}.
268 * Time of Evaluation:: The @code{cl-eval-when} construct.
272 @section Argument Lists
275 Emacs Lisp's notation for argument lists of functions is a subset of
276 the Common Lisp notation. As well as the familiar @code{&optional}
277 and @code{&rest} markers, Common Lisp allows you to specify default
278 values for optional arguments, and it provides the additional markers
279 @code{&key} and @code{&aux}.
281 Since argument parsing is built-in to Emacs, there is no way for
282 this package to implement Common Lisp argument lists seamlessly.
283 Instead, this package defines alternates for several Lisp forms
284 which you must use if you need Common Lisp argument lists.
286 @defmac cl-defun name arglist body...
287 This form is identical to the regular @code{defun} form, except
288 that @var{arglist} is allowed to be a full Common Lisp argument
289 list. Also, the function body is enclosed in an implicit block
290 called @var{name}; @pxref{Blocks and Exits}.
293 @defmac cl-defsubst name arglist body...
294 This is just like @code{cl-defun}, except that the function that
295 is defined is automatically proclaimed @code{inline}, i.e.,
296 calls to it may be expanded into in-line code by the byte compiler.
297 This is analogous to the @code{defsubst} form;
298 @code{cl-defsubst} uses a different method (compiler macros) which
299 works in all versions of Emacs, and also generates somewhat more
300 efficient inline expansions. In particular, @code{cl-defsubst}
301 arranges for the processing of keyword arguments, default values,
302 etc., to be done at compile-time whenever possible.
305 @defmac cl-defmacro name arglist body...
306 This is identical to the regular @code{defmacro} form,
307 except that @var{arglist} is allowed to be a full Common Lisp
308 argument list. The @code{&environment} keyword is supported as
309 described in Steele. The @code{&whole} keyword is supported only
310 within destructured lists (see below); top-level @code{&whole}
311 cannot be implemented with the current Emacs Lisp interpreter.
312 The macro expander body is enclosed in an implicit block called
316 @defmac cl-function symbol-or-lambda
317 This is identical to the regular @code{function} form,
318 except that if the argument is a @code{lambda} form then that
319 form may use a full Common Lisp argument list.
322 Also, all forms (such as @code{cl-flet} and @code{cl-labels}) defined
323 in this package that include @var{arglist}s in their syntax allow
324 full Common Lisp argument lists.
326 Note that it is @emph{not} necessary to use @code{cl-defun} in
327 order to have access to most @code{CL} features in your function.
328 These features are always present; @code{cl-defun}'s only
329 difference from @code{defun} is its more flexible argument
330 lists and its implicit block.
332 The full form of a Common Lisp argument list is
336 &optional (@var{var} @var{initform} @var{svar})...
338 &key ((@var{keyword} @var{var}) @var{initform} @var{svar})...
339 &aux (@var{var} @var{initform})...)
342 Each of the five argument list sections is optional. The @var{svar},
343 @var{initform}, and @var{keyword} parts are optional; if they are
344 omitted, then @samp{(@var{var})} may be written simply @samp{@var{var}}.
346 The first section consists of zero or more @dfn{required} arguments.
347 These arguments must always be specified in a call to the function;
348 there is no difference between Emacs Lisp and Common Lisp as far as
349 required arguments are concerned.
351 The second section consists of @dfn{optional} arguments. These
352 arguments may be specified in the function call; if they are not,
353 @var{initform} specifies the default value used for the argument.
354 (No @var{initform} means to use @code{nil} as the default.) The
355 @var{initform} is evaluated with the bindings for the preceding
356 arguments already established; @code{(a &optional (b (1+ a)))}
357 matches one or two arguments, with the second argument defaulting
358 to one plus the first argument. If the @var{svar} is specified,
359 it is an auxiliary variable which is bound to @code{t} if the optional
360 argument was specified, or to @code{nil} if the argument was omitted.
361 If you don't use an @var{svar}, then there will be no way for your
362 function to tell whether it was called with no argument, or with
363 the default value passed explicitly as an argument.
365 The third section consists of a single @dfn{rest} argument. If
366 more arguments were passed to the function than are accounted for
367 by the required and optional arguments, those extra arguments are
368 collected into a list and bound to the ``rest'' argument variable.
369 Common Lisp's @code{&rest} is equivalent to that of Emacs Lisp.
370 Common Lisp accepts @code{&body} as a synonym for @code{&rest} in
371 macro contexts; this package accepts it all the time.
373 The fourth section consists of @dfn{keyword} arguments. These
374 are optional arguments which are specified by name rather than
375 positionally in the argument list. For example,
378 (cl-defun foo (a &optional b &key c d (e 17)))
382 defines a function which may be called with one, two, or more
383 arguments. The first two arguments are bound to @code{a} and
384 @code{b} in the usual way. The remaining arguments must be
385 pairs of the form @code{:c}, @code{:d}, or @code{:e} followed
386 by the value to be bound to the corresponding argument variable.
387 (Symbols whose names begin with a colon are called @dfn{keywords},
388 and they are self-quoting in the same way as @code{nil} and
391 For example, the call @code{(foo 1 2 :d 3 :c 4)} sets the five
392 arguments to 1, 2, 4, 3, and 17, respectively. If the same keyword
393 appears more than once in the function call, the first occurrence
394 takes precedence over the later ones. Note that it is not possible
395 to specify keyword arguments without specifying the optional
396 argument @code{b} as well, since @code{(foo 1 :c 2)} would bind
397 @code{b} to the keyword @code{:c}, then signal an error because
398 @code{2} is not a valid keyword.
400 You can also explicitly specify the keyword argument; it need not be
401 simply the variable name prefixed with a colon. For example,
404 (cl-defun bar (&key (a 1) ((baz b) 4)))
409 specifies a keyword @code{:a} that sets the variable @code{a} with
410 default value 1, as well as a keyword @code{baz} that sets the
411 variable @code{b} with default value 4. In this case, because
412 @code{baz} is not self-quoting, you must quote it explicitly in the
413 function call, like this:
419 Ordinarily, it is an error to pass an unrecognized keyword to
420 a function, e.g., @code{(foo 1 2 :c 3 :goober 4)}. You can ask
421 Lisp to ignore unrecognized keywords, either by adding the
422 marker @code{&allow-other-keys} after the keyword section
423 of the argument list, or by specifying an @code{:allow-other-keys}
424 argument in the call whose value is non-@code{nil}. If the
425 function uses both @code{&rest} and @code{&key} at the same time,
426 the ``rest'' argument is bound to the keyword list as it appears
427 in the call. For example:
430 (cl-defun find-thing (thing &rest rest &key need &allow-other-keys)
431 (or (apply 'cl-member thing thing-list :allow-other-keys t rest)
432 (if need (error "Thing not found"))))
436 This function takes a @code{:need} keyword argument, but also
437 accepts other keyword arguments which are passed on to the
438 @code{cl-member} function. @code{allow-other-keys} is used to
439 keep both @code{find-thing} and @code{cl-member} from complaining
440 about each others' keywords in the arguments.
442 The fifth section of the argument list consists of @dfn{auxiliary
443 variables}. These are not really arguments at all, but simply
444 variables which are bound to @code{nil} or to the specified
445 @var{initforms} during execution of the function. There is no
446 difference between the following two functions, except for a
447 matter of stylistic taste:
450 (cl-defun foo (a b &aux (c (+ a b)) d)
458 Argument lists support @dfn{destructuring}. In Common Lisp,
459 destructuring is only allowed with @code{defmacro}; this package
460 allows it with @code{cl-defun} and other argument lists as well.
461 In destructuring, any argument variable (@var{var} in the above
462 diagram) can be replaced by a list of variables, or more generally,
463 a recursive argument list. The corresponding argument value must
464 be a list whose elements match this recursive argument list.
468 (cl-defmacro dolist ((var listform &optional resultform)
473 This says that the first argument of @code{dolist} must be a list
474 of two or three items; if there are other arguments as well as this
475 list, they are stored in @code{body}. All features allowed in
476 regular argument lists are allowed in these recursive argument lists.
477 In addition, the clause @samp{&whole @var{var}} is allowed at the
478 front of a recursive argument list. It binds @var{var} to the
479 whole list being matched; thus @code{(&whole all a b)} matches
480 a list of two things, with @code{a} bound to the first thing,
481 @code{b} bound to the second thing, and @code{all} bound to the
482 list itself. (Common Lisp allows @code{&whole} in top-level
483 @code{defmacro} argument lists as well, but Emacs Lisp does not
486 One last feature of destructuring is that the argument list may be
487 dotted, so that the argument list @code{(a b . c)} is functionally
488 equivalent to @code{(a b &rest c)}.
490 If the optimization quality @code{safety} is set to 0
491 (@pxref{Declarations}), error checking for wrong number of
492 arguments and invalid keyword arguments is disabled. By default,
493 argument lists are rigorously checked.
495 @node Time of Evaluation
496 @section Time of Evaluation
499 Normally, the byte-compiler does not actually execute the forms in
500 a file it compiles. For example, if a file contains @code{(setq foo t)},
501 the act of compiling it will not actually set @code{foo} to @code{t}.
502 This is true even if the @code{setq} was a top-level form (i.e., not
503 enclosed in a @code{defun} or other form). Sometimes, though, you
504 would like to have certain top-level forms evaluated at compile-time.
505 For example, the compiler effectively evaluates @code{defmacro} forms
506 at compile-time so that later parts of the file can refer to the
507 macros that are defined.
509 @defmac cl-eval-when (situations...) forms...
510 This form controls when the body @var{forms} are evaluated.
511 The @var{situations} list may contain any set of the symbols
512 @code{compile}, @code{load}, and @code{eval} (or their long-winded
513 ANSI equivalents, @code{:compile-toplevel}, @code{:load-toplevel},
514 and @code{:execute}).
516 The @code{cl-eval-when} form is handled differently depending on
517 whether or not it is being compiled as a top-level form.
518 Specifically, it gets special treatment if it is being compiled
519 by a command such as @code{byte-compile-file} which compiles files
520 or buffers of code, and it appears either literally at the
521 top level of the file or inside a top-level @code{progn}.
523 For compiled top-level @code{cl-eval-when}s, the body @var{forms} are
524 executed at compile-time if @code{compile} is in the @var{situations}
525 list, and the @var{forms} are written out to the file (to be executed
526 at load-time) if @code{load} is in the @var{situations} list.
528 For non-compiled-top-level forms, only the @code{eval} situation is
529 relevant. (This includes forms executed by the interpreter, forms
530 compiled with @code{byte-compile} rather than @code{byte-compile-file},
531 and non-top-level forms.) The @code{cl-eval-when} acts like a
532 @code{progn} if @code{eval} is specified, and like @code{nil}
533 (ignoring the body @var{forms}) if not.
535 The rules become more subtle when @code{cl-eval-when}s are nested;
536 consult Steele (second edition) for the gruesome details (and
537 some gruesome examples).
539 Some simple examples:
542 ;; Top-level forms in foo.el:
543 (cl-eval-when (compile) (setq foo1 'bar))
544 (cl-eval-when (load) (setq foo2 'bar))
545 (cl-eval-when (compile load) (setq foo3 'bar))
546 (cl-eval-when (eval) (setq foo4 'bar))
547 (cl-eval-when (eval compile) (setq foo5 'bar))
548 (cl-eval-when (eval load) (setq foo6 'bar))
549 (cl-eval-when (eval compile load) (setq foo7 'bar))
552 When @file{foo.el} is compiled, these variables will be set during
553 the compilation itself:
556 foo1 foo3 foo5 foo7 ; `compile'
559 When @file{foo.elc} is loaded, these variables will be set:
562 foo2 foo3 foo6 foo7 ; `load'
565 And if @file{foo.el} is loaded uncompiled, these variables will
569 foo4 foo5 foo6 foo7 ; `eval'
572 If these seven @code{cl-eval-when}s had been, say, inside a @code{defun},
573 then the first three would have been equivalent to @code{nil} and the
574 last four would have been equivalent to the corresponding @code{setq}s.
576 Note that @code{(cl-eval-when (load eval) @dots{})} is equivalent
577 to @code{(progn @dots{})} in all contexts. The compiler treats
578 certain top-level forms, like @code{defmacro} (sort-of) and
579 @code{require}, as if they were wrapped in @code{(cl-eval-when
580 (compile load eval) @dots{})}.
583 Emacs includes two special forms related to @code{cl-eval-when}.
584 One of these, @code{eval-when-compile}, is not quite equivalent to
585 any @code{cl-eval-when} construct and is described below.
587 The other form, @code{(eval-and-compile @dots{})}, is exactly
588 equivalent to @samp{(cl-eval-when (compile load eval) @dots{})} and
589 so is not itself defined by this package.
591 @defmac eval-when-compile forms...
592 The @var{forms} are evaluated at compile-time; at execution time,
593 this form acts like a quoted constant of the resulting value. Used
594 at top-level, @code{eval-when-compile} is just like @samp{eval-when
595 (compile eval)}. In other contexts, @code{eval-when-compile}
596 allows code to be evaluated once at compile-time for efficiency
599 This form is similar to the @samp{#.} syntax of true Common Lisp.
602 @defmac cl-load-time-value form
603 The @var{form} is evaluated at load-time; at execution time,
604 this form acts like a quoted constant of the resulting value.
606 Early Common Lisp had a @samp{#,} syntax that was similar to
607 this, but ANSI Common Lisp replaced it with @code{load-time-value}
608 and gave it more well-defined semantics.
610 In a compiled file, @code{cl-load-time-value} arranges for @var{form}
611 to be evaluated when the @file{.elc} file is loaded and then used
612 as if it were a quoted constant. In code compiled by
613 @code{byte-compile} rather than @code{byte-compile-file}, the
614 effect is identical to @code{eval-when-compile}. In uncompiled
615 code, both @code{eval-when-compile} and @code{cl-load-time-value}
616 act exactly like @code{progn}.
620 (insert "This function was executed on: "
621 (current-time-string)
623 (eval-when-compile (current-time-string))
624 ;; or '#.(current-time-string) in real Common Lisp
626 (cl-load-time-value (current-time-string))))
630 Byte-compiled, the above defun will result in the following code
631 (or its compiled equivalent, of course) in the @file{.elc} file:
634 (setq --temp-- (current-time-string))
636 (insert "This function was executed on: "
637 (current-time-string)
639 '"Wed Jun 23 18:33:43 1993"
649 This section describes functions for testing whether various
650 facts are true or false.
653 * Type Predicates:: @code{cl-typep}, @code{cl-deftype}, and @code{cl-coerce}.
654 * Equality Predicates:: @code{cl-equalp}.
657 @node Type Predicates
658 @section Type Predicates
660 @defun cl-typep object type
661 Check if @var{object} is of type @var{type}, where @var{type} is a
662 (quoted) type name of the sort used by Common Lisp. For example,
663 @code{(cl-typep foo 'integer)} is equivalent to @code{(integerp foo)}.
666 The @var{type} argument to the above function is either a symbol
667 or a list beginning with a symbol.
671 If the type name is a symbol, Emacs appends @samp{-p} to the
672 symbol name to form the name of a predicate function for testing
673 the type. (Built-in predicates whose names end in @samp{p} rather
674 than @samp{-p} are used when appropriate.)
677 The type symbol @code{t} stands for the union of all types.
678 @code{(cl-typep @var{object} t)} is always true. Likewise, the
679 type symbol @code{nil} stands for nothing at all, and
680 @code{(cl-typep @var{object} nil)} is always false.
683 The type symbol @code{null} represents the symbol @code{nil}.
684 Thus @code{(cl-typep @var{object} 'null)} is equivalent to
685 @code{(null @var{object})}.
688 The type symbol @code{atom} represents all objects that are not cons
689 cells. Thus @code{(cl-typep @var{object} 'atom)} is equivalent to
690 @code{(atom @var{object})}.
693 The type symbol @code{real} is a synonym for @code{number}, and
694 @code{fixnum} is a synonym for @code{integer}.
697 The type symbols @code{character} and @code{string-char} match
698 integers in the range from 0 to 255.
701 The type symbol @code{float} uses the @code{cl-floatp-safe} predicate
702 defined by this package rather than @code{floatp}, so it will work
703 correctly even in Emacs versions without floating-point support.
706 The type list @code{(integer @var{low} @var{high})} represents all
707 integers between @var{low} and @var{high}, inclusive. Either bound
708 may be a list of a single integer to specify an exclusive limit,
709 or a @code{*} to specify no limit. The type @code{(integer * *)}
710 is thus equivalent to @code{integer}.
713 Likewise, lists beginning with @code{float}, @code{real}, or
714 @code{number} represent numbers of that type falling in a particular
718 Lists beginning with @code{and}, @code{or}, and @code{not} form
719 combinations of types. For example, @code{(or integer (float 0 *))}
720 represents all objects that are integers or non-negative floats.
723 Lists beginning with @code{member} or @code{cl-member} represent
724 objects @code{eql} to any of the following values. For example,
725 @code{(member 1 2 3 4)} is equivalent to @code{(integer 1 4)},
726 and @code{(member nil)} is equivalent to @code{null}.
729 Lists of the form @code{(satisfies @var{predicate})} represent
730 all objects for which @var{predicate} returns true when called
731 with that object as an argument.
734 The following function and macro (not technically predicates) are
735 related to @code{cl-typep}.
737 @defun cl-coerce object type
738 This function attempts to convert @var{object} to the specified
739 @var{type}. If @var{object} is already of that type as determined by
740 @code{cl-typep}, it is simply returned. Otherwise, certain types of
741 conversions will be made: If @var{type} is any sequence type
742 (@code{string}, @code{list}, etc.) then @var{object} will be
743 converted to that type if possible. If @var{type} is
744 @code{character}, then strings of length one and symbols with
745 one-character names can be coerced. If @var{type} is @code{float},
746 then integers can be coerced in versions of Emacs that support
747 floats. In all other circumstances, @code{cl-coerce} signals an
751 @defmac cl-deftype name arglist forms...
752 This macro defines a new type called @var{name}. It is similar
753 to @code{defmacro} in many ways; when @var{name} is encountered
754 as a type name, the body @var{forms} are evaluated and should
755 return a type specifier that is equivalent to the type. The
756 @var{arglist} is a Common Lisp argument list of the sort accepted
757 by @code{cl-defmacro}. The type specifier @samp{(@var{name} @var{args}...)}
758 is expanded by calling the expander with those arguments; the type
759 symbol @samp{@var{name}} is expanded by calling the expander with
760 no arguments. The @var{arglist} is processed the same as for
761 @code{cl-defmacro} except that optional arguments without explicit
762 defaults use @code{*} instead of @code{nil} as the ``default''
763 default. Some examples:
766 (cl-deftype null () '(satisfies null)) ; predefined
767 (cl-deftype list () '(or null cons)) ; predefined
768 (cl-deftype unsigned-byte (&optional bits)
769 (list 'integer 0 (if (eq bits '*) bits (1- (lsh 1 bits)))))
770 (unsigned-byte 8) @equiv{} (integer 0 255)
771 (unsigned-byte) @equiv{} (integer 0 *)
772 unsigned-byte @equiv{} (integer 0 *)
776 The last example shows how the Common Lisp @code{unsigned-byte}
777 type specifier could be implemented if desired; this package does
778 not implement @code{unsigned-byte} by default.
781 The @code{cl-typecase} and @code{cl-check-type} macros also use type
782 names. @xref{Conditionals}. @xref{Assertions}. The @code{cl-map},
783 @code{cl-concatenate}, and @code{cl-merge} functions take type-name
784 arguments to specify the type of sequence to return. @xref{Sequences}.
786 @node Equality Predicates
787 @section Equality Predicates
790 This package defines the Common Lisp predicate @code{cl-equalp}.
793 This function is a more flexible version of @code{equal}. In
794 particular, it compares strings case-insensitively, and it compares
795 numbers without regard to type (so that @code{(cl-equalp 3 3.0)} is
796 true). Vectors and conses are compared recursively. All other
797 objects are compared as if by @code{equal}.
799 This function differs from Common Lisp @code{equalp} in several
800 respects. First, Common Lisp's @code{equalp} also compares
801 @emph{characters} case-insensitively, which would be impractical
802 in this package since Emacs does not distinguish between integers
803 and characters. In keeping with the idea that strings are less
804 vector-like in Emacs Lisp, this package's @code{cl-equalp} also will
805 not compare strings against vectors of integers.
808 Also note that the Common Lisp functions @code{member} and @code{assoc}
809 use @code{eql} to compare elements, whereas Emacs Lisp follows the
810 MacLisp tradition and uses @code{equal} for these two functions.
811 In Emacs, use @code{memq} (or @code{cl-member}) and @code{assq} (or
812 @code{cl-assoc}) to get functions which use @code{eql} for comparisons.
814 @node Control Structure
815 @chapter Control Structure
818 The features described in the following sections implement
819 various advanced control structures, including extensions to the
820 standard @code{setf} facility, and a number of looping and conditional
824 @c flet is not cl-flet.
826 * Assignment:: The @code{cl-psetq} form.
827 * Generalized Variables:: Extensions to generalized variables.
828 * Variable Bindings:: @code{cl-progv}, @code{flet}, @code{cl-macrolet}.
829 * Conditionals:: @code{cl-case}, @code{cl-typecase}.
830 * Blocks and Exits:: @code{cl-block}, @code{cl-return}, @code{cl-return-from}.
831 * Iteration:: @code{cl-do}, @code{cl-dotimes}, @code{cl-dolist}, @code{cl-do-symbols}.
832 * Loop Facility:: The Common Lisp @code{cl-loop} macro.
833 * Multiple Values:: @code{cl-values}, @code{cl-multiple-value-bind}, etc.
840 The @code{cl-psetq} form is just like @code{setq}, except that multiple
841 assignments are done in parallel rather than sequentially.
843 @defmac cl-psetq [symbol form]@dots{}
844 This special form (actually a macro) is used to assign to several
845 variables simultaneously. Given only one @var{symbol} and @var{form},
846 it has the same effect as @code{setq}. Given several @var{symbol}
847 and @var{form} pairs, it evaluates all the @var{form}s in advance
848 and then stores the corresponding variables afterwards.
852 (setq x (+ x y) y (* x y))
855 y ; @r{@code{y} was computed after @code{x} was set.}
858 (cl-psetq x (+ x y) y (* x y))
861 y ; @r{@code{y} was computed before @code{x} was set.}
865 The simplest use of @code{cl-psetq} is @code{(cl-psetq x y y x)}, which
866 exchanges the values of two variables. (The @code{cl-rotatef} form
867 provides an even more convenient way to swap two variables;
868 @pxref{Modify Macros}.)
870 @code{cl-psetq} always returns @code{nil}.
873 @node Generalized Variables
874 @section Generalized Variables
876 A @dfn{generalized variable} or @dfn{place form} is one of the many
877 places in Lisp memory where values can be stored. The simplest place
878 form is a regular Lisp variable. But the cars and cdrs of lists,
879 elements of arrays, properties of symbols, and many other locations
880 are also places where Lisp values are stored. For basic information,
881 @pxref{Generalized Variables,,,elisp,GNU Emacs Lisp Reference Manual}.
882 This package provides several additional features related to
883 generalized variables.
886 * Setf Extensions:: Additional @code{setf} places.
887 * Modify Macros:: @code{cl-incf}, @code{cl-rotatef}, @code{cl-letf}, @code{cl-callf}, etc.
890 @node Setf Extensions
891 @subsection Setf Extensions
893 Several standard (e.g. @code{car}) and Emacs-specific
894 (e.g. @code{window-point}) Lisp functions are @code{setf}-able by default.
895 This package defines @code{setf} handlers for several additional functions:
899 Functions from @code{CL} itself:
901 cl-caaar .. cl-cddddr cl-first .. cl-tenth
902 cl-rest cl-get cl-getf cl-subseq
906 Note that for @code{cl-getf} (as for @code{nthcdr}), the list argument
907 of the function must itself be a valid @var{place} form.
910 General Emacs Lisp functions:
912 buffer-file-name getenv
913 buffer-modified-p global-key-binding
914 buffer-name local-key-binding
916 buffer-substring mark-marker
917 current-buffer marker-position
918 current-case-table mouse-position
920 current-global-map point-marker
921 current-input-mode point-max
922 current-local-map point-min
923 current-window-configuration read-mouse-position
924 default-file-modes screen-height
925 documentation-property screen-width
926 face-background selected-window
927 face-background-pixmap selected-screen
928 face-font selected-frame
929 face-foreground standard-case-table
930 face-underline-p syntax-table
931 file-modes visited-file-modtime
932 frame-height window-height
933 frame-parameters window-width
934 frame-visible-p x-get-secondary-selection
935 frame-width x-get-selection
939 Most of these have directly corresponding ``set'' functions, like
940 @code{use-local-map} for @code{current-local-map}, or @code{goto-char}
941 for @code{point}. A few, like @code{point-min}, expand to longer
942 sequences of code when they are used with @code{setf}
943 (@code{(narrow-to-region x (point-max))} in this case).
946 A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])},
947 where @var{subplace} is itself a valid generalized variable whose
948 current value is a string, and where the value stored is also a
949 string. The new string is spliced into the specified part of the
950 destination string. For example:
953 (setq a (list "hello" "world"))
954 @result{} ("hello" "world")
957 (substring (cadr a) 2 4)
959 (setf (substring (cadr a) 2 4) "o")
964 @result{} ("hello" "wood")
967 The generalized variable @code{buffer-substring}, listed above,
968 also works in this way by replacing a portion of the current buffer.
970 @c FIXME? Also `eq'? (see cl-lib.el)
972 @c Currently commented out in cl.el.
975 A call of the form @code{(apply '@var{func} @dots{})} or
976 @code{(apply (function @var{func}) @dots{})}, where @var{func}
977 is a @code{setf}-able function whose store function is ``suitable''
978 in the sense described in Steele's book; since none of the standard
979 Emacs place functions are suitable in this sense, this feature is
980 only interesting when used with places you define yourself with
981 @code{define-setf-method} or the long form of @code{defsetf}.
982 @xref{Obsolete Setf Customization}.
986 A macro call, in which case the macro is expanded and @code{setf}
987 is applied to the resulting form.
990 Any form for which a @code{defsetf} or @code{define-setf-method}
991 has been made. @xref{Obsolete Setf Customization}.
994 @c FIXME should this be in lispref? It seems self-evident.
995 @c Contrast with the cl-incf example later on.
996 @c Here it really only serves as a constrast to wrong-order.
997 The @code{setf} macro takes care to evaluate all subforms in
998 the proper left-to-right order; for example,
1001 (setf (aref vec (cl-incf i)) i)
1005 looks like it will evaluate @code{(cl-incf i)} exactly once, before the
1006 following access to @code{i}; the @code{setf} expander will insert
1007 temporary variables as necessary to ensure that it does in fact work
1008 this way no matter what setf-method is defined for @code{aref}.
1009 (In this case, @code{aset} would be used and no such steps would
1010 be necessary since @code{aset} takes its arguments in a convenient
1013 However, if the @var{place} form is a macro which explicitly
1014 evaluates its arguments in an unusual order, this unusual order
1015 will be preserved. Adapting an example from Steele, given
1018 (defmacro wrong-order (x y) (list 'aref y x))
1022 the form @code{(setf (wrong-order @var{a} @var{b}) 17)} will
1023 evaluate @var{b} first, then @var{a}, just as in an actual call
1024 to @code{wrong-order}.
1027 @subsection Modify Macros
1030 This package defines a number of macros that operate on generalized
1031 variables. Many are interesting and useful even when the @var{place}
1032 is just a variable name.
1034 @defmac cl-psetf [place form]@dots{}
1035 This macro is to @code{setf} what @code{cl-psetq} is to @code{setq}:
1036 When several @var{place}s and @var{form}s are involved, the
1037 assignments take place in parallel rather than sequentially.
1038 Specifically, all subforms are evaluated from left to right, then
1039 all the assignments are done (in an undefined order).
1042 @defmac cl-incf place &optional x
1043 This macro increments the number stored in @var{place} by one, or
1044 by @var{x} if specified. The incremented value is returned. For
1045 example, @code{(cl-incf i)} is equivalent to @code{(setq i (1+ i))}, and
1046 @code{(cl-incf (car x) 2)} is equivalent to @code{(setcar x (+ (car x) 2))}.
1048 As with @code{setf}, care is taken to preserve the ``apparent'' order
1049 of evaluation. For example,
1052 (cl-incf (aref vec (cl-incf i)))
1056 appears to increment @code{i} once, then increment the element of
1057 @code{vec} addressed by @code{i}; this is indeed exactly what it
1058 does, which means the above form is @emph{not} equivalent to the
1059 ``obvious'' expansion,
1062 (setf (aref vec (cl-incf i))
1063 (1+ (aref vec (cl-incf i)))) ; wrong!
1067 but rather to something more like
1070 (let ((temp (cl-incf i)))
1071 (setf (aref vec temp) (1+ (aref vec temp))))
1075 Again, all of this is taken care of automatically by @code{cl-incf} and
1076 the other generalized-variable macros.
1078 As a more Emacs-specific example of @code{cl-incf}, the expression
1079 @code{(cl-incf (point) @var{n})} is essentially equivalent to
1080 @code{(forward-char @var{n})}.
1083 @defmac cl-decf place &optional x
1084 This macro decrements the number stored in @var{place} by one, or
1085 by @var{x} if specified.
1088 @defmac cl-pushnew x place @t{&key :test :test-not :key}
1089 This macro inserts @var{x} at the front of the list stored in
1090 @var{place}, but only if @var{x} was not @code{eql} to any
1091 existing element of the list. The optional keyword arguments
1092 are interpreted in the same way as for @code{cl-adjoin}.
1093 @xref{Lists as Sets}.
1096 @defmac cl-shiftf place@dots{} newvalue
1097 This macro shifts the @var{place}s left by one, shifting in the
1098 value of @var{newvalue} (which may be any Lisp expression, not just
1099 a generalized variable), and returning the value shifted out of
1100 the first @var{place}. Thus, @code{(cl-shiftf @var{a} @var{b} @var{c}
1101 @var{d})} is equivalent to
1106 (cl-psetf @var{a} @var{b}
1112 except that the subforms of @var{a}, @var{b}, and @var{c} are actually
1113 evaluated only once each and in the apparent order.
1116 @defmac cl-rotatef place@dots{}
1117 This macro rotates the @var{place}s left by one in circular fashion.
1118 Thus, @code{(cl-rotatef @var{a} @var{b} @var{c} @var{d})} is equivalent to
1121 (cl-psetf @var{a} @var{b}
1128 except for the evaluation of subforms. @code{cl-rotatef} always
1129 returns @code{nil}. Note that @code{(cl-rotatef @var{a} @var{b})}
1130 conveniently exchanges @var{a} and @var{b}.
1133 The following macros were invented for this package; they have no
1134 analogues in Common Lisp.
1136 @defmac cl-letf (bindings@dots{}) forms@dots{}
1137 This macro is analogous to @code{let}, but for generalized variables
1138 rather than just symbols. Each @var{binding} should be of the form
1139 @code{(@var{place} @var{value})}; the original contents of the
1140 @var{place}s are saved, the @var{value}s are stored in them, and
1141 then the body @var{form}s are executed. Afterwards, the @var{places}
1142 are set back to their original saved contents. This cleanup happens
1143 even if the @var{form}s exit irregularly due to a @code{throw} or an
1149 (cl-letf (((point) (point-min))
1155 moves point in the current buffer to the beginning of the buffer,
1156 and also binds @code{a} to 17 (as if by a normal @code{let}, since
1157 @code{a} is just a regular variable). After the body exits, @code{a}
1158 is set back to its original value and point is moved back to its
1161 Note that @code{cl-letf} on @code{(point)} is not quite like a
1162 @code{save-excursion}, as the latter effectively saves a marker
1163 which tracks insertions and deletions in the buffer. Actually,
1164 a @code{cl-letf} of @code{(point-marker)} is much closer to this
1165 behavior. (@code{point} and @code{point-marker} are equivalent
1166 as @code{setf} places; each will accept either an integer or a
1167 marker as the stored value.)
1169 Since generalized variables look like lists, @code{let}'s shorthand
1170 of using @samp{foo} for @samp{(foo nil)} as a @var{binding} would
1171 be ambiguous in @code{cl-letf} and is not allowed.
1173 However, a @var{binding} specifier may be a one-element list
1174 @samp{(@var{place})}, which is similar to @samp{(@var{place}
1175 @var{place})}. In other words, the @var{place} is not disturbed
1176 on entry to the body, and the only effect of the @code{cl-letf} is
1177 to restore the original value of @var{place} afterwards.
1178 @c I suspect this may no longer be true; either way it's
1179 @c implementation detail and so not essential to document.
1181 (The redundant access-and-store suggested by the @code{(@var{place}
1182 @var{place})} example does not actually occur.)
1185 Note that in this case, and in fact almost every case, @var{place}
1186 must have a well-defined value outside the @code{cl-letf} body.
1187 There is essentially only one exception to this, which is @var{place}
1188 a plain variable with a specified @var{value} (such as @code{(a 17)}
1189 in the above example).
1190 @c See http://debbugs.gnu.org/12758
1191 @c Some or all of this was true for cl.el, but not for cl-lib.el.
1193 The only exceptions are plain variables and calls to
1194 @code{symbol-value} and @code{symbol-function}. If the symbol is not
1195 bound on entry, it is simply made unbound by @code{makunbound} or
1196 @code{fmakunbound} on exit.
1200 @defmac cl-letf* (bindings@dots{}) forms@dots{}
1201 This macro is to @code{cl-letf} what @code{let*} is to @code{let}:
1202 It does the bindings in sequential rather than parallel order.
1205 @defmac cl-callf @var{function} @var{place} @var{args}@dots{}
1206 This is the ``generic'' modify macro. It calls @var{function},
1207 which should be an unquoted function name, macro name, or lambda.
1208 It passes @var{place} and @var{args} as arguments, and assigns the
1209 result back to @var{place}. For example, @code{(cl-incf @var{place}
1210 @var{n})} is the same as @code{(cl-callf + @var{place} @var{n})}.
1214 (cl-callf abs my-number)
1215 (cl-callf concat (buffer-name) "<" (number-to-string n) ">")
1216 (cl-callf cl-union happy-people (list joe bob) :test 'same-person)
1219 Note again that @code{cl-callf} is an extension to standard Common Lisp.
1222 @defmac cl-callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{}
1223 This macro is like @code{cl-callf}, except that @var{place} is
1224 the @emph{second} argument of @var{function} rather than the
1225 first. For example, @code{(push @var{x} @var{place})} is
1226 equivalent to @code{(cl-callf2 cons @var{x} @var{place})}.
1229 The @code{cl-callf} and @code{cl-callf2} macros serve as building
1230 blocks for other macros like @code{cl-incf}, and @code{cl-pushnew}.
1231 The @code{cl-letf} and @code{cl-letf*} macros are used in the processing
1232 of symbol macros; @pxref{Macro Bindings}.
1235 @node Variable Bindings
1236 @section Variable Bindings
1239 These Lisp forms make bindings to variables and function names,
1240 analogous to Lisp's built-in @code{let} form.
1242 @xref{Modify Macros}, for the @code{cl-letf} and @code{cl-letf*} forms which
1243 are also related to variable bindings.
1246 * Dynamic Bindings:: The @code{cl-progv} form.
1247 * Function Bindings:: @code{flet} and @code{labels}.
1248 * Macro Bindings:: @code{cl-macrolet} and @code{cl-symbol-macrolet}.
1251 @node Dynamic Bindings
1252 @subsection Dynamic Bindings
1255 The standard @code{let} form binds variables whose names are known
1256 at compile-time. The @code{cl-progv} form provides an easy way to
1257 bind variables whose names are computed at run-time.
1259 @defmac cl-progv symbols values forms@dots{}
1260 This form establishes @code{let}-style variable bindings on a
1261 set of variables computed at run-time. The expressions
1262 @var{symbols} and @var{values} are evaluated, and must return lists
1263 of symbols and values, respectively. The symbols are bound to the
1264 corresponding values for the duration of the body @var{form}s.
1265 If @var{values} is shorter than @var{symbols}, the last few symbols
1266 are bound to @code{nil}.
1267 If @var{symbols} is shorter than @var{values}, the excess values
1271 @node Function Bindings
1272 @subsection Function Bindings
1275 These forms make @code{let}-like bindings to functions instead
1278 @defmac flet (bindings@dots{}) forms@dots{}
1279 This form establishes @code{let}-style bindings on the function
1280 cells of symbols rather than on the value cells. Each @var{binding}
1281 must be a list of the form @samp{(@var{name} @var{arglist}
1282 @var{forms}@dots{})}, which defines a function exactly as if
1283 it were a @code{cl-defun} form. The function @var{name} is defined
1284 accordingly for the duration of the body of the @code{flet}; then
1285 the old function definition, or lack thereof, is restored.
1287 While @code{flet} in Common Lisp establishes a lexical binding of
1288 @var{name}, Emacs Lisp @code{flet} makes a dynamic binding. The
1289 result is that @code{flet} affects indirect calls to a function as
1290 well as calls directly inside the @code{flet} form itself.
1292 You can use @code{flet} to disable or modify the behavior of a
1293 function in a temporary fashion. This will even work on Emacs
1294 primitives, although note that some calls to primitive functions
1295 internal to Emacs are made without going through the symbol's
1296 function cell, and so will not be affected by @code{flet}. For
1300 (flet ((message (&rest args) (push args saved-msgs)))
1304 This code attempts to replace the built-in function @code{message}
1305 with a function that simply saves the messages in a list rather
1306 than displaying them. The original definition of @code{message}
1307 will be restored after @code{do-something} exits. This code will
1308 work fine on messages generated by other Lisp code, but messages
1309 generated directly inside Emacs will not be caught since they make
1310 direct C-language calls to the message routines rather than going
1311 through the Lisp @code{message} function.
1314 Also note that many primitives (e.g. @code{+}) have special byte-compile
1315 handling. Attempts to redefine such functions using @code{flet} will
1316 fail if byte-compiled. In such cases, use @code{labels} instead.
1318 Functions defined by @code{flet} may use the full Common Lisp
1319 argument notation supported by @code{cl-defun}; also, the function
1320 body is enclosed in an implicit block as if by @code{cl-defun}.
1321 @xref{Program Structure}.
1324 @defmac labels (bindings@dots{}) forms@dots{}
1325 The @code{labels} form is like @code{flet}, except that it
1326 makes lexical bindings of the function names rather than
1327 dynamic bindings. (In true Common Lisp, both @code{flet} and
1328 @code{labels} make lexical bindings of slightly different sorts;
1329 since Emacs Lisp is dynamically bound by default, it seemed
1330 more appropriate for @code{flet} also to use dynamic binding.
1331 The @code{labels} form, with its lexical binding, is fully
1332 compatible with Common Lisp.)
1334 Lexical scoping means that all references to the named
1335 functions must appear physically within the body of the
1336 @code{labels} form. References may appear both in the body
1337 @var{forms} of @code{labels} itself, and in the bodies of
1338 the functions themselves. Thus, @code{labels} can define
1339 local recursive functions, or mutually-recursive sets of
1342 A ``reference'' to a function name is either a call to that
1343 function, or a use of its name quoted by @code{quote} or
1344 @code{function} to be passed on to, say, @code{mapcar}.
1347 @node Macro Bindings
1348 @subsection Macro Bindings
1351 These forms create local macros and ``symbol macros''.
1353 @defmac cl-macrolet (bindings@dots{}) forms@dots{}
1354 This form is analogous to @code{flet}, but for macros instead of
1355 functions. Each @var{binding} is a list of the same form as the
1356 arguments to @code{cl-defmacro} (i.e., a macro name, argument list,
1357 and macro-expander forms). The macro is defined accordingly for
1358 use within the body of the @code{cl-macrolet}.
1360 @c FIXME this should be modified to say ``even when lexical-binding
1361 @c is code{nil}'', but is that true? The doc of cl-macrolet just
1362 @c refers us to cl-flet, which refers to cl-labels, which says that it
1363 @c behaves differently according to whether l-b is true or not.
1364 Because of the nature of macros, @code{cl-macrolet} is lexically
1365 scoped even in Emacs Lisp: The @code{cl-macrolet} binding will
1366 affect only calls that appear physically within the body
1367 @var{forms}, possibly after expansion of other macros in the
1371 @defmac cl-symbol-macrolet (bindings@dots{}) forms@dots{}
1372 This form creates @dfn{symbol macros}, which are macros that look
1373 like variable references rather than function calls. Each
1374 @var{binding} is a list @samp{(@var{var} @var{expansion})};
1375 any reference to @var{var} within the body @var{forms} is
1376 replaced by @var{expansion}.
1380 (cl-symbol-macrolet ((foo (car bar)))
1386 A @code{setq} of a symbol macro is treated the same as a @code{setf}.
1387 I.e., @code{(setq foo 4)} in the above would be equivalent to
1388 @code{(setf foo 4)}, which in turn expands to @code{(setf (car bar) 4)}.
1390 Likewise, a @code{let} or @code{let*} binding a symbol macro is
1391 treated like a @code{cl-letf} or @code{cl-letf*}. This differs from true
1392 @c FIXME does it work like this in Emacs with lexical-binding = t?
1393 Common Lisp, where the rules of lexical scoping cause a @code{let}
1394 binding to shadow a @code{cl-symbol-macrolet} binding. In this package,
1396 only @code{lexical-let} and @code{lexical-let*} will shadow a symbol
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 (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
1445 These conditional forms augment Emacs Lisp's simple @code{if},
1446 @code{and}, @code{or}, and @code{cond} forms.
1448 @defmac cl-case keyform clause@dots{}
1449 This macro evaluates @var{keyform}, then compares it with the key
1450 values listed in the various @var{clause}s. Whichever clause matches
1451 the key is executed; comparison is done by @code{eql}. If no clause
1452 matches, the @code{cl-case} form returns @code{nil}. The clauses are
1456 (@var{keylist} @var{body-forms}@dots{})
1460 where @var{keylist} is a list of key values. If there is exactly
1461 one value, and it is not a cons cell or the symbol @code{nil} or
1462 @code{t}, then it can be used by itself as a @var{keylist} without
1463 being enclosed in a list. All key values in the @code{cl-case} form
1464 must be distinct. The final clauses may use @code{t} in place of
1465 a @var{keylist} to indicate a default clause that should be taken
1466 if none of the other clauses match. (The symbol @code{otherwise}
1467 is also recognized in place of @code{t}. To make a clause that
1468 matches the actual symbol @code{t}, @code{nil}, or @code{otherwise},
1469 enclose the symbol in a list.)
1471 For example, this expression reads a keystroke, then does one of
1472 four things depending on whether it is an @samp{a}, a @samp{b},
1473 a @key{RET} or @kbd{C-j}, or anything else.
1476 (cl-case (read-char)
1479 ((?\r ?\n) (do-ret-thing))
1480 (t (do-other-thing)))
1484 @defmac cl-ecase keyform clause@dots{}
1485 This macro is just like @code{cl-case}, except that if the key does
1486 not match any of the clauses, an error is signaled rather than
1487 simply returning @code{nil}.
1490 @defmac cl-typecase keyform clause@dots{}
1491 This macro is a version of @code{cl-case} that checks for types
1492 rather than values. Each @var{clause} is of the form
1493 @samp{(@var{type} @var{body}...)}. @xref{Type Predicates},
1494 for a description of type specifiers. For example,
1498 (integer (munch-integer x))
1499 (float (munch-float x))
1500 (string (munch-integer (string-to-int x)))
1501 (t (munch-anything x)))
1504 The type specifier @code{t} matches any type of object; the word
1505 @code{otherwise} is also allowed. To make one clause match any of
1506 several types, use an @code{(or ...)} type specifier.
1509 @defmac cl-etypecase keyform clause@dots{}
1510 This macro is just like @code{cl-typecase}, except that if the key does
1511 not match any of the clauses, an error is signaled rather than
1512 simply returning @code{nil}.
1515 @node Blocks and Exits
1516 @section Blocks and Exits
1519 Common Lisp @dfn{blocks} provide a non-local exit mechanism very
1520 similar to @code{catch} and @code{throw}, but lexically rather than
1521 dynamically scoped. This package actually implements @code{cl-block}
1522 in terms of @code{catch}; however, the lexical scoping allows the
1523 optimizing byte-compiler to omit the costly @code{catch} step if the
1524 body of the block does not actually @code{cl-return-from} the block.
1526 @defmac cl-block name forms@dots{}
1527 The @var{forms} are evaluated as if by a @code{progn}. However,
1528 if any of the @var{forms} execute @code{(cl-return-from @var{name})},
1529 they will jump out and return directly from the @code{cl-block} form.
1530 The @code{cl-block} returns the result of the last @var{form} unless
1531 a @code{cl-return-from} occurs.
1533 The @code{cl-block}/@code{cl-return-from} mechanism is quite similar to
1534 the @code{catch}/@code{throw} mechanism. The main differences are
1535 that block @var{name}s are unevaluated symbols, rather than forms
1536 (such as quoted symbols) which evaluate to a tag at run-time; and
1537 also that blocks are lexically scoped whereas @code{catch}/@code{throw}
1538 are dynamically scoped. This means that functions called from the
1539 body of a @code{catch} can also @code{throw} to the @code{catch},
1540 but the @code{cl-return-from} referring to a block name must appear
1541 physically within the @var{forms} that make up the body of the block.
1542 They may not appear within other called functions, although they may
1543 appear within macro expansions or @code{lambda}s in the body. Block
1544 names and @code{catch} names form independent name-spaces.
1546 In true Common Lisp, @code{defun} and @code{defmacro} surround
1547 the function or expander bodies with implicit blocks with the
1548 same name as the function or macro. This does not occur in Emacs
1549 Lisp, but this package provides @code{cl-defun} and @code{cl-defmacro}
1550 forms which do create the implicit block.
1552 The Common Lisp looping constructs defined by this package,
1553 such as @code{cl-loop} and @code{cl-dolist}, also create implicit blocks
1554 just as in Common Lisp.
1556 Because they are implemented in terms of Emacs Lisp @code{catch}
1557 and @code{throw}, blocks have the same overhead as actual
1558 @code{catch} constructs (roughly two function calls). However,
1559 the optimizing byte compiler will optimize away the @code{catch}
1561 not in fact contain any @code{cl-return} or @code{cl-return-from} calls
1562 that jump to it. This means that @code{cl-do} loops and @code{cl-defun}
1563 functions which don't use @code{cl-return} don't pay the overhead to
1567 @defmac cl-return-from name [result]
1568 This macro returns from the block named @var{name}, which must be
1569 an (unevaluated) symbol. If a @var{result} form is specified, it
1570 is evaluated to produce the result returned from the @code{block}.
1571 Otherwise, @code{nil} is returned.
1574 @defmac cl-return [result]
1575 This macro is exactly like @code{(cl-return-from nil @var{result})}.
1576 Common Lisp loops like @code{cl-do} and @code{cl-dolist} implicitly enclose
1577 themselves in @code{nil} blocks.
1584 The macros described here provide more sophisticated, high-level
1585 looping constructs to complement Emacs Lisp's basic @code{while}
1588 @defmac cl-loop forms@dots{}
1589 The @code{CL} package supports both the simple, old-style meaning of
1590 @code{loop} and the extremely powerful and flexible feature known as
1591 the @dfn{Loop Facility} or @dfn{Loop Macro}. This more advanced
1592 facility is discussed in the following section; @pxref{Loop Facility}.
1593 The simple form of @code{loop} is described here.
1595 If @code{cl-loop} is followed by zero or more Lisp expressions,
1596 then @code{(cl-loop @var{exprs}@dots{})} simply creates an infinite
1597 loop executing the expressions over and over. The loop is
1598 enclosed in an implicit @code{nil} block. Thus,
1601 (cl-loop (foo) (if (no-more) (return 72)) (bar))
1605 is exactly equivalent to
1608 (cl-block nil (while t (foo) (if (no-more) (return 72)) (bar)))
1611 If any of the expressions are plain symbols, the loop is instead
1612 interpreted as a Loop Macro specification as described later.
1613 (This is not a restriction in practice, since a plain symbol
1614 in the above notation would simply access and throw away the
1615 value of a variable.)
1618 @defmac cl-do (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
1619 This macro creates a general iterative loop. Each @var{spec} is
1623 (@var{var} [@var{init} [@var{step}]])
1626 The loop works as follows: First, each @var{var} is bound to the
1627 associated @var{init} value as if by a @code{let} form. Then, in
1628 each iteration of the loop, the @var{end-test} is evaluated; if
1629 true, the loop is finished. Otherwise, the body @var{forms} are
1630 evaluated, then each @var{var} is set to the associated @var{step}
1631 expression (as if by a @code{cl-psetq} form) and the next iteration
1632 begins. Once the @var{end-test} becomes true, the @var{result}
1633 forms are evaluated (with the @var{var}s still bound to their
1634 values) to produce the result returned by @code{cl-do}.
1636 The entire @code{cl-do} loop is enclosed in an implicit @code{nil}
1637 block, so that you can use @code{(cl-return)} to break out of the
1640 If there are no @var{result} forms, the loop returns @code{nil}.
1641 If a given @var{var} has no @var{step} form, it is bound to its
1642 @var{init} value but not otherwise modified during the @code{cl-do}
1643 loop (unless the code explicitly modifies it); this case is just
1644 a shorthand for putting a @code{(let ((@var{var} @var{init})) @dots{})}
1645 around the loop. If @var{init} is also omitted it defaults to
1646 @code{nil}, and in this case a plain @samp{@var{var}} can be used
1647 in place of @samp{(@var{var})}, again following the analogy with
1650 This example (from Steele) illustrates a loop which applies the
1651 function @code{f} to successive pairs of values from the lists
1652 @code{foo} and @code{bar}; it is equivalent to the call
1653 @code{(cl-mapcar 'f foo bar)}. Note that this loop has no body
1654 @var{forms} at all, performing all its work as side effects of
1655 the rest of the loop.
1658 (cl-do ((x foo (cdr x))
1660 (z nil (cons (f (car x) (car y)) z)))
1661 ((or (null x) (null y))
1666 @defmac cl-do* (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
1667 This is to @code{cl-do} what @code{let*} is to @code{let}. In
1668 particular, the initial values are bound as if by @code{let*}
1669 rather than @code{let}, and the steps are assigned as if by
1670 @code{setq} rather than @code{cl-psetq}.
1672 Here is another way to write the above loop:
1675 (cl-do* ((xp foo (cdr xp))
1677 (x (car xp) (car xp))
1678 (y (car yp) (car yp))
1680 ((or (null xp) (null yp))
1686 @defmac cl-dolist (var list [result]) forms@dots{}
1687 This is a more specialized loop which iterates across the elements
1688 of a list. @var{list} should evaluate to a list; the body @var{forms}
1689 are executed with @var{var} bound to each element of the list in
1690 turn. Finally, the @var{result} form (or @code{nil}) is evaluated
1691 with @var{var} bound to @code{nil} to produce the result returned by
1692 the loop. Unlike with Emacs's built in @code{dolist}, the loop is
1693 surrounded by an implicit @code{nil} block.
1696 @defmac cl-dotimes (var count [result]) forms@dots{}
1697 This is a more specialized loop which iterates a specified number
1698 of times. The body is executed with @var{var} bound to the integers
1699 from zero (inclusive) to @var{count} (exclusive), in turn. Then
1700 the @code{result} form is evaluated with @var{var} bound to the total
1701 number of iterations that were done (i.e., @code{(max 0 @var{count})})
1702 to get the return value for the loop form. Unlike with Emacs's built in
1703 @code{dolist}, the loop is surrounded by an implicit @code{nil} block.
1706 @defmac cl-do-symbols (var [obarray [result]]) forms@dots{}
1707 This loop iterates over all interned symbols. If @var{obarray}
1708 is specified and is not @code{nil}, it loops over all symbols in
1709 that obarray. For each symbol, the body @var{forms} are evaluated
1710 with @var{var} bound to that symbol. The symbols are visited in
1711 an unspecified order. Afterward the @var{result} form, if any,
1712 is evaluated (with @var{var} bound to @code{nil}) to get the return
1713 value. The loop is surrounded by an implicit @code{nil} block.
1716 @defmac cl-do-all-symbols (var [result]) forms@dots{}
1717 This is identical to @code{cl-do-symbols} except that the @var{obarray}
1718 argument is omitted; it always iterates over the default obarray.
1721 @xref{Mapping over Sequences}, for some more functions for
1722 iterating over vectors or lists.
1725 @section Loop Facility
1728 A common complaint with Lisp's traditional looping constructs is
1729 that they are either too simple and limited, such as Common Lisp's
1730 @code{dotimes} or Emacs Lisp's @code{while}, or too unreadable and
1731 obscure, like Common Lisp's @code{do} loop.
1733 To remedy this, recent versions of Common Lisp have added a new
1734 construct called the ``Loop Facility'' or ``@code{loop} macro'',
1735 with an easy-to-use but very powerful and expressive syntax.
1738 * Loop Basics:: @code{cl-loop} macro, basic clause structure.
1739 * Loop Examples:: Working examples of @code{cl-loop} macro.
1740 * For Clauses:: Clauses introduced by @code{for} or @code{as}.
1741 * Iteration Clauses:: @code{repeat}, @code{while}, @code{thereis}, etc.
1742 * Accumulation Clauses:: @code{collect}, @code{sum}, @code{maximize}, etc.
1743 * Other Clauses:: @code{with}, @code{if}, @code{initially}, @code{finally}.
1747 @subsection Loop Basics
1750 The @code{cl-loop} macro essentially creates a mini-language within
1751 Lisp that is specially tailored for describing loops. While this
1752 language is a little strange-looking by the standards of regular Lisp,
1753 it turns out to be very easy to learn and well-suited to its purpose.
1755 Since @code{cl-loop} is a macro, all parsing of the loop language
1756 takes place at byte-compile time; compiled @code{cl-loop}s are just
1757 as efficient as the equivalent @code{while} loops written longhand.
1759 @defmac cl-loop clauses@dots{}
1760 A loop construct consists of a series of @var{clause}s, each
1761 introduced by a symbol like @code{for} or @code{do}. Clauses
1762 are simply strung together in the argument list of @code{cl-loop},
1763 with minimal extra parentheses. The various types of clauses
1764 specify initializations, such as the binding of temporary
1765 variables, actions to be taken in the loop, stepping actions,
1768 Common Lisp specifies a certain general order of clauses in a
1772 (cl-loop @var{name-clause}
1773 @var{var-clauses}@dots{}
1774 @var{action-clauses}@dots{})
1777 The @var{name-clause} optionally gives a name to the implicit
1778 block that surrounds the loop. By default, the implicit block
1779 is named @code{nil}. The @var{var-clauses} specify what
1780 variables should be bound during the loop, and how they should
1781 be modified or iterated throughout the course of the loop. The
1782 @var{action-clauses} are things to be done during the loop, such
1783 as computing, collecting, and returning values.
1785 The Emacs version of the @code{cl-loop} macro is less restrictive about
1786 the order of clauses, but things will behave most predictably if
1787 you put the variable-binding clauses @code{with}, @code{for}, and
1788 @code{repeat} before the action clauses. As in Common Lisp,
1789 @code{initially} and @code{finally} clauses can go anywhere.
1791 Loops generally return @code{nil} by default, but you can cause
1792 them to return a value by using an accumulation clause like
1793 @code{collect}, an end-test clause like @code{always}, or an
1794 explicit @code{return} clause to jump out of the implicit block.
1795 (Because the loop body is enclosed in an implicit block, you can
1796 also use regular Lisp @code{cl-return} or @code{cl-return-from} to
1797 break out of the loop.)
1800 The following sections give some examples of the Loop Macro in
1801 action, and describe the particular loop clauses in great detail.
1802 Consult the second edition of Steele's @dfn{Common Lisp, the Language},
1803 for additional discussion and examples of the @code{loop} macro.
1806 @subsection Loop Examples
1809 Before listing the full set of clauses that are allowed, let's
1810 look at a few example loops just to get a feel for the @code{cl-loop}
1814 (cl-loop for buf in (buffer-list)
1815 collect (buffer-file-name buf))
1819 This loop iterates over all Emacs buffers, using the list
1820 returned by @code{buffer-list}. For each buffer @var{buf},
1821 it calls @code{buffer-file-name} and collects the results into
1822 a list, which is then returned from the @code{cl-loop} construct.
1823 The result is a list of the file names of all the buffers in
1824 Emacs's memory. The words @code{for}, @code{in}, and @code{collect}
1825 are reserved words in the @code{cl-loop} language.
1828 (cl-loop repeat 20 do (insert "Yowsa\n"))
1832 This loop inserts the phrase ``Yowsa'' twenty times in the
1836 (cl-loop until (eobp) do (munch-line) (forward-line 1))
1840 This loop calls @code{munch-line} on every line until the end
1841 of the buffer. If point is already at the end of the buffer,
1842 the loop exits immediately.
1845 (cl-loop do (munch-line) until (eobp) do (forward-line 1))
1849 This loop is similar to the above one, except that @code{munch-line}
1850 is always called at least once.
1853 (cl-loop for x from 1 to 100
1856 finally return (list x (= y 729)))
1860 This more complicated loop searches for a number @code{x} whose
1861 square is 729. For safety's sake it only examines @code{x}
1862 values up to 100; dropping the phrase @samp{to 100} would
1863 cause the loop to count upwards with no limit. The second
1864 @code{for} clause defines @code{y} to be the square of @code{x}
1865 within the loop; the expression after the @code{=} sign is
1866 reevaluated each time through the loop. The @code{until}
1867 clause gives a condition for terminating the loop, and the
1868 @code{finally} clause says what to do when the loop finishes.
1869 (This particular example was written less concisely than it
1870 could have been, just for the sake of illustration.)
1872 Note that even though this loop contains three clauses (two
1873 @code{for}s and an @code{until}) that would have been enough to
1874 define loops all by themselves, it still creates a single loop
1875 rather than some sort of triple-nested loop. You must explicitly
1876 nest your @code{cl-loop} constructs if you want nested loops.
1879 @subsection For Clauses
1882 Most loops are governed by one or more @code{for} clauses.
1883 A @code{for} clause simultaneously describes variables to be
1884 bound, how those variables are to be stepped during the loop,
1885 and usually an end condition based on those variables.
1887 The word @code{as} is a synonym for the word @code{for}. This
1888 word is followed by a variable name, then a word like @code{from}
1889 or @code{across} that describes the kind of iteration desired.
1890 In Common Lisp, the phrase @code{being the} sometimes precedes
1891 the type of iteration; in this package both @code{being} and
1892 @code{the} are optional. The word @code{each} is a synonym
1893 for @code{the}, and the word that follows it may be singular
1894 or plural: @samp{for x being the elements of y} or
1895 @samp{for x being each element of y}. Which form you use
1896 is purely a matter of style.
1898 The variable is bound around the loop as if by @code{let}:
1902 (cl-loop for i from 1 to 10 do (do-something-with i))
1908 @item for @var{var} from @var{expr1} to @var{expr2} by @var{expr3}
1909 This type of @code{for} clause creates a counting loop. Each of
1910 the three sub-terms is optional, though there must be at least one
1911 term so that the clause is marked as a counting clause.
1913 The three expressions are the starting value, the ending value, and
1914 the step value, respectively, of the variable. The loop counts
1915 upwards by default (@var{expr3} must be positive), from @var{expr1}
1916 to @var{expr2} inclusively. If you omit the @code{from} term, the
1917 loop counts from zero; if you omit the @code{to} term, the loop
1918 counts forever without stopping (unless stopped by some other
1919 loop clause, of course); if you omit the @code{by} term, the loop
1920 counts in steps of one.
1922 You can replace the word @code{from} with @code{upfrom} or
1923 @code{downfrom} to indicate the direction of the loop. Likewise,
1924 you can replace @code{to} with @code{upto} or @code{downto}.
1925 For example, @samp{for x from 5 downto 1} executes five times
1926 with @code{x} taking on the integers from 5 down to 1 in turn.
1927 Also, you can replace @code{to} with @code{below} or @code{above},
1928 which are like @code{upto} and @code{downto} respectively except
1929 that they are exclusive rather than inclusive limits:
1932 (cl-loop for x to 10 collect x)
1933 @result{} (0 1 2 3 4 5 6 7 8 9 10)
1934 (cl-loop for x below 10 collect x)
1935 @result{} (0 1 2 3 4 5 6 7 8 9)
1938 The @code{by} value is always positive, even for downward-counting
1939 loops. Some sort of @code{from} value is required for downward
1940 loops; @samp{for x downto 5} is not a valid loop clause all by
1943 @item for @var{var} in @var{list} by @var{function}
1944 This clause iterates @var{var} over all the elements of @var{list},
1945 in turn. If you specify the @code{by} term, then @var{function}
1946 is used to traverse the list instead of @code{cdr}; it must be a
1947 function taking one argument. For example:
1950 (cl-loop for x in '(1 2 3 4 5 6) collect (* x x))
1951 @result{} (1 4 9 16 25 36)
1952 (cl-loop for x in '(1 2 3 4 5 6) by 'cddr collect (* x x))
1956 @item for @var{var} on @var{list} by @var{function}
1957 This clause iterates @var{var} over all the cons cells of @var{list}.
1960 (cl-loop for x on '(1 2 3 4) collect x)
1961 @result{} ((1 2 3 4) (2 3 4) (3 4) (4))
1964 With @code{by}, there is no real reason that the @code{on} expression
1965 must be a list. For example:
1968 (cl-loop for x on first-animal by 'next-animal collect x)
1972 where @code{(next-animal x)} takes an ``animal'' @var{x} and returns
1973 the next in the (assumed) sequence of animals, or @code{nil} if
1974 @var{x} was the last animal in the sequence.
1976 @item for @var{var} in-ref @var{list} by @var{function}
1977 This is like a regular @code{in} clause, but @var{var} becomes
1978 a @code{setf}-able ``reference'' onto the elements of the list
1979 rather than just a temporary variable. For example,
1982 (cl-loop for x in-ref my-list do (cl-incf x))
1986 increments every element of @code{my-list} in place. This clause
1987 is an extension to standard Common Lisp.
1989 @item for @var{var} across @var{array}
1990 This clause iterates @var{var} over all the elements of @var{array},
1991 which may be a vector or a string.
1994 (cl-loop for x across "aeiou"
1995 do (use-vowel (char-to-string x)))
1998 @item for @var{var} across-ref @var{array}
1999 This clause iterates over an array, with @var{var} a @code{setf}-able
2000 reference onto the elements; see @code{in-ref} above.
2002 @item for @var{var} being the elements of @var{sequence}
2003 This clause iterates over the elements of @var{sequence}, which may
2004 be a list, vector, or string. Since the type must be determined
2005 at run-time, this is somewhat less efficient than @code{in} or
2006 @code{across}. The clause may be followed by the additional term
2007 @samp{using (index @var{var2})} to cause @var{var2} to be bound to
2008 the successive indices (starting at 0) of the elements.
2010 This clause type is taken from older versions of the @code{loop} macro,
2011 and is not present in modern Common Lisp. The @samp{using (sequence ...)}
2012 term of the older macros is not supported.
2014 @item for @var{var} being the elements of-ref @var{sequence}
2015 This clause iterates over a sequence, with @var{var} a @code{setf}-able
2016 reference onto the elements; see @code{in-ref} above.
2018 @item for @var{var} being the symbols [of @var{obarray}]
2019 This clause iterates over symbols, either over all interned symbols
2020 or over all symbols in @var{obarray}. The loop is executed with
2021 @var{var} bound to each symbol in turn. The symbols are visited in
2022 an unspecified order.
2027 (cl-loop for sym being the symbols
2029 when (string-match "^map" (symbol-name sym))
2034 returns a list of all the functions whose names begin with @samp{map}.
2036 The Common Lisp words @code{external-symbols} and @code{present-symbols}
2037 are also recognized but are equivalent to @code{symbols} in Emacs Lisp.
2039 Due to a minor implementation restriction, it will not work to have
2040 more than one @code{for} clause iterating over symbols, hash tables,
2041 keymaps, overlays, or intervals in a given @code{cl-loop}. Fortunately,
2042 it would rarely if ever be useful to do so. It @emph{is} valid to mix
2043 one of these types of clauses with other clauses like @code{for ... to}
2046 @item for @var{var} being the hash-keys of @var{hash-table}
2047 @itemx for @var{var} being the hash-values of @var{hash-table}
2048 This clause iterates over the entries in @var{hash-table} with
2049 @var{var} bound to each key, or value. A @samp{using} clause can bind
2050 a second variable to the opposite part.
2053 (cl-loop for k being the hash-keys of h
2054 using (hash-values v)
2056 (message "key %S -> value %S" k v))
2059 @item for @var{var} being the key-codes of @var{keymap}
2060 @itemx for @var{var} being the key-bindings of @var{keymap}
2061 This clause iterates over the entries in @var{keymap}.
2062 The iteration does not enter nested keymaps but does enter inherited
2064 A @code{using} clause can access both the codes and the bindings
2068 (cl-loop for c being the key-codes of (current-local-map)
2069 using (key-bindings b)
2071 (message "key %S -> binding %S" c b))
2075 @item for @var{var} being the key-seqs of @var{keymap}
2076 This clause iterates over all key sequences defined by @var{keymap}
2077 and its nested keymaps, where @var{var} takes on values which are
2078 vectors. The strings or vectors
2079 are reused for each iteration, so you must copy them if you wish to keep
2080 them permanently. You can add a @samp{using (key-bindings ...)}
2081 clause to get the command bindings as well.
2083 @item for @var{var} being the overlays [of @var{buffer}] @dots{}
2084 This clause iterates over the ``overlays'' of a buffer
2085 (the clause @code{extents} is synonymous
2086 with @code{overlays}). If the @code{of} term is omitted, the current
2088 This clause also accepts optional @samp{from @var{pos}} and
2089 @samp{to @var{pos}} terms, limiting the clause to overlays which
2090 overlap the specified region.
2092 @item for @var{var} being the intervals [of @var{buffer}] @dots{}
2093 This clause iterates over all intervals of a buffer with constant
2094 text properties. The variable @var{var} will be bound to conses
2095 of start and end positions, where one start position is always equal
2096 to the previous end position. The clause allows @code{of},
2097 @code{from}, @code{to}, and @code{property} terms, where the latter
2098 term restricts the search to just the specified property. The
2099 @code{of} term may specify either a buffer or a string.
2101 @item for @var{var} being the frames
2102 This clause iterates over all Emacs frames. The clause @code{screens} is
2103 a synonym for @code{frames}. The frames are visited in
2104 @code{next-frame} order starting from @code{selected-frame}.
2106 @item for @var{var} being the windows [of @var{frame}]
2107 This clause iterates over the windows (in the Emacs sense) of
2108 the current frame, or of the specified @var{frame}. It visits windows
2109 in @code{next-window} order starting from @code{selected-window}
2110 (or @code{frame-selected-window} if you specify @var{frame}).
2111 This clause treats the minibuffer window in the same way as
2112 @code{next-window} does. For greater flexibility, consider using
2113 @code{walk-windows} instead.
2115 @item for @var{var} being the buffers
2116 This clause iterates over all buffers in Emacs. It is equivalent
2117 to @samp{for @var{var} in (buffer-list)}.
2119 @item for @var{var} = @var{expr1} then @var{expr2}
2120 This clause does a general iteration. The first time through
2121 the loop, @var{var} will be bound to @var{expr1}. On the second
2122 and successive iterations it will be set by evaluating @var{expr2}
2123 (which may refer to the old value of @var{var}). For example,
2124 these two loops are effectively the same:
2127 (cl-loop for x on my-list by 'cddr do ...)
2128 (cl-loop for x = my-list then (cddr x) while x do ...)
2131 Note that this type of @code{for} clause does not imply any sort
2132 of terminating condition; the above example combines it with a
2133 @code{while} clause to tell when to end the loop.
2135 If you omit the @code{then} term, @var{expr1} is used both for
2136 the initial setting and for successive settings:
2139 (cl-loop for x = (random) when (> x 0) return x)
2143 This loop keeps taking random numbers from the @code{(random)}
2144 function until it gets a positive one, which it then returns.
2147 If you include several @code{for} clauses in a row, they are
2148 treated sequentially (as if by @code{let*} and @code{setq}).
2149 You can instead use the word @code{and} to link the clauses,
2150 in which case they are processed in parallel (as if by @code{let}
2151 and @code{cl-psetq}).
2154 (cl-loop for x below 5 for y = nil then x collect (list x y))
2155 @result{} ((0 nil) (1 1) (2 2) (3 3) (4 4))
2156 (cl-loop for x below 5 and y = nil then x collect (list x y))
2157 @result{} ((0 nil) (1 0) (2 1) (3 2) (4 3))
2161 In the first loop, @code{y} is set based on the value of @code{x}
2162 that was just set by the previous clause; in the second loop,
2163 @code{x} and @code{y} are set simultaneously so @code{y} is set
2164 based on the value of @code{x} left over from the previous time
2167 Another feature of the @code{cl-loop} macro is @dfn{destructuring},
2168 similar in concept to the destructuring provided by @code{defmacro}.
2169 The @var{var} part of any @code{for} clause can be given as a list
2170 of variables instead of a single variable. The values produced
2171 during loop execution must be lists; the values in the lists are
2172 stored in the corresponding variables.
2175 (cl-loop for (x y) in '((2 3) (4 5) (6 7)) collect (+ x y))
2179 In loop destructuring, if there are more values than variables
2180 the trailing values are ignored, and if there are more variables
2181 than values the trailing variables get the value @code{nil}.
2182 If @code{nil} is used as a variable name, the corresponding
2183 values are ignored. Destructuring may be nested, and dotted
2184 lists of variables like @code{(x . y)} are allowed, so for example
2188 (cl-loop for (key . value) in '((a . 1) (b . 2))
2193 @node Iteration Clauses
2194 @subsection Iteration Clauses
2197 Aside from @code{for} clauses, there are several other loop clauses
2198 that control the way the loop operates. They might be used by
2199 themselves, or in conjunction with one or more @code{for} clauses.
2202 @item repeat @var{integer}
2203 This clause simply counts up to the specified number using an
2204 internal temporary variable. The loops
2207 (cl-loop repeat (1+ n) do ...)
2208 (cl-loop for temp to n do ...)
2212 are identical except that the second one forces you to choose
2213 a name for a variable you aren't actually going to use.
2215 @item while @var{condition}
2216 This clause stops the loop when the specified condition (any Lisp
2217 expression) becomes @code{nil}. For example, the following two
2218 loops are equivalent, except for the implicit @code{nil} block
2219 that surrounds the second one:
2222 (while @var{cond} @var{forms}@dots{})
2223 (cl-loop while @var{cond} do @var{forms}@dots{})
2226 @item until @var{condition}
2227 This clause stops the loop when the specified condition is true,
2228 i.e., non-@code{nil}.
2230 @item always @var{condition}
2231 This clause stops the loop when the specified condition is @code{nil}.
2232 Unlike @code{while}, it stops the loop using @code{return nil} so that
2233 the @code{finally} clauses are not executed. If all the conditions
2234 were non-@code{nil}, the loop returns @code{t}:
2237 (if (cl-loop for size in size-list always (> size 10))
2242 @item never @var{condition}
2243 This clause is like @code{always}, except that the loop returns
2244 @code{t} if any conditions were false, or @code{nil} otherwise.
2246 @item thereis @var{condition}
2247 This clause stops the loop when the specified form is non-@code{nil};
2248 in this case, it returns that non-@code{nil} value. If all the
2249 values were @code{nil}, the loop returns @code{nil}.
2252 @node Accumulation Clauses
2253 @subsection Accumulation Clauses
2256 These clauses cause the loop to accumulate information about the
2257 specified Lisp @var{form}. The accumulated result is returned
2258 from the loop unless overridden, say, by a @code{return} clause.
2261 @item collect @var{form}
2262 This clause collects the values of @var{form} into a list. Several
2263 examples of @code{collect} appear elsewhere in this manual.
2265 The word @code{collecting} is a synonym for @code{collect}, and
2266 likewise for the other accumulation clauses.
2268 @item append @var{form}
2269 This clause collects lists of values into a result list using
2272 @item nconc @var{form}
2273 This clause collects lists of values into a result list by
2274 destructively modifying the lists rather than copying them.
2276 @item concat @var{form}
2277 This clause concatenates the values of the specified @var{form}
2278 into a string. (It and the following clause are extensions to
2279 standard Common Lisp.)
2281 @item vconcat @var{form}
2282 This clause concatenates the values of the specified @var{form}
2285 @item count @var{form}
2286 This clause counts the number of times the specified @var{form}
2287 evaluates to a non-@code{nil} value.
2289 @item sum @var{form}
2290 This clause accumulates the sum of the values of the specified
2291 @var{form}, which must evaluate to a number.
2293 @item maximize @var{form}
2294 This clause accumulates the maximum value of the specified @var{form},
2295 which must evaluate to a number. The return value is undefined if
2296 @code{maximize} is executed zero times.
2298 @item minimize @var{form}
2299 This clause accumulates the minimum value of the specified @var{form}.
2302 Accumulation clauses can be followed by @samp{into @var{var}} to
2303 cause the data to be collected into variable @var{var} (which is
2304 automatically @code{let}-bound during the loop) rather than an
2305 unnamed temporary variable. Also, @code{into} accumulations do
2306 not automatically imply a return value. The loop must use some
2307 explicit mechanism, such as @code{finally return}, to return
2308 the accumulated result.
2310 It is valid for several accumulation clauses of the same type to
2311 accumulate into the same place. From Steele:
2314 (cl-loop for name in '(fred sue alice joe june)
2315 for kids in '((bob ken) () () (kris sunshine) ())
2318 @result{} (fred bob ken sue alice joe kris sunshine june)
2322 @subsection Other Clauses
2325 This section describes the remaining loop clauses.
2328 @item with @var{var} = @var{value}
2329 This clause binds a variable to a value around the loop, but
2330 otherwise leaves the variable alone during the loop. The following
2331 loops are basically equivalent:
2334 (cl-loop with x = 17 do ...)
2335 (let ((x 17)) (cl-loop do ...))
2336 (cl-loop for x = 17 then x do ...)
2339 Naturally, the variable @var{var} might be used for some purpose
2340 in the rest of the loop. For example:
2343 (cl-loop for x in my-list with res = nil do (push x res)
2347 This loop inserts the elements of @code{my-list} at the front of
2348 a new list being accumulated in @code{res}, then returns the
2349 list @code{res} at the end of the loop. The effect is similar
2350 to that of a @code{collect} clause, but the list gets reversed
2351 by virtue of the fact that elements are being pushed onto the
2352 front of @code{res} rather than the end.
2354 If you omit the @code{=} term, the variable is initialized to
2355 @code{nil}. (Thus the @samp{= nil} in the above example is
2358 Bindings made by @code{with} are sequential by default, as if
2359 by @code{let*}. Just like @code{for} clauses, @code{with} clauses
2360 can be linked with @code{and} to cause the bindings to be made by
2363 @item if @var{condition} @var{clause}
2364 This clause executes the following loop clause only if the specified
2365 condition is true. The following @var{clause} should be an accumulation,
2366 @code{do}, @code{return}, @code{if}, or @code{unless} clause.
2367 Several clauses may be linked by separating them with @code{and}.
2368 These clauses may be followed by @code{else} and a clause or clauses
2369 to execute if the condition was false. The whole construct may
2370 optionally be followed by the word @code{end} (which may be used to
2371 disambiguate an @code{else} or @code{and} in a nested @code{if}).
2373 The actual non-@code{nil} value of the condition form is available
2374 by the name @code{it} in the ``then'' part. For example:
2377 (setq funny-numbers '(6 13 -1))
2379 (cl-loop for x below 10
2382 and if (memq x funny-numbers) return (cdr it) end
2384 collect x into evens
2385 finally return (vector odds evens))
2386 @result{} [(1 3 5 7 9) (0 2 4 6 8)]
2387 (setq funny-numbers '(6 7 13 -1))
2388 @result{} (6 7 13 -1)
2389 (cl-loop <@r{same thing again}>)
2393 Note the use of @code{and} to put two clauses into the ``then''
2394 part, one of which is itself an @code{if} clause. Note also that
2395 @code{end}, while normally optional, was necessary here to make
2396 it clear that the @code{else} refers to the outermost @code{if}
2397 clause. In the first case, the loop returns a vector of lists
2398 of the odd and even values of @var{x}. In the second case, the
2399 odd number 7 is one of the @code{funny-numbers} so the loop
2400 returns early; the actual returned value is based on the result
2401 of the @code{memq} call.
2403 @item when @var{condition} @var{clause}
2404 This clause is just a synonym for @code{if}.
2406 @item unless @var{condition} @var{clause}
2407 The @code{unless} clause is just like @code{if} except that the
2408 sense of the condition is reversed.
2410 @item named @var{name}
2411 This clause gives a name other than @code{nil} to the implicit
2412 block surrounding the loop. The @var{name} is the symbol to be
2413 used as the block name.
2415 @item initially [do] @var{forms}...
2416 This keyword introduces one or more Lisp forms which will be
2417 executed before the loop itself begins (but after any variables
2418 requested by @code{for} or @code{with} have been bound to their
2419 initial values). @code{initially} clauses can appear anywhere;
2420 if there are several, they are executed in the order they appear
2421 in the loop. The keyword @code{do} is optional.
2423 @item finally [do] @var{forms}...
2424 This introduces Lisp forms which will be executed after the loop
2425 finishes (say, on request of a @code{for} or @code{while}).
2426 @code{initially} and @code{finally} clauses may appear anywhere
2427 in the loop construct, but they are executed (in the specified
2428 order) at the beginning or end, respectively, of the loop.
2430 @item finally return @var{form}
2431 This says that @var{form} should be executed after the loop
2432 is done to obtain a return value. (Without this, or some other
2433 clause like @code{collect} or @code{return}, the loop will simply
2434 return @code{nil}.) Variables bound by @code{for}, @code{with},
2435 or @code{into} will still contain their final values when @var{form}
2438 @item do @var{forms}...
2439 The word @code{do} may be followed by any number of Lisp expressions
2440 which are executed as an implicit @code{progn} in the body of the
2441 loop. Many of the examples in this section illustrate the use of
2444 @item return @var{form}
2445 This clause causes the loop to return immediately. The following
2446 Lisp form is evaluated to give the return value of the @code{loop}
2447 form. The @code{finally} clauses, if any, are not executed.
2448 Of course, @code{return} is generally used inside an @code{if} or
2449 @code{unless}, as its use in a top-level loop clause would mean
2450 the loop would never get to ``loop'' more than once.
2452 The clause @samp{return @var{form}} is equivalent to
2453 @c FIXME cl-do, cl-return?
2454 @samp{do (return @var{form})} (or @code{return-from} if the loop
2455 was named). The @code{return} clause is implemented a bit more
2456 efficiently, though.
2459 While there is no high-level way to add user extensions to @code{cl-loop},
2460 this package does offer two properties called @code{cl-loop-handler}
2461 and @code{cl-loop-for-handler} which are functions to be called when a
2462 given symbol is encountered as a top-level loop clause or @code{for}
2463 clause, respectively. Consult the source code in file
2464 @file{cl-macs.el} for details.
2466 This package's @code{cl-loop} macro is compatible with that of Common
2467 Lisp, except that a few features are not implemented: @code{loop-finish}
2468 and data-type specifiers. Naturally, the @code{for} clauses which
2469 iterate over keymaps, overlays, intervals, frames, windows, and
2470 buffers are Emacs-specific extensions.
2472 @node Multiple Values
2473 @section Multiple Values
2476 Common Lisp functions can return zero or more results. Emacs Lisp
2477 functions, by contrast, always return exactly one result. This
2478 package makes no attempt to emulate Common Lisp multiple return
2479 values; Emacs versions of Common Lisp functions that return more
2480 than one value either return just the first value (as in
2481 @code{cl-compiler-macroexpand}) or return a list of values.
2482 This package @emph{does} define placeholders
2483 for the Common Lisp functions that work with multiple values, but
2484 in Emacs Lisp these functions simply operate on lists instead.
2485 The @code{cl-values} form, for example, is a synonym for @code{list}
2488 @defmac cl-multiple-value-bind (var@dots{}) values-form forms@dots{}
2489 This form evaluates @var{values-form}, which must return a list of
2490 values. It then binds the @var{var}s to these respective values,
2491 as if by @code{let}, and then executes the body @var{forms}.
2492 If there are more @var{var}s than values, the extra @var{var}s
2493 are bound to @code{nil}. If there are fewer @var{var}s than
2494 values, the excess values are ignored.
2497 @defmac cl-multiple-value-setq (var@dots{}) form
2498 This form evaluates @var{form}, which must return a list of values.
2499 It then sets the @var{var}s to these respective values, as if by
2500 @code{setq}. Extra @var{var}s or values are treated the same as
2501 in @code{cl-multiple-value-bind}.
2504 Since a perfect emulation is not feasible in Emacs Lisp, this
2505 package opts to keep it as simple and predictable as possible.
2511 This package implements the various Common Lisp features of
2512 @code{defmacro}, such as destructuring, @code{&environment},
2513 and @code{&body}. Top-level @code{&whole} is not implemented
2514 for @code{defmacro} due to technical difficulties.
2515 @xref{Argument Lists}.
2517 Destructuring is made available to the user by way of the
2520 @defmac cl-destructuring-bind arglist expr forms@dots{}
2521 This macro expands to code which executes @var{forms}, with
2522 the variables in @var{arglist} bound to the list of values
2523 returned by @var{expr}. The @var{arglist} can include all
2524 the features allowed for @code{defmacro} argument lists,
2525 including destructuring. (The @code{&environment} keyword
2526 is not allowed.) The macro expansion will signal an error
2527 if @var{expr} returns a list of the wrong number of arguments
2528 or with incorrect keyword arguments.
2531 This package also includes the Common Lisp @code{cl-define-compiler-macro}
2532 facility, which allows you to define compile-time expansions and
2533 optimizations for your functions.
2535 @defmac cl-define-compiler-macro name arglist forms@dots{}
2536 This form is similar to @code{defmacro}, except that it only expands
2537 calls to @var{name} at compile-time; calls processed by the Lisp
2538 interpreter are not expanded, nor are they expanded by the
2539 @code{macroexpand} function.
2541 The argument list may begin with a @code{&whole} keyword and a
2542 variable. This variable is bound to the macro-call form itself,
2543 i.e., to a list of the form @samp{(@var{name} @var{args}@dots{})}.
2544 If the macro expander returns this form unchanged, then the
2545 compiler treats it as a normal function call. This allows
2546 compiler macros to work as optimizers for special cases of a
2547 function, leaving complicated cases alone.
2549 For example, here is a simplified version of a definition that
2550 appears as a standard part of this package:
2553 (cl-define-compiler-macro cl-member (&whole form a list &rest keys)
2554 (if (and (null keys)
2555 (eq (car-safe a) 'quote)
2556 (not (floatp-safe (cadr a))))
2562 This definition causes @code{(cl-member @var{a} @var{list})} to change
2563 to a call to the faster @code{memq} in the common case where @var{a}
2564 is a non-floating-point constant; if @var{a} is anything else, or
2565 if there are any keyword arguments in the call, then the original
2566 @code{cl-member} call is left intact. (The actual compiler macro
2567 for @code{cl-member} optimizes a number of other cases, including
2568 common @code{:test} predicates.)
2571 @defun cl-compiler-macroexpand form
2572 This function is analogous to @code{macroexpand}, except that it
2573 expands compiler macros rather than regular macros. It returns
2574 @var{form} unchanged if it is not a call to a function for which
2575 a compiler macro has been defined, or if that compiler macro
2576 decided to punt by returning its @code{&whole} argument. Like
2577 @code{macroexpand}, it expands repeatedly until it reaches a form
2578 for which no further expansion is possible.
2581 @xref{Macro Bindings}, for descriptions of the @code{cl-macrolet}
2582 and @code{cl-symbol-macrolet} forms for making ``local'' macro
2586 @chapter Declarations
2589 Common Lisp includes a complex and powerful ``declaration''
2590 mechanism that allows you to give the compiler special hints
2591 about the types of data that will be stored in particular variables,
2592 and about the ways those variables and functions will be used. This
2593 package defines versions of all the Common Lisp declaration forms:
2594 @code{cl-declare}, @code{cl-locally}, @code{cl-proclaim}, @code{cl-declaim},
2597 Most of the Common Lisp declarations are not currently useful in
2598 Emacs Lisp, as the byte-code system provides little opportunity
2599 to benefit from type information, and @code{special} declarations
2600 are redundant in a fully dynamically-scoped Lisp. A few
2601 declarations are meaningful when the optimizing byte
2602 compiler is being used, however. Under the earlier non-optimizing
2603 compiler, these declarations will effectively be ignored.
2605 @defun cl-proclaim decl-spec
2606 This function records a ``global'' declaration specified by
2607 @var{decl-spec}. Since @code{cl-proclaim} is a function, @var{decl-spec}
2608 is evaluated and thus should normally be quoted.
2611 @defmac cl-declaim decl-specs@dots{}
2612 This macro is like @code{cl-proclaim}, except that it takes any number
2613 of @var{decl-spec} arguments, and the arguments are unevaluated and
2614 unquoted. The @code{cl-declaim} macro also puts an @code{(cl-eval-when
2615 (compile load eval) ...)} around the declarations so that they will
2616 be registered at compile-time as well as at run-time. (This is vital,
2617 since normally the declarations are meant to influence the way the
2618 compiler treats the rest of the file that contains the @code{cl-declaim}
2622 @defmac cl-declare decl-specs@dots{}
2623 This macro is used to make declarations within functions and other
2624 code. Common Lisp allows declarations in various locations, generally
2625 at the beginning of any of the many ``implicit @code{progn}s''
2626 throughout Lisp syntax, such as function bodies, @code{let} bodies,
2627 etc. Currently the only declaration understood by @code{cl-declare}
2631 @defmac cl-locally declarations@dots{} forms@dots{}
2632 In this package, @code{cl-locally} is no different from @code{progn}.
2635 @defmac cl-the type form
2636 Type information provided by @code{cl-the} is ignored in this package;
2637 in other words, @code{(cl-the @var{type} @var{form})} is equivalent
2638 to @var{form}. Future versions of the optimizing byte-compiler may
2639 make use of this information.
2641 For example, @code{mapcar} can map over both lists and arrays. It is
2642 hard for the compiler to expand @code{mapcar} into an in-line loop
2643 unless it knows whether the sequence will be a list or an array ahead
2644 of time. With @code{(mapcar 'car (cl-the vector foo))}, a future
2645 compiler would have enough information to expand the loop in-line.
2646 For now, Emacs Lisp will treat the above code as exactly equivalent
2647 to @code{(mapcar 'car foo)}.
2650 Each @var{decl-spec} in a @code{cl-proclaim}, @code{cl-declaim}, or
2651 @code{cl-declare} should be a list beginning with a symbol that says
2652 what kind of declaration it is. This package currently understands
2653 @code{special}, @code{inline}, @code{notinline}, @code{optimize},
2654 and @code{warn} declarations. (The @code{warn} declaration is an
2655 extension of standard Common Lisp.) Other Common Lisp declarations,
2656 such as @code{type} and @code{ftype}, are silently ignored.
2660 Since all variables in Emacs Lisp are ``special'' (in the Common
2661 Lisp sense), @code{special} declarations are only advisory. They
2662 simply tell the optimizing byte compiler that the specified
2663 variables are intentionally being referred to without being
2664 bound in the body of the function. The compiler normally emits
2665 warnings for such references, since they could be typographical
2666 errors for references to local variables.
2668 The declaration @code{(cl-declare (special @var{var1} @var{var2}))} is
2669 equivalent to @code{(defvar @var{var1}) (defvar @var{var2})} in the
2670 optimizing compiler, or to nothing at all in older compilers (which
2671 do not warn for non-local references).
2673 In top-level contexts, it is generally better to write
2674 @code{(defvar @var{var})} than @code{(cl-declaim (special @var{var}))},
2675 since @code{defvar} makes your intentions clearer. But the older
2676 byte compilers can not handle @code{defvar}s appearing inside of
2677 functions, while @code{(cl-declare (special @var{var}))} takes care
2678 to work correctly with all compilers.
2681 The @code{inline} @var{decl-spec} lists one or more functions
2682 whose bodies should be expanded ``in-line'' into calling functions
2683 whenever the compiler is able to arrange for it. For example,
2684 the Common Lisp function @code{cadr} is declared @code{inline}
2685 by this package so that the form @code{(cadr @var{x})} will
2686 expand directly into @code{(car (cdr @var{x}))} when it is called
2687 in user functions, for a savings of one (relatively expensive)
2690 The following declarations are all equivalent. Note that the
2691 @code{defsubst} form is a convenient way to define a function
2692 and declare it inline all at once.
2695 (cl-declaim (inline foo bar))
2696 (cl-eval-when (compile load eval)
2697 (cl-proclaim '(inline foo bar)))
2698 (defsubst foo (...) ...) ; instead of defun
2701 @strong{Please note:} this declaration remains in effect after the
2702 containing source file is done. It is correct to use it to
2703 request that a function you have defined should be inlined,
2704 but it is impolite to use it to request inlining of an external
2707 In Common Lisp, it is possible to use @code{(cl-declare (inline @dots{}))}
2708 before a particular call to a function to cause just that call to
2709 be inlined; the current byte compilers provide no way to implement
2710 this, so @code{(cl-declare (inline @dots{}))} is currently ignored by
2714 The @code{notinline} declaration lists functions which should
2715 not be inlined after all; it cancels a previous @code{inline}
2719 This declaration controls how much optimization is performed by
2720 the compiler. Naturally, it is ignored by the earlier non-optimizing
2723 The word @code{optimize} is followed by any number of lists like
2724 @code{(speed 3)} or @code{(safety 2)}. Common Lisp defines several
2725 optimization ``qualities''; this package ignores all but @code{speed}
2726 and @code{safety}. The value of a quality should be an integer from
2727 0 to 3, with 0 meaning ``unimportant'' and 3 meaning ``very important''.
2728 The default level for both qualities is 1.
2730 In this package, with the optimizing compiler, the
2731 @code{speed} quality is tied to the @code{byte-optimize}
2732 flag, which is set to @code{nil} for @code{(speed 0)} and to
2733 @code{t} for higher settings; and the @code{safety} quality is
2734 tied to the @code{byte-compile-delete-errors} flag, which is
2735 set to @code{nil} for @code{(safety 3)} and to @code{t} for all
2736 lower settings. (The latter flag controls whether the compiler
2737 is allowed to optimize out code whose only side-effect could
2738 be to signal an error, e.g., rewriting @code{(progn foo bar)} to
2739 @code{bar} when it is not known whether @code{foo} will be bound
2742 Note that even compiling with @code{(safety 0)}, the Emacs
2743 byte-code system provides sufficient checking to prevent real
2744 harm from being done. For example, barring serious bugs in
2745 Emacs itself, Emacs will not crash with a segmentation fault
2746 just because of an error in a fully-optimized Lisp program.
2748 The @code{optimize} declaration is normally used in a top-level
2749 @code{cl-proclaim} or @code{cl-declaim} in a file; Common Lisp allows
2750 it to be used with @code{cl-declare} to set the level of optimization
2751 locally for a given form, but this will not work correctly with the
2752 current version of the optimizing compiler. (The @code{cl-declare}
2753 will set the new optimization level, but that level will not
2754 automatically be unset after the enclosing form is done.)
2757 This declaration controls what sorts of warnings are generated
2758 by the byte compiler. Again, only the optimizing compiler
2759 generates warnings. The word @code{warn} is followed by any
2760 number of ``warning qualities'', similar in form to optimization
2761 qualities. The currently supported warning types are
2762 @code{redefine}, @code{callargs}, @code{unresolved}, and
2763 @code{free-vars}; in the current system, a value of 0 will
2764 disable these warnings and any higher value will enable them.
2765 See the documentation for the optimizing byte compiler for details.
2772 This package defines several symbol-related features that were
2773 missing from Emacs Lisp.
2776 * Property Lists:: @code{cl-get}, @code{cl-remprop}, @code{cl-getf}, @code{cl-remf}.
2777 * Creating Symbols:: @code{cl-gensym}, @code{cl-gentemp}.
2780 @node Property Lists
2781 @section Property Lists
2784 These functions augment the standard Emacs Lisp functions @code{get}
2785 and @code{put} for operating on properties attached to symbols.
2786 There are also functions for working with property lists as
2787 first-class data structures not attached to particular symbols.
2789 @defun cl-get symbol property &optional default
2790 This function is like @code{get}, except that if the property is
2791 not found, the @var{default} argument provides the return value.
2792 (The Emacs Lisp @code{get} function always uses @code{nil} as
2793 the default; this package's @code{cl-get} is equivalent to Common
2796 The @code{cl-get} function is @code{setf}-able; when used in this
2797 fashion, the @var{default} argument is allowed but ignored.
2800 @defun cl-remprop symbol property
2801 This function removes the entry for @var{property} from the property
2802 list of @var{symbol}. It returns a true value if the property was
2803 indeed found and removed, or @code{nil} if there was no such property.
2804 (This function was probably omitted from Emacs originally because,
2805 since @code{get} did not allow a @var{default}, it was very difficult
2806 to distinguish between a missing property and a property whose value
2807 was @code{nil}; thus, setting a property to @code{nil} was close
2808 enough to @code{cl-remprop} for most purposes.)
2811 @defun cl-getf place property &optional default
2812 This function scans the list @var{place} as if it were a property
2813 list, i.e., a list of alternating property names and values. If
2814 an even-numbered element of @var{place} is found which is @code{eq}
2815 to @var{property}, the following odd-numbered element is returned.
2816 Otherwise, @var{default} is returned (or @code{nil} if no default
2822 (get sym prop) @equiv{} (cl-getf (symbol-plist sym) prop)
2825 It is valid to use @code{cl-getf} as a @code{setf} place, in which case
2826 its @var{place} argument must itself be a valid @code{setf} place.
2827 The @var{default} argument, if any, is ignored in this context.
2828 The effect is to change (via @code{setcar}) the value cell in the
2829 list that corresponds to @var{property}, or to cons a new property-value
2830 pair onto the list if the property is not yet present.
2833 (put sym prop val) @equiv{} (setf (cl-getf (symbol-plist sym) prop) val)
2836 The @code{get} and @code{cl-get} functions are also @code{setf}-able.
2837 The fact that @code{default} is ignored can sometimes be useful:
2840 (cl-incf (cl-get 'foo 'usage-count 0))
2843 Here, symbol @code{foo}'s @code{usage-count} property is incremented
2844 if it exists, or set to 1 (an incremented 0) otherwise.
2846 When not used as a @code{setf} form, @code{cl-getf} is just a regular
2847 function and its @var{place} argument can actually be any Lisp
2851 @defmac cl-remf place property
2852 This macro removes the property-value pair for @var{property} from
2853 the property list stored at @var{place}, which is any @code{setf}-able
2854 place expression. It returns true if the property was found. Note
2855 that if @var{property} happens to be first on the list, this will
2856 effectively do a @code{(setf @var{place} (cddr @var{place}))},
2857 whereas if it occurs later, this simply uses @code{setcdr} to splice
2858 out the property and value cells.
2861 @node Creating Symbols
2862 @section Creating Symbols
2865 These functions create unique symbols, typically for use as
2866 temporary variables.
2868 @defun cl-gensym &optional x
2869 This function creates a new, uninterned symbol (using @code{make-symbol})
2870 with a unique name. (The name of an uninterned symbol is relevant
2871 only if the symbol is printed.) By default, the name is generated
2872 from an increasing sequence of numbers, @samp{G1000}, @samp{G1001},
2873 @samp{G1002}, etc. If the optional argument @var{x} is a string, that
2874 string is used as a prefix instead of @samp{G}. Uninterned symbols
2875 are used in macro expansions for temporary variables, to ensure that
2876 their names will not conflict with ``real'' variables in the user's
2880 @defvar cl--gensym-counter
2881 This variable holds the counter used to generate @code{cl-gensym} names.
2882 It is incremented after each use by @code{cl-gensym}. In Common Lisp
2883 this is initialized with 0, but this package initializes it with a
2884 random (time-dependent) value to avoid trouble when two files that
2885 each used @code{cl-gensym} in their compilation are loaded together.
2886 (Uninterned symbols become interned when the compiler writes them
2887 out to a file and the Emacs loader loads them, so their names have to
2888 be treated a bit more carefully than in Common Lisp where uninterned
2889 symbols remain uninterned after loading.)
2892 @defun cl-gentemp &optional x
2893 This function is like @code{cl-gensym}, except that it produces a new
2894 @emph{interned} symbol. If the symbol that is generated already
2895 exists, the function keeps incrementing the counter and trying
2896 again until a new symbol is generated.
2899 This package automatically creates all keywords that are called for by
2900 @code{&key} argument specifiers, and discourages the use of keywords
2901 as data unrelated to keyword arguments, so the related function
2902 @code{defkeyword} (to create self-quoting keyword symbols) is not
2909 This section defines a few simple Common Lisp operations on numbers
2910 which were left out of Emacs Lisp.
2913 * Predicates on Numbers:: @code{cl-plusp}, @code{cl-oddp}, @code{cl-floatp-safe}, etc.
2914 * Numerical Functions:: @code{abs}, @code{cl-floor}, etc.
2915 * Random Numbers:: @code{cl-random}, @code{cl-make-random-state}.
2916 * Implementation Parameters:: @code{cl-most-positive-float}.
2919 @node Predicates on Numbers
2920 @section Predicates on Numbers
2923 These functions return @code{t} if the specified condition is
2924 true of the numerical argument, or @code{nil} otherwise.
2926 @defun cl-plusp number
2927 This predicate tests whether @var{number} is positive. It is an
2928 error if the argument is not a number.
2931 @defun cl-minusp number
2932 This predicate tests whether @var{number} is negative. It is an
2933 error if the argument is not a number.
2936 @defun cl-oddp integer
2937 This predicate tests whether @var{integer} is odd. It is an
2938 error if the argument is not an integer.
2941 @defun cl-evenp integer
2942 This predicate tests whether @var{integer} is even. It is an
2943 error if the argument is not an integer.
2946 @defun cl-floatp-safe object
2947 This predicate tests whether @var{object} is a floating-point
2948 number. On systems that support floating-point, this is equivalent
2949 to @code{floatp}. On other systems, this always returns @code{nil}.
2952 @node Numerical Functions
2953 @section Numerical Functions
2956 These functions perform various arithmetic operations on numbers.
2958 @defun cl-gcd &rest integers
2959 This function returns the Greatest Common Divisor of the arguments.
2960 For one argument, it returns the absolute value of that argument.
2961 For zero arguments, it returns zero.
2964 @defun cl-lcm &rest integers
2965 This function returns the Least Common Multiple of the arguments.
2966 For one argument, it returns the absolute value of that argument.
2967 For zero arguments, it returns one.
2970 @defun cl-isqrt integer
2971 This function computes the ``integer square root'' of its integer
2972 argument, i.e., the greatest integer less than or equal to the true
2973 square root of the argument.
2976 @defun cl-floor number &optional divisor
2977 With one argument, @code{cl-floor} returns a list of two numbers:
2978 The argument rounded down (toward minus infinity) to an integer,
2979 and the ``remainder'' which would have to be added back to the
2980 first return value to yield the argument again. If the argument
2981 is an integer @var{x}, the result is always the list @code{(@var{x} 0)}.
2982 If the argument is a floating-point number, the first
2983 result is a Lisp integer and the second is a Lisp float between
2984 0 (inclusive) and 1 (exclusive).
2986 With two arguments, @code{cl-floor} divides @var{number} by
2987 @var{divisor}, and returns the floor of the quotient and the
2988 corresponding remainder as a list of two numbers. If
2989 @code{(cl-floor @var{x} @var{y})} returns @code{(@var{q} @var{r})},
2990 then @code{@var{q}*@var{y} + @var{r} = @var{x}}, with @var{r}
2991 between 0 (inclusive) and @var{r} (exclusive). Also, note
2992 that @code{(cl-floor @var{x})} is exactly equivalent to
2993 @code{(cl-floor @var{x} 1)}.
2995 This function is entirely compatible with Common Lisp's @code{floor}
2996 function, except that it returns the two results in a list since
2997 Emacs Lisp does not support multiple-valued functions.
3000 @defun cl-ceiling number &optional divisor
3001 This function implements the Common Lisp @code{ceiling} function,
3002 which is analogous to @code{floor} except that it rounds the
3003 argument or quotient of the arguments up toward plus infinity.
3004 The remainder will be between 0 and minus @var{r}.
3007 @defun cl-truncate number &optional divisor
3008 This function implements the Common Lisp @code{truncate} function,
3009 which is analogous to @code{floor} except that it rounds the
3010 argument or quotient of the arguments toward zero. Thus it is
3011 equivalent to @code{cl-floor} if the argument or quotient is
3012 positive, or to @code{cl-ceiling} otherwise. The remainder has
3013 the same sign as @var{number}.
3016 @defun cl-round number &optional divisor
3017 This function implements the Common Lisp @code{round} function,
3018 which is analogous to @code{floor} except that it rounds the
3019 argument or quotient of the arguments to the nearest integer.
3020 In the case of a tie (the argument or quotient is exactly
3021 halfway between two integers), it rounds to the even integer.
3024 @defun cl-mod number divisor
3025 This function returns the same value as the second return value
3029 @defun cl-rem number divisor
3030 This function returns the same value as the second return value
3031 of @code{cl-truncate}.
3034 @node Random Numbers
3035 @section Random Numbers
3038 This package also provides an implementation of the Common Lisp
3039 random number generator. It uses its own additive-congruential
3040 algorithm, which is much more likely to give statistically clean
3041 random numbers than the simple generators supplied by many
3044 @defun cl-random number &optional state
3045 This function returns a random nonnegative number less than
3046 @var{number}, and of the same type (either integer or floating-point).
3047 The @var{state} argument should be a @code{random-state} object
3048 which holds the state of the random number generator. The
3049 function modifies this state object as a side effect. If
3050 @var{state} is omitted, it defaults to the variable
3051 @code{cl--random-state}, which contains a pre-initialized
3052 @code{random-state} object.
3055 @defvar cl--random-state
3056 This variable contains the system ``default'' @code{random-state}
3057 object, used for calls to @code{cl-random} that do not specify an
3058 alternative state object. Since any number of programs in the
3059 Emacs process may be accessing @code{cl--random-state} in interleaved
3060 fashion, the sequence generated from this variable will be
3061 irreproducible for all intents and purposes.
3064 @defun cl-make-random-state &optional state
3065 This function creates or copies a @code{random-state} object.
3066 If @var{state} is omitted or @code{nil}, it returns a new copy of
3067 @code{cl--random-state}. This is a copy in the sense that future
3068 sequences of calls to @code{(cl-random @var{n})} and
3069 @code{(cl-random @var{n} @var{s})} (where @var{s} is the new
3070 random-state object) will return identical sequences of random
3073 If @var{state} is a @code{random-state} object, this function
3074 returns a copy of that object. If @var{state} is @code{t}, this
3075 function returns a new @code{random-state} object seeded from the
3076 date and time. As an extension to Common Lisp, @var{state} may also
3077 be an integer in which case the new object is seeded from that
3078 integer; each different integer seed will result in a completely
3079 different sequence of random numbers.
3081 It is valid to print a @code{random-state} object to a buffer or
3082 file and later read it back with @code{read}. If a program wishes
3083 to use a sequence of pseudo-random numbers which can be reproduced
3084 later for debugging, it can call @code{(cl-make-random-state t)} to
3085 get a new sequence, then print this sequence to a file. When the
3086 program is later rerun, it can read the original run's random-state
3090 @defun cl-random-state-p object
3091 This predicate returns @code{t} if @var{object} is a
3092 @code{random-state} object, or @code{nil} otherwise.
3095 @node Implementation Parameters
3096 @section Implementation Parameters
3099 This package defines several useful constants having to with numbers.
3101 The following parameters have to do with floating-point numbers.
3102 This package determines their values by exercising the computer's
3103 floating-point arithmetic in various ways. Because this operation
3104 might be slow, the code for initializing them is kept in a separate
3105 function that must be called before the parameters can be used.
3107 @defun cl-float-limits
3108 This function makes sure that the Common Lisp floating-point parameters
3109 like @code{cl-most-positive-float} have been initialized. Until it is
3110 called, these parameters will be @code{nil}. If this version of Emacs
3111 does not support floats, the parameters will remain @code{nil}. If the
3112 parameters have already been initialized, the function returns
3115 The algorithm makes assumptions that will be valid for most modern
3116 machines, but will fail if the machine's arithmetic is extremely
3117 unusual, e.g., decimal.
3120 Since true Common Lisp supports up to four different floating-point
3121 precisions, it has families of constants like
3122 @code{most-positive-single-float}, @code{most-positive-double-float},
3123 @code{most-positive-long-float}, and so on. Emacs has only one
3124 floating-point precision, so this package omits the precision word
3125 from the constants' names.
3127 @defvar cl-most-positive-float
3128 This constant equals the largest value a Lisp float can hold.
3129 For those systems whose arithmetic supports infinities, this is
3130 the largest @emph{finite} value. For IEEE machines, the value
3131 is approximately @code{1.79e+308}.
3134 @defvar cl-most-negative-float
3135 This constant equals the most-negative value a Lisp float can hold.
3136 (It is assumed to be equal to @code{(- cl-most-positive-float)}.)
3139 @defvar cl-least-positive-float
3140 This constant equals the smallest Lisp float value greater than zero.
3141 For IEEE machines, it is about @code{4.94e-324} if denormals are
3142 supported or @code{2.22e-308} if not.
3145 @defvar cl-least-positive-normalized-float
3146 This constant equals the smallest @emph{normalized} Lisp float greater
3147 than zero, i.e., the smallest value for which IEEE denormalization
3148 will not result in a loss of precision. For IEEE machines, this
3149 value is about @code{2.22e-308}. For machines that do not support
3150 the concept of denormalization and gradual underflow, this constant
3151 will always equal @code{cl-least-positive-float}.
3154 @defvar cl-least-negative-float
3155 This constant is the negative counterpart of @code{cl-least-positive-float}.
3158 @defvar cl-least-negative-normalized-float
3159 This constant is the negative counterpart of
3160 @code{cl-least-positive-normalized-float}.
3163 @defvar cl-float-epsilon
3164 This constant is the smallest positive Lisp float that can be added
3165 to 1.0 to produce a distinct value. Adding a smaller number to 1.0
3166 will yield 1.0 again due to roundoff. For IEEE machines, epsilon
3167 is about @code{2.22e-16}.
3170 @defvar cl-float-negative-epsilon
3171 This is the smallest positive value that can be subtracted from
3172 1.0 to produce a distinct value. For IEEE machines, it is about
3180 Common Lisp defines a number of functions that operate on
3181 @dfn{sequences}, which are either lists, strings, or vectors.
3182 Emacs Lisp includes a few of these, notably @code{elt} and
3183 @code{length}; this package defines most of the rest.
3186 * Sequence Basics:: Arguments shared by all sequence functions.
3187 * Mapping over Sequences:: @code{cl-mapcar}, @code{cl-mapcan}, @code{cl-map}, @code{cl-every}, etc.
3188 * Sequence Functions:: @code{cl-subseq}, @code{cl-remove}, @code{cl-substitute}, etc.
3189 * Searching Sequences:: @code{cl-find}, @code{cl-position}, @code{cl-count}, @code{cl-search}, etc.
3190 * Sorting Sequences:: @code{cl-sort}, @code{cl-stable-sort}, @code{cl-merge}.
3193 @node Sequence Basics
3194 @section Sequence Basics
3197 Many of the sequence functions take keyword arguments; @pxref{Argument
3198 Lists}. All keyword arguments are optional and, if specified,
3199 may appear in any order.
3201 The @code{:key} argument should be passed either @code{nil}, or a
3202 function of one argument. This key function is used as a filter
3203 through which the elements of the sequence are seen; for example,
3204 @code{(cl-find x y :key 'car)} is similar to @code{(cl-assoc x y)}:
3205 It searches for an element of the list whose @code{car} equals
3206 @code{x}, rather than for an element which equals @code{x} itself.
3207 If @code{:key} is omitted or @code{nil}, the filter is effectively
3208 the identity function.
3210 The @code{:test} and @code{:test-not} arguments should be either
3211 @code{nil}, or functions of two arguments. The test function is
3212 used to compare two sequence elements, or to compare a search value
3213 with sequence elements. (The two values are passed to the test
3214 function in the same order as the original sequence function
3215 arguments from which they are derived, or, if they both come from
3216 the same sequence, in the same order as they appear in that sequence.)
3217 The @code{:test} argument specifies a function which must return
3218 true (non-@code{nil}) to indicate a match; instead, you may use
3219 @code{:test-not} to give a function which returns @emph{false} to
3220 indicate a match. The default test function is @code{eql}.
3222 Many functions which take @var{item} and @code{:test} or @code{:test-not}
3223 arguments also come in @code{-if} and @code{-if-not} varieties,
3224 where a @var{predicate} function is passed instead of @var{item},
3225 and sequence elements match if the predicate returns true on them
3226 (or false in the case of @code{-if-not}). For example:
3229 (cl-remove 0 seq :test '=) @equiv{} (cl-remove-if 'zerop seq)
3233 to remove all zeros from sequence @code{seq}.
3235 Some operations can work on a subsequence of the argument sequence;
3236 these function take @code{:start} and @code{:end} arguments which
3237 default to zero and the length of the sequence, respectively.
3238 Only elements between @var{start} (inclusive) and @var{end}
3239 (exclusive) are affected by the operation. The @var{end} argument
3240 may be passed @code{nil} to signify the length of the sequence;
3241 otherwise, both @var{start} and @var{end} must be integers, with
3242 @code{0 <= @var{start} <= @var{end} <= (length @var{seq})}.
3243 If the function takes two sequence arguments, the limits are
3244 defined by keywords @code{:start1} and @code{:end1} for the first,
3245 and @code{:start2} and @code{:end2} for the second.
3247 A few functions accept a @code{:from-end} argument, which, if
3248 non-@code{nil}, causes the operation to go from right-to-left
3249 through the sequence instead of left-to-right, and a @code{:count}
3250 argument, which specifies an integer maximum number of elements
3251 to be removed or otherwise processed.
3253 The sequence functions make no guarantees about the order in
3254 which the @code{:test}, @code{:test-not}, and @code{:key} functions
3255 are called on various elements. Therefore, it is a bad idea to depend
3256 on side effects of these functions. For example, @code{:from-end}
3257 may cause the sequence to be scanned actually in reverse, or it may
3258 be scanned forwards but computing a result ``as if'' it were scanned
3259 backwards. (Some functions, like @code{cl-mapcar} and @code{cl-every},
3260 @emph{do} specify exactly the order in which the function is called
3261 so side effects are perfectly acceptable in those cases.)
3263 Strings may contain ``text properties'' as well
3264 as character data. Except as noted, it is undefined whether or
3265 not text properties are preserved by sequence functions. For
3266 example, @code{(cl-remove ?A @var{str})} may or may not preserve
3267 the properties of the characters copied from @var{str} into the
3270 @node Mapping over Sequences
3271 @section Mapping over Sequences
3274 These functions ``map'' the function you specify over the elements
3275 of lists or arrays. They are all variations on the theme of the
3276 built-in function @code{mapcar}.
3278 @defun cl-mapcar function seq &rest more-seqs
3279 This function calls @var{function} on successive parallel sets of
3280 elements from its argument sequences. Given a single @var{seq}
3281 argument it is equivalent to @code{mapcar}; given @var{n} sequences,
3282 it calls the function with the first elements of each of the sequences
3283 as the @var{n} arguments to yield the first element of the result
3284 list, then with the second elements, and so on. The mapping stops as
3285 soon as the shortest sequence runs out. The argument sequences may
3286 be any mixture of lists, strings, and vectors; the return sequence
3289 Common Lisp's @code{mapcar} accepts multiple arguments but works
3290 only on lists; Emacs Lisp's @code{mapcar} accepts a single sequence
3291 argument. This package's @code{cl-mapcar} works as a compatible
3295 @defun cl-map result-type function seq &rest more-seqs
3296 This function maps @var{function} over the argument sequences,
3297 just like @code{cl-mapcar}, but it returns a sequence of type
3298 @var{result-type} rather than a list. @var{result-type} must
3299 be one of the following symbols: @code{vector}, @code{string},
3300 @code{list} (in which case the effect is the same as for
3301 @code{cl-mapcar}), or @code{nil} (in which case the results are
3302 thrown away and @code{cl-map} returns @code{nil}).
3305 @defun cl-maplist function list &rest more-lists
3306 This function calls @var{function} on each of its argument lists,
3307 then on the @code{cdr}s of those lists, and so on, until the
3308 shortest list runs out. The results are returned in the form
3309 of a list. Thus, @code{cl-maplist} is like @code{cl-mapcar} except
3310 that it passes in the list pointers themselves rather than the
3311 @code{car}s of the advancing pointers.
3314 @defun cl-mapc function seq &rest more-seqs
3315 This function is like @code{cl-mapcar}, except that the values returned
3316 by @var{function} are ignored and thrown away rather than being
3317 collected into a list. The return value of @code{cl-mapc} is @var{seq},
3318 the first sequence. This function is more general than the Emacs
3319 primitive @code{mapc}. (Note that this function is called
3320 @code{cl-mapc} even in @file{cl.el}, rather than @code{map*} as you
3322 @c http://debbugs.gnu.org/6575
3325 @defun cl-mapl function list &rest more-lists
3326 This function is like @code{cl-maplist}, except that it throws away
3327 the values returned by @var{function}.
3330 @defun cl-mapcan function seq &rest more-seqs
3331 This function is like @code{cl-mapcar}, except that it concatenates
3332 the return values (which must be lists) using @code{nconc},
3333 rather than simply collecting them into a list.
3336 @defun cl-mapcon function list &rest more-lists
3337 This function is like @code{cl-maplist}, except that it concatenates
3338 the return values using @code{nconc}.
3341 @defun cl-some predicate seq &rest more-seqs
3342 This function calls @var{predicate} on each element of @var{seq}
3343 in turn; if @var{predicate} returns a non-@code{nil} value,
3344 @code{some} returns that value, otherwise it returns @code{nil}.
3345 Given several sequence arguments, it steps through the sequences
3346 in parallel until the shortest one runs out, just as in
3347 @code{cl-mapcar}. You can rely on the left-to-right order in which
3348 the elements are visited, and on the fact that mapping stops
3349 immediately as soon as @var{predicate} returns non-@code{nil}.
3352 @defun cl-every predicate seq &rest more-seqs
3353 This function calls @var{predicate} on each element of the sequence(s)
3354 in turn; it returns @code{nil} as soon as @var{predicate} returns
3355 @code{nil} for any element, or @code{t} if the predicate was true
3359 @defun cl-notany 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 a non-@code{nil} value for any element, or @code{t} if the predicate
3363 was @code{nil} for all elements.
3366 @defun cl-notevery predicate seq &rest more-seqs
3367 This function calls @var{predicate} on each element of the sequence(s)
3368 in turn; it returns a non-@code{nil} value as soon as @var{predicate}
3369 returns @code{nil} for any element, or @code{t} if the predicate was
3370 true for all elements.
3373 @defun cl-reduce function seq @t{&key :from-end :start :end :initial-value :key}
3374 This function combines the elements of @var{seq} using an associative
3375 binary operation. Suppose @var{function} is @code{*} and @var{seq} is
3376 the list @code{(2 3 4 5)}. The first two elements of the list are
3377 combined with @code{(* 2 3) = 6}; this is combined with the next
3378 element, @code{(* 6 4) = 24}, and that is combined with the final
3379 element: @code{(* 24 5) = 120}. Note that the @code{*} function happens
3380 to be self-reducing, so that @code{(* 2 3 4 5)} has the same effect as
3381 an explicit call to @code{cl-reduce}.
3383 If @code{:from-end} is true, the reduction is right-associative instead
3384 of left-associative:
3387 (cl-reduce '- '(1 2 3 4))
3388 @equiv{} (- (- (- 1 2) 3) 4) @result{} -8
3389 (cl-reduce '- '(1 2 3 4) :from-end t)
3390 @equiv{} (- 1 (- 2 (- 3 4))) @result{} -2
3393 If @code{:key} is specified, it is a function of one argument which
3394 is called on each of the sequence elements in turn.
3396 If @code{:initial-value} is specified, it is effectively added to the
3397 front (or rear in the case of @code{:from-end}) of the sequence.
3398 The @code{:key} function is @emph{not} applied to the initial value.
3400 If the sequence, including the initial value, has exactly one element
3401 then that element is returned without ever calling @var{function}.
3402 If the sequence is empty (and there is no initial value), then
3403 @var{function} is called with no arguments to obtain the return value.
3406 All of these mapping operations can be expressed conveniently in
3407 terms of the @code{cl-loop} macro. In compiled code, @code{cl-loop} will
3408 be faster since it generates the loop as in-line code with no
3411 @node Sequence Functions
3412 @section Sequence Functions
3415 This section describes a number of Common Lisp functions for
3416 operating on sequences.
3418 @defun cl-subseq sequence start &optional end
3419 This function returns a given subsequence of the argument
3420 @var{sequence}, which may be a list, string, or vector.
3421 The indices @var{start} and @var{end} must be in range, and
3422 @var{start} must be no greater than @var{end}. If @var{end}
3423 is omitted, it defaults to the length of the sequence. The
3424 return value is always a copy; it does not share structure
3425 with @var{sequence}.
3427 As an extension to Common Lisp, @var{start} and/or @var{end}
3428 may be negative, in which case they represent a distance back
3429 from the end of the sequence. This is for compatibility with
3430 Emacs's @code{substring} function. Note that @code{cl-subseq} is
3431 the @emph{only} sequence function that allows negative
3432 @var{start} and @var{end}.
3434 You can use @code{setf} on a @code{cl-subseq} form to replace a
3435 specified range of elements with elements from another sequence.
3436 The replacement is done as if by @code{cl-replace}, described below.
3439 @defun cl-concatenate result-type &rest seqs
3440 This function concatenates the argument sequences together to
3441 form a result sequence of type @var{result-type}, one of the
3442 symbols @code{vector}, @code{string}, or @code{list}. The
3443 arguments are always copied, even in cases such as
3444 @code{(cl-concatenate 'list '(1 2 3))} where the result is
3445 identical to an argument.
3448 @defun cl-fill seq item @t{&key :start :end}
3449 This function fills the elements of the sequence (or the specified
3450 part of the sequence) with the value @var{item}.
3453 @defun cl-replace seq1 seq2 @t{&key :start1 :end1 :start2 :end2}
3454 This function copies part of @var{seq2} into part of @var{seq1}.
3455 The sequence @var{seq1} is not stretched or resized; the amount
3456 of data copied is simply the shorter of the source and destination
3457 (sub)sequences. The function returns @var{seq1}.
3459 If @var{seq1} and @var{seq2} are @code{eq}, then the replacement
3460 will work correctly even if the regions indicated by the start
3461 and end arguments overlap. However, if @var{seq1} and @var{seq2}
3462 are lists which share storage but are not @code{eq}, and the
3463 start and end arguments specify overlapping regions, the effect
3467 @defun cl-remove item seq @t{&key :test :test-not :key :count :start :end :from-end}
3468 This returns a copy of @var{seq} with all elements matching
3469 @var{item} removed. The result may share storage with or be
3470 @code{eq} to @var{seq} in some circumstances, but the original
3471 @var{seq} will not be modified. The @code{:test}, @code{:test-not},
3472 and @code{:key} arguments define the matching test that is used;
3473 by default, elements @code{eql} to @var{item} are removed. The
3474 @code{:count} argument specifies the maximum number of matching
3475 elements that can be removed (only the leftmost @var{count} matches
3476 are removed). The @code{:start} and @code{:end} arguments specify
3477 a region in @var{seq} in which elements will be removed; elements
3478 outside that region are not matched or removed. The @code{:from-end}
3479 argument, if true, says that elements should be deleted from the
3480 end of the sequence rather than the beginning (this matters only
3481 if @var{count} was also specified).
3484 @defun cl-delete item seq @t{&key :test :test-not :key :count :start :end :from-end}
3485 This deletes all elements of @var{seq} which match @var{item}.
3486 It is a destructive operation. Since Emacs Lisp does not support
3487 stretchable strings or vectors, this is the same as @code{cl-remove}
3488 for those sequence types. On lists, @code{cl-remove} will copy the
3489 list if necessary to preserve the original list, whereas
3490 @code{cl-delete} will splice out parts of the argument list.
3491 Compare @code{append} and @code{nconc}, which are analogous
3492 non-destructive and destructive list operations in Emacs Lisp.
3495 @findex cl-remove-if
3496 @findex cl-remove-if-not
3497 @findex cl-delete-if
3498 @findex cl-delete-if-not
3499 The predicate-oriented functions @code{cl-remove-if}, @code{cl-remove-if-not},
3500 @code{cl-delete-if}, and @code{cl-delete-if-not} are defined similarly.
3502 @defun cl-remove-duplicates seq @t{&key :test :test-not :key :start :end :from-end}
3503 This function returns a copy of @var{seq} with duplicate elements
3504 removed. Specifically, if two elements from the sequence match
3505 according to the @code{:test}, @code{:test-not}, and @code{:key}
3506 arguments, only the rightmost one is retained. If @code{:from-end}
3507 is true, the leftmost one is retained instead. If @code{:start} or
3508 @code{:end} is specified, only elements within that subsequence are
3509 examined or removed.
3512 @defun cl-delete-duplicates seq @t{&key :test :test-not :key :start :end :from-end}
3513 This function deletes duplicate elements from @var{seq}. It is
3514 a destructive version of @code{cl-remove-duplicates}.
3517 @defun cl-substitute new old seq @t{&key :test :test-not :key :count :start :end :from-end}
3518 This function returns a copy of @var{seq}, with all elements
3519 matching @var{old} replaced with @var{new}. The @code{:count},
3520 @code{:start}, @code{:end}, and @code{:from-end} arguments may be
3521 used to limit the number of substitutions made.
3524 @defun cl-nsubstitute new old seq @t{&key :test :test-not :key :count :start :end :from-end}
3525 This is a destructive version of @code{cl-substitute}; it performs
3526 the substitution using @code{setcar} or @code{aset} rather than
3527 by returning a changed copy of the sequence.
3530 @findex cl-substitute-if
3531 @findex cl-substitute-if-not
3532 @findex cl-nsubstitute-if
3533 @findex cl-nsubstitute-if-not
3534 The functions @code{cl-substitute-if}, @code{cl-substitute-if-not},
3535 @code{cl-nsubstitute-if}, and @code{cl-nsubstitute-if-not} are defined
3536 similarly. For these, a @var{predicate} is given in place of the
3539 @node Searching Sequences
3540 @section Searching Sequences
3543 These functions search for elements or subsequences in a sequence.
3544 (See also @code{cl-member} and @code{cl-assoc}; @pxref{Lists}.)
3546 @defun cl-find item seq @t{&key :test :test-not :key :start :end :from-end}
3547 This function searches @var{seq} for an element matching @var{item}.
3548 If it finds a match, it returns the matching element. Otherwise,
3549 it returns @code{nil}. It returns the leftmost match, unless
3550 @code{:from-end} is true, in which case it returns the rightmost
3551 match. The @code{:start} and @code{:end} arguments may be used to
3552 limit the range of elements that are searched.
3555 @defun cl-position item seq @t{&key :test :test-not :key :start :end :from-end}
3556 This function is like @code{cl-find}, except that it returns the
3557 integer position in the sequence of the matching item rather than
3558 the item itself. The position is relative to the start of the
3559 sequence as a whole, even if @code{:start} is non-zero. The function
3560 returns @code{nil} if no matching element was found.
3563 @defun cl-count item seq @t{&key :test :test-not :key :start :end}
3564 This function returns the number of elements of @var{seq} which
3565 match @var{item}. The result is always a nonnegative integer.
3569 @findex cl-find-if-not
3570 @findex cl-position-if
3571 @findex cl-position-if-not
3573 @findex cl-count-if-not
3574 The @code{cl-find-if}, @code{cl-find-if-not}, @code{cl-position-if},
3575 @code{cl-position-if-not}, @code{cl-count-if}, and @code{cl-count-if-not}
3576 functions are defined similarly.
3578 @defun cl-mismatch seq1 seq2 @t{&key :test :test-not :key :start1 :end1 :start2 :end2 :from-end}
3579 This function compares the specified parts of @var{seq1} and
3580 @var{seq2}. If they are the same length and the corresponding
3581 elements match (according to @code{:test}, @code{:test-not},
3582 and @code{:key}), the function returns @code{nil}. If there is
3583 a mismatch, the function returns the index (relative to @var{seq1})
3584 of the first mismatching element. This will be the leftmost pair of
3585 elements which do not match, or the position at which the shorter of
3586 the two otherwise-matching sequences runs out.
3588 If @code{:from-end} is true, then the elements are compared from right
3589 to left starting at @code{(1- @var{end1})} and @code{(1- @var{end2})}.
3590 If the sequences differ, then one plus the index of the rightmost
3591 difference (relative to @var{seq1}) is returned.
3593 An interesting example is @code{(cl-mismatch str1 str2 :key 'upcase)},
3594 which compares two strings case-insensitively.
3597 @defun cl-search seq1 seq2 @t{&key :test :test-not :key :from-end :start1 :end1 :start2 :end2}
3598 This function searches @var{seq2} for a subsequence that matches
3599 @var{seq1} (or part of it specified by @code{:start1} and
3600 @code{:end1}.) Only matches which fall entirely within the region
3601 defined by @code{:start2} and @code{:end2} will be considered.
3602 The return value is the index of the leftmost element of the
3603 leftmost match, relative to the start of @var{seq2}, or @code{nil}
3604 if no matches were found. If @code{:from-end} is true, the
3605 function finds the @emph{rightmost} matching subsequence.
3608 @node Sorting Sequences
3609 @section Sorting Sequences
3611 @defun clsort seq predicate @t{&key :key}
3612 This function sorts @var{seq} into increasing order as determined
3613 by using @var{predicate} to compare pairs of elements. @var{predicate}
3614 should return true (non-@code{nil}) if and only if its first argument
3615 is less than (not equal to) its second argument. For example,
3616 @code{<} and @code{string-lessp} are suitable predicate functions
3617 for sorting numbers and strings, respectively; @code{>} would sort
3618 numbers into decreasing rather than increasing order.
3620 This function differs from Emacs's built-in @code{sort} in that it
3621 can operate on any type of sequence, not just lists. Also, it
3622 accepts a @code{:key} argument which is used to preprocess data
3623 fed to the @var{predicate} function. For example,
3626 (setq data (cl-sort data 'string-lessp :key 'downcase))
3630 sorts @var{data}, a sequence of strings, into increasing alphabetical
3631 order without regard to case. A @code{:key} function of @code{car}
3632 would be useful for sorting association lists. It should only be a
3633 simple accessor though, it's used heavily in the current
3636 The @code{cl-sort} function is destructive; it sorts lists by actually
3637 rearranging the @code{cdr} pointers in suitable fashion.
3640 @defun cl-stable-sort seq predicate @t{&key :key}
3641 This function sorts @var{seq} @dfn{stably}, meaning two elements
3642 which are equal in terms of @var{predicate} are guaranteed not to
3643 be rearranged out of their original order by the sort.
3645 In practice, @code{cl-sort} and @code{cl-stable-sort} are equivalent
3646 in Emacs Lisp because the underlying @code{sort} function is
3647 stable by default. However, this package reserves the right to
3648 use non-stable methods for @code{cl-sort} in the future.
3651 @defun cl-merge type seq1 seq2 predicate @t{&key :key}
3652 This function merges two sequences @var{seq1} and @var{seq2} by
3653 interleaving their elements. The result sequence, of type @var{type}
3654 (in the sense of @code{cl-concatenate}), has length equal to the sum
3655 of the lengths of the two input sequences. The sequences may be
3656 modified destructively. Order of elements within @var{seq1} and
3657 @var{seq2} is preserved in the interleaving; elements of the two
3658 sequences are compared by @var{predicate} (in the sense of
3659 @code{sort}) and the lesser element goes first in the result.
3660 When elements are equal, those from @var{seq1} precede those from
3661 @var{seq2} in the result. Thus, if @var{seq1} and @var{seq2} are
3662 both sorted according to @var{predicate}, then the result will be
3663 a merged sequence which is (stably) sorted according to
3671 The functions described here operate on lists.
3674 * List Functions:: @code{cl-caddr}, @code{cl-first}, @code{cl-list*}, etc.
3675 * Substitution of Expressions:: @code{cl-subst}, @code{cl-sublis}, etc.
3676 * Lists as Sets:: @code{cl-member}, @code{cl-adjoin}, @code{cl-union}, etc.
3677 * Association Lists:: @code{cl-assoc}, @code{cl-rassoc}, @code{cl-acons}, @code{cl-pairlis}.
3680 @node List Functions
3681 @section List Functions
3684 This section describes a number of simple operations on lists,
3685 i.e., chains of cons cells.
3688 This function is equivalent to @code{(car (cdr (cdr @var{x})))}.
3689 Likewise, this package defines all 28 @code{c@var{xxx}r} functions
3690 where @var{xxx} is up to four @samp{a}s and/or @samp{d}s.
3691 All of these functions are @code{setf}-able, and calls to them
3692 are expanded inline by the byte-compiler for maximum efficiency.
3696 This function is a synonym for @code{(car @var{x})}. Likewise,
3697 the functions @code{cl-second}, @code{cl-third}, @dots{}, through
3698 @code{cl-tenth} return the given element of the list @var{x}.
3702 This function is a synonym for @code{(cdr @var{x})}.
3706 Common Lisp defines this function to act like @code{null}, but
3707 signaling an error if @code{x} is neither a @code{nil} nor a
3708 cons cell. This package simply defines @code{cl-endp} as a synonym
3712 @defun cl-list-length x
3713 This function returns the length of list @var{x}, exactly like
3714 @code{(length @var{x})}, except that if @var{x} is a circular
3715 list (where the cdr-chain forms a loop rather than terminating
3716 with @code{nil}), this function returns @code{nil}. (The regular
3717 @code{length} function would get stuck if given a circular list.)
3720 @defun cl-list* arg &rest others
3721 This function constructs a list of its arguments. The final
3722 argument becomes the @code{cdr} of the last cell constructed.
3723 Thus, @code{(cl-list* @var{a} @var{b} @var{c})} is equivalent to
3724 @code{(cons @var{a} (cons @var{b} @var{c}))}, and
3725 @code{(cl-list* @var{a} @var{b} nil)} is equivalent to
3726 @code{(list @var{a} @var{b})}.
3729 @defun cl-ldiff list sublist
3730 If @var{sublist} is a sublist of @var{list}, i.e., is @code{eq} to
3731 one of the cons cells of @var{list}, then this function returns
3732 a copy of the part of @var{list} up to but not including
3733 @var{sublist}. For example, @code{(cl-ldiff x (cddr x))} returns
3734 the first two elements of the list @code{x}. The result is a
3735 copy; the original @var{list} is not modified. If @var{sublist}
3736 is not a sublist of @var{list}, a copy of the entire @var{list}
3740 @defun cl-copy-list list
3741 This function returns a copy of the list @var{list}. It copies
3742 dotted lists like @code{(1 2 . 3)} correctly.
3745 @defun copy-tree x &optional vecp
3746 This function returns a copy of the tree of cons cells @var{x}.
3747 @c FIXME? cl-copy-list is not an alias of copy-sequence.
3748 Unlike @code{copy-sequence} (and its alias @code{cl-copy-list}),
3749 which copies only along the @code{cdr} direction, this function
3750 copies (recursively) along both the @code{car} and the @code{cdr}
3751 directions. If @var{x} is not a cons cell, the function simply
3752 returns @var{x} unchanged. If the optional @var{vecp} argument
3753 is true, this function copies vectors (recursively) as well as
3757 @defun cl-tree-equal x y @t{&key :test :test-not :key}
3758 This function compares two trees of cons cells. If @var{x} and
3759 @var{y} are both cons cells, their @code{car}s and @code{cdr}s are
3760 compared recursively. If neither @var{x} nor @var{y} is a cons
3761 cell, they are compared by @code{eql}, or according to the
3762 specified test. The @code{:key} function, if specified, is
3763 applied to the elements of both trees. @xref{Sequences}.
3766 @node Substitution of Expressions
3767 @section Substitution of Expressions
3770 These functions substitute elements throughout a tree of cons
3771 cells. (@xref{Sequence Functions}, for the @code{cl-substitute}
3772 function, which works on just the top-level elements of a list.)
3774 @defun cl-subst new old tree @t{&key :test :test-not :key}
3775 This function substitutes occurrences of @var{old} with @var{new}
3776 in @var{tree}, a tree of cons cells. It returns a substituted
3777 tree, which will be a copy except that it may share storage with
3778 the argument @var{tree} in parts where no substitutions occurred.
3779 The original @var{tree} is not modified. This function recurses
3780 on, and compares against @var{old}, both @code{car}s and @code{cdr}s
3781 of the component cons cells. If @var{old} is itself a cons cell,
3782 then matching cells in the tree are substituted as usual without
3783 recursively substituting in that cell. Comparisons with @var{old}
3784 are done according to the specified test (@code{eql} by default).
3785 The @code{:key} function is applied to the elements of the tree
3786 but not to @var{old}.
3789 @defun cl-nsubst new old tree @t{&key :test :test-not :key}
3790 This function is like @code{cl-subst}, except that it works by
3791 destructive modification (by @code{setcar} or @code{setcdr})
3792 rather than copying.
3796 @findex cl-subst-if-not
3797 @findex cl-nsubst-if
3798 @findex cl-nsubst-if-not
3799 The @code{cl-subst-if}, @code{cl-subst-if-not}, @code{cl-nsubst-if}, and
3800 @code{cl-nsubst-if-not} functions are defined similarly.
3802 @defun cl-sublis alist tree @t{&key :test :test-not :key}
3803 This function is like @code{cl-subst}, except that it takes an
3804 association list @var{alist} of @var{old}-@var{new} pairs.
3805 Each element of the tree (after applying the @code{:key}
3806 function, if any), is compared with the @code{car}s of
3807 @var{alist}; if it matches, it is replaced by the corresponding
3811 @defun cl-nsublis alist tree @t{&key :test :test-not :key}
3812 This is a destructive version of @code{cl-sublis}.
3816 @section Lists as Sets
3819 These functions perform operations on lists which represent sets
3822 @defun cl-member item list @t{&key :test :test-not :key}
3823 This function searches @var{list} for an element matching @var{item}.
3824 If a match is found, it returns the cons cell whose @code{car} was
3825 the matching element. Otherwise, it returns @code{nil}. Elements
3826 are compared by @code{eql} by default; you can use the @code{:test},
3827 @code{:test-not}, and @code{:key} arguments to modify this behavior.
3830 The standard Emacs lisp function @code{member} uses @code{equal} for
3831 comparisons; it is equivalent to @code{(cl-member @var{item} @var{list}
3835 @findex cl-member-if
3836 @findex cl-member-if-not
3837 The @code{cl-member-if} and @code{cl-member-if-not} functions
3838 analogously search for elements which satisfy a given predicate.
3840 @defun cl-tailp sublist list
3841 This function returns @code{t} if @var{sublist} is a sublist of
3842 @var{list}, i.e., if @var{sublist} is @code{eql} to @var{list} or to
3843 any of its @code{cdr}s.
3846 @defun cl-adjoin item list @t{&key :test :test-not :key}
3847 This function conses @var{item} onto the front of @var{list},
3848 like @code{(cons @var{item} @var{list})}, but only if @var{item}
3849 is not already present on the list (as determined by @code{cl-member}).
3850 If a @code{:key} argument is specified, it is applied to
3851 @var{item} as well as to the elements of @var{list} during
3852 the search, on the reasoning that @var{item} is ``about'' to
3853 become part of the list.
3856 @defun cl-union list1 list2 @t{&key :test :test-not :key}
3857 This function combines two lists which represent sets of items,
3858 returning a list that represents the union of those two sets.
3859 The result list will contain all items which appear in @var{list1}
3860 or @var{list2}, and no others. If an item appears in both
3861 @var{list1} and @var{list2} it will be copied only once. If
3862 an item is duplicated in @var{list1} or @var{list2}, it is
3863 undefined whether or not that duplication will survive in the
3864 result list. The order of elements in the result list is also
3868 @defun cl-nunion list1 list2 @t{&key :test :test-not :key}
3869 This is a destructive version of @code{cl-union}; rather than copying,
3870 it tries to reuse the storage of the argument lists if possible.
3873 @defun cl-intersection list1 list2 @t{&key :test :test-not :key}
3874 This function computes the intersection of the sets represented
3875 by @var{list1} and @var{list2}. It returns the list of items
3876 which appear in both @var{list1} and @var{list2}.
3879 @defun cl-nintersection list1 list2 @t{&key :test :test-not :key}
3880 This is a destructive version of @code{cl-intersection}. It
3881 tries to reuse storage of @var{list1} rather than copying.
3882 It does @emph{not} reuse the storage of @var{list2}.
3885 @defun cl-set-difference list1 list2 @t{&key :test :test-not :key}
3886 This function computes the ``set difference'' of @var{list1}
3887 and @var{list2}, i.e., the set of elements that appear in
3888 @var{list1} but @emph{not} in @var{list2}.
3891 @defun cl-nset-difference list1 list2 @t{&key :test :test-not :key}
3892 This is a destructive @code{cl-set-difference}, which will try
3893 to reuse @var{list1} if possible.
3896 @defun cl-set-exclusive-or list1 list2 @t{&key :test :test-not :key}
3897 This function computes the ``set exclusive or'' of @var{list1}
3898 and @var{list2}, i.e., the set of elements that appear in
3899 exactly one of @var{list1} and @var{list2}.
3902 @defun cl-nset-exclusive-or list1 list2 @t{&key :test :test-not :key}
3903 This is a destructive @code{cl-set-exclusive-or}, which will try
3904 to reuse @var{list1} and @var{list2} if possible.
3907 @defun cl-subsetp list1 list2 @t{&key :test :test-not :key}
3908 This function checks whether @var{list1} represents a subset
3909 of @var{list2}, i.e., whether every element of @var{list1}
3910 also appears in @var{list2}.
3913 @node Association Lists
3914 @section Association Lists
3917 An @dfn{association list} is a list representing a mapping from
3918 one set of values to another; any list whose elements are cons
3919 cells is an association list.
3921 @defun cl-assoc item a-list @t{&key :test :test-not :key}
3922 This function searches the association list @var{a-list} for an
3923 element whose @code{car} matches (in the sense of @code{:test},
3924 @code{:test-not}, and @code{:key}, or by comparison with @code{eql})
3925 a given @var{item}. It returns the matching element, if any,
3926 otherwise @code{nil}. It ignores elements of @var{a-list} which
3927 are not cons cells. (This corresponds to the behavior of
3928 @code{assq} and @code{assoc} in Emacs Lisp; Common Lisp's
3929 @code{assoc} ignores @code{nil}s but considers any other non-cons
3930 elements of @var{a-list} to be an error.)
3933 @defun cl-rassoc item a-list @t{&key :test :test-not :key}
3934 This function searches for an element whose @code{cdr} matches
3935 @var{item}. If @var{a-list} represents a mapping, this applies
3936 the inverse of the mapping to @var{item}.
3940 @findex cl-assoc-if-not
3941 @findex cl-rassoc-if
3942 @findex cl-rassoc-if-not
3943 The @code{cl-assoc-if}, @code{cl-assoc-if-not}, @code{cl-rassoc-if},
3944 and @code{cl-rassoc-if-not} functions are defined similarly.
3946 Two simple functions for constructing association lists are:
3948 @defun cl-acons key value alist
3949 This is equivalent to @code{(cons (cons @var{key} @var{value}) @var{alist})}.
3952 @defun cl-pairlis keys values &optional alist
3953 This is equivalent to @code{(nconc (cl-mapcar 'cons @var{keys} @var{values})
3961 The Common Lisp @dfn{structure} mechanism provides a general way
3962 to define data types similar to C's @code{struct} types. A
3963 structure is a Lisp object containing some number of @dfn{slots},
3964 each of which can hold any Lisp data object. Functions are
3965 provided for accessing and setting the slots, creating or copying
3966 structure objects, and recognizing objects of a particular structure
3969 In true Common Lisp, each structure type is a new type distinct
3970 from all existing Lisp types. Since the underlying Emacs Lisp
3971 system provides no way to create new distinct types, this package
3972 implements structures as vectors (or lists upon request) with a
3973 special ``tag'' symbol to identify them.
3975 @defmac cl-defstruct name slots@dots{}
3976 The @code{cl-defstruct} form defines a new structure type called
3977 @var{name}, with the specified @var{slots}. (The @var{slots}
3978 may begin with a string which documents the structure type.)
3979 In the simplest case, @var{name} and each of the @var{slots}
3980 are symbols. For example,
3983 (cl-defstruct person name age sex)
3987 defines a struct type called @code{person} which contains three
3988 slots. Given a @code{person} object @var{p}, you can access those
3989 slots by calling @code{(person-name @var{p})}, @code{(person-age @var{p})},
3990 and @code{(person-sex @var{p})}. You can also change these slots by
3991 using @code{setf} on any of these place forms:
3994 (cl-incf (person-age birthday-boy))
3997 You can create a new @code{person} by calling @code{make-person},
3998 which takes keyword arguments @code{:name}, @code{:age}, and
3999 @code{:sex} to specify the initial values of these slots in the
4000 new object. (Omitting any of these arguments leaves the corresponding
4001 slot ``undefined'', according to the Common Lisp standard; in Emacs
4002 Lisp, such uninitialized slots are filled with @code{nil}.)
4004 Given a @code{person}, @code{(copy-person @var{p})} makes a new
4005 object of the same type whose slots are @code{eq} to those of @var{p}.
4007 Given any Lisp object @var{x}, @code{(person-p @var{x})} returns
4008 true if @var{x} looks like a @code{person}, false otherwise. (Again,
4009 in Common Lisp this predicate would be exact; in Emacs Lisp the
4010 best it can do is verify that @var{x} is a vector of the correct
4011 length which starts with the correct tag symbol.)
4013 Accessors like @code{person-name} normally check their arguments
4014 (effectively using @code{person-p}) and signal an error if the
4015 argument is the wrong type. This check is affected by
4016 @code{(optimize (safety @dots{}))} declarations. Safety level 1,
4017 the default, uses a somewhat optimized check that will detect all
4018 incorrect arguments, but may use an uninformative error message
4019 (e.g., ``expected a vector'' instead of ``expected a @code{person}'').
4020 Safety level 0 omits all checks except as provided by the underlying
4021 @code{aref} call; safety levels 2 and 3 do rigorous checking that will
4022 always print a descriptive error message for incorrect inputs.
4023 @xref{Declarations}.
4026 (setq dave (make-person :name "Dave" :sex 'male))
4027 @result{} [cl-struct-person "Dave" nil male]
4028 (setq other (copy-person dave))
4029 @result{} [cl-struct-person "Dave" nil male]
4032 (eq (person-name dave) (person-name other))
4036 (person-p [1 2 3 4])
4040 (person-p '[cl-struct-person counterfeit person object])
4044 In general, @var{name} is either a name symbol or a list of a name
4045 symbol followed by any number of @dfn{struct options}; each @var{slot}
4046 is either a slot symbol or a list of the form @samp{(@var{slot-name}
4047 @var{default-value} @var{slot-options}@dots{})}. The @var{default-value}
4048 is a Lisp form which is evaluated any time an instance of the
4049 structure type is created without specifying that slot's value.
4051 Common Lisp defines several slot options, but the only one
4052 implemented in this package is @code{:read-only}. A non-@code{nil}
4053 value for this option means the slot should not be @code{setf}-able;
4054 the slot's value is determined when the object is created and does
4055 not change afterward.
4058 (cl-defstruct person
4059 (name nil :read-only t)
4064 Any slot options other than @code{:read-only} are ignored.
4066 For obscure historical reasons, structure options take a different
4067 form than slot options. A structure option is either a keyword
4068 symbol, or a list beginning with a keyword symbol possibly followed
4069 by arguments. (By contrast, slot options are key-value pairs not
4073 (cl-defstruct (person (:constructor create-person)
4079 The following structure options are recognized.
4083 The argument is a symbol whose print name is used as the prefix for
4084 the names of slot accessor functions. The default is the name of
4085 the struct type followed by a hyphen. The option @code{(:conc-name p-)}
4086 would change this prefix to @code{p-}. Specifying @code{nil} as an
4087 argument means no prefix, so that the slot names themselves are used
4088 to name the accessor functions.
4091 In the simple case, this option takes one argument which is an
4092 alternate name to use for the constructor function. The default
4093 is @code{make-@var{name}}, e.g., @code{make-person}. The above
4094 example changes this to @code{create-person}. Specifying @code{nil}
4095 as an argument means that no standard constructor should be
4098 In the full form of this option, the constructor name is followed
4099 by an arbitrary argument list. @xref{Program Structure}, for a
4100 description of the format of Common Lisp argument lists. All
4101 options, such as @code{&rest} and @code{&key}, are supported.
4102 The argument names should match the slot names; each slot is
4103 initialized from the corresponding argument. Slots whose names
4104 do not appear in the argument list are initialized based on the
4105 @var{default-value} in their slot descriptor. Also, @code{&optional}
4106 and @code{&key} arguments which don't specify defaults take their
4107 defaults from the slot descriptor. It is valid to include arguments
4108 which don't correspond to slot names; these are useful if they are
4109 referred to in the defaults for optional, keyword, or @code{&aux}
4110 arguments which @emph{do} correspond to slots.
4112 You can specify any number of full-format @code{:constructor}
4113 options on a structure. The default constructor is still generated
4114 as well unless you disable it with a simple-format @code{:constructor}
4120 (:constructor nil) ; no default constructor
4121 (:constructor new-person
4122 (name sex &optional (age 0)))
4123 (:constructor new-hound (&key (name "Rover")
4125 &aux (age (* 7 dog-years))
4130 The first constructor here takes its arguments positionally rather
4131 than by keyword. (In official Common Lisp terminology, constructors
4132 that work By Order of Arguments instead of by keyword are called
4133 ``BOA constructors''. No, I'm not making this up.) For example,
4134 @code{(new-person "Jane" 'female)} generates a person whose slots
4135 are @code{"Jane"}, 0, and @code{female}, respectively.
4137 The second constructor takes two keyword arguments, @code{:name},
4138 which initializes the @code{name} slot and defaults to @code{"Rover"},
4139 and @code{:dog-years}, which does not itself correspond to a slot
4140 but which is used to initialize the @code{age} slot. The @code{sex}
4141 slot is forced to the symbol @code{canine} with no syntax for
4145 The argument is an alternate name for the copier function for
4146 this type. The default is @code{copy-@var{name}}. @code{nil}
4147 means not to generate a copier function. (In this implementation,
4148 all copier functions are simply synonyms for @code{copy-sequence}.)
4151 The argument is an alternate name for the predicate which recognizes
4152 objects of this type. The default is @code{@var{name}-p}. @code{nil}
4153 means not to generate a predicate function. (If the @code{:type}
4154 option is used without the @code{:named} option, no predicate is
4157 In true Common Lisp, @code{typep} is always able to recognize a
4158 structure object even if @code{:predicate} was used. In this
4159 package, @code{cl-typep} simply looks for a function called
4160 @code{@var{typename}-p}, so it will work for structure types
4161 only if they used the default predicate name.
4164 This option implements a very limited form of C++-style inheritance.
4165 The argument is the name of another structure type previously
4166 created with @code{cl-defstruct}. The effect is to cause the new
4167 structure type to inherit all of the included structure's slots
4168 (plus, of course, any new slots described by this struct's slot
4169 descriptors). The new structure is considered a ``specialization''
4170 of the included one. In fact, the predicate and slot accessors
4171 for the included type will also accept objects of the new type.
4173 If there are extra arguments to the @code{:include} option after
4174 the included-structure name, these options are treated as replacement
4175 slot descriptors for slots in the included structure, possibly with
4176 modified default values. Borrowing an example from Steele:
4179 (cl-defstruct person name (age 0) sex)
4181 (cl-defstruct (astronaut (:include person (age 45)))
4183 (favorite-beverage 'tang))
4186 (setq joe (make-person :name "Joe"))
4187 @result{} [cl-struct-person "Joe" 0 nil]
4188 (setq buzz (make-astronaut :name "Buzz"))
4189 @result{} [cl-struct-astronaut "Buzz" 45 nil nil tang]
4191 (list (person-p joe) (person-p buzz))
4193 (list (astronaut-p joe) (astronaut-p buzz))
4198 (astronaut-name joe)
4199 @result{} error: "astronaut-name accessing a non-astronaut"
4202 Thus, if @code{astronaut} is a specialization of @code{person},
4203 then every @code{astronaut} is also a @code{person} (but not the
4204 other way around). Every @code{astronaut} includes all the slots
4205 of a @code{person}, plus extra slots that are specific to
4206 astronauts. Operations that work on people (like @code{person-name})
4207 work on astronauts just like other people.
4209 @item :print-function
4210 In full Common Lisp, this option allows you to specify a function
4211 which is called to print an instance of the structure type. The
4212 Emacs Lisp system offers no hooks into the Lisp printer which would
4213 allow for such a feature, so this package simply ignores
4214 @code{:print-function}.
4217 The argument should be one of the symbols @code{vector} or @code{list}.
4218 This tells which underlying Lisp data type should be used to implement
4219 the new structure type. Vectors are used by default, but
4220 @code{(:type list)} will cause structure objects to be stored as
4223 The vector representation for structure objects has the advantage
4224 that all structure slots can be accessed quickly, although creating
4225 vectors is a bit slower in Emacs Lisp. Lists are easier to create,
4226 but take a relatively long time accessing the later slots.
4229 This option, which takes no arguments, causes a characteristic ``tag''
4230 symbol to be stored at the front of the structure object. Using
4231 @code{:type} without also using @code{:named} will result in a
4232 structure type stored as plain vectors or lists with no identifying
4235 The default, if you don't specify @code{:type} explicitly, is to
4236 use named vectors. Therefore, @code{:named} is only useful in
4237 conjunction with @code{:type}.
4240 (cl-defstruct (person1) name age sex)
4241 (cl-defstruct (person2 (:type list) :named) name age sex)
4242 (cl-defstruct (person3 (:type list)) name age sex)
4244 (setq p1 (make-person1))
4245 @result{} [cl-struct-person1 nil nil nil]
4246 (setq p2 (make-person2))
4247 @result{} (person2 nil nil nil)
4248 (setq p3 (make-person3))
4249 @result{} (nil nil nil)
4256 @result{} error: function person3-p undefined
4259 Since unnamed structures don't have tags, @code{cl-defstruct} is not
4260 able to make a useful predicate for recognizing them. Also,
4261 accessors like @code{person3-name} will be generated but they
4262 will not be able to do any type checking. The @code{person3-name}
4263 function, for example, will simply be a synonym for @code{car} in
4264 this case. By contrast, @code{person2-name} is able to verify
4265 that its argument is indeed a @code{person2} object before
4268 @item :initial-offset
4269 The argument must be a nonnegative integer. It specifies a
4270 number of slots to be left ``empty'' at the front of the
4271 structure. If the structure is named, the tag appears at the
4272 specified position in the list or vector; otherwise, the first
4273 slot appears at that position. Earlier positions are filled
4274 with @code{nil} by the constructors and ignored otherwise. If
4275 the type @code{:include}s another type, then @code{:initial-offset}
4276 specifies a number of slots to be skipped between the last slot
4277 of the included type and the first new slot.
4281 Except as noted, the @code{cl-defstruct} facility of this package is
4282 entirely compatible with that of Common Lisp.
4285 @chapter Assertions and Errors
4288 This section describes two macros that test @dfn{assertions}, i.e.,
4289 conditions which must be true if the program is operating correctly.
4290 Assertions never add to the behavior of a Lisp program; they simply
4291 make ``sanity checks'' to make sure everything is as it should be.
4293 If the optimization property @code{speed} has been set to 3, and
4294 @code{safety} is less than 3, then the byte-compiler will optimize
4295 away the following assertions. Because assertions might be optimized
4296 away, it is a bad idea for them to include side-effects.
4298 @defmac cl-assert test-form [show-args string args@dots{}]
4299 This form verifies that @var{test-form} is true (i.e., evaluates to
4300 a non-@code{nil} value). If so, it returns @code{nil}. If the test
4301 is not satisfied, @code{cl-assert} signals an error.
4303 A default error message will be supplied which includes @var{test-form}.
4304 You can specify a different error message by including a @var{string}
4305 argument plus optional extra arguments. Those arguments are simply
4306 passed to @code{error} to signal the error.
4308 If the optional second argument @var{show-args} is @code{t} instead
4309 of @code{nil}, then the error message (with or without @var{string})
4310 will also include all non-constant arguments of the top-level
4311 @var{form}. For example:
4314 (cl-assert (> x 10) t "x is too small: %d")
4317 This usage of @var{show-args} is an extension to Common Lisp. In
4318 true Common Lisp, the second argument gives a list of @var{places}
4319 which can be @code{setf}'d by the user before continuing from the
4320 error. Since Emacs Lisp does not support continuable errors, it
4321 makes no sense to specify @var{places}.
4324 @defmac cl-check-type form type [string]
4325 This form verifies that @var{form} evaluates to a value of type
4326 @var{type}. If so, it returns @code{nil}. If not, @code{cl-check-type}
4327 signals a @code{wrong-type-argument} error. The default error message
4328 lists the erroneous value along with @var{type} and @var{form}
4329 themselves. If @var{string} is specified, it is included in the
4330 error message in place of @var{type}. For example:
4333 (cl-check-type x (integer 1 *) "a positive integer")
4336 @xref{Type Predicates}, for a description of the type specifiers
4337 that may be used for @var{type}.
4339 Note that in Common Lisp, the first argument to @code{check-type}
4340 must be a @var{place} suitable for use by @code{setf}, because
4341 @code{check-type} signals a continuable error that allows the
4342 user to modify @var{place}.
4345 @node Efficiency Concerns
4346 @appendix Efficiency Concerns
4351 Many of the advanced features of this package, such as @code{cl-defun},
4352 @code{cl-loop}, etc., are implemented as Lisp macros. In
4353 byte-compiled code, these complex notations will be expanded into
4354 equivalent Lisp code which is simple and efficient. For example,
4362 is expanded at compile-time to the Lisp form
4369 which is the most efficient ways of doing this operation
4370 in Lisp. Thus, there is no performance penalty for using the more
4371 readable @code{cl-incf} form in your compiled code.
4373 @emph{Interpreted} code, on the other hand, must expand these macros
4374 every time they are executed. For this reason it is strongly
4375 recommended that code making heavy use of macros be compiled.
4376 A loop using @code{cl-incf} a hundred times will execute considerably
4377 faster if compiled, and will also garbage-collect less because the
4378 macro expansion will not have to be generated, used, and thrown away a
4381 You can find out how a macro expands by using the
4382 @code{cl-prettyexpand} function.
4384 @defun cl-prettyexpand form &optional full
4385 This function takes a single Lisp form as an argument and inserts
4386 a nicely formatted copy of it in the current buffer (which must be
4387 in Lisp mode so that indentation works properly). It also expands
4388 all Lisp macros which appear in the form. The easiest way to use
4389 this function is to go to the @file{*scratch*} buffer and type, say,
4392 (cl-prettyexpand '(cl-loop for x below 10 collect x))
4396 and type @kbd{C-x C-e} immediately after the closing parenthesis;
4404 (setq G1004 (cons x G1004))
4410 will be inserted into the buffer. (The @code{cl-block} macro is
4411 expanded differently in the interpreter and compiler, so
4412 @code{cl-prettyexpand} just leaves it alone. The temporary
4413 variable @code{G1004} was created by @code{cl-gensym}.)
4415 If the optional argument @var{full} is true, then @emph{all}
4416 macros are expanded, including @code{cl-block}, @code{cl-eval-when},
4417 and compiler macros. Expansion is done as if @var{form} were
4418 a top-level form in a file being compiled. For example,
4421 (cl-prettyexpand '(cl-pushnew 'x list))
4422 @print{} (setq list (cl-adjoin 'x list))
4423 (cl-prettyexpand '(cl-pushnew 'x list) t)
4424 @print{} (setq list (if (memq 'x list) list (cons 'x list)))
4425 (cl-prettyexpand '(caddr (cl-member 'a list)) t)
4426 @print{} (car (cdr (cdr (memq 'a list))))
4429 Note that @code{cl-adjoin}, @code{cl-caddr}, and @code{cl-member} all
4430 have built-in compiler macros to optimize them in common cases.
4438 @appendixsec Error Checking
4441 Common Lisp compliance has in general not been sacrificed for the
4442 sake of efficiency. A few exceptions have been made for cases
4443 where substantial gains were possible at the expense of marginal
4446 The Common Lisp standard (as embodied in Steele's book) uses the
4447 phrase ``it is an error if'' to indicate a situation which is not
4448 supposed to arise in complying programs; implementations are strongly
4449 encouraged but not required to signal an error in these situations.
4450 This package sometimes omits such error checking in the interest of
4451 compactness and efficiency. For example, @code{cl-do} variable
4452 specifiers are supposed to be lists of one, two, or three forms;
4453 extra forms are ignored by this package rather than signaling a
4454 syntax error. The @code{cl-endp} function is simply a synonym for
4455 @code{null} in this package. Functions taking keyword arguments
4456 will accept an odd number of arguments, treating the trailing
4457 keyword as if it were followed by the value @code{nil}.
4459 Argument lists (as processed by @code{cl-defun} and friends)
4460 @emph{are} checked rigorously except for the minor point just
4461 mentioned; in particular, keyword arguments are checked for
4462 validity, and @code{&allow-other-keys} and @code{:allow-other-keys}
4463 are fully implemented. Keyword validity checking is slightly
4464 time consuming (though not too bad in byte-compiled code);
4465 you can use @code{&allow-other-keys} to omit this check. Functions
4466 defined in this package such as @code{cl-find} and @code{cl-member}
4467 do check their keyword arguments for validity.
4474 @appendixsec Optimizing Compiler
4477 Use of the optimizing Emacs compiler is highly recommended; many of the Common
4479 code which can be improved by optimization. In particular,
4480 @code{cl-block}s (whether explicit or implicit in constructs like
4481 @code{cl-defun} and @code{cl-loop}) carry a fair run-time penalty; the
4482 optimizing compiler removes @code{cl-block}s which are not actually
4483 referenced by @code{cl-return} or @code{cl-return-from} inside the block.
4485 @node Common Lisp Compatibility
4486 @appendix Common Lisp Compatibility
4489 Following is a list of all known incompatibilities between this
4490 package and Common Lisp as documented in Steele (2nd edition).
4492 The word @code{cl-defun} is required instead of @code{defun} in order
4493 to use extended Common Lisp argument lists in a function. Likewise,
4494 @code{cl-defmacro} and @code{cl-function} are versions of those forms
4495 which understand full-featured argument lists. The @code{&whole}
4496 keyword does not work in @code{defmacro} argument lists (except
4497 inside recursive argument lists).
4499 The @code{equal} predicate does not distinguish
4500 between IEEE floating-point plus and minus zero. The @code{cl-equalp}
4501 predicate has several differences with Common Lisp; @pxref{Predicates}.
4503 @c FIXME no longer provided by cl.
4504 The @code{setf} mechanism is entirely compatible, except that
4505 setf-methods return a list of five values rather than five
4506 values directly. Also, the new ``@code{setf} function'' concept
4507 (typified by @code{(defun (setf foo) @dots{})}) is not implemented.
4509 The @code{cl-do-all-symbols} form is the same as @code{cl-do-symbols}
4510 with no @var{obarray} argument. In Common Lisp, this form would
4511 iterate over all symbols in all packages. Since Emacs obarrays
4512 are not a first-class package mechanism, there is no way for
4513 @code{cl-do-all-symbols} to locate any but the default obarray.
4515 The @code{cl-loop} macro is complete except that @code{loop-finish}
4516 and type specifiers are unimplemented.
4518 The multiple-value return facility treats lists as multiple
4519 values, since Emacs Lisp cannot support multiple return values
4520 directly. The macros will be compatible with Common Lisp if
4521 @code{cl-values} or @code{cl-values-list} is always used to return to
4522 a @code{cl-multiple-value-bind} or other multiple-value receiver;
4523 if @code{cl-values} is used without @code{cl-multiple-value-@dots{}}
4524 or vice-versa the effect will be different from Common Lisp.
4526 Many Common Lisp declarations are ignored, and others match
4527 the Common Lisp standard in concept but not in detail. For
4528 example, local @code{special} declarations, which are purely
4529 advisory in Emacs Lisp, do not rigorously obey the scoping rules
4530 set down in Steele's book.
4532 The variable @code{cl--gensym-counter} starts out with a pseudo-random
4533 value rather than with zero. This is to cope with the fact that
4534 generated symbols become interned when they are written to and
4535 loaded back from a file.
4537 The @code{cl-defstruct} facility is compatible, except that structures
4538 are of type @code{:type vector :named} by default rather than some
4539 special, distinct type. Also, the @code{:type} slot option is ignored.
4541 The second argument of @code{cl-check-type} is treated differently.
4543 @node Porting Common Lisp
4544 @appendix Porting Common Lisp
4547 This package is meant to be used as an extension to Emacs Lisp,
4548 not as an Emacs implementation of true Common Lisp. Some of the
4549 remaining differences between Emacs Lisp and Common Lisp make it
4550 difficult to port large Common Lisp applications to Emacs. For
4551 one, some of the features in this package are not fully compliant
4552 with ANSI or Steele; @pxref{Common Lisp Compatibility}. But there
4553 are also quite a few features that this package does not provide
4554 at all. Here are some major omissions that you will want to watch out
4555 for when bringing Common Lisp code into Emacs.
4559 Case-insensitivity. Symbols in Common Lisp are case-insensitive
4560 by default. Some programs refer to a function or variable as
4561 @code{foo} in one place and @code{Foo} or @code{FOO} in another.
4562 Emacs Lisp will treat these as three distinct symbols.
4564 Some Common Lisp code is written entirely in upper case. While Emacs
4565 is happy to let the program's own functions and variables use
4566 this convention, calls to Lisp builtins like @code{if} and
4567 @code{defun} will have to be changed to lower case.
4570 Lexical scoping. In Common Lisp, function arguments and @code{let}
4571 bindings apply only to references physically within their bodies (or
4572 within macro expansions in their bodies). Traditionally, Emacs Lisp
4573 uses @dfn{dynamic scoping} wherein a binding to a variable is visible
4574 even inside functions called from the body.
4575 @xref{Dynamic Binding,,,elisp,GNU Emacs Lisp Reference Manual}.
4576 Lexical binding is available since Emacs 24.1, so be sure to set
4577 @code{lexical-binding} to @code{t} if you need to emulate this aspect
4578 of Common Lisp. @xref{Lexical Binding,,,elisp,GNU Emacs Lisp Reference Manual}.
4580 Here is an example of a Common Lisp code fragment that would fail in
4581 Emacs Lisp if @code{lexical-binding} were set to @code{nil}:
4584 (defun map-odd-elements (func list)
4586 for flag = t then (not flag)
4587 collect (if flag x (funcall func x))))
4589 (defun add-odd-elements (list x)
4590 (map-odd-elements (lambda (a) (+ a x)) list))
4594 With lexical binding, the two functions' usages of @code{x} are
4595 completely independent. With dynamic binding, the binding to @code{x}
4596 made by @code{add-odd-elements} will have been hidden by the binding
4597 in @code{map-odd-elements} by the time the @code{(+ a x)} function is
4600 Internally, this package uses lexical binding so that such problems do
4601 not occur. @xref{Lexical Bindings}, for a description of the obsolete
4602 @code{lexical-let} form that emulates a Common Lisp-style lexical
4603 binding when dynamic binding is in use.
4606 Reader macros. Common Lisp includes a second type of macro that
4607 works at the level of individual characters. For example, Common
4608 Lisp implements the quote notation by a reader macro called @code{'},
4609 whereas Emacs Lisp's parser just treats quote as a special case.
4610 Some Lisp packages use reader macros to create special syntaxes
4611 for themselves, which the Emacs parser is incapable of reading.
4614 Other syntactic features. Common Lisp provides a number of
4615 notations beginning with @code{#} that the Emacs Lisp parser
4616 won't understand. For example, @samp{#| ... |#} is an
4617 alternate comment notation, and @samp{#+lucid (foo)} tells
4618 the parser to ignore the @code{(foo)} except in Lucid Common
4622 Packages. In Common Lisp, symbols are divided into @dfn{packages}.
4623 Symbols that are Lisp built-ins are typically stored in one package;
4624 symbols that are vendor extensions are put in another, and each
4625 application program would have a package for its own symbols.
4626 Certain symbols are ``exported'' by a package and others are
4627 internal; certain packages ``use'' or import the exported symbols
4628 of other packages. To access symbols that would not normally be
4629 visible due to this importing and exporting, Common Lisp provides
4630 a syntax like @code{package:symbol} or @code{package::symbol}.
4632 Emacs Lisp has a single namespace for all interned symbols, and
4633 then uses a naming convention of putting a prefix like @code{cl-}
4634 in front of the name. Some Emacs packages adopt the Common Lisp-like
4635 convention of using @code{cl:} or @code{cl::} as the prefix.
4636 However, the Emacs parser does not understand colons and just
4637 treats them as part of the symbol name. Thus, while @code{mapcar}
4638 and @code{lisp:mapcar} may refer to the same symbol in Common
4639 Lisp, they are totally distinct in Emacs Lisp. Common Lisp
4640 programs which refer to a symbol by the full name sometimes
4641 and the short name other times will not port cleanly to Emacs.
4643 Emacs Lisp does have a concept of ``obarrays'', which are
4644 package-like collections of symbols, but this feature is not
4645 strong enough to be used as a true package mechanism.
4648 The @code{format} function is quite different between Common
4649 Lisp and Emacs Lisp. It takes an additional ``destination''
4650 argument before the format string. A destination of @code{nil}
4651 means to format to a string as in Emacs Lisp; a destination
4652 of @code{t} means to write to the terminal (similar to
4653 @code{message} in Emacs). Also, format control strings are
4654 utterly different; @code{~} is used instead of @code{%} to
4655 introduce format codes, and the set of available codes is
4656 much richer. There are no notations like @code{\n} for
4657 string literals; instead, @code{format} is used with the
4658 ``newline'' format code, @code{~%}. More advanced formatting
4659 codes provide such features as paragraph filling, case
4660 conversion, and even loops and conditionals.
4662 While it would have been possible to implement most of Common
4663 Lisp @code{format} in this package (under the name @code{cl-format},
4664 of course), it was not deemed worthwhile. It would have required
4665 a huge amount of code to implement even a decent subset of
4666 @code{cl-format}, yet the functionality it would provide over
4667 Emacs Lisp's @code{format} would rarely be useful.
4670 Vector constants use square brackets in Emacs Lisp, but
4671 @code{#(a b c)} notation in Common Lisp. To further complicate
4672 matters, Emacs has its own @code{#(} notation for
4673 something entirely different---strings with properties.
4676 Characters are distinct from integers in Common Lisp. The notation
4677 for character constants is also different: @code{#\A} in Common Lisp
4678 where Emacs Lisp uses @code{?A}. Also, @code{string=} and
4679 @code{string-equal} are synonyms in Emacs Lisp, whereas the latter is
4680 case-insensitive in Common Lisp.
4683 Data types. Some Common Lisp data types do not exist in Emacs
4684 Lisp. Rational numbers and complex numbers are not present,
4685 nor are large integers (all integers are ``fixnums''). All
4686 arrays are one-dimensional. There are no readtables or pathnames;
4687 streams are a set of existing data types rather than a new data
4688 type of their own. Hash tables, random-states, structures, and
4689 packages (obarrays) are built from Lisp vectors or lists rather
4690 than being distinct types.
4693 The Common Lisp Object System (CLOS) is not implemented,
4694 nor is the Common Lisp Condition System. However, the EIEIO package
4695 (@pxref{Top, , Introduction, eieio, EIEIO}) does implement some
4699 Common Lisp features that are completely redundant with Emacs
4700 Lisp features of a different name generally have not been
4701 implemented. For example, Common Lisp writes @code{defconstant}
4702 where Emacs Lisp uses @code{defconst}. Similarly, @code{make-list}
4703 takes its arguments in different ways in the two Lisps but does
4704 exactly the same thing, so this package has not bothered to
4705 implement a Common Lisp-style @code{make-list}.
4708 A few more notable Common Lisp features not included in this
4709 package: @code{compiler-let}, @code{tagbody}, @code{prog},
4710 @code{ldb/dpb}, @code{parse-integer}, @code{cerror}.
4713 Recursion. While recursion works in Emacs Lisp just like it
4714 does in Common Lisp, various details of the Emacs Lisp system
4715 and compiler make recursion much less efficient than it is in
4716 most Lisps. Some schools of thought prefer to use recursion
4717 in Lisp over other techniques; they would sum a list of
4718 numbers using something like
4721 (defun sum-list (list)
4723 (+ (car list) (sum-list (cdr list)))
4728 where a more iteratively-minded programmer might write one of
4732 (let ((total 0)) (dolist (x my-list) (cl-incf total x)) total)
4733 (cl-loop for x in my-list sum x)
4736 While this would be mainly a stylistic choice in most Common Lisps,
4737 in Emacs Lisp you should be aware that the iterative forms are
4738 much faster than recursion. Also, Lisp programmers will want to
4739 note that the current Emacs Lisp compiler does not optimize tail
4743 @node Obsolete Features
4744 @appendix Obsolete Features
4746 This section describes some features of the package that are obsolete
4747 and should not be used in new code. They are either only provided by
4748 the old @file{cl.el} entry point, not by the newer @file{cl-lib.el};
4749 or where versions with a @samp{cl-} prefix do exist they do not behave
4750 in exactly the same way.
4753 * Lexical Bindings:: An approximation of lexical binding.
4754 * Obsolete Lexical Macros:: Obsolete macros using lexical-let.
4755 * Obsolete Setf Customization:: Obsolete ways to customize setf.
4758 @node Lexical Bindings
4759 @appendixsec Lexical Bindings
4761 The following macros are extensions to Common Lisp, where all bindings
4762 are lexical unless declared otherwise. These features are likewise
4763 obsolete since the introduction of true lexical binding in Emacs 24.1.
4765 @defmac lexical-let (bindings@dots{}) forms@dots{}
4766 This form is exactly like @code{let} except that the bindings it
4767 establishes are purely lexical.
4770 @c FIXME remove this and refer to elisp manual.
4771 @c Maybe merge some stuff from here to there?
4773 Lexical bindings are similar to local variables in a language like C:
4774 Only the code physically within the body of the @code{lexical-let}
4775 (after macro expansion) may refer to the bound variables.
4779 (defun foo (b) (+ a b))
4780 (let ((a 2)) (foo a))
4782 (lexical-let ((a 2)) (foo a))
4787 In this example, a regular @code{let} binding of @code{a} actually
4788 makes a temporary change to the global variable @code{a}, so @code{foo}
4789 is able to see the binding of @code{a} to 2. But @code{lexical-let}
4790 actually creates a distinct local variable @code{a} for use within its
4791 body, without any effect on the global variable of the same name.
4793 The most important use of lexical bindings is to create @dfn{closures}.
4794 A closure is a function object that refers to an outside lexical
4795 variable (@pxref{Closures,,,elisp,GNU Emacs Lisp Reference Manual}).
4799 (defun make-adder (n)
4800 (lexical-let ((n n))
4801 (function (lambda (m) (+ n m)))))
4802 (setq add17 (make-adder 17))
4808 The call @code{(make-adder 17)} returns a function object which adds
4809 17 to its argument. If @code{let} had been used instead of
4810 @code{lexical-let}, the function object would have referred to the
4811 global @code{n}, which would have been bound to 17 only during the
4812 call to @code{make-adder} itself.
4815 (defun make-counter ()
4816 (lexical-let ((n 0))
4817 (cl-function (lambda (&optional (m 1)) (cl-incf n m)))))
4818 (setq count-1 (make-counter))
4821 (funcall count-1 14)
4823 (setq count-2 (make-counter))
4833 Here we see that each call to @code{make-counter} creates a distinct
4834 local variable @code{n}, which serves as a private counter for the
4835 function object that is returned.
4837 Closed-over lexical variables persist until the last reference to
4838 them goes away, just like all other Lisp objects. For example,
4839 @code{count-2} refers to a function object which refers to an
4840 instance of the variable @code{n}; this is the only reference
4841 to that variable, so after @code{(setq count-2 nil)} the garbage
4842 collector would be able to delete this instance of @code{n}.
4843 Of course, if a @code{lexical-let} does not actually create any
4844 closures, then the lexical variables are free as soon as the
4845 @code{lexical-let} returns.
4847 Many closures are used only during the extent of the bindings they
4848 refer to; these are known as ``downward funargs'' in Lisp parlance.
4849 When a closure is used in this way, regular Emacs Lisp dynamic
4850 bindings suffice and will be more efficient than @code{lexical-let}
4854 (defun add-to-list (x list)
4855 (mapcar (lambda (y) (+ x y))) list)
4856 (add-to-list 7 '(1 2 5))
4861 Since this lambda is only used while @code{x} is still bound,
4862 it is not necessary to make a true closure out of it.
4864 You can use @code{defun} or @code{flet} inside a @code{lexical-let}
4865 to create a named closure. If several closures are created in the
4866 body of a single @code{lexical-let}, they all close over the same
4867 instance of the lexical variable.
4869 @defmac lexical-let* (bindings@dots{}) forms@dots{}
4870 This form is just like @code{lexical-let}, except that the bindings
4871 are made sequentially in the manner of @code{let*}.
4874 @node Obsolete Lexical Macros
4875 @appendixsec Macros Defined Using Lexical-Let
4877 The following macros are defined using @code{lexical-let}.
4878 They are replaced by versions with a @samp{cl-} prefix that use true
4879 lexical binding (and hence rely on @code{lexical-binding} being set to
4880 @code{t} in code using them).
4882 @defmac flet (bindings@dots{}) forms@dots{}
4883 Replaced by @code{cl-flet} (@pxref{Function Bindings})
4884 or @code{cl-letf} (@pxref{Modify Macros}).
4887 @defmac labels (bindings@dots{}) forms@dots{}
4888 Replaced by @code{cl-labels} (@pxref{Function Bindings}).
4891 @defmac letf (bindings@dots{}) forms@dots{}
4892 This macro is almost exactly the same as @code{cl-letf}, which
4893 replaces it (@pxref{Modify Macros}). The only difference is in
4894 details that relate to some deprecated usage of @code{symbol-function}
4898 @node Obsolete Setf Customization
4899 @appendixsec Obsolete Ways to Customize Setf
4901 Common Lisp defines three macros, @code{define-modify-macro},
4902 @code{defsetf}, and @code{define-setf-method}, that allow the
4903 user to extend generalized variables in various ways.
4904 In Emacs, these are obsolete, replaced by various features of
4905 @file{gv.el} in Emacs 24.3.
4908 @defmac define-modify-macro name arglist function [doc-string]
4909 This macro defines a ``read-modify-write'' macro similar to
4910 @code{cl-incf} and @code{cl-decf}. The macro @var{name} is defined
4911 to take a @var{place} argument followed by additional arguments
4912 described by @var{arglist}. The call
4915 (@var{name} @var{place} @var{args}...)
4922 (cl-callf @var{func} @var{place} @var{args}...)
4926 which in turn is roughly equivalent to
4929 (setf @var{place} (@var{func} @var{place} @var{args}...))
4935 (define-modify-macro cl-incf (&optional (n 1)) +)
4936 (define-modify-macro cl-concatf (&rest args) concat)
4939 Note that @code{&key} is not allowed in @var{arglist}, but
4940 @code{&rest} is sufficient to pass keywords on to the function.
4942 Most of the modify macros defined by Common Lisp do not exactly
4943 follow the pattern of @code{define-modify-macro}. For example,
4944 @code{push} takes its arguments in the wrong order, and @code{pop}
4945 is completely irregular. You can define these macros ``by hand''
4946 using @code{get-setf-method}, or consult the source
4947 to see how to use the internal @code{setf} building blocks.
4950 @defmac defsetf access-fn update-fn
4951 This is the simpler of two @code{defsetf} forms. Where
4952 @var{access-fn} is the name of a function which accesses a place,
4953 this declares @var{update-fn} to be the corresponding store
4954 function. From now on,
4957 (setf (@var{access-fn} @var{arg1} @var{arg2} @var{arg3}) @var{value})
4964 (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} @var{value})
4968 The @var{update-fn} is required to be either a true function, or
4969 a macro which evaluates its arguments in a function-like way. Also,
4970 the @var{update-fn} is expected to return @var{value} as its result.
4971 Otherwise, the above expansion would not obey the rules for the way
4972 @code{setf} is supposed to behave.
4974 As a special (non-Common-Lisp) extension, a third argument of @code{t}
4975 to @code{defsetf} says that the @code{update-fn}'s return value is
4976 not suitable, so that the above @code{setf} should be expanded to
4980 (let ((temp @var{value}))
4981 (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} temp)
4985 Some examples of the use of @code{defsetf}, drawn from the standard
4986 suite of setf methods, are:
4989 (defsetf car setcar)
4990 (defsetf symbol-value set)
4991 (defsetf buffer-name rename-buffer t)
4995 @defmac defsetf access-fn arglist (store-var) forms@dots{}
4996 This is the second, more complex, form of @code{defsetf}. It is
4997 rather like @code{defmacro} except for the additional @var{store-var}
4998 argument. The @var{forms} should return a Lisp form which stores
4999 the value of @var{store-var} into the generalized variable formed
5000 by a call to @var{access-fn} with arguments described by @var{arglist}.
5001 The @var{forms} may begin with a string which documents the @code{setf}
5002 method (analogous to the doc string that appears at the front of a
5005 For example, the simple form of @code{defsetf} is shorthand for
5008 (defsetf @var{access-fn} (&rest args) (store)
5009 (append '(@var{update-fn}) args (list store)))
5012 The Lisp form that is returned can access the arguments from
5013 @var{arglist} and @var{store-var} in an unrestricted fashion;
5014 macros like @code{setf} and @code{cl-incf} which invoke this
5015 setf-method will insert temporary variables as needed to make
5016 sure the apparent order of evaluation is preserved.
5018 Another example drawn from the standard package:
5021 (defsetf nth (n x) (store)
5022 (list 'setcar (list 'nthcdr n x) store))
5026 @defmac define-setf-method access-fn arglist forms@dots{}
5027 This is the most general way to create new place forms. When
5028 a @code{setf} to @var{access-fn} with arguments described by
5029 @var{arglist} is expanded, the @var{forms} are evaluated and
5030 must return a list of five items:
5034 A list of @dfn{temporary variables}.
5037 A list of @dfn{value forms} corresponding to the temporary variables
5038 above. The temporary variables will be bound to these value forms
5039 as the first step of any operation on the generalized variable.
5042 A list of exactly one @dfn{store variable} (generally obtained
5043 from a call to @code{gensym}).
5046 A Lisp form which stores the contents of the store variable into
5047 the generalized variable, assuming the temporaries have been
5048 bound as described above.
5051 A Lisp form which accesses the contents of the generalized variable,
5052 assuming the temporaries have been bound.
5055 This is exactly like the Common Lisp macro of the same name,
5056 except that the method returns a list of five values rather
5057 than the five values themselves, since Emacs Lisp does not
5058 support Common Lisp's notion of multiple return values.
5060 Once again, the @var{forms} may begin with a documentation string.
5062 A setf-method should be maximally conservative with regard to
5063 temporary variables. In the setf-methods generated by
5064 @code{defsetf}, the second return value is simply the list of
5065 arguments in the place form, and the first return value is a
5066 list of a corresponding number of temporary variables generated
5067 by @code{cl-gensym}. Macros like @code{setf} and @code{cl-incf} which
5068 use this setf-method will optimize away most temporaries that
5069 turn out to be unnecessary, so there is little reason for the
5070 setf-method itself to optimize.
5073 @defun get-setf-method place &optional env
5074 This function returns the setf-method for @var{place}, by
5075 invoking the definition previously recorded by @code{defsetf}
5076 or @code{define-setf-method}. The result is a list of five
5077 values as described above. You can use this function to build
5078 your own @code{cl-incf}-like modify macros. (Actually, it is
5080 better to use the internal functions @code{cl-setf-do-modify}
5081 and @code{cl-setf-do-store}, which are a bit easier to use and
5082 which also do a number of optimizations; consult the source
5083 code for the @code{cl-incf} function for a simple example.)
5085 The argument @var{env} specifies the ``environment'' to be
5086 passed on to @code{macroexpand} if @code{get-setf-method} should
5087 need to expand a macro in @var{place}. It should come from
5088 an @code{&environment} argument to the macro or setf-method
5089 that called @code{get-setf-method}.
5091 See also the source code for the setf-method for
5092 @c Also @code{apply}, but that is commented out.
5093 @code{substring}, which works by calling @code{get-setf-method} on a
5094 simpler case, then massaging the result.
5097 Modern Common Lisp defines a second, independent way to specify
5098 the @code{setf} behavior of a function, namely ``@code{setf}
5099 functions'' whose names are lists @code{(setf @var{name})}
5100 rather than symbols. For example, @code{(defun (setf foo) @dots{})}
5101 defines the function that is used when @code{setf} is applied to
5102 @code{foo}. This package does not currently support @code{setf}
5103 functions. In particular, it is a compile-time error to use
5104 @code{setf} on a form which has not already been @code{defsetf}'d
5105 or otherwise declared; in newer Common Lisps, this would not be
5106 an error since the function @code{(setf @var{func})} might be
5110 @node GNU Free Documentation License
5111 @appendix GNU Free Documentation License
5112 @include doclicense.texi
5114 @node Function Index
5115 @unnumbered Function Index
5119 @node Variable Index
5120 @unnumbered Variable Index