* text.texi (Special Properties): Fix typo.
[emacs.git] / doc / misc / cl.texi
blob755b2f3f1b70494108ca7e37858d190848aea355
1 \input texinfo    @c -*-texinfo-*-
2 @setfilename ../../info/cl
3 @settitle Common Lisp Extensions
5 @copying
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, 2010  Free Software Foundation, Inc.
11 @quotation
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.''
22 @end quotation
23 @end copying
25 @dircategory Emacs
26 @direntry
27 * CL: (cl).                     Partial Common Lisp support for Emacs Lisp.
28 @end direntry
30 @finalout
32 @titlepage
33 @sp 6
34 @center @titlefont{Common Lisp Extensions}
35 @sp 4
36 @center For GNU Emacs Lisp
37 @sp 1
38 @center Version 2.02
39 @sp 5
40 @center Dave Gillespie
41 @center daveg@@synaptics.com
42 @page
43 @vskip 0pt plus 1filll
44 @insertcopying
45 @end titlepage
47 @contents
49 @node Top, Overview, (dir), (dir)
50 @chapter Introduction
52 @noindent
53 This document describes a set of Emacs Lisp facilities borrowed from
54 Common Lisp.  All the facilities are described here in detail.  While
55 this document does not assume any prior knowledge of Common Lisp, it
56 does assume a basic familiarity with Emacs Lisp.
58 @ifnottex
59 @insertcopying
60 @end ifnottex
62 @menu
63 * Overview::             Installation, usage, etc.
64 * Program Structure::    Arglists, `eval-when', `defalias'
65 * Predicates::           `typep' and `equalp'
66 * Control Structure::    `setf', `do', `loop', etc.
67 * Macros::               Destructuring, `define-compiler-macro'
68 * Declarations::         `proclaim', `declare', etc.
69 * Symbols::              Property lists, `gensym'
70 * Numbers::              Predicates, functions, random numbers
71 * Sequences::            Mapping, functions, searching, sorting
72 * Lists::                `caddr', `sublis', `member*', `assoc*', etc.
73 * Structures::           `defstruct'
74 * Assertions::           `check-type', `assert', `ignore-errors'.
76 * Efficiency Concerns::         Hints and techniques
77 * Common Lisp Compatibility::   All known differences with Steele
78 * Old CL Compatibility::        All known differences with old cl.el
79 * Porting Common Lisp::         Hints for porting Common Lisp code
81 * GNU Free Documentation License:: The license for this documentation.
82 * Function Index::
83 * Variable Index::
84 @end menu
86 @node Overview, Program Structure, Top, Top
87 @ifnottex
88 @chapter Overview
89 @end ifnottex
91 @noindent
92 Common Lisp is a huge language, and Common Lisp systems tend to be
93 massive and extremely complex.  Emacs Lisp, by contrast, is rather
94 minimalist in the choice of Lisp features it offers the programmer.
95 As Emacs Lisp programmers have grown in number, and the applications
96 they write have grown more ambitious, it has become clear that Emacs
97 Lisp could benefit from many of the conveniences of Common Lisp.
99 The @dfn{CL} package adds a number of Common Lisp functions and
100 control structures to Emacs Lisp.  While not a 100% complete
101 implementation of Common Lisp, @dfn{CL} adds enough functionality
102 to make Emacs Lisp programming significantly more convenient.
104 @strong{Please note:} the @dfn{CL} functions are not standard parts of
105 the Emacs Lisp name space, so it is legitimate for users to define
106 them with other, conflicting meanings.  To avoid conflicting with
107 those user activities, we have a policy that packages installed in
108 Emacs must not load @dfn{CL} at run time.  (It is ok for them to load
109 @dfn{CL} at compile time only, with @code{eval-when-compile}, and use
110 the macros it provides.)  If you are writing packages that you plan to
111 distribute and invite widespread use for, you might want to observe
112 the same rule.
114 Some Common Lisp features have been omitted from this package
115 for various reasons:
117 @itemize @bullet
118 @item
119 Some features are too complex or bulky relative to their benefit
120 to Emacs Lisp programmers.  CLOS and Common Lisp streams are fine
121 examples of this group.
123 @item
124 Other features cannot be implemented without modification to the
125 Emacs Lisp interpreter itself, such as multiple return values,
126 lexical scoping, case-insensitive symbols, and complex numbers.
127 The @dfn{CL} package generally makes no attempt to emulate these
128 features.
130 @item
131 Some features conflict with existing things in Emacs Lisp.  For
132 example, Emacs' @code{assoc} function is incompatible with the
133 Common Lisp @code{assoc}.  In such cases, this package usually
134 adds the suffix @samp{*} to the function name of the Common
135 Lisp version of the function (e.g., @code{assoc*}).
136 @end itemize
138 The package described here was written by Dave Gillespie,
139 @file{daveg@@synaptics.com}.  It is a total rewrite of the original
140 1986 @file{cl.el} package by Cesar Quiroz.  Most features of the
141 Quiroz package have been retained; any incompatibilities are
142 noted in the descriptions below.  Care has been taken in this
143 version to ensure that each function is defined efficiently,
144 concisely, and with minimal impact on the rest of the Emacs
145 environment.
147 @menu
148 * Usage::                How to use the CL package
149 * Organization::         The package's five component files
150 * Installation::         Compiling and installing CL
151 * Naming Conventions::   Notes on CL function names
152 @end menu
154 @node Usage, Organization, Overview, Overview
155 @section Usage
157 @noindent
158 Lisp code that uses features from the @dfn{CL} package should
159 include at the beginning:
161 @example
162 (require 'cl)
163 @end example
165 @noindent
166 If you want to ensure that the new (Gillespie) version of @dfn{CL}
167 is the one that is present, add an additional @code{(require 'cl-19)}
168 call:
170 @example
171 (require 'cl)
172 (require 'cl-19)
173 @end example
175 @noindent
176 The second call will fail (with ``@file{cl-19.el} not found'') if
177 the old @file{cl.el} package was in use.
179 It is safe to arrange to load @dfn{CL} at all times, e.g.,
180 in your @file{.emacs} file.  But it's a good idea, for portability,
181 to @code{(require 'cl)} in your code even if you do this.
183 @node Organization, Installation, Usage, Overview
184 @section Organization
186 @noindent
187 The Common Lisp package is organized into four files:
189 @table @file
190 @item cl.el
191 This is the ``main'' file, which contains basic functions
192 and information about the package.  This file is relatively
193 compact---about 700 lines.
195 @item cl-extra.el
196 This file contains the larger, more complex or unusual functions.
197 It is kept separate so that packages which only want to use Common
198 Lisp fundamentals like the @code{cadr} function won't need to pay
199 the overhead of loading the more advanced functions.
201 @item cl-seq.el
202 This file contains most of the advanced functions for operating
203 on sequences or lists, such as @code{delete-if} and @code{assoc*}.
205 @item cl-macs.el
206 This file contains the features of the packages which are macros
207 instead of functions.  Macros expand when the caller is compiled,
208 not when it is run, so the macros generally only need to be
209 present when the byte-compiler is running (or when the macros are
210 used in uncompiled code such as a @file{.emacs} file).  Most of
211 the macros of this package are isolated in @file{cl-macs.el} so
212 that they won't take up memory unless you are compiling.
213 @end table
215 The file @file{cl.el} includes all necessary @code{autoload}
216 commands for the functions and macros in the other three files.
217 All you have to do is @code{(require 'cl)}, and @file{cl.el}
218 will take care of pulling in the other files when they are
219 needed.
221 There is another file, @file{cl-compat.el}, which defines some
222 routines from the older @file{cl.el} package that are no longer
223 present in the new package.  This includes internal routines
224 like @code{setelt} and @code{zip-lists}, deprecated features
225 like @code{defkeyword}, and an emulation of the old-style
226 multiple-values feature.  @xref{Old CL Compatibility}.
228 @node Installation, Naming Conventions, Organization, Overview
229 @section Installation
231 @noindent
232 Installation of the @dfn{CL} package is simple:  Just put the
233 byte-compiled files @file{cl.elc}, @file{cl-extra.elc},
234 @file{cl-seq.elc}, @file{cl-macs.elc}, and @file{cl-compat.elc}
235 into a directory on your @code{load-path}.
237 There are no special requirements to compile this package:
238 The files do not have to be loaded before they are compiled,
239 nor do they need to be compiled in any particular order.
241 You may choose to put the files into your main @file{lisp/}
242 directory, replacing the original @file{cl.el} file there.  Or,
243 you could put them into a directory that comes before @file{lisp/}
244 on your @code{load-path} so that the old @file{cl.el} is
245 effectively hidden.
247 Also, format the @file{cl.texinfo} file and put the resulting
248 Info files in the @file{info/} directory or another suitable place.
250 You may instead wish to leave this package's components all in
251 their own directory, and then add this directory to your
252 @code{load-path} and @code{Info-directory-list}.
253 Add the directory to the front of the list so the old @dfn{CL}
254 package and its documentation are hidden.
256 @node Naming Conventions,  , Installation, Overview
257 @section Naming Conventions
259 @noindent
260 Except where noted, all functions defined by this package have the
261 same names and calling conventions as their Common Lisp counterparts.
263 Following is a complete list of functions whose names were changed
264 from Common Lisp, usually to avoid conflicts with Emacs.  In each
265 case, a @samp{*} has been appended to the Common Lisp name to obtain
266 the Emacs name:
268 @example
269 defun*        defsubst*     defmacro*     function*
270 member*       assoc*        rassoc*       get*
271 remove*       delete*       mapcar*       sort*
272 floor*        ceiling*      truncate*     round*
273 mod*          rem*          random*
274 @end example
276 Internal function and variable names in the package are prefixed
277 by @code{cl-}.  Here is a complete list of functions @emph{not}
278 prefixed by @code{cl-} which were not taken from Common Lisp:
280 @example
281 floatp-safe   lexical-let   lexical-let*
282 callf         callf2        letf          letf*
283 defsubst*
284 @end example
286 The following simple functions and macros are defined in @file{cl.el};
287 they do not cause other components like @file{cl-extra} to be loaded.
289 @example
290 floatp-safe   endp
291 evenp         oddp          plusp         minusp
292 caaar .. cddddr
293 list*         ldiff         rest          first .. tenth
294 copy-list     subst         mapcar* [2]
295 adjoin [3]    acons         pairlis       pop [4]
296 push [4]      pushnew [3,4] incf [4]      decf [4]
297 proclaim      declaim
298 @end example
300 @noindent
301 [2] Only for one sequence argument or two list arguments.
303 @noindent
304 [3] Only if @code{:test} is @code{eq}, @code{equal}, or unspecified,
305 and @code{:key} is not used.
307 @noindent
308 [4] Only when @var{place} is a plain variable name.
310 @iftex
311 @chapno=4
312 @end iftex
314 @node Program Structure, Predicates, Overview, Top
315 @chapter Program Structure
317 @noindent
318 This section describes features of the @dfn{CL} package which have to
319 do with programs as a whole: advanced argument lists for functions,
320 and the @code{eval-when} construct.
322 @menu
323 * Argument Lists::       `&key', `&aux', `defun*', `defmacro*'.
324 * Time of Evaluation::   The `eval-when' construct.
325 @end menu
327 @iftex
328 @secno=1
329 @end iftex
331 @node Argument Lists, Time of Evaluation, Program Structure, Program Structure
332 @section Argument Lists
334 @noindent
335 Emacs Lisp's notation for argument lists of functions is a subset of
336 the Common Lisp notation.  As well as the familiar @code{&optional}
337 and @code{&rest} markers, Common Lisp allows you to specify default
338 values for optional arguments, and it provides the additional markers
339 @code{&key} and @code{&aux}.
341 Since argument parsing is built-in to Emacs, there is no way for
342 this package to implement Common Lisp argument lists seamlessly.
343 Instead, this package defines alternates for several Lisp forms
344 which you must use if you need Common Lisp argument lists.
346 @defspec defun* name arglist body...
347 This form is identical to the regular @code{defun} form, except
348 that @var{arglist} is allowed to be a full Common Lisp argument
349 list.  Also, the function body is enclosed in an implicit block
350 called @var{name}; @pxref{Blocks and Exits}.
351 @end defspec
353 @defspec defsubst* name arglist body...
354 This is just like @code{defun*}, except that the function that
355 is defined is automatically proclaimed @code{inline}, i.e.,
356 calls to it may be expanded into in-line code by the byte compiler.
357 This is analogous to the @code{defsubst} form;
358 @code{defsubst*} uses a different method (compiler macros) which
359 works in all versions of Emacs, and also generates somewhat more
360 efficient inline expansions.  In particular, @code{defsubst*}
361 arranges for the processing of keyword arguments, default values,
362 etc., to be done at compile-time whenever possible.
363 @end defspec
365 @defspec defmacro* name arglist body...
366 This is identical to the regular @code{defmacro} form,
367 except that @var{arglist} is allowed to be a full Common Lisp
368 argument list.  The @code{&environment} keyword is supported as
369 described in Steele.  The @code{&whole} keyword is supported only
370 within destructured lists (see below); top-level @code{&whole}
371 cannot be implemented with the current Emacs Lisp interpreter.
372 The macro expander body is enclosed in an implicit block called
373 @var{name}.
374 @end defspec
376 @defspec function* symbol-or-lambda
377 This is identical to the regular @code{function} form,
378 except that if the argument is a @code{lambda} form then that
379 form may use a full Common Lisp argument list.
380 @end defspec
382 Also, all forms (such as @code{defsetf} and @code{flet}) defined
383 in this package that include @var{arglist}s in their syntax allow
384 full Common Lisp argument lists.
386 Note that it is @emph{not} necessary to use @code{defun*} in
387 order to have access to most @dfn{CL} features in your function.
388 These features are always present; @code{defun*}'s only
389 difference from @code{defun} is its more flexible argument
390 lists and its implicit block.
392 The full form of a Common Lisp argument list is
394 @example
395 (@var{var}...
396  &optional (@var{var} @var{initform} @var{svar})...
397  &rest @var{var}
398  &key ((@var{keyword} @var{var}) @var{initform} @var{svar})...
399  &aux (@var{var} @var{initform})...)
400 @end example
402 Each of the five argument list sections is optional.  The @var{svar},
403 @var{initform}, and @var{keyword} parts are optional; if they are
404 omitted, then @samp{(@var{var})} may be written simply @samp{@var{var}}.
406 The first section consists of zero or more @dfn{required} arguments.
407 These arguments must always be specified in a call to the function;
408 there is no difference between Emacs Lisp and Common Lisp as far as
409 required arguments are concerned.
411 The second section consists of @dfn{optional} arguments.  These
412 arguments may be specified in the function call; if they are not,
413 @var{initform} specifies the default value used for the argument.
414 (No @var{initform} means to use @code{nil} as the default.)  The
415 @var{initform} is evaluated with the bindings for the preceding
416 arguments already established; @code{(a &optional (b (1+ a)))}
417 matches one or two arguments, with the second argument defaulting
418 to one plus the first argument.  If the @var{svar} is specified,
419 it is an auxiliary variable which is bound to @code{t} if the optional
420 argument was specified, or to @code{nil} if the argument was omitted.
421 If you don't use an @var{svar}, then there will be no way for your
422 function to tell whether it was called with no argument, or with
423 the default value passed explicitly as an argument.
425 The third section consists of a single @dfn{rest} argument.  If
426 more arguments were passed to the function than are accounted for
427 by the required and optional arguments, those extra arguments are
428 collected into a list and bound to the ``rest'' argument variable.
429 Common Lisp's @code{&rest} is equivalent to that of Emacs Lisp.
430 Common Lisp accepts @code{&body} as a synonym for @code{&rest} in
431 macro contexts; this package accepts it all the time.
433 The fourth section consists of @dfn{keyword} arguments.  These
434 are optional arguments which are specified by name rather than
435 positionally in the argument list.  For example,
437 @example
438 (defun* foo (a &optional b &key c d (e 17)))
439 @end example
441 @noindent
442 defines a function which may be called with one, two, or more
443 arguments.  The first two arguments are bound to @code{a} and
444 @code{b} in the usual way.  The remaining arguments must be
445 pairs of the form @code{:c}, @code{:d}, or @code{:e} followed
446 by the value to be bound to the corresponding argument variable.
447 (Symbols whose names begin with a colon are called @dfn{keywords},
448 and they are self-quoting in the same way as @code{nil} and
449 @code{t}.)
451 For example, the call @code{(foo 1 2 :d 3 :c 4)} sets the five
452 arguments to 1, 2, 4, 3, and 17, respectively.  If the same keyword
453 appears more than once in the function call, the first occurrence
454 takes precedence over the later ones.  Note that it is not possible
455 to specify keyword arguments without specifying the optional
456 argument @code{b} as well, since @code{(foo 1 :c 2)} would bind
457 @code{b} to the keyword @code{:c}, then signal an error because
458 @code{2} is not a valid keyword.
460 You can also explicitly specify the keyword argument; it need not be
461 simply the variable name prefixed with a colon.  For example,
463 @example
464 (defun* bar (&key (a 1) ((baz b) 4)))
465 @end example
467 @noindent
469 specifies a keyword @code{:a} that sets the variable @code{a} with
470 default value 1, as well as a keyword @code{baz} that sets the
471 variable @code{b} with default value 4.  In this case, because
472 @code{baz} is not self-quoting, you must quote it explicitly in the
473 function call, like this:
475 @example
476 (bar :a 10 'baz 42)
477 @end example
479 Ordinarily, it is an error to pass an unrecognized keyword to
480 a function, e.g., @code{(foo 1 2 :c 3 :goober 4)}.  You can ask
481 Lisp to ignore unrecognized keywords, either by adding the
482 marker @code{&allow-other-keys} after the keyword section
483 of the argument list, or by specifying an @code{:allow-other-keys}
484 argument in the call whose value is non-@code{nil}.  If the
485 function uses both @code{&rest} and @code{&key} at the same time,
486 the ``rest'' argument is bound to the keyword list as it appears
487 in the call.  For example:
489 @smallexample
490 (defun* find-thing (thing &rest rest &key need &allow-other-keys)
491   (or (apply 'member* thing thing-list :allow-other-keys t rest)
492       (if need (error "Thing not found"))))
493 @end smallexample
495 @noindent
496 This function takes a @code{:need} keyword argument, but also
497 accepts other keyword arguments which are passed on to the
498 @code{member*} function.  @code{allow-other-keys} is used to
499 keep both @code{find-thing} and @code{member*} from complaining
500 about each others' keywords in the arguments.
502 The fifth section of the argument list consists of @dfn{auxiliary
503 variables}.  These are not really arguments at all, but simply
504 variables which are bound to @code{nil} or to the specified
505 @var{initforms} during execution of the function.  There is no
506 difference between the following two functions, except for a
507 matter of stylistic taste:
509 @example
510 (defun* foo (a b &aux (c (+ a b)) d)
511   @var{body})
513 (defun* foo (a b)
514   (let ((c (+ a b)) d)
515     @var{body}))
516 @end example
518 Argument lists support @dfn{destructuring}.  In Common Lisp,
519 destructuring is only allowed with @code{defmacro}; this package
520 allows it with @code{defun*} and other argument lists as well.
521 In destructuring, any argument variable (@var{var} in the above
522 diagram) can be replaced by a list of variables, or more generally,
523 a recursive argument list.  The corresponding argument value must
524 be a list whose elements match this recursive argument list.
525 For example:
527 @example
528 (defmacro* dolist ((var listform &optional resultform)
529                    &rest body)
530   ...)
531 @end example
533 This says that the first argument of @code{dolist} must be a list
534 of two or three items; if there are other arguments as well as this
535 list, they are stored in @code{body}.  All features allowed in
536 regular argument lists are allowed in these recursive argument lists.
537 In addition, the clause @samp{&whole @var{var}} is allowed at the
538 front of a recursive argument list.  It binds @var{var} to the
539 whole list being matched; thus @code{(&whole all a b)} matches
540 a list of two things, with @code{a} bound to the first thing,
541 @code{b} bound to the second thing, and @code{all} bound to the
542 list itself.  (Common Lisp allows @code{&whole} in top-level
543 @code{defmacro} argument lists as well, but Emacs Lisp does not
544 support this usage.)
546 One last feature of destructuring is that the argument list may be
547 dotted, so that the argument list @code{(a b . c)} is functionally
548 equivalent to @code{(a b &rest c)}.
550 If the optimization quality @code{safety} is set to 0
551 (@pxref{Declarations}), error checking for wrong number of
552 arguments and invalid keyword arguments is disabled.  By default,
553 argument lists are rigorously checked.
555 @node Time of Evaluation,  , Argument Lists, Program Structure
556 @section Time of Evaluation
558 @noindent
559 Normally, the byte-compiler does not actually execute the forms in
560 a file it compiles.  For example, if a file contains @code{(setq foo t)},
561 the act of compiling it will not actually set @code{foo} to @code{t}.
562 This is true even if the @code{setq} was a top-level form (i.e., not
563 enclosed in a @code{defun} or other form).  Sometimes, though, you
564 would like to have certain top-level forms evaluated at compile-time.
565 For example, the compiler effectively evaluates @code{defmacro} forms
566 at compile-time so that later parts of the file can refer to the
567 macros that are defined.
569 @defspec eval-when (situations...) forms...
570 This form controls when the body @var{forms} are evaluated.
571 The @var{situations} list may contain any set of the symbols
572 @code{compile}, @code{load}, and @code{eval} (or their long-winded
573 ANSI equivalents, @code{:compile-toplevel}, @code{:load-toplevel},
574 and @code{:execute}).
576 The @code{eval-when} form is handled differently depending on
577 whether or not it is being compiled as a top-level form.
578 Specifically, it gets special treatment if it is being compiled
579 by a command such as @code{byte-compile-file} which compiles files
580 or buffers of code, and it appears either literally at the
581 top level of the file or inside a top-level @code{progn}.
583 For compiled top-level @code{eval-when}s, the body @var{forms} are
584 executed at compile-time if @code{compile} is in the @var{situations}
585 list, and the @var{forms} are written out to the file (to be executed
586 at load-time) if @code{load} is in the @var{situations} list.
588 For non-compiled-top-level forms, only the @code{eval} situation is
589 relevant.  (This includes forms executed by the interpreter, forms
590 compiled with @code{byte-compile} rather than @code{byte-compile-file},
591 and non-top-level forms.)  The @code{eval-when} acts like a
592 @code{progn} if @code{eval} is specified, and like @code{nil}
593 (ignoring the body @var{forms}) if not.
595 The rules become more subtle when @code{eval-when}s are nested;
596 consult Steele (second edition) for the gruesome details (and
597 some gruesome examples).
599 Some simple examples:
601 @example
602 ;; Top-level forms in foo.el:
603 (eval-when (compile)           (setq foo1 'bar))
604 (eval-when (load)              (setq foo2 'bar))
605 (eval-when (compile load)      (setq foo3 'bar))
606 (eval-when (eval)              (setq foo4 'bar))
607 (eval-when (eval compile)      (setq foo5 'bar))
608 (eval-when (eval load)         (setq foo6 'bar))
609 (eval-when (eval compile load) (setq foo7 'bar))
610 @end example
612 When @file{foo.el} is compiled, these variables will be set during
613 the compilation itself:
615 @example
616 foo1  foo3  foo5  foo7      ; `compile'
617 @end example
619 When @file{foo.elc} is loaded, these variables will be set:
621 @example
622 foo2  foo3  foo6  foo7      ; `load'
623 @end example
625 And if @file{foo.el} is loaded uncompiled, these variables will
626 be set:
628 @example
629 foo4  foo5  foo6  foo7      ; `eval'
630 @end example
632 If these seven @code{eval-when}s had been, say, inside a @code{defun},
633 then the first three would have been equivalent to @code{nil} and the
634 last four would have been equivalent to the corresponding @code{setq}s.
636 Note that @code{(eval-when (load eval) @dots{})} is equivalent
637 to @code{(progn @dots{})} in all contexts.  The compiler treats
638 certain top-level forms, like @code{defmacro} (sort-of) and
639 @code{require}, as if they were wrapped in @code{(eval-when
640 (compile load eval) @dots{})}.
641 @end defspec
643 Emacs includes two special forms related to @code{eval-when}.
644 One of these, @code{eval-when-compile}, is not quite equivalent to
645 any @code{eval-when} construct and is described below.
647 The other form, @code{(eval-and-compile @dots{})}, is exactly
648 equivalent to @samp{(eval-when (compile load eval) @dots{})} and
649 so is not itself defined by this package.
651 @defspec eval-when-compile forms...
652 The @var{forms} are evaluated at compile-time; at execution time,
653 this form acts like a quoted constant of the resulting value.  Used
654 at top-level, @code{eval-when-compile} is just like @samp{eval-when
655 (compile eval)}.  In other contexts, @code{eval-when-compile}
656 allows code to be evaluated once at compile-time for efficiency
657 or other reasons.
659 This form is similar to the @samp{#.} syntax of true Common Lisp.
660 @end defspec
662 @defspec load-time-value form
663 The @var{form} is evaluated at load-time; at execution time,
664 this form acts like a quoted constant of the resulting value.
666 Early Common Lisp had a @samp{#,} syntax that was similar to
667 this, but ANSI Common Lisp replaced it with @code{load-time-value}
668 and gave it more well-defined semantics.
670 In a compiled file, @code{load-time-value} arranges for @var{form}
671 to be evaluated when the @file{.elc} file is loaded and then used
672 as if it were a quoted constant.  In code compiled by
673 @code{byte-compile} rather than @code{byte-compile-file}, the
674 effect is identical to @code{eval-when-compile}.  In uncompiled
675 code, both @code{eval-when-compile} and @code{load-time-value}
676 act exactly like @code{progn}.
678 @example
679 (defun report ()
680   (insert "This function was executed on: "
681           (current-time-string)
682           ", compiled on: "
683           (eval-when-compile (current-time-string))
684           ;; or '#.(current-time-string) in real Common Lisp
685           ", and loaded on: "
686           (load-time-value (current-time-string))))
687 @end example
689 @noindent
690 Byte-compiled, the above defun will result in the following code
691 (or its compiled equivalent, of course) in the @file{.elc} file:
693 @example
694 (setq --temp-- (current-time-string))
695 (defun report ()
696   (insert "This function was executed on: "
697           (current-time-string)
698           ", compiled on: "
699           '"Wed Jun 23 18:33:43 1993"
700           ", and loaded on: "
701           --temp--))
702 @end example
703 @end defspec
705 @node Predicates, Control Structure, Program Structure, Top
706 @chapter Predicates
708 @noindent
709 This section describes functions for testing whether various
710 facts are true or false.
712 @menu
713 * Type Predicates::      `typep', `deftype', and `coerce'
714 * Equality Predicates::  `equalp'
715 @end menu
717 @node Type Predicates, Equality Predicates, Predicates, Predicates
718 @section Type Predicates
720 @noindent
721 The @dfn{CL} package defines a version of the Common Lisp @code{typep}
722 predicate.
724 @defun typep object type
725 Check if @var{object} is of type @var{type}, where @var{type} is a
726 (quoted) type name of the sort used by Common Lisp.  For example,
727 @code{(typep foo 'integer)} is equivalent to @code{(integerp foo)}.
728 @end defun
730 The @var{type} argument to the above function is either a symbol
731 or a list beginning with a symbol.
733 @itemize @bullet
734 @item
735 If the type name is a symbol, Emacs appends @samp{-p} to the
736 symbol name to form the name of a predicate function for testing
737 the type.  (Built-in predicates whose names end in @samp{p} rather
738 than @samp{-p} are used when appropriate.)
740 @item
741 The type symbol @code{t} stands for the union of all types.
742 @code{(typep @var{object} t)} is always true.  Likewise, the
743 type symbol @code{nil} stands for nothing at all, and
744 @code{(typep @var{object} nil)} is always false.
746 @item
747 The type symbol @code{null} represents the symbol @code{nil}.
748 Thus @code{(typep @var{object} 'null)} is equivalent to
749 @code{(null @var{object})}.
751 @item
752 The type symbol @code{atom} represents all objects that are not cons
753 cells. Thus @code{(typep @var{object} 'atom)} is equivalent to
754 @code{(atom @var{object})}.
756 @item
757 The type symbol @code{real} is a synonym for @code{number}, and
758 @code{fixnum} is a synonym for @code{integer}.
760 @item
761 The type symbols @code{character} and @code{string-char} match
762 integers in the range from 0 to 255.
764 @item
765 The type symbol @code{float} uses the @code{floatp-safe} predicate
766 defined by this package rather than @code{floatp}, so it will work
767 correctly even in Emacs versions without floating-point support.
769 @item
770 The type list @code{(integer @var{low} @var{high})} represents all
771 integers between @var{low} and @var{high}, inclusive.  Either bound
772 may be a list of a single integer to specify an exclusive limit,
773 or a @code{*} to specify no limit.  The type @code{(integer * *)}
774 is thus equivalent to @code{integer}.
776 @item
777 Likewise, lists beginning with @code{float}, @code{real}, or
778 @code{number} represent numbers of that type falling in a particular
779 range.
781 @item
782 Lists beginning with @code{and}, @code{or}, and @code{not} form
783 combinations of types.  For example, @code{(or integer (float 0 *))}
784 represents all objects that are integers or non-negative floats.
786 @item
787 Lists beginning with @code{member} or @code{member*} represent
788 objects @code{eql} to any of the following values.  For example,
789 @code{(member 1 2 3 4)} is equivalent to @code{(integer 1 4)},
790 and @code{(member nil)} is equivalent to @code{null}.
792 @item
793 Lists of the form @code{(satisfies @var{predicate})} represent
794 all objects for which @var{predicate} returns true when called
795 with that object as an argument.
796 @end itemize
798 The following function and macro (not technically predicates) are
799 related to @code{typep}.
801 @defun coerce object type
802 This function attempts to convert @var{object} to the specified
803 @var{type}.  If @var{object} is already of that type as determined by
804 @code{typep}, it is simply returned.  Otherwise, certain types of
805 conversions will be made:  If @var{type} is any sequence type
806 (@code{string}, @code{list}, etc.) then @var{object} will be
807 converted to that type if possible.  If @var{type} is
808 @code{character}, then strings of length one and symbols with
809 one-character names can be coerced.  If @var{type} is @code{float},
810 then integers can be coerced in versions of Emacs that support
811 floats.  In all other circumstances, @code{coerce} signals an
812 error.
813 @end defun
815 @defspec deftype name arglist forms...
816 This macro defines a new type called @var{name}.  It is similar
817 to @code{defmacro} in many ways; when @var{name} is encountered
818 as a type name, the body @var{forms} are evaluated and should
819 return a type specifier that is equivalent to the type.  The
820 @var{arglist} is a Common Lisp argument list of the sort accepted
821 by @code{defmacro*}.  The type specifier @samp{(@var{name} @var{args}...)}
822 is expanded by calling the expander with those arguments; the type
823 symbol @samp{@var{name}} is expanded by calling the expander with
824 no arguments.  The @var{arglist} is processed the same as for
825 @code{defmacro*} except that optional arguments without explicit
826 defaults use @code{*} instead of @code{nil} as the ``default''
827 default.  Some examples:
829 @example
830 (deftype null () '(satisfies null))    ; predefined
831 (deftype list () '(or null cons))      ; predefined
832 (deftype unsigned-byte (&optional bits)
833   (list 'integer 0 (if (eq bits '*) bits (1- (lsh 1 bits)))))
834 (unsigned-byte 8)  @equiv{}  (integer 0 255)
835 (unsigned-byte)  @equiv{}  (integer 0 *)
836 unsigned-byte  @equiv{}  (integer 0 *)
837 @end example
839 @noindent
840 The last example shows how the Common Lisp @code{unsigned-byte}
841 type specifier could be implemented if desired; this package does
842 not implement @code{unsigned-byte} by default.
843 @end defspec
845 The @code{typecase} and @code{check-type} macros also use type
846 names.  @xref{Conditionals}.  @xref{Assertions}.  The @code{map},
847 @code{concatenate}, and @code{merge} functions take type-name
848 arguments to specify the type of sequence to return.  @xref{Sequences}.
850 @node Equality Predicates,  , Type Predicates, Predicates
851 @section Equality Predicates
853 @noindent
854 This package defines the Common Lisp predicate @code{equalp}.
856 @defun equalp a b
857 This function is a more flexible version of @code{equal}.  In
858 particular, it compares strings case-insensitively, and it compares
859 numbers without regard to type (so that @code{(equalp 3 3.0)} is
860 true).  Vectors and conses are compared recursively.  All other
861 objects are compared as if by @code{equal}.
863 This function differs from Common Lisp @code{equalp} in several
864 respects.  First, Common Lisp's @code{equalp} also compares
865 @emph{characters} case-insensitively, which would be impractical
866 in this package since Emacs does not distinguish between integers
867 and characters.  In keeping with the idea that strings are less
868 vector-like in Emacs Lisp, this package's @code{equalp} also will
869 not compare strings against vectors of integers.
870 @end defun
872 Also note that the Common Lisp functions @code{member} and @code{assoc}
873 use @code{eql} to compare elements, whereas Emacs Lisp follows the
874 MacLisp tradition and uses @code{equal} for these two functions.
875 In Emacs, use @code{member*} and @code{assoc*} to get functions
876 which use @code{eql} for comparisons.
878 @node Control Structure, Macros, Predicates, Top
879 @chapter Control Structure
881 @noindent
882 The features described in the following sections implement
883 various advanced control structures, including the powerful
884 @code{setf} facility and a number of looping and conditional
885 constructs.
887 @menu
888 * Assignment::             The `psetq' form
889 * Generalized Variables::  `setf', `incf', `push', etc.
890 * Variable Bindings::      `progv', `lexical-let', `flet', `macrolet'
891 * Conditionals::           `case', `typecase'
892 * Blocks and Exits::       `block', `return', `return-from'
893 * Iteration::              `do', `dotimes', `dolist', `do-symbols'
894 * Loop Facility::          The Common Lisp `loop' macro
895 * Multiple Values::        `values', `multiple-value-bind', etc.
896 @end menu
898 @node Assignment, Generalized Variables, Control Structure, Control Structure
899 @section Assignment
901 @noindent
902 The @code{psetq} form is just like @code{setq}, except that multiple
903 assignments are done in parallel rather than sequentially.
905 @defspec psetq [symbol form]@dots{}
906 This special form (actually a macro) is used to assign to several
907 variables simultaneously.  Given only one @var{symbol} and @var{form},
908 it has the same effect as @code{setq}.  Given several @var{symbol}
909 and @var{form} pairs, it evaluates all the @var{form}s in advance
910 and then stores the corresponding variables afterwards.
912 @example
913 (setq x 2 y 3)
914 (setq x (+ x y)  y (* x y))
916      @result{} 5
917 y                     ; @r{@code{y} was computed after @code{x} was set.}
918      @result{} 15
919 (setq x 2 y 3)
920 (psetq x (+ x y)  y (* x y))
922      @result{} 5
923 y                     ; @r{@code{y} was computed before @code{x} was set.}
924      @result{} 6
925 @end example
927 The simplest use of @code{psetq} is @code{(psetq x y y x)}, which
928 exchanges the values of two variables.  (The @code{rotatef} form
929 provides an even more convenient way to swap two variables;
930 @pxref{Modify Macros}.)
932 @code{psetq} always returns @code{nil}.
933 @end defspec
935 @node Generalized Variables, Variable Bindings, Assignment, Control Structure
936 @section Generalized Variables
938 @noindent
939 A ``generalized variable'' or ``place form'' is one of the many places
940 in Lisp memory where values can be stored.  The simplest place form is
941 a regular Lisp variable.  But the cars and cdrs of lists, elements
942 of arrays, properties of symbols, and many other locations are also
943 places where Lisp values are stored.
945 The @code{setf} form is like @code{setq}, except that it accepts
946 arbitrary place forms on the left side rather than just
947 symbols.  For example, @code{(setf (car a) b)} sets the car of
948 @code{a} to @code{b}, doing the same operation as @code{(setcar a b)}
949 but without having to remember two separate functions for setting
950 and accessing every type of place.
952 Generalized variables are analogous to ``lvalues'' in the C
953 language, where @samp{x = a[i]} gets an element from an array
954 and @samp{a[i] = x} stores an element using the same notation.
955 Just as certain forms like @code{a[i]} can be lvalues in C, there
956 is a set of forms that can be generalized variables in Lisp.
958 @menu
959 * Basic Setf::         `setf' and place forms
960 * Modify Macros::      `incf', `push', `rotatef', `letf', `callf', etc.
961 * Customizing Setf::   `define-modify-macro', `defsetf', `define-setf-method'
962 @end menu
964 @node Basic Setf, Modify Macros, Generalized Variables, Generalized Variables
965 @subsection Basic Setf
967 @noindent
968 The @code{setf} macro is the most basic way to operate on generalized
969 variables.
971 @defspec setf [place form]@dots{}
972 This macro evaluates @var{form} and stores it in @var{place}, which
973 must be a valid generalized variable form.  If there are several
974 @var{place} and @var{form} pairs, the assignments are done sequentially
975 just as with @code{setq}.  @code{setf} returns the value of the last
976 @var{form}.
978 The following Lisp forms will work as generalized variables, and
979 so may appear in the @var{place} argument of @code{setf}:
981 @itemize @bullet
982 @item
983 A symbol naming a variable.  In other words, @code{(setf x y)} is
984 exactly equivalent to @code{(setq x y)}, and @code{setq} itself is
985 strictly speaking redundant now that @code{setf} exists.  Many
986 programmers continue to prefer @code{setq} for setting simple
987 variables, though, purely for stylistic or historical reasons.
988 The macro @code{(setf x y)} actually expands to @code{(setq x y)},
989 so there is no performance penalty for using it in compiled code.
991 @item
992 A call to any of the following Lisp functions:
994 @smallexample
995 car                 cdr                 caar .. cddddr
996 nth                 rest                first .. tenth
997 aref                elt                 nthcdr
998 symbol-function     symbol-value        symbol-plist
999 get                 get*                getf
1000 gethash             subseq
1001 @end smallexample
1003 @noindent
1004 Note that for @code{nthcdr} and @code{getf}, the list argument
1005 of the function must itself be a valid @var{place} form.  For
1006 example, @code{(setf (nthcdr 0 foo) 7)} will set @code{foo} itself
1007 to 7.  Note that @code{push} and @code{pop} on an @code{nthcdr}
1008 place can be used to insert or delete at any position in a list.
1009 The use of @code{nthcdr} as a @var{place} form is an extension
1010 to standard Common Lisp.
1012 @item
1013 The following Emacs-specific functions are also @code{setf}-able.
1015 @smallexample
1016 buffer-file-name                  marker-position
1017 buffer-modified-p                 match-data
1018 buffer-name                       mouse-position
1019 buffer-string                     overlay-end
1020 buffer-substring                  overlay-get
1021 current-buffer                    overlay-start
1022 current-case-table                point
1023 current-column                    point-marker
1024 current-global-map                point-max
1025 current-input-mode                point-min
1026 current-local-map                 process-buffer
1027 current-window-configuration      process-filter
1028 default-file-modes                process-sentinel
1029 default-value                     read-mouse-position
1030 documentation-property            screen-height
1031 extent-data                       screen-menubar
1032 extent-end-position               screen-width
1033 extent-start-position             selected-window
1034 face-background                   selected-screen
1035 face-background-pixmap            selected-frame
1036 face-font                         standard-case-table
1037 face-foreground                   syntax-table
1038 face-underline-p                  window-buffer
1039 file-modes                        window-dedicated-p
1040 frame-height                      window-display-table
1041 frame-parameters                  window-height
1042 frame-visible-p                   window-hscroll
1043 frame-width                       window-point
1044 get-register                      window-start
1045 getenv                            window-width
1046 global-key-binding                x-get-cut-buffer
1047 keymap-parent                     x-get-cutbuffer
1048 local-key-binding                 x-get-secondary-selection
1049 mark                              x-get-selection
1050 mark-marker
1051 @end smallexample
1053 Most of these have directly corresponding ``set'' functions, like
1054 @code{use-local-map} for @code{current-local-map}, or @code{goto-char}
1055 for @code{point}.  A few, like @code{point-min}, expand to longer
1056 sequences of code when they are @code{setf}'d (@code{(narrow-to-region
1057 x (point-max))} in this case).
1059 @item
1060 A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])},
1061 where @var{subplace} is itself a valid generalized variable whose
1062 current value is a string, and where the value stored is also a
1063 string.  The new string is spliced into the specified part of the
1064 destination string.  For example:
1066 @example
1067 (setq a (list "hello" "world"))
1068      @result{} ("hello" "world")
1069 (cadr a)
1070      @result{} "world"
1071 (substring (cadr a) 2 4)
1072      @result{} "rl"
1073 (setf (substring (cadr a) 2 4) "o")
1074      @result{} "o"
1075 (cadr a)
1076      @result{} "wood"
1078      @result{} ("hello" "wood")
1079 @end example
1081 The generalized variable @code{buffer-substring}, listed above,
1082 also works in this way by replacing a portion of the current buffer.
1084 @item
1085 A call of the form @code{(apply '@var{func} @dots{})} or
1086 @code{(apply (function @var{func}) @dots{})}, where @var{func}
1087 is a @code{setf}-able function whose store function is ``suitable''
1088 in the sense described in Steele's book; since none of the standard
1089 Emacs place functions are suitable in this sense, this feature is
1090 only interesting when used with places you define yourself with
1091 @code{define-setf-method} or the long form of @code{defsetf}.
1093 @item
1094 A macro call, in which case the macro is expanded and @code{setf}
1095 is applied to the resulting form.
1097 @item
1098 Any form for which a @code{defsetf} or @code{define-setf-method}
1099 has been made.
1100 @end itemize
1102 Using any forms other than these in the @var{place} argument to
1103 @code{setf} will signal an error.
1105 The @code{setf} macro takes care to evaluate all subforms in
1106 the proper left-to-right order; for example,
1108 @example
1109 (setf (aref vec (incf i)) i)
1110 @end example
1112 @noindent
1113 looks like it will evaluate @code{(incf i)} exactly once, before the
1114 following access to @code{i}; the @code{setf} expander will insert
1115 temporary variables as necessary to ensure that it does in fact work
1116 this way no matter what setf-method is defined for @code{aref}.
1117 (In this case, @code{aset} would be used and no such steps would
1118 be necessary since @code{aset} takes its arguments in a convenient
1119 order.)
1121 However, if the @var{place} form is a macro which explicitly
1122 evaluates its arguments in an unusual order, this unusual order
1123 will be preserved.  Adapting an example from Steele, given
1125 @example
1126 (defmacro wrong-order (x y) (list 'aref y x))
1127 @end example
1129 @noindent
1130 the form @code{(setf (wrong-order @var{a} @var{b}) 17)} will
1131 evaluate @var{b} first, then @var{a}, just as in an actual call
1132 to @code{wrong-order}.
1133 @end defspec
1135 @node Modify Macros, Customizing Setf, Basic Setf, Generalized Variables
1136 @subsection Modify Macros
1138 @noindent
1139 This package defines a number of other macros besides @code{setf}
1140 that operate on generalized variables.  Many are interesting and
1141 useful even when the @var{place} is just a variable name.
1143 @defspec psetf [place form]@dots{}
1144 This macro is to @code{setf} what @code{psetq} is to @code{setq}:
1145 When several @var{place}s and @var{form}s are involved, the
1146 assignments take place in parallel rather than sequentially.
1147 Specifically, all subforms are evaluated from left to right, then
1148 all the assignments are done (in an undefined order).
1149 @end defspec
1151 @defspec incf place &optional x
1152 This macro increments the number stored in @var{place} by one, or
1153 by @var{x} if specified.  The incremented value is returned.  For
1154 example, @code{(incf i)} is equivalent to @code{(setq i (1+ i))}, and
1155 @code{(incf (car x) 2)} is equivalent to @code{(setcar x (+ (car x) 2))}.
1157 Once again, care is taken to preserve the ``apparent'' order of
1158 evaluation.  For example,
1160 @example
1161 (incf (aref vec (incf i)))
1162 @end example
1164 @noindent
1165 appears to increment @code{i} once, then increment the element of
1166 @code{vec} addressed by @code{i}; this is indeed exactly what it
1167 does, which means the above form is @emph{not} equivalent to the
1168 ``obvious'' expansion,
1170 @example
1171 (setf (aref vec (incf i)) (1+ (aref vec (incf i))))   ; Wrong!
1172 @end example
1174 @noindent
1175 but rather to something more like
1177 @example
1178 (let ((temp (incf i)))
1179   (setf (aref vec temp) (1+ (aref vec temp))))
1180 @end example
1182 @noindent
1183 Again, all of this is taken care of automatically by @code{incf} and
1184 the other generalized-variable macros.
1186 As a more Emacs-specific example of @code{incf}, the expression
1187 @code{(incf (point) @var{n})} is essentially equivalent to
1188 @code{(forward-char @var{n})}.
1189 @end defspec
1191 @defspec decf place &optional x
1192 This macro decrements the number stored in @var{place} by one, or
1193 by @var{x} if specified.
1194 @end defspec
1196 @defspec pop place
1197 This macro removes and returns the first element of the list stored
1198 in @var{place}.  It is analogous to @code{(prog1 (car @var{place})
1199 (setf @var{place} (cdr @var{place})))}, except that it takes care
1200 to evaluate all subforms only once.
1201 @end defspec
1203 @defspec push x place
1204 This macro inserts @var{x} at the front of the list stored in
1205 @var{place}.  It is analogous to @code{(setf @var{place} (cons
1206 @var{x} @var{place}))}, except for evaluation of the subforms.
1207 @end defspec
1209 @defspec pushnew x place @t{&key :test :test-not :key}
1210 This macro inserts @var{x} at the front of the list stored in
1211 @var{place}, but only if @var{x} was not @code{eql} to any
1212 existing element of the list.  The optional keyword arguments
1213 are interpreted in the same way as for @code{adjoin}.
1214 @xref{Lists as Sets}.
1215 @end defspec
1217 @defspec shiftf place@dots{} newvalue
1218 This macro shifts the @var{place}s left by one, shifting in the
1219 value of @var{newvalue} (which may be any Lisp expression, not just
1220 a generalized variable), and returning the value shifted out of
1221 the first @var{place}.  Thus, @code{(shiftf @var{a} @var{b} @var{c}
1222 @var{d})} is equivalent to
1224 @example
1225 (prog1
1226     @var{a}
1227   (psetf @var{a} @var{b}
1228          @var{b} @var{c}
1229          @var{c} @var{d}))
1230 @end example
1232 @noindent
1233 except that the subforms of @var{a}, @var{b}, and @var{c} are actually
1234 evaluated only once each and in the apparent order.
1235 @end defspec
1237 @defspec rotatef place@dots{}
1238 This macro rotates the @var{place}s left by one in circular fashion.
1239 Thus, @code{(rotatef @var{a} @var{b} @var{c} @var{d})} is equivalent to
1241 @example
1242 (psetf @var{a} @var{b}
1243        @var{b} @var{c}
1244        @var{c} @var{d}
1245        @var{d} @var{a})
1246 @end example
1248 @noindent
1249 except for the evaluation of subforms.  @code{rotatef} always
1250 returns @code{nil}.  Note that @code{(rotatef @var{a} @var{b})}
1251 conveniently exchanges @var{a} and @var{b}.
1252 @end defspec
1254 The following macros were invented for this package; they have no
1255 analogues in Common Lisp.
1257 @defspec letf (bindings@dots{}) forms@dots{}
1258 This macro is analogous to @code{let}, but for generalized variables
1259 rather than just symbols.  Each @var{binding} should be of the form
1260 @code{(@var{place} @var{value})}; the original contents of the
1261 @var{place}s are saved, the @var{value}s are stored in them, and
1262 then the body @var{form}s are executed.  Afterwards, the @var{places}
1263 are set back to their original saved contents.  This cleanup happens
1264 even if the @var{form}s exit irregularly due to a @code{throw} or an
1265 error.
1267 For example,
1269 @example
1270 (letf (((point) (point-min))
1271        (a 17))
1272   ...)
1273 @end example
1275 @noindent
1276 moves ``point'' in the current buffer to the beginning of the buffer,
1277 and also binds @code{a} to 17 (as if by a normal @code{let}, since
1278 @code{a} is just a regular variable).  After the body exits, @code{a}
1279 is set back to its original value and point is moved back to its
1280 original position.
1282 Note that @code{letf} on @code{(point)} is not quite like a
1283 @code{save-excursion}, as the latter effectively saves a marker
1284 which tracks insertions and deletions in the buffer.  Actually,
1285 a @code{letf} of @code{(point-marker)} is much closer to this
1286 behavior.  (@code{point} and @code{point-marker} are equivalent
1287 as @code{setf} places; each will accept either an integer or a
1288 marker as the stored value.)
1290 Since generalized variables look like lists, @code{let}'s shorthand
1291 of using @samp{foo} for @samp{(foo nil)} as a @var{binding} would
1292 be ambiguous in @code{letf} and is not allowed.
1294 However, a @var{binding} specifier may be a one-element list
1295 @samp{(@var{place})}, which is similar to @samp{(@var{place}
1296 @var{place})}.  In other words, the @var{place} is not disturbed
1297 on entry to the body, and the only effect of the @code{letf} is
1298 to restore the original value of @var{place} afterwards.  (The
1299 redundant access-and-store suggested by the @code{(@var{place}
1300 @var{place})} example does not actually occur.)
1302 In most cases, the @var{place} must have a well-defined value on
1303 entry to the @code{letf} form.  The only exceptions are plain
1304 variables and calls to @code{symbol-value} and @code{symbol-function}.
1305 If the symbol is not bound on entry, it is simply made unbound by
1306 @code{makunbound} or @code{fmakunbound} on exit.
1307 @end defspec
1309 @defspec letf* (bindings@dots{}) forms@dots{}
1310 This macro is to @code{letf} what @code{let*} is to @code{let}:
1311 It does the bindings in sequential rather than parallel order.
1312 @end defspec
1314 @defspec callf @var{function} @var{place} @var{args}@dots{}
1315 This is the ``generic'' modify macro.  It calls @var{function},
1316 which should be an unquoted function name, macro name, or lambda.
1317 It passes @var{place} and @var{args} as arguments, and assigns the
1318 result back to @var{place}.  For example, @code{(incf @var{place}
1319 @var{n})} is the same as @code{(callf + @var{place} @var{n})}.
1320 Some more examples:
1322 @example
1323 (callf abs my-number)
1324 (callf concat (buffer-name) "<" (int-to-string n) ">")
1325 (callf union happy-people (list joe bob) :test 'same-person)
1326 @end example
1328 @xref{Customizing Setf}, for @code{define-modify-macro}, a way
1329 to create even more concise notations for modify macros.  Note
1330 again that @code{callf} is an extension to standard Common Lisp.
1331 @end defspec
1333 @defspec callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{}
1334 This macro is like @code{callf}, except that @var{place} is
1335 the @emph{second} argument of @var{function} rather than the
1336 first.  For example, @code{(push @var{x} @var{place})} is
1337 equivalent to @code{(callf2 cons @var{x} @var{place})}.
1338 @end defspec
1340 The @code{callf} and @code{callf2} macros serve as building
1341 blocks for other macros like @code{incf}, @code{pushnew}, and
1342 @code{define-modify-macro}.  The @code{letf} and @code{letf*}
1343 macros are used in the processing of symbol macros;
1344 @pxref{Macro Bindings}.
1346 @node Customizing Setf,  , Modify Macros, Generalized Variables
1347 @subsection Customizing Setf
1349 @noindent
1350 Common Lisp defines three macros, @code{define-modify-macro},
1351 @code{defsetf}, and @code{define-setf-method}, that allow the
1352 user to extend generalized variables in various ways.
1354 @defspec define-modify-macro name arglist function [doc-string]
1355 This macro defines a ``read-modify-write'' macro similar to
1356 @code{incf} and @code{decf}.  The macro @var{name} is defined
1357 to take a @var{place} argument followed by additional arguments
1358 described by @var{arglist}.  The call
1360 @example
1361 (@var{name} @var{place} @var{args}...)
1362 @end example
1364 @noindent
1365 will be expanded to
1367 @example
1368 (callf @var{func} @var{place} @var{args}...)
1369 @end example
1371 @noindent
1372 which in turn is roughly equivalent to
1374 @example
1375 (setf @var{place} (@var{func} @var{place} @var{args}...))
1376 @end example
1378 For example:
1380 @example
1381 (define-modify-macro incf (&optional (n 1)) +)
1382 (define-modify-macro concatf (&rest args) concat)
1383 @end example
1385 Note that @code{&key} is not allowed in @var{arglist}, but
1386 @code{&rest} is sufficient to pass keywords on to the function.
1388 Most of the modify macros defined by Common Lisp do not exactly
1389 follow the pattern of @code{define-modify-macro}.  For example,
1390 @code{push} takes its arguments in the wrong order, and @code{pop}
1391 is completely irregular.  You can define these macros ``by hand''
1392 using @code{get-setf-method}, or consult the source file
1393 @file{cl-macs.el} to see how to use the internal @code{setf}
1394 building blocks.
1395 @end defspec
1397 @defspec defsetf access-fn update-fn
1398 This is the simpler of two @code{defsetf} forms.  Where
1399 @var{access-fn} is the name of a function which accesses a place,
1400 this declares @var{update-fn} to be the corresponding store
1401 function.  From now on,
1403 @example
1404 (setf (@var{access-fn} @var{arg1} @var{arg2} @var{arg3}) @var{value})
1405 @end example
1407 @noindent
1408 will be expanded to
1410 @example
1411 (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} @var{value})
1412 @end example
1414 @noindent
1415 The @var{update-fn} is required to be either a true function, or
1416 a macro which evaluates its arguments in a function-like way.  Also,
1417 the @var{update-fn} is expected to return @var{value} as its result.
1418 Otherwise, the above expansion would not obey the rules for the way
1419 @code{setf} is supposed to behave.
1421 As a special (non-Common-Lisp) extension, a third argument of @code{t}
1422 to @code{defsetf} says that the @code{update-fn}'s return value is
1423 not suitable, so that the above @code{setf} should be expanded to
1424 something more like
1426 @example
1427 (let ((temp @var{value}))
1428   (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} temp)
1429   temp)
1430 @end example
1432 Some examples of the use of @code{defsetf}, drawn from the standard
1433 suite of setf methods, are:
1435 @example
1436 (defsetf car setcar)
1437 (defsetf symbol-value set)
1438 (defsetf buffer-name rename-buffer t)
1439 @end example
1440 @end defspec
1442 @defspec defsetf access-fn arglist (store-var) forms@dots{}
1443 This is the second, more complex, form of @code{defsetf}.  It is
1444 rather like @code{defmacro} except for the additional @var{store-var}
1445 argument.  The @var{forms} should return a Lisp form which stores
1446 the value of @var{store-var} into the generalized variable formed
1447 by a call to @var{access-fn} with arguments described by @var{arglist}.
1448 The @var{forms} may begin with a string which documents the @code{setf}
1449 method (analogous to the doc string that appears at the front of a
1450 function).
1452 For example, the simple form of @code{defsetf} is shorthand for
1454 @example
1455 (defsetf @var{access-fn} (&rest args) (store)
1456   (append '(@var{update-fn}) args (list store)))
1457 @end example
1459 The Lisp form that is returned can access the arguments from
1460 @var{arglist} and @var{store-var} in an unrestricted fashion;
1461 macros like @code{setf} and @code{incf} which invoke this
1462 setf-method will insert temporary variables as needed to make
1463 sure the apparent order of evaluation is preserved.
1465 Another example drawn from the standard package:
1467 @example
1468 (defsetf nth (n x) (store)
1469   (list 'setcar (list 'nthcdr n x) store))
1470 @end example
1471 @end defspec
1473 @defspec define-setf-method access-fn arglist forms@dots{}
1474 This is the most general way to create new place forms.  When
1475 a @code{setf} to @var{access-fn} with arguments described by
1476 @var{arglist} is expanded, the @var{forms} are evaluated and
1477 must return a list of five items:
1479 @enumerate
1480 @item
1481 A list of @dfn{temporary variables}.
1483 @item
1484 A list of @dfn{value forms} corresponding to the temporary variables
1485 above.  The temporary variables will be bound to these value forms
1486 as the first step of any operation on the generalized variable.
1488 @item
1489 A list of exactly one @dfn{store variable} (generally obtained
1490 from a call to @code{gensym}).
1492 @item
1493 A Lisp form which stores the contents of the store variable into
1494 the generalized variable, assuming the temporaries have been
1495 bound as described above.
1497 @item
1498 A Lisp form which accesses the contents of the generalized variable,
1499 assuming the temporaries have been bound.
1500 @end enumerate
1502 This is exactly like the Common Lisp macro of the same name,
1503 except that the method returns a list of five values rather
1504 than the five values themselves, since Emacs Lisp does not
1505 support Common Lisp's notion of multiple return values.
1507 Once again, the @var{forms} may begin with a documentation string.
1509 A setf-method should be maximally conservative with regard to
1510 temporary variables.  In the setf-methods generated by
1511 @code{defsetf}, the second return value is simply the list of
1512 arguments in the place form, and the first return value is a
1513 list of a corresponding number of temporary variables generated
1514 by @code{gensym}.  Macros like @code{setf} and @code{incf} which
1515 use this setf-method will optimize away most temporaries that
1516 turn out to be unnecessary, so there is little reason for the
1517 setf-method itself to optimize.
1518 @end defspec
1520 @defun get-setf-method place &optional env
1521 This function returns the setf-method for @var{place}, by
1522 invoking the definition previously recorded by @code{defsetf}
1523 or @code{define-setf-method}.  The result is a list of five
1524 values as described above.  You can use this function to build
1525 your own @code{incf}-like modify macros.  (Actually, it is
1526 better to use the internal functions @code{cl-setf-do-modify}
1527 and @code{cl-setf-do-store}, which are a bit easier to use and
1528 which also do a number of optimizations; consult the source
1529 code for the @code{incf} function for a simple example.)
1531 The argument @var{env} specifies the ``environment'' to be
1532 passed on to @code{macroexpand} if @code{get-setf-method} should
1533 need to expand a macro in @var{place}.  It should come from
1534 an @code{&environment} argument to the macro or setf-method
1535 that called @code{get-setf-method}.
1537 See also the source code for the setf-methods for @code{apply}
1538 and @code{substring}, each of which works by calling
1539 @code{get-setf-method} on a simpler case, then massaging
1540 the result in various ways.
1541 @end defun
1543 Modern Common Lisp defines a second, independent way to specify
1544 the @code{setf} behavior of a function, namely ``@code{setf}
1545 functions'' whose names are lists @code{(setf @var{name})}
1546 rather than symbols.  For example, @code{(defun (setf foo) @dots{})}
1547 defines the function that is used when @code{setf} is applied to
1548 @code{foo}.  This package does not currently support @code{setf}
1549 functions.  In particular, it is a compile-time error to use
1550 @code{setf} on a form which has not already been @code{defsetf}'d
1551 or otherwise declared; in newer Common Lisps, this would not be
1552 an error since the function @code{(setf @var{func})} might be
1553 defined later.
1555 @iftex
1556 @secno=4
1557 @end iftex
1559 @node Variable Bindings, Conditionals, Generalized Variables, Control Structure
1560 @section Variable Bindings
1562 @noindent
1563 These Lisp forms make bindings to variables and function names,
1564 analogous to Lisp's built-in @code{let} form.
1566 @xref{Modify Macros}, for the @code{letf} and @code{letf*} forms which
1567 are also related to variable bindings.
1569 @menu
1570 * Dynamic Bindings::     The `progv' form
1571 * Lexical Bindings::     `lexical-let' and lexical closures
1572 * Function Bindings::    `flet' and `labels'
1573 * Macro Bindings::       `macrolet' and `symbol-macrolet'
1574 @end menu
1576 @node Dynamic Bindings, Lexical Bindings, Variable Bindings, Variable Bindings
1577 @subsection Dynamic Bindings
1579 @noindent
1580 The standard @code{let} form binds variables whose names are known
1581 at compile-time.  The @code{progv} form provides an easy way to
1582 bind variables whose names are computed at run-time.
1584 @defspec progv symbols values forms@dots{}
1585 This form establishes @code{let}-style variable bindings on a
1586 set of variables computed at run-time.  The expressions
1587 @var{symbols} and @var{values} are evaluated, and must return lists
1588 of symbols and values, respectively.  The symbols are bound to the
1589 corresponding values for the duration of the body @var{form}s.
1590 If @var{values} is shorter than @var{symbols}, the last few symbols
1591 are made unbound (as if by @code{makunbound}) inside the body.
1592 If @var{symbols} is shorter than @var{values}, the excess values
1593 are ignored.
1594 @end defspec
1596 @node Lexical Bindings, Function Bindings, Dynamic Bindings, Variable Bindings
1597 @subsection Lexical Bindings
1599 @noindent
1600 The @dfn{CL} package defines the following macro which
1601 more closely follows the Common Lisp @code{let} form:
1603 @defspec lexical-let (bindings@dots{}) forms@dots{}
1604 This form is exactly like @code{let} except that the bindings it
1605 establishes are purely lexical.  Lexical bindings are similar to
1606 local variables in a language like C:  Only the code physically
1607 within the body of the @code{lexical-let} (after macro expansion)
1608 may refer to the bound variables.
1610 @example
1611 (setq a 5)
1612 (defun foo (b) (+ a b))
1613 (let ((a 2)) (foo a))
1614      @result{} 4
1615 (lexical-let ((a 2)) (foo a))
1616      @result{} 7
1617 @end example
1619 @noindent
1620 In this example, a regular @code{let} binding of @code{a} actually
1621 makes a temporary change to the global variable @code{a}, so @code{foo}
1622 is able to see the binding of @code{a} to 2.  But @code{lexical-let}
1623 actually creates a distinct local variable @code{a} for use within its
1624 body, without any effect on the global variable of the same name.
1626 The most important use of lexical bindings is to create @dfn{closures}.
1627 A closure is a function object that refers to an outside lexical
1628 variable.  For example:
1630 @example
1631 (defun make-adder (n)
1632   (lexical-let ((n n))
1633     (function (lambda (m) (+ n m)))))
1634 (setq add17 (make-adder 17))
1635 (funcall add17 4)
1636      @result{} 21
1637 @end example
1639 @noindent
1640 The call @code{(make-adder 17)} returns a function object which adds
1641 17 to its argument.  If @code{let} had been used instead of
1642 @code{lexical-let}, the function object would have referred to the
1643 global @code{n}, which would have been bound to 17 only during the
1644 call to @code{make-adder} itself.
1646 @example
1647 (defun make-counter ()
1648   (lexical-let ((n 0))
1649     (function* (lambda (&optional (m 1)) (incf n m)))))
1650 (setq count-1 (make-counter))
1651 (funcall count-1 3)
1652      @result{} 3
1653 (funcall count-1 14)
1654      @result{} 17
1655 (setq count-2 (make-counter))
1656 (funcall count-2 5)
1657      @result{} 5
1658 (funcall count-1 2)
1659      @result{} 19
1660 (funcall count-2)
1661      @result{} 6
1662 @end example
1664 @noindent
1665 Here we see that each call to @code{make-counter} creates a distinct
1666 local variable @code{n}, which serves as a private counter for the
1667 function object that is returned.
1669 Closed-over lexical variables persist until the last reference to
1670 them goes away, just like all other Lisp objects.  For example,
1671 @code{count-2} refers to a function object which refers to an
1672 instance of the variable @code{n}; this is the only reference
1673 to that variable, so after @code{(setq count-2 nil)} the garbage
1674 collector would be able to delete this instance of @code{n}.
1675 Of course, if a @code{lexical-let} does not actually create any
1676 closures, then the lexical variables are free as soon as the
1677 @code{lexical-let} returns.
1679 Many closures are used only during the extent of the bindings they
1680 refer to; these are known as ``downward funargs'' in Lisp parlance.
1681 When a closure is used in this way, regular Emacs Lisp dynamic
1682 bindings suffice and will be more efficient than @code{lexical-let}
1683 closures:
1685 @example
1686 (defun add-to-list (x list)
1687   (mapcar (lambda (y) (+ x y))) list)
1688 (add-to-list 7 '(1 2 5))
1689      @result{} (8 9 12)
1690 @end example
1692 @noindent
1693 Since this lambda is only used while @code{x} is still bound,
1694 it is not necessary to make a true closure out of it.
1696 You can use @code{defun} or @code{flet} inside a @code{lexical-let}
1697 to create a named closure.  If several closures are created in the
1698 body of a single @code{lexical-let}, they all close over the same
1699 instance of the lexical variable.
1701 The @code{lexical-let} form is an extension to Common Lisp.  In
1702 true Common Lisp, all bindings are lexical unless declared otherwise.
1703 @end defspec
1705 @defspec lexical-let* (bindings@dots{}) forms@dots{}
1706 This form is just like @code{lexical-let}, except that the bindings
1707 are made sequentially in the manner of @code{let*}.
1708 @end defspec
1710 @node Function Bindings, Macro Bindings, Lexical Bindings, Variable Bindings
1711 @subsection Function Bindings
1713 @noindent
1714 These forms make @code{let}-like bindings to functions instead
1715 of variables.
1717 @defspec flet (bindings@dots{}) forms@dots{}
1718 This form establishes @code{let}-style bindings on the function
1719 cells of symbols rather than on the value cells.  Each @var{binding}
1720 must be a list of the form @samp{(@var{name} @var{arglist}
1721 @var{forms}@dots{})}, which defines a function exactly as if
1722 it were a @code{defun*} form.  The function @var{name} is defined
1723 accordingly for the duration of the body of the @code{flet}; then
1724 the old function definition, or lack thereof, is restored.
1726 While @code{flet} in Common Lisp establishes a lexical binding of
1727 @var{name}, Emacs Lisp @code{flet} makes a dynamic binding.  The
1728 result is that @code{flet} affects indirect calls to a function as
1729 well as calls directly inside the @code{flet} form itself.
1731 You can use @code{flet} to disable or modify the behavior of a
1732 function in a temporary fashion.  This will even work on Emacs
1733 primitives, although note that some calls to primitive functions
1734 internal to Emacs are made without going through the symbol's
1735 function cell, and so will not be affected by @code{flet}.  For
1736 example,
1738 @example
1739 (flet ((message (&rest args) (push args saved-msgs)))
1740   (do-something))
1741 @end example
1743 This code attempts to replace the built-in function @code{message}
1744 with a function that simply saves the messages in a list rather
1745 than displaying them.  The original definition of @code{message}
1746 will be restored after @code{do-something} exits.  This code will
1747 work fine on messages generated by other Lisp code, but messages
1748 generated directly inside Emacs will not be caught since they make
1749 direct C-language calls to the message routines rather than going
1750 through the Lisp @code{message} function.
1752 @c Bug#411.
1753 Also note that many primitives (e.g. @code{+}) have special byte-compile
1754 handling.  Attempts to redefine such functions using @code{flet} will
1755 fail if byte-compiled.  In such cases, use @code{labels} instead.
1757 Functions defined by @code{flet} may use the full Common Lisp
1758 argument notation supported by @code{defun*}; also, the function
1759 body is enclosed in an implicit block as if by @code{defun*}.
1760 @xref{Program Structure}.
1761 @end defspec
1763 @defspec labels (bindings@dots{}) forms@dots{}
1764 The @code{labels} form is like @code{flet}, except that it
1765 makes lexical bindings of the function names rather than
1766 dynamic bindings.  (In true Common Lisp, both @code{flet} and
1767 @code{labels} make lexical bindings of slightly different sorts;
1768 since Emacs Lisp is dynamically bound by default, it seemed
1769 more appropriate for @code{flet} also to use dynamic binding.
1770 The @code{labels} form, with its lexical binding, is fully
1771 compatible with Common Lisp.)
1773 Lexical scoping means that all references to the named
1774 functions must appear physically within the body of the
1775 @code{labels} form.  References may appear both in the body
1776 @var{forms} of @code{labels} itself, and in the bodies of
1777 the functions themselves.  Thus, @code{labels} can define
1778 local recursive functions, or mutually-recursive sets of
1779 functions.
1781 A ``reference'' to a function name is either a call to that
1782 function, or a use of its name quoted by @code{quote} or
1783 @code{function} to be passed on to, say, @code{mapcar}.
1784 @end defspec
1786 @node Macro Bindings,  , Function Bindings, Variable Bindings
1787 @subsection Macro Bindings
1789 @noindent
1790 These forms create local macros and ``symbol macros.''
1792 @defspec macrolet (bindings@dots{}) forms@dots{}
1793 This form is analogous to @code{flet}, but for macros instead of
1794 functions.  Each @var{binding} is a list of the same form as the
1795 arguments to @code{defmacro*} (i.e., a macro name, argument list,
1796 and macro-expander forms).  The macro is defined accordingly for
1797 use within the body of the @code{macrolet}.
1799 Because of the nature of macros, @code{macrolet} is lexically
1800 scoped even in Emacs Lisp:  The @code{macrolet} binding will
1801 affect only calls that appear physically within the body
1802 @var{forms}, possibly after expansion of other macros in the
1803 body.
1804 @end defspec
1806 @defspec symbol-macrolet (bindings@dots{}) forms@dots{}
1807 This form creates @dfn{symbol macros}, which are macros that look
1808 like variable references rather than function calls.  Each
1809 @var{binding} is a list @samp{(@var{var} @var{expansion})};
1810 any reference to @var{var} within the body @var{forms} is
1811 replaced by @var{expansion}.
1813 @example
1814 (setq bar '(5 . 9))
1815 (symbol-macrolet ((foo (car bar)))
1816   (incf foo))
1818      @result{} (6 . 9)
1819 @end example
1821 A @code{setq} of a symbol macro is treated the same as a @code{setf}.
1822 I.e., @code{(setq foo 4)} in the above would be equivalent to
1823 @code{(setf foo 4)}, which in turn expands to @code{(setf (car bar) 4)}.
1825 Likewise, a @code{let} or @code{let*} binding a symbol macro is
1826 treated like a @code{letf} or @code{letf*}.  This differs from true
1827 Common Lisp, where the rules of lexical scoping cause a @code{let}
1828 binding to shadow a @code{symbol-macrolet} binding.  In this package,
1829 only @code{lexical-let} and @code{lexical-let*} will shadow a symbol
1830 macro.
1832 There is no analogue of @code{defmacro} for symbol macros; all symbol
1833 macros are local.  A typical use of @code{symbol-macrolet} is in the
1834 expansion of another macro:
1836 @example
1837 (defmacro* my-dolist ((x list) &rest body)
1838   (let ((var (gensym)))
1839     (list 'loop 'for var 'on list 'do
1840           (list* 'symbol-macrolet (list (list x (list 'car var)))
1841                  body))))
1843 (setq mylist '(1 2 3 4))
1844 (my-dolist (x mylist) (incf x))
1845 mylist
1846      @result{} (2 3 4 5)
1847 @end example
1849 @noindent
1850 In this example, the @code{my-dolist} macro is similar to @code{dolist}
1851 (@pxref{Iteration}) except that the variable @code{x} becomes a true
1852 reference onto the elements of the list.  The @code{my-dolist} call
1853 shown here expands to
1855 @example
1856 (loop for G1234 on mylist do
1857       (symbol-macrolet ((x (car G1234)))
1858         (incf x)))
1859 @end example
1861 @noindent
1862 which in turn expands to
1864 @example
1865 (loop for G1234 on mylist do (incf (car G1234)))
1866 @end example
1868 @xref{Loop Facility}, for a description of the @code{loop} macro.
1869 This package defines a nonstandard @code{in-ref} loop clause that
1870 works much like @code{my-dolist}.
1871 @end defspec
1873 @node Conditionals, Blocks and Exits, Variable Bindings, Control Structure
1874 @section Conditionals
1876 @noindent
1877 These conditional forms augment Emacs Lisp's simple @code{if},
1878 @code{and}, @code{or}, and @code{cond} forms.
1880 @defspec case keyform clause@dots{}
1881 This macro evaluates @var{keyform}, then compares it with the key
1882 values listed in the various @var{clause}s.  Whichever clause matches
1883 the key is executed; comparison is done by @code{eql}.  If no clause
1884 matches, the @code{case} form returns @code{nil}.  The clauses are
1885 of the form
1887 @example
1888 (@var{keylist} @var{body-forms}@dots{})
1889 @end example
1891 @noindent
1892 where @var{keylist} is a list of key values.  If there is exactly
1893 one value, and it is not a cons cell or the symbol @code{nil} or
1894 @code{t}, then it can be used by itself as a @var{keylist} without
1895 being enclosed in a list.  All key values in the @code{case} form
1896 must be distinct.  The final clauses may use @code{t} in place of
1897 a @var{keylist} to indicate a default clause that should be taken
1898 if none of the other clauses match.  (The symbol @code{otherwise}
1899 is also recognized in place of @code{t}.  To make a clause that
1900 matches the actual symbol @code{t}, @code{nil}, or @code{otherwise},
1901 enclose the symbol in a list.)
1903 For example, this expression reads a keystroke, then does one of
1904 four things depending on whether it is an @samp{a}, a @samp{b},
1905 a @key{RET} or @kbd{C-j}, or anything else.
1907 @example
1908 (case (read-char)
1909   (?a (do-a-thing))
1910   (?b (do-b-thing))
1911   ((?\r ?\n) (do-ret-thing))
1912   (t (do-other-thing)))
1913 @end example
1914 @end defspec
1916 @defspec ecase keyform clause@dots{}
1917 This macro is just like @code{case}, except that if the key does
1918 not match any of the clauses, an error is signaled rather than
1919 simply returning @code{nil}.
1920 @end defspec
1922 @defspec typecase keyform clause@dots{}
1923 This macro is a version of @code{case} that checks for types
1924 rather than values.  Each @var{clause} is of the form
1925 @samp{(@var{type} @var{body}...)}.  @xref{Type Predicates},
1926 for a description of type specifiers.  For example,
1928 @example
1929 (typecase x
1930   (integer (munch-integer x))
1931   (float (munch-float x))
1932   (string (munch-integer (string-to-int x)))
1933   (t (munch-anything x)))
1934 @end example
1936 The type specifier @code{t} matches any type of object; the word
1937 @code{otherwise} is also allowed.  To make one clause match any of
1938 several types, use an @code{(or ...)} type specifier.
1939 @end defspec
1941 @defspec etypecase keyform clause@dots{}
1942 This macro is just like @code{typecase}, except that if the key does
1943 not match any of the clauses, an error is signaled rather than
1944 simply returning @code{nil}.
1945 @end defspec
1947 @node Blocks and Exits, Iteration, Conditionals, Control Structure
1948 @section Blocks and Exits
1950 @noindent
1951 Common Lisp @dfn{blocks} provide a non-local exit mechanism very
1952 similar to @code{catch} and @code{throw}, but lexically rather than
1953 dynamically scoped.  This package actually implements @code{block}
1954 in terms of @code{catch}; however, the lexical scoping allows the
1955 optimizing byte-compiler to omit the costly @code{catch} step if the
1956 body of the block does not actually @code{return-from} the block.
1958 @defspec block name forms@dots{}
1959 The @var{forms} are evaluated as if by a @code{progn}.  However,
1960 if any of the @var{forms} execute @code{(return-from @var{name})},
1961 they will jump out and return directly from the @code{block} form.
1962 The @code{block} returns the result of the last @var{form} unless
1963 a @code{return-from} occurs.
1965 The @code{block}/@code{return-from} mechanism is quite similar to
1966 the @code{catch}/@code{throw} mechanism.  The main differences are
1967 that block @var{name}s are unevaluated symbols, rather than forms
1968 (such as quoted symbols) which evaluate to a tag at run-time; and
1969 also that blocks are lexically scoped whereas @code{catch}/@code{throw}
1970 are dynamically scoped.  This means that functions called from the
1971 body of a @code{catch} can also @code{throw} to the @code{catch},
1972 but the @code{return-from} referring to a block name must appear
1973 physically within the @var{forms} that make up the body of the block.
1974 They may not appear within other called functions, although they may
1975 appear within macro expansions or @code{lambda}s in the body.  Block
1976 names and @code{catch} names form independent name-spaces.
1978 In true Common Lisp, @code{defun} and @code{defmacro} surround
1979 the function or expander bodies with implicit blocks with the
1980 same name as the function or macro.  This does not occur in Emacs
1981 Lisp, but this package provides @code{defun*} and @code{defmacro*}
1982 forms which do create the implicit block.
1984 The Common Lisp looping constructs defined by this package,
1985 such as @code{loop} and @code{dolist}, also create implicit blocks
1986 just as in Common Lisp.
1988 Because they are implemented in terms of Emacs Lisp @code{catch}
1989 and @code{throw}, blocks have the same overhead as actual
1990 @code{catch} constructs (roughly two function calls).  However,
1991 the optimizing byte compiler will optimize away the @code{catch}
1992 if the block does
1993 not in fact contain any @code{return} or @code{return-from} calls
1994 that jump to it.  This means that @code{do} loops and @code{defun*}
1995 functions which don't use @code{return} don't pay the overhead to
1996 support it.
1997 @end defspec
1999 @defspec return-from name [result]
2000 This macro returns from the block named @var{name}, which must be
2001 an (unevaluated) symbol.  If a @var{result} form is specified, it
2002 is evaluated to produce the result returned from the @code{block}.
2003 Otherwise, @code{nil} is returned.
2004 @end defspec
2006 @defspec return [result]
2007 This macro is exactly like @code{(return-from nil @var{result})}.
2008 Common Lisp loops like @code{do} and @code{dolist} implicitly enclose
2009 themselves in @code{nil} blocks.
2010 @end defspec
2012 @node Iteration, Loop Facility, Blocks and Exits, Control Structure
2013 @section Iteration
2015 @noindent
2016 The macros described here provide more sophisticated, high-level
2017 looping constructs to complement Emacs Lisp's basic @code{while}
2018 loop.
2020 @defspec loop forms@dots{}
2021 The @dfn{CL} package supports both the simple, old-style meaning of
2022 @code{loop} and the extremely powerful and flexible feature known as
2023 the @dfn{Loop Facility} or @dfn{Loop Macro}.  This more advanced
2024 facility is discussed in the following section; @pxref{Loop Facility}.
2025 The simple form of @code{loop} is described here.
2027 If @code{loop} is followed by zero or more Lisp expressions,
2028 then @code{(loop @var{exprs}@dots{})} simply creates an infinite
2029 loop executing the expressions over and over.  The loop is
2030 enclosed in an implicit @code{nil} block.  Thus,
2032 @example
2033 (loop (foo)  (if (no-more) (return 72))  (bar))
2034 @end example
2036 @noindent
2037 is exactly equivalent to
2039 @example
2040 (block nil (while t (foo)  (if (no-more) (return 72))  (bar)))
2041 @end example
2043 If any of the expressions are plain symbols, the loop is instead
2044 interpreted as a Loop Macro specification as described later.
2045 (This is not a restriction in practice, since a plain symbol
2046 in the above notation would simply access and throw away the
2047 value of a variable.)
2048 @end defspec
2050 @defspec do (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
2051 This macro creates a general iterative loop.  Each @var{spec} is
2052 of the form
2054 @example
2055 (@var{var} [@var{init} [@var{step}]])
2056 @end example
2058 The loop works as follows:  First, each @var{var} is bound to the
2059 associated @var{init} value as if by a @code{let} form.  Then, in
2060 each iteration of the loop, the @var{end-test} is evaluated; if
2061 true, the loop is finished.  Otherwise, the body @var{forms} are
2062 evaluated, then each @var{var} is set to the associated @var{step}
2063 expression (as if by a @code{psetq} form) and the next iteration
2064 begins.  Once the @var{end-test} becomes true, the @var{result}
2065 forms are evaluated (with the @var{var}s still bound to their
2066 values) to produce the result returned by @code{do}.
2068 The entire @code{do} loop is enclosed in an implicit @code{nil}
2069 block, so that you can use @code{(return)} to break out of the
2070 loop at any time.
2072 If there are no @var{result} forms, the loop returns @code{nil}.
2073 If a given @var{var} has no @var{step} form, it is bound to its
2074 @var{init} value but not otherwise modified during the @code{do}
2075 loop (unless the code explicitly modifies it); this case is just
2076 a shorthand for putting a @code{(let ((@var{var} @var{init})) @dots{})}
2077 around the loop.  If @var{init} is also omitted it defaults to
2078 @code{nil}, and in this case a plain @samp{@var{var}} can be used
2079 in place of @samp{(@var{var})}, again following the analogy with
2080 @code{let}.
2082 This example (from Steele) illustrates a loop which applies the
2083 function @code{f} to successive pairs of values from the lists
2084 @code{foo} and @code{bar}; it is equivalent to the call
2085 @code{(mapcar* 'f foo bar)}.  Note that this loop has no body
2086 @var{forms} at all, performing all its work as side effects of
2087 the rest of the loop.
2089 @example
2090 (do ((x foo (cdr x))
2091      (y bar (cdr y))
2092      (z nil (cons (f (car x) (car y)) z)))
2093   ((or (null x) (null y))
2094    (nreverse z)))
2095 @end example
2096 @end defspec
2098 @defspec do* (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
2099 This is to @code{do} what @code{let*} is to @code{let}.  In
2100 particular, the initial values are bound as if by @code{let*}
2101 rather than @code{let}, and the steps are assigned as if by
2102 @code{setq} rather than @code{psetq}.
2104 Here is another way to write the above loop:
2106 @example
2107 (do* ((xp foo (cdr xp))
2108       (yp bar (cdr yp))
2109       (x (car xp) (car xp))
2110       (y (car yp) (car yp))
2111       z)
2112   ((or (null xp) (null yp))
2113    (nreverse z))
2114   (push (f x y) z))
2115 @end example
2116 @end defspec
2118 @defspec dolist (var list [result]) forms@dots{}
2119 This is a more specialized loop which iterates across the elements
2120 of a list.  @var{list} should evaluate to a list; the body @var{forms}
2121 are executed with @var{var} bound to each element of the list in
2122 turn.  Finally, the @var{result} form (or @code{nil}) is evaluated
2123 with @var{var} bound to @code{nil} to produce the result returned by
2124 the loop.  Unlike with Emacs's built in @code{dolist}, the loop is
2125 surrounded by an implicit @code{nil} block.
2126 @end defspec
2128 @defspec dotimes (var count [result]) forms@dots{}
2129 This is a more specialized loop which iterates a specified number
2130 of times.  The body is executed with @var{var} bound to the integers
2131 from zero (inclusive) to @var{count} (exclusive), in turn.  Then
2132 the @code{result} form is evaluated with @var{var} bound to the total
2133 number of iterations that were done (i.e., @code{(max 0 @var{count})})
2134 to get the return value for the loop form.  Unlike with Emacs's built in
2135 @code{dolist}, the loop is surrounded by an implicit @code{nil} block.
2136 @end defspec
2138 @defspec do-symbols (var [obarray [result]]) forms@dots{}
2139 This loop iterates over all interned symbols.  If @var{obarray}
2140 is specified and is not @code{nil}, it loops over all symbols in
2141 that obarray.  For each symbol, the body @var{forms} are evaluated
2142 with @var{var} bound to that symbol.  The symbols are visited in
2143 an unspecified order.  Afterward the @var{result} form, if any,
2144 is evaluated (with @var{var} bound to @code{nil}) to get the return
2145 value.  The loop is surrounded by an implicit @code{nil} block.
2146 @end defspec
2148 @defspec do-all-symbols (var [result]) forms@dots{}
2149 This is identical to @code{do-symbols} except that the @var{obarray}
2150 argument is omitted; it always iterates over the default obarray.
2151 @end defspec
2153 @xref{Mapping over Sequences}, for some more functions for
2154 iterating over vectors or lists.
2156 @node Loop Facility, Multiple Values, Iteration, Control Structure
2157 @section Loop Facility
2159 @noindent
2160 A common complaint with Lisp's traditional looping constructs is
2161 that they are either too simple and limited, such as Common Lisp's
2162 @code{dotimes} or Emacs Lisp's @code{while}, or too unreadable and
2163 obscure, like Common Lisp's @code{do} loop.
2165 To remedy this, recent versions of Common Lisp have added a new
2166 construct called the ``Loop Facility'' or ``@code{loop} macro,''
2167 with an easy-to-use but very powerful and expressive syntax.
2169 @menu
2170 * Loop Basics::           `loop' macro, basic clause structure
2171 * Loop Examples::         Working examples of `loop' macro
2172 * For Clauses::           Clauses introduced by `for' or `as'
2173 * Iteration Clauses::     `repeat', `while', `thereis', etc.
2174 * Accumulation Clauses::  `collect', `sum', `maximize', etc.
2175 * Other Clauses::         `with', `if', `initially', `finally'
2176 @end menu
2178 @node Loop Basics, Loop Examples, Loop Facility, Loop Facility
2179 @subsection Loop Basics
2181 @noindent
2182 The @code{loop} macro essentially creates a mini-language within
2183 Lisp that is specially tailored for describing loops.  While this
2184 language is a little strange-looking by the standards of regular Lisp,
2185 it turns out to be very easy to learn and well-suited to its purpose.
2187 Since @code{loop} is a macro, all parsing of the loop language
2188 takes place at byte-compile time; compiled @code{loop}s are just
2189 as efficient as the equivalent @code{while} loops written longhand.
2191 @defspec loop clauses@dots{}
2192 A loop construct consists of a series of @var{clause}s, each
2193 introduced by a symbol like @code{for} or @code{do}.  Clauses
2194 are simply strung together in the argument list of @code{loop},
2195 with minimal extra parentheses.  The various types of clauses
2196 specify initializations, such as the binding of temporary
2197 variables, actions to be taken in the loop, stepping actions,
2198 and final cleanup.
2200 Common Lisp specifies a certain general order of clauses in a
2201 loop:
2203 @example
2204 (loop @var{name-clause}
2205       @var{var-clauses}@dots{}
2206       @var{action-clauses}@dots{})
2207 @end example
2209 The @var{name-clause} optionally gives a name to the implicit
2210 block that surrounds the loop.  By default, the implicit block
2211 is named @code{nil}.  The @var{var-clauses} specify what
2212 variables should be bound during the loop, and how they should
2213 be modified or iterated throughout the course of the loop.  The
2214 @var{action-clauses} are things to be done during the loop, such
2215 as computing, collecting, and returning values.
2217 The Emacs version of the @code{loop} macro is less restrictive about
2218 the order of clauses, but things will behave most predictably if
2219 you put the variable-binding clauses @code{with}, @code{for}, and
2220 @code{repeat} before the action clauses.  As in Common Lisp,
2221 @code{initially} and @code{finally} clauses can go anywhere.
2223 Loops generally return @code{nil} by default, but you can cause
2224 them to return a value by using an accumulation clause like
2225 @code{collect}, an end-test clause like @code{always}, or an
2226 explicit @code{return} clause to jump out of the implicit block.
2227 (Because the loop body is enclosed in an implicit block, you can
2228 also use regular Lisp @code{return} or @code{return-from} to
2229 break out of the loop.)
2230 @end defspec
2232 The following sections give some examples of the Loop Macro in
2233 action, and describe the particular loop clauses in great detail.
2234 Consult the second edition of Steele's @dfn{Common Lisp, the Language},
2235 for additional discussion and examples of the @code{loop} macro.
2237 @node Loop Examples, For Clauses, Loop Basics, Loop Facility
2238 @subsection Loop Examples
2240 @noindent
2241 Before listing the full set of clauses that are allowed, let's
2242 look at a few example loops just to get a feel for the @code{loop}
2243 language.
2245 @example
2246 (loop for buf in (buffer-list)
2247       collect (buffer-file-name buf))
2248 @end example
2250 @noindent
2251 This loop iterates over all Emacs buffers, using the list
2252 returned by @code{buffer-list}.  For each buffer @code{buf},
2253 it calls @code{buffer-file-name} and collects the results into
2254 a list, which is then returned from the @code{loop} construct.
2255 The result is a list of the file names of all the buffers in
2256 Emacs' memory.  The words @code{for}, @code{in}, and @code{collect}
2257 are reserved words in the @code{loop} language.
2259 @example
2260 (loop repeat 20 do (insert "Yowsa\n"))
2261 @end example
2263 @noindent
2264 This loop inserts the phrase ``Yowsa'' twenty times in the
2265 current buffer.
2267 @example
2268 (loop until (eobp) do (munch-line) (forward-line 1))
2269 @end example
2271 @noindent
2272 This loop calls @code{munch-line} on every line until the end
2273 of the buffer.  If point is already at the end of the buffer,
2274 the loop exits immediately.
2276 @example
2277 (loop do (munch-line) until (eobp) do (forward-line 1))
2278 @end example
2280 @noindent
2281 This loop is similar to the above one, except that @code{munch-line}
2282 is always called at least once.
2284 @example
2285 (loop for x from 1 to 100
2286       for y = (* x x)
2287       until (>= y 729)
2288       finally return (list x (= y 729)))
2289 @end example
2291 @noindent
2292 This more complicated loop searches for a number @code{x} whose
2293 square is 729.  For safety's sake it only examines @code{x}
2294 values up to 100; dropping the phrase @samp{to 100} would
2295 cause the loop to count upwards with no limit.  The second
2296 @code{for} clause defines @code{y} to be the square of @code{x}
2297 within the loop; the expression after the @code{=} sign is
2298 reevaluated each time through the loop.  The @code{until}
2299 clause gives a condition for terminating the loop, and the
2300 @code{finally} clause says what to do when the loop finishes.
2301 (This particular example was written less concisely than it
2302 could have been, just for the sake of illustration.)
2304 Note that even though this loop contains three clauses (two
2305 @code{for}s and an @code{until}) that would have been enough to
2306 define loops all by themselves, it still creates a single loop
2307 rather than some sort of triple-nested loop.  You must explicitly
2308 nest your @code{loop} constructs if you want nested loops.
2310 @node For Clauses, Iteration Clauses, Loop Examples, Loop Facility
2311 @subsection For Clauses
2313 @noindent
2314 Most loops are governed by one or more @code{for} clauses.
2315 A @code{for} clause simultaneously describes variables to be
2316 bound, how those variables are to be stepped during the loop,
2317 and usually an end condition based on those variables.
2319 The word @code{as} is a synonym for the word @code{for}.  This
2320 word is followed by a variable name, then a word like @code{from}
2321 or @code{across} that describes the kind of iteration desired.
2322 In Common Lisp, the phrase @code{being the} sometimes precedes
2323 the type of iteration; in this package both @code{being} and
2324 @code{the} are optional.  The word @code{each} is a synonym
2325 for @code{the}, and the word that follows it may be singular
2326 or plural:  @samp{for x being the elements of y} or
2327 @samp{for x being each element of y}.  Which form you use
2328 is purely a matter of style.
2330 The variable is bound around the loop as if by @code{let}:
2332 @example
2333 (setq i 'happy)
2334 (loop for i from 1 to 10 do (do-something-with i))
2336      @result{} happy
2337 @end example
2339 @table @code
2340 @item for @var{var} from @var{expr1} to @var{expr2} by @var{expr3}
2341 This type of @code{for} clause creates a counting loop.  Each of
2342 the three sub-terms is optional, though there must be at least one
2343 term so that the clause is marked as a counting clause.
2345 The three expressions are the starting value, the ending value, and
2346 the step value, respectively, of the variable.  The loop counts
2347 upwards by default (@var{expr3} must be positive), from @var{expr1}
2348 to @var{expr2} inclusively.  If you omit the @code{from} term, the
2349 loop counts from zero; if you omit the @code{to} term, the loop
2350 counts forever without stopping (unless stopped by some other
2351 loop clause, of course); if you omit the @code{by} term, the loop
2352 counts in steps of one.
2354 You can replace the word @code{from} with @code{upfrom} or
2355 @code{downfrom} to indicate the direction of the loop.  Likewise,
2356 you can replace @code{to} with @code{upto} or @code{downto}.
2357 For example, @samp{for x from 5 downto 1} executes five times
2358 with @code{x} taking on the integers from 5 down to 1 in turn.
2359 Also, you can replace @code{to} with @code{below} or @code{above},
2360 which are like @code{upto} and @code{downto} respectively except
2361 that they are exclusive rather than inclusive limits:
2363 @example
2364 (loop for x to 10 collect x)
2365      @result{} (0 1 2 3 4 5 6 7 8 9 10)
2366 (loop for x below 10 collect x)
2367      @result{} (0 1 2 3 4 5 6 7 8 9)
2368 @end example
2370 The @code{by} value is always positive, even for downward-counting
2371 loops.  Some sort of @code{from} value is required for downward
2372 loops; @samp{for x downto 5} is not a valid loop clause all by
2373 itself.
2375 @item for @var{var} in @var{list} by @var{function}
2376 This clause iterates @var{var} over all the elements of @var{list},
2377 in turn.  If you specify the @code{by} term, then @var{function}
2378 is used to traverse the list instead of @code{cdr}; it must be a
2379 function taking one argument.  For example:
2381 @example
2382 (loop for x in '(1 2 3 4 5 6) collect (* x x))
2383      @result{} (1 4 9 16 25 36)
2384 (loop for x in '(1 2 3 4 5 6) by 'cddr collect (* x x))
2385      @result{} (1 9 25)
2386 @end example
2388 @item for @var{var} on @var{list} by @var{function}
2389 This clause iterates @var{var} over all the cons cells of @var{list}.
2391 @example
2392 (loop for x on '(1 2 3 4) collect x)
2393      @result{} ((1 2 3 4) (2 3 4) (3 4) (4))
2394 @end example
2396 With @code{by}, there is no real reason that the @code{on} expression
2397 must be a list.  For example:
2399 @example
2400 (loop for x on first-animal by 'next-animal collect x)
2401 @end example
2403 @noindent
2404 where @code{(next-animal x)} takes an ``animal'' @var{x} and returns
2405 the next in the (assumed) sequence of animals, or @code{nil} if
2406 @var{x} was the last animal in the sequence.
2408 @item for @var{var} in-ref @var{list} by @var{function}
2409 This is like a regular @code{in} clause, but @var{var} becomes
2410 a @code{setf}-able ``reference'' onto the elements of the list
2411 rather than just a temporary variable.  For example,
2413 @example
2414 (loop for x in-ref my-list do (incf x))
2415 @end example
2417 @noindent
2418 increments every element of @code{my-list} in place.  This clause
2419 is an extension to standard Common Lisp.
2421 @item for @var{var} across @var{array}
2422 This clause iterates @var{var} over all the elements of @var{array},
2423 which may be a vector or a string.
2425 @example
2426 (loop for x across "aeiou"
2427       do (use-vowel (char-to-string x)))
2428 @end example
2430 @item for @var{var} across-ref @var{array}
2431 This clause iterates over an array, with @var{var} a @code{setf}-able
2432 reference onto the elements; see @code{in-ref} above.
2434 @item for @var{var} being the elements of @var{sequence}
2435 This clause iterates over the elements of @var{sequence}, which may
2436 be a list, vector, or string.  Since the type must be determined
2437 at run-time, this is somewhat less efficient than @code{in} or
2438 @code{across}.  The clause may be followed by the additional term
2439 @samp{using (index @var{var2})} to cause @var{var2} to be bound to
2440 the successive indices (starting at 0) of the elements.
2442 This clause type is taken from older versions of the @code{loop} macro,
2443 and is not present in modern Common Lisp.  The @samp{using (sequence ...)}
2444 term of the older macros is not supported.
2446 @item for @var{var} being the elements of-ref @var{sequence}
2447 This clause iterates over a sequence, with @var{var} a @code{setf}-able
2448 reference onto the elements; see @code{in-ref} above.
2450 @item for @var{var} being the symbols [of @var{obarray}]
2451 This clause iterates over symbols, either over all interned symbols
2452 or over all symbols in @var{obarray}.  The loop is executed with
2453 @var{var} bound to each symbol in turn.  The symbols are visited in
2454 an unspecified order.
2456 As an example,
2458 @example
2459 (loop for sym being the symbols
2460       when (fboundp sym)
2461       when (string-match "^map" (symbol-name sym))
2462       collect sym)
2463 @end example
2465 @noindent
2466 returns a list of all the functions whose names begin with @samp{map}.
2468 The Common Lisp words @code{external-symbols} and @code{present-symbols}
2469 are also recognized but are equivalent to @code{symbols} in Emacs Lisp.
2471 Due to a minor implementation restriction, it will not work to have
2472 more than one @code{for} clause iterating over symbols, hash tables,
2473 keymaps, overlays, or intervals in a given @code{loop}.  Fortunately,
2474 it would rarely if ever be useful to do so.  It @emph{is} valid to mix
2475 one of these types of clauses with other clauses like @code{for ... to}
2476 or @code{while}.
2478 @item for @var{var} being the hash-keys of @var{hash-table}
2479 This clause iterates over the entries in @var{hash-table}.  For each
2480 hash table entry, @var{var} is bound to the entry's key.  If you write
2481 @samp{the hash-values} instead, @var{var} is bound to the values
2482 of the entries.  The clause may be followed by the additional
2483 term @samp{using (hash-values @var{var2})} (where @code{hash-values}
2484 is the opposite word of the word following @code{the}) to cause
2485 @var{var} and @var{var2} to be bound to the two parts of each
2486 hash table entry.
2488 @item for @var{var} being the key-codes of @var{keymap}
2489 This clause iterates over the entries in @var{keymap}.
2490 The iteration does not enter nested keymaps but does enter inherited
2491 (parent) keymaps.
2492 You can use @samp{the key-bindings} to access the commands bound to
2493 the keys rather than the key codes, and you can add a @code{using}
2494 clause to access both the codes and the bindings together.
2496 @item for @var{var} being the key-seqs of @var{keymap}
2497 This clause iterates over all key sequences defined by @var{keymap}
2498 and its nested keymaps, where @var{var} takes on values which are
2499 vectors.  The strings or vectors
2500 are reused for each iteration, so you must copy them if you wish to keep
2501 them permanently.  You can add a @samp{using (key-bindings ...)}
2502 clause to get the command bindings as well.
2504 @item for @var{var} being the overlays [of @var{buffer}] @dots{}
2505 This clause iterates over the ``overlays'' of a buffer
2506 (the clause @code{extents} is synonymous
2507 with @code{overlays}).  If the @code{of} term is omitted, the current
2508 buffer is used.
2509 This clause also accepts optional @samp{from @var{pos}} and
2510 @samp{to @var{pos}} terms, limiting the clause to overlays which
2511 overlap the specified region.
2513 @item for @var{var} being the intervals [of @var{buffer}] @dots{}
2514 This clause iterates over all intervals of a buffer with constant
2515 text properties.  The variable @var{var} will be bound to conses
2516 of start and end positions, where one start position is always equal
2517 to the previous end position.  The clause allows @code{of},
2518 @code{from}, @code{to}, and @code{property} terms, where the latter
2519 term restricts the search to just the specified property.  The
2520 @code{of} term may specify either a buffer or a string.
2522 @item for @var{var} being the frames
2523 This clause iterates over all frames, i.e., X window system windows
2524 open on Emacs files.  The
2525 clause @code{screens} is a synonym for @code{frames}.  The frames
2526 are visited in @code{next-frame} order starting from
2527 @code{selected-frame}.
2529 @item for @var{var} being the windows [of @var{frame}]
2530 This clause iterates over the windows (in the Emacs sense) of
2531 the current frame, or of the specified @var{frame}.
2533 @item for @var{var} being the buffers
2534 This clause iterates over all buffers in Emacs.  It is equivalent
2535 to @samp{for @var{var} in (buffer-list)}.
2537 @item for @var{var} = @var{expr1} then @var{expr2}
2538 This clause does a general iteration.  The first time through
2539 the loop, @var{var} will be bound to @var{expr1}.  On the second
2540 and successive iterations it will be set by evaluating @var{expr2}
2541 (which may refer to the old value of @var{var}).  For example,
2542 these two loops are effectively the same:
2544 @example
2545 (loop for x on my-list by 'cddr do ...)
2546 (loop for x = my-list then (cddr x) while x do ...)
2547 @end example
2549 Note that this type of @code{for} clause does not imply any sort
2550 of terminating condition; the above example combines it with a
2551 @code{while} clause to tell when to end the loop.
2553 If you omit the @code{then} term, @var{expr1} is used both for
2554 the initial setting and for successive settings:
2556 @example
2557 (loop for x = (random) when (> x 0) return x)
2558 @end example
2560 @noindent
2561 This loop keeps taking random numbers from the @code{(random)}
2562 function until it gets a positive one, which it then returns.
2563 @end table
2565 If you include several @code{for} clauses in a row, they are
2566 treated sequentially (as if by @code{let*} and @code{setq}).
2567 You can instead use the word @code{and} to link the clauses,
2568 in which case they are processed in parallel (as if by @code{let}
2569 and @code{psetq}).
2571 @example
2572 (loop for x below 5 for y = nil then x collect (list x y))
2573      @result{} ((0 nil) (1 1) (2 2) (3 3) (4 4))
2574 (loop for x below 5 and y = nil then x collect (list x y))
2575      @result{} ((0 nil) (1 0) (2 1) (3 2) (4 3))
2576 @end example
2578 @noindent
2579 In the first loop, @code{y} is set based on the value of @code{x}
2580 that was just set by the previous clause; in the second loop,
2581 @code{x} and @code{y} are set simultaneously so @code{y} is set
2582 based on the value of @code{x} left over from the previous time
2583 through the loop.
2585 Another feature of the @code{loop} macro is @dfn{destructuring},
2586 similar in concept to the destructuring provided by @code{defmacro}.
2587 The @var{var} part of any @code{for} clause can be given as a list
2588 of variables instead of a single variable.  The values produced
2589 during loop execution must be lists; the values in the lists are
2590 stored in the corresponding variables.
2592 @example
2593 (loop for (x y) in '((2 3) (4 5) (6 7)) collect (+ x y))
2594      @result{} (5 9 13)
2595 @end example
2597 In loop destructuring, if there are more values than variables
2598 the trailing values are ignored, and if there are more variables
2599 than values the trailing variables get the value @code{nil}.
2600 If @code{nil} is used as a variable name, the corresponding
2601 values are ignored.  Destructuring may be nested, and dotted
2602 lists of variables like @code{(x . y)} are allowed.
2604 @node Iteration Clauses, Accumulation Clauses, For Clauses, Loop Facility
2605 @subsection Iteration Clauses
2607 @noindent
2608 Aside from @code{for} clauses, there are several other loop clauses
2609 that control the way the loop operates.  They might be used by
2610 themselves, or in conjunction with one or more @code{for} clauses.
2612 @table @code
2613 @item repeat @var{integer}
2614 This clause simply counts up to the specified number using an
2615 internal temporary variable.  The loops
2617 @example
2618 (loop repeat (1+ n) do ...)
2619 (loop for temp to n do ...)
2620 @end example
2622 @noindent
2623 are identical except that the second one forces you to choose
2624 a name for a variable you aren't actually going to use.
2626 @item while @var{condition}
2627 This clause stops the loop when the specified condition (any Lisp
2628 expression) becomes @code{nil}.  For example, the following two
2629 loops are equivalent, except for the implicit @code{nil} block
2630 that surrounds the second one:
2632 @example
2633 (while @var{cond} @var{forms}@dots{})
2634 (loop while @var{cond} do @var{forms}@dots{})
2635 @end example
2637 @item until @var{condition}
2638 This clause stops the loop when the specified condition is true,
2639 i.e., non-@code{nil}.
2641 @item always @var{condition}
2642 This clause stops the loop when the specified condition is @code{nil}.
2643 Unlike @code{while}, it stops the loop using @code{return nil} so that
2644 the @code{finally} clauses are not executed.  If all the conditions
2645 were non-@code{nil}, the loop returns @code{t}:
2647 @example
2648 (if (loop for size in size-list always (> size 10))
2649     (some-big-sizes)
2650   (no-big-sizes))
2651 @end example
2653 @item never @var{condition}
2654 This clause is like @code{always}, except that the loop returns
2655 @code{t} if any conditions were false, or @code{nil} otherwise.
2657 @item thereis @var{condition}
2658 This clause stops the loop when the specified form is non-@code{nil};
2659 in this case, it returns that non-@code{nil} value.  If all the
2660 values were @code{nil}, the loop returns @code{nil}.
2661 @end table
2663 @node Accumulation Clauses, Other Clauses, Iteration Clauses, Loop Facility
2664 @subsection Accumulation Clauses
2666 @noindent
2667 These clauses cause the loop to accumulate information about the
2668 specified Lisp @var{form}.  The accumulated result is returned
2669 from the loop unless overridden, say, by a @code{return} clause.
2671 @table @code
2672 @item collect @var{form}
2673 This clause collects the values of @var{form} into a list.  Several
2674 examples of @code{collect} appear elsewhere in this manual.
2676 The word @code{collecting} is a synonym for @code{collect}, and
2677 likewise for the other accumulation clauses.
2679 @item append @var{form}
2680 This clause collects lists of values into a result list using
2681 @code{append}.
2683 @item nconc @var{form}
2684 This clause collects lists of values into a result list by
2685 destructively modifying the lists rather than copying them.
2687 @item concat @var{form}
2688 This clause concatenates the values of the specified @var{form}
2689 into a string.  (It and the following clause are extensions to
2690 standard Common Lisp.)
2692 @item vconcat @var{form}
2693 This clause concatenates the values of the specified @var{form}
2694 into a vector.
2696 @item count @var{form}
2697 This clause counts the number of times the specified @var{form}
2698 evaluates to a non-@code{nil} value.
2700 @item sum @var{form}
2701 This clause accumulates the sum of the values of the specified
2702 @var{form}, which must evaluate to a number.
2704 @item maximize @var{form}
2705 This clause accumulates the maximum value of the specified @var{form},
2706 which must evaluate to a number.  The return value is undefined if
2707 @code{maximize} is executed zero times.
2709 @item minimize @var{form}
2710 This clause accumulates the minimum value of the specified @var{form}.
2711 @end table
2713 Accumulation clauses can be followed by @samp{into @var{var}} to
2714 cause the data to be collected into variable @var{var} (which is
2715 automatically @code{let}-bound during the loop) rather than an
2716 unnamed temporary variable.  Also, @code{into} accumulations do
2717 not automatically imply a return value.  The loop must use some
2718 explicit mechanism, such as @code{finally return}, to return
2719 the accumulated result.
2721 It is valid for several accumulation clauses of the same type to
2722 accumulate into the same place.  From Steele:
2724 @example
2725 (loop for name in '(fred sue alice joe june)
2726       for kids in '((bob ken) () () (kris sunshine) ())
2727       collect name
2728       append kids)
2729      @result{} (fred bob ken sue alice joe kris sunshine june)
2730 @end example
2732 @node Other Clauses,  , Accumulation Clauses, Loop Facility
2733 @subsection Other Clauses
2735 @noindent
2736 This section describes the remaining loop clauses.
2738 @table @code
2739 @item with @var{var} = @var{value}
2740 This clause binds a variable to a value around the loop, but
2741 otherwise leaves the variable alone during the loop.  The following
2742 loops are basically equivalent:
2744 @example
2745 (loop with x = 17 do ...)
2746 (let ((x 17)) (loop do ...))
2747 (loop for x = 17 then x do ...)
2748 @end example
2750 Naturally, the variable @var{var} might be used for some purpose
2751 in the rest of the loop.  For example:
2753 @example
2754 (loop for x in my-list  with res = nil  do (push x res)
2755       finally return res)
2756 @end example
2758 This loop inserts the elements of @code{my-list} at the front of
2759 a new list being accumulated in @code{res}, then returns the
2760 list @code{res} at the end of the loop.  The effect is similar
2761 to that of a @code{collect} clause, but the list gets reversed
2762 by virtue of the fact that elements are being pushed onto the
2763 front of @code{res} rather than the end.
2765 If you omit the @code{=} term, the variable is initialized to
2766 @code{nil}.  (Thus the @samp{= nil} in the above example is
2767 unnecessary.)
2769 Bindings made by @code{with} are sequential by default, as if
2770 by @code{let*}.  Just like @code{for} clauses, @code{with} clauses
2771 can be linked with @code{and} to cause the bindings to be made by
2772 @code{let} instead.
2774 @item if @var{condition} @var{clause}
2775 This clause executes the following loop clause only if the specified
2776 condition is true.  The following @var{clause} should be an accumulation,
2777 @code{do}, @code{return}, @code{if}, or @code{unless} clause.
2778 Several clauses may be linked by separating them with @code{and}.
2779 These clauses may be followed by @code{else} and a clause or clauses
2780 to execute if the condition was false.  The whole construct may
2781 optionally be followed by the word @code{end} (which may be used to
2782 disambiguate an @code{else} or @code{and} in a nested @code{if}).
2784 The actual non-@code{nil} value of the condition form is available
2785 by the name @code{it} in the ``then'' part.  For example:
2787 @example
2788 (setq funny-numbers '(6 13 -1))
2789      @result{} (6 13 -1)
2790 (loop for x below 10
2791       if (oddp x)
2792         collect x into odds
2793         and if (memq x funny-numbers) return (cdr it) end
2794       else
2795         collect x into evens
2796       finally return (vector odds evens))
2797      @result{} [(1 3 5 7 9) (0 2 4 6 8)]
2798 (setq funny-numbers '(6 7 13 -1))
2799      @result{} (6 7 13 -1)
2800 (loop <@r{same thing again}>)
2801      @result{} (13 -1)
2802 @end example
2804 Note the use of @code{and} to put two clauses into the ``then''
2805 part, one of which is itself an @code{if} clause.  Note also that
2806 @code{end}, while normally optional, was necessary here to make
2807 it clear that the @code{else} refers to the outermost @code{if}
2808 clause.  In the first case, the loop returns a vector of lists
2809 of the odd and even values of @var{x}.  In the second case, the
2810 odd number 7 is one of the @code{funny-numbers} so the loop
2811 returns early; the actual returned value is based on the result
2812 of the @code{memq} call.
2814 @item when @var{condition} @var{clause}
2815 This clause is just a synonym for @code{if}.
2817 @item unless @var{condition} @var{clause}
2818 The @code{unless} clause is just like @code{if} except that the
2819 sense of the condition is reversed.
2821 @item named @var{name}
2822 This clause gives a name other than @code{nil} to the implicit
2823 block surrounding the loop.  The @var{name} is the symbol to be
2824 used as the block name.
2826 @item initially [do] @var{forms}...
2827 This keyword introduces one or more Lisp forms which will be
2828 executed before the loop itself begins (but after any variables
2829 requested by @code{for} or @code{with} have been bound to their
2830 initial values).  @code{initially} clauses can appear anywhere;
2831 if there are several, they are executed in the order they appear
2832 in the loop.  The keyword @code{do} is optional.
2834 @item finally [do] @var{forms}...
2835 This introduces Lisp forms which will be executed after the loop
2836 finishes (say, on request of a @code{for} or @code{while}).
2837 @code{initially} and @code{finally} clauses may appear anywhere
2838 in the loop construct, but they are executed (in the specified
2839 order) at the beginning or end, respectively, of the loop.
2841 @item finally return @var{form}
2842 This says that @var{form} should be executed after the loop
2843 is done to obtain a return value.  (Without this, or some other
2844 clause like @code{collect} or @code{return}, the loop will simply
2845 return @code{nil}.)  Variables bound by @code{for}, @code{with},
2846 or @code{into} will still contain their final values when @var{form}
2847 is executed.
2849 @item do @var{forms}...
2850 The word @code{do} may be followed by any number of Lisp expressions
2851 which are executed as an implicit @code{progn} in the body of the
2852 loop.  Many of the examples in this section illustrate the use of
2853 @code{do}.
2855 @item return @var{form}
2856 This clause causes the loop to return immediately.  The following
2857 Lisp form is evaluated to give the return value of the @code{loop}
2858 form.  The @code{finally} clauses, if any, are not executed.
2859 Of course, @code{return} is generally used inside an @code{if} or
2860 @code{unless}, as its use in a top-level loop clause would mean
2861 the loop would never get to ``loop'' more than once.
2863 The clause @samp{return @var{form}} is equivalent to
2864 @samp{do (return @var{form})} (or @code{return-from} if the loop
2865 was named).  The @code{return} clause is implemented a bit more
2866 efficiently, though.
2867 @end table
2869 While there is no high-level way to add user extensions to @code{loop}
2870 (comparable to @code{defsetf} for @code{setf}, say), this package
2871 does offer two properties called @code{cl-loop-handler} and
2872 @code{cl-loop-for-handler} which are functions to be called when
2873 a given symbol is encountered as a top-level loop clause or
2874 @code{for} clause, respectively.  Consult the source code in
2875 file @file{cl-macs.el} for details.
2877 This package's @code{loop} macro is compatible with that of Common
2878 Lisp, except that a few features are not implemented:  @code{loop-finish}
2879 and data-type specifiers.  Naturally, the @code{for} clauses which
2880 iterate over keymaps, overlays, intervals, frames, windows, and
2881 buffers are Emacs-specific extensions.
2883 @node Multiple Values,  , Loop Facility, Control Structure
2884 @section Multiple Values
2886 @noindent
2887 Common Lisp functions can return zero or more results.  Emacs Lisp
2888 functions, by contrast, always return exactly one result.  This
2889 package makes no attempt to emulate Common Lisp multiple return
2890 values; Emacs versions of Common Lisp functions that return more
2891 than one value either return just the first value (as in
2892 @code{compiler-macroexpand}) or return a list of values (as in
2893 @code{get-setf-method}).  This package @emph{does} define placeholders
2894 for the Common Lisp functions that work with multiple values, but
2895 in Emacs Lisp these functions simply operate on lists instead.
2896 The @code{values} form, for example, is a synonym for @code{list}
2897 in Emacs.
2899 @defspec multiple-value-bind (var@dots{}) values-form forms@dots{}
2900 This form evaluates @var{values-form}, which must return a list of
2901 values.  It then binds the @var{var}s to these respective values,
2902 as if by @code{let}, and then executes the body @var{forms}.
2903 If there are more @var{var}s than values, the extra @var{var}s
2904 are bound to @code{nil}.  If there are fewer @var{var}s than
2905 values, the excess values are ignored.
2906 @end defspec
2908 @defspec multiple-value-setq (var@dots{}) form
2909 This form evaluates @var{form}, which must return a list of values.
2910 It then sets the @var{var}s to these respective values, as if by
2911 @code{setq}.  Extra @var{var}s or values are treated the same as
2912 in @code{multiple-value-bind}.
2913 @end defspec
2915 The older Quiroz package attempted a more faithful (but still
2916 imperfect) emulation of Common Lisp multiple values.  The old
2917 method ``usually'' simulated true multiple values quite well,
2918 but under certain circumstances would leave spurious return
2919 values in memory where a later, unrelated @code{multiple-value-bind}
2920 form would see them.
2922 Since a perfect emulation is not feasible in Emacs Lisp, this
2923 package opts to keep it as simple and predictable as possible.
2925 @node Macros, Declarations, Control Structure, Top
2926 @chapter Macros
2928 @noindent
2929 This package implements the various Common Lisp features of
2930 @code{defmacro}, such as destructuring, @code{&environment},
2931 and @code{&body}.  Top-level @code{&whole} is not implemented
2932 for @code{defmacro} due to technical difficulties.
2933 @xref{Argument Lists}.
2935 Destructuring is made available to the user by way of the
2936 following macro:
2938 @defspec destructuring-bind arglist expr forms@dots{}
2939 This macro expands to code which executes @var{forms}, with
2940 the variables in @var{arglist} bound to the list of values
2941 returned by @var{expr}.  The @var{arglist} can include all
2942 the features allowed for @code{defmacro} argument lists,
2943 including destructuring.  (The @code{&environment} keyword
2944 is not allowed.)  The macro expansion will signal an error
2945 if @var{expr} returns a list of the wrong number of arguments
2946 or with incorrect keyword arguments.
2947 @end defspec
2949 This package also includes the Common Lisp @code{define-compiler-macro}
2950 facility, which allows you to define compile-time expansions and
2951 optimizations for your functions.
2953 @defspec define-compiler-macro name arglist forms@dots{}
2954 This form is similar to @code{defmacro}, except that it only expands
2955 calls to @var{name} at compile-time; calls processed by the Lisp
2956 interpreter are not expanded, nor are they expanded by the
2957 @code{macroexpand} function.
2959 The argument list may begin with a @code{&whole} keyword and a
2960 variable.  This variable is bound to the macro-call form itself,
2961 i.e., to a list of the form @samp{(@var{name} @var{args}@dots{})}.
2962 If the macro expander returns this form unchanged, then the
2963 compiler treats it as a normal function call.  This allows
2964 compiler macros to work as optimizers for special cases of a
2965 function, leaving complicated cases alone.
2967 For example, here is a simplified version of a definition that
2968 appears as a standard part of this package:
2970 @example
2971 (define-compiler-macro member* (&whole form a list &rest keys)
2972   (if (and (null keys)
2973            (eq (car-safe a) 'quote)
2974            (not (floatp-safe (cadr a))))
2975       (list 'memq a list)
2976     form))
2977 @end example
2979 @noindent
2980 This definition causes @code{(member* @var{a} @var{list})} to change
2981 to a call to the faster @code{memq} in the common case where @var{a}
2982 is a non-floating-point constant; if @var{a} is anything else, or
2983 if there are any keyword arguments in the call, then the original
2984 @code{member*} call is left intact.  (The actual compiler macro
2985 for @code{member*} optimizes a number of other cases, including
2986 common @code{:test} predicates.)
2987 @end defspec
2989 @defun compiler-macroexpand form
2990 This function is analogous to @code{macroexpand}, except that it
2991 expands compiler macros rather than regular macros.  It returns
2992 @var{form} unchanged if it is not a call to a function for which
2993 a compiler macro has been defined, or if that compiler macro
2994 decided to punt by returning its @code{&whole} argument.  Like
2995 @code{macroexpand}, it expands repeatedly until it reaches a form
2996 for which no further expansion is possible.
2997 @end defun
2999 @xref{Macro Bindings}, for descriptions of the @code{macrolet}
3000 and @code{symbol-macrolet} forms for making ``local'' macro
3001 definitions.
3003 @node Declarations, Symbols, Macros, Top
3004 @chapter Declarations
3006 @noindent
3007 Common Lisp includes a complex and powerful ``declaration''
3008 mechanism that allows you to give the compiler special hints
3009 about the types of data that will be stored in particular variables,
3010 and about the ways those variables and functions will be used.  This
3011 package defines versions of all the Common Lisp declaration forms:
3012 @code{declare}, @code{locally}, @code{proclaim}, @code{declaim},
3013 and @code{the}.
3015 Most of the Common Lisp declarations are not currently useful in
3016 Emacs Lisp, as the byte-code system provides little opportunity
3017 to benefit from type information, and @code{special} declarations
3018 are redundant in a fully dynamically-scoped Lisp.  A few
3019 declarations are meaningful when the optimizing byte
3020 compiler is being used, however.  Under the earlier non-optimizing
3021 compiler, these declarations will effectively be ignored.
3023 @defun proclaim decl-spec
3024 This function records a ``global'' declaration specified by
3025 @var{decl-spec}.  Since @code{proclaim} is a function, @var{decl-spec}
3026 is evaluated and thus should normally be quoted.
3027 @end defun
3029 @defspec declaim decl-specs@dots{}
3030 This macro is like @code{proclaim}, except that it takes any number
3031 of @var{decl-spec} arguments, and the arguments are unevaluated and
3032 unquoted.  The @code{declaim} macro also puts an @code{(eval-when
3033 (compile load eval) ...)} around the declarations so that they will
3034 be registered at compile-time as well as at run-time.  (This is vital,
3035 since normally the declarations are meant to influence the way the
3036 compiler treats the rest of the file that contains the @code{declaim}
3037 form.)
3038 @end defspec
3040 @defspec declare decl-specs@dots{}
3041 This macro is used to make declarations within functions and other
3042 code.  Common Lisp allows declarations in various locations, generally
3043 at the beginning of any of the many ``implicit @code{progn}s''
3044 throughout Lisp syntax, such as function bodies, @code{let} bodies,
3045 etc.  Currently the only declaration understood by @code{declare}
3046 is @code{special}.
3047 @end defspec
3049 @defspec locally declarations@dots{} forms@dots{}
3050 In this package, @code{locally} is no different from @code{progn}.
3051 @end defspec
3053 @defspec the type form
3054 Type information provided by @code{the} is ignored in this package;
3055 in other words, @code{(the @var{type} @var{form})} is equivalent
3056 to @var{form}.  Future versions of the optimizing byte-compiler may
3057 make use of this information.
3059 For example, @code{mapcar} can map over both lists and arrays.  It is
3060 hard for the compiler to expand @code{mapcar} into an in-line loop
3061 unless it knows whether the sequence will be a list or an array ahead
3062 of time.  With @code{(mapcar 'car (the vector foo))}, a future
3063 compiler would have enough information to expand the loop in-line.
3064 For now, Emacs Lisp will treat the above code as exactly equivalent
3065 to @code{(mapcar 'car foo)}.
3066 @end defspec
3068 Each @var{decl-spec} in a @code{proclaim}, @code{declaim}, or
3069 @code{declare} should be a list beginning with a symbol that says
3070 what kind of declaration it is.  This package currently understands
3071 @code{special}, @code{inline}, @code{notinline}, @code{optimize},
3072 and @code{warn} declarations.  (The @code{warn} declaration is an
3073 extension of standard Common Lisp.)  Other Common Lisp declarations,
3074 such as @code{type} and @code{ftype}, are silently ignored.
3076 @table @code
3077 @item special
3078 Since all variables in Emacs Lisp are ``special'' (in the Common
3079 Lisp sense), @code{special} declarations are only advisory.  They
3080 simply tell the optimizing byte compiler that the specified
3081 variables are intentionally being referred to without being
3082 bound in the body of the function.  The compiler normally emits
3083 warnings for such references, since they could be typographical
3084 errors for references to local variables.
3086 The declaration @code{(declare (special @var{var1} @var{var2}))} is
3087 equivalent to @code{(defvar @var{var1}) (defvar @var{var2})} in the
3088 optimizing compiler, or to nothing at all in older compilers (which
3089 do not warn for non-local references).
3091 In top-level contexts, it is generally better to write
3092 @code{(defvar @var{var})} than @code{(declaim (special @var{var}))},
3093 since @code{defvar} makes your intentions clearer.  But the older
3094 byte compilers can not handle @code{defvar}s appearing inside of
3095 functions, while @code{(declare (special @var{var}))} takes care
3096 to work correctly with all compilers.
3098 @item inline
3099 The @code{inline} @var{decl-spec} lists one or more functions
3100 whose bodies should be expanded ``in-line'' into calling functions
3101 whenever the compiler is able to arrange for it.  For example,
3102 the Common Lisp function @code{cadr} is declared @code{inline}
3103 by this package so that the form @code{(cadr @var{x})} will
3104 expand directly into @code{(car (cdr @var{x}))} when it is called
3105 in user functions, for a savings of one (relatively expensive)
3106 function call.
3108 The following declarations are all equivalent.  Note that the
3109 @code{defsubst} form is a convenient way to define a function
3110 and declare it inline all at once.
3112 @example
3113 (declaim (inline foo bar))
3114 (eval-when (compile load eval) (proclaim '(inline foo bar)))
3115 (defsubst foo (...) ...)       ; instead of defun
3116 @end example
3118 @strong{Please note:}  this declaration remains in effect after the
3119 containing source file is done.  It is correct to use it to
3120 request that a function you have defined should be inlined,
3121 but it is impolite to use it to request inlining of an external
3122 function.
3124 In Common Lisp, it is possible to use @code{(declare (inline @dots{}))}
3125 before a particular call to a function to cause just that call to
3126 be inlined; the current byte compilers provide no way to implement
3127 this, so @code{(declare (inline @dots{}))} is currently ignored by
3128 this package.
3130 @item notinline
3131 The @code{notinline} declaration lists functions which should
3132 not be inlined after all; it cancels a previous @code{inline}
3133 declaration.
3135 @item optimize
3136 This declaration controls how much optimization is performed by
3137 the compiler.  Naturally, it is ignored by the earlier non-optimizing
3138 compilers.
3140 The word @code{optimize} is followed by any number of lists like
3141 @code{(speed 3)} or @code{(safety 2)}.  Common Lisp defines several
3142 optimization ``qualities''; this package ignores all but @code{speed}
3143 and @code{safety}.  The value of a quality should be an integer from
3144 0 to 3, with 0 meaning ``unimportant'' and 3 meaning ``very important.''
3145 The default level for both qualities is 1.
3147 In this package, with the optimizing compiler, the
3148 @code{speed} quality is tied to the @code{byte-compile-optimize}
3149 flag, which is set to @code{nil} for @code{(speed 0)} and to
3150 @code{t} for higher settings; and the @code{safety} quality is
3151 tied to the @code{byte-compile-delete-errors} flag, which is
3152 set to @code{t} for @code{(safety 3)} and to @code{nil} for all
3153 lower settings.  (The latter flag controls whether the compiler
3154 is allowed to optimize out code whose only side-effect could
3155 be to signal an error, e.g., rewriting @code{(progn foo bar)} to
3156 @code{bar} when it is not known whether @code{foo} will be bound
3157 at run-time.)
3159 Note that even compiling with @code{(safety 0)}, the Emacs
3160 byte-code system provides sufficient checking to prevent real
3161 harm from being done.  For example, barring serious bugs in
3162 Emacs itself, Emacs will not crash with a segmentation fault
3163 just because of an error in a fully-optimized Lisp program.
3165 The @code{optimize} declaration is normally used in a top-level
3166 @code{proclaim} or @code{declaim} in a file; Common Lisp allows
3167 it to be used with @code{declare} to set the level of optimization
3168 locally for a given form, but this will not work correctly with the
3169 current version of the optimizing compiler.  (The @code{declare}
3170 will set the new optimization level, but that level will not
3171 automatically be unset after the enclosing form is done.)
3173 @item warn
3174 This declaration controls what sorts of warnings are generated
3175 by the byte compiler.  Again, only the optimizing compiler
3176 generates warnings.  The word @code{warn} is followed by any
3177 number of ``warning qualities,'' similar in form to optimization
3178 qualities.  The currently supported warning types are
3179 @code{redefine}, @code{callargs}, @code{unresolved}, and
3180 @code{free-vars}; in the current system, a value of 0 will
3181 disable these warnings and any higher value will enable them.
3182 See the documentation for the optimizing byte compiler for details.
3183 @end table
3185 @node Symbols, Numbers, Declarations, Top
3186 @chapter Symbols
3188 @noindent
3189 This package defines several symbol-related features that were
3190 missing from Emacs Lisp.
3192 @menu
3193 * Property Lists::       `get*', `remprop', `getf', `remf'
3194 * Creating Symbols::     `gensym', `gentemp'
3195 @end menu
3197 @node Property Lists, Creating Symbols, Symbols, Symbols
3198 @section Property Lists
3200 @noindent
3201 These functions augment the standard Emacs Lisp functions @code{get}
3202 and @code{put} for operating on properties attached to symbols.
3203 There are also functions for working with property lists as
3204 first-class data structures not attached to particular symbols.
3206 @defun get* symbol property &optional default
3207 This function is like @code{get}, except that if the property is
3208 not found, the @var{default} argument provides the return value.
3209 (The Emacs Lisp @code{get} function always uses @code{nil} as
3210 the default; this package's @code{get*} is equivalent to Common
3211 Lisp's @code{get}.)
3213 The @code{get*} function is @code{setf}-able; when used in this
3214 fashion, the @var{default} argument is allowed but ignored.
3215 @end defun
3217 @defun remprop symbol property
3218 This function removes the entry for @var{property} from the property
3219 list of @var{symbol}.  It returns a true value if the property was
3220 indeed found and removed, or @code{nil} if there was no such property.
3221 (This function was probably omitted from Emacs originally because,
3222 since @code{get} did not allow a @var{default}, it was very difficult
3223 to distinguish between a missing property and a property whose value
3224 was @code{nil}; thus, setting a property to @code{nil} was close
3225 enough to @code{remprop} for most purposes.)
3226 @end defun
3228 @defun getf place property &optional default
3229 This function scans the list @var{place} as if it were a property
3230 list, i.e., a list of alternating property names and values.  If
3231 an even-numbered element of @var{place} is found which is @code{eq}
3232 to @var{property}, the following odd-numbered element is returned.
3233 Otherwise, @var{default} is returned (or @code{nil} if no default
3234 is given).
3236 In particular,
3238 @example
3239 (get sym prop)  @equiv{}  (getf (symbol-plist sym) prop)
3240 @end example
3242 It is valid to use @code{getf} as a @code{setf} place, in which case
3243 its @var{place} argument must itself be a valid @code{setf} place.
3244 The @var{default} argument, if any, is ignored in this context.
3245 The effect is to change (via @code{setcar}) the value cell in the
3246 list that corresponds to @var{property}, or to cons a new property-value
3247 pair onto the list if the property is not yet present.
3249 @example
3250 (put sym prop val)  @equiv{}  (setf (getf (symbol-plist sym) prop) val)
3251 @end example
3253 The @code{get} and @code{get*} functions are also @code{setf}-able.
3254 The fact that @code{default} is ignored can sometimes be useful:
3256 @example
3257 (incf (get* 'foo 'usage-count 0))
3258 @end example
3260 Here, symbol @code{foo}'s @code{usage-count} property is incremented
3261 if it exists, or set to 1 (an incremented 0) otherwise.
3263 When not used as a @code{setf} form, @code{getf} is just a regular
3264 function and its @var{place} argument can actually be any Lisp
3265 expression.
3266 @end defun
3268 @defspec remf place property
3269 This macro removes the property-value pair for @var{property} from
3270 the property list stored at @var{place}, which is any @code{setf}-able
3271 place expression.  It returns true if the property was found.  Note
3272 that if @var{property} happens to be first on the list, this will
3273 effectively do a @code{(setf @var{place} (cddr @var{place}))},
3274 whereas if it occurs later, this simply uses @code{setcdr} to splice
3275 out the property and value cells.
3276 @end defspec
3278 @iftex
3279 @secno=2
3280 @end iftex
3282 @node Creating Symbols,  , Property Lists, Symbols
3283 @section Creating Symbols
3285 @noindent
3286 These functions create unique symbols, typically for use as
3287 temporary variables.
3289 @defun gensym &optional x
3290 This function creates a new, uninterned symbol (using @code{make-symbol})
3291 with a unique name.  (The name of an uninterned symbol is relevant
3292 only if the symbol is printed.)  By default, the name is generated
3293 from an increasing sequence of numbers, @samp{G1000}, @samp{G1001},
3294 @samp{G1002}, etc.  If the optional argument @var{x} is a string, that
3295 string is used as a prefix instead of @samp{G}.  Uninterned symbols
3296 are used in macro expansions for temporary variables, to ensure that
3297 their names will not conflict with ``real'' variables in the user's
3298 code.
3299 @end defun
3301 @defvar *gensym-counter*
3302 This variable holds the counter used to generate @code{gensym} names.
3303 It is incremented after each use by @code{gensym}.  In Common Lisp
3304 this is initialized with 0, but this package initializes it with a
3305 random (time-dependent) value to avoid trouble when two files that
3306 each used @code{gensym} in their compilation are loaded together.
3307 (Uninterned symbols become interned when the compiler writes them
3308 out to a file and the Emacs loader loads them, so their names have to
3309 be treated a bit more carefully than in Common Lisp where uninterned
3310 symbols remain uninterned after loading.)
3311 @end defvar
3313 @defun gentemp &optional x
3314 This function is like @code{gensym}, except that it produces a new
3315 @emph{interned} symbol.  If the symbol that is generated already
3316 exists, the function keeps incrementing the counter and trying
3317 again until a new symbol is generated.
3318 @end defun
3320 The Quiroz @file{cl.el} package also defined a @code{defkeyword}
3321 form for creating self-quoting keyword symbols.  This package
3322 automatically creates all keywords that are called for by
3323 @code{&key} argument specifiers, and discourages the use of
3324 keywords as data unrelated to keyword arguments, so the
3325 @code{defkeyword} form has been discontinued.
3327 @iftex
3328 @chapno=11
3329 @end iftex
3331 @node Numbers, Sequences, Symbols, Top
3332 @chapter Numbers
3334 @noindent
3335 This section defines a few simple Common Lisp operations on numbers
3336 which were left out of Emacs Lisp.
3338 @menu
3339 * Predicates on Numbers::       `plusp', `oddp', `floatp-safe', etc.
3340 * Numerical Functions::         `abs', `floor*', etc.
3341 * Random Numbers::              `random*', `make-random-state'
3342 * Implementation Parameters::   `most-positive-float'
3343 @end menu
3345 @iftex
3346 @secno=1
3347 @end iftex
3349 @node Predicates on Numbers, Numerical Functions, Numbers, Numbers
3350 @section Predicates on Numbers
3352 @noindent
3353 These functions return @code{t} if the specified condition is
3354 true of the numerical argument, or @code{nil} otherwise.
3356 @defun plusp number
3357 This predicate tests whether @var{number} is positive.  It is an
3358 error if the argument is not a number.
3359 @end defun
3361 @defun minusp number
3362 This predicate tests whether @var{number} is negative.  It is an
3363 error if the argument is not a number.
3364 @end defun
3366 @defun oddp integer
3367 This predicate tests whether @var{integer} is odd.  It is an
3368 error if the argument is not an integer.
3369 @end defun
3371 @defun evenp integer
3372 This predicate tests whether @var{integer} is even.  It is an
3373 error if the argument is not an integer.
3374 @end defun
3376 @defun floatp-safe object
3377 This predicate tests whether @var{object} is a floating-point
3378 number.  On systems that support floating-point, this is equivalent
3379 to @code{floatp}.  On other systems, this always returns @code{nil}.
3380 @end defun
3382 @iftex
3383 @secno=3
3384 @end iftex
3386 @node Numerical Functions, Random Numbers, Predicates on Numbers, Numbers
3387 @section Numerical Functions
3389 @noindent
3390 These functions perform various arithmetic operations on numbers.
3392 @defun gcd &rest integers
3393 This function returns the Greatest Common Divisor of the arguments.
3394 For one argument, it returns the absolute value of that argument.
3395 For zero arguments, it returns zero.
3396 @end defun
3398 @defun lcm &rest integers
3399 This function returns the Least Common Multiple of the arguments.
3400 For one argument, it returns the absolute value of that argument.
3401 For zero arguments, it returns one.
3402 @end defun
3404 @defun isqrt integer
3405 This function computes the ``integer square root'' of its integer
3406 argument, i.e., the greatest integer less than or equal to the true
3407 square root of the argument.
3408 @end defun
3410 @defun floor* number &optional divisor
3411 This function implements the Common Lisp @code{floor} function.
3412 It is called @code{floor*} to avoid name conflicts with the
3413 simpler @code{floor} function built-in to Emacs.
3415 With one argument, @code{floor*} returns a list of two numbers:
3416 The argument rounded down (toward minus infinity) to an integer,
3417 and the ``remainder'' which would have to be added back to the
3418 first return value to yield the argument again.  If the argument
3419 is an integer @var{x}, the result is always the list @code{(@var{x} 0)}.
3420 If the argument is a floating-point number, the first
3421 result is a Lisp integer and the second is a Lisp float between
3422 0 (inclusive) and 1 (exclusive).
3424 With two arguments, @code{floor*} divides @var{number} by
3425 @var{divisor}, and returns the floor of the quotient and the
3426 corresponding remainder as a list of two numbers.  If
3427 @code{(floor* @var{x} @var{y})} returns @code{(@var{q} @var{r})},
3428 then @code{@var{q}*@var{y} + @var{r} = @var{x}}, with @var{r}
3429 between 0 (inclusive) and @var{r} (exclusive).  Also, note
3430 that @code{(floor* @var{x})} is exactly equivalent to
3431 @code{(floor* @var{x} 1)}.
3433 This function is entirely compatible with Common Lisp's @code{floor}
3434 function, except that it returns the two results in a list since
3435 Emacs Lisp does not support multiple-valued functions.
3436 @end defun
3438 @defun ceiling* number &optional divisor
3439 This function implements the Common Lisp @code{ceiling} function,
3440 which is analogous to @code{floor} except that it rounds the
3441 argument or quotient of the arguments up toward plus infinity.
3442 The remainder will be between 0 and minus @var{r}.
3443 @end defun
3445 @defun truncate* number &optional divisor
3446 This function implements the Common Lisp @code{truncate} function,
3447 which is analogous to @code{floor} except that it rounds the
3448 argument or quotient of the arguments toward zero.  Thus it is
3449 equivalent to @code{floor*} if the argument or quotient is
3450 positive, or to @code{ceiling*} otherwise.  The remainder has
3451 the same sign as @var{number}.
3452 @end defun
3454 @defun round* number &optional divisor
3455 This function implements the Common Lisp @code{round} function,
3456 which is analogous to @code{floor} except that it rounds the
3457 argument or quotient of the arguments to the nearest integer.
3458 In the case of a tie (the argument or quotient is exactly
3459 halfway between two integers), it rounds to the even integer.
3460 @end defun
3462 @defun mod* number divisor
3463 This function returns the same value as the second return value
3464 of @code{floor}.
3465 @end defun
3467 @defun rem* number divisor
3468 This function returns the same value as the second return value
3469 of @code{truncate}.
3470 @end defun
3472 These definitions are compatible with those in the Quiroz
3473 @file{cl.el} package, except that this package appends @samp{*}
3474 to certain function names to avoid conflicts with existing
3475 Emacs functions, and that the mechanism for returning
3476 multiple values is different.
3478 @iftex
3479 @secno=8
3480 @end iftex
3482 @node Random Numbers, Implementation Parameters, Numerical Functions, Numbers
3483 @section Random Numbers
3485 @noindent
3486 This package also provides an implementation of the Common Lisp
3487 random number generator.  It uses its own additive-congruential
3488 algorithm, which is much more likely to give statistically clean
3489 random numbers than the simple generators supplied by many
3490 operating systems.
3492 @defun random* number &optional state
3493 This function returns a random nonnegative number less than
3494 @var{number}, and of the same type (either integer or floating-point).
3495 The @var{state} argument should be a @code{random-state} object
3496 which holds the state of the random number generator.  The
3497 function modifies this state object as a side effect.  If
3498 @var{state} is omitted, it defaults to the variable
3499 @code{*random-state*}, which contains a pre-initialized
3500 @code{random-state} object.
3501 @end defun
3503 @defvar *random-state*
3504 This variable contains the system ``default'' @code{random-state}
3505 object, used for calls to @code{random*} that do not specify an
3506 alternative state object.  Since any number of programs in the
3507 Emacs process may be accessing @code{*random-state*} in interleaved
3508 fashion, the sequence generated from this variable will be
3509 irreproducible for all intents and purposes.
3510 @end defvar
3512 @defun make-random-state &optional state
3513 This function creates or copies a @code{random-state} object.
3514 If @var{state} is omitted or @code{nil}, it returns a new copy of
3515 @code{*random-state*}.  This is a copy in the sense that future
3516 sequences of calls to @code{(random* @var{n})} and
3517 @code{(random* @var{n} @var{s})} (where @var{s} is the new
3518 random-state object) will return identical sequences of random
3519 numbers.
3521 If @var{state} is a @code{random-state} object, this function
3522 returns a copy of that object.  If @var{state} is @code{t}, this
3523 function returns a new @code{random-state} object seeded from the
3524 date and time.  As an extension to Common Lisp, @var{state} may also
3525 be an integer in which case the new object is seeded from that
3526 integer; each different integer seed will result in a completely
3527 different sequence of random numbers.
3529 It is valid to print a @code{random-state} object to a buffer or
3530 file and later read it back with @code{read}.  If a program wishes
3531 to use a sequence of pseudo-random numbers which can be reproduced
3532 later for debugging, it can call @code{(make-random-state t)} to
3533 get a new sequence, then print this sequence to a file.  When the
3534 program is later rerun, it can read the original run's random-state
3535 from the file.
3536 @end defun
3538 @defun random-state-p object
3539 This predicate returns @code{t} if @var{object} is a
3540 @code{random-state} object, or @code{nil} otherwise.
3541 @end defun
3543 @node Implementation Parameters,  , Random Numbers, Numbers
3544 @section Implementation Parameters
3546 @noindent
3547 This package defines several useful constants having to with numbers.
3549 The following parameters have to do with floating-point numbers.
3550 This package determines their values by exercising the computer's
3551 floating-point arithmetic in various ways.  Because this operation
3552 might be slow, the code for initializing them is kept in a separate
3553 function that must be called before the parameters can be used.
3555 @defun cl-float-limits
3556 This function makes sure that the Common Lisp floating-point parameters
3557 like @code{most-positive-float} have been initialized.  Until it is
3558 called, these parameters will be @code{nil}.  If this version of Emacs
3559 does not support floats, the parameters will remain @code{nil}.  If the
3560 parameters have already been initialized, the function returns
3561 immediately.
3563 The algorithm makes assumptions that will be valid for most modern
3564 machines, but will fail if the machine's arithmetic is extremely
3565 unusual, e.g., decimal.
3566 @end defun
3568 Since true Common Lisp supports up to four different floating-point
3569 precisions, it has families of constants like
3570 @code{most-positive-single-float}, @code{most-positive-double-float},
3571 @code{most-positive-long-float}, and so on.  Emacs has only one
3572 floating-point precision, so this package omits the precision word
3573 from the constants' names.
3575 @defvar most-positive-float
3576 This constant equals the largest value a Lisp float can hold.
3577 For those systems whose arithmetic supports infinities, this is
3578 the largest @emph{finite} value.  For IEEE machines, the value
3579 is approximately @code{1.79e+308}.
3580 @end defvar
3582 @defvar most-negative-float
3583 This constant equals the most-negative value a Lisp float can hold.
3584 (It is assumed to be equal to @code{(- most-positive-float)}.)
3585 @end defvar
3587 @defvar least-positive-float
3588 This constant equals the smallest Lisp float value greater than zero.
3589 For IEEE machines, it is about @code{4.94e-324} if denormals are
3590 supported or @code{2.22e-308} if not.
3591 @end defvar
3593 @defvar least-positive-normalized-float
3594 This constant equals the smallest @emph{normalized} Lisp float greater
3595 than zero, i.e., the smallest value for which IEEE denormalization
3596 will not result in a loss of precision.  For IEEE machines, this
3597 value is about @code{2.22e-308}.  For machines that do not support
3598 the concept of denormalization and gradual underflow, this constant
3599 will always equal @code{least-positive-float}.
3600 @end defvar
3602 @defvar least-negative-float
3603 This constant is the negative counterpart of @code{least-positive-float}.
3604 @end defvar
3606 @defvar least-negative-normalized-float
3607 This constant is the negative counterpart of
3608 @code{least-positive-normalized-float}.
3609 @end defvar
3611 @defvar float-epsilon
3612 This constant is the smallest positive Lisp float that can be added
3613 to 1.0 to produce a distinct value.  Adding a smaller number to 1.0
3614 will yield 1.0 again due to roundoff.  For IEEE machines, epsilon
3615 is about @code{2.22e-16}.
3616 @end defvar
3618 @defvar float-negative-epsilon
3619 This is the smallest positive value that can be subtracted from
3620 1.0 to produce a distinct value.  For IEEE machines, it is about
3621 @code{1.11e-16}.
3622 @end defvar
3624 @iftex
3625 @chapno=13
3626 @end iftex
3628 @node Sequences, Lists, Numbers, Top
3629 @chapter Sequences
3631 @noindent
3632 Common Lisp defines a number of functions that operate on
3633 @dfn{sequences}, which are either lists, strings, or vectors.
3634 Emacs Lisp includes a few of these, notably @code{elt} and
3635 @code{length}; this package defines most of the rest.
3637 @menu
3638 * Sequence Basics::          Arguments shared by all sequence functions
3639 * Mapping over Sequences::   `mapcar*', `mapcan', `map', `every', etc.
3640 * Sequence Functions::       `subseq', `remove*', `substitute', etc.
3641 * Searching Sequences::      `find', `position', `count', `search', etc.
3642 * Sorting Sequences::        `sort*', `stable-sort', `merge'
3643 @end menu
3645 @node Sequence Basics, Mapping over Sequences, Sequences, Sequences
3646 @section Sequence Basics
3648 @noindent
3649 Many of the sequence functions take keyword arguments; @pxref{Argument
3650 Lists}.  All keyword arguments are optional and, if specified,
3651 may appear in any order.
3653 The @code{:key} argument should be passed either @code{nil}, or a
3654 function of one argument.  This key function is used as a filter
3655 through which the elements of the sequence are seen; for example,
3656 @code{(find x y :key 'car)} is similar to @code{(assoc* x y)}:
3657 It searches for an element of the list whose @code{car} equals
3658 @code{x}, rather than for an element which equals @code{x} itself.
3659 If @code{:key} is omitted or @code{nil}, the filter is effectively
3660 the identity function.
3662 The @code{:test} and @code{:test-not} arguments should be either
3663 @code{nil}, or functions of two arguments.  The test function is
3664 used to compare two sequence elements, or to compare a search value
3665 with sequence elements.  (The two values are passed to the test
3666 function in the same order as the original sequence function
3667 arguments from which they are derived, or, if they both come from
3668 the same sequence, in the same order as they appear in that sequence.)
3669 The @code{:test} argument specifies a function which must return
3670 true (non-@code{nil}) to indicate a match; instead, you may use
3671 @code{:test-not} to give a function which returns @emph{false} to
3672 indicate a match.  The default test function is @code{eql}.
3674 Many functions which take @var{item} and @code{:test} or @code{:test-not}
3675 arguments also come in @code{-if} and @code{-if-not} varieties,
3676 where a @var{predicate} function is passed instead of @var{item},
3677 and sequence elements match if the predicate returns true on them
3678 (or false in the case of @code{-if-not}).  For example:
3680 @example
3681 (remove* 0 seq :test '=)  @equiv{}  (remove-if 'zerop seq)
3682 @end example
3684 @noindent
3685 to remove all zeros from sequence @code{seq}.
3687 Some operations can work on a subsequence of the argument sequence;
3688 these function take @code{:start} and @code{:end} arguments which
3689 default to zero and the length of the sequence, respectively.
3690 Only elements between @var{start} (inclusive) and @var{end}
3691 (exclusive) are affected by the operation.  The @var{end} argument
3692 may be passed @code{nil} to signify the length of the sequence;
3693 otherwise, both @var{start} and @var{end} must be integers, with
3694 @code{0 <= @var{start} <= @var{end} <= (length @var{seq})}.
3695 If the function takes two sequence arguments, the limits are
3696 defined by keywords @code{:start1} and @code{:end1} for the first,
3697 and @code{:start2} and @code{:end2} for the second.
3699 A few functions accept a @code{:from-end} argument, which, if
3700 non-@code{nil}, causes the operation to go from right-to-left
3701 through the sequence instead of left-to-right, and a @code{:count}
3702 argument, which specifies an integer maximum number of elements
3703 to be removed or otherwise processed.
3705 The sequence functions make no guarantees about the order in
3706 which the @code{:test}, @code{:test-not}, and @code{:key} functions
3707 are called on various elements.  Therefore, it is a bad idea to depend
3708 on side effects of these functions.  For example, @code{:from-end}
3709 may cause the sequence to be scanned actually in reverse, or it may
3710 be scanned forwards but computing a result ``as if'' it were scanned
3711 backwards.  (Some functions, like @code{mapcar*} and @code{every},
3712 @emph{do} specify exactly the order in which the function is called
3713 so side effects are perfectly acceptable in those cases.)
3715 Strings may contain ``text properties'' as well
3716 as character data.  Except as noted, it is undefined whether or
3717 not text properties are preserved by sequence functions.  For
3718 example, @code{(remove* ?A @var{str})} may or may not preserve
3719 the properties of the characters copied from @var{str} into the
3720 result.
3722 @node Mapping over Sequences, Sequence Functions, Sequence Basics, Sequences
3723 @section Mapping over Sequences
3725 @noindent
3726 These functions ``map'' the function you specify over the elements
3727 of lists or arrays.  They are all variations on the theme of the
3728 built-in function @code{mapcar}.
3730 @defun mapcar* function seq &rest more-seqs
3731 This function calls @var{function} on successive parallel sets of
3732 elements from its argument sequences.  Given a single @var{seq}
3733 argument it is equivalent to @code{mapcar}; given @var{n} sequences,
3734 it calls the function with the first elements of each of the sequences
3735 as the @var{n} arguments to yield the first element of the result
3736 list, then with the second elements, and so on.  The mapping stops as
3737 soon as the shortest sequence runs out.  The argument sequences may
3738 be any mixture of lists, strings, and vectors; the return sequence
3739 is always a list.
3741 Common Lisp's @code{mapcar} accepts multiple arguments but works
3742 only on lists; Emacs Lisp's @code{mapcar} accepts a single sequence
3743 argument.  This package's @code{mapcar*} works as a compatible
3744 superset of both.
3745 @end defun
3747 @defun map result-type function seq &rest more-seqs
3748 This function maps @var{function} over the argument sequences,
3749 just like @code{mapcar*}, but it returns a sequence of type
3750 @var{result-type} rather than a list.  @var{result-type} must
3751 be one of the following symbols: @code{vector}, @code{string},
3752 @code{list} (in which case the effect is the same as for
3753 @code{mapcar*}), or @code{nil} (in which case the results are
3754 thrown away and @code{map} returns @code{nil}).
3755 @end defun
3757 @defun maplist function list &rest more-lists
3758 This function calls @var{function} on each of its argument lists,
3759 then on the @code{cdr}s of those lists, and so on, until the
3760 shortest list runs out.  The results are returned in the form
3761 of a list.  Thus, @code{maplist} is like @code{mapcar*} except
3762 that it passes in the list pointers themselves rather than the
3763 @code{car}s of the advancing pointers.
3764 @end defun
3766 @defun mapc function seq &rest more-seqs
3767 This function is like @code{mapcar*}, except that the values returned
3768 by @var{function} are ignored and thrown away rather than being
3769 collected into a list.  The return value of @code{mapc} is @var{seq},
3770 the first sequence.  This function is more general than the Emacs
3771 primitive @code{mapc}.
3772 @end defun
3774 @defun mapl function list &rest more-lists
3775 This function is like @code{maplist}, except that it throws away
3776 the values returned by @var{function}.
3777 @end defun
3779 @defun mapcan function seq &rest more-seqs
3780 This function is like @code{mapcar*}, except that it concatenates
3781 the return values (which must be lists) using @code{nconc},
3782 rather than simply collecting them into a list.
3783 @end defun
3785 @defun mapcon function list &rest more-lists
3786 This function is like @code{maplist}, except that it concatenates
3787 the return values using @code{nconc}.
3788 @end defun
3790 @defun some predicate seq &rest more-seqs
3791 This function calls @var{predicate} on each element of @var{seq}
3792 in turn; if @var{predicate} returns a non-@code{nil} value,
3793 @code{some} returns that value, otherwise it returns @code{nil}.
3794 Given several sequence arguments, it steps through the sequences
3795 in parallel until the shortest one runs out, just as in
3796 @code{mapcar*}.  You can rely on the left-to-right order in which
3797 the elements are visited, and on the fact that mapping stops
3798 immediately as soon as @var{predicate} returns non-@code{nil}.
3799 @end defun
3801 @defun every predicate seq &rest more-seqs
3802 This function calls @var{predicate} on each element of the sequence(s)
3803 in turn; it returns @code{nil} as soon as @var{predicate} returns
3804 @code{nil} for any element, or @code{t} if the predicate was true
3805 for all elements.
3806 @end defun
3808 @defun notany predicate seq &rest more-seqs
3809 This function calls @var{predicate} on each element of the sequence(s)
3810 in turn; it returns @code{nil} as soon as @var{predicate} returns
3811 a non-@code{nil} value for any element, or @code{t} if the predicate
3812 was @code{nil} for all elements.
3813 @end defun
3815 @defun notevery predicate seq &rest more-seqs
3816 This function calls @var{predicate} on each element of the sequence(s)
3817 in turn; it returns a non-@code{nil} value as soon as @var{predicate}
3818 returns @code{nil} for any element, or @code{t} if the predicate was
3819 true for all elements.
3820 @end defun
3822 @defun reduce function seq @t{&key :from-end :start :end :initial-value :key}
3823 This function combines the elements of @var{seq} using an associative
3824 binary operation.  Suppose @var{function} is @code{*} and @var{seq} is
3825 the list @code{(2 3 4 5)}.  The first two elements of the list are
3826 combined with @code{(* 2 3) = 6}; this is combined with the next
3827 element, @code{(* 6 4) = 24}, and that is combined with the final
3828 element: @code{(* 24 5) = 120}.  Note that the @code{*} function happens
3829 to be self-reducing, so that @code{(* 2 3 4 5)} has the same effect as
3830 an explicit call to @code{reduce}.
3832 If @code{:from-end} is true, the reduction is right-associative instead
3833 of left-associative:
3835 @example
3836 (reduce '- '(1 2 3 4))
3837      @equiv{} (- (- (- 1 2) 3) 4) @result{} -8
3838 (reduce '- '(1 2 3 4) :from-end t)
3839      @equiv{} (- 1 (- 2 (- 3 4))) @result{} -2
3840 @end example
3842 If @code{:key} is specified, it is a function of one argument which
3843 is called on each of the sequence elements in turn.
3845 If @code{:initial-value} is specified, it is effectively added to the
3846 front (or rear in the case of @code{:from-end}) of the sequence.
3847 The @code{:key} function is @emph{not} applied to the initial value.
3849 If the sequence, including the initial value, has exactly one element
3850 then that element is returned without ever calling @var{function}.
3851 If the sequence is empty (and there is no initial value), then
3852 @var{function} is called with no arguments to obtain the return value.
3853 @end defun
3855 All of these mapping operations can be expressed conveniently in
3856 terms of the @code{loop} macro.  In compiled code, @code{loop} will
3857 be faster since it generates the loop as in-line code with no
3858 function calls.
3860 @node Sequence Functions, Searching Sequences, Mapping over Sequences, Sequences
3861 @section Sequence Functions
3863 @noindent
3864 This section describes a number of Common Lisp functions for
3865 operating on sequences.
3867 @defun subseq sequence start &optional end
3868 This function returns a given subsequence of the argument
3869 @var{sequence}, which may be a list, string, or vector.
3870 The indices @var{start} and @var{end} must be in range, and
3871 @var{start} must be no greater than @var{end}.  If @var{end}
3872 is omitted, it defaults to the length of the sequence.  The
3873 return value is always a copy; it does not share structure
3874 with @var{sequence}.
3876 As an extension to Common Lisp, @var{start} and/or @var{end}
3877 may be negative, in which case they represent a distance back
3878 from the end of the sequence.  This is for compatibility with
3879 Emacs' @code{substring} function.  Note that @code{subseq} is
3880 the @emph{only} sequence function that allows negative
3881 @var{start} and @var{end}.
3883 You can use @code{setf} on a @code{subseq} form to replace a
3884 specified range of elements with elements from another sequence.
3885 The replacement is done as if by @code{replace}, described below.
3886 @end defun
3888 @defun concatenate result-type &rest seqs
3889 This function concatenates the argument sequences together to
3890 form a result sequence of type @var{result-type}, one of the
3891 symbols @code{vector}, @code{string}, or @code{list}.  The
3892 arguments are always copied, even in cases such as
3893 @code{(concatenate 'list '(1 2 3))} where the result is
3894 identical to an argument.
3895 @end defun
3897 @defun fill seq item @t{&key :start :end}
3898 This function fills the elements of the sequence (or the specified
3899 part of the sequence) with the value @var{item}.
3900 @end defun
3902 @defun replace seq1 seq2 @t{&key :start1 :end1 :start2 :end2}
3903 This function copies part of @var{seq2} into part of @var{seq1}.
3904 The sequence @var{seq1} is not stretched or resized; the amount
3905 of data copied is simply the shorter of the source and destination
3906 (sub)sequences.  The function returns @var{seq1}.
3908 If @var{seq1} and @var{seq2} are @code{eq}, then the replacement
3909 will work correctly even if the regions indicated by the start
3910 and end arguments overlap.  However, if @var{seq1} and @var{seq2}
3911 are lists which share storage but are not @code{eq}, and the
3912 start and end arguments specify overlapping regions, the effect
3913 is undefined.
3914 @end defun
3916 @defun remove* item seq @t{&key :test :test-not :key :count :start :end :from-end}
3917 This returns a copy of @var{seq} with all elements matching
3918 @var{item} removed.  The result may share storage with or be
3919 @code{eq} to @var{seq} in some circumstances, but the original
3920 @var{seq} will not be modified.  The @code{:test}, @code{:test-not},
3921 and @code{:key} arguments define the matching test that is used;
3922 by default, elements @code{eql} to @var{item} are removed.  The
3923 @code{:count} argument specifies the maximum number of matching
3924 elements that can be removed (only the leftmost @var{count} matches
3925 are removed).  The @code{:start} and @code{:end} arguments specify
3926 a region in @var{seq} in which elements will be removed; elements
3927 outside that region are not matched or removed.  The @code{:from-end}
3928 argument, if true, says that elements should be deleted from the
3929 end of the sequence rather than the beginning (this matters only
3930 if @var{count} was also specified).
3931 @end defun
3933 @defun delete* item seq @t{&key :test :test-not :key :count :start :end :from-end}
3934 This deletes all elements of @var{seq} which match @var{item}.
3935 It is a destructive operation.  Since Emacs Lisp does not support
3936 stretchable strings or vectors, this is the same as @code{remove*}
3937 for those sequence types.  On lists, @code{remove*} will copy the
3938 list if necessary to preserve the original list, whereas
3939 @code{delete*} will splice out parts of the argument list.
3940 Compare @code{append} and @code{nconc}, which are analogous
3941 non-destructive and destructive list operations in Emacs Lisp.
3942 @end defun
3944 @findex remove-if
3945 @findex remove-if-not
3946 @findex delete-if
3947 @findex delete-if-not
3948 The predicate-oriented functions @code{remove-if}, @code{remove-if-not},
3949 @code{delete-if}, and @code{delete-if-not} are defined similarly.
3951 @defun remove-duplicates seq @t{&key :test :test-not :key :start :end :from-end}
3952 This function returns a copy of @var{seq} with duplicate elements
3953 removed.  Specifically, if two elements from the sequence match
3954 according to the @code{:test}, @code{:test-not}, and @code{:key}
3955 arguments, only the rightmost one is retained.  If @code{:from-end}
3956 is true, the leftmost one is retained instead.  If @code{:start} or
3957 @code{:end} is specified, only elements within that subsequence are
3958 examined or removed.
3959 @end defun
3961 @defun delete-duplicates seq @t{&key :test :test-not :key :start :end :from-end}
3962 This function deletes duplicate elements from @var{seq}.  It is
3963 a destructive version of @code{remove-duplicates}.
3964 @end defun
3966 @defun substitute new old seq @t{&key :test :test-not :key :count :start :end :from-end}
3967 This function returns a copy of @var{seq}, with all elements
3968 matching @var{old} replaced with @var{new}.  The @code{:count},
3969 @code{:start}, @code{:end}, and @code{:from-end} arguments may be
3970 used to limit the number of substitutions made.
3971 @end defun
3973 @defun nsubstitute new old seq @t{&key :test :test-not :key :count :start :end :from-end}
3974 This is a destructive version of @code{substitute}; it performs
3975 the substitution using @code{setcar} or @code{aset} rather than
3976 by returning a changed copy of the sequence.
3977 @end defun
3979 @findex substitute-if
3980 @findex substitute-if-not
3981 @findex nsubstitute-if
3982 @findex nsubstitute-if-not
3983 The @code{substitute-if}, @code{substitute-if-not}, @code{nsubstitute-if},
3984 and @code{nsubstitute-if-not} functions are defined similarly.  For
3985 these, a @var{predicate} is given in place of the @var{old} argument.
3987 @node Searching Sequences, Sorting Sequences, Sequence Functions, Sequences
3988 @section Searching Sequences
3990 @noindent
3991 These functions search for elements or subsequences in a sequence.
3992 (See also @code{member*} and @code{assoc*}; @pxref{Lists}.)
3994 @defun find item seq @t{&key :test :test-not :key :start :end :from-end}
3995 This function searches @var{seq} for an element matching @var{item}.
3996 If it finds a match, it returns the matching element.  Otherwise,
3997 it returns @code{nil}.  It returns the leftmost match, unless
3998 @code{:from-end} is true, in which case it returns the rightmost
3999 match.  The @code{:start} and @code{:end} arguments may be used to
4000 limit the range of elements that are searched.
4001 @end defun
4003 @defun position item seq @t{&key :test :test-not :key :start :end :from-end}
4004 This function is like @code{find}, except that it returns the
4005 integer position in the sequence of the matching item rather than
4006 the item itself.  The position is relative to the start of the
4007 sequence as a whole, even if @code{:start} is non-zero.  The function
4008 returns @code{nil} if no matching element was found.
4009 @end defun
4011 @defun count item seq @t{&key :test :test-not :key :start :end}
4012 This function returns the number of elements of @var{seq} which
4013 match @var{item}.  The result is always a nonnegative integer.
4014 @end defun
4016 @findex find-if
4017 @findex find-if-not
4018 @findex position-if
4019 @findex position-if-not
4020 @findex count-if
4021 @findex count-if-not
4022 The @code{find-if}, @code{find-if-not}, @code{position-if},
4023 @code{position-if-not}, @code{count-if}, and @code{count-if-not}
4024 functions are defined similarly.
4026 @defun mismatch seq1 seq2 @t{&key :test :test-not :key :start1 :end1 :start2 :end2 :from-end}
4027 This function compares the specified parts of @var{seq1} and
4028 @var{seq2}.  If they are the same length and the corresponding
4029 elements match (according to @code{:test}, @code{:test-not},
4030 and @code{:key}), the function returns @code{nil}.  If there is
4031 a mismatch, the function returns the index (relative to @var{seq1})
4032 of the first mismatching element.  This will be the leftmost pair of
4033 elements which do not match, or the position at which the shorter of
4034 the two otherwise-matching sequences runs out.
4036 If @code{:from-end} is true, then the elements are compared from right
4037 to left starting at @code{(1- @var{end1})} and @code{(1- @var{end2})}.
4038 If the sequences differ, then one plus the index of the rightmost
4039 difference (relative to @var{seq1}) is returned.
4041 An interesting example is @code{(mismatch str1 str2 :key 'upcase)},
4042 which compares two strings case-insensitively.
4043 @end defun
4045 @defun search seq1 seq2 @t{&key :test :test-not :key :from-end :start1 :end1 :start2 :end2}
4046 This function searches @var{seq2} for a subsequence that matches
4047 @var{seq1} (or part of it specified by @code{:start1} and
4048 @code{:end1}.)  Only matches which fall entirely within the region
4049 defined by @code{:start2} and @code{:end2} will be considered.
4050 The return value is the index of the leftmost element of the
4051 leftmost match, relative to the start of @var{seq2}, or @code{nil}
4052 if no matches were found.  If @code{:from-end} is true, the
4053 function finds the @emph{rightmost} matching subsequence.
4054 @end defun
4056 @node Sorting Sequences,  , Searching Sequences, Sequences
4057 @section Sorting Sequences
4059 @defun sort* seq predicate @t{&key :key}
4060 This function sorts @var{seq} into increasing order as determined
4061 by using @var{predicate} to compare pairs of elements.  @var{predicate}
4062 should return true (non-@code{nil}) if and only if its first argument
4063 is less than (not equal to) its second argument.  For example,
4064 @code{<} and @code{string-lessp} are suitable predicate functions
4065 for sorting numbers and strings, respectively; @code{>} would sort
4066 numbers into decreasing rather than increasing order.
4068 This function differs from Emacs' built-in @code{sort} in that it
4069 can operate on any type of sequence, not just lists.  Also, it
4070 accepts a @code{:key} argument which is used to preprocess data
4071 fed to the @var{predicate} function.  For example,
4073 @example
4074 (setq data (sort* data 'string-lessp :key 'downcase))
4075 @end example
4077 @noindent
4078 sorts @var{data}, a sequence of strings, into increasing alphabetical
4079 order without regard to case.  A @code{:key} function of @code{car}
4080 would be useful for sorting association lists.  It should only be a
4081 simple accessor though, it's used heavily in the current
4082 implementation.
4084 The @code{sort*} function is destructive; it sorts lists by actually
4085 rearranging the @code{cdr} pointers in suitable fashion.
4086 @end defun
4088 @defun stable-sort seq predicate @t{&key :key}
4089 This function sorts @var{seq} @dfn{stably}, meaning two elements
4090 which are equal in terms of @var{predicate} are guaranteed not to
4091 be rearranged out of their original order by the sort.
4093 In practice, @code{sort*} and @code{stable-sort} are equivalent
4094 in Emacs Lisp because the underlying @code{sort} function is
4095 stable by default.  However, this package reserves the right to
4096 use non-stable methods for @code{sort*} in the future.
4097 @end defun
4099 @defun merge type seq1 seq2 predicate @t{&key :key}
4100 This function merges two sequences @var{seq1} and @var{seq2} by
4101 interleaving their elements.  The result sequence, of type @var{type}
4102 (in the sense of @code{concatenate}), has length equal to the sum
4103 of the lengths of the two input sequences.  The sequences may be
4104 modified destructively.  Order of elements within @var{seq1} and
4105 @var{seq2} is preserved in the interleaving; elements of the two
4106 sequences are compared by @var{predicate} (in the sense of
4107 @code{sort}) and the lesser element goes first in the result.
4108 When elements are equal, those from @var{seq1} precede those from
4109 @var{seq2} in the result.  Thus, if @var{seq1} and @var{seq2} are
4110 both sorted according to @var{predicate}, then the result will be
4111 a merged sequence which is (stably) sorted according to
4112 @var{predicate}.
4113 @end defun
4115 @node Lists, Structures, Sequences, Top
4116 @chapter Lists
4118 @noindent
4119 The functions described here operate on lists.
4121 @menu
4122 * List Functions::                `caddr', `first', `list*', etc.
4123 * Substitution of Expressions::   `subst', `sublis', etc.
4124 * Lists as Sets::                 `member*', `adjoin', `union', etc.
4125 * Association Lists::             `assoc*', `rassoc*', `acons', `pairlis'
4126 @end menu
4128 @node List Functions, Substitution of Expressions, Lists, Lists
4129 @section List Functions
4131 @noindent
4132 This section describes a number of simple operations on lists,
4133 i.e., chains of cons cells.
4135 @defun caddr x
4136 This function is equivalent to @code{(car (cdr (cdr @var{x})))}.
4137 Likewise, this package defines all 28 @code{c@var{xxx}r} functions
4138 where @var{xxx} is up to four @samp{a}s and/or @samp{d}s.
4139 All of these functions are @code{setf}-able, and calls to them
4140 are expanded inline by the byte-compiler for maximum efficiency.
4141 @end defun
4143 @defun first x
4144 This function is a synonym for @code{(car @var{x})}.  Likewise,
4145 the functions @code{second}, @code{third}, @dots{}, through
4146 @code{tenth} return the given element of the list @var{x}.
4147 @end defun
4149 @defun rest x
4150 This function is a synonym for @code{(cdr @var{x})}.
4151 @end defun
4153 @defun endp x
4154 Common Lisp defines this function to act like @code{null}, but
4155 signaling an error if @code{x} is neither a @code{nil} nor a
4156 cons cell.  This package simply defines @code{endp} as a synonym
4157 for @code{null}.
4158 @end defun
4160 @defun list-length x
4161 This function returns the length of list @var{x}, exactly like
4162 @code{(length @var{x})}, except that if @var{x} is a circular
4163 list (where the cdr-chain forms a loop rather than terminating
4164 with @code{nil}), this function returns @code{nil}.  (The regular
4165 @code{length} function would get stuck if given a circular list.)
4166 @end defun
4168 @defun list* arg &rest others
4169 This function constructs a list of its arguments.  The final
4170 argument becomes the @code{cdr} of the last cell constructed.
4171 Thus, @code{(list* @var{a} @var{b} @var{c})} is equivalent to
4172 @code{(cons @var{a} (cons @var{b} @var{c}))}, and
4173 @code{(list* @var{a} @var{b} nil)} is equivalent to
4174 @code{(list @var{a} @var{b})}.
4176 (Note that this function really is called @code{list*} in Common
4177 Lisp; it is not a name invented for this package like @code{member*}
4178 or @code{defun*}.)
4179 @end defun
4181 @defun ldiff list sublist
4182 If @var{sublist} is a sublist of @var{list}, i.e., is @code{eq} to
4183 one of the cons cells of @var{list}, then this function returns
4184 a copy of the part of @var{list} up to but not including
4185 @var{sublist}.  For example, @code{(ldiff x (cddr x))} returns
4186 the first two elements of the list @code{x}.  The result is a
4187 copy; the original @var{list} is not modified.  If @var{sublist}
4188 is not a sublist of @var{list}, a copy of the entire @var{list}
4189 is returned.
4190 @end defun
4192 @defun copy-list list
4193 This function returns a copy of the list @var{list}.  It copies
4194 dotted lists like @code{(1 2 . 3)} correctly.
4195 @end defun
4197 @defun copy-tree x &optional vecp
4198 This function returns a copy of the tree of cons cells @var{x}.
4199 Unlike @code{copy-sequence} (and its alias @code{copy-list}),
4200 which copies only along the @code{cdr} direction, this function
4201 copies (recursively) along both the @code{car} and the @code{cdr}
4202 directions.  If @var{x} is not a cons cell, the function simply
4203 returns @var{x} unchanged.  If the optional @var{vecp} argument
4204 is true, this function copies vectors (recursively) as well as
4205 cons cells.
4206 @end defun
4208 @defun tree-equal x y @t{&key :test :test-not :key}
4209 This function compares two trees of cons cells.  If @var{x} and
4210 @var{y} are both cons cells, their @code{car}s and @code{cdr}s are
4211 compared recursively.  If neither @var{x} nor @var{y} is a cons
4212 cell, they are compared by @code{eql}, or according to the
4213 specified test.  The @code{:key} function, if specified, is
4214 applied to the elements of both trees.  @xref{Sequences}.
4215 @end defun
4217 @iftex
4218 @secno=3
4219 @end iftex
4221 @node Substitution of Expressions, Lists as Sets, List Functions, Lists
4222 @section Substitution of Expressions
4224 @noindent
4225 These functions substitute elements throughout a tree of cons
4226 cells.  (@xref{Sequence Functions}, for the @code{substitute}
4227 function, which works on just the top-level elements of a list.)
4229 @defun subst new old tree @t{&key :test :test-not :key}
4230 This function substitutes occurrences of @var{old} with @var{new}
4231 in @var{tree}, a tree of cons cells.  It returns a substituted
4232 tree, which will be a copy except that it may share storage with
4233 the argument @var{tree} in parts where no substitutions occurred.
4234 The original @var{tree} is not modified.  This function recurses
4235 on, and compares against @var{old}, both @code{car}s and @code{cdr}s
4236 of the component cons cells.  If @var{old} is itself a cons cell,
4237 then matching cells in the tree are substituted as usual without
4238 recursively substituting in that cell.  Comparisons with @var{old}
4239 are done according to the specified test (@code{eql} by default).
4240 The @code{:key} function is applied to the elements of the tree
4241 but not to @var{old}.
4242 @end defun
4244 @defun nsubst new old tree @t{&key :test :test-not :key}
4245 This function is like @code{subst}, except that it works by
4246 destructive modification (by @code{setcar} or @code{setcdr})
4247 rather than copying.
4248 @end defun
4250 @findex subst-if
4251 @findex subst-if-not
4252 @findex nsubst-if
4253 @findex nsubst-if-not
4254 The @code{subst-if}, @code{subst-if-not}, @code{nsubst-if}, and
4255 @code{nsubst-if-not} functions are defined similarly.
4257 @defun sublis alist tree @t{&key :test :test-not :key}
4258 This function is like @code{subst}, except that it takes an
4259 association list @var{alist} of @var{old}-@var{new} pairs.
4260 Each element of the tree (after applying the @code{:key}
4261 function, if any), is compared with the @code{car}s of
4262 @var{alist}; if it matches, it is replaced by the corresponding
4263 @code{cdr}.
4264 @end defun
4266 @defun nsublis alist tree @t{&key :test :test-not :key}
4267 This is a destructive version of @code{sublis}.
4268 @end defun
4270 @node Lists as Sets, Association Lists, Substitution of Expressions, Lists
4271 @section Lists as Sets
4273 @noindent
4274 These functions perform operations on lists which represent sets
4275 of elements.
4277 @defun member* item list @t{&key :test :test-not :key}
4278 This function searches @var{list} for an element matching @var{item}.
4279 If a match is found, it returns the cons cell whose @code{car} was
4280 the matching element.  Otherwise, it returns @code{nil}.  Elements
4281 are compared by @code{eql} by default; you can use the @code{:test},
4282 @code{:test-not}, and @code{:key} arguments to modify this behavior.
4283 @xref{Sequences}.
4285 Note that this function's name is suffixed by @samp{*} to avoid
4286 the incompatible @code{member} function defined in Emacs.
4287 (That function uses @code{equal} for comparisons; it is equivalent
4288 to @code{(member* @var{item} @var{list} :test 'equal)}.)
4289 @end defun
4291 @findex member-if
4292 @findex member-if-not
4293 The @code{member-if} and @code{member-if-not} functions
4294 analogously search for elements which satisfy a given predicate.
4296 @defun tailp sublist list
4297 This function returns @code{t} if @var{sublist} is a sublist of
4298 @var{list}, i.e., if @var{sublist} is @code{eql} to @var{list} or to
4299 any of its @code{cdr}s.
4300 @end defun
4302 @defun adjoin item list @t{&key :test :test-not :key}
4303 This function conses @var{item} onto the front of @var{list},
4304 like @code{(cons @var{item} @var{list})}, but only if @var{item}
4305 is not already present on the list (as determined by @code{member*}).
4306 If a @code{:key} argument is specified, it is applied to
4307 @var{item} as well as to the elements of @var{list} during
4308 the search, on the reasoning that @var{item} is ``about'' to
4309 become part of the list.
4310 @end defun
4312 @defun union list1 list2 @t{&key :test :test-not :key}
4313 This function combines two lists which represent sets of items,
4314 returning a list that represents the union of those two sets.
4315 The result list will contain all items which appear in @var{list1}
4316 or @var{list2}, and no others.  If an item appears in both
4317 @var{list1} and @var{list2} it will be copied only once.  If
4318 an item is duplicated in @var{list1} or @var{list2}, it is
4319 undefined whether or not that duplication will survive in the
4320 result list.  The order of elements in the result list is also
4321 undefined.
4322 @end defun
4324 @defun nunion list1 list2 @t{&key :test :test-not :key}
4325 This is a destructive version of @code{union}; rather than copying,
4326 it tries to reuse the storage of the argument lists if possible.
4327 @end defun
4329 @defun intersection list1 list2 @t{&key :test :test-not :key}
4330 This function computes the intersection of the sets represented
4331 by @var{list1} and @var{list2}.  It returns the list of items
4332 which appear in both @var{list1} and @var{list2}.
4333 @end defun
4335 @defun nintersection list1 list2 @t{&key :test :test-not :key}
4336 This is a destructive version of @code{intersection}.  It
4337 tries to reuse storage of @var{list1} rather than copying.
4338 It does @emph{not} reuse the storage of @var{list2}.
4339 @end defun
4341 @defun set-difference list1 list2 @t{&key :test :test-not :key}
4342 This function computes the ``set difference'' of @var{list1}
4343 and @var{list2}, i.e., the set of elements that appear in
4344 @var{list1} but @emph{not} in @var{list2}.
4345 @end defun
4347 @defun nset-difference list1 list2 @t{&key :test :test-not :key}
4348 This is a destructive @code{set-difference}, which will try
4349 to reuse @var{list1} if possible.
4350 @end defun
4352 @defun set-exclusive-or list1 list2 @t{&key :test :test-not :key}
4353 This function computes the ``set exclusive or'' of @var{list1}
4354 and @var{list2}, i.e., the set of elements that appear in
4355 exactly one of @var{list1} and @var{list2}.
4356 @end defun
4358 @defun nset-exclusive-or list1 list2 @t{&key :test :test-not :key}
4359 This is a destructive @code{set-exclusive-or}, which will try
4360 to reuse @var{list1} and @var{list2} if possible.
4361 @end defun
4363 @defun subsetp list1 list2 @t{&key :test :test-not :key}
4364 This function checks whether @var{list1} represents a subset
4365 of @var{list2}, i.e., whether every element of @var{list1}
4366 also appears in @var{list2}.
4367 @end defun
4369 @node Association Lists,  , Lists as Sets, Lists
4370 @section Association Lists
4372 @noindent
4373 An @dfn{association list} is a list representing a mapping from
4374 one set of values to another; any list whose elements are cons
4375 cells is an association list.
4377 @defun assoc* item a-list @t{&key :test :test-not :key}
4378 This function searches the association list @var{a-list} for an
4379 element whose @code{car} matches (in the sense of @code{:test},
4380 @code{:test-not}, and @code{:key}, or by comparison with @code{eql})
4381 a given @var{item}.  It returns the matching element, if any,
4382 otherwise @code{nil}.  It ignores elements of @var{a-list} which
4383 are not cons cells.  (This corresponds to the behavior of
4384 @code{assq} and @code{assoc} in Emacs Lisp; Common Lisp's
4385 @code{assoc} ignores @code{nil}s but considers any other non-cons
4386 elements of @var{a-list} to be an error.)
4387 @end defun
4389 @defun rassoc* item a-list @t{&key :test :test-not :key}
4390 This function searches for an element whose @code{cdr} matches
4391 @var{item}.  If @var{a-list} represents a mapping, this applies
4392 the inverse of the mapping to @var{item}.
4393 @end defun
4395 @findex assoc-if
4396 @findex assoc-if-not
4397 @findex rassoc-if
4398 @findex rassoc-if-not
4399 The @code{assoc-if}, @code{assoc-if-not}, @code{rassoc-if},
4400 and @code{rassoc-if-not} functions are defined similarly.
4402 Two simple functions for constructing association lists are:
4404 @defun acons key value alist
4405 This is equivalent to @code{(cons (cons @var{key} @var{value}) @var{alist})}.
4406 @end defun
4408 @defun pairlis keys values &optional alist
4409 This is equivalent to @code{(nconc (mapcar* 'cons @var{keys} @var{values})
4410 @var{alist})}.
4411 @end defun
4413 @iftex
4414 @chapno=18
4415 @end iftex
4417 @node Structures, Assertions, Lists, Top
4418 @chapter Structures
4420 @noindent
4421 The Common Lisp @dfn{structure} mechanism provides a general way
4422 to define data types similar to C's @code{struct} types.  A
4423 structure is a Lisp object containing some number of @dfn{slots},
4424 each of which can hold any Lisp data object.  Functions are
4425 provided for accessing and setting the slots, creating or copying
4426 structure objects, and recognizing objects of a particular structure
4427 type.
4429 In true Common Lisp, each structure type is a new type distinct
4430 from all existing Lisp types.  Since the underlying Emacs Lisp
4431 system provides no way to create new distinct types, this package
4432 implements structures as vectors (or lists upon request) with a
4433 special ``tag'' symbol to identify them.
4435 @defspec defstruct name slots@dots{}
4436 The @code{defstruct} form defines a new structure type called
4437 @var{name}, with the specified @var{slots}.  (The @var{slots}
4438 may begin with a string which documents the structure type.)
4439 In the simplest case, @var{name} and each of the @var{slots}
4440 are symbols.  For example,
4442 @example
4443 (defstruct person name age sex)
4444 @end example
4446 @noindent
4447 defines a struct type called @code{person} which contains three
4448 slots.  Given a @code{person} object @var{p}, you can access those
4449 slots by calling @code{(person-name @var{p})}, @code{(person-age @var{p})},
4450 and @code{(person-sex @var{p})}.  You can also change these slots by
4451 using @code{setf} on any of these place forms:
4453 @example
4454 (incf (person-age birthday-boy))
4455 @end example
4457 You can create a new @code{person} by calling @code{make-person},
4458 which takes keyword arguments @code{:name}, @code{:age}, and
4459 @code{:sex} to specify the initial values of these slots in the
4460 new object.  (Omitting any of these arguments leaves the corresponding
4461 slot ``undefined,'' according to the Common Lisp standard; in Emacs
4462 Lisp, such uninitialized slots are filled with @code{nil}.)
4464 Given a @code{person}, @code{(copy-person @var{p})} makes a new
4465 object of the same type whose slots are @code{eq} to those of @var{p}.
4467 Given any Lisp object @var{x}, @code{(person-p @var{x})} returns
4468 true if @var{x} looks like a @code{person}, false otherwise.  (Again,
4469 in Common Lisp this predicate would be exact; in Emacs Lisp the
4470 best it can do is verify that @var{x} is a vector of the correct
4471 length which starts with the correct tag symbol.)
4473 Accessors like @code{person-name} normally check their arguments
4474 (effectively using @code{person-p}) and signal an error if the
4475 argument is the wrong type.  This check is affected by
4476 @code{(optimize (safety @dots{}))} declarations.  Safety level 1,
4477 the default, uses a somewhat optimized check that will detect all
4478 incorrect arguments, but may use an uninformative error message
4479 (e.g., ``expected a vector'' instead of ``expected a @code{person}'').
4480 Safety level 0 omits all checks except as provided by the underlying
4481 @code{aref} call; safety levels 2 and 3 do rigorous checking that will
4482 always print a descriptive error message for incorrect inputs.
4483 @xref{Declarations}.
4485 @example
4486 (setq dave (make-person :name "Dave" :sex 'male))
4487      @result{} [cl-struct-person "Dave" nil male]
4488 (setq other (copy-person dave))
4489      @result{} [cl-struct-person "Dave" nil male]
4490 (eq dave other)
4491      @result{} nil
4492 (eq (person-name dave) (person-name other))
4493      @result{} t
4494 (person-p dave)
4495      @result{} t
4496 (person-p [1 2 3 4])
4497      @result{} nil
4498 (person-p "Bogus")
4499      @result{} nil
4500 (person-p '[cl-struct-person counterfeit person object])
4501      @result{} t
4502 @end example
4504 In general, @var{name} is either a name symbol or a list of a name
4505 symbol followed by any number of @dfn{struct options}; each @var{slot}
4506 is either a slot symbol or a list of the form @samp{(@var{slot-name}
4507 @var{default-value} @var{slot-options}@dots{})}.  The @var{default-value}
4508 is a Lisp form which is evaluated any time an instance of the
4509 structure type is created without specifying that slot's value.
4511 Common Lisp defines several slot options, but the only one
4512 implemented in this package is @code{:read-only}.  A non-@code{nil}
4513 value for this option means the slot should not be @code{setf}-able;
4514 the slot's value is determined when the object is created and does
4515 not change afterward.
4517 @example
4518 (defstruct person
4519   (name nil :read-only t)
4520   age
4521   (sex 'unknown))
4522 @end example
4524 Any slot options other than @code{:read-only} are ignored.
4526 For obscure historical reasons, structure options take a different
4527 form than slot options.  A structure option is either a keyword
4528 symbol, or a list beginning with a keyword symbol possibly followed
4529 by arguments.  (By contrast, slot options are key-value pairs not
4530 enclosed in lists.)
4532 @example
4533 (defstruct (person (:constructor create-person)
4534                    (:type list)
4535                    :named)
4536   name age sex)
4537 @end example
4539 The following structure options are recognized.
4541 @table @code
4542 @iftex
4543 @itemmax=0 in
4544 @advance@leftskip-.5@tableindent
4545 @end iftex
4546 @item :conc-name
4547 The argument is a symbol whose print name is used as the prefix for
4548 the names of slot accessor functions.  The default is the name of
4549 the struct type followed by a hyphen.  The option @code{(:conc-name p-)}
4550 would change this prefix to @code{p-}.  Specifying @code{nil} as an
4551 argument means no prefix, so that the slot names themselves are used
4552 to name the accessor functions.
4554 @item :constructor
4555 In the simple case, this option takes one argument which is an
4556 alternate name to use for the constructor function.  The default
4557 is @code{make-@var{name}}, e.g., @code{make-person}.  The above
4558 example changes this to @code{create-person}.  Specifying @code{nil}
4559 as an argument means that no standard constructor should be
4560 generated at all.
4562 In the full form of this option, the constructor name is followed
4563 by an arbitrary argument list.  @xref{Program Structure}, for a
4564 description of the format of Common Lisp argument lists.  All
4565 options, such as @code{&rest} and @code{&key}, are supported.
4566 The argument names should match the slot names; each slot is
4567 initialized from the corresponding argument.  Slots whose names
4568 do not appear in the argument list are initialized based on the
4569 @var{default-value} in their slot descriptor.  Also, @code{&optional}
4570 and @code{&key} arguments which don't specify defaults take their
4571 defaults from the slot descriptor.  It is valid to include arguments
4572 which don't correspond to slot names; these are useful if they are
4573 referred to in the defaults for optional, keyword, or @code{&aux}
4574 arguments which @emph{do} correspond to slots.
4576 You can specify any number of full-format @code{:constructor}
4577 options on a structure.  The default constructor is still generated
4578 as well unless you disable it with a simple-format @code{:constructor}
4579 option.
4581 @example
4582 (defstruct
4583  (person
4584   (:constructor nil)   ; no default constructor
4585   (:constructor new-person (name sex &optional (age 0)))
4586   (:constructor new-hound (&key (name "Rover")
4587                                 (dog-years 0)
4588                            &aux (age (* 7 dog-years))
4589                                 (sex 'canine))))
4590  name age sex)
4591 @end example
4593 The first constructor here takes its arguments positionally rather
4594 than by keyword.  (In official Common Lisp terminology, constructors
4595 that work By Order of Arguments instead of by keyword are called
4596 ``BOA constructors.''  No, I'm not making this up.)  For example,
4597 @code{(new-person "Jane" 'female)} generates a person whose slots
4598 are @code{"Jane"}, 0, and @code{female}, respectively.
4600 The second constructor takes two keyword arguments, @code{:name},
4601 which initializes the @code{name} slot and defaults to @code{"Rover"},
4602 and @code{:dog-years}, which does not itself correspond to a slot
4603 but which is used to initialize the @code{age} slot.  The @code{sex}
4604 slot is forced to the symbol @code{canine} with no syntax for
4605 overriding it.
4607 @item :copier
4608 The argument is an alternate name for the copier function for
4609 this type.  The default is @code{copy-@var{name}}.  @code{nil}
4610 means not to generate a copier function.  (In this implementation,
4611 all copier functions are simply synonyms for @code{copy-sequence}.)
4613 @item :predicate
4614 The argument is an alternate name for the predicate which recognizes
4615 objects of this type.  The default is @code{@var{name}-p}.  @code{nil}
4616 means not to generate a predicate function.  (If the @code{:type}
4617 option is used without the @code{:named} option, no predicate is
4618 ever generated.)
4620 In true Common Lisp, @code{typep} is always able to recognize a
4621 structure object even if @code{:predicate} was used.  In this
4622 package, @code{typep} simply looks for a function called
4623 @code{@var{typename}-p}, so it will work for structure types
4624 only if they used the default predicate name.
4626 @item :include
4627 This option implements a very limited form of C++-style inheritance.
4628 The argument is the name of another structure type previously
4629 created with @code{defstruct}.  The effect is to cause the new
4630 structure type to inherit all of the included structure's slots
4631 (plus, of course, any new slots described by this struct's slot
4632 descriptors).  The new structure is considered a ``specialization''
4633 of the included one.  In fact, the predicate and slot accessors
4634 for the included type will also accept objects of the new type.
4636 If there are extra arguments to the @code{:include} option after
4637 the included-structure name, these options are treated as replacement
4638 slot descriptors for slots in the included structure, possibly with
4639 modified default values.  Borrowing an example from Steele:
4641 @example
4642 (defstruct person name (age 0) sex)
4643      @result{} person
4644 (defstruct (astronaut (:include person (age 45)))
4645   helmet-size
4646   (favorite-beverage 'tang))
4647      @result{} astronaut
4649 (setq joe (make-person :name "Joe"))
4650      @result{} [cl-struct-person "Joe" 0 nil]
4651 (setq buzz (make-astronaut :name "Buzz"))
4652      @result{} [cl-struct-astronaut "Buzz" 45 nil nil tang]
4654 (list (person-p joe) (person-p buzz))
4655      @result{} (t t)
4656 (list (astronaut-p joe) (astronaut-p buzz))
4657      @result{} (nil t)
4659 (person-name buzz)
4660      @result{} "Buzz"
4661 (astronaut-name joe)
4662      @result{} error: "astronaut-name accessing a non-astronaut"
4663 @end example
4665 Thus, if @code{astronaut} is a specialization of @code{person},
4666 then every @code{astronaut} is also a @code{person} (but not the
4667 other way around).  Every @code{astronaut} includes all the slots
4668 of a @code{person}, plus extra slots that are specific to
4669 astronauts.  Operations that work on people (like @code{person-name})
4670 work on astronauts just like other people.
4672 @item :print-function
4673 In full Common Lisp, this option allows you to specify a function
4674 which is called to print an instance of the structure type.  The
4675 Emacs Lisp system offers no hooks into the Lisp printer which would
4676 allow for such a feature, so this package simply ignores
4677 @code{:print-function}.
4679 @item :type
4680 The argument should be one of the symbols @code{vector} or @code{list}.
4681 This tells which underlying Lisp data type should be used to implement
4682 the new structure type.  Vectors are used by default, but
4683 @code{(:type list)} will cause structure objects to be stored as
4684 lists instead.
4686 The vector representation for structure objects has the advantage
4687 that all structure slots can be accessed quickly, although creating
4688 vectors is a bit slower in Emacs Lisp.  Lists are easier to create,
4689 but take a relatively long time accessing the later slots.
4691 @item :named
4692 This option, which takes no arguments, causes a characteristic ``tag''
4693 symbol to be stored at the front of the structure object.  Using
4694 @code{:type} without also using @code{:named} will result in a
4695 structure type stored as plain vectors or lists with no identifying
4696 features.
4698 The default, if you don't specify @code{:type} explicitly, is to
4699 use named vectors.  Therefore, @code{:named} is only useful in
4700 conjunction with @code{:type}.
4702 @example
4703 (defstruct (person1) name age sex)
4704 (defstruct (person2 (:type list) :named) name age sex)
4705 (defstruct (person3 (:type list)) name age sex)
4707 (setq p1 (make-person1))
4708      @result{} [cl-struct-person1 nil nil nil]
4709 (setq p2 (make-person2))
4710      @result{} (person2 nil nil nil)
4711 (setq p3 (make-person3))
4712      @result{} (nil nil nil)
4714 (person1-p p1)
4715      @result{} t
4716 (person2-p p2)
4717      @result{} t
4718 (person3-p p3)
4719      @result{} error: function person3-p undefined
4720 @end example
4722 Since unnamed structures don't have tags, @code{defstruct} is not
4723 able to make a useful predicate for recognizing them.  Also,
4724 accessors like @code{person3-name} will be generated but they
4725 will not be able to do any type checking.  The @code{person3-name}
4726 function, for example, will simply be a synonym for @code{car} in
4727 this case.  By contrast, @code{person2-name} is able to verify
4728 that its argument is indeed a @code{person2} object before
4729 proceeding.
4731 @item :initial-offset
4732 The argument must be a nonnegative integer.  It specifies a
4733 number of slots to be left ``empty'' at the front of the
4734 structure.  If the structure is named, the tag appears at the
4735 specified position in the list or vector; otherwise, the first
4736 slot appears at that position.  Earlier positions are filled
4737 with @code{nil} by the constructors and ignored otherwise.  If
4738 the type @code{:include}s another type, then @code{:initial-offset}
4739 specifies a number of slots to be skipped between the last slot
4740 of the included type and the first new slot.
4741 @end table
4742 @end defspec
4744 Except as noted, the @code{defstruct} facility of this package is
4745 entirely compatible with that of Common Lisp.
4747 @iftex
4748 @chapno=23
4749 @end iftex
4751 @node Assertions, Efficiency Concerns, Structures, Top
4752 @chapter Assertions and Errors
4754 @noindent
4755 This section describes two macros that test @dfn{assertions}, i.e.,
4756 conditions which must be true if the program is operating correctly.
4757 Assertions never add to the behavior of a Lisp program; they simply
4758 make ``sanity checks'' to make sure everything is as it should be.
4760 If the optimization property @code{speed} has been set to 3, and
4761 @code{safety} is less than 3, then the byte-compiler will optimize
4762 away the following assertions.  Because assertions might be optimized
4763 away, it is a bad idea for them to include side-effects.
4765 @defspec assert test-form [show-args string args@dots{}]
4766 This form verifies that @var{test-form} is true (i.e., evaluates to
4767 a non-@code{nil} value).  If so, it returns @code{nil}.  If the test
4768 is not satisfied, @code{assert} signals an error.
4770 A default error message will be supplied which includes @var{test-form}.
4771 You can specify a different error message by including a @var{string}
4772 argument plus optional extra arguments.  Those arguments are simply
4773 passed to @code{error} to signal the error.
4775 If the optional second argument @var{show-args} is @code{t} instead
4776 of @code{nil}, then the error message (with or without @var{string})
4777 will also include all non-constant arguments of the top-level
4778 @var{form}.  For example:
4780 @example
4781 (assert (> x 10) t "x is too small: %d")
4782 @end example
4784 This usage of @var{show-args} is an extension to Common Lisp.  In
4785 true Common Lisp, the second argument gives a list of @var{places}
4786 which can be @code{setf}'d by the user before continuing from the
4787 error.  Since Emacs Lisp does not support continuable errors, it
4788 makes no sense to specify @var{places}.
4789 @end defspec
4791 @defspec check-type form type [string]
4792 This form verifies that @var{form} evaluates to a value of type
4793 @var{type}.  If so, it returns @code{nil}.  If not, @code{check-type}
4794 signals a @code{wrong-type-argument} error.  The default error message
4795 lists the erroneous value along with @var{type} and @var{form}
4796 themselves.  If @var{string} is specified, it is included in the
4797 error message in place of @var{type}.  For example:
4799 @example
4800 (check-type x (integer 1 *) "a positive integer")
4801 @end example
4803 @xref{Type Predicates}, for a description of the type specifiers
4804 that may be used for @var{type}.
4806 Note that in Common Lisp, the first argument to @code{check-type}
4807 must be a @var{place} suitable for use by @code{setf}, because
4808 @code{check-type} signals a continuable error that allows the
4809 user to modify @var{place}.
4810 @end defspec
4812 The following error-related macro is also defined:
4814 @defspec ignore-errors forms@dots{}
4815 This executes @var{forms} exactly like a @code{progn}, except that
4816 errors are ignored during the @var{forms}.  More precisely, if
4817 an error is signaled then @code{ignore-errors} immediately
4818 aborts execution of the @var{forms} and returns @code{nil}.
4819 If the @var{forms} complete successfully, @code{ignore-errors}
4820 returns the result of the last @var{form}.
4821 @end defspec
4823 @node Efficiency Concerns, Common Lisp Compatibility, Assertions, Top
4824 @appendix Efficiency Concerns
4826 @appendixsec Macros
4828 @noindent
4829 Many of the advanced features of this package, such as @code{defun*},
4830 @code{loop}, and @code{setf}, are implemented as Lisp macros.  In
4831 byte-compiled code, these complex notations will be expanded into
4832 equivalent Lisp code which is simple and efficient.  For example,
4833 the forms
4835 @example
4836 (incf i n)
4837 (push x (car p))
4838 @end example
4840 @noindent
4841 are expanded at compile-time to the Lisp forms
4843 @example
4844 (setq i (+ i n))
4845 (setcar p (cons x (car p)))
4846 @end example
4848 @noindent
4849 which are the most efficient ways of doing these respective operations
4850 in Lisp.  Thus, there is no performance penalty for using the more
4851 readable @code{incf} and @code{push} forms in your compiled code.
4853 @emph{Interpreted} code, on the other hand, must expand these macros
4854 every time they are executed.  For this reason it is strongly
4855 recommended that code making heavy use of macros be compiled.
4856 (The features labeled ``Special Form'' instead of ``Function'' in
4857 this manual are macros.)  A loop using @code{incf} a hundred times
4858 will execute considerably faster if compiled, and will also
4859 garbage-collect less because the macro expansion will not have
4860 to be generated, used, and thrown away a hundred times.
4862 You can find out how a macro expands by using the
4863 @code{cl-prettyexpand} function.
4865 @defun cl-prettyexpand form &optional full
4866 This function takes a single Lisp form as an argument and inserts
4867 a nicely formatted copy of it in the current buffer (which must be
4868 in Lisp mode so that indentation works properly).  It also expands
4869 all Lisp macros which appear in the form.  The easiest way to use
4870 this function is to go to the @code{*scratch*} buffer and type, say,
4872 @example
4873 (cl-prettyexpand '(loop for x below 10 collect x))
4874 @end example
4876 @noindent
4877 and type @kbd{C-x C-e} immediately after the closing parenthesis;
4878 the expansion
4880 @example
4881 (block nil
4882   (let* ((x 0)
4883          (G1004 nil))
4884     (while (< x 10)
4885       (setq G1004 (cons x G1004))
4886       (setq x (+ x 1)))
4887     (nreverse G1004)))
4888 @end example
4890 @noindent
4891 will be inserted into the buffer.  (The @code{block} macro is
4892 expanded differently in the interpreter and compiler, so
4893 @code{cl-prettyexpand} just leaves it alone.  The temporary
4894 variable @code{G1004} was created by @code{gensym}.)
4896 If the optional argument @var{full} is true, then @emph{all}
4897 macros are expanded, including @code{block}, @code{eval-when},
4898 and compiler macros.  Expansion is done as if @var{form} were
4899 a top-level form in a file being compiled.  For example,
4901 @example
4902 (cl-prettyexpand '(pushnew 'x list))
4903      @print{} (setq list (adjoin 'x list))
4904 (cl-prettyexpand '(pushnew 'x list) t)
4905      @print{} (setq list (if (memq 'x list) list (cons 'x list)))
4906 (cl-prettyexpand '(caddr (member* 'a list)) t)
4907      @print{} (car (cdr (cdr (memq 'a list))))
4908 @end example
4910 Note that @code{adjoin}, @code{caddr}, and @code{member*} all
4911 have built-in compiler macros to optimize them in common cases.
4912 @end defun
4914 @ifinfo
4915 @example
4917 @end example
4918 @end ifinfo
4919 @appendixsec Error Checking
4921 @noindent
4922 Common Lisp compliance has in general not been sacrificed for the
4923 sake of efficiency.  A few exceptions have been made for cases
4924 where substantial gains were possible at the expense of marginal
4925 incompatibility.
4927 The Common Lisp standard (as embodied in Steele's book) uses the
4928 phrase ``it is an error if'' to indicate a situation which is not
4929 supposed to arise in complying programs; implementations are strongly
4930 encouraged but not required to signal an error in these situations.
4931 This package sometimes omits such error checking in the interest of
4932 compactness and efficiency.  For example, @code{do} variable
4933 specifiers are supposed to be lists of one, two, or three forms;
4934 extra forms are ignored by this package rather than signaling a
4935 syntax error.  The @code{endp} function is simply a synonym for
4936 @code{null} in this package.  Functions taking keyword arguments
4937 will accept an odd number of arguments, treating the trailing
4938 keyword as if it were followed by the value @code{nil}.
4940 Argument lists (as processed by @code{defun*} and friends)
4941 @emph{are} checked rigorously except for the minor point just
4942 mentioned; in particular, keyword arguments are checked for
4943 validity, and @code{&allow-other-keys} and @code{:allow-other-keys}
4944 are fully implemented.  Keyword validity checking is slightly
4945 time consuming (though not too bad in byte-compiled code);
4946 you can use @code{&allow-other-keys} to omit this check.  Functions
4947 defined in this package such as @code{find} and @code{member*}
4948 do check their keyword arguments for validity.
4950 @ifinfo
4951 @example
4953 @end example
4954 @end ifinfo
4955 @appendixsec Optimizing Compiler
4957 @noindent
4958 Use of the optimizing Emacs compiler is highly recommended; many of the Common
4959 Lisp macros emit
4960 code which can be improved by optimization.  In particular,
4961 @code{block}s (whether explicit or implicit in constructs like
4962 @code{defun*} and @code{loop}) carry a fair run-time penalty; the
4963 optimizing compiler removes @code{block}s which are not actually
4964 referenced by @code{return} or @code{return-from} inside the block.
4966 @node Common Lisp Compatibility, Old CL Compatibility, Efficiency Concerns, Top
4967 @appendix Common Lisp Compatibility
4969 @noindent
4970 Following is a list of all known incompatibilities between this
4971 package and Common Lisp as documented in Steele (2nd edition).
4973 Certain function names, such as @code{member}, @code{assoc}, and
4974 @code{floor}, were already taken by (incompatible) Emacs Lisp
4975 functions; this package appends @samp{*} to the names of its
4976 Common Lisp versions of these functions.
4978 The word @code{defun*} is required instead of @code{defun} in order
4979 to use extended Common Lisp argument lists in a function.  Likewise,
4980 @code{defmacro*} and @code{function*} are versions of those forms
4981 which understand full-featured argument lists.  The @code{&whole}
4982 keyword does not work in @code{defmacro} argument lists (except
4983 inside recursive argument lists).
4985 The @code{equal} predicate does not distinguish
4986 between IEEE floating-point plus and minus zero.  The @code{equalp}
4987 predicate has several differences with Common Lisp; @pxref{Predicates}.
4989 The @code{setf} mechanism is entirely compatible, except that
4990 setf-methods return a list of five values rather than five
4991 values directly.  Also, the new ``@code{setf} function'' concept
4992 (typified by @code{(defun (setf foo) @dots{})}) is not implemented.
4994 The @code{do-all-symbols} form is the same as @code{do-symbols}
4995 with no @var{obarray} argument.  In Common Lisp, this form would
4996 iterate over all symbols in all packages.  Since Emacs obarrays
4997 are not a first-class package mechanism, there is no way for
4998 @code{do-all-symbols} to locate any but the default obarray.
5000 The @code{loop} macro is complete except that @code{loop-finish}
5001 and type specifiers are unimplemented.
5003 The multiple-value return facility treats lists as multiple
5004 values, since Emacs Lisp cannot support multiple return values
5005 directly.  The macros will be compatible with Common Lisp if
5006 @code{values} or @code{values-list} is always used to return to
5007 a @code{multiple-value-bind} or other multiple-value receiver;
5008 if @code{values} is used without @code{multiple-value-@dots{}}
5009 or vice-versa the effect will be different from Common Lisp.
5011 Many Common Lisp declarations are ignored, and others match
5012 the Common Lisp standard in concept but not in detail.  For
5013 example, local @code{special} declarations, which are purely
5014 advisory in Emacs Lisp, do not rigorously obey the scoping rules
5015 set down in Steele's book.
5017 The variable @code{*gensym-counter*} starts out with a pseudo-random
5018 value rather than with zero.  This is to cope with the fact that
5019 generated symbols become interned when they are written to and
5020 loaded back from a file.
5022 The @code{defstruct} facility is compatible, except that structures
5023 are of type @code{:type vector :named} by default rather than some
5024 special, distinct type.  Also, the @code{:type} slot option is ignored.
5026 The second argument of @code{check-type} is treated differently.
5028 @node Old CL Compatibility, Porting Common Lisp, Common Lisp Compatibility, Top
5029 @appendix Old CL Compatibility
5031 @noindent
5032 Following is a list of all known incompatibilities between this package
5033 and the older Quiroz @file{cl.el} package.
5035 This package's emulation of multiple return values in functions is
5036 incompatible with that of the older package.  That package attempted
5037 to come as close as possible to true Common Lisp multiple return
5038 values; unfortunately, it could not be 100% reliable and so was prone
5039 to occasional surprises if used freely.  This package uses a simpler
5040 method, namely replacing multiple values with lists of values, which
5041 is more predictable though more noticeably different from Common Lisp.
5043 The @code{defkeyword} form and @code{keywordp} function are not
5044 implemented in this package.
5046 The @code{member}, @code{floor}, @code{ceiling}, @code{truncate},
5047 @code{round}, @code{mod}, and @code{rem} functions are suffixed
5048 by @samp{*} in this package to avoid collision with existing
5049 functions in Emacs.  The older package simply
5050 redefined these functions, overwriting the built-in meanings and
5051 causing serious portability problems.  (Some more
5052 recent versions of the Quiroz package changed the names to
5053 @code{cl-member}, etc.; this package defines the latter names as
5054 aliases for @code{member*}, etc.)
5056 Certain functions in the old package which were buggy or inconsistent
5057 with the Common Lisp standard are incompatible with the conforming
5058 versions in this package.  For example, @code{eql} and @code{member}
5059 were synonyms for @code{eq} and @code{memq} in that package, @code{setf}
5060 failed to preserve correct order of evaluation of its arguments, etc.
5062 Finally, unlike the older package, this package is careful to
5063 prefix all of its internal names with @code{cl-}.  Except for a
5064 few functions which are explicitly defined as additional features
5065 (such as @code{floatp-safe} and @code{letf}), this package does not
5066 export any non-@samp{cl-} symbols which are not also part of Common
5067 Lisp.
5069 @ifinfo
5070 @example
5072 @end example
5073 @end ifinfo
5074 @appendixsec The @code{cl-compat} package
5076 @noindent
5077 The @dfn{CL} package includes emulations of some features of the
5078 old @file{cl.el}, in the form of a compatibility package
5079 @code{cl-compat}.  To use it, put @code{(require 'cl-compat)} in
5080 your program.
5082 The old package defined a number of internal routines without
5083 @code{cl-} prefixes or other annotations.  Call to these routines
5084 may have crept into existing Lisp code.  @code{cl-compat}
5085 provides emulations of the following internal routines:
5086 @code{pair-with-newsyms}, @code{zip-lists}, @code{unzip-lists},
5087 @code{reassemble-arglists}, @code{duplicate-symbols-p},
5088 @code{safe-idiv}.
5090 Some @code{setf} forms translated into calls to internal
5091 functions that user code might call directly.  The functions
5092 @code{setnth}, @code{setnthcdr}, and @code{setelt} fall in
5093 this category; they are defined by @code{cl-compat}, but the
5094 best fix is to change to use @code{setf} properly.
5096 The @code{cl-compat} file defines the keyword functions
5097 @code{keywordp}, @code{keyword-of}, and @code{defkeyword},
5098 which are not defined by the new @dfn{CL} package because the
5099 use of keywords as data is discouraged.
5101 The @code{build-klist} mechanism for parsing keyword arguments
5102 is emulated by @code{cl-compat}; the @code{with-keyword-args}
5103 macro is not, however, and in any case it's best to change to
5104 use the more natural keyword argument processing offered by
5105 @code{defun*}.
5107 Multiple return values are treated differently by the two
5108 Common Lisp packages.  The old package's method was more
5109 compatible with true Common Lisp, though it used heuristics
5110 that caused it to report spurious multiple return values in
5111 certain cases.  The @code{cl-compat} package defines a set
5112 of multiple-value macros that are compatible with the old
5113 CL package; again, they are heuristic in nature, but they
5114 are guaranteed to work in any case where the old package's
5115 macros worked.  To avoid name collision with the ``official''
5116 multiple-value facilities, the ones in @code{cl-compat} have
5117 capitalized names:  @code{Values}, @code{Values-list},
5118 @code{Multiple-value-bind}, etc.
5120 The functions @code{cl-floor}, @code{cl-ceiling}, @code{cl-truncate},
5121 and @code{cl-round} are defined by @code{cl-compat} to use the
5122 old-style multiple-value mechanism, just as they did in the old
5123 package.  The newer @code{floor*} and friends return their two
5124 results in a list rather than as multiple values.  Note that
5125 older versions of the old package used the unadorned names
5126 @code{floor}, @code{ceiling}, etc.; @code{cl-compat} cannot use
5127 these names because they conflict with Emacs built-ins.
5129 @node Porting Common Lisp, GNU Free Documentation License, Old CL Compatibility, Top
5130 @appendix Porting Common Lisp
5132 @noindent
5133 This package is meant to be used as an extension to Emacs Lisp,
5134 not as an Emacs implementation of true Common Lisp.  Some of the
5135 remaining differences between Emacs Lisp and Common Lisp make it
5136 difficult to port large Common Lisp applications to Emacs.  For
5137 one, some of the features in this package are not fully compliant
5138 with ANSI or Steele; @pxref{Common Lisp Compatibility}.  But there
5139 are also quite a few features that this package does not provide
5140 at all.  Here are some major omissions that you will want to watch out
5141 for when bringing Common Lisp code into Emacs.
5143 @itemize @bullet
5144 @item
5145 Case-insensitivity.  Symbols in Common Lisp are case-insensitive
5146 by default.  Some programs refer to a function or variable as
5147 @code{foo} in one place and @code{Foo} or @code{FOO} in another.
5148 Emacs Lisp will treat these as three distinct symbols.
5150 Some Common Lisp code is written entirely in upper case.  While Emacs
5151 is happy to let the program's own functions and variables use
5152 this convention, calls to Lisp builtins like @code{if} and
5153 @code{defun} will have to be changed to lower case.
5155 @item
5156 Lexical scoping.  In Common Lisp, function arguments and @code{let}
5157 bindings apply only to references physically within their bodies
5158 (or within macro expansions in their bodies).  Emacs Lisp, by
5159 contrast, uses @dfn{dynamic scoping} wherein a binding to a
5160 variable is visible even inside functions called from the body.
5162 Variables in Common Lisp can be made dynamically scoped by
5163 declaring them @code{special} or using @code{defvar}.  In Emacs
5164 Lisp it is as if all variables were declared @code{special}.
5166 Often you can use code that was written for lexical scoping
5167 even in a dynamically scoped Lisp, but not always.  Here is
5168 an example of a Common Lisp code fragment that would fail in
5169 Emacs Lisp:
5171 @example
5172 (defun map-odd-elements (func list)
5173   (loop for x in list
5174         for flag = t then (not flag)
5175         collect (if flag x (funcall func x))))
5177 (defun add-odd-elements (list x)
5178   (map-odd-elements (lambda (a) (+ a x)) list))
5179 @end example
5181 @noindent
5182 In Common Lisp, the two functions' usages of @code{x} are completely
5183 independent.  In Emacs Lisp, the binding to @code{x} made by
5184 @code{add-odd-elements} will have been hidden by the binding
5185 in @code{map-odd-elements} by the time the @code{(+ a x)} function
5186 is called.
5188 (This package avoids such problems in its own mapping functions
5189 by using names like @code{cl-x} instead of @code{x} internally;
5190 as long as you don't use the @code{cl-} prefix for your own
5191 variables no collision can occur.)
5193 @xref{Lexical Bindings}, for a description of the @code{lexical-let}
5194 form which establishes a Common Lisp-style lexical binding, and some
5195 examples of how it differs from Emacs' regular @code{let}.
5197 @item
5198 Reader macros.  Common Lisp includes a second type of macro that
5199 works at the level of individual characters.  For example, Common
5200 Lisp implements the quote notation by a reader macro called @code{'},
5201 whereas Emacs Lisp's parser just treats quote as a special case.
5202 Some Lisp packages use reader macros to create special syntaxes
5203 for themselves, which the Emacs parser is incapable of reading.
5205 @item
5206 Other syntactic features.  Common Lisp provides a number of
5207 notations beginning with @code{#} that the Emacs Lisp parser
5208 won't understand.  For example, @samp{#| ... |#} is an
5209 alternate comment notation, and @samp{#+lucid (foo)} tells
5210 the parser to ignore the @code{(foo)} except in Lucid Common
5211 Lisp.
5213 @item
5214 Packages.  In Common Lisp, symbols are divided into @dfn{packages}.
5215 Symbols that are Lisp built-ins are typically stored in one package;
5216 symbols that are vendor extensions are put in another, and each
5217 application program would have a package for its own symbols.
5218 Certain symbols are ``exported'' by a package and others are
5219 internal; certain packages ``use'' or import the exported symbols
5220 of other packages.  To access symbols that would not normally be
5221 visible due to this importing and exporting, Common Lisp provides
5222 a syntax like @code{package:symbol} or @code{package::symbol}.
5224 Emacs Lisp has a single namespace for all interned symbols, and
5225 then uses a naming convention of putting a prefix like @code{cl-}
5226 in front of the name.  Some Emacs packages adopt the Common Lisp-like
5227 convention of using @code{cl:} or @code{cl::} as the prefix.
5228 However, the Emacs parser does not understand colons and just
5229 treats them as part of the symbol name.  Thus, while @code{mapcar}
5230 and @code{lisp:mapcar} may refer to the same symbol in Common
5231 Lisp, they are totally distinct in Emacs Lisp.  Common Lisp
5232 programs which refer to a symbol by the full name sometimes
5233 and the short name other times will not port cleanly to Emacs.
5235 Emacs Lisp does have a concept of ``obarrays,'' which are
5236 package-like collections of symbols, but this feature is not
5237 strong enough to be used as a true package mechanism.
5239 @item
5240 The @code{format} function is quite different between Common
5241 Lisp and Emacs Lisp.  It takes an additional ``destination''
5242 argument before the format string.  A destination of @code{nil}
5243 means to format to a string as in Emacs Lisp; a destination
5244 of @code{t} means to write to the terminal (similar to
5245 @code{message} in Emacs).  Also, format control strings are
5246 utterly different; @code{~} is used instead of @code{%} to
5247 introduce format codes, and the set of available codes is
5248 much richer.  There are no notations like @code{\n} for
5249 string literals; instead, @code{format} is used with the
5250 ``newline'' format code, @code{~%}.  More advanced formatting
5251 codes provide such features as paragraph filling, case
5252 conversion, and even loops and conditionals.
5254 While it would have been possible to implement most of Common
5255 Lisp @code{format} in this package (under the name @code{format*},
5256 of course), it was not deemed worthwhile.  It would have required
5257 a huge amount of code to implement even a decent subset of
5258 @code{format*}, yet the functionality it would provide over
5259 Emacs Lisp's @code{format} would rarely be useful.
5261 @item
5262 Vector constants use square brackets in Emacs Lisp, but
5263 @code{#(a b c)} notation in Common Lisp.  To further complicate
5264 matters, Emacs has its own @code{#(} notation for
5265 something entirely different---strings with properties.
5267 @item
5268 Characters are distinct from integers in Common Lisp.  The notation
5269 for character constants is also different: @code{#\A} in Common Lisp
5270 where Emacs Lisp uses @code{?A}.  Also, @code{string=} and
5271 @code{string-equal} are synonyms in Emacs Lisp, whereas the latter is
5272 case-insensitive in Common Lisp.
5274 @item
5275 Data types.  Some Common Lisp data types do not exist in Emacs
5276 Lisp.  Rational numbers and complex numbers are not present,
5277 nor are large integers (all integers are ``fixnums'').  All
5278 arrays are one-dimensional.  There are no readtables or pathnames;
5279 streams are a set of existing data types rather than a new data
5280 type of their own.  Hash tables, random-states, structures, and
5281 packages (obarrays) are built from Lisp vectors or lists rather
5282 than being distinct types.
5284 @item
5285 The Common Lisp Object System (CLOS) is not implemented,
5286 nor is the Common Lisp Condition System.  However, the EIEIO package
5287 (@pxref{Top, , Introduction, eieio, EIEIO}) does implement some
5288 CLOS functionality.
5290 @item
5291 Common Lisp features that are completely redundant with Emacs
5292 Lisp features of a different name generally have not been
5293 implemented.  For example, Common Lisp writes @code{defconstant}
5294 where Emacs Lisp uses @code{defconst}.  Similarly, @code{make-list}
5295 takes its arguments in different ways in the two Lisps but does
5296 exactly the same thing, so this package has not bothered to
5297 implement a Common Lisp-style @code{make-list}.
5299 @item
5300 A few more notable Common Lisp features not included in this
5301 package:  @code{compiler-let}, @code{tagbody}, @code{prog},
5302 @code{ldb/dpb}, @code{parse-integer}, @code{cerror}.
5304 @item
5305 Recursion.  While recursion works in Emacs Lisp just like it
5306 does in Common Lisp, various details of the Emacs Lisp system
5307 and compiler make recursion much less efficient than it is in
5308 most Lisps.  Some schools of thought prefer to use recursion
5309 in Lisp over other techniques; they would sum a list of
5310 numbers using something like
5312 @example
5313 (defun sum-list (list)
5314   (if list
5315       (+ (car list) (sum-list (cdr list)))
5316     0))
5317 @end example
5319 @noindent
5320 where a more iteratively-minded programmer might write one of
5321 these forms:
5323 @example
5324 (let ((total 0)) (dolist (x my-list) (incf total x)) total)
5325 (loop for x in my-list sum x)
5326 @end example
5328 While this would be mainly a stylistic choice in most Common Lisps,
5329 in Emacs Lisp you should be aware that the iterative forms are
5330 much faster than recursion.  Also, Lisp programmers will want to
5331 note that the current Emacs Lisp compiler does not optimize tail
5332 recursion.
5333 @end itemize
5335 @node GNU Free Documentation License, Function Index, Porting Common Lisp, Top
5336 @appendix GNU Free Documentation License
5337 @include doclicense.texi
5339 @node Function Index, Variable Index, GNU Free Documentation License, Top
5340 @unnumbered Function Index
5342 @printindex fn
5344 @node Variable Index,  , Function Index, Top
5345 @unnumbered Variable Index
5347 @printindex vr
5349 @bye
5351 @ignore
5352    arch-tag: b61e7200-3bfa-4a70-a9d3-095e152696f8
5353 @end ignore