comparison man/cl.texi @ 0:376386a54a3c r19-14

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