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