1 \input texinfo @c -*-texinfo-*-
2 @setfilename ../../info/cl
3 @settitle Common Lisp Extensions
6 This file documents the GNU Emacs Common Lisp emulation package.
8 Copyright @copyright{} 1993, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
9 2008, 2009 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.''
27 * CL: (cl). Partial Common Lisp support for Emacs Lisp.
34 @center @titlefont{Common Lisp Extensions}
36 @center For GNU Emacs Lisp
40 @center Dave Gillespie
41 @center daveg@@synaptics.com
43 @vskip 0pt plus 1filll
47 @node Top, Overview, (dir), (dir)
51 This document describes a set of Emacs Lisp facilities borrowed from
52 Common Lisp. All the facilities are described here in detail. While
53 this document does not assume any prior knowledge of Common Lisp, it
54 does assume a basic familiarity with Emacs Lisp.
57 * Overview:: Installation, usage, etc.
58 * Program Structure:: Arglists, `eval-when', `defalias'
59 * Predicates:: `typep' and `equalp'
60 * Control Structure:: `setf', `do', `loop', etc.
61 * Macros:: Destructuring, `define-compiler-macro'
62 * Declarations:: `proclaim', `declare', etc.
63 * Symbols:: Property lists, `gensym'
64 * Numbers:: Predicates, functions, random numbers
65 * Sequences:: Mapping, functions, searching, sorting
66 * Lists:: `caddr', `sublis', `member*', `assoc*', etc.
67 * Structures:: `defstruct'
68 * Assertions:: `check-type', `assert', `ignore-errors'.
70 * Efficiency Concerns:: Hints and techniques
71 * Common Lisp Compatibility:: All known differences with Steele
72 * Old CL Compatibility:: All known differences with old cl.el
73 * Porting Common Lisp:: Hints for porting Common Lisp code
75 * GNU Free Documentation License:: The license for this documentation.
80 @node Overview, Program Structure, Top, Top
86 Common Lisp is a huge language, and Common Lisp systems tend to be
87 massive and extremely complex. Emacs Lisp, by contrast, is rather
88 minimalist in the choice of Lisp features it offers the programmer.
89 As Emacs Lisp programmers have grown in number, and the applications
90 they write have grown more ambitious, it has become clear that Emacs
91 Lisp could benefit from many of the conveniences of Common Lisp.
93 The @dfn{CL} package adds a number of Common Lisp functions and
94 control structures to Emacs Lisp. While not a 100% complete
95 implementation of Common Lisp, @dfn{CL} adds enough functionality
96 to make Emacs Lisp programming significantly more convenient.
98 @strong{Please note:} the @dfn{CL} functions are not standard parts of
99 the Emacs Lisp name space, so it is legitimate for users to define
100 them with other, conflicting meanings. To avoid conflicting with
101 those user activities, we have a policy that packages installed in
102 Emacs must not load @dfn{CL} at run time. (It is ok for them to load
103 @dfn{CL} at compile time only, with @code{eval-when-compile}, and use
104 the macros it provides.) If you are writing packages that you plan to
105 distribute and invite widespread use for, you might want to observe
108 Some Common Lisp features have been omitted from this package
113 Some features are too complex or bulky relative to their benefit
114 to Emacs Lisp programmers. CLOS and Common Lisp streams are fine
115 examples of this group.
118 Other features cannot be implemented without modification to the
119 Emacs Lisp interpreter itself, such as multiple return values,
120 lexical scoping, case-insensitive symbols, and complex numbers.
121 The @dfn{CL} package generally makes no attempt to emulate these
125 Some features conflict with existing things in Emacs Lisp. For
126 example, Emacs' @code{assoc} function is incompatible with the
127 Common Lisp @code{assoc}. In such cases, this package usually
128 adds the suffix @samp{*} to the function name of the Common
129 Lisp version of the function (e.g., @code{assoc*}).
132 The package described here was written by Dave Gillespie,
133 @file{daveg@@synaptics.com}. It is a total rewrite of the original
134 1986 @file{cl.el} package by Cesar Quiroz. Most features of the
135 Quiroz package have been retained; any incompatibilities are
136 noted in the descriptions below. Care has been taken in this
137 version to ensure that each function is defined efficiently,
138 concisely, and with minimal impact on the rest of the Emacs
142 * Usage:: How to use the CL package
143 * Organization:: The package's five component files
144 * Installation:: Compiling and installing CL
145 * Naming Conventions:: Notes on CL function names
148 @node Usage, Organization, Overview, Overview
152 Lisp code that uses features from the @dfn{CL} package should
153 include at the beginning:
160 If you want to ensure that the new (Gillespie) version of @dfn{CL}
161 is the one that is present, add an additional @code{(require 'cl-19)}
170 The second call will fail (with ``@file{cl-19.el} not found'') if
171 the old @file{cl.el} package was in use.
173 It is safe to arrange to load @dfn{CL} at all times, e.g.,
174 in your @file{.emacs} file. But it's a good idea, for portability,
175 to @code{(require 'cl)} in your code even if you do this.
177 @node Organization, Installation, Usage, Overview
178 @section Organization
181 The Common Lisp package is organized into four files:
185 This is the ``main'' file, which contains basic functions
186 and information about the package. This file is relatively
187 compact---about 700 lines.
190 This file contains the larger, more complex or unusual functions.
191 It is kept separate so that packages which only want to use Common
192 Lisp fundamentals like the @code{cadr} function won't need to pay
193 the overhead of loading the more advanced functions.
196 This file contains most of the advanced functions for operating
197 on sequences or lists, such as @code{delete-if} and @code{assoc*}.
200 This file contains the features of the packages which are macros
201 instead of functions. Macros expand when the caller is compiled,
202 not when it is run, so the macros generally only need to be
203 present when the byte-compiler is running (or when the macros are
204 used in uncompiled code such as a @file{.emacs} file). Most of
205 the macros of this package are isolated in @file{cl-macs.el} so
206 that they won't take up memory unless you are compiling.
209 The file @file{cl.el} includes all necessary @code{autoload}
210 commands for the functions and macros in the other three files.
211 All you have to do is @code{(require 'cl)}, and @file{cl.el}
212 will take care of pulling in the other files when they are
215 There is another file, @file{cl-compat.el}, which defines some
216 routines from the older @file{cl.el} package that are no longer
217 present in the new package. This includes internal routines
218 like @code{setelt} and @code{zip-lists}, deprecated features
219 like @code{defkeyword}, and an emulation of the old-style
220 multiple-values feature. @xref{Old CL Compatibility}.
222 @node Installation, Naming Conventions, Organization, Overview
223 @section Installation
226 Installation of the @dfn{CL} package is simple: Just put the
227 byte-compiled files @file{cl.elc}, @file{cl-extra.elc},
228 @file{cl-seq.elc}, @file{cl-macs.elc}, and @file{cl-compat.elc}
229 into a directory on your @code{load-path}.
231 There are no special requirements to compile this package:
232 The files do not have to be loaded before they are compiled,
233 nor do they need to be compiled in any particular order.
235 You may choose to put the files into your main @file{lisp/}
236 directory, replacing the original @file{cl.el} file there. Or,
237 you could put them into a directory that comes before @file{lisp/}
238 on your @code{load-path} so that the old @file{cl.el} is
241 Also, format the @file{cl.texinfo} file and put the resulting
242 Info files in the @file{info/} directory or another suitable place.
244 You may instead wish to leave this package's components all in
245 their own directory, and then add this directory to your
246 @code{load-path} and @code{Info-directory-list}.
247 Add the directory to the front of the list so the old @dfn{CL}
248 package and its documentation are hidden.
250 @node Naming Conventions, , Installation, Overview
251 @section Naming Conventions
254 Except where noted, all functions defined by this package have the
255 same names and calling conventions as their Common Lisp counterparts.
257 Following is a complete list of functions whose names were changed
258 from Common Lisp, usually to avoid conflicts with Emacs. In each
259 case, a @samp{*} has been appended to the Common Lisp name to obtain
263 defun* defsubst* defmacro* function*
264 member* assoc* rassoc* get*
265 remove* delete* mapcar* sort*
266 floor* ceiling* truncate* round*
270 Internal function and variable names in the package are prefixed
271 by @code{cl-}. Here is a complete list of functions @emph{not}
272 prefixed by @code{cl-} which were not taken from Common Lisp:
275 floatp-safe lexical-let lexical-let*
276 callf callf2 letf letf*
280 The following simple functions and macros are defined in @file{cl.el};
281 they do not cause other components like @file{cl-extra} to be loaded.
285 evenp oddp plusp minusp
287 list* ldiff rest first .. tenth
288 copy-list subst mapcar* [2]
289 adjoin [3] acons pairlis pop [4]
290 push [4] pushnew [3,4] incf [4] decf [4]
295 [2] Only for one sequence argument or two list arguments.
298 [3] Only if @code{:test} is @code{eq}, @code{equal}, or unspecified,
299 and @code{:key} is not used.
302 [4] Only when @var{place} is a plain variable name.
308 @node Program Structure, Predicates, Overview, Top
309 @chapter Program Structure
312 This section describes features of the @dfn{CL} package which have to
313 do with programs as a whole: advanced argument lists for functions,
314 and the @code{eval-when} construct.
317 * Argument Lists:: `&key', `&aux', `defun*', `defmacro*'.
318 * Time of Evaluation:: The `eval-when' construct.
325 @node Argument Lists, Time of Evaluation, Program Structure, Program Structure
326 @section Argument Lists
329 Emacs Lisp's notation for argument lists of functions is a subset of
330 the Common Lisp notation. As well as the familiar @code{&optional}
331 and @code{&rest} markers, Common Lisp allows you to specify default
332 values for optional arguments, and it provides the additional markers
333 @code{&key} and @code{&aux}.
335 Since argument parsing is built-in to Emacs, there is no way for
336 this package to implement Common Lisp argument lists seamlessly.
337 Instead, this package defines alternates for several Lisp forms
338 which you must use if you need Common Lisp argument lists.
340 @defspec defun* name arglist body...
341 This form is identical to the regular @code{defun} form, except
342 that @var{arglist} is allowed to be a full Common Lisp argument
343 list. Also, the function body is enclosed in an implicit block
344 called @var{name}; @pxref{Blocks and Exits}.
347 @defspec defsubst* name arglist body...
348 This is just like @code{defun*}, except that the function that
349 is defined is automatically proclaimed @code{inline}, i.e.,
350 calls to it may be expanded into in-line code by the byte compiler.
351 This is analogous to the @code{defsubst} form;
352 @code{defsubst*} uses a different method (compiler macros) which
353 works in all version of Emacs, and also generates somewhat more
354 efficient inline expansions. In particular, @code{defsubst*}
355 arranges for the processing of keyword arguments, default values,
356 etc., to be done at compile-time whenever possible.
359 @defspec defmacro* name arglist body...
360 This is identical to the regular @code{defmacro} form,
361 except that @var{arglist} is allowed to be a full Common Lisp
362 argument list. The @code{&environment} keyword is supported as
363 described in Steele. The @code{&whole} keyword is supported only
364 within destructured lists (see below); top-level @code{&whole}
365 cannot be implemented with the current Emacs Lisp interpreter.
366 The macro expander body is enclosed in an implicit block called
370 @defspec function* symbol-or-lambda
371 This is identical to the regular @code{function} form,
372 except that if the argument is a @code{lambda} form then that
373 form may use a full Common Lisp argument list.
376 Also, all forms (such as @code{defsetf} and @code{flet}) defined
377 in this package that include @var{arglist}s in their syntax allow
378 full Common Lisp argument lists.
380 Note that it is @emph{not} necessary to use @code{defun*} in
381 order to have access to most @dfn{CL} features in your function.
382 These features are always present; @code{defun*}'s only
383 difference from @code{defun} is its more flexible argument
384 lists and its implicit block.
386 The full form of a Common Lisp argument list is
390 &optional (@var{var} @var{initform} @var{svar})...
392 &key ((@var{keyword} @var{var}) @var{initform} @var{svar})...
393 &aux (@var{var} @var{initform})...)
396 Each of the five argument list sections is optional. The @var{svar},
397 @var{initform}, and @var{keyword} parts are optional; if they are
398 omitted, then @samp{(@var{var})} may be written simply @samp{@var{var}}.
400 The first section consists of zero or more @dfn{required} arguments.
401 These arguments must always be specified in a call to the function;
402 there is no difference between Emacs Lisp and Common Lisp as far as
403 required arguments are concerned.
405 The second section consists of @dfn{optional} arguments. These
406 arguments may be specified in the function call; if they are not,
407 @var{initform} specifies the default value used for the argument.
408 (No @var{initform} means to use @code{nil} as the default.) The
409 @var{initform} is evaluated with the bindings for the preceding
410 arguments already established; @code{(a &optional (b (1+ a)))}
411 matches one or two arguments, with the second argument defaulting
412 to one plus the first argument. If the @var{svar} is specified,
413 it is an auxiliary variable which is bound to @code{t} if the optional
414 argument was specified, or to @code{nil} if the argument was omitted.
415 If you don't use an @var{svar}, then there will be no way for your
416 function to tell whether it was called with no argument, or with
417 the default value passed explicitly as an argument.
419 The third section consists of a single @dfn{rest} argument. If
420 more arguments were passed to the function than are accounted for
421 by the required and optional arguments, those extra arguments are
422 collected into a list and bound to the ``rest'' argument variable.
423 Common Lisp's @code{&rest} is equivalent to that of Emacs Lisp.
424 Common Lisp accepts @code{&body} as a synonym for @code{&rest} in
425 macro contexts; this package accepts it all the time.
427 The fourth section consists of @dfn{keyword} arguments. These
428 are optional arguments which are specified by name rather than
429 positionally in the argument list. For example,
432 (defun* foo (a &optional b &key c d (e 17)))
436 defines a function which may be called with one, two, or more
437 arguments. The first two arguments are bound to @code{a} and
438 @code{b} in the usual way. The remaining arguments must be
439 pairs of the form @code{:c}, @code{:d}, or @code{:e} followed
440 by the value to be bound to the corresponding argument variable.
441 (Symbols whose names begin with a colon are called @dfn{keywords},
442 and they are self-quoting in the same way as @code{nil} and
445 For example, the call @code{(foo 1 2 :d 3 :c 4)} sets the five
446 arguments to 1, 2, 4, 3, and 17, respectively. If the same keyword
447 appears more than once in the function call, the first occurrence
448 takes precedence over the later ones. Note that it is not possible
449 to specify keyword arguments without specifying the optional
450 argument @code{b} as well, since @code{(foo 1 :c 2)} would bind
451 @code{b} to the keyword @code{:c}, then signal an error because
452 @code{2} is not a valid keyword.
454 If a @var{keyword} symbol is explicitly specified in the argument
455 list as shown in the above diagram, then that keyword will be
456 used instead of just the variable name prefixed with a colon.
457 You can specify a @var{keyword} symbol which does not begin with
458 a colon at all, but such symbols will not be self-quoting; you
459 will have to quote them explicitly with an apostrophe in the
462 Ordinarily it is an error to pass an unrecognized keyword to
463 a function, e.g., @code{(foo 1 2 :c 3 :goober 4)}. You can ask
464 Lisp to ignore unrecognized keywords, either by adding the
465 marker @code{&allow-other-keys} after the keyword section
466 of the argument list, or by specifying an @code{:allow-other-keys}
467 argument in the call whose value is non-@code{nil}. If the
468 function uses both @code{&rest} and @code{&key} at the same time,
469 the ``rest'' argument is bound to the keyword list as it appears
470 in the call. For example:
473 (defun* find-thing (thing &rest rest &key need &allow-other-keys)
474 (or (apply 'member* thing thing-list :allow-other-keys t rest)
475 (if need (error "Thing not found"))))
479 This function takes a @code{:need} keyword argument, but also
480 accepts other keyword arguments which are passed on to the
481 @code{member*} function. @code{allow-other-keys} is used to
482 keep both @code{find-thing} and @code{member*} from complaining
483 about each others' keywords in the arguments.
485 The fifth section of the argument list consists of @dfn{auxiliary
486 variables}. These are not really arguments at all, but simply
487 variables which are bound to @code{nil} or to the specified
488 @var{initforms} during execution of the function. There is no
489 difference between the following two functions, except for a
490 matter of stylistic taste:
493 (defun* foo (a b &aux (c (+ a b)) d)
501 Argument lists support @dfn{destructuring}. In Common Lisp,
502 destructuring is only allowed with @code{defmacro}; this package
503 allows it with @code{defun*} and other argument lists as well.
504 In destructuring, any argument variable (@var{var} in the above
505 diagram) can be replaced by a list of variables, or more generally,
506 a recursive argument list. The corresponding argument value must
507 be a list whose elements match this recursive argument list.
511 (defmacro* dolist ((var listform &optional resultform)
516 This says that the first argument of @code{dolist} must be a list
517 of two or three items; if there are other arguments as well as this
518 list, they are stored in @code{body}. All features allowed in
519 regular argument lists are allowed in these recursive argument lists.
520 In addition, the clause @samp{&whole @var{var}} is allowed at the
521 front of a recursive argument list. It binds @var{var} to the
522 whole list being matched; thus @code{(&whole all a b)} matches
523 a list of two things, with @code{a} bound to the first thing,
524 @code{b} bound to the second thing, and @code{all} bound to the
525 list itself. (Common Lisp allows @code{&whole} in top-level
526 @code{defmacro} argument lists as well, but Emacs Lisp does not
529 One last feature of destructuring is that the argument list may be
530 dotted, so that the argument list @code{(a b . c)} is functionally
531 equivalent to @code{(a b &rest c)}.
533 If the optimization quality @code{safety} is set to 0
534 (@pxref{Declarations}), error checking for wrong number of
535 arguments and invalid keyword arguments is disabled. By default,
536 argument lists are rigorously checked.
538 @node Time of Evaluation, , Argument Lists, Program Structure
539 @section Time of Evaluation
542 Normally, the byte-compiler does not actually execute the forms in
543 a file it compiles. For example, if a file contains @code{(setq foo t)},
544 the act of compiling it will not actually set @code{foo} to @code{t}.
545 This is true even if the @code{setq} was a top-level form (i.e., not
546 enclosed in a @code{defun} or other form). Sometimes, though, you
547 would like to have certain top-level forms evaluated at compile-time.
548 For example, the compiler effectively evaluates @code{defmacro} forms
549 at compile-time so that later parts of the file can refer to the
550 macros that are defined.
552 @defspec eval-when (situations...) forms...
553 This form controls when the body @var{forms} are evaluated.
554 The @var{situations} list may contain any set of the symbols
555 @code{compile}, @code{load}, and @code{eval} (or their long-winded
556 ANSI equivalents, @code{:compile-toplevel}, @code{:load-toplevel},
557 and @code{:execute}).
559 The @code{eval-when} form is handled differently depending on
560 whether or not it is being compiled as a top-level form.
561 Specifically, it gets special treatment if it is being compiled
562 by a command such as @code{byte-compile-file} which compiles files
563 or buffers of code, and it appears either literally at the
564 top level of the file or inside a top-level @code{progn}.
566 For compiled top-level @code{eval-when}s, the body @var{forms} are
567 executed at compile-time if @code{compile} is in the @var{situations}
568 list, and the @var{forms} are written out to the file (to be executed
569 at load-time) if @code{load} is in the @var{situations} list.
571 For non-compiled-top-level forms, only the @code{eval} situation is
572 relevant. (This includes forms executed by the interpreter, forms
573 compiled with @code{byte-compile} rather than @code{byte-compile-file},
574 and non-top-level forms.) The @code{eval-when} acts like a
575 @code{progn} if @code{eval} is specified, and like @code{nil}
576 (ignoring the body @var{forms}) if not.
578 The rules become more subtle when @code{eval-when}s are nested;
579 consult Steele (second edition) for the gruesome details (and
580 some gruesome examples).
582 Some simple examples:
585 ;; Top-level forms in foo.el:
586 (eval-when (compile) (setq foo1 'bar))
587 (eval-when (load) (setq foo2 'bar))
588 (eval-when (compile load) (setq foo3 'bar))
589 (eval-when (eval) (setq foo4 'bar))
590 (eval-when (eval compile) (setq foo5 'bar))
591 (eval-when (eval load) (setq foo6 'bar))
592 (eval-when (eval compile load) (setq foo7 'bar))
595 When @file{foo.el} is compiled, these variables will be set during
596 the compilation itself:
599 foo1 foo3 foo5 foo7 ; `compile'
602 When @file{foo.elc} is loaded, these variables will be set:
605 foo2 foo3 foo6 foo7 ; `load'
608 And if @file{foo.el} is loaded uncompiled, these variables will
612 foo4 foo5 foo6 foo7 ; `eval'
615 If these seven @code{eval-when}s had been, say, inside a @code{defun},
616 then the first three would have been equivalent to @code{nil} and the
617 last four would have been equivalent to the corresponding @code{setq}s.
619 Note that @code{(eval-when (load eval) @dots{})} is equivalent
620 to @code{(progn @dots{})} in all contexts. The compiler treats
621 certain top-level forms, like @code{defmacro} (sort-of) and
622 @code{require}, as if they were wrapped in @code{(eval-when
623 (compile load eval) @dots{})}.
626 Emacs includes two special forms related to @code{eval-when}.
627 One of these, @code{eval-when-compile}, is not quite equivalent to
628 any @code{eval-when} construct and is described below.
630 The other form, @code{(eval-and-compile @dots{})}, is exactly
631 equivalent to @samp{(eval-when (compile load eval) @dots{})} and
632 so is not itself defined by this package.
634 @defspec eval-when-compile forms...
635 The @var{forms} are evaluated at compile-time; at execution time,
636 this form acts like a quoted constant of the resulting value. Used
637 at top-level, @code{eval-when-compile} is just like @samp{eval-when
638 (compile eval)}. In other contexts, @code{eval-when-compile}
639 allows code to be evaluated once at compile-time for efficiency
642 This form is similar to the @samp{#.} syntax of true Common Lisp.
645 @defspec load-time-value form
646 The @var{form} is evaluated at load-time; at execution time,
647 this form acts like a quoted constant of the resulting value.
649 Early Common Lisp had a @samp{#,} syntax that was similar to
650 this, but ANSI Common Lisp replaced it with @code{load-time-value}
651 and gave it more well-defined semantics.
653 In a compiled file, @code{load-time-value} arranges for @var{form}
654 to be evaluated when the @file{.elc} file is loaded and then used
655 as if it were a quoted constant. In code compiled by
656 @code{byte-compile} rather than @code{byte-compile-file}, the
657 effect is identical to @code{eval-when-compile}. In uncompiled
658 code, both @code{eval-when-compile} and @code{load-time-value}
659 act exactly like @code{progn}.
663 (insert "This function was executed on: "
664 (current-time-string)
666 (eval-when-compile (current-time-string))
667 ;; or '#.(current-time-string) in real Common Lisp
669 (load-time-value (current-time-string))))
673 Byte-compiled, the above defun will result in the following code
674 (or its compiled equivalent, of course) in the @file{.elc} file:
677 (setq --temp-- (current-time-string))
679 (insert "This function was executed on: "
680 (current-time-string)
682 '"Wed Jun 23 18:33:43 1993"
688 @node Predicates, Control Structure, Program Structure, Top
692 This section describes functions for testing whether various
693 facts are true or false.
696 * Type Predicates:: `typep', `deftype', and `coerce'
697 * Equality Predicates:: `equalp'
700 @node Type Predicates, Equality Predicates, Predicates, Predicates
701 @section Type Predicates
704 The @dfn{CL} package defines a version of the Common Lisp @code{typep}
707 @defun typep object type
708 Check if @var{object} is of type @var{type}, where @var{type} is a
709 (quoted) type name of the sort used by Common Lisp. For example,
710 @code{(typep foo 'integer)} is equivalent to @code{(integerp foo)}.
713 The @var{type} argument to the above function is either a symbol
714 or a list beginning with a symbol.
718 If the type name is a symbol, Emacs appends @samp{-p} to the
719 symbol name to form the name of a predicate function for testing
720 the type. (Built-in predicates whose names end in @samp{p} rather
721 than @samp{-p} are used when appropriate.)
724 The type symbol @code{t} stands for the union of all types.
725 @code{(typep @var{object} t)} is always true. Likewise, the
726 type symbol @code{nil} stands for nothing at all, and
727 @code{(typep @var{object} nil)} is always false.
730 The type symbol @code{null} represents the symbol @code{nil}.
731 Thus @code{(typep @var{object} 'null)} is equivalent to
732 @code{(null @var{object})}.
735 The type symbol @code{atom} represents all objects that are not cons
736 cells. Thus @code{(typep @var{object} 'atom)} is equivalent to
737 @code{(atom @var{object})}.
740 The type symbol @code{real} is a synonym for @code{number}, and
741 @code{fixnum} is a synonym for @code{integer}.
744 The type symbols @code{character} and @code{string-char} match
745 integers in the range from 0 to 255.
748 The type symbol @code{float} uses the @code{floatp-safe} predicate
749 defined by this package rather than @code{floatp}, so it will work
750 correctly even in Emacs versions without floating-point support.
753 The type list @code{(integer @var{low} @var{high})} represents all
754 integers between @var{low} and @var{high}, inclusive. Either bound
755 may be a list of a single integer to specify an exclusive limit,
756 or a @code{*} to specify no limit. The type @code{(integer * *)}
757 is thus equivalent to @code{integer}.
760 Likewise, lists beginning with @code{float}, @code{real}, or
761 @code{number} represent numbers of that type falling in a particular
765 Lists beginning with @code{and}, @code{or}, and @code{not} form
766 combinations of types. For example, @code{(or integer (float 0 *))}
767 represents all objects that are integers or non-negative floats.
770 Lists beginning with @code{member} or @code{member*} represent
771 objects @code{eql} to any of the following values. For example,
772 @code{(member 1 2 3 4)} is equivalent to @code{(integer 1 4)},
773 and @code{(member nil)} is equivalent to @code{null}.
776 Lists of the form @code{(satisfies @var{predicate})} represent
777 all objects for which @var{predicate} returns true when called
778 with that object as an argument.
781 The following function and macro (not technically predicates) are
782 related to @code{typep}.
784 @defun coerce object type
785 This function attempts to convert @var{object} to the specified
786 @var{type}. If @var{object} is already of that type as determined by
787 @code{typep}, it is simply returned. Otherwise, certain types of
788 conversions will be made: If @var{type} is any sequence type
789 (@code{string}, @code{list}, etc.) then @var{object} will be
790 converted to that type if possible. If @var{type} is
791 @code{character}, then strings of length one and symbols with
792 one-character names can be coerced. If @var{type} is @code{float},
793 then integers can be coerced in versions of Emacs that support
794 floats. In all other circumstances, @code{coerce} signals an
798 @defspec deftype name arglist forms...
799 This macro defines a new type called @var{name}. It is similar
800 to @code{defmacro} in many ways; when @var{name} is encountered
801 as a type name, the body @var{forms} are evaluated and should
802 return a type specifier that is equivalent to the type. The
803 @var{arglist} is a Common Lisp argument list of the sort accepted
804 by @code{defmacro*}. The type specifier @samp{(@var{name} @var{args}...)}
805 is expanded by calling the expander with those arguments; the type
806 symbol @samp{@var{name}} is expanded by calling the expander with
807 no arguments. The @var{arglist} is processed the same as for
808 @code{defmacro*} except that optional arguments without explicit
809 defaults use @code{*} instead of @code{nil} as the ``default''
810 default. Some examples:
813 (deftype null () '(satisfies null)) ; predefined
814 (deftype list () '(or null cons)) ; predefined
815 (deftype unsigned-byte (&optional bits)
816 (list 'integer 0 (if (eq bits '*) bits (1- (lsh 1 bits)))))
817 (unsigned-byte 8) @equiv{} (integer 0 255)
818 (unsigned-byte) @equiv{} (integer 0 *)
819 unsigned-byte @equiv{} (integer 0 *)
823 The last example shows how the Common Lisp @code{unsigned-byte}
824 type specifier could be implemented if desired; this package does
825 not implement @code{unsigned-byte} by default.
828 The @code{typecase} and @code{check-type} macros also use type
829 names. @xref{Conditionals}. @xref{Assertions}. The @code{map},
830 @code{concatenate}, and @code{merge} functions take type-name
831 arguments to specify the type of sequence to return. @xref{Sequences}.
833 @node Equality Predicates, , Type Predicates, Predicates
834 @section Equality Predicates
837 This package defines the Common Lisp predicate @code{equalp}.
840 This function is a more flexible version of @code{equal}. In
841 particular, it compares strings case-insensitively, and it compares
842 numbers without regard to type (so that @code{(equalp 3 3.0)} is
843 true). Vectors and conses are compared recursively. All other
844 objects are compared as if by @code{equal}.
846 This function differs from Common Lisp @code{equalp} in several
847 respects. First, Common Lisp's @code{equalp} also compares
848 @emph{characters} case-insensitively, which would be impractical
849 in this package since Emacs does not distinguish between integers
850 and characters. In keeping with the idea that strings are less
851 vector-like in Emacs Lisp, this package's @code{equalp} also will
852 not compare strings against vectors of integers.
855 Also note that the Common Lisp functions @code{member} and @code{assoc}
856 use @code{eql} to compare elements, whereas Emacs Lisp follows the
857 MacLisp tradition and uses @code{equal} for these two functions.
858 In Emacs, use @code{member*} and @code{assoc*} to get functions
859 which use @code{eql} for comparisons.
861 @node Control Structure, Macros, Predicates, Top
862 @chapter Control Structure
865 The features described in the following sections implement
866 various advanced control structures, including the powerful
867 @code{setf} facility and a number of looping and conditional
871 * Assignment:: The `psetq' form
872 * Generalized Variables:: `setf', `incf', `push', etc.
873 * Variable Bindings:: `progv', `lexical-let', `flet', `macrolet'
874 * Conditionals:: `case', `typecase'
875 * Blocks and Exits:: `block', `return', `return-from'
876 * Iteration:: `do', `dotimes', `dolist', `do-symbols'
877 * Loop Facility:: The Common Lisp `loop' macro
878 * Multiple Values:: `values', `multiple-value-bind', etc.
881 @node Assignment, Generalized Variables, Control Structure, Control Structure
885 The @code{psetq} form is just like @code{setq}, except that multiple
886 assignments are done in parallel rather than sequentially.
888 @defspec psetq [symbol form]@dots{}
889 This special form (actually a macro) is used to assign to several
890 variables simultaneously. Given only one @var{symbol} and @var{form},
891 it has the same effect as @code{setq}. Given several @var{symbol}
892 and @var{form} pairs, it evaluates all the @var{form}s in advance
893 and then stores the corresponding variables afterwards.
897 (setq x (+ x y) y (* x y))
900 y ; @r{@code{y} was computed after @code{x} was set.}
903 (psetq x (+ x y) y (* x y))
906 y ; @r{@code{y} was computed before @code{x} was set.}
910 The simplest use of @code{psetq} is @code{(psetq x y y x)}, which
911 exchanges the values of two variables. (The @code{rotatef} form
912 provides an even more convenient way to swap two variables;
913 @pxref{Modify Macros}.)
915 @code{psetq} always returns @code{nil}.
918 @node Generalized Variables, Variable Bindings, Assignment, Control Structure
919 @section Generalized Variables
922 A ``generalized variable'' or ``place form'' is one of the many places
923 in Lisp memory where values can be stored. The simplest place form is
924 a regular Lisp variable. But the cars and cdrs of lists, elements
925 of arrays, properties of symbols, and many other locations are also
926 places where Lisp values are stored.
928 The @code{setf} form is like @code{setq}, except that it accepts
929 arbitrary place forms on the left side rather than just
930 symbols. For example, @code{(setf (car a) b)} sets the car of
931 @code{a} to @code{b}, doing the same operation as @code{(setcar a b)}
932 but without having to remember two separate functions for setting
933 and accessing every type of place.
935 Generalized variables are analogous to ``lvalues'' in the C
936 language, where @samp{x = a[i]} gets an element from an array
937 and @samp{a[i] = x} stores an element using the same notation.
938 Just as certain forms like @code{a[i]} can be lvalues in C, there
939 is a set of forms that can be generalized variables in Lisp.
942 * Basic Setf:: `setf' and place forms
943 * Modify Macros:: `incf', `push', `rotatef', `letf', `callf', etc.
944 * Customizing Setf:: `define-modify-macro', `defsetf', `define-setf-method'
947 @node Basic Setf, Modify Macros, Generalized Variables, Generalized Variables
948 @subsection Basic Setf
951 The @code{setf} macro is the most basic way to operate on generalized
954 @defspec setf [place form]@dots{}
955 This macro evaluates @var{form} and stores it in @var{place}, which
956 must be a valid generalized variable form. If there are several
957 @var{place} and @var{form} pairs, the assignments are done sequentially
958 just as with @code{setq}. @code{setf} returns the value of the last
961 The following Lisp forms will work as generalized variables, and
962 so may appear in the @var{place} argument of @code{setf}:
966 A symbol naming a variable. In other words, @code{(setf x y)} is
967 exactly equivalent to @code{(setq x y)}, and @code{setq} itself is
968 strictly speaking redundant now that @code{setf} exists. Many
969 programmers continue to prefer @code{setq} for setting simple
970 variables, though, purely for stylistic or historical reasons.
971 The macro @code{(setf x y)} actually expands to @code{(setq x y)},
972 so there is no performance penalty for using it in compiled code.
975 A call to any of the following Lisp functions:
978 car cdr caar .. cddddr
979 nth rest first .. tenth
981 symbol-function symbol-value symbol-plist
987 Note that for @code{nthcdr} and @code{getf}, the list argument
988 of the function must itself be a valid @var{place} form. For
989 example, @code{(setf (nthcdr 0 foo) 7)} will set @code{foo} itself
990 to 7. Note that @code{push} and @code{pop} on an @code{nthcdr}
991 place can be used to insert or delete at any position in a list.
992 The use of @code{nthcdr} as a @var{place} form is an extension
993 to standard Common Lisp.
996 The following Emacs-specific functions are also @code{setf}-able.
999 buffer-file-name marker-position
1000 buffer-modified-p match-data
1001 buffer-name mouse-position
1002 buffer-string overlay-end
1003 buffer-substring overlay-get
1004 current-buffer overlay-start
1005 current-case-table point
1006 current-column point-marker
1007 current-global-map point-max
1008 current-input-mode point-min
1009 current-local-map process-buffer
1010 current-window-configuration process-filter
1011 default-file-modes process-sentinel
1012 default-value read-mouse-position
1013 documentation-property screen-height
1014 extent-data screen-menubar
1015 extent-end-position screen-width
1016 extent-start-position selected-window
1017 face-background selected-screen
1018 face-background-pixmap selected-frame
1019 face-font standard-case-table
1020 face-foreground syntax-table
1021 face-underline-p window-buffer
1022 file-modes window-dedicated-p
1023 frame-height window-display-table
1024 frame-parameters window-height
1025 frame-visible-p window-hscroll
1026 frame-width window-point
1027 get-register window-start
1029 global-key-binding x-get-cut-buffer
1030 keymap-parent x-get-cutbuffer
1031 local-key-binding x-get-secondary-selection
1032 mark x-get-selection
1036 Most of these have directly corresponding ``set'' functions, like
1037 @code{use-local-map} for @code{current-local-map}, or @code{goto-char}
1038 for @code{point}. A few, like @code{point-min}, expand to longer
1039 sequences of code when they are @code{setf}'d (@code{(narrow-to-region
1040 x (point-max))} in this case).
1043 A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])},
1044 where @var{subplace} is itself a valid generalized variable whose
1045 current value is a string, and where the value stored is also a
1046 string. The new string is spliced into the specified part of the
1047 destination string. For example:
1050 (setq a (list "hello" "world"))
1051 @result{} ("hello" "world")
1054 (substring (cadr a) 2 4)
1056 (setf (substring (cadr a) 2 4) "o")
1061 @result{} ("hello" "wood")
1064 The generalized variable @code{buffer-substring}, listed above,
1065 also works in this way by replacing a portion of the current buffer.
1068 A call of the form @code{(apply '@var{func} @dots{})} or
1069 @code{(apply (function @var{func}) @dots{})}, where @var{func}
1070 is a @code{setf}-able function whose store function is ``suitable''
1071 in the sense described in Steele's book; since none of the standard
1072 Emacs place functions are suitable in this sense, this feature is
1073 only interesting when used with places you define yourself with
1074 @code{define-setf-method} or the long form of @code{defsetf}.
1077 A macro call, in which case the macro is expanded and @code{setf}
1078 is applied to the resulting form.
1081 Any form for which a @code{defsetf} or @code{define-setf-method}
1085 Using any forms other than these in the @var{place} argument to
1086 @code{setf} will signal an error.
1088 The @code{setf} macro takes care to evaluate all subforms in
1089 the proper left-to-right order; for example,
1092 (setf (aref vec (incf i)) i)
1096 looks like it will evaluate @code{(incf i)} exactly once, before the
1097 following access to @code{i}; the @code{setf} expander will insert
1098 temporary variables as necessary to ensure that it does in fact work
1099 this way no matter what setf-method is defined for @code{aref}.
1100 (In this case, @code{aset} would be used and no such steps would
1101 be necessary since @code{aset} takes its arguments in a convenient
1104 However, if the @var{place} form is a macro which explicitly
1105 evaluates its arguments in an unusual order, this unusual order
1106 will be preserved. Adapting an example from Steele, given
1109 (defmacro wrong-order (x y) (list 'aref y x))
1113 the form @code{(setf (wrong-order @var{a} @var{b}) 17)} will
1114 evaluate @var{b} first, then @var{a}, just as in an actual call
1115 to @code{wrong-order}.
1118 @node Modify Macros, Customizing Setf, Basic Setf, Generalized Variables
1119 @subsection Modify Macros
1122 This package defines a number of other macros besides @code{setf}
1123 that operate on generalized variables. Many are interesting and
1124 useful even when the @var{place} is just a variable name.
1126 @defspec psetf [place form]@dots{}
1127 This macro is to @code{setf} what @code{psetq} is to @code{setq}:
1128 When several @var{place}s and @var{form}s are involved, the
1129 assignments take place in parallel rather than sequentially.
1130 Specifically, all subforms are evaluated from left to right, then
1131 all the assignments are done (in an undefined order).
1134 @defspec incf place &optional x
1135 This macro increments the number stored in @var{place} by one, or
1136 by @var{x} if specified. The incremented value is returned. For
1137 example, @code{(incf i)} is equivalent to @code{(setq i (1+ i))}, and
1138 @code{(incf (car x) 2)} is equivalent to @code{(setcar x (+ (car x) 2))}.
1140 Once again, care is taken to preserve the ``apparent'' order of
1141 evaluation. For example,
1144 (incf (aref vec (incf i)))
1148 appears to increment @code{i} once, then increment the element of
1149 @code{vec} addressed by @code{i}; this is indeed exactly what it
1150 does, which means the above form is @emph{not} equivalent to the
1151 ``obvious'' expansion,
1154 (setf (aref vec (incf i)) (1+ (aref vec (incf i)))) ; Wrong!
1158 but rather to something more like
1161 (let ((temp (incf i)))
1162 (setf (aref vec temp) (1+ (aref vec temp))))
1166 Again, all of this is taken care of automatically by @code{incf} and
1167 the other generalized-variable macros.
1169 As a more Emacs-specific example of @code{incf}, the expression
1170 @code{(incf (point) @var{n})} is essentially equivalent to
1171 @code{(forward-char @var{n})}.
1174 @defspec decf place &optional x
1175 This macro decrements the number stored in @var{place} by one, or
1176 by @var{x} if specified.
1180 This macro removes and returns the first element of the list stored
1181 in @var{place}. It is analogous to @code{(prog1 (car @var{place})
1182 (setf @var{place} (cdr @var{place})))}, except that it takes care
1183 to evaluate all subforms only once.
1186 @defspec push x place
1187 This macro inserts @var{x} at the front of the list stored in
1188 @var{place}. It is analogous to @code{(setf @var{place} (cons
1189 @var{x} @var{place}))}, except for evaluation of the subforms.
1192 @defspec pushnew x place @t{&key :test :test-not :key}
1193 This macro inserts @var{x} at the front of the list stored in
1194 @var{place}, but only if @var{x} was not @code{eql} to any
1195 existing element of the list. The optional keyword arguments
1196 are interpreted in the same way as for @code{adjoin}.
1197 @xref{Lists as Sets}.
1200 @defspec shiftf place@dots{} newvalue
1201 This macro shifts the @var{place}s left by one, shifting in the
1202 value of @var{newvalue} (which may be any Lisp expression, not just
1203 a generalized variable), and returning the value shifted out of
1204 the first @var{place}. Thus, @code{(shiftf @var{a} @var{b} @var{c}
1205 @var{d})} is equivalent to
1210 (psetf @var{a} @var{b}
1216 except that the subforms of @var{a}, @var{b}, and @var{c} are actually
1217 evaluated only once each and in the apparent order.
1220 @defspec rotatef place@dots{}
1221 This macro rotates the @var{place}s left by one in circular fashion.
1222 Thus, @code{(rotatef @var{a} @var{b} @var{c} @var{d})} is equivalent to
1225 (psetf @var{a} @var{b}
1232 except for the evaluation of subforms. @code{rotatef} always
1233 returns @code{nil}. Note that @code{(rotatef @var{a} @var{b})}
1234 conveniently exchanges @var{a} and @var{b}.
1237 The following macros were invented for this package; they have no
1238 analogues in Common Lisp.
1240 @defspec letf (bindings@dots{}) forms@dots{}
1241 This macro is analogous to @code{let}, but for generalized variables
1242 rather than just symbols. Each @var{binding} should be of the form
1243 @code{(@var{place} @var{value})}; the original contents of the
1244 @var{place}s are saved, the @var{value}s are stored in them, and
1245 then the body @var{form}s are executed. Afterwards, the @var{places}
1246 are set back to their original saved contents. This cleanup happens
1247 even if the @var{form}s exit irregularly due to a @code{throw} or an
1253 (letf (((point) (point-min))
1259 moves ``point'' in the current buffer to the beginning of the buffer,
1260 and also binds @code{a} to 17 (as if by a normal @code{let}, since
1261 @code{a} is just a regular variable). After the body exits, @code{a}
1262 is set back to its original value and point is moved back to its
1265 Note that @code{letf} on @code{(point)} is not quite like a
1266 @code{save-excursion}, as the latter effectively saves a marker
1267 which tracks insertions and deletions in the buffer. Actually,
1268 a @code{letf} of @code{(point-marker)} is much closer to this
1269 behavior. (@code{point} and @code{point-marker} are equivalent
1270 as @code{setf} places; each will accept either an integer or a
1271 marker as the stored value.)
1273 Since generalized variables look like lists, @code{let}'s shorthand
1274 of using @samp{foo} for @samp{(foo nil)} as a @var{binding} would
1275 be ambiguous in @code{letf} and is not allowed.
1277 However, a @var{binding} specifier may be a one-element list
1278 @samp{(@var{place})}, which is similar to @samp{(@var{place}
1279 @var{place})}. In other words, the @var{place} is not disturbed
1280 on entry to the body, and the only effect of the @code{letf} is
1281 to restore the original value of @var{place} afterwards. (The
1282 redundant access-and-store suggested by the @code{(@var{place}
1283 @var{place})} example does not actually occur.)
1285 In most cases, the @var{place} must have a well-defined value on
1286 entry to the @code{letf} form. The only exceptions are plain
1287 variables and calls to @code{symbol-value} and @code{symbol-function}.
1288 If the symbol is not bound on entry, it is simply made unbound by
1289 @code{makunbound} or @code{fmakunbound} on exit.
1292 @defspec letf* (bindings@dots{}) forms@dots{}
1293 This macro is to @code{letf} what @code{let*} is to @code{let}:
1294 It does the bindings in sequential rather than parallel order.
1297 @defspec callf @var{function} @var{place} @var{args}@dots{}
1298 This is the ``generic'' modify macro. It calls @var{function},
1299 which should be an unquoted function name, macro name, or lambda.
1300 It passes @var{place} and @var{args} as arguments, and assigns the
1301 result back to @var{place}. For example, @code{(incf @var{place}
1302 @var{n})} is the same as @code{(callf + @var{place} @var{n})}.
1306 (callf abs my-number)
1307 (callf concat (buffer-name) "<" (int-to-string n) ">")
1308 (callf union happy-people (list joe bob) :test 'same-person)
1311 @xref{Customizing Setf}, for @code{define-modify-macro}, a way
1312 to create even more concise notations for modify macros. Note
1313 again that @code{callf} is an extension to standard Common Lisp.
1316 @defspec callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{}
1317 This macro is like @code{callf}, except that @var{place} is
1318 the @emph{second} argument of @var{function} rather than the
1319 first. For example, @code{(push @var{x} @var{place})} is
1320 equivalent to @code{(callf2 cons @var{x} @var{place})}.
1323 The @code{callf} and @code{callf2} macros serve as building
1324 blocks for other macros like @code{incf}, @code{pushnew}, and
1325 @code{define-modify-macro}. The @code{letf} and @code{letf*}
1326 macros are used in the processing of symbol macros;
1327 @pxref{Macro Bindings}.
1329 @node Customizing Setf, , Modify Macros, Generalized Variables
1330 @subsection Customizing Setf
1333 Common Lisp defines three macros, @code{define-modify-macro},
1334 @code{defsetf}, and @code{define-setf-method}, that allow the
1335 user to extend generalized variables in various ways.
1337 @defspec define-modify-macro name arglist function [doc-string]
1338 This macro defines a ``read-modify-write'' macro similar to
1339 @code{incf} and @code{decf}. The macro @var{name} is defined
1340 to take a @var{place} argument followed by additional arguments
1341 described by @var{arglist}. The call
1344 (@var{name} @var{place} @var{args}...)
1351 (callf @var{func} @var{place} @var{args}...)
1355 which in turn is roughly equivalent to
1358 (setf @var{place} (@var{func} @var{place} @var{args}...))
1364 (define-modify-macro incf (&optional (n 1)) +)
1365 (define-modify-macro concatf (&rest args) concat)
1368 Note that @code{&key} is not allowed in @var{arglist}, but
1369 @code{&rest} is sufficient to pass keywords on to the function.
1371 Most of the modify macros defined by Common Lisp do not exactly
1372 follow the pattern of @code{define-modify-macro}. For example,
1373 @code{push} takes its arguments in the wrong order, and @code{pop}
1374 is completely irregular. You can define these macros ``by hand''
1375 using @code{get-setf-method}, or consult the source file
1376 @file{cl-macs.el} to see how to use the internal @code{setf}
1380 @defspec defsetf access-fn update-fn
1381 This is the simpler of two @code{defsetf} forms. Where
1382 @var{access-fn} is the name of a function which accesses a place,
1383 this declares @var{update-fn} to be the corresponding store
1384 function. From now on,
1387 (setf (@var{access-fn} @var{arg1} @var{arg2} @var{arg3}) @var{value})
1394 (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} @var{value})
1398 The @var{update-fn} is required to be either a true function, or
1399 a macro which evaluates its arguments in a function-like way. Also,
1400 the @var{update-fn} is expected to return @var{value} as its result.
1401 Otherwise, the above expansion would not obey the rules for the way
1402 @code{setf} is supposed to behave.
1404 As a special (non-Common-Lisp) extension, a third argument of @code{t}
1405 to @code{defsetf} says that the @code{update-fn}'s return value is
1406 not suitable, so that the above @code{setf} should be expanded to
1410 (let ((temp @var{value}))
1411 (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} temp)
1415 Some examples of the use of @code{defsetf}, drawn from the standard
1416 suite of setf methods, are:
1419 (defsetf car setcar)
1420 (defsetf symbol-value set)
1421 (defsetf buffer-name rename-buffer t)
1425 @defspec defsetf access-fn arglist (store-var) forms@dots{}
1426 This is the second, more complex, form of @code{defsetf}. It is
1427 rather like @code{defmacro} except for the additional @var{store-var}
1428 argument. The @var{forms} should return a Lisp form which stores
1429 the value of @var{store-var} into the generalized variable formed
1430 by a call to @var{access-fn} with arguments described by @var{arglist}.
1431 The @var{forms} may begin with a string which documents the @code{setf}
1432 method (analogous to the doc string that appears at the front of a
1435 For example, the simple form of @code{defsetf} is shorthand for
1438 (defsetf @var{access-fn} (&rest args) (store)
1439 (append '(@var{update-fn}) args (list store)))
1442 The Lisp form that is returned can access the arguments from
1443 @var{arglist} and @var{store-var} in an unrestricted fashion;
1444 macros like @code{setf} and @code{incf} which invoke this
1445 setf-method will insert temporary variables as needed to make
1446 sure the apparent order of evaluation is preserved.
1448 Another example drawn from the standard package:
1451 (defsetf nth (n x) (store)
1452 (list 'setcar (list 'nthcdr n x) store))
1456 @defspec define-setf-method access-fn arglist forms@dots{}
1457 This is the most general way to create new place forms. When
1458 a @code{setf} to @var{access-fn} with arguments described by
1459 @var{arglist} is expanded, the @var{forms} are evaluated and
1460 must return a list of five items:
1464 A list of @dfn{temporary variables}.
1467 A list of @dfn{value forms} corresponding to the temporary variables
1468 above. The temporary variables will be bound to these value forms
1469 as the first step of any operation on the generalized variable.
1472 A list of exactly one @dfn{store variable} (generally obtained
1473 from a call to @code{gensym}).
1476 A Lisp form which stores the contents of the store variable into
1477 the generalized variable, assuming the temporaries have been
1478 bound as described above.
1481 A Lisp form which accesses the contents of the generalized variable,
1482 assuming the temporaries have been bound.
1485 This is exactly like the Common Lisp macro of the same name,
1486 except that the method returns a list of five values rather
1487 than the five values themselves, since Emacs Lisp does not
1488 support Common Lisp's notion of multiple return values.
1490 Once again, the @var{forms} may begin with a documentation string.
1492 A setf-method should be maximally conservative with regard to
1493 temporary variables. In the setf-methods generated by
1494 @code{defsetf}, the second return value is simply the list of
1495 arguments in the place form, and the first return value is a
1496 list of a corresponding number of temporary variables generated
1497 by @code{gensym}. Macros like @code{setf} and @code{incf} which
1498 use this setf-method will optimize away most temporaries that
1499 turn out to be unnecessary, so there is little reason for the
1500 setf-method itself to optimize.
1503 @defun get-setf-method place &optional env
1504 This function returns the setf-method for @var{place}, by
1505 invoking the definition previously recorded by @code{defsetf}
1506 or @code{define-setf-method}. The result is a list of five
1507 values as described above. You can use this function to build
1508 your own @code{incf}-like modify macros. (Actually, it is
1509 better to use the internal functions @code{cl-setf-do-modify}
1510 and @code{cl-setf-do-store}, which are a bit easier to use and
1511 which also do a number of optimizations; consult the source
1512 code for the @code{incf} function for a simple example.)
1514 The argument @var{env} specifies the ``environment'' to be
1515 passed on to @code{macroexpand} if @code{get-setf-method} should
1516 need to expand a macro in @var{place}. It should come from
1517 an @code{&environment} argument to the macro or setf-method
1518 that called @code{get-setf-method}.
1520 See also the source code for the setf-methods for @code{apply}
1521 and @code{substring}, each of which works by calling
1522 @code{get-setf-method} on a simpler case, then massaging
1523 the result in various ways.
1526 Modern Common Lisp defines a second, independent way to specify
1527 the @code{setf} behavior of a function, namely ``@code{setf}
1528 functions'' whose names are lists @code{(setf @var{name})}
1529 rather than symbols. For example, @code{(defun (setf foo) @dots{})}
1530 defines the function that is used when @code{setf} is applied to
1531 @code{foo}. This package does not currently support @code{setf}
1532 functions. In particular, it is a compile-time error to use
1533 @code{setf} on a form which has not already been @code{defsetf}'d
1534 or otherwise declared; in newer Common Lisps, this would not be
1535 an error since the function @code{(setf @var{func})} might be
1542 @node Variable Bindings, Conditionals, Generalized Variables, Control Structure
1543 @section Variable Bindings
1546 These Lisp forms make bindings to variables and function names,
1547 analogous to Lisp's built-in @code{let} form.
1549 @xref{Modify Macros}, for the @code{letf} and @code{letf*} forms which
1550 are also related to variable bindings.
1553 * Dynamic Bindings:: The `progv' form
1554 * Lexical Bindings:: `lexical-let' and lexical closures
1555 * Function Bindings:: `flet' and `labels'
1556 * Macro Bindings:: `macrolet' and `symbol-macrolet'
1559 @node Dynamic Bindings, Lexical Bindings, Variable Bindings, Variable Bindings
1560 @subsection Dynamic Bindings
1563 The standard @code{let} form binds variables whose names are known
1564 at compile-time. The @code{progv} form provides an easy way to
1565 bind variables whose names are computed at run-time.
1567 @defspec progv symbols values forms@dots{}
1568 This form establishes @code{let}-style variable bindings on a
1569 set of variables computed at run-time. The expressions
1570 @var{symbols} and @var{values} are evaluated, and must return lists
1571 of symbols and values, respectively. The symbols are bound to the
1572 corresponding values for the duration of the body @var{form}s.
1573 If @var{values} is shorter than @var{symbols}, the last few symbols
1574 are made unbound (as if by @code{makunbound}) inside the body.
1575 If @var{symbols} is shorter than @var{values}, the excess values
1579 @node Lexical Bindings, Function Bindings, Dynamic Bindings, Variable Bindings
1580 @subsection Lexical Bindings
1583 The @dfn{CL} package defines the following macro which
1584 more closely follows the Common Lisp @code{let} form:
1586 @defspec lexical-let (bindings@dots{}) forms@dots{}
1587 This form is exactly like @code{let} except that the bindings it
1588 establishes are purely lexical. Lexical bindings are similar to
1589 local variables in a language like C: Only the code physically
1590 within the body of the @code{lexical-let} (after macro expansion)
1591 may refer to the bound variables.
1595 (defun foo (b) (+ a b))
1596 (let ((a 2)) (foo a))
1598 (lexical-let ((a 2)) (foo a))
1603 In this example, a regular @code{let} binding of @code{a} actually
1604 makes a temporary change to the global variable @code{a}, so @code{foo}
1605 is able to see the binding of @code{a} to 2. But @code{lexical-let}
1606 actually creates a distinct local variable @code{a} for use within its
1607 body, without any effect on the global variable of the same name.
1609 The most important use of lexical bindings is to create @dfn{closures}.
1610 A closure is a function object that refers to an outside lexical
1611 variable. For example:
1614 (defun make-adder (n)
1615 (lexical-let ((n n))
1616 (function (lambda (m) (+ n m)))))
1617 (setq add17 (make-adder 17))
1623 The call @code{(make-adder 17)} returns a function object which adds
1624 17 to its argument. If @code{let} had been used instead of
1625 @code{lexical-let}, the function object would have referred to the
1626 global @code{n}, which would have been bound to 17 only during the
1627 call to @code{make-adder} itself.
1630 (defun make-counter ()
1631 (lexical-let ((n 0))
1632 (function* (lambda (&optional (m 1)) (incf n m)))))
1633 (setq count-1 (make-counter))
1636 (funcall count-1 14)
1638 (setq count-2 (make-counter))
1648 Here we see that each call to @code{make-counter} creates a distinct
1649 local variable @code{n}, which serves as a private counter for the
1650 function object that is returned.
1652 Closed-over lexical variables persist until the last reference to
1653 them goes away, just like all other Lisp objects. For example,
1654 @code{count-2} refers to a function object which refers to an
1655 instance of the variable @code{n}; this is the only reference
1656 to that variable, so after @code{(setq count-2 nil)} the garbage
1657 collector would be able to delete this instance of @code{n}.
1658 Of course, if a @code{lexical-let} does not actually create any
1659 closures, then the lexical variables are free as soon as the
1660 @code{lexical-let} returns.
1662 Many closures are used only during the extent of the bindings they
1663 refer to; these are known as ``downward funargs'' in Lisp parlance.
1664 When a closure is used in this way, regular Emacs Lisp dynamic
1665 bindings suffice and will be more efficient than @code{lexical-let}
1669 (defun add-to-list (x list)
1670 (mapcar (lambda (y) (+ x y))) list)
1671 (add-to-list 7 '(1 2 5))
1676 Since this lambda is only used while @code{x} is still bound,
1677 it is not necessary to make a true closure out of it.
1679 You can use @code{defun} or @code{flet} inside a @code{lexical-let}
1680 to create a named closure. If several closures are created in the
1681 body of a single @code{lexical-let}, they all close over the same
1682 instance of the lexical variable.
1684 The @code{lexical-let} form is an extension to Common Lisp. In
1685 true Common Lisp, all bindings are lexical unless declared otherwise.
1688 @defspec lexical-let* (bindings@dots{}) forms@dots{}
1689 This form is just like @code{lexical-let}, except that the bindings
1690 are made sequentially in the manner of @code{let*}.
1693 @node Function Bindings, Macro Bindings, Lexical Bindings, Variable Bindings
1694 @subsection Function Bindings
1697 These forms make @code{let}-like bindings to functions instead
1700 @defspec flet (bindings@dots{}) forms@dots{}
1701 This form establishes @code{let}-style bindings on the function
1702 cells of symbols rather than on the value cells. Each @var{binding}
1703 must be a list of the form @samp{(@var{name} @var{arglist}
1704 @var{forms}@dots{})}, which defines a function exactly as if
1705 it were a @code{defun*} form. The function @var{name} is defined
1706 accordingly for the duration of the body of the @code{flet}; then
1707 the old function definition, or lack thereof, is restored.
1709 While @code{flet} in Common Lisp establishes a lexical binding of
1710 @var{name}, Emacs Lisp @code{flet} makes a dynamic binding. The
1711 result is that @code{flet} affects indirect calls to a function as
1712 well as calls directly inside the @code{flet} form itself.
1714 You can use @code{flet} to disable or modify the behavior of a
1715 function in a temporary fashion. This will even work on Emacs
1716 primitives, although note that some calls to primitive functions
1717 internal to Emacs are made without going through the symbol's
1718 function cell, and so will not be affected by @code{flet}. For
1722 (flet ((message (&rest args) (push args saved-msgs)))
1726 This code attempts to replace the built-in function @code{message}
1727 with a function that simply saves the messages in a list rather
1728 than displaying them. The original definition of @code{message}
1729 will be restored after @code{do-something} exits. This code will
1730 work fine on messages generated by other Lisp code, but messages
1731 generated directly inside Emacs will not be caught since they make
1732 direct C-language calls to the message routines rather than going
1733 through the Lisp @code{message} function.
1736 Also note that many primitives (e.g. @code{+}) have special byte-compile
1737 handling. Attempts to redefine such functions using @code{flet} will
1738 fail if byte-compiled. In such cases, use @code{labels} instead.
1740 Functions defined by @code{flet} may use the full Common Lisp
1741 argument notation supported by @code{defun*}; also, the function
1742 body is enclosed in an implicit block as if by @code{defun*}.
1743 @xref{Program Structure}.
1746 @defspec labels (bindings@dots{}) forms@dots{}
1747 The @code{labels} form is like @code{flet}, except that it
1748 makes lexical bindings of the function names rather than
1749 dynamic bindings. (In true Common Lisp, both @code{flet} and
1750 @code{labels} make lexical bindings of slightly different sorts;
1751 since Emacs Lisp is dynamically bound by default, it seemed
1752 more appropriate for @code{flet} also to use dynamic binding.
1753 The @code{labels} form, with its lexical binding, is fully
1754 compatible with Common Lisp.)
1756 Lexical scoping means that all references to the named
1757 functions must appear physically within the body of the
1758 @code{labels} form. References may appear both in the body
1759 @var{forms} of @code{labels} itself, and in the bodies of
1760 the functions themselves. Thus, @code{labels} can define
1761 local recursive functions, or mutually-recursive sets of
1764 A ``reference'' to a function name is either a call to that
1765 function, or a use of its name quoted by @code{quote} or
1766 @code{function} to be passed on to, say, @code{mapcar}.
1769 @node Macro Bindings, , Function Bindings, Variable Bindings
1770 @subsection Macro Bindings
1773 These forms create local macros and ``symbol macros.''
1775 @defspec macrolet (bindings@dots{}) forms@dots{}
1776 This form is analogous to @code{flet}, but for macros instead of
1777 functions. Each @var{binding} is a list of the same form as the
1778 arguments to @code{defmacro*} (i.e., a macro name, argument list,
1779 and macro-expander forms). The macro is defined accordingly for
1780 use within the body of the @code{macrolet}.
1782 Because of the nature of macros, @code{macrolet} is lexically
1783 scoped even in Emacs Lisp: The @code{macrolet} binding will
1784 affect only calls that appear physically within the body
1785 @var{forms}, possibly after expansion of other macros in the
1789 @defspec symbol-macrolet (bindings@dots{}) forms@dots{}
1790 This form creates @dfn{symbol macros}, which are macros that look
1791 like variable references rather than function calls. Each
1792 @var{binding} is a list @samp{(@var{var} @var{expansion})};
1793 any reference to @var{var} within the body @var{forms} is
1794 replaced by @var{expansion}.
1798 (symbol-macrolet ((foo (car bar)))
1804 A @code{setq} of a symbol macro is treated the same as a @code{setf}.
1805 I.e., @code{(setq foo 4)} in the above would be equivalent to
1806 @code{(setf foo 4)}, which in turn expands to @code{(setf (car bar) 4)}.
1808 Likewise, a @code{let} or @code{let*} binding a symbol macro is
1809 treated like a @code{letf} or @code{letf*}. This differs from true
1810 Common Lisp, where the rules of lexical scoping cause a @code{let}
1811 binding to shadow a @code{symbol-macrolet} binding. In this package,
1812 only @code{lexical-let} and @code{lexical-let*} will shadow a symbol
1815 There is no analogue of @code{defmacro} for symbol macros; all symbol
1816 macros are local. A typical use of @code{symbol-macrolet} is in the
1817 expansion of another macro:
1820 (defmacro* my-dolist ((x list) &rest body)
1821 (let ((var (gensym)))
1822 (list 'loop 'for var 'on list 'do
1823 (list* 'symbol-macrolet (list (list x (list 'car var)))
1826 (setq mylist '(1 2 3 4))
1827 (my-dolist (x mylist) (incf x))
1833 In this example, the @code{my-dolist} macro is similar to @code{dolist}
1834 (@pxref{Iteration}) except that the variable @code{x} becomes a true
1835 reference onto the elements of the list. The @code{my-dolist} call
1836 shown here expands to
1839 (loop for G1234 on mylist do
1840 (symbol-macrolet ((x (car G1234)))
1845 which in turn expands to
1848 (loop for G1234 on mylist do (incf (car G1234)))
1851 @xref{Loop Facility}, for a description of the @code{loop} macro.
1852 This package defines a nonstandard @code{in-ref} loop clause that
1853 works much like @code{my-dolist}.
1856 @node Conditionals, Blocks and Exits, Variable Bindings, Control Structure
1857 @section Conditionals
1860 These conditional forms augment Emacs Lisp's simple @code{if},
1861 @code{and}, @code{or}, and @code{cond} forms.
1863 @defspec case keyform clause@dots{}
1864 This macro evaluates @var{keyform}, then compares it with the key
1865 values listed in the various @var{clause}s. Whichever clause matches
1866 the key is executed; comparison is done by @code{eql}. If no clause
1867 matches, the @code{case} form returns @code{nil}. The clauses are
1871 (@var{keylist} @var{body-forms}@dots{})
1875 where @var{keylist} is a list of key values. If there is exactly
1876 one value, and it is not a cons cell or the symbol @code{nil} or
1877 @code{t}, then it can be used by itself as a @var{keylist} without
1878 being enclosed in a list. All key values in the @code{case} form
1879 must be distinct. The final clauses may use @code{t} in place of
1880 a @var{keylist} to indicate a default clause that should be taken
1881 if none of the other clauses match. (The symbol @code{otherwise}
1882 is also recognized in place of @code{t}. To make a clause that
1883 matches the actual symbol @code{t}, @code{nil}, or @code{otherwise},
1884 enclose the symbol in a list.)
1886 For example, this expression reads a keystroke, then does one of
1887 four things depending on whether it is an @samp{a}, a @samp{b},
1888 a @key{RET} or @kbd{C-j}, or anything else.
1894 ((?\r ?\n) (do-ret-thing))
1895 (t (do-other-thing)))
1899 @defspec ecase keyform clause@dots{}
1900 This macro is just like @code{case}, except that if the key does
1901 not match any of the clauses, an error is signaled rather than
1902 simply returning @code{nil}.
1905 @defspec typecase keyform clause@dots{}
1906 This macro is a version of @code{case} that checks for types
1907 rather than values. Each @var{clause} is of the form
1908 @samp{(@var{type} @var{body}...)}. @xref{Type Predicates},
1909 for a description of type specifiers. For example,
1913 (integer (munch-integer x))
1914 (float (munch-float x))
1915 (string (munch-integer (string-to-int x)))
1916 (t (munch-anything x)))
1919 The type specifier @code{t} matches any type of object; the word
1920 @code{otherwise} is also allowed. To make one clause match any of
1921 several types, use an @code{(or ...)} type specifier.
1924 @defspec etypecase keyform clause@dots{}
1925 This macro is just like @code{typecase}, except that if the key does
1926 not match any of the clauses, an error is signaled rather than
1927 simply returning @code{nil}.
1930 @node Blocks and Exits, Iteration, Conditionals, Control Structure
1931 @section Blocks and Exits
1934 Common Lisp @dfn{blocks} provide a non-local exit mechanism very
1935 similar to @code{catch} and @code{throw}, but lexically rather than
1936 dynamically scoped. This package actually implements @code{block}
1937 in terms of @code{catch}; however, the lexical scoping allows the
1938 optimizing byte-compiler to omit the costly @code{catch} step if the
1939 body of the block does not actually @code{return-from} the block.
1941 @defspec block name forms@dots{}
1942 The @var{forms} are evaluated as if by a @code{progn}. However,
1943 if any of the @var{forms} execute @code{(return-from @var{name})},
1944 they will jump out and return directly from the @code{block} form.
1945 The @code{block} returns the result of the last @var{form} unless
1946 a @code{return-from} occurs.
1948 The @code{block}/@code{return-from} mechanism is quite similar to
1949 the @code{catch}/@code{throw} mechanism. The main differences are
1950 that block @var{name}s are unevaluated symbols, rather than forms
1951 (such as quoted symbols) which evaluate to a tag at run-time; and
1952 also that blocks are lexically scoped whereas @code{catch}/@code{throw}
1953 are dynamically scoped. This means that functions called from the
1954 body of a @code{catch} can also @code{throw} to the @code{catch},
1955 but the @code{return-from} referring to a block name must appear
1956 physically within the @var{forms} that make up the body of the block.
1957 They may not appear within other called functions, although they may
1958 appear within macro expansions or @code{lambda}s in the body. Block
1959 names and @code{catch} names form independent name-spaces.
1961 In true Common Lisp, @code{defun} and @code{defmacro} surround
1962 the function or expander bodies with implicit blocks with the
1963 same name as the function or macro. This does not occur in Emacs
1964 Lisp, but this package provides @code{defun*} and @code{defmacro*}
1965 forms which do create the implicit block.
1967 The Common Lisp looping constructs defined by this package,
1968 such as @code{loop} and @code{dolist}, also create implicit blocks
1969 just as in Common Lisp.
1971 Because they are implemented in terms of Emacs Lisp @code{catch}
1972 and @code{throw}, blocks have the same overhead as actual
1973 @code{catch} constructs (roughly two function calls). However,
1974 the optimizing byte compiler will optimize away the @code{catch}
1976 not in fact contain any @code{return} or @code{return-from} calls
1977 that jump to it. This means that @code{do} loops and @code{defun*}
1978 functions which don't use @code{return} don't pay the overhead to
1982 @defspec return-from name [result]
1983 This macro returns from the block named @var{name}, which must be
1984 an (unevaluated) symbol. If a @var{result} form is specified, it
1985 is evaluated to produce the result returned from the @code{block}.
1986 Otherwise, @code{nil} is returned.
1989 @defspec return [result]
1990 This macro is exactly like @code{(return-from nil @var{result})}.
1991 Common Lisp loops like @code{do} and @code{dolist} implicitly enclose
1992 themselves in @code{nil} blocks.
1995 @node Iteration, Loop Facility, Blocks and Exits, Control Structure
1999 The macros described here provide more sophisticated, high-level
2000 looping constructs to complement Emacs Lisp's basic @code{while}
2003 @defspec loop forms@dots{}
2004 The @dfn{CL} package supports both the simple, old-style meaning of
2005 @code{loop} and the extremely powerful and flexible feature known as
2006 the @dfn{Loop Facility} or @dfn{Loop Macro}. This more advanced
2007 facility is discussed in the following section; @pxref{Loop Facility}.
2008 The simple form of @code{loop} is described here.
2010 If @code{loop} is followed by zero or more Lisp expressions,
2011 then @code{(loop @var{exprs}@dots{})} simply creates an infinite
2012 loop executing the expressions over and over. The loop is
2013 enclosed in an implicit @code{nil} block. Thus,
2016 (loop (foo) (if (no-more) (return 72)) (bar))
2020 is exactly equivalent to
2023 (block nil (while t (foo) (if (no-more) (return 72)) (bar)))
2026 If any of the expressions are plain symbols, the loop is instead
2027 interpreted as a Loop Macro specification as described later.
2028 (This is not a restriction in practice, since a plain symbol
2029 in the above notation would simply access and throw away the
2030 value of a variable.)
2033 @defspec do (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
2034 This macro creates a general iterative loop. Each @var{spec} is
2038 (@var{var} [@var{init} [@var{step}]])
2041 The loop works as follows: First, each @var{var} is bound to the
2042 associated @var{init} value as if by a @code{let} form. Then, in
2043 each iteration of the loop, the @var{end-test} is evaluated; if
2044 true, the loop is finished. Otherwise, the body @var{forms} are
2045 evaluated, then each @var{var} is set to the associated @var{step}
2046 expression (as if by a @code{psetq} form) and the next iteration
2047 begins. Once the @var{end-test} becomes true, the @var{result}
2048 forms are evaluated (with the @var{var}s still bound to their
2049 values) to produce the result returned by @code{do}.
2051 The entire @code{do} loop is enclosed in an implicit @code{nil}
2052 block, so that you can use @code{(return)} to break out of the
2055 If there are no @var{result} forms, the loop returns @code{nil}.
2056 If a given @var{var} has no @var{step} form, it is bound to its
2057 @var{init} value but not otherwise modified during the @code{do}
2058 loop (unless the code explicitly modifies it); this case is just
2059 a shorthand for putting a @code{(let ((@var{var} @var{init})) @dots{})}
2060 around the loop. If @var{init} is also omitted it defaults to
2061 @code{nil}, and in this case a plain @samp{@var{var}} can be used
2062 in place of @samp{(@var{var})}, again following the analogy with
2065 This example (from Steele) illustrates a loop which applies the
2066 function @code{f} to successive pairs of values from the lists
2067 @code{foo} and @code{bar}; it is equivalent to the call
2068 @code{(mapcar* 'f foo bar)}. Note that this loop has no body
2069 @var{forms} at all, performing all its work as side effects of
2070 the rest of the loop.
2073 (do ((x foo (cdr x))
2075 (z nil (cons (f (car x) (car y)) z)))
2076 ((or (null x) (null y))
2081 @defspec do* (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
2082 This is to @code{do} what @code{let*} is to @code{let}. In
2083 particular, the initial values are bound as if by @code{let*}
2084 rather than @code{let}, and the steps are assigned as if by
2085 @code{setq} rather than @code{psetq}.
2087 Here is another way to write the above loop:
2090 (do* ((xp foo (cdr xp))
2092 (x (car xp) (car xp))
2093 (y (car yp) (car yp))
2095 ((or (null xp) (null yp))
2101 @defspec dolist (var list [result]) forms@dots{}
2102 This is a more specialized loop which iterates across the elements
2103 of a list. @var{list} should evaluate to a list; the body @var{forms}
2104 are executed with @var{var} bound to each element of the list in
2105 turn. Finally, the @var{result} form (or @code{nil}) is evaluated
2106 with @var{var} bound to @code{nil} to produce the result returned by
2107 the loop. Unlike with Emacs's built in @code{dolist}, the loop is
2108 surrounded by an implicit @code{nil} block.
2111 @defspec dotimes (var count [result]) forms@dots{}
2112 This is a more specialized loop which iterates a specified number
2113 of times. The body is executed with @var{var} bound to the integers
2114 from zero (inclusive) to @var{count} (exclusive), in turn. Then
2115 the @code{result} form is evaluated with @var{var} bound to the total
2116 number of iterations that were done (i.e., @code{(max 0 @var{count})})
2117 to get the return value for the loop form. Unlike with Emacs's built in
2118 @code{dolist}, the loop is surrounded by an implicit @code{nil} block.
2121 @defspec do-symbols (var [obarray [result]]) forms@dots{}
2122 This loop iterates over all interned symbols. If @var{obarray}
2123 is specified and is not @code{nil}, it loops over all symbols in
2124 that obarray. For each symbol, the body @var{forms} are evaluated
2125 with @var{var} bound to that symbol. The symbols are visited in
2126 an unspecified order. Afterward the @var{result} form, if any,
2127 is evaluated (with @var{var} bound to @code{nil}) to get the return
2128 value. The loop is surrounded by an implicit @code{nil} block.
2131 @defspec do-all-symbols (var [result]) forms@dots{}
2132 This is identical to @code{do-symbols} except that the @var{obarray}
2133 argument is omitted; it always iterates over the default obarray.
2136 @xref{Mapping over Sequences}, for some more functions for
2137 iterating over vectors or lists.
2139 @node Loop Facility, Multiple Values, Iteration, Control Structure
2140 @section Loop Facility
2143 A common complaint with Lisp's traditional looping constructs is
2144 that they are either too simple and limited, such as Common Lisp's
2145 @code{dotimes} or Emacs Lisp's @code{while}, or too unreadable and
2146 obscure, like Common Lisp's @code{do} loop.
2148 To remedy this, recent versions of Common Lisp have added a new
2149 construct called the ``Loop Facility'' or ``@code{loop} macro,''
2150 with an easy-to-use but very powerful and expressive syntax.
2153 * Loop Basics:: `loop' macro, basic clause structure
2154 * Loop Examples:: Working examples of `loop' macro
2155 * For Clauses:: Clauses introduced by `for' or `as'
2156 * Iteration Clauses:: `repeat', `while', `thereis', etc.
2157 * Accumulation Clauses:: `collect', `sum', `maximize', etc.
2158 * Other Clauses:: `with', `if', `initially', `finally'
2161 @node Loop Basics, Loop Examples, Loop Facility, Loop Facility
2162 @subsection Loop Basics
2165 The @code{loop} macro essentially creates a mini-language within
2166 Lisp that is specially tailored for describing loops. While this
2167 language is a little strange-looking by the standards of regular Lisp,
2168 it turns out to be very easy to learn and well-suited to its purpose.
2170 Since @code{loop} is a macro, all parsing of the loop language
2171 takes place at byte-compile time; compiled @code{loop}s are just
2172 as efficient as the equivalent @code{while} loops written longhand.
2174 @defspec loop clauses@dots{}
2175 A loop construct consists of a series of @var{clause}s, each
2176 introduced by a symbol like @code{for} or @code{do}. Clauses
2177 are simply strung together in the argument list of @code{loop},
2178 with minimal extra parentheses. The various types of clauses
2179 specify initializations, such as the binding of temporary
2180 variables, actions to be taken in the loop, stepping actions,
2183 Common Lisp specifies a certain general order of clauses in a
2187 (loop @var{name-clause}
2188 @var{var-clauses}@dots{}
2189 @var{action-clauses}@dots{})
2192 The @var{name-clause} optionally gives a name to the implicit
2193 block that surrounds the loop. By default, the implicit block
2194 is named @code{nil}. The @var{var-clauses} specify what
2195 variables should be bound during the loop, and how they should
2196 be modified or iterated throughout the course of the loop. The
2197 @var{action-clauses} are things to be done during the loop, such
2198 as computing, collecting, and returning values.
2200 The Emacs version of the @code{loop} macro is less restrictive about
2201 the order of clauses, but things will behave most predictably if
2202 you put the variable-binding clauses @code{with}, @code{for}, and
2203 @code{repeat} before the action clauses. As in Common Lisp,
2204 @code{initially} and @code{finally} clauses can go anywhere.
2206 Loops generally return @code{nil} by default, but you can cause
2207 them to return a value by using an accumulation clause like
2208 @code{collect}, an end-test clause like @code{always}, or an
2209 explicit @code{return} clause to jump out of the implicit block.
2210 (Because the loop body is enclosed in an implicit block, you can
2211 also use regular Lisp @code{return} or @code{return-from} to
2212 break out of the loop.)
2215 The following sections give some examples of the Loop Macro in
2216 action, and describe the particular loop clauses in great detail.
2217 Consult the second edition of Steele's @dfn{Common Lisp, the Language},
2218 for additional discussion and examples of the @code{loop} macro.
2220 @node Loop Examples, For Clauses, Loop Basics, Loop Facility
2221 @subsection Loop Examples
2224 Before listing the full set of clauses that are allowed, let's
2225 look at a few example loops just to get a feel for the @code{loop}
2229 (loop for buf in (buffer-list)
2230 collect (buffer-file-name buf))
2234 This loop iterates over all Emacs buffers, using the list
2235 returned by @code{buffer-list}. For each buffer @code{buf},
2236 it calls @code{buffer-file-name} and collects the results into
2237 a list, which is then returned from the @code{loop} construct.
2238 The result is a list of the file names of all the buffers in
2239 Emacs' memory. The words @code{for}, @code{in}, and @code{collect}
2240 are reserved words in the @code{loop} language.
2243 (loop repeat 20 do (insert "Yowsa\n"))
2247 This loop inserts the phrase ``Yowsa'' twenty times in the
2251 (loop until (eobp) do (munch-line) (forward-line 1))
2255 This loop calls @code{munch-line} on every line until the end
2256 of the buffer. If point is already at the end of the buffer,
2257 the loop exits immediately.
2260 (loop do (munch-line) until (eobp) do (forward-line 1))
2264 This loop is similar to the above one, except that @code{munch-line}
2265 is always called at least once.
2268 (loop for x from 1 to 100
2271 finally return (list x (= y 729)))
2275 This more complicated loop searches for a number @code{x} whose
2276 square is 729. For safety's sake it only examines @code{x}
2277 values up to 100; dropping the phrase @samp{to 100} would
2278 cause the loop to count upwards with no limit. The second
2279 @code{for} clause defines @code{y} to be the square of @code{x}
2280 within the loop; the expression after the @code{=} sign is
2281 reevaluated each time through the loop. The @code{until}
2282 clause gives a condition for terminating the loop, and the
2283 @code{finally} clause says what to do when the loop finishes.
2284 (This particular example was written less concisely than it
2285 could have been, just for the sake of illustration.)
2287 Note that even though this loop contains three clauses (two
2288 @code{for}s and an @code{until}) that would have been enough to
2289 define loops all by themselves, it still creates a single loop
2290 rather than some sort of triple-nested loop. You must explicitly
2291 nest your @code{loop} constructs if you want nested loops.
2293 @node For Clauses, Iteration Clauses, Loop Examples, Loop Facility
2294 @subsection For Clauses
2297 Most loops are governed by one or more @code{for} clauses.
2298 A @code{for} clause simultaneously describes variables to be
2299 bound, how those variables are to be stepped during the loop,
2300 and usually an end condition based on those variables.
2302 The word @code{as} is a synonym for the word @code{for}. This
2303 word is followed by a variable name, then a word like @code{from}
2304 or @code{across} that describes the kind of iteration desired.
2305 In Common Lisp, the phrase @code{being the} sometimes precedes
2306 the type of iteration; in this package both @code{being} and
2307 @code{the} are optional. The word @code{each} is a synonym
2308 for @code{the}, and the word that follows it may be singular
2309 or plural: @samp{for x being the elements of y} or
2310 @samp{for x being each element of y}. Which form you use
2311 is purely a matter of style.
2313 The variable is bound around the loop as if by @code{let}:
2317 (loop for i from 1 to 10 do (do-something-with i))
2323 @item for @var{var} from @var{expr1} to @var{expr2} by @var{expr3}
2324 This type of @code{for} clause creates a counting loop. Each of
2325 the three sub-terms is optional, though there must be at least one
2326 term so that the clause is marked as a counting clause.
2328 The three expressions are the starting value, the ending value, and
2329 the step value, respectively, of the variable. The loop counts
2330 upwards by default (@var{expr3} must be positive), from @var{expr1}
2331 to @var{expr2} inclusively. If you omit the @code{from} term, the
2332 loop counts from zero; if you omit the @code{to} term, the loop
2333 counts forever without stopping (unless stopped by some other
2334 loop clause, of course); if you omit the @code{by} term, the loop
2335 counts in steps of one.
2337 You can replace the word @code{from} with @code{upfrom} or
2338 @code{downfrom} to indicate the direction of the loop. Likewise,
2339 you can replace @code{to} with @code{upto} or @code{downto}.
2340 For example, @samp{for x from 5 downto 1} executes five times
2341 with @code{x} taking on the integers from 5 down to 1 in turn.
2342 Also, you can replace @code{to} with @code{below} or @code{above},
2343 which are like @code{upto} and @code{downto} respectively except
2344 that they are exclusive rather than inclusive limits:
2347 (loop for x to 10 collect x)
2348 @result{} (0 1 2 3 4 5 6 7 8 9 10)
2349 (loop for x below 10 collect x)
2350 @result{} (0 1 2 3 4 5 6 7 8 9)
2353 The @code{by} value is always positive, even for downward-counting
2354 loops. Some sort of @code{from} value is required for downward
2355 loops; @samp{for x downto 5} is not a valid loop clause all by
2358 @item for @var{var} in @var{list} by @var{function}
2359 This clause iterates @var{var} over all the elements of @var{list},
2360 in turn. If you specify the @code{by} term, then @var{function}
2361 is used to traverse the list instead of @code{cdr}; it must be a
2362 function taking one argument. For example:
2365 (loop for x in '(1 2 3 4 5 6) collect (* x x))
2366 @result{} (1 4 9 16 25 36)
2367 (loop for x in '(1 2 3 4 5 6) by 'cddr collect (* x x))
2371 @item for @var{var} on @var{list} by @var{function}
2372 This clause iterates @var{var} over all the cons cells of @var{list}.
2375 (loop for x on '(1 2 3 4) collect x)
2376 @result{} ((1 2 3 4) (2 3 4) (3 4) (4))
2379 With @code{by}, there is no real reason that the @code{on} expression
2380 must be a list. For example:
2383 (loop for x on first-animal by 'next-animal collect x)
2387 where @code{(next-animal x)} takes an ``animal'' @var{x} and returns
2388 the next in the (assumed) sequence of animals, or @code{nil} if
2389 @var{x} was the last animal in the sequence.
2391 @item for @var{var} in-ref @var{list} by @var{function}
2392 This is like a regular @code{in} clause, but @var{var} becomes
2393 a @code{setf}-able ``reference'' onto the elements of the list
2394 rather than just a temporary variable. For example,
2397 (loop for x in-ref my-list do (incf x))
2401 increments every element of @code{my-list} in place. This clause
2402 is an extension to standard Common Lisp.
2404 @item for @var{var} across @var{array}
2405 This clause iterates @var{var} over all the elements of @var{array},
2406 which may be a vector or a string.
2409 (loop for x across "aeiou"
2410 do (use-vowel (char-to-string x)))
2413 @item for @var{var} across-ref @var{array}
2414 This clause iterates over an array, with @var{var} a @code{setf}-able
2415 reference onto the elements; see @code{in-ref} above.
2417 @item for @var{var} being the elements of @var{sequence}
2418 This clause iterates over the elements of @var{sequence}, which may
2419 be a list, vector, or string. Since the type must be determined
2420 at run-time, this is somewhat less efficient than @code{in} or
2421 @code{across}. The clause may be followed by the additional term
2422 @samp{using (index @var{var2})} to cause @var{var2} to be bound to
2423 the successive indices (starting at 0) of the elements.
2425 This clause type is taken from older versions of the @code{loop} macro,
2426 and is not present in modern Common Lisp. The @samp{using (sequence ...)}
2427 term of the older macros is not supported.
2429 @item for @var{var} being the elements of-ref @var{sequence}
2430 This clause iterates over a sequence, with @var{var} a @code{setf}-able
2431 reference onto the elements; see @code{in-ref} above.
2433 @item for @var{var} being the symbols [of @var{obarray}]
2434 This clause iterates over symbols, either over all interned symbols
2435 or over all symbols in @var{obarray}. The loop is executed with
2436 @var{var} bound to each symbol in turn. The symbols are visited in
2437 an unspecified order.
2442 (loop for sym being the symbols
2444 when (string-match "^map" (symbol-name sym))
2449 returns a list of all the functions whose names begin with @samp{map}.
2451 The Common Lisp words @code{external-symbols} and @code{present-symbols}
2452 are also recognized but are equivalent to @code{symbols} in Emacs Lisp.
2454 Due to a minor implementation restriction, it will not work to have
2455 more than one @code{for} clause iterating over symbols, hash tables,
2456 keymaps, overlays, or intervals in a given @code{loop}. Fortunately,
2457 it would rarely if ever be useful to do so. It @emph{is} valid to mix
2458 one of these types of clauses with other clauses like @code{for ... to}
2461 @item for @var{var} being the hash-keys of @var{hash-table}
2462 This clause iterates over the entries in @var{hash-table}. For each
2463 hash table entry, @var{var} is bound to the entry's key. If you write
2464 @samp{the hash-values} instead, @var{var} is bound to the values
2465 of the entries. The clause may be followed by the additional
2466 term @samp{using (hash-values @var{var2})} (where @code{hash-values}
2467 is the opposite word of the word following @code{the}) to cause
2468 @var{var} and @var{var2} to be bound to the two parts of each
2471 @item for @var{var} being the key-codes of @var{keymap}
2472 This clause iterates over the entries in @var{keymap}.
2473 The iteration does not enter nested keymaps but does enter inherited
2475 You can use @samp{the key-bindings} to access the commands bound to
2476 the keys rather than the key codes, and you can add a @code{using}
2477 clause to access both the codes and the bindings together.
2479 @item for @var{var} being the key-seqs of @var{keymap}
2480 This clause iterates over all key sequences defined by @var{keymap}
2481 and its nested keymaps, where @var{var} takes on values which are
2482 vectors. The strings or vectors
2483 are reused for each iteration, so you must copy them if you wish to keep
2484 them permanently. You can add a @samp{using (key-bindings ...)}
2485 clause to get the command bindings as well.
2487 @item for @var{var} being the overlays [of @var{buffer}] @dots{}
2488 This clause iterates over the ``overlays'' of a buffer
2489 (the clause @code{extents} is synonymous
2490 with @code{overlays}). If the @code{of} term is omitted, the current
2492 This clause also accepts optional @samp{from @var{pos}} and
2493 @samp{to @var{pos}} terms, limiting the clause to overlays which
2494 overlap the specified region.
2496 @item for @var{var} being the intervals [of @var{buffer}] @dots{}
2497 This clause iterates over all intervals of a buffer with constant
2498 text properties. The variable @var{var} will be bound to conses
2499 of start and end positions, where one start position is always equal
2500 to the previous end position. The clause allows @code{of},
2501 @code{from}, @code{to}, and @code{property} terms, where the latter
2502 term restricts the search to just the specified property. The
2503 @code{of} term may specify either a buffer or a string.
2505 @item for @var{var} being the frames
2506 This clause iterates over all frames, i.e., X window system windows
2507 open on Emacs files. The
2508 clause @code{screens} is a synonym for @code{frames}. The frames
2509 are visited in @code{next-frame} order starting from
2510 @code{selected-frame}.
2512 @item for @var{var} being the windows [of @var{frame}]
2513 This clause iterates over the windows (in the Emacs sense) of
2514 the current frame, or of the specified @var{frame}.
2516 @item for @var{var} being the buffers
2517 This clause iterates over all buffers in Emacs. It is equivalent
2518 to @samp{for @var{var} in (buffer-list)}.
2520 @item for @var{var} = @var{expr1} then @var{expr2}
2521 This clause does a general iteration. The first time through
2522 the loop, @var{var} will be bound to @var{expr1}. On the second
2523 and successive iterations it will be set by evaluating @var{expr2}
2524 (which may refer to the old value of @var{var}). For example,
2525 these two loops are effectively the same:
2528 (loop for x on my-list by 'cddr do ...)
2529 (loop for x = my-list then (cddr x) while x do ...)
2532 Note that this type of @code{for} clause does not imply any sort
2533 of terminating condition; the above example combines it with a
2534 @code{while} clause to tell when to end the loop.
2536 If you omit the @code{then} term, @var{expr1} is used both for
2537 the initial setting and for successive settings:
2540 (loop for x = (random) when (> x 0) return x)
2544 This loop keeps taking random numbers from the @code{(random)}
2545 function until it gets a positive one, which it then returns.
2548 If you include several @code{for} clauses in a row, they are
2549 treated sequentially (as if by @code{let*} and @code{setq}).
2550 You can instead use the word @code{and} to link the clauses,
2551 in which case they are processed in parallel (as if by @code{let}
2555 (loop for x below 5 for y = nil then x collect (list x y))
2556 @result{} ((0 nil) (1 1) (2 2) (3 3) (4 4))
2557 (loop for x below 5 and y = nil then x collect (list x y))
2558 @result{} ((0 nil) (1 0) (2 1) (3 2) (4 3))
2562 In the first loop, @code{y} is set based on the value of @code{x}
2563 that was just set by the previous clause; in the second loop,
2564 @code{x} and @code{y} are set simultaneously so @code{y} is set
2565 based on the value of @code{x} left over from the previous time
2568 Another feature of the @code{loop} macro is @dfn{destructuring},
2569 similar in concept to the destructuring provided by @code{defmacro}.
2570 The @var{var} part of any @code{for} clause can be given as a list
2571 of variables instead of a single variable. The values produced
2572 during loop execution must be lists; the values in the lists are
2573 stored in the corresponding variables.
2576 (loop for (x y) in '((2 3) (4 5) (6 7)) collect (+ x y))
2580 In loop destructuring, if there are more values than variables
2581 the trailing values are ignored, and if there are more variables
2582 than values the trailing variables get the value @code{nil}.
2583 If @code{nil} is used as a variable name, the corresponding
2584 values are ignored. Destructuring may be nested, and dotted
2585 lists of variables like @code{(x . y)} are allowed.
2587 @node Iteration Clauses, Accumulation Clauses, For Clauses, Loop Facility
2588 @subsection Iteration Clauses
2591 Aside from @code{for} clauses, there are several other loop clauses
2592 that control the way the loop operates. They might be used by
2593 themselves, or in conjunction with one or more @code{for} clauses.
2596 @item repeat @var{integer}
2597 This clause simply counts up to the specified number using an
2598 internal temporary variable. The loops
2601 (loop repeat (1+ n) do ...)
2602 (loop for temp to n do ...)
2606 are identical except that the second one forces you to choose
2607 a name for a variable you aren't actually going to use.
2609 @item while @var{condition}
2610 This clause stops the loop when the specified condition (any Lisp
2611 expression) becomes @code{nil}. For example, the following two
2612 loops are equivalent, except for the implicit @code{nil} block
2613 that surrounds the second one:
2616 (while @var{cond} @var{forms}@dots{})
2617 (loop while @var{cond} do @var{forms}@dots{})
2620 @item until @var{condition}
2621 This clause stops the loop when the specified condition is true,
2622 i.e., non-@code{nil}.
2624 @item always @var{condition}
2625 This clause stops the loop when the specified condition is @code{nil}.
2626 Unlike @code{while}, it stops the loop using @code{return nil} so that
2627 the @code{finally} clauses are not executed. If all the conditions
2628 were non-@code{nil}, the loop returns @code{t}:
2631 (if (loop for size in size-list always (> size 10))
2636 @item never @var{condition}
2637 This clause is like @code{always}, except that the loop returns
2638 @code{t} if any conditions were false, or @code{nil} otherwise.
2640 @item thereis @var{condition}
2641 This clause stops the loop when the specified form is non-@code{nil};
2642 in this case, it returns that non-@code{nil} value. If all the
2643 values were @code{nil}, the loop returns @code{nil}.
2646 @node Accumulation Clauses, Other Clauses, Iteration Clauses, Loop Facility
2647 @subsection Accumulation Clauses
2650 These clauses cause the loop to accumulate information about the
2651 specified Lisp @var{form}. The accumulated result is returned
2652 from the loop unless overridden, say, by a @code{return} clause.
2655 @item collect @var{form}
2656 This clause collects the values of @var{form} into a list. Several
2657 examples of @code{collect} appear elsewhere in this manual.
2659 The word @code{collecting} is a synonym for @code{collect}, and
2660 likewise for the other accumulation clauses.
2662 @item append @var{form}
2663 This clause collects lists of values into a result list using
2666 @item nconc @var{form}
2667 This clause collects lists of values into a result list by
2668 destructively modifying the lists rather than copying them.
2670 @item concat @var{form}
2671 This clause concatenates the values of the specified @var{form}
2672 into a string. (It and the following clause are extensions to
2673 standard Common Lisp.)
2675 @item vconcat @var{form}
2676 This clause concatenates the values of the specified @var{form}
2679 @item count @var{form}
2680 This clause counts the number of times the specified @var{form}
2681 evaluates to a non-@code{nil} value.
2683 @item sum @var{form}
2684 This clause accumulates the sum of the values of the specified
2685 @var{form}, which must evaluate to a number.
2687 @item maximize @var{form}
2688 This clause accumulates the maximum value of the specified @var{form},
2689 which must evaluate to a number. The return value is undefined if
2690 @code{maximize} is executed zero times.
2692 @item minimize @var{form}
2693 This clause accumulates the minimum value of the specified @var{form}.
2696 Accumulation clauses can be followed by @samp{into @var{var}} to
2697 cause the data to be collected into variable @var{var} (which is
2698 automatically @code{let}-bound during the loop) rather than an
2699 unnamed temporary variable. Also, @code{into} accumulations do
2700 not automatically imply a return value. The loop must use some
2701 explicit mechanism, such as @code{finally return}, to return
2702 the accumulated result.
2704 It is valid for several accumulation clauses of the same type to
2705 accumulate into the same place. From Steele:
2708 (loop for name in '(fred sue alice joe june)
2709 for kids in '((bob ken) () () (kris sunshine) ())
2712 @result{} (fred bob ken sue alice joe kris sunshine june)
2715 @node Other Clauses, , Accumulation Clauses, Loop Facility
2716 @subsection Other Clauses
2719 This section describes the remaining loop clauses.
2722 @item with @var{var} = @var{value}
2723 This clause binds a variable to a value around the loop, but
2724 otherwise leaves the variable alone during the loop. The following
2725 loops are basically equivalent:
2728 (loop with x = 17 do ...)
2729 (let ((x 17)) (loop do ...))
2730 (loop for x = 17 then x do ...)
2733 Naturally, the variable @var{var} might be used for some purpose
2734 in the rest of the loop. For example:
2737 (loop for x in my-list with res = nil do (push x res)
2741 This loop inserts the elements of @code{my-list} at the front of
2742 a new list being accumulated in @code{res}, then returns the
2743 list @code{res} at the end of the loop. The effect is similar
2744 to that of a @code{collect} clause, but the list gets reversed
2745 by virtue of the fact that elements are being pushed onto the
2746 front of @code{res} rather than the end.
2748 If you omit the @code{=} term, the variable is initialized to
2749 @code{nil}. (Thus the @samp{= nil} in the above example is
2752 Bindings made by @code{with} are sequential by default, as if
2753 by @code{let*}. Just like @code{for} clauses, @code{with} clauses
2754 can be linked with @code{and} to cause the bindings to be made by
2757 @item if @var{condition} @var{clause}
2758 This clause executes the following loop clause only if the specified
2759 condition is true. The following @var{clause} should be an accumulation,
2760 @code{do}, @code{return}, @code{if}, or @code{unless} clause.
2761 Several clauses may be linked by separating them with @code{and}.
2762 These clauses may be followed by @code{else} and a clause or clauses
2763 to execute if the condition was false. The whole construct may
2764 optionally be followed by the word @code{end} (which may be used to
2765 disambiguate an @code{else} or @code{and} in a nested @code{if}).
2767 The actual non-@code{nil} value of the condition form is available
2768 by the name @code{it} in the ``then'' part. For example:
2771 (setq funny-numbers '(6 13 -1))
2773 (loop for x below 10
2776 and if (memq x funny-numbers) return (cdr it) end
2778 collect x into evens
2779 finally return (vector odds evens))
2780 @result{} [(1 3 5 7 9) (0 2 4 6 8)]
2781 (setq funny-numbers '(6 7 13 -1))
2782 @result{} (6 7 13 -1)
2783 (loop <@r{same thing again}>)
2787 Note the use of @code{and} to put two clauses into the ``then''
2788 part, one of which is itself an @code{if} clause. Note also that
2789 @code{end}, while normally optional, was necessary here to make
2790 it clear that the @code{else} refers to the outermost @code{if}
2791 clause. In the first case, the loop returns a vector of lists
2792 of the odd and even values of @var{x}. In the second case, the
2793 odd number 7 is one of the @code{funny-numbers} so the loop
2794 returns early; the actual returned value is based on the result
2795 of the @code{memq} call.
2797 @item when @var{condition} @var{clause}
2798 This clause is just a synonym for @code{if}.
2800 @item unless @var{condition} @var{clause}
2801 The @code{unless} clause is just like @code{if} except that the
2802 sense of the condition is reversed.
2804 @item named @var{name}
2805 This clause gives a name other than @code{nil} to the implicit
2806 block surrounding the loop. The @var{name} is the symbol to be
2807 used as the block name.
2809 @item initially [do] @var{forms}...
2810 This keyword introduces one or more Lisp forms which will be
2811 executed before the loop itself begins (but after any variables
2812 requested by @code{for} or @code{with} have been bound to their
2813 initial values). @code{initially} clauses can appear anywhere;
2814 if there are several, they are executed in the order they appear
2815 in the loop. The keyword @code{do} is optional.
2817 @item finally [do] @var{forms}...
2818 This introduces Lisp forms which will be executed after the loop
2819 finishes (say, on request of a @code{for} or @code{while}).
2820 @code{initially} and @code{finally} clauses may appear anywhere
2821 in the loop construct, but they are executed (in the specified
2822 order) at the beginning or end, respectively, of the loop.
2824 @item finally return @var{form}
2825 This says that @var{form} should be executed after the loop
2826 is done to obtain a return value. (Without this, or some other
2827 clause like @code{collect} or @code{return}, the loop will simply
2828 return @code{nil}.) Variables bound by @code{for}, @code{with},
2829 or @code{into} will still contain their final values when @var{form}
2832 @item do @var{forms}...
2833 The word @code{do} may be followed by any number of Lisp expressions
2834 which are executed as an implicit @code{progn} in the body of the
2835 loop. Many of the examples in this section illustrate the use of
2838 @item return @var{form}
2839 This clause causes the loop to return immediately. The following
2840 Lisp form is evaluated to give the return value of the @code{loop}
2841 form. The @code{finally} clauses, if any, are not executed.
2842 Of course, @code{return} is generally used inside an @code{if} or
2843 @code{unless}, as its use in a top-level loop clause would mean
2844 the loop would never get to ``loop'' more than once.
2846 The clause @samp{return @var{form}} is equivalent to
2847 @samp{do (return @var{form})} (or @code{return-from} if the loop
2848 was named). The @code{return} clause is implemented a bit more
2849 efficiently, though.
2852 While there is no high-level way to add user extensions to @code{loop}
2853 (comparable to @code{defsetf} for @code{setf}, say), this package
2854 does offer two properties called @code{cl-loop-handler} and
2855 @code{cl-loop-for-handler} which are functions to be called when
2856 a given symbol is encountered as a top-level loop clause or
2857 @code{for} clause, respectively. Consult the source code in
2858 file @file{cl-macs.el} for details.
2860 This package's @code{loop} macro is compatible with that of Common
2861 Lisp, except that a few features are not implemented: @code{loop-finish}
2862 and data-type specifiers. Naturally, the @code{for} clauses which
2863 iterate over keymaps, overlays, intervals, frames, windows, and
2864 buffers are Emacs-specific extensions.
2866 @node Multiple Values, , Loop Facility, Control Structure
2867 @section Multiple Values
2870 Common Lisp functions can return zero or more results. Emacs Lisp
2871 functions, by contrast, always return exactly one result. This
2872 package makes no attempt to emulate Common Lisp multiple return
2873 values; Emacs versions of Common Lisp functions that return more
2874 than one value either return just the first value (as in
2875 @code{compiler-macroexpand}) or return a list of values (as in
2876 @code{get-setf-method}). This package @emph{does} define placeholders
2877 for the Common Lisp functions that work with multiple values, but
2878 in Emacs Lisp these functions simply operate on lists instead.
2879 The @code{values} form, for example, is a synonym for @code{list}
2882 @defspec multiple-value-bind (var@dots{}) values-form forms@dots{}
2883 This form evaluates @var{values-form}, which must return a list of
2884 values. It then binds the @var{var}s to these respective values,
2885 as if by @code{let}, and then executes the body @var{forms}.
2886 If there are more @var{var}s than values, the extra @var{var}s
2887 are bound to @code{nil}. If there are fewer @var{var}s than
2888 values, the excess values are ignored.
2891 @defspec multiple-value-setq (var@dots{}) form
2892 This form evaluates @var{form}, which must return a list of values.
2893 It then sets the @var{var}s to these respective values, as if by
2894 @code{setq}. Extra @var{var}s or values are treated the same as
2895 in @code{multiple-value-bind}.
2898 The older Quiroz package attempted a more faithful (but still
2899 imperfect) emulation of Common Lisp multiple values. The old
2900 method ``usually'' simulated true multiple values quite well,
2901 but under certain circumstances would leave spurious return
2902 values in memory where a later, unrelated @code{multiple-value-bind}
2903 form would see them.
2905 Since a perfect emulation is not feasible in Emacs Lisp, this
2906 package opts to keep it as simple and predictable as possible.
2908 @node Macros, Declarations, Control Structure, Top
2912 This package implements the various Common Lisp features of
2913 @code{defmacro}, such as destructuring, @code{&environment},
2914 and @code{&body}. Top-level @code{&whole} is not implemented
2915 for @code{defmacro} due to technical difficulties.
2916 @xref{Argument Lists}.
2918 Destructuring is made available to the user by way of the
2921 @defspec destructuring-bind arglist expr forms@dots{}
2922 This macro expands to code which executes @var{forms}, with
2923 the variables in @var{arglist} bound to the list of values
2924 returned by @var{expr}. The @var{arglist} can include all
2925 the features allowed for @code{defmacro} argument lists,
2926 including destructuring. (The @code{&environment} keyword
2927 is not allowed.) The macro expansion will signal an error
2928 if @var{expr} returns a list of the wrong number of arguments
2929 or with incorrect keyword arguments.
2932 This package also includes the Common Lisp @code{define-compiler-macro}
2933 facility, which allows you to define compile-time expansions and
2934 optimizations for your functions.
2936 @defspec define-compiler-macro name arglist forms@dots{}
2937 This form is similar to @code{defmacro}, except that it only expands
2938 calls to @var{name} at compile-time; calls processed by the Lisp
2939 interpreter are not expanded, nor are they expanded by the
2940 @code{macroexpand} function.
2942 The argument list may begin with a @code{&whole} keyword and a
2943 variable. This variable is bound to the macro-call form itself,
2944 i.e., to a list of the form @samp{(@var{name} @var{args}@dots{})}.
2945 If the macro expander returns this form unchanged, then the
2946 compiler treats it as a normal function call. This allows
2947 compiler macros to work as optimizers for special cases of a
2948 function, leaving complicated cases alone.
2950 For example, here is a simplified version of a definition that
2951 appears as a standard part of this package:
2954 (define-compiler-macro member* (&whole form a list &rest keys)
2955 (if (and (null keys)
2956 (eq (car-safe a) 'quote)
2957 (not (floatp-safe (cadr a))))
2963 This definition causes @code{(member* @var{a} @var{list})} to change
2964 to a call to the faster @code{memq} in the common case where @var{a}
2965 is a non-floating-point constant; if @var{a} is anything else, or
2966 if there are any keyword arguments in the call, then the original
2967 @code{member*} call is left intact. (The actual compiler macro
2968 for @code{member*} optimizes a number of other cases, including
2969 common @code{:test} predicates.)
2972 @defun compiler-macroexpand form
2973 This function is analogous to @code{macroexpand}, except that it
2974 expands compiler macros rather than regular macros. It returns
2975 @var{form} unchanged if it is not a call to a function for which
2976 a compiler macro has been defined, or if that compiler macro
2977 decided to punt by returning its @code{&whole} argument. Like
2978 @code{macroexpand}, it expands repeatedly until it reaches a form
2979 for which no further expansion is possible.
2982 @xref{Macro Bindings}, for descriptions of the @code{macrolet}
2983 and @code{symbol-macrolet} forms for making ``local'' macro
2986 @node Declarations, Symbols, Macros, Top
2987 @chapter Declarations
2990 Common Lisp includes a complex and powerful ``declaration''
2991 mechanism that allows you to give the compiler special hints
2992 about the types of data that will be stored in particular variables,
2993 and about the ways those variables and functions will be used. This
2994 package defines versions of all the Common Lisp declaration forms:
2995 @code{declare}, @code{locally}, @code{proclaim}, @code{declaim},
2998 Most of the Common Lisp declarations are not currently useful in
2999 Emacs Lisp, as the byte-code system provides little opportunity
3000 to benefit from type information, and @code{special} declarations
3001 are redundant in a fully dynamically-scoped Lisp. A few
3002 declarations are meaningful when the optimizing byte
3003 compiler is being used, however. Under the earlier non-optimizing
3004 compiler, these declarations will effectively be ignored.
3006 @defun proclaim decl-spec
3007 This function records a ``global'' declaration specified by
3008 @var{decl-spec}. Since @code{proclaim} is a function, @var{decl-spec}
3009 is evaluated and thus should normally be quoted.
3012 @defspec declaim decl-specs@dots{}
3013 This macro is like @code{proclaim}, except that it takes any number
3014 of @var{decl-spec} arguments, and the arguments are unevaluated and
3015 unquoted. The @code{declaim} macro also puts an @code{(eval-when
3016 (compile load eval) ...)} around the declarations so that they will
3017 be registered at compile-time as well as at run-time. (This is vital,
3018 since normally the declarations are meant to influence the way the
3019 compiler treats the rest of the file that contains the @code{declaim}
3023 @defspec declare decl-specs@dots{}
3024 This macro is used to make declarations within functions and other
3025 code. Common Lisp allows declarations in various locations, generally
3026 at the beginning of any of the many ``implicit @code{progn}s''
3027 throughout Lisp syntax, such as function bodies, @code{let} bodies,
3028 etc. Currently the only declaration understood by @code{declare}
3032 @defspec locally declarations@dots{} forms@dots{}
3033 In this package, @code{locally} is no different from @code{progn}.
3036 @defspec the type form
3037 Type information provided by @code{the} is ignored in this package;
3038 in other words, @code{(the @var{type} @var{form})} is equivalent
3039 to @var{form}. Future versions of the optimizing byte-compiler may
3040 make use of this information.
3042 For example, @code{mapcar} can map over both lists and arrays. It is
3043 hard for the compiler to expand @code{mapcar} into an in-line loop
3044 unless it knows whether the sequence will be a list or an array ahead
3045 of time. With @code{(mapcar 'car (the vector foo))}, a future
3046 compiler would have enough information to expand the loop in-line.
3047 For now, Emacs Lisp will treat the above code as exactly equivalent
3048 to @code{(mapcar 'car foo)}.
3051 Each @var{decl-spec} in a @code{proclaim}, @code{declaim}, or
3052 @code{declare} should be a list beginning with a symbol that says
3053 what kind of declaration it is. This package currently understands
3054 @code{special}, @code{inline}, @code{notinline}, @code{optimize},
3055 and @code{warn} declarations. (The @code{warn} declaration is an
3056 extension of standard Common Lisp.) Other Common Lisp declarations,
3057 such as @code{type} and @code{ftype}, are silently ignored.
3061 Since all variables in Emacs Lisp are ``special'' (in the Common
3062 Lisp sense), @code{special} declarations are only advisory. They
3063 simply tell the optimizing byte compiler that the specified
3064 variables are intentionally being referred to without being
3065 bound in the body of the function. The compiler normally emits
3066 warnings for such references, since they could be typographical
3067 errors for references to local variables.
3069 The declaration @code{(declare (special @var{var1} @var{var2}))} is
3070 equivalent to @code{(defvar @var{var1}) (defvar @var{var2})} in the
3071 optimizing compiler, or to nothing at all in older compilers (which
3072 do not warn for non-local references).
3074 In top-level contexts, it is generally better to write
3075 @code{(defvar @var{var})} than @code{(declaim (special @var{var}))},
3076 since @code{defvar} makes your intentions clearer. But the older
3077 byte compilers can not handle @code{defvar}s appearing inside of
3078 functions, while @code{(declare (special @var{var}))} takes care
3079 to work correctly with all compilers.
3082 The @code{inline} @var{decl-spec} lists one or more functions
3083 whose bodies should be expanded ``in-line'' into calling functions
3084 whenever the compiler is able to arrange for it. For example,
3085 the Common Lisp function @code{cadr} is declared @code{inline}
3086 by this package so that the form @code{(cadr @var{x})} will
3087 expand directly into @code{(car (cdr @var{x}))} when it is called
3088 in user functions, for a savings of one (relatively expensive)
3091 The following declarations are all equivalent. Note that the
3092 @code{defsubst} form is a convenient way to define a function
3093 and declare it inline all at once.
3096 (declaim (inline foo bar))
3097 (eval-when (compile load eval) (proclaim '(inline foo bar)))
3098 (defsubst foo (...) ...) ; instead of defun
3101 @strong{Please note:} this declaration remains in effect after the
3102 containing source file is done. It is correct to use it to
3103 request that a function you have defined should be inlined,
3104 but it is impolite to use it to request inlining of an external
3107 In Common Lisp, it is possible to use @code{(declare (inline @dots{}))}
3108 before a particular call to a function to cause just that call to
3109 be inlined; the current byte compilers provide no way to implement
3110 this, so @code{(declare (inline @dots{}))} is currently ignored by
3114 The @code{notinline} declaration lists functions which should
3115 not be inlined after all; it cancels a previous @code{inline}
3119 This declaration controls how much optimization is performed by
3120 the compiler. Naturally, it is ignored by the earlier non-optimizing
3123 The word @code{optimize} is followed by any number of lists like
3124 @code{(speed 3)} or @code{(safety 2)}. Common Lisp defines several
3125 optimization ``qualities''; this package ignores all but @code{speed}
3126 and @code{safety}. The value of a quality should be an integer from
3127 0 to 3, with 0 meaning ``unimportant'' and 3 meaning ``very important.''
3128 The default level for both qualities is 1.
3130 In this package, with the optimizing compiler, the
3131 @code{speed} quality is tied to the @code{byte-compile-optimize}
3132 flag, which is set to @code{nil} for @code{(speed 0)} and to
3133 @code{t} for higher settings; and the @code{safety} quality is
3134 tied to the @code{byte-compile-delete-errors} flag, which is
3135 set to @code{t} for @code{(safety 3)} and to @code{nil} for all
3136 lower settings. (The latter flag controls whether the compiler
3137 is allowed to optimize out code whose only side-effect could
3138 be to signal an error, e.g., rewriting @code{(progn foo bar)} to
3139 @code{bar} when it is not known whether @code{foo} will be bound
3142 Note that even compiling with @code{(safety 0)}, the Emacs
3143 byte-code system provides sufficient checking to prevent real
3144 harm from being done. For example, barring serious bugs in
3145 Emacs itself, Emacs will not crash with a segmentation fault
3146 just because of an error in a fully-optimized Lisp program.
3148 The @code{optimize} declaration is normally used in a top-level
3149 @code{proclaim} or @code{declaim} in a file; Common Lisp allows
3150 it to be used with @code{declare} to set the level of optimization
3151 locally for a given form, but this will not work correctly with the
3152 current version of the optimizing compiler. (The @code{declare}
3153 will set the new optimization level, but that level will not
3154 automatically be unset after the enclosing form is done.)
3157 This declaration controls what sorts of warnings are generated
3158 by the byte compiler. Again, only the optimizing compiler
3159 generates warnings. The word @code{warn} is followed by any
3160 number of ``warning qualities,'' similar in form to optimization
3161 qualities. The currently supported warning types are
3162 @code{redefine}, @code{callargs}, @code{unresolved}, and
3163 @code{free-vars}; in the current system, a value of 0 will
3164 disable these warnings and any higher value will enable them.
3165 See the documentation for the optimizing byte compiler for details.
3168 @node Symbols, Numbers, Declarations, Top
3172 This package defines several symbol-related features that were
3173 missing from Emacs Lisp.
3176 * Property Lists:: `get*', `remprop', `getf', `remf'
3177 * Creating Symbols:: `gensym', `gentemp'
3180 @node Property Lists, Creating Symbols, Symbols, Symbols
3181 @section Property Lists
3184 These functions augment the standard Emacs Lisp functions @code{get}
3185 and @code{put} for operating on properties attached to symbols.
3186 There are also functions for working with property lists as
3187 first-class data structures not attached to particular symbols.
3189 @defun get* symbol property &optional default
3190 This function is like @code{get}, except that if the property is
3191 not found, the @var{default} argument provides the return value.
3192 (The Emacs Lisp @code{get} function always uses @code{nil} as
3193 the default; this package's @code{get*} is equivalent to Common
3196 The @code{get*} function is @code{setf}-able; when used in this
3197 fashion, the @var{default} argument is allowed but ignored.
3200 @defun remprop symbol property
3201 This function removes the entry for @var{property} from the property
3202 list of @var{symbol}. It returns a true value if the property was
3203 indeed found and removed, or @code{nil} if there was no such property.
3204 (This function was probably omitted from Emacs originally because,
3205 since @code{get} did not allow a @var{default}, it was very difficult
3206 to distinguish between a missing property and a property whose value
3207 was @code{nil}; thus, setting a property to @code{nil} was close
3208 enough to @code{remprop} for most purposes.)
3211 @defun getf place property &optional default
3212 This function scans the list @var{place} as if it were a property
3213 list, i.e., a list of alternating property names and values. If
3214 an even-numbered element of @var{place} is found which is @code{eq}
3215 to @var{property}, the following odd-numbered element is returned.
3216 Otherwise, @var{default} is returned (or @code{nil} if no default
3222 (get sym prop) @equiv{} (getf (symbol-plist sym) prop)
3225 It is valid to use @code{getf} as a @code{setf} place, in which case
3226 its @var{place} argument must itself be a valid @code{setf} place.
3227 The @var{default} argument, if any, is ignored in this context.
3228 The effect is to change (via @code{setcar}) the value cell in the
3229 list that corresponds to @var{property}, or to cons a new property-value
3230 pair onto the list if the property is not yet present.
3233 (put sym prop val) @equiv{} (setf (getf (symbol-plist sym) prop) val)
3236 The @code{get} and @code{get*} functions are also @code{setf}-able.
3237 The fact that @code{default} is ignored can sometimes be useful:
3240 (incf (get* 'foo 'usage-count 0))
3243 Here, symbol @code{foo}'s @code{usage-count} property is incremented
3244 if it exists, or set to 1 (an incremented 0) otherwise.
3246 When not used as a @code{setf} form, @code{getf} is just a regular
3247 function and its @var{place} argument can actually be any Lisp
3251 @defspec remf place property
3252 This macro removes the property-value pair for @var{property} from
3253 the property list stored at @var{place}, which is any @code{setf}-able
3254 place expression. It returns true if the property was found. Note
3255 that if @var{property} happens to be first on the list, this will
3256 effectively do a @code{(setf @var{place} (cddr @var{place}))},
3257 whereas if it occurs later, this simply uses @code{setcdr} to splice
3258 out the property and value cells.
3265 @node Creating Symbols, , Property Lists, Symbols
3266 @section Creating Symbols
3269 These functions create unique symbols, typically for use as
3270 temporary variables.
3272 @defun gensym &optional x
3273 This function creates a new, uninterned symbol (using @code{make-symbol})
3274 with a unique name. (The name of an uninterned symbol is relevant
3275 only if the symbol is printed.) By default, the name is generated
3276 from an increasing sequence of numbers, @samp{G1000}, @samp{G1001},
3277 @samp{G1002}, etc. If the optional argument @var{x} is a string, that
3278 string is used as a prefix instead of @samp{G}. Uninterned symbols
3279 are used in macro expansions for temporary variables, to ensure that
3280 their names will not conflict with ``real'' variables in the user's
3284 @defvar *gensym-counter*
3285 This variable holds the counter used to generate @code{gensym} names.
3286 It is incremented after each use by @code{gensym}. In Common Lisp
3287 this is initialized with 0, but this package initializes it with a
3288 random (time-dependent) value to avoid trouble when two files that
3289 each used @code{gensym} in their compilation are loaded together.
3290 (Uninterned symbols become interned when the compiler writes them
3291 out to a file and the Emacs loader loads them, so their names have to
3292 be treated a bit more carefully than in Common Lisp where uninterned
3293 symbols remain uninterned after loading.)
3296 @defun gentemp &optional x
3297 This function is like @code{gensym}, except that it produces a new
3298 @emph{interned} symbol. If the symbol that is generated already
3299 exists, the function keeps incrementing the counter and trying
3300 again until a new symbol is generated.
3303 The Quiroz @file{cl.el} package also defined a @code{defkeyword}
3304 form for creating self-quoting keyword symbols. This package
3305 automatically creates all keywords that are called for by
3306 @code{&key} argument specifiers, and discourages the use of
3307 keywords as data unrelated to keyword arguments, so the
3308 @code{defkeyword} form has been discontinued.
3314 @node Numbers, Sequences, Symbols, Top
3318 This section defines a few simple Common Lisp operations on numbers
3319 which were left out of Emacs Lisp.
3322 * Predicates on Numbers:: `plusp', `oddp', `floatp-safe', etc.
3323 * Numerical Functions:: `abs', `floor*', etc.
3324 * Random Numbers:: `random*', `make-random-state'
3325 * Implementation Parameters:: `most-positive-float'
3332 @node Predicates on Numbers, Numerical Functions, Numbers, Numbers
3333 @section Predicates on Numbers
3336 These functions return @code{t} if the specified condition is
3337 true of the numerical argument, or @code{nil} otherwise.
3340 This predicate tests whether @var{number} is positive. It is an
3341 error if the argument is not a number.
3344 @defun minusp number
3345 This predicate tests whether @var{number} is negative. It is an
3346 error if the argument is not a number.
3350 This predicate tests whether @var{integer} is odd. It is an
3351 error if the argument is not an integer.
3354 @defun evenp integer
3355 This predicate tests whether @var{integer} is even. It is an
3356 error if the argument is not an integer.
3359 @defun floatp-safe object
3360 This predicate tests whether @var{object} is a floating-point
3361 number. On systems that support floating-point, this is equivalent
3362 to @code{floatp}. On other systems, this always returns @code{nil}.
3369 @node Numerical Functions, Random Numbers, Predicates on Numbers, Numbers
3370 @section Numerical Functions
3373 These functions perform various arithmetic operations on numbers.
3375 @defun gcd &rest integers
3376 This function returns the Greatest Common Divisor of the arguments.
3377 For one argument, it returns the absolute value of that argument.
3378 For zero arguments, it returns zero.
3381 @defun lcm &rest integers
3382 This function returns the Least Common Multiple of the arguments.
3383 For one argument, it returns the absolute value of that argument.
3384 For zero arguments, it returns one.
3387 @defun isqrt integer
3388 This function computes the ``integer square root'' of its integer
3389 argument, i.e., the greatest integer less than or equal to the true
3390 square root of the argument.
3393 @defun floor* number &optional divisor
3394 This function implements the Common Lisp @code{floor} function.
3395 It is called @code{floor*} to avoid name conflicts with the
3396 simpler @code{floor} function built-in to Emacs.
3398 With one argument, @code{floor*} returns a list of two numbers:
3399 The argument rounded down (toward minus infinity) to an integer,
3400 and the ``remainder'' which would have to be added back to the
3401 first return value to yield the argument again. If the argument
3402 is an integer @var{x}, the result is always the list @code{(@var{x} 0)}.
3403 If the argument is a floating-point number, the first
3404 result is a Lisp integer and the second is a Lisp float between
3405 0 (inclusive) and 1 (exclusive).
3407 With two arguments, @code{floor*} divides @var{number} by
3408 @var{divisor}, and returns the floor of the quotient and the
3409 corresponding remainder as a list of two numbers. If
3410 @code{(floor* @var{x} @var{y})} returns @code{(@var{q} @var{r})},
3411 then @code{@var{q}*@var{y} + @var{r} = @var{x}}, with @var{r}
3412 between 0 (inclusive) and @var{r} (exclusive). Also, note
3413 that @code{(floor* @var{x})} is exactly equivalent to
3414 @code{(floor* @var{x} 1)}.
3416 This function is entirely compatible with Common Lisp's @code{floor}
3417 function, except that it returns the two results in a list since
3418 Emacs Lisp does not support multiple-valued functions.
3421 @defun ceiling* number &optional divisor
3422 This function implements the Common Lisp @code{ceiling} function,
3423 which is analogous to @code{floor} except that it rounds the
3424 argument or quotient of the arguments up toward plus infinity.
3425 The remainder will be between 0 and minus @var{r}.
3428 @defun truncate* number &optional divisor
3429 This function implements the Common Lisp @code{truncate} function,
3430 which is analogous to @code{floor} except that it rounds the
3431 argument or quotient of the arguments toward zero. Thus it is
3432 equivalent to @code{floor*} if the argument or quotient is
3433 positive, or to @code{ceiling*} otherwise. The remainder has
3434 the same sign as @var{number}.
3437 @defun round* number &optional divisor
3438 This function implements the Common Lisp @code{round} function,
3439 which is analogous to @code{floor} except that it rounds the
3440 argument or quotient of the arguments to the nearest integer.
3441 In the case of a tie (the argument or quotient is exactly
3442 halfway between two integers), it rounds to the even integer.
3445 @defun mod* number divisor
3446 This function returns the same value as the second return value
3450 @defun rem* number divisor
3451 This function returns the same value as the second return value
3455 These definitions are compatible with those in the Quiroz
3456 @file{cl.el} package, except that this package appends @samp{*}
3457 to certain function names to avoid conflicts with existing
3458 Emacs functions, and that the mechanism for returning
3459 multiple values is different.
3465 @node Random Numbers, Implementation Parameters, Numerical Functions, Numbers
3466 @section Random Numbers
3469 This package also provides an implementation of the Common Lisp
3470 random number generator. It uses its own additive-congruential
3471 algorithm, which is much more likely to give statistically clean
3472 random numbers than the simple generators supplied by many
3475 @defun random* number &optional state
3476 This function returns a random nonnegative number less than
3477 @var{number}, and of the same type (either integer or floating-point).
3478 The @var{state} argument should be a @code{random-state} object
3479 which holds the state of the random number generator. The
3480 function modifies this state object as a side effect. If
3481 @var{state} is omitted, it defaults to the variable
3482 @code{*random-state*}, which contains a pre-initialized
3483 @code{random-state} object.
3486 @defvar *random-state*
3487 This variable contains the system ``default'' @code{random-state}
3488 object, used for calls to @code{random*} that do not specify an
3489 alternative state object. Since any number of programs in the
3490 Emacs process may be accessing @code{*random-state*} in interleaved
3491 fashion, the sequence generated from this variable will be
3492 irreproducible for all intents and purposes.
3495 @defun make-random-state &optional state
3496 This function creates or copies a @code{random-state} object.
3497 If @var{state} is omitted or @code{nil}, it returns a new copy of
3498 @code{*random-state*}. This is a copy in the sense that future
3499 sequences of calls to @code{(random* @var{n})} and
3500 @code{(random* @var{n} @var{s})} (where @var{s} is the new
3501 random-state object) will return identical sequences of random
3504 If @var{state} is a @code{random-state} object, this function
3505 returns a copy of that object. If @var{state} is @code{t}, this
3506 function returns a new @code{random-state} object seeded from the
3507 date and time. As an extension to Common Lisp, @var{state} may also
3508 be an integer in which case the new object is seeded from that
3509 integer; each different integer seed will result in a completely
3510 different sequence of random numbers.
3512 It is valid to print a @code{random-state} object to a buffer or
3513 file and later read it back with @code{read}. If a program wishes
3514 to use a sequence of pseudo-random numbers which can be reproduced
3515 later for debugging, it can call @code{(make-random-state t)} to
3516 get a new sequence, then print this sequence to a file. When the
3517 program is later rerun, it can read the original run's random-state
3521 @defun random-state-p object
3522 This predicate returns @code{t} if @var{object} is a
3523 @code{random-state} object, or @code{nil} otherwise.
3526 @node Implementation Parameters, , Random Numbers, Numbers
3527 @section Implementation Parameters
3530 This package defines several useful constants having to with numbers.
3532 The following parameters have to do with floating-point numbers.
3533 This package determines their values by exercising the computer's
3534 floating-point arithmetic in various ways. Because this operation
3535 might be slow, the code for initializing them is kept in a separate
3536 function that must be called before the parameters can be used.
3538 @defun cl-float-limits
3539 This function makes sure that the Common Lisp floating-point parameters
3540 like @code{most-positive-float} have been initialized. Until it is
3541 called, these parameters will be @code{nil}. If this version of Emacs
3542 does not support floats, the parameters will remain @code{nil}. If the
3543 parameters have already been initialized, the function returns
3546 The algorithm makes assumptions that will be valid for most modern
3547 machines, but will fail if the machine's arithmetic is extremely
3548 unusual, e.g., decimal.
3551 Since true Common Lisp supports up to four different floating-point
3552 precisions, it has families of constants like
3553 @code{most-positive-single-float}, @code{most-positive-double-float},
3554 @code{most-positive-long-float}, and so on. Emacs has only one
3555 floating-point precision, so this package omits the precision word
3556 from the constants' names.
3558 @defvar most-positive-float
3559 This constant equals the largest value a Lisp float can hold.
3560 For those systems whose arithmetic supports infinities, this is
3561 the largest @emph{finite} value. For IEEE machines, the value
3562 is approximately @code{1.79e+308}.
3565 @defvar most-negative-float
3566 This constant equals the most-negative value a Lisp float can hold.
3567 (It is assumed to be equal to @code{(- most-positive-float)}.)
3570 @defvar least-positive-float
3571 This constant equals the smallest Lisp float value greater than zero.
3572 For IEEE machines, it is about @code{4.94e-324} if denormals are
3573 supported or @code{2.22e-308} if not.
3576 @defvar least-positive-normalized-float
3577 This constant equals the smallest @emph{normalized} Lisp float greater
3578 than zero, i.e., the smallest value for which IEEE denormalization
3579 will not result in a loss of precision. For IEEE machines, this
3580 value is about @code{2.22e-308}. For machines that do not support
3581 the concept of denormalization and gradual underflow, this constant
3582 will always equal @code{least-positive-float}.
3585 @defvar least-negative-float
3586 This constant is the negative counterpart of @code{least-positive-float}.
3589 @defvar least-negative-normalized-float
3590 This constant is the negative counterpart of
3591 @code{least-positive-normalized-float}.
3594 @defvar float-epsilon
3595 This constant is the smallest positive Lisp float that can be added
3596 to 1.0 to produce a distinct value. Adding a smaller number to 1.0
3597 will yield 1.0 again due to roundoff. For IEEE machines, epsilon
3598 is about @code{2.22e-16}.
3601 @defvar float-negative-epsilon
3602 This is the smallest positive value that can be subtracted from
3603 1.0 to produce a distinct value. For IEEE machines, it is about
3611 @node Sequences, Lists, Numbers, Top
3615 Common Lisp defines a number of functions that operate on
3616 @dfn{sequences}, which are either lists, strings, or vectors.
3617 Emacs Lisp includes a few of these, notably @code{elt} and
3618 @code{length}; this package defines most of the rest.
3621 * Sequence Basics:: Arguments shared by all sequence functions
3622 * Mapping over Sequences:: `mapcar*', `mapcan', `map', `every', etc.
3623 * Sequence Functions:: `subseq', `remove*', `substitute', etc.
3624 * Searching Sequences:: `find', `position', `count', `search', etc.
3625 * Sorting Sequences:: `sort*', `stable-sort', `merge'
3628 @node Sequence Basics, Mapping over Sequences, Sequences, Sequences
3629 @section Sequence Basics
3632 Many of the sequence functions take keyword arguments; @pxref{Argument
3633 Lists}. All keyword arguments are optional and, if specified,
3634 may appear in any order.
3636 The @code{:key} argument should be passed either @code{nil}, or a
3637 function of one argument. This key function is used as a filter
3638 through which the elements of the sequence are seen; for example,
3639 @code{(find x y :key 'car)} is similar to @code{(assoc* x y)}:
3640 It searches for an element of the list whose @code{car} equals
3641 @code{x}, rather than for an element which equals @code{x} itself.
3642 If @code{:key} is omitted or @code{nil}, the filter is effectively
3643 the identity function.
3645 The @code{:test} and @code{:test-not} arguments should be either
3646 @code{nil}, or functions of two arguments. The test function is
3647 used to compare two sequence elements, or to compare a search value
3648 with sequence elements. (The two values are passed to the test
3649 function in the same order as the original sequence function
3650 arguments from which they are derived, or, if they both come from
3651 the same sequence, in the same order as they appear in that sequence.)
3652 The @code{:test} argument specifies a function which must return
3653 true (non-@code{nil}) to indicate a match; instead, you may use
3654 @code{:test-not} to give a function which returns @emph{false} to
3655 indicate a match. The default test function is @code{eql}.
3657 Many functions which take @var{item} and @code{:test} or @code{:test-not}
3658 arguments also come in @code{-if} and @code{-if-not} varieties,
3659 where a @var{predicate} function is passed instead of @var{item},
3660 and sequence elements match if the predicate returns true on them
3661 (or false in the case of @code{-if-not}). For example:
3664 (remove* 0 seq :test '=) @equiv{} (remove-if 'zerop seq)
3668 to remove all zeros from sequence @code{seq}.
3670 Some operations can work on a subsequence of the argument sequence;
3671 these function take @code{:start} and @code{:end} arguments which
3672 default to zero and the length of the sequence, respectively.
3673 Only elements between @var{start} (inclusive) and @var{end}
3674 (exclusive) are affected by the operation. The @var{end} argument
3675 may be passed @code{nil} to signify the length of the sequence;
3676 otherwise, both @var{start} and @var{end} must be integers, with
3677 @code{0 <= @var{start} <= @var{end} <= (length @var{seq})}.
3678 If the function takes two sequence arguments, the limits are
3679 defined by keywords @code{:start1} and @code{:end1} for the first,
3680 and @code{:start2} and @code{:end2} for the second.
3682 A few functions accept a @code{:from-end} argument, which, if
3683 non-@code{nil}, causes the operation to go from right-to-left
3684 through the sequence instead of left-to-right, and a @code{:count}
3685 argument, which specifies an integer maximum number of elements
3686 to be removed or otherwise processed.
3688 The sequence functions make no guarantees about the order in
3689 which the @code{:test}, @code{:test-not}, and @code{:key} functions
3690 are called on various elements. Therefore, it is a bad idea to depend
3691 on side effects of these functions. For example, @code{:from-end}
3692 may cause the sequence to be scanned actually in reverse, or it may
3693 be scanned forwards but computing a result ``as if'' it were scanned
3694 backwards. (Some functions, like @code{mapcar*} and @code{every},
3695 @emph{do} specify exactly the order in which the function is called
3696 so side effects are perfectly acceptable in those cases.)
3698 Strings may contain ``text properties'' as well
3699 as character data. Except as noted, it is undefined whether or
3700 not text properties are preserved by sequence functions. For
3701 example, @code{(remove* ?A @var{str})} may or may not preserve
3702 the properties of the characters copied from @var{str} into the
3705 @node Mapping over Sequences, Sequence Functions, Sequence Basics, Sequences
3706 @section Mapping over Sequences
3709 These functions ``map'' the function you specify over the elements
3710 of lists or arrays. They are all variations on the theme of the
3711 built-in function @code{mapcar}.
3713 @defun mapcar* function seq &rest more-seqs
3714 This function calls @var{function} on successive parallel sets of
3715 elements from its argument sequences. Given a single @var{seq}
3716 argument it is equivalent to @code{mapcar}; given @var{n} sequences,
3717 it calls the function with the first elements of each of the sequences
3718 as the @var{n} arguments to yield the first element of the result
3719 list, then with the second elements, and so on. The mapping stops as
3720 soon as the shortest sequence runs out. The argument sequences may
3721 be any mixture of lists, strings, and vectors; the return sequence
3724 Common Lisp's @code{mapcar} accepts multiple arguments but works
3725 only on lists; Emacs Lisp's @code{mapcar} accepts a single sequence
3726 argument. This package's @code{mapcar*} works as a compatible
3730 @defun map result-type function seq &rest more-seqs
3731 This function maps @var{function} over the argument sequences,
3732 just like @code{mapcar*}, but it returns a sequence of type
3733 @var{result-type} rather than a list. @var{result-type} must
3734 be one of the following symbols: @code{vector}, @code{string},
3735 @code{list} (in which case the effect is the same as for
3736 @code{mapcar*}), or @code{nil} (in which case the results are
3737 thrown away and @code{map} returns @code{nil}).
3740 @defun maplist function list &rest more-lists
3741 This function calls @var{function} on each of its argument lists,
3742 then on the @code{cdr}s of those lists, and so on, until the
3743 shortest list runs out. The results are returned in the form
3744 of a list. Thus, @code{maplist} is like @code{mapcar*} except
3745 that it passes in the list pointers themselves rather than the
3746 @code{car}s of the advancing pointers.
3749 @defun mapc function seq &rest more-seqs
3750 This function is like @code{mapcar*}, except that the values returned
3751 by @var{function} are ignored and thrown away rather than being
3752 collected into a list. The return value of @code{mapc} is @var{seq},
3753 the first sequence. This function is more general than the Emacs
3754 primitive @code{mapc}.
3757 @defun mapl function list &rest more-lists
3758 This function is like @code{maplist}, except that it throws away
3759 the values returned by @var{function}.
3762 @defun mapcan function seq &rest more-seqs
3763 This function is like @code{mapcar*}, except that it concatenates
3764 the return values (which must be lists) using @code{nconc},
3765 rather than simply collecting them into a list.
3768 @defun mapcon function list &rest more-lists
3769 This function is like @code{maplist}, except that it concatenates
3770 the return values using @code{nconc}.
3773 @defun some predicate seq &rest more-seqs
3774 This function calls @var{predicate} on each element of @var{seq}
3775 in turn; if @var{predicate} returns a non-@code{nil} value,
3776 @code{some} returns that value, otherwise it returns @code{nil}.
3777 Given several sequence arguments, it steps through the sequences
3778 in parallel until the shortest one runs out, just as in
3779 @code{mapcar*}. You can rely on the left-to-right order in which
3780 the elements are visited, and on the fact that mapping stops
3781 immediately as soon as @var{predicate} returns non-@code{nil}.
3784 @defun every predicate seq &rest more-seqs
3785 This function calls @var{predicate} on each element of the sequence(s)
3786 in turn; it returns @code{nil} as soon as @var{predicate} returns
3787 @code{nil} for any element, or @code{t} if the predicate was true
3791 @defun notany predicate seq &rest more-seqs
3792 This function calls @var{predicate} on each element of the sequence(s)
3793 in turn; it returns @code{nil} as soon as @var{predicate} returns
3794 a non-@code{nil} value for any element, or @code{t} if the predicate
3795 was @code{nil} for all elements.
3798 @defun notevery predicate seq &rest more-seqs
3799 This function calls @var{predicate} on each element of the sequence(s)
3800 in turn; it returns a non-@code{nil} value as soon as @var{predicate}
3801 returns @code{nil} for any element, or @code{t} if the predicate was
3802 true for all elements.
3805 @defun reduce function seq @t{&key :from-end :start :end :initial-value :key}
3806 This function combines the elements of @var{seq} using an associative
3807 binary operation. Suppose @var{function} is @code{*} and @var{seq} is
3808 the list @code{(2 3 4 5)}. The first two elements of the list are
3809 combined with @code{(* 2 3) = 6}; this is combined with the next
3810 element, @code{(* 6 4) = 24}, and that is combined with the final
3811 element: @code{(* 24 5) = 120}. Note that the @code{*} function happens
3812 to be self-reducing, so that @code{(* 2 3 4 5)} has the same effect as
3813 an explicit call to @code{reduce}.
3815 If @code{:from-end} is true, the reduction is right-associative instead
3816 of left-associative:
3819 (reduce '- '(1 2 3 4))
3820 @equiv{} (- (- (- 1 2) 3) 4) @result{} -8
3821 (reduce '- '(1 2 3 4) :from-end t)
3822 @equiv{} (- 1 (- 2 (- 3 4))) @result{} -2
3825 If @code{:key} is specified, it is a function of one argument which
3826 is called on each of the sequence elements in turn.
3828 If @code{:initial-value} is specified, it is effectively added to the
3829 front (or rear in the case of @code{:from-end}) of the sequence.
3830 The @code{:key} function is @emph{not} applied to the initial value.
3832 If the sequence, including the initial value, has exactly one element
3833 then that element is returned without ever calling @var{function}.
3834 If the sequence is empty (and there is no initial value), then
3835 @var{function} is called with no arguments to obtain the return value.
3838 All of these mapping operations can be expressed conveniently in
3839 terms of the @code{loop} macro. In compiled code, @code{loop} will
3840 be faster since it generates the loop as in-line code with no
3843 @node Sequence Functions, Searching Sequences, Mapping over Sequences, Sequences
3844 @section Sequence Functions
3847 This section describes a number of Common Lisp functions for
3848 operating on sequences.
3850 @defun subseq sequence start &optional end
3851 This function returns a given subsequence of the argument
3852 @var{sequence}, which may be a list, string, or vector.
3853 The indices @var{start} and @var{end} must be in range, and
3854 @var{start} must be no greater than @var{end}. If @var{end}
3855 is omitted, it defaults to the length of the sequence. The
3856 return value is always a copy; it does not share structure
3857 with @var{sequence}.
3859 As an extension to Common Lisp, @var{start} and/or @var{end}
3860 may be negative, in which case they represent a distance back
3861 from the end of the sequence. This is for compatibility with
3862 Emacs' @code{substring} function. Note that @code{subseq} is
3863 the @emph{only} sequence function that allows negative
3864 @var{start} and @var{end}.
3866 You can use @code{setf} on a @code{subseq} form to replace a
3867 specified range of elements with elements from another sequence.
3868 The replacement is done as if by @code{replace}, described below.
3871 @defun concatenate result-type &rest seqs
3872 This function concatenates the argument sequences together to
3873 form a result sequence of type @var{result-type}, one of the
3874 symbols @code{vector}, @code{string}, or @code{list}. The
3875 arguments are always copied, even in cases such as
3876 @code{(concatenate 'list '(1 2 3))} where the result is
3877 identical to an argument.
3880 @defun fill seq item @t{&key :start :end}
3881 This function fills the elements of the sequence (or the specified
3882 part of the sequence) with the value @var{item}.
3885 @defun replace seq1 seq2 @t{&key :start1 :end1 :start2 :end2}
3886 This function copies part of @var{seq2} into part of @var{seq1}.
3887 The sequence @var{seq1} is not stretched or resized; the amount
3888 of data copied is simply the shorter of the source and destination
3889 (sub)sequences. The function returns @var{seq1}.
3891 If @var{seq1} and @var{seq2} are @code{eq}, then the replacement
3892 will work correctly even if the regions indicated by the start
3893 and end arguments overlap. However, if @var{seq1} and @var{seq2}
3894 are lists which share storage but are not @code{eq}, and the
3895 start and end arguments specify overlapping regions, the effect
3899 @defun remove* item seq @t{&key :test :test-not :key :count :start :end :from-end}
3900 This returns a copy of @var{seq} with all elements matching
3901 @var{item} removed. The result may share storage with or be
3902 @code{eq} to @var{seq} in some circumstances, but the original
3903 @var{seq} will not be modified. The @code{:test}, @code{:test-not},
3904 and @code{:key} arguments define the matching test that is used;
3905 by default, elements @code{eql} to @var{item} are removed. The
3906 @code{:count} argument specifies the maximum number of matching
3907 elements that can be removed (only the leftmost @var{count} matches
3908 are removed). The @code{:start} and @code{:end} arguments specify
3909 a region in @var{seq} in which elements will be removed; elements
3910 outside that region are not matched or removed. The @code{:from-end}
3911 argument, if true, says that elements should be deleted from the
3912 end of the sequence rather than the beginning (this matters only
3913 if @var{count} was also specified).
3916 @defun delete* item seq @t{&key :test :test-not :key :count :start :end :from-end}
3917 This deletes all elements of @var{seq} which match @var{item}.
3918 It is a destructive operation. Since Emacs Lisp does not support
3919 stretchable strings or vectors, this is the same as @code{remove*}
3920 for those sequence types. On lists, @code{remove*} will copy the
3921 list if necessary to preserve the original list, whereas
3922 @code{delete*} will splice out parts of the argument list.
3923 Compare @code{append} and @code{nconc}, which are analogous
3924 non-destructive and destructive list operations in Emacs Lisp.
3928 @findex remove-if-not
3930 @findex delete-if-not
3931 The predicate-oriented functions @code{remove-if}, @code{remove-if-not},
3932 @code{delete-if}, and @code{delete-if-not} are defined similarly.
3934 @defun remove-duplicates seq @t{&key :test :test-not :key :start :end :from-end}
3935 This function returns a copy of @var{seq} with duplicate elements
3936 removed. Specifically, if two elements from the sequence match
3937 according to the @code{:test}, @code{:test-not}, and @code{:key}
3938 arguments, only the rightmost one is retained. If @code{:from-end}
3939 is true, the leftmost one is retained instead. If @code{:start} or
3940 @code{:end} is specified, only elements within that subsequence are
3941 examined or removed.
3944 @defun delete-duplicates seq @t{&key :test :test-not :key :start :end :from-end}
3945 This function deletes duplicate elements from @var{seq}. It is
3946 a destructive version of @code{remove-duplicates}.
3949 @defun substitute new old seq @t{&key :test :test-not :key :count :start :end :from-end}
3950 This function returns a copy of @var{seq}, with all elements
3951 matching @var{old} replaced with @var{new}. The @code{:count},
3952 @code{:start}, @code{:end}, and @code{:from-end} arguments may be
3953 used to limit the number of substitutions made.
3956 @defun nsubstitute new old seq @t{&key :test :test-not :key :count :start :end :from-end}
3957 This is a destructive version of @code{substitute}; it performs
3958 the substitution using @code{setcar} or @code{aset} rather than
3959 by returning a changed copy of the sequence.
3962 @findex substitute-if
3963 @findex substitute-if-not
3964 @findex nsubstitute-if
3965 @findex nsubstitute-if-not
3966 The @code{substitute-if}, @code{substitute-if-not}, @code{nsubstitute-if},
3967 and @code{nsubstitute-if-not} functions are defined similarly. For
3968 these, a @var{predicate} is given in place of the @var{old} argument.
3970 @node Searching Sequences, Sorting Sequences, Sequence Functions, Sequences
3971 @section Searching Sequences
3974 These functions search for elements or subsequences in a sequence.
3975 (See also @code{member*} and @code{assoc*}; @pxref{Lists}.)
3977 @defun find item seq @t{&key :test :test-not :key :start :end :from-end}
3978 This function searches @var{seq} for an element matching @var{item}.
3979 If it finds a match, it returns the matching element. Otherwise,
3980 it returns @code{nil}. It returns the leftmost match, unless
3981 @code{:from-end} is true, in which case it returns the rightmost
3982 match. The @code{:start} and @code{:end} arguments may be used to
3983 limit the range of elements that are searched.
3986 @defun position item seq @t{&key :test :test-not :key :start :end :from-end}
3987 This function is like @code{find}, except that it returns the
3988 integer position in the sequence of the matching item rather than
3989 the item itself. The position is relative to the start of the
3990 sequence as a whole, even if @code{:start} is non-zero. The function
3991 returns @code{nil} if no matching element was found.
3994 @defun count item seq @t{&key :test :test-not :key :start :end}
3995 This function returns the number of elements of @var{seq} which
3996 match @var{item}. The result is always a nonnegative integer.
4002 @findex position-if-not
4004 @findex count-if-not
4005 The @code{find-if}, @code{find-if-not}, @code{position-if},
4006 @code{position-if-not}, @code{count-if}, and @code{count-if-not}
4007 functions are defined similarly.
4009 @defun mismatch seq1 seq2 @t{&key :test :test-not :key :start1 :end1 :start2 :end2 :from-end}
4010 This function compares the specified parts of @var{seq1} and
4011 @var{seq2}. If they are the same length and the corresponding
4012 elements match (according to @code{:test}, @code{:test-not},
4013 and @code{:key}), the function returns @code{nil}. If there is
4014 a mismatch, the function returns the index (relative to @var{seq1})
4015 of the first mismatching element. This will be the leftmost pair of
4016 elements which do not match, or the position at which the shorter of
4017 the two otherwise-matching sequences runs out.
4019 If @code{:from-end} is true, then the elements are compared from right
4020 to left starting at @code{(1- @var{end1})} and @code{(1- @var{end2})}.
4021 If the sequences differ, then one plus the index of the rightmost
4022 difference (relative to @var{seq1}) is returned.
4024 An interesting example is @code{(mismatch str1 str2 :key 'upcase)},
4025 which compares two strings case-insensitively.
4028 @defun search seq1 seq2 @t{&key :test :test-not :key :from-end :start1 :end1 :start2 :end2}
4029 This function searches @var{seq2} for a subsequence that matches
4030 @var{seq1} (or part of it specified by @code{:start1} and
4031 @code{:end1}.) Only matches which fall entirely within the region
4032 defined by @code{:start2} and @code{:end2} will be considered.
4033 The return value is the index of the leftmost element of the
4034 leftmost match, relative to the start of @var{seq2}, or @code{nil}
4035 if no matches were found. If @code{:from-end} is true, the
4036 function finds the @emph{rightmost} matching subsequence.
4039 @node Sorting Sequences, , Searching Sequences, Sequences
4040 @section Sorting Sequences
4042 @defun sort* seq predicate @t{&key :key}
4043 This function sorts @var{seq} into increasing order as determined
4044 by using @var{predicate} to compare pairs of elements. @var{predicate}
4045 should return true (non-@code{nil}) if and only if its first argument
4046 is less than (not equal to) its second argument. For example,
4047 @code{<} and @code{string-lessp} are suitable predicate functions
4048 for sorting numbers and strings, respectively; @code{>} would sort
4049 numbers into decreasing rather than increasing order.
4051 This function differs from Emacs' built-in @code{sort} in that it
4052 can operate on any type of sequence, not just lists. Also, it
4053 accepts a @code{:key} argument which is used to preprocess data
4054 fed to the @var{predicate} function. For example,
4057 (setq data (sort* data 'string-lessp :key 'downcase))
4061 sorts @var{data}, a sequence of strings, into increasing alphabetical
4062 order without regard to case. A @code{:key} function of @code{car}
4063 would be useful for sorting association lists. It should only be a
4064 simple accessor though, it's used heavily in the current
4067 The @code{sort*} function is destructive; it sorts lists by actually
4068 rearranging the @code{cdr} pointers in suitable fashion.
4071 @defun stable-sort seq predicate @t{&key :key}
4072 This function sorts @var{seq} @dfn{stably}, meaning two elements
4073 which are equal in terms of @var{predicate} are guaranteed not to
4074 be rearranged out of their original order by the sort.
4076 In practice, @code{sort*} and @code{stable-sort} are equivalent
4077 in Emacs Lisp because the underlying @code{sort} function is
4078 stable by default. However, this package reserves the right to
4079 use non-stable methods for @code{sort*} in the future.
4082 @defun merge type seq1 seq2 predicate @t{&key :key}
4083 This function merges two sequences @var{seq1} and @var{seq2} by
4084 interleaving their elements. The result sequence, of type @var{type}
4085 (in the sense of @code{concatenate}), has length equal to the sum
4086 of the lengths of the two input sequences. The sequences may be
4087 modified destructively. Order of elements within @var{seq1} and
4088 @var{seq2} is preserved in the interleaving; elements of the two
4089 sequences are compared by @var{predicate} (in the sense of
4090 @code{sort}) and the lesser element goes first in the result.
4091 When elements are equal, those from @var{seq1} precede those from
4092 @var{seq2} in the result. Thus, if @var{seq1} and @var{seq2} are
4093 both sorted according to @var{predicate}, then the result will be
4094 a merged sequence which is (stably) sorted according to
4098 @node Lists, Structures, Sequences, Top
4102 The functions described here operate on lists.
4105 * List Functions:: `caddr', `first', `list*', etc.
4106 * Substitution of Expressions:: `subst', `sublis', etc.
4107 * Lists as Sets:: `member*', `adjoin', `union', etc.
4108 * Association Lists:: `assoc*', `rassoc*', `acons', `pairlis'
4111 @node List Functions, Substitution of Expressions, Lists, Lists
4112 @section List Functions
4115 This section describes a number of simple operations on lists,
4116 i.e., chains of cons cells.
4119 This function is equivalent to @code{(car (cdr (cdr @var{x})))}.
4120 Likewise, this package defines all 28 @code{c@var{xxx}r} functions
4121 where @var{xxx} is up to four @samp{a}s and/or @samp{d}s.
4122 All of these functions are @code{setf}-able, and calls to them
4123 are expanded inline by the byte-compiler for maximum efficiency.
4127 This function is a synonym for @code{(car @var{x})}. Likewise,
4128 the functions @code{second}, @code{third}, @dots{}, through
4129 @code{tenth} return the given element of the list @var{x}.
4133 This function is a synonym for @code{(cdr @var{x})}.
4137 Common Lisp defines this function to act like @code{null}, but
4138 signaling an error if @code{x} is neither a @code{nil} nor a
4139 cons cell. This package simply defines @code{endp} as a synonym
4143 @defun list-length x
4144 This function returns the length of list @var{x}, exactly like
4145 @code{(length @var{x})}, except that if @var{x} is a circular
4146 list (where the cdr-chain forms a loop rather than terminating
4147 with @code{nil}), this function returns @code{nil}. (The regular
4148 @code{length} function would get stuck if given a circular list.)
4151 @defun list* arg &rest others
4152 This function constructs a list of its arguments. The final
4153 argument becomes the @code{cdr} of the last cell constructed.
4154 Thus, @code{(list* @var{a} @var{b} @var{c})} is equivalent to
4155 @code{(cons @var{a} (cons @var{b} @var{c}))}, and
4156 @code{(list* @var{a} @var{b} nil)} is equivalent to
4157 @code{(list @var{a} @var{b})}.
4159 (Note that this function really is called @code{list*} in Common
4160 Lisp; it is not a name invented for this package like @code{member*}
4164 @defun ldiff list sublist
4165 If @var{sublist} is a sublist of @var{list}, i.e., is @code{eq} to
4166 one of the cons cells of @var{list}, then this function returns
4167 a copy of the part of @var{list} up to but not including
4168 @var{sublist}. For example, @code{(ldiff x (cddr x))} returns
4169 the first two elements of the list @code{x}. The result is a
4170 copy; the original @var{list} is not modified. If @var{sublist}
4171 is not a sublist of @var{list}, a copy of the entire @var{list}
4175 @defun copy-list list
4176 This function returns a copy of the list @var{list}. It copies
4177 dotted lists like @code{(1 2 . 3)} correctly.
4180 @defun copy-tree x &optional vecp
4181 This function returns a copy of the tree of cons cells @var{x}.
4182 Unlike @code{copy-sequence} (and its alias @code{copy-list}),
4183 which copies only along the @code{cdr} direction, this function
4184 copies (recursively) along both the @code{car} and the @code{cdr}
4185 directions. If @var{x} is not a cons cell, the function simply
4186 returns @var{x} unchanged. If the optional @var{vecp} argument
4187 is true, this function copies vectors (recursively) as well as
4191 @defun tree-equal x y @t{&key :test :test-not :key}
4192 This function compares two trees of cons cells. If @var{x} and
4193 @var{y} are both cons cells, their @code{car}s and @code{cdr}s are
4194 compared recursively. If neither @var{x} nor @var{y} is a cons
4195 cell, they are compared by @code{eql}, or according to the
4196 specified test. The @code{:key} function, if specified, is
4197 applied to the elements of both trees. @xref{Sequences}.
4204 @node Substitution of Expressions, Lists as Sets, List Functions, Lists
4205 @section Substitution of Expressions
4208 These functions substitute elements throughout a tree of cons
4209 cells. (@xref{Sequence Functions}, for the @code{substitute}
4210 function, which works on just the top-level elements of a list.)
4212 @defun subst new old tree @t{&key :test :test-not :key}
4213 This function substitutes occurrences of @var{old} with @var{new}
4214 in @var{tree}, a tree of cons cells. It returns a substituted
4215 tree, which will be a copy except that it may share storage with
4216 the argument @var{tree} in parts where no substitutions occurred.
4217 The original @var{tree} is not modified. This function recurses
4218 on, and compares against @var{old}, both @code{car}s and @code{cdr}s
4219 of the component cons cells. If @var{old} is itself a cons cell,
4220 then matching cells in the tree are substituted as usual without
4221 recursively substituting in that cell. Comparisons with @var{old}
4222 are done according to the specified test (@code{eql} by default).
4223 The @code{:key} function is applied to the elements of the tree
4224 but not to @var{old}.
4227 @defun nsubst new old tree @t{&key :test :test-not :key}
4228 This function is like @code{subst}, except that it works by
4229 destructive modification (by @code{setcar} or @code{setcdr})
4230 rather than copying.
4234 @findex subst-if-not
4236 @findex nsubst-if-not
4237 The @code{subst-if}, @code{subst-if-not}, @code{nsubst-if}, and
4238 @code{nsubst-if-not} functions are defined similarly.
4240 @defun sublis alist tree @t{&key :test :test-not :key}
4241 This function is like @code{subst}, except that it takes an
4242 association list @var{alist} of @var{old}-@var{new} pairs.
4243 Each element of the tree (after applying the @code{:key}
4244 function, if any), is compared with the @code{car}s of
4245 @var{alist}; if it matches, it is replaced by the corresponding
4249 @defun nsublis alist tree @t{&key :test :test-not :key}
4250 This is a destructive version of @code{sublis}.
4253 @node Lists as Sets, Association Lists, Substitution of Expressions, Lists
4254 @section Lists as Sets
4257 These functions perform operations on lists which represent sets
4260 @defun member* item list @t{&key :test :test-not :key}
4261 This function searches @var{list} for an element matching @var{item}.
4262 If a match is found, it returns the cons cell whose @code{car} was
4263 the matching element. Otherwise, it returns @code{nil}. Elements
4264 are compared by @code{eql} by default; you can use the @code{:test},
4265 @code{:test-not}, and @code{:key} arguments to modify this behavior.
4268 Note that this function's name is suffixed by @samp{*} to avoid
4269 the incompatible @code{member} function defined in Emacs.
4270 (That function uses @code{equal} for comparisons; it is equivalent
4271 to @code{(member* @var{item} @var{list} :test 'equal)}.)
4275 @findex member-if-not
4276 The @code{member-if} and @code{member-if-not} functions
4277 analogously search for elements which satisfy a given predicate.
4279 @defun tailp sublist list
4280 This function returns @code{t} if @var{sublist} is a sublist of
4281 @var{list}, i.e., if @var{sublist} is @code{eql} to @var{list} or to
4282 any of its @code{cdr}s.
4285 @defun adjoin item list @t{&key :test :test-not :key}
4286 This function conses @var{item} onto the front of @var{list},
4287 like @code{(cons @var{item} @var{list})}, but only if @var{item}
4288 is not already present on the list (as determined by @code{member*}).
4289 If a @code{:key} argument is specified, it is applied to
4290 @var{item} as well as to the elements of @var{list} during
4291 the search, on the reasoning that @var{item} is ``about'' to
4292 become part of the list.
4295 @defun union list1 list2 @t{&key :test :test-not :key}
4296 This function combines two lists which represent sets of items,
4297 returning a list that represents the union of those two sets.
4298 The result list will contain all items which appear in @var{list1}
4299 or @var{list2}, and no others. If an item appears in both
4300 @var{list1} and @var{list2} it will be copied only once. If
4301 an item is duplicated in @var{list1} or @var{list2}, it is
4302 undefined whether or not that duplication will survive in the
4303 result list. The order of elements in the result list is also
4307 @defun nunion list1 list2 @t{&key :test :test-not :key}
4308 This is a destructive version of @code{union}; rather than copying,
4309 it tries to reuse the storage of the argument lists if possible.
4312 @defun intersection list1 list2 @t{&key :test :test-not :key}
4313 This function computes the intersection of the sets represented
4314 by @var{list1} and @var{list2}. It returns the list of items
4315 which appear in both @var{list1} and @var{list2}.
4318 @defun nintersection list1 list2 @t{&key :test :test-not :key}
4319 This is a destructive version of @code{intersection}. It
4320 tries to reuse storage of @var{list1} rather than copying.
4321 It does @emph{not} reuse the storage of @var{list2}.
4324 @defun set-difference list1 list2 @t{&key :test :test-not :key}
4325 This function computes the ``set difference'' of @var{list1}
4326 and @var{list2}, i.e., the set of elements that appear in
4327 @var{list1} but @emph{not} in @var{list2}.
4330 @defun nset-difference list1 list2 @t{&key :test :test-not :key}
4331 This is a destructive @code{set-difference}, which will try
4332 to reuse @var{list1} if possible.
4335 @defun set-exclusive-or list1 list2 @t{&key :test :test-not :key}
4336 This function computes the ``set exclusive or'' of @var{list1}
4337 and @var{list2}, i.e., the set of elements that appear in
4338 exactly one of @var{list1} and @var{list2}.
4341 @defun nset-exclusive-or list1 list2 @t{&key :test :test-not :key}
4342 This is a destructive @code{set-exclusive-or}, which will try
4343 to reuse @var{list1} and @var{list2} if possible.
4346 @defun subsetp list1 list2 @t{&key :test :test-not :key}
4347 This function checks whether @var{list1} represents a subset
4348 of @var{list2}, i.e., whether every element of @var{list1}
4349 also appears in @var{list2}.
4352 @node Association Lists, , Lists as Sets, Lists
4353 @section Association Lists
4356 An @dfn{association list} is a list representing a mapping from
4357 one set of values to another; any list whose elements are cons
4358 cells is an association list.
4360 @defun assoc* item a-list @t{&key :test :test-not :key}
4361 This function searches the association list @var{a-list} for an
4362 element whose @code{car} matches (in the sense of @code{:test},
4363 @code{:test-not}, and @code{:key}, or by comparison with @code{eql})
4364 a given @var{item}. It returns the matching element, if any,
4365 otherwise @code{nil}. It ignores elements of @var{a-list} which
4366 are not cons cells. (This corresponds to the behavior of
4367 @code{assq} and @code{assoc} in Emacs Lisp; Common Lisp's
4368 @code{assoc} ignores @code{nil}s but considers any other non-cons
4369 elements of @var{a-list} to be an error.)
4372 @defun rassoc* item a-list @t{&key :test :test-not :key}
4373 This function searches for an element whose @code{cdr} matches
4374 @var{item}. If @var{a-list} represents a mapping, this applies
4375 the inverse of the mapping to @var{item}.
4379 @findex assoc-if-not
4381 @findex rassoc-if-not
4382 The @code{assoc-if}, @code{assoc-if-not}, @code{rassoc-if},
4383 and @code{rassoc-if-not} functions are defined similarly.
4385 Two simple functions for constructing association lists are:
4387 @defun acons key value alist
4388 This is equivalent to @code{(cons (cons @var{key} @var{value}) @var{alist})}.
4391 @defun pairlis keys values &optional alist
4392 This is equivalent to @code{(nconc (mapcar* 'cons @var{keys} @var{values})
4400 @node Structures, Assertions, Lists, Top
4404 The Common Lisp @dfn{structure} mechanism provides a general way
4405 to define data types similar to C's @code{struct} types. A
4406 structure is a Lisp object containing some number of @dfn{slots},
4407 each of which can hold any Lisp data object. Functions are
4408 provided for accessing and setting the slots, creating or copying
4409 structure objects, and recognizing objects of a particular structure
4412 In true Common Lisp, each structure type is a new type distinct
4413 from all existing Lisp types. Since the underlying Emacs Lisp
4414 system provides no way to create new distinct types, this package
4415 implements structures as vectors (or lists upon request) with a
4416 special ``tag'' symbol to identify them.
4418 @defspec defstruct name slots@dots{}
4419 The @code{defstruct} form defines a new structure type called
4420 @var{name}, with the specified @var{slots}. (The @var{slots}
4421 may begin with a string which documents the structure type.)
4422 In the simplest case, @var{name} and each of the @var{slots}
4423 are symbols. For example,
4426 (defstruct person name age sex)
4430 defines a struct type called @code{person} which contains three
4431 slots. Given a @code{person} object @var{p}, you can access those
4432 slots by calling @code{(person-name @var{p})}, @code{(person-age @var{p})},
4433 and @code{(person-sex @var{p})}. You can also change these slots by
4434 using @code{setf} on any of these place forms:
4437 (incf (person-age birthday-boy))
4440 You can create a new @code{person} by calling @code{make-person},
4441 which takes keyword arguments @code{:name}, @code{:age}, and
4442 @code{:sex} to specify the initial values of these slots in the
4443 new object. (Omitting any of these arguments leaves the corresponding
4444 slot ``undefined,'' according to the Common Lisp standard; in Emacs
4445 Lisp, such uninitialized slots are filled with @code{nil}.)
4447 Given a @code{person}, @code{(copy-person @var{p})} makes a new
4448 object of the same type whose slots are @code{eq} to those of @var{p}.
4450 Given any Lisp object @var{x}, @code{(person-p @var{x})} returns
4451 true if @var{x} looks like a @code{person}, false otherwise. (Again,
4452 in Common Lisp this predicate would be exact; in Emacs Lisp the
4453 best it can do is verify that @var{x} is a vector of the correct
4454 length which starts with the correct tag symbol.)
4456 Accessors like @code{person-name} normally check their arguments
4457 (effectively using @code{person-p}) and signal an error if the
4458 argument is the wrong type. This check is affected by
4459 @code{(optimize (safety @dots{}))} declarations. Safety level 1,
4460 the default, uses a somewhat optimized check that will detect all
4461 incorrect arguments, but may use an uninformative error message
4462 (e.g., ``expected a vector'' instead of ``expected a @code{person}'').
4463 Safety level 0 omits all checks except as provided by the underlying
4464 @code{aref} call; safety levels 2 and 3 do rigorous checking that will
4465 always print a descriptive error message for incorrect inputs.
4466 @xref{Declarations}.
4469 (setq dave (make-person :name "Dave" :sex 'male))
4470 @result{} [cl-struct-person "Dave" nil male]
4471 (setq other (copy-person dave))
4472 @result{} [cl-struct-person "Dave" nil male]
4475 (eq (person-name dave) (person-name other))
4479 (person-p [1 2 3 4])
4483 (person-p '[cl-struct-person counterfeit person object])
4487 In general, @var{name} is either a name symbol or a list of a name
4488 symbol followed by any number of @dfn{struct options}; each @var{slot}
4489 is either a slot symbol or a list of the form @samp{(@var{slot-name}
4490 @var{default-value} @var{slot-options}@dots{})}. The @var{default-value}
4491 is a Lisp form which is evaluated any time an instance of the
4492 structure type is created without specifying that slot's value.
4494 Common Lisp defines several slot options, but the only one
4495 implemented in this package is @code{:read-only}. A non-@code{nil}
4496 value for this option means the slot should not be @code{setf}-able;
4497 the slot's value is determined when the object is created and does
4498 not change afterward.
4502 (name nil :read-only t)
4507 Any slot options other than @code{:read-only} are ignored.
4509 For obscure historical reasons, structure options take a different
4510 form than slot options. A structure option is either a keyword
4511 symbol, or a list beginning with a keyword symbol possibly followed
4512 by arguments. (By contrast, slot options are key-value pairs not
4516 (defstruct (person (:constructor create-person)
4522 The following structure options are recognized.
4527 @advance@leftskip-.5@tableindent
4530 The argument is a symbol whose print name is used as the prefix for
4531 the names of slot accessor functions. The default is the name of
4532 the struct type followed by a hyphen. The option @code{(:conc-name p-)}
4533 would change this prefix to @code{p-}. Specifying @code{nil} as an
4534 argument means no prefix, so that the slot names themselves are used
4535 to name the accessor functions.
4538 In the simple case, this option takes one argument which is an
4539 alternate name to use for the constructor function. The default
4540 is @code{make-@var{name}}, e.g., @code{make-person}. The above
4541 example changes this to @code{create-person}. Specifying @code{nil}
4542 as an argument means that no standard constructor should be
4545 In the full form of this option, the constructor name is followed
4546 by an arbitrary argument list. @xref{Program Structure}, for a
4547 description of the format of Common Lisp argument lists. All
4548 options, such as @code{&rest} and @code{&key}, are supported.
4549 The argument names should match the slot names; each slot is
4550 initialized from the corresponding argument. Slots whose names
4551 do not appear in the argument list are initialized based on the
4552 @var{default-value} in their slot descriptor. Also, @code{&optional}
4553 and @code{&key} arguments which don't specify defaults take their
4554 defaults from the slot descriptor. It is valid to include arguments
4555 which don't correspond to slot names; these are useful if they are
4556 referred to in the defaults for optional, keyword, or @code{&aux}
4557 arguments which @emph{do} correspond to slots.
4559 You can specify any number of full-format @code{:constructor}
4560 options on a structure. The default constructor is still generated
4561 as well unless you disable it with a simple-format @code{:constructor}
4567 (:constructor nil) ; no default constructor
4568 (:constructor new-person (name sex &optional (age 0)))
4569 (:constructor new-hound (&key (name "Rover")
4571 &aux (age (* 7 dog-years))
4576 The first constructor here takes its arguments positionally rather
4577 than by keyword. (In official Common Lisp terminology, constructors
4578 that work By Order of Arguments instead of by keyword are called
4579 ``BOA constructors.'' No, I'm not making this up.) For example,
4580 @code{(new-person "Jane" 'female)} generates a person whose slots
4581 are @code{"Jane"}, 0, and @code{female}, respectively.
4583 The second constructor takes two keyword arguments, @code{:name},
4584 which initializes the @code{name} slot and defaults to @code{"Rover"},
4585 and @code{:dog-years}, which does not itself correspond to a slot
4586 but which is used to initialize the @code{age} slot. The @code{sex}
4587 slot is forced to the symbol @code{canine} with no syntax for
4591 The argument is an alternate name for the copier function for
4592 this type. The default is @code{copy-@var{name}}. @code{nil}
4593 means not to generate a copier function. (In this implementation,
4594 all copier functions are simply synonyms for @code{copy-sequence}.)
4597 The argument is an alternate name for the predicate which recognizes
4598 objects of this type. The default is @code{@var{name}-p}. @code{nil}
4599 means not to generate a predicate function. (If the @code{:type}
4600 option is used without the @code{:named} option, no predicate is
4603 In true Common Lisp, @code{typep} is always able to recognize a
4604 structure object even if @code{:predicate} was used. In this
4605 package, @code{typep} simply looks for a function called
4606 @code{@var{typename}-p}, so it will work for structure types
4607 only if they used the default predicate name.
4610 This option implements a very limited form of C++-style inheritance.
4611 The argument is the name of another structure type previously
4612 created with @code{defstruct}. The effect is to cause the new
4613 structure type to inherit all of the included structure's slots
4614 (plus, of course, any new slots described by this struct's slot
4615 descriptors). The new structure is considered a ``specialization''
4616 of the included one. In fact, the predicate and slot accessors
4617 for the included type will also accept objects of the new type.
4619 If there are extra arguments to the @code{:include} option after
4620 the included-structure name, these options are treated as replacement
4621 slot descriptors for slots in the included structure, possibly with
4622 modified default values. Borrowing an example from Steele:
4625 (defstruct person name (age 0) sex)
4627 (defstruct (astronaut (:include person (age 45)))
4629 (favorite-beverage 'tang))
4632 (setq joe (make-person :name "Joe"))
4633 @result{} [cl-struct-person "Joe" 0 nil]
4634 (setq buzz (make-astronaut :name "Buzz"))
4635 @result{} [cl-struct-astronaut "Buzz" 45 nil nil tang]
4637 (list (person-p joe) (person-p buzz))
4639 (list (astronaut-p joe) (astronaut-p buzz))
4644 (astronaut-name joe)
4645 @result{} error: "astronaut-name accessing a non-astronaut"
4648 Thus, if @code{astronaut} is a specialization of @code{person},
4649 then every @code{astronaut} is also a @code{person} (but not the
4650 other way around). Every @code{astronaut} includes all the slots
4651 of a @code{person}, plus extra slots that are specific to
4652 astronauts. Operations that work on people (like @code{person-name})
4653 work on astronauts just like other people.
4655 @item :print-function
4656 In full Common Lisp, this option allows you to specify a function
4657 which is called to print an instance of the structure type. The
4658 Emacs Lisp system offers no hooks into the Lisp printer which would
4659 allow for such a feature, so this package simply ignores
4660 @code{:print-function}.
4663 The argument should be one of the symbols @code{vector} or @code{list}.
4664 This tells which underlying Lisp data type should be used to implement
4665 the new structure type. Vectors are used by default, but
4666 @code{(:type list)} will cause structure objects to be stored as
4669 The vector representation for structure objects has the advantage
4670 that all structure slots can be accessed quickly, although creating
4671 vectors is a bit slower in Emacs Lisp. Lists are easier to create,
4672 but take a relatively long time accessing the later slots.
4675 This option, which takes no arguments, causes a characteristic ``tag''
4676 symbol to be stored at the front of the structure object. Using
4677 @code{:type} without also using @code{:named} will result in a
4678 structure type stored as plain vectors or lists with no identifying
4681 The default, if you don't specify @code{:type} explicitly, is to
4682 use named vectors. Therefore, @code{:named} is only useful in
4683 conjunction with @code{:type}.
4686 (defstruct (person1) name age sex)
4687 (defstruct (person2 (:type list) :named) name age sex)
4688 (defstruct (person3 (:type list)) name age sex)
4690 (setq p1 (make-person1))
4691 @result{} [cl-struct-person1 nil nil nil]
4692 (setq p2 (make-person2))
4693 @result{} (person2 nil nil nil)
4694 (setq p3 (make-person3))
4695 @result{} (nil nil nil)
4702 @result{} error: function person3-p undefined
4705 Since unnamed structures don't have tags, @code{defstruct} is not
4706 able to make a useful predicate for recognizing them. Also,
4707 accessors like @code{person3-name} will be generated but they
4708 will not be able to do any type checking. The @code{person3-name}
4709 function, for example, will simply be a synonym for @code{car} in
4710 this case. By contrast, @code{person2-name} is able to verify
4711 that its argument is indeed a @code{person2} object before
4714 @item :initial-offset
4715 The argument must be a nonnegative integer. It specifies a
4716 number of slots to be left ``empty'' at the front of the
4717 structure. If the structure is named, the tag appears at the
4718 specified position in the list or vector; otherwise, the first
4719 slot appears at that position. Earlier positions are filled
4720 with @code{nil} by the constructors and ignored otherwise. If
4721 the type @code{:include}s another type, then @code{:initial-offset}
4722 specifies a number of slots to be skipped between the last slot
4723 of the included type and the first new slot.
4727 Except as noted, the @code{defstruct} facility of this package is
4728 entirely compatible with that of Common Lisp.
4734 @node Assertions, Efficiency Concerns, Structures, Top
4735 @chapter Assertions and Errors
4738 This section describes two macros that test @dfn{assertions}, i.e.,
4739 conditions which must be true if the program is operating correctly.
4740 Assertions never add to the behavior of a Lisp program; they simply
4741 make ``sanity checks'' to make sure everything is as it should be.
4743 If the optimization property @code{speed} has been set to 3, and
4744 @code{safety} is less than 3, then the byte-compiler will optimize
4745 away the following assertions. Because assertions might be optimized
4746 away, it is a bad idea for them to include side-effects.
4748 @defspec assert test-form [show-args string args@dots{}]
4749 This form verifies that @var{test-form} is true (i.e., evaluates to
4750 a non-@code{nil} value). If so, it returns @code{nil}. If the test
4751 is not satisfied, @code{assert} signals an error.
4753 A default error message will be supplied which includes @var{test-form}.
4754 You can specify a different error message by including a @var{string}
4755 argument plus optional extra arguments. Those arguments are simply
4756 passed to @code{error} to signal the error.
4758 If the optional second argument @var{show-args} is @code{t} instead
4759 of @code{nil}, then the error message (with or without @var{string})
4760 will also include all non-constant arguments of the top-level
4761 @var{form}. For example:
4764 (assert (> x 10) t "x is too small: %d")
4767 This usage of @var{show-args} is an extension to Common Lisp. In
4768 true Common Lisp, the second argument gives a list of @var{places}
4769 which can be @code{setf}'d by the user before continuing from the
4770 error. Since Emacs Lisp does not support continuable errors, it
4771 makes no sense to specify @var{places}.
4774 @defspec check-type form type [string]
4775 This form verifies that @var{form} evaluates to a value of type
4776 @var{type}. If so, it returns @code{nil}. If not, @code{check-type}
4777 signals a @code{wrong-type-argument} error. The default error message
4778 lists the erroneous value along with @var{type} and @var{form}
4779 themselves. If @var{string} is specified, it is included in the
4780 error message in place of @var{type}. For example:
4783 (check-type x (integer 1 *) "a positive integer")
4786 @xref{Type Predicates}, for a description of the type specifiers
4787 that may be used for @var{type}.
4789 Note that in Common Lisp, the first argument to @code{check-type}
4790 must be a @var{place} suitable for use by @code{setf}, because
4791 @code{check-type} signals a continuable error that allows the
4792 user to modify @var{place}.
4795 The following error-related macro is also defined:
4797 @defspec ignore-errors forms@dots{}
4798 This executes @var{forms} exactly like a @code{progn}, except that
4799 errors are ignored during the @var{forms}. More precisely, if
4800 an error is signaled then @code{ignore-errors} immediately
4801 aborts execution of the @var{forms} and returns @code{nil}.
4802 If the @var{forms} complete successfully, @code{ignore-errors}
4803 returns the result of the last @var{form}.
4806 @node Efficiency Concerns, Common Lisp Compatibility, Assertions, Top
4807 @appendix Efficiency Concerns
4812 Many of the advanced features of this package, such as @code{defun*},
4813 @code{loop}, and @code{setf}, are implemented as Lisp macros. In
4814 byte-compiled code, these complex notations will be expanded into
4815 equivalent Lisp code which is simple and efficient. For example,
4824 are expanded at compile-time to the Lisp forms
4828 (setcar p (cons x (car p)))
4832 which are the most efficient ways of doing these respective operations
4833 in Lisp. Thus, there is no performance penalty for using the more
4834 readable @code{incf} and @code{push} forms in your compiled code.
4836 @emph{Interpreted} code, on the other hand, must expand these macros
4837 every time they are executed. For this reason it is strongly
4838 recommended that code making heavy use of macros be compiled.
4839 (The features labeled ``Special Form'' instead of ``Function'' in
4840 this manual are macros.) A loop using @code{incf} a hundred times
4841 will execute considerably faster if compiled, and will also
4842 garbage-collect less because the macro expansion will not have
4843 to be generated, used, and thrown away a hundred times.
4845 You can find out how a macro expands by using the
4846 @code{cl-prettyexpand} function.
4848 @defun cl-prettyexpand form &optional full
4849 This function takes a single Lisp form as an argument and inserts
4850 a nicely formatted copy of it in the current buffer (which must be
4851 in Lisp mode so that indentation works properly). It also expands
4852 all Lisp macros which appear in the form. The easiest way to use
4853 this function is to go to the @code{*scratch*} buffer and type, say,
4856 (cl-prettyexpand '(loop for x below 10 collect x))
4860 and type @kbd{C-x C-e} immediately after the closing parenthesis;
4868 (setq G1004 (cons x G1004))
4874 will be inserted into the buffer. (The @code{block} macro is
4875 expanded differently in the interpreter and compiler, so
4876 @code{cl-prettyexpand} just leaves it alone. The temporary
4877 variable @code{G1004} was created by @code{gensym}.)
4879 If the optional argument @var{full} is true, then @emph{all}
4880 macros are expanded, including @code{block}, @code{eval-when},
4881 and compiler macros. Expansion is done as if @var{form} were
4882 a top-level form in a file being compiled. For example,
4885 (cl-prettyexpand '(pushnew 'x list))
4886 @print{} (setq list (adjoin 'x list))
4887 (cl-prettyexpand '(pushnew 'x list) t)
4888 @print{} (setq list (if (memq 'x list) list (cons 'x list)))
4889 (cl-prettyexpand '(caddr (member* 'a list)) t)
4890 @print{} (car (cdr (cdr (memq 'a list))))
4893 Note that @code{adjoin}, @code{caddr}, and @code{member*} all
4894 have built-in compiler macros to optimize them in common cases.
4902 @appendixsec Error Checking
4905 Common Lisp compliance has in general not been sacrificed for the
4906 sake of efficiency. A few exceptions have been made for cases
4907 where substantial gains were possible at the expense of marginal
4910 The Common Lisp standard (as embodied in Steele's book) uses the
4911 phrase ``it is an error if'' to indicate a situation which is not
4912 supposed to arise in complying programs; implementations are strongly
4913 encouraged but not required to signal an error in these situations.
4914 This package sometimes omits such error checking in the interest of
4915 compactness and efficiency. For example, @code{do} variable
4916 specifiers are supposed to be lists of one, two, or three forms;
4917 extra forms are ignored by this package rather than signaling a
4918 syntax error. The @code{endp} function is simply a synonym for
4919 @code{null} in this package. Functions taking keyword arguments
4920 will accept an odd number of arguments, treating the trailing
4921 keyword as if it were followed by the value @code{nil}.
4923 Argument lists (as processed by @code{defun*} and friends)
4924 @emph{are} checked rigorously except for the minor point just
4925 mentioned; in particular, keyword arguments are checked for
4926 validity, and @code{&allow-other-keys} and @code{:allow-other-keys}
4927 are fully implemented. Keyword validity checking is slightly
4928 time consuming (though not too bad in byte-compiled code);
4929 you can use @code{&allow-other-keys} to omit this check. Functions
4930 defined in this package such as @code{find} and @code{member*}
4931 do check their keyword arguments for validity.
4938 @appendixsec Optimizing Compiler
4941 Use of the optimizing Emacs compiler is highly recommended; many of the Common
4943 code which can be improved by optimization. In particular,
4944 @code{block}s (whether explicit or implicit in constructs like
4945 @code{defun*} and @code{loop}) carry a fair run-time penalty; the
4946 optimizing compiler removes @code{block}s which are not actually
4947 referenced by @code{return} or @code{return-from} inside the block.
4949 @node Common Lisp Compatibility, Old CL Compatibility, Efficiency Concerns, Top
4950 @appendix Common Lisp Compatibility
4953 Following is a list of all known incompatibilities between this
4954 package and Common Lisp as documented in Steele (2nd edition).
4956 Certain function names, such as @code{member}, @code{assoc}, and
4957 @code{floor}, were already taken by (incompatible) Emacs Lisp
4958 functions; this package appends @samp{*} to the names of its
4959 Common Lisp versions of these functions.
4961 The word @code{defun*} is required instead of @code{defun} in order
4962 to use extended Common Lisp argument lists in a function. Likewise,
4963 @code{defmacro*} and @code{function*} are versions of those forms
4964 which understand full-featured argument lists. The @code{&whole}
4965 keyword does not work in @code{defmacro} argument lists (except
4966 inside recursive argument lists).
4968 The @code{equal} predicate does not distinguish
4969 between IEEE floating-point plus and minus zero. The @code{equalp}
4970 predicate has several differences with Common Lisp; @pxref{Predicates}.
4972 The @code{setf} mechanism is entirely compatible, except that
4973 setf-methods return a list of five values rather than five
4974 values directly. Also, the new ``@code{setf} function'' concept
4975 (typified by @code{(defun (setf foo) @dots{})}) is not implemented.
4977 The @code{do-all-symbols} form is the same as @code{do-symbols}
4978 with no @var{obarray} argument. In Common Lisp, this form would
4979 iterate over all symbols in all packages. Since Emacs obarrays
4980 are not a first-class package mechanism, there is no way for
4981 @code{do-all-symbols} to locate any but the default obarray.
4983 The @code{loop} macro is complete except that @code{loop-finish}
4984 and type specifiers are unimplemented.
4986 The multiple-value return facility treats lists as multiple
4987 values, since Emacs Lisp cannot support multiple return values
4988 directly. The macros will be compatible with Common Lisp if
4989 @code{values} or @code{values-list} is always used to return to
4990 a @code{multiple-value-bind} or other multiple-value receiver;
4991 if @code{values} is used without @code{multiple-value-@dots{}}
4992 or vice-versa the effect will be different from Common Lisp.
4994 Many Common Lisp declarations are ignored, and others match
4995 the Common Lisp standard in concept but not in detail. For
4996 example, local @code{special} declarations, which are purely
4997 advisory in Emacs Lisp, do not rigorously obey the scoping rules
4998 set down in Steele's book.
5000 The variable @code{*gensym-counter*} starts out with a pseudo-random
5001 value rather than with zero. This is to cope with the fact that
5002 generated symbols become interned when they are written to and
5003 loaded back from a file.
5005 The @code{defstruct} facility is compatible, except that structures
5006 are of type @code{:type vector :named} by default rather than some
5007 special, distinct type. Also, the @code{:type} slot option is ignored.
5009 The second argument of @code{check-type} is treated differently.
5011 @node Old CL Compatibility, Porting Common Lisp, Common Lisp Compatibility, Top
5012 @appendix Old CL Compatibility
5015 Following is a list of all known incompatibilities between this package
5016 and the older Quiroz @file{cl.el} package.
5018 This package's emulation of multiple return values in functions is
5019 incompatible with that of the older package. That package attempted
5020 to come as close as possible to true Common Lisp multiple return
5021 values; unfortunately, it could not be 100% reliable and so was prone
5022 to occasional surprises if used freely. This package uses a simpler
5023 method, namely replacing multiple values with lists of values, which
5024 is more predictable though more noticeably different from Common Lisp.
5026 The @code{defkeyword} form and @code{keywordp} function are not
5027 implemented in this package.
5029 The @code{member}, @code{floor}, @code{ceiling}, @code{truncate},
5030 @code{round}, @code{mod}, and @code{rem} functions are suffixed
5031 by @samp{*} in this package to avoid collision with existing
5032 functions in Emacs. The older package simply
5033 redefined these functions, overwriting the built-in meanings and
5034 causing serious portability problems. (Some more
5035 recent versions of the Quiroz package changed the names to
5036 @code{cl-member}, etc.; this package defines the latter names as
5037 aliases for @code{member*}, etc.)
5039 Certain functions in the old package which were buggy or inconsistent
5040 with the Common Lisp standard are incompatible with the conforming
5041 versions in this package. For example, @code{eql} and @code{member}
5042 were synonyms for @code{eq} and @code{memq} in that package, @code{setf}
5043 failed to preserve correct order of evaluation of its arguments, etc.
5045 Finally, unlike the older package, this package is careful to
5046 prefix all of its internal names with @code{cl-}. Except for a
5047 few functions which are explicitly defined as additional features
5048 (such as @code{floatp-safe} and @code{letf}), this package does not
5049 export any non-@samp{cl-} symbols which are not also part of Common
5057 @appendixsec The @code{cl-compat} package
5060 The @dfn{CL} package includes emulations of some features of the
5061 old @file{cl.el}, in the form of a compatibility package
5062 @code{cl-compat}. To use it, put @code{(require 'cl-compat)} in
5065 The old package defined a number of internal routines without
5066 @code{cl-} prefixes or other annotations. Call to these routines
5067 may have crept into existing Lisp code. @code{cl-compat}
5068 provides emulations of the following internal routines:
5069 @code{pair-with-newsyms}, @code{zip-lists}, @code{unzip-lists},
5070 @code{reassemble-arglists}, @code{duplicate-symbols-p},
5073 Some @code{setf} forms translated into calls to internal
5074 functions that user code might call directly. The functions
5075 @code{setnth}, @code{setnthcdr}, and @code{setelt} fall in
5076 this category; they are defined by @code{cl-compat}, but the
5077 best fix is to change to use @code{setf} properly.
5079 The @code{cl-compat} file defines the keyword functions
5080 @code{keywordp}, @code{keyword-of}, and @code{defkeyword},
5081 which are not defined by the new @dfn{CL} package because the
5082 use of keywords as data is discouraged.
5084 The @code{build-klist} mechanism for parsing keyword arguments
5085 is emulated by @code{cl-compat}; the @code{with-keyword-args}
5086 macro is not, however, and in any case it's best to change to
5087 use the more natural keyword argument processing offered by
5090 Multiple return values are treated differently by the two
5091 Common Lisp packages. The old package's method was more
5092 compatible with true Common Lisp, though it used heuristics
5093 that caused it to report spurious multiple return values in
5094 certain cases. The @code{cl-compat} package defines a set
5095 of multiple-value macros that are compatible with the old
5096 CL package; again, they are heuristic in nature, but they
5097 are guaranteed to work in any case where the old package's
5098 macros worked. To avoid name collision with the ``official''
5099 multiple-value facilities, the ones in @code{cl-compat} have
5100 capitalized names: @code{Values}, @code{Values-list},
5101 @code{Multiple-value-bind}, etc.
5103 The functions @code{cl-floor}, @code{cl-ceiling}, @code{cl-truncate},
5104 and @code{cl-round} are defined by @code{cl-compat} to use the
5105 old-style multiple-value mechanism, just as they did in the old
5106 package. The newer @code{floor*} and friends return their two
5107 results in a list rather than as multiple values. Note that
5108 older versions of the old package used the unadorned names
5109 @code{floor}, @code{ceiling}, etc.; @code{cl-compat} cannot use
5110 these names because they conflict with Emacs built-ins.
5112 @node Porting Common Lisp, GNU Free Documentation License, Old CL Compatibility, Top
5113 @appendix Porting Common Lisp
5116 This package is meant to be used as an extension to Emacs Lisp,
5117 not as an Emacs implementation of true Common Lisp. Some of the
5118 remaining differences between Emacs Lisp and Common Lisp make it
5119 difficult to port large Common Lisp applications to Emacs. For
5120 one, some of the features in this package are not fully compliant
5121 with ANSI or Steele; @pxref{Common Lisp Compatibility}. But there
5122 are also quite a few features that this package does not provide
5123 at all. Here are some major omissions that you will want to watch out
5124 for when bringing Common Lisp code into Emacs.
5128 Case-insensitivity. Symbols in Common Lisp are case-insensitive
5129 by default. Some programs refer to a function or variable as
5130 @code{foo} in one place and @code{Foo} or @code{FOO} in another.
5131 Emacs Lisp will treat these as three distinct symbols.
5133 Some Common Lisp code is written entirely in upper case. While Emacs
5134 is happy to let the program's own functions and variables use
5135 this convention, calls to Lisp builtins like @code{if} and
5136 @code{defun} will have to be changed to lower case.
5139 Lexical scoping. In Common Lisp, function arguments and @code{let}
5140 bindings apply only to references physically within their bodies
5141 (or within macro expansions in their bodies). Emacs Lisp, by
5142 contrast, uses @dfn{dynamic scoping} wherein a binding to a
5143 variable is visible even inside functions called from the body.
5145 Variables in Common Lisp can be made dynamically scoped by
5146 declaring them @code{special} or using @code{defvar}. In Emacs
5147 Lisp it is as if all variables were declared @code{special}.
5149 Often you can use code that was written for lexical scoping
5150 even in a dynamically scoped Lisp, but not always. Here is
5151 an example of a Common Lisp code fragment that would fail in
5155 (defun map-odd-elements (func list)
5157 for flag = t then (not flag)
5158 collect (if flag x (funcall func x))))
5160 (defun add-odd-elements (list x)
5161 (map-odd-elements (lambda (a) (+ a x)) list))
5165 In Common Lisp, the two functions' usages of @code{x} are completely
5166 independent. In Emacs Lisp, the binding to @code{x} made by
5167 @code{add-odd-elements} will have been hidden by the binding
5168 in @code{map-odd-elements} by the time the @code{(+ a x)} function
5171 (This package avoids such problems in its own mapping functions
5172 by using names like @code{cl-x} instead of @code{x} internally;
5173 as long as you don't use the @code{cl-} prefix for your own
5174 variables no collision can occur.)
5176 @xref{Lexical Bindings}, for a description of the @code{lexical-let}
5177 form which establishes a Common Lisp-style lexical binding, and some
5178 examples of how it differs from Emacs' regular @code{let}.
5181 Reader macros. Common Lisp includes a second type of macro that
5182 works at the level of individual characters. For example, Common
5183 Lisp implements the quote notation by a reader macro called @code{'},
5184 whereas Emacs Lisp's parser just treats quote as a special case.
5185 Some Lisp packages use reader macros to create special syntaxes
5186 for themselves, which the Emacs parser is incapable of reading.
5189 Other syntactic features. Common Lisp provides a number of
5190 notations beginning with @code{#} that the Emacs Lisp parser
5191 won't understand. For example, @samp{#| ... |#} is an
5192 alternate comment notation, and @samp{#+lucid (foo)} tells
5193 the parser to ignore the @code{(foo)} except in Lucid Common
5197 Packages. In Common Lisp, symbols are divided into @dfn{packages}.
5198 Symbols that are Lisp built-ins are typically stored in one package;
5199 symbols that are vendor extensions are put in another, and each
5200 application program would have a package for its own symbols.
5201 Certain symbols are ``exported'' by a package and others are
5202 internal; certain packages ``use'' or import the exported symbols
5203 of other packages. To access symbols that would not normally be
5204 visible due to this importing and exporting, Common Lisp provides
5205 a syntax like @code{package:symbol} or @code{package::symbol}.
5207 Emacs Lisp has a single namespace for all interned symbols, and
5208 then uses a naming convention of putting a prefix like @code{cl-}
5209 in front of the name. Some Emacs packages adopt the Common Lisp-like
5210 convention of using @code{cl:} or @code{cl::} as the prefix.
5211 However, the Emacs parser does not understand colons and just
5212 treats them as part of the symbol name. Thus, while @code{mapcar}
5213 and @code{lisp:mapcar} may refer to the same symbol in Common
5214 Lisp, they are totally distinct in Emacs Lisp. Common Lisp
5215 programs which refer to a symbol by the full name sometimes
5216 and the short name other times will not port cleanly to Emacs.
5218 Emacs Lisp does have a concept of ``obarrays,'' which are
5219 package-like collections of symbols, but this feature is not
5220 strong enough to be used as a true package mechanism.
5223 The @code{format} function is quite different between Common
5224 Lisp and Emacs Lisp. It takes an additional ``destination''
5225 argument before the format string. A destination of @code{nil}
5226 means to format to a string as in Emacs Lisp; a destination
5227 of @code{t} means to write to the terminal (similar to
5228 @code{message} in Emacs). Also, format control strings are
5229 utterly different; @code{~} is used instead of @code{%} to
5230 introduce format codes, and the set of available codes is
5231 much richer. There are no notations like @code{\n} for
5232 string literals; instead, @code{format} is used with the
5233 ``newline'' format code, @code{~%}. More advanced formatting
5234 codes provide such features as paragraph filling, case
5235 conversion, and even loops and conditionals.
5237 While it would have been possible to implement most of Common
5238 Lisp @code{format} in this package (under the name @code{format*},
5239 of course), it was not deemed worthwhile. It would have required
5240 a huge amount of code to implement even a decent subset of
5241 @code{format*}, yet the functionality it would provide over
5242 Emacs Lisp's @code{format} would rarely be useful.
5245 Vector constants use square brackets in Emacs Lisp, but
5246 @code{#(a b c)} notation in Common Lisp. To further complicate
5247 matters, Emacs has its own @code{#(} notation for
5248 something entirely different---strings with properties.
5251 Characters are distinct from integers in Common Lisp. The notation
5252 for character constants is also different: @code{#\A} in Common Lisp
5253 where Emacs Lisp uses @code{?A}. Also, @code{string=} and
5254 @code{string-equal} are synonyms in Emacs Lisp, whereas the latter is
5255 case-insensitive in Common Lisp.
5258 Data types. Some Common Lisp data types do not exist in Emacs
5259 Lisp. Rational numbers and complex numbers are not present,
5260 nor are large integers (all integers are ``fixnums''). All
5261 arrays are one-dimensional. There are no readtables or pathnames;
5262 streams are a set of existing data types rather than a new data
5263 type of their own. Hash tables, random-states, structures, and
5264 packages (obarrays) are built from Lisp vectors or lists rather
5265 than being distinct types.
5268 The Common Lisp Object System (CLOS) is not implemented,
5269 nor is the Common Lisp Condition System. However, the EIEIO package
5270 from @uref{ftp://ftp.ultranet.com/pub/zappo} does implement some
5274 Common Lisp features that are completely redundant with Emacs
5275 Lisp features of a different name generally have not been
5276 implemented. For example, Common Lisp writes @code{defconstant}
5277 where Emacs Lisp uses @code{defconst}. Similarly, @code{make-list}
5278 takes its arguments in different ways in the two Lisps but does
5279 exactly the same thing, so this package has not bothered to
5280 implement a Common Lisp-style @code{make-list}.
5283 A few more notable Common Lisp features not included in this
5284 package: @code{compiler-let}, @code{tagbody}, @code{prog},
5285 @code{ldb/dpb}, @code{parse-integer}, @code{cerror}.
5288 Recursion. While recursion works in Emacs Lisp just like it
5289 does in Common Lisp, various details of the Emacs Lisp system
5290 and compiler make recursion much less efficient than it is in
5291 most Lisps. Some schools of thought prefer to use recursion
5292 in Lisp over other techniques; they would sum a list of
5293 numbers using something like
5296 (defun sum-list (list)
5298 (+ (car list) (sum-list (cdr list)))
5303 where a more iteratively-minded programmer might write one of
5307 (let ((total 0)) (dolist (x my-list) (incf total x)) total)
5308 (loop for x in my-list sum x)
5311 While this would be mainly a stylistic choice in most Common Lisps,
5312 in Emacs Lisp you should be aware that the iterative forms are
5313 much faster than recursion. Also, Lisp programmers will want to
5314 note that the current Emacs Lisp compiler does not optimize tail
5318 @node GNU Free Documentation License, Function Index, Porting Common Lisp, Top
5319 @appendix GNU Free Documentation License
5320 @include doclicense.texi
5322 @node Function Index, Variable Index, GNU Free Documentation License, Top
5323 @unnumbered Function Index
5327 @node Variable Index, , Function Index, Top
5328 @unnumbered Variable Index
5332 @setchapternewpage odd
5337 arch-tag: b61e7200-3bfa-4a70-a9d3-095e152696f8