1 \input texinfo @c -*-texinfo-*-
2 @setfilename ../info/cl.info
3 @settitle Common Lisp Extensions
10 @dircategory XEmacs Editor
12 * Common Lisp: (cl). GNU Emacs Common Lisp emulation package.
15 This file documents the GNU Emacs Common Lisp emulation package.
17 Copyright (C) 1993 Free Software Foundation, Inc.
19 Permission is granted to make and distribute verbatim copies of this
20 manual provided the copyright notice and this permission notice are
21 preserved on all copies.
24 Permission is granted to process this file through TeX and print the
25 results, provided the printed document carries copying permission notice
26 identical to this one except for the removal of this paragraph (this
27 paragraph not being relevant to the printed manual).
30 Permission is granted to copy and distribute modified versions of this
31 manual under the conditions for verbatim copying, provided also that the
32 section entitled ``GNU General Public License'' is included exactly as
33 in the original, and provided that the entire resulting derived work is
34 distributed under the terms of a permission notice identical to this one.
36 Permission is granted to copy and distribute translations of this manual
37 into another language, under the above conditions for modified versions,
38 except that the section entitled ``GNU General Public License'' may be
39 included in a translation approved by the author instead of in the
45 @center @titlefont{Common Lisp Extensions}
47 @center For GNU Emacs Lisp
51 @center Dave Gillespie
52 @center daveg@@synaptics.com
55 @vskip 0pt plus 1filll
56 Copyright @copyright{} 1993 Free Software Foundation, Inc.
58 Permission is granted to make and distribute verbatim copies of
59 this manual provided the copyright notice and this permission notice
60 are preserved on all copies.
63 Permission is granted to process this file through TeX and print the
64 results, provided the printed document carries copying permission notice
65 identical to this one except for the removal of this paragraph (this
66 paragraph not being relevant to the printed manual).
69 Permission is granted to copy and distribute modified versions of this
70 manual under the conditions for verbatim copying, provided also that the
71 section entitled ``GNU General Public License'' is included exactly as
72 in the original, and provided that the entire resulting derived work is
73 distributed under the terms of a permission notice identical to this one.
75 Permission is granted to copy and distribute translations of this manual
76 into another language, under the above conditions for modified versions,
77 except that the section entitled ``GNU General Public License'' may be
78 included in a translation approved by the author instead of in the
82 @node Top, Overview,, (dir)
83 @chapter Common Lisp Extensions
86 This document describes a set of Emacs Lisp facilities borrowed from
87 Common Lisp. All the facilities are described here in detail; for
88 more discussion and examples, Guy L. Steele's @cite{Common Lisp, the
89 Language}, second edition, is the definitive book on Common Lisp.
91 Chapter numbers and most section numbers of this document parallel
92 those of Steele's book.
94 While this document does not assume any prior knowledge of Common
95 Lisp, it does assume a basic familiarity with Emacs Lisp.
98 * Overview:: Installation, usage, etc.
99 * Program Structure:: Arglists, `eval-when', `defalias'
100 * Predicates:: `typep', `eql', and `equalp'
101 * Control Structure:: `setf', `when', `do', `loop', etc.
102 * Macros:: Destructuring, `define-compiler-macro'
103 * Declarations:: `proclaim', `declare', etc.
104 * Symbols:: Property lists, `gensym'
105 * Numbers:: Predicates, functions, random numbers
106 * Sequences:: Mapping, functions, searching, sorting
107 * Lists:: `cadr', `sublis', `member*', `assoc*', etc.
108 * Hash Tables:: `make-hash-table', `gethash', etc.
109 * Structures:: `defstruct'
110 * Assertions:: `check-type', `assert', `ignore-errors'.
112 * Efficiency Concerns:: Hints and techniques
113 * Common Lisp Compatibility:: All known differences with Steele
114 * Old CL Compatibility:: All known differences with old cl.el
115 * Porting Common Lisp:: Hints for porting Common Lisp code
121 @node Overview, Program Structure, Top, Top
130 Common Lisp is a huge language, and Common Lisp systems tend to be
131 massive and extremely complex. Emacs Lisp, by contrast, is rather
132 minimalist in the choice of Lisp features it offers the programmer.
133 As Emacs Lisp programmers have grown in number, and the applications
134 they write have grown more ambitious, it has become clear that Emacs
135 Lisp could benefit from many of the conveniences of Common Lisp.
137 The @dfn{CL} package adds a number of Common Lisp functions and
138 control structures to Emacs Lisp. While not a 100% complete
139 implementation of Common Lisp, @dfn{CL} adds enough functionality
140 to make Emacs Lisp programming significantly more convenient.
142 Some Common Lisp features have been omitted from this package
147 Some features are too complex or bulky relative to their benefit
148 to Emacs Lisp programmers. CLOS and Common Lisp streams are fine
149 examples of this group.
152 Other features cannot be implemented without modification to the
153 Emacs Lisp interpreter itself, such as multiple return values,
154 lexical scoping, case-insensitive symbols, and complex numbers.
155 The @dfn{CL} package generally makes no attempt to emulate these
159 Some features conflict with existing things in Emacs Lisp. For
160 example, Emacs' @code{assoc} function is incompatible with the
161 Common Lisp @code{assoc}. In such cases, this package usually
162 adds the suffix @samp{*} to the function name of the Common
163 Lisp version of the function (e.g., @code{assoc*}).
166 The package described here was written by Dave Gillespie,
167 @file{daveg@@synaptics.com}. It is a total rewrite of the original
168 1986 @file{cl.el} package by Cesar Quiroz. Most features of
169 the Quiroz package have been retained; any incompatibilities are
170 noted in the descriptions below. Care has been taken in this
171 version to ensure that each function is defined efficiently,
172 concisely, and with minimal impact on the rest of the Emacs
176 * Usage:: How to use the CL package
177 * Organization:: The package's five component files
178 * Installation:: Compiling and installing CL
179 * Naming Conventions:: Notes on CL function names
182 @node Usage, Organization, Overview, Overview
186 Lisp code that uses features from the @dfn{CL} package should
187 include at the beginning:
194 If you want to ensure that the new (Gillespie) version of @dfn{CL}
195 is the one that is present, add an additional @code{(require 'cl-19)}
204 The second call will fail (with ``@file{cl-19.el} not found'') if
205 the old @file{cl.el} package was in use.
207 It is safe to arrange to load @dfn{CL} at all times, e.g.,
208 in your @file{.emacs} file. But it's a good idea, for portability,
209 to @code{(require 'cl)} in your code even if you do this.
211 @node Organization, Installation, Usage, Overview
212 @section Organization
215 The Common Lisp package is organized into four files:
219 This is the ``main'' file, which contains basic functions
220 and information about the package. This file is relatively
221 compact---about 700 lines.
224 This file contains the larger, more complex or unusual functions.
225 It is kept separate so that packages which only want to use Common
226 Lisp fundamentals like the @code{cadr} function won't need to pay
227 the overhead of loading the more advanced functions.
230 This file contains most of the advanced functions for operating
231 on sequences or lists, such as @code{delete-if} and @code{assoc*}.
234 This file contains the features of the packages which are macros
235 instead of functions. Macros expand when the caller is compiled,
236 not when it is run, so the macros generally only need to be
237 present when the byte-compiler is running (or when the macros are
238 used in uncompiled code such as a @file{.emacs} file). Most of
239 the macros of this package are isolated in @file{cl-macs.el} so
240 that they won't take up memory unless you are compiling.
243 The file @file{cl.el} includes all necessary @code{autoload}
244 commands for the functions and macros in the other three files.
245 All you have to do is @code{(require 'cl)}, and @file{cl.el}
246 will take care of pulling in the other files when they are
249 There is another file, @file{cl-compat.el}, which defines some
250 routines from the older @file{cl.el} package that are no longer
251 present in the new package. This includes internal routines
252 like @code{setelt} and @code{zip-lists}, deprecated features
253 like @code{defkeyword}, and an emulation of the old-style
254 multiple-values feature. @xref{Old CL Compatibility}.
256 @node Installation, Naming Conventions, Organization, Overview
257 @section Installation
260 Installation of the @dfn{CL} package is simple: Just put the
261 byte-compiled files @file{cl.elc}, @file{cl-extra.elc},
262 @file{cl-seq.elc}, @file{cl-macs.elc}, and @file{cl-compat.elc}
263 into a directory on your @code{load-path}.
265 There are no special requirements to compile this package:
266 The files do not have to be loaded before they are compiled,
267 nor do they need to be compiled in any particular order.
269 You may choose to put the files into your main @file{lisp/}
270 directory, replacing the original @file{cl.el} file there. Or,
271 you could put them into a directory that comes before @file{lisp/}
272 on your @code{load-path} so that the old @file{cl.el} is
275 Also, format the @file{cl.texinfo} file and put the resulting
276 Info files in the @file{info/} directory or another suitable place.
278 You may instead wish to leave this package's components all in
279 their own directory, and then add this directory to your
280 @code{load-path} and (Emacs 19 only) @code{Info-directory-list}.
281 Add the directory to the front of the list so the old @dfn{CL}
282 package and its documentation are hidden.
284 @node Naming Conventions, , Installation, Overview
285 @section Naming Conventions
288 Except where noted, all functions defined by this package have the
289 same names and calling conventions as their Common Lisp counterparts.
291 Following is a complete list of functions whose names were changed
292 from Common Lisp, usually to avoid conflicts with Emacs. In each
293 case, a @samp{*} has been appended to the Common Lisp name to obtain
297 defun* defsubst* defmacro* function*
298 member* assoc* rassoc* remove*
299 delete* mapcar* sort* floor*
300 ceiling* truncate* round* mod*
304 Internal function and variable names in the package are prefixed
305 by @code{cl-}. Here is a complete list of functions @emph{not}
306 prefixed by @code{cl-} which were not taken from Common Lisp:
309 member delete remove remq
310 rassoc floatp-safe lexical-let lexical-let*
311 callf callf2 letf letf*
312 defsubst* defalias add-hook eval-when-compile
316 (Most of these are Emacs 19 features provided to Emacs 18 users,
317 or introduced, like @code{remq}, for reasons of symmetry
318 with similar features.)
320 The following simple functions and macros are defined in @file{cl.el};
321 they do not cause other components like @file{cl-extra} to be loaded.
324 eql floatp-safe abs endp
325 evenp oddp plusp minusp
326 last butlast nbutlast caar .. cddddr
327 list* ldiff rest first .. tenth
328 member [1] copy-list subst mapcar* [2]
329 adjoin [3] acons pairlis when
330 unless pop [4] push [4] pushnew [3,4]
331 incf [4] decf [4] proclaim declaim
336 [1] This is the Emacs 19-compatible function, not @code{member*}.
339 [2] Only for one sequence argument or two list arguments.
342 [3] Only if @code{:test} is @code{eq}, @code{equal}, or unspecified,
343 and @code{:key} is not used.
346 [4] Only when @var{place} is a plain variable name.
352 @node Program Structure, Predicates, Overview, Top
353 @chapter Program Structure
356 This section describes features of the @dfn{CL} package which have to
357 do with programs as a whole: advanced argument lists for functions,
358 and the @code{eval-when} construct.
361 * Argument Lists:: `&key', `&aux', `defun*', `defmacro*'.
362 * Time of Evaluation:: The `eval-when' construct.
363 * Function Aliases:: The `defalias' function.
370 @node Argument Lists, Time of Evaluation, Program Structure, Program Structure
371 @section Argument Lists
374 Emacs Lisp's notation for argument lists of functions is a subset of
375 the Common Lisp notation. As well as the familiar @code{&optional}
376 and @code{&rest} markers, Common Lisp allows you to specify default
377 values for optional arguments, and it provides the additional markers
378 @code{&key} and @code{&aux}.
380 Since argument parsing is built-in to Emacs, there is no way for
381 this package to implement Common Lisp argument lists seamlessly.
382 Instead, this package defines alternates for several Lisp forms
383 which you must use if you need Common Lisp argument lists.
385 @defspec defun* name arglist body...
386 This form is identical to the regular @code{defun} form, except
387 that @var{arglist} is allowed to be a full Common Lisp argument
388 list. Also, the function body is enclosed in an implicit block
389 called @var{name}; @pxref{Blocks and Exits}.
392 @defspec defsubst* name arglist body...
393 This is just like @code{defun*}, except that the function that
394 is defined is automatically proclaimed @code{inline}, i.e.,
395 calls to it may be expanded into in-line code by the byte compiler.
396 This is analogous to the @code{defsubst} form in Emacs 19;
397 @code{defsubst*} uses a different method (compiler macros) which
398 works in all version of Emacs, and also generates somewhat more
399 efficient inline expansions. In particular, @code{defsubst*}
400 arranges for the processing of keyword arguments, default values,
401 etc., to be done at compile-time whenever possible.
404 @defspec defmacro* name arglist body...
405 This is identical to the regular @code{defmacro} form,
406 except that @var{arglist} is allowed to be a full Common Lisp
407 argument list. The @code{&environment} keyword is supported as
408 described in Steele. The @code{&whole} keyword is supported only
409 within destructured lists (see below); top-level @code{&whole}
410 cannot be implemented with the current Emacs Lisp interpreter.
411 The macro expander body is enclosed in an implicit block called
415 @defspec function* symbol-or-lambda
416 This is identical to the regular @code{function} form,
417 except that if the argument is a @code{lambda} form then that
418 form may use a full Common Lisp argument list.
421 Also, all forms (such as @code{defsetf} and @code{flet}) defined
422 in this package that include @var{arglist}s in their syntax allow
423 full Common Lisp argument lists.
425 Note that it is @emph{not} necessary to use @code{defun*} in
426 order to have access to most @dfn{CL} features in your function.
427 These features are always present; @code{defun*}'s only
428 difference from @code{defun} is its more flexible argument
429 lists and its implicit block.
431 The full form of a Common Lisp argument list is
435 &optional (@var{var} @var{initform} @var{svar})...
437 &key ((@var{keyword} @var{var}) @var{initform} @var{svar})...
438 &aux (@var{var} @var{initform})...)
441 Each of the five argument list sections is optional. The @var{svar},
442 @var{initform}, and @var{keyword} parts are optional; if they are
443 omitted, then @samp{(@var{var})} may be written simply @samp{@var{var}}.
445 The first section consists of zero or more @dfn{required} arguments.
446 These arguments must always be specified in a call to the function;
447 there is no difference between Emacs Lisp and Common Lisp as far as
448 required arguments are concerned.
450 The second section consists of @dfn{optional} arguments. These
451 arguments may be specified in the function call; if they are not,
452 @var{initform} specifies the default value used for the argument.
453 (No @var{initform} means to use @code{nil} as the default.) The
454 @var{initform} is evaluated with the bindings for the preceding
455 arguments already established; @code{(a &optional (b (1+ a)))}
456 matches one or two arguments, with the second argument defaulting
457 to one plus the first argument. If the @var{svar} is specified,
458 it is an auxiliary variable which is bound to @code{t} if the optional
459 argument was specified, or to @code{nil} if the argument was omitted.
460 If you don't use an @var{svar}, then there will be no way for your
461 function to tell whether it was called with no argument, or with
462 the default value passed explicitly as an argument.
464 The third section consists of a single @dfn{rest} argument. If
465 more arguments were passed to the function than are accounted for
466 by the required and optional arguments, those extra arguments are
467 collected into a list and bound to the ``rest'' argument variable.
468 Common Lisp's @code{&rest} is equivalent to that of Emacs Lisp.
469 Common Lisp accepts @code{&body} as a synonym for @code{&rest} in
470 macro contexts; this package accepts it all the time.
472 The fourth section consists of @dfn{keyword} arguments. These
473 are optional arguments which are specified by name rather than
474 positionally in the argument list. For example,
477 (defun* foo (a &optional b &key c d (e 17)))
481 defines a function which may be called with one, two, or more
482 arguments. The first two arguments are bound to @code{a} and
483 @code{b} in the usual way. The remaining arguments must be
484 pairs of the form @code{:c}, @code{:d}, or @code{:e} followed
485 by the value to be bound to the corresponding argument variable.
486 (Symbols whose names begin with a colon are called @dfn{keywords},
487 and they are self-quoting in the same way as @code{nil} and
490 For example, the call @code{(foo 1 2 :d 3 :c 4)} sets the five
491 arguments to 1, 2, 4, 3, and 17, respectively. If the same keyword
492 appears more than once in the function call, the first occurrence
493 takes precedence over the later ones. Note that it is not possible
494 to specify keyword arguments without specifying the optional
495 argument @code{b} as well, since @code{(foo 1 :c 2)} would bind
496 @code{b} to the keyword @code{:c}, then signal an error because
497 @code{2} is not a valid keyword.
499 If a @var{keyword} symbol is explicitly specified in the argument
500 list as shown in the above diagram, then that keyword will be
501 used instead of just the variable name prefixed with a colon.
502 You can specify a @var{keyword} symbol which does not begin with
503 a colon at all, but such symbols will not be self-quoting; you
504 will have to quote them explicitly with an apostrophe in the
507 Ordinarily it is an error to pass an unrecognized keyword to
508 a function, e.g., @code{(foo 1 2 :c 3 :goober 4)}. You can ask
509 Lisp to ignore unrecognized keywords, either by adding the
510 marker @code{&allow-other-keys} after the keyword section
511 of the argument list, or by specifying an @code{:allow-other-keys}
512 argument in the call whose value is non-@code{nil}. If the
513 function uses both @code{&rest} and @code{&key} at the same time,
514 the ``rest'' argument is bound to the keyword list as it appears
515 in the call. For example:
518 (defun* find-thing (thing &rest rest &key need &allow-other-keys)
519 (or (apply 'member* thing thing-list :allow-other-keys t rest)
520 (if need (error "Thing not found"))))
524 This function takes a @code{:need} keyword argument, but also
525 accepts other keyword arguments which are passed on to the
526 @code{member*} function. @code{allow-other-keys} is used to
527 keep both @code{find-thing} and @code{member*} from complaining
528 about each others' keywords in the arguments.
530 As a (significant) performance optimization, this package
531 implements the scan for keyword arguments by calling @code{memq}
532 to search for keywords in a ``rest'' argument. Technically
533 speaking, this is incorrect, since @code{memq} looks at the
534 odd-numbered values as well as the even-numbered keywords.
535 The net effect is that if you happen to pass a keyword symbol
536 as the @emph{value} of another keyword argument, where that
537 keyword symbol happens to equal the name of a valid keyword
538 argument of the same function, then the keyword parser will
539 become confused. This minor bug can only affect you if you
540 use keyword symbols as general-purpose data in your program;
541 this practice is strongly discouraged in Emacs Lisp.
543 The fifth section of the argument list consists of @dfn{auxiliary
544 variables}. These are not really arguments at all, but simply
545 variables which are bound to @code{nil} or to the specified
546 @var{initforms} during execution of the function. There is no
547 difference between the following two functions, except for a
548 matter of stylistic taste:
551 (defun* foo (a b &aux (c (+ a b)) d)
559 Argument lists support @dfn{destructuring}. In Common Lisp,
560 destructuring is only allowed with @code{defmacro}; this package
561 allows it with @code{defun*} and other argument lists as well.
562 In destructuring, any argument variable (@var{var} in the above
563 diagram) can be replaced by a list of variables, or more generally,
564 a recursive argument list. The corresponding argument value must
565 be a list whose elements match this recursive argument list.
569 (defmacro* dolist ((var listform &optional resultform)
574 This says that the first argument of @code{dolist} must be a list
575 of two or three items; if there are other arguments as well as this
576 list, they are stored in @code{body}. All features allowed in
577 regular argument lists are allowed in these recursive argument lists.
578 In addition, the clause @samp{&whole @var{var}} is allowed at the
579 front of a recursive argument list. It binds @var{var} to the
580 whole list being matched; thus @code{(&whole all a b)} matches
581 a list of two things, with @code{a} bound to the first thing,
582 @code{b} bound to the second thing, and @code{all} bound to the
583 list itself. (Common Lisp allows @code{&whole} in top-level
584 @code{defmacro} argument lists as well, but Emacs Lisp does not
587 One last feature of destructuring is that the argument list may be
588 dotted, so that the argument list @code{(a b . c)} is functionally
589 equivalent to @code{(a b &rest c)}.
591 If the optimization quality @code{safety} is set to 0
592 (@pxref{Declarations}), error checking for wrong number of
593 arguments and invalid keyword arguments is disabled. By default,
594 argument lists are rigorously checked.
596 @node Time of Evaluation, Function Aliases, Argument Lists, Program Structure
597 @section Time of Evaluation
600 Normally, the byte-compiler does not actually execute the forms in
601 a file it compiles. For example, if a file contains @code{(setq foo t)},
602 the act of compiling it will not actually set @code{foo} to @code{t}.
603 This is true even if the @code{setq} was a top-level form (i.e., not
604 enclosed in a @code{defun} or other form). Sometimes, though, you
605 would like to have certain top-level forms evaluated at compile-time.
606 For example, the compiler effectively evaluates @code{defmacro} forms
607 at compile-time so that later parts of the file can refer to the
608 macros that are defined.
610 @defspec eval-when (situations...) forms...
611 This form controls when the body @var{forms} are evaluated.
612 The @var{situations} list may contain any set of the symbols
613 @code{compile}, @code{load}, and @code{eval} (or their long-winded
614 ANSI equivalents, @code{:compile-toplevel}, @code{:load-toplevel},
615 and @code{:execute}).
617 The @code{eval-when} form is handled differently depending on
618 whether or not it is being compiled as a top-level form.
619 Specifically, it gets special treatment if it is being compiled
620 by a command such as @code{byte-compile-file} which compiles files
621 or buffers of code, and it appears either literally at the
622 top level of the file or inside a top-level @code{progn}.
624 For compiled top-level @code{eval-when}s, the body @var{forms} are
625 executed at compile-time if @code{compile} is in the @var{situations}
626 list, and the @var{forms} are written out to the file (to be executed
627 at load-time) if @code{load} is in the @var{situations} list.
629 For non-compiled-top-level forms, only the @code{eval} situation is
630 relevant. (This includes forms executed by the interpreter, forms
631 compiled with @code{byte-compile} rather than @code{byte-compile-file},
632 and non-top-level forms.) The @code{eval-when} acts like a
633 @code{progn} if @code{eval} is specified, and like @code{nil}
634 (ignoring the body @var{forms}) if not.
636 The rules become more subtle when @code{eval-when}s are nested;
637 consult Steele (second edition) for the gruesome details (and
638 some gruesome examples).
640 Some simple examples:
643 ;; Top-level forms in foo.el:
644 (eval-when (compile) (setq foo1 'bar))
645 (eval-when (load) (setq foo2 'bar))
646 (eval-when (compile load) (setq foo3 'bar))
647 (eval-when (eval) (setq foo4 'bar))
648 (eval-when (eval compile) (setq foo5 'bar))
649 (eval-when (eval load) (setq foo6 'bar))
650 (eval-when (eval compile load) (setq foo7 'bar))
653 When @file{foo.el} is compiled, these variables will be set during
654 the compilation itself:
657 foo1 foo3 foo5 foo7 ; `compile'
660 When @file{foo.elc} is loaded, these variables will be set:
663 foo2 foo3 foo6 foo7 ; `load'
666 And if @file{foo.el} is loaded uncompiled, these variables will
670 foo4 foo5 foo6 foo7 ; `eval'
673 If these seven @code{eval-when}s had been, say, inside a @code{defun},
674 then the first three would have been equivalent to @code{nil} and the
675 last four would have been equivalent to the corresponding @code{setq}s.
677 Note that @code{(eval-when (load eval) @dots{})} is equivalent
678 to @code{(progn @dots{})} in all contexts. The compiler treats
679 certain top-level forms, like @code{defmacro} (sort-of) and
680 @code{require}, as if they were wrapped in @code{(eval-when
681 (compile load eval) @dots{})}.
684 Emacs 19 includes two special forms related to @code{eval-when}.
685 One of these, @code{eval-when-compile}, is not quite equivalent to
686 any @code{eval-when} construct and is described below. This package
687 defines a version of @code{eval-when-compile} for the benefit of
690 The other form, @code{(eval-and-compile @dots{})}, is exactly
691 equivalent to @samp{(eval-when (compile load eval) @dots{})} and
692 so is not itself defined by this package.
694 @defspec eval-when-compile forms...
695 The @var{forms} are evaluated at compile-time; at execution time,
696 this form acts like a quoted constant of the resulting value. Used
697 at top-level, @code{eval-when-compile} is just like @samp{eval-when
698 (compile eval)}. In other contexts, @code{eval-when-compile}
699 allows code to be evaluated once at compile-time for efficiency
702 This form is similar to the @samp{#.} syntax of true Common Lisp.
705 @defspec load-time-value form
706 The @var{form} is evaluated at load-time; at execution time,
707 this form acts like a quoted constant of the resulting value.
709 Early Common Lisp had a @samp{#,} syntax that was similar to
710 this, but ANSI Common Lisp replaced it with @code{load-time-value}
711 and gave it more well-defined semantics.
713 In a compiled file, @code{load-time-value} arranges for @var{form}
714 to be evaluated when the @file{.elc} file is loaded and then used
715 as if it were a quoted constant. In code compiled by
716 @code{byte-compile} rather than @code{byte-compile-file}, the
717 effect is identical to @code{eval-when-compile}. In uncompiled
718 code, both @code{eval-when-compile} and @code{load-time-value}
719 act exactly like @code{progn}.
723 (insert "This function was executed on: "
724 (current-time-string)
726 (eval-when-compile (current-time-string))
727 ;; or '#.(current-time-string) in real Common Lisp
729 (load-time-value (current-time-string))))
733 Byte-compiled, the above defun will result in the following code
734 (or its compiled equivalent, of course) in the @file{.elc} file:
737 (setq --temp-- (current-time-string))
739 (insert "This function was executed on: "
740 (current-time-string)
742 '"Wed Jun 23 18:33:43 1993"
748 @node Function Aliases, , Time of Evaluation, Program Structure
749 @section Function Aliases
752 This section describes a feature from GNU Emacs 19 which this
753 package makes available in other versions of Emacs.
755 @defun defalias symbol function
756 This function sets @var{symbol}'s function cell to @var{function}.
757 It is equivalent to @code{fset}, except that in GNU Emacs 19 it also
758 records the setting in @code{load-history} so that it can be undone
759 by a later @code{unload-feature}.
761 In other versions of Emacs, @code{defalias} is a synonym for
765 @node Predicates, Control Structure, Program Structure, Top
769 This section describes functions for testing whether various
770 facts are true or false.
773 * Type Predicates:: `typep', `deftype', and `coerce'
774 * Equality Predicates:: `eql' and `equalp'
777 @node Type Predicates, Equality Predicates, Predicates, Predicates
778 @section Type Predicates
781 The @dfn{CL} package defines a version of the Common Lisp @code{typep}
784 @defun typep object type
785 Check if @var{object} is of type @var{type}, where @var{type} is a
786 (quoted) type name of the sort used by Common Lisp. For example,
787 @code{(typep foo 'integer)} is equivalent to @code{(integerp foo)}.
790 The @var{type} argument to the above function is either a symbol
791 or a list beginning with a symbol.
795 If the type name is a symbol, Emacs appends @samp{-p} to the
796 symbol name to form the name of a predicate function for testing
797 the type. (Built-in predicates whose names end in @samp{p} rather
798 than @samp{-p} are used when appropriate.)
801 The type symbol @code{t} stands for the union of all types.
802 @code{(typep @var{object} t)} is always true. Likewise, the
803 type symbol @code{nil} stands for nothing at all, and
804 @code{(typep @var{object} nil)} is always false.
807 The type symbol @code{null} represents the symbol @code{nil}.
808 Thus @code{(typep @var{object} 'null)} is equivalent to
809 @code{(null @var{object})}.
812 The type symbol @code{real} is a synonym for @code{number}, and
813 @code{fixnum} is a synonym for @code{integer}.
816 The type symbols @code{character} and @code{string-char} match
817 characters. In Emacs-19 and XEmacs-19, characters are the same thing as
818 integers in the range 0-255. In XEmacs-20, where characters are a
819 first-class data type, this checks for actual characters, and
820 @code{(typep @var{8bit-integer} 'character)} will return @code{nil}.
823 The type symbol @code{float} uses the @code{floatp-safe} predicate
824 defined by this package rather than @code{floatp}, so it will work
825 correctly even in Emacs versions without floating-point support.
828 The type list @code{(integer @var{low} @var{high})} represents all
829 integers between @var{low} and @var{high}, inclusive. Either bound
830 may be a list of a single integer to specify an exclusive limit,
831 or a @code{*} to specify no limit. The type @code{(integer * *)}
832 is thus equivalent to @code{integer}.
835 Likewise, lists beginning with @code{float}, @code{real}, or
836 @code{number} represent numbers of that type falling in a particular
840 Lists beginning with @code{and}, @code{or}, and @code{not} form
841 combinations of types. For example, @code{(or integer (float 0 *))}
842 represents all objects that are integers or non-negative floats.
845 Lists beginning with @code{member} or @code{member*} represent
846 objects @code{eql} to any of the following values. For example,
847 @code{(member 1 2 3 4)} is equivalent to @code{(integer 1 4)},
848 and @code{(member nil)} is equivalent to @code{null}.
851 Lists of the form @code{(satisfies @var{predicate})} represent
852 all objects for which @var{predicate} returns true when called
853 with that object as an argument.
856 The following function and macro (not technically predicates) are
857 related to @code{typep}.
859 @defun coerce object type
860 This function attempts to convert @var{object} to the specified
861 @var{type}. If @var{object} is already of that type as determined by
862 @code{typep}, it is simply returned. Otherwise, certain types of
863 conversions will be made: If @var{type} is any sequence type
864 (@code{string}, @code{list}, etc.) then @var{object} will be
865 converted to that type if possible. If @var{type} is
866 @code{character}, then strings of length one and symbols with
867 one-character names can be coerced. If @var{type} is @code{float},
868 then integers can be coerced in versions of Emacs that support
869 floats. In all other circumstances, @code{coerce} signals an
873 @defspec deftype name arglist forms...
874 This macro defines a new type called @var{name}. It is similar
875 to @code{defmacro} in many ways; when @var{name} is encountered
876 as a type name, the body @var{forms} are evaluated and should
877 return a type specifier that is equivalent to the type. The
878 @var{arglist} is a Common Lisp argument list of the sort accepted
879 by @code{defmacro*}. The type specifier @samp{(@var{name} @var{args}...)}
880 is expanded by calling the expander with those arguments; the type
881 symbol @samp{@var{name}} is expanded by calling the expander with
882 no arguments. The @var{arglist} is processed the same as for
883 @code{defmacro*} except that optional arguments without explicit
884 defaults use @code{*} instead of @code{nil} as the ``default''
885 default. Some examples:
888 (deftype null () '(satisfies null)) ; predefined
889 (deftype list () '(or null cons)) ; predefined
890 (deftype unsigned-byte (&optional bits)
891 (list 'integer 0 (if (eq bits '*) bits (1- (lsh 1 bits)))))
892 (unsigned-byte 8) @equiv{} (integer 0 255)
893 (unsigned-byte) @equiv{} (integer 0 *)
894 unsigned-byte @equiv{} (integer 0 *)
898 The last example shows how the Common Lisp @code{unsigned-byte}
899 type specifier could be implemented if desired; this package does
900 not implement @code{unsigned-byte} by default.
903 The @code{typecase} and @code{check-type} macros also use type
904 names. @xref{Conditionals}. @xref{Assertions}. The @code{map},
905 @code{concatenate}, and @code{merge} functions take type-name
906 arguments to specify the type of sequence to return. @xref{Sequences}.
908 @node Equality Predicates, , Type Predicates, Predicates
909 @section Equality Predicates
912 This package defines two Common Lisp predicates, @code{eql} and
916 This function is almost the same as @code{eq}, except that if @var{a}
917 and @var{b} are numbers of the same type, it compares them for numeric
918 equality (as if by @code{equal} instead of @code{eq}). This makes a
919 difference only for versions of Emacs that are compiled with
920 floating-point support, such as Emacs 19. Emacs floats are allocated
921 objects just like cons cells, which means that @code{(eq 3.0 3.0)}
922 will not necessarily be true---if the two @code{3.0}s were allocated
923 separately, the pointers will be different even though the numbers are
924 the same. But @code{(eql 3.0 3.0)} will always be true.
926 The types of the arguments must match, so @code{(eql 3 3.0)} is
929 Note that Emacs integers are ``direct'' rather than allocated, which
930 basically means @code{(eq 3 3)} will always be true. Thus @code{eq}
931 and @code{eql} behave differently only if floating-point numbers are
932 involved, and are indistinguishable on Emacs versions that don't
935 There is a slight inconsistency with Common Lisp in the treatment of
936 positive and negative zeros. Some machines, notably those with IEEE
937 standard arithmetic, represent @code{+0} and @code{-0} as distinct
938 values. Normally this doesn't matter because the standard specifies
939 that @code{(= 0.0 -0.0)} should always be true, and this is indeed
940 what Emacs Lisp and Common Lisp do. But the Common Lisp standard
941 states that @code{(eql 0.0 -0.0)} and @code{(equal 0.0 -0.0)} should
942 be false on IEEE-like machines; Emacs Lisp does not do this, and in
943 fact the only known way to distinguish between the two zeros in Emacs
944 Lisp is to @code{format} them and check for a minus sign.
948 This function is a more flexible version of @code{equal}. In
949 particular, it compares strings and characters case-insensitively, and
950 it compares numbers without regard to type (so that @code{(equalp 3
951 3.0)} is true). Vectors and conses are compared recursively. All other
952 objects are compared as if by @code{equal}.
954 This function differs from Common Lisp @code{equalp} in several
955 respects. In keeping with the idea that strings are less
956 vector-like in Emacs Lisp, this package's @code{equalp} also will not
957 compare strings against vectors of integers.
960 Also note that the Common Lisp functions @code{member} and @code{assoc}
961 use @code{eql} to compare elements, whereas Emacs Lisp follows the
962 MacLisp tradition and uses @code{equal} for these two functions.
963 In Emacs, use @code{member*} and @code{assoc*} to get functions
964 which use @code{eql} for comparisons.
966 @node Control Structure, Macros, Predicates, Top
967 @chapter Control Structure
970 The features described in the following sections implement
971 various advanced control structures, including the powerful
972 @code{setf} facility and a number of looping and conditional
976 * Assignment:: The `psetq' form
977 * Generalized Variables:: `setf', `incf', `push', etc.
978 * Variable Bindings:: `progv', `lexical-let', `flet', `macrolet'
979 * Conditionals:: `when', `unless', `case', `typecase'
980 * Blocks and Exits:: `block', `return', `return-from'
981 * Iteration:: `do', `dotimes', `dolist', `do-symbols'
982 * Loop Facility:: The Common Lisp `loop' macro
983 * Multiple Values:: `values', `multiple-value-bind', etc.
986 @node Assignment, Generalized Variables, Control Structure, Control Structure
990 The @code{psetq} form is just like @code{setq}, except that multiple
991 assignments are done in parallel rather than sequentially.
993 @defspec psetq [symbol form]@dots{}
994 This special form (actually a macro) is used to assign to several
995 variables simultaneously. Given only one @var{symbol} and @var{form},
996 it has the same effect as @code{setq}. Given several @var{symbol}
997 and @var{form} pairs, it evaluates all the @var{form}s in advance
998 and then stores the corresponding variables afterwards.
1002 (setq x (+ x y) y (* x y))
1005 y ; @r{@code{y} was computed after @code{x} was set.}
1008 (psetq x (+ x y) y (* x y))
1011 y ; @r{@code{y} was computed before @code{x} was set.}
1015 The simplest use of @code{psetq} is @code{(psetq x y y x)}, which
1016 exchanges the values of two variables. (The @code{rotatef} form
1017 provides an even more convenient way to swap two variables;
1018 @pxref{Modify Macros}.)
1020 @code{psetq} always returns @code{nil}.
1023 @node Generalized Variables, Variable Bindings, Assignment, Control Structure
1024 @section Generalized Variables
1027 A ``generalized variable'' or ``place form'' is one of the many places
1028 in Lisp memory where values can be stored. The simplest place form is
1029 a regular Lisp variable. But the cars and cdrs of lists, elements
1030 of arrays, properties of symbols, and many other locations are also
1031 places where Lisp values are stored.
1033 The @code{setf} form is like @code{setq}, except that it accepts
1034 arbitrary place forms on the left side rather than just
1035 symbols. For example, @code{(setf (car a) b)} sets the car of
1036 @code{a} to @code{b}, doing the same operation as @code{(setcar a b)}
1037 but without having to remember two separate functions for setting
1038 and accessing every type of place.
1040 Generalized variables are analogous to ``lvalues'' in the C
1041 language, where @samp{x = a[i]} gets an element from an array
1042 and @samp{a[i] = x} stores an element using the same notation.
1043 Just as certain forms like @code{a[i]} can be lvalues in C, there
1044 is a set of forms that can be generalized variables in Lisp.
1047 * Basic Setf:: `setf' and place forms
1048 * Modify Macros:: `incf', `push', `rotatef', `letf', `callf', etc.
1049 * Customizing Setf:: `define-modify-macro', `defsetf', `define-setf-method'
1052 @node Basic Setf, Modify Macros, Generalized Variables, Generalized Variables
1053 @subsection Basic Setf
1056 The @code{setf} macro is the most basic way to operate on generalized
1059 @defspec setf [place form]@dots{}
1060 This macro evaluates @var{form} and stores it in @var{place}, which
1061 must be a valid generalized variable form. If there are several
1062 @var{place} and @var{form} pairs, the assignments are done sequentially
1063 just as with @code{setq}. @code{setf} returns the value of the last
1066 The following Lisp forms will work as generalized variables, and
1067 so may legally appear in the @var{place} argument of @code{setf}:
1071 A symbol naming a variable. In other words, @code{(setf x y)} is
1072 exactly equivalent to @code{(setq x y)}, and @code{setq} itself is
1073 strictly speaking redundant now that @code{setf} exists. Many
1074 programmers continue to prefer @code{setq} for setting simple
1075 variables, though, purely for stylistic or historical reasons.
1076 The form @code{(setf x y)} actually expands to @code{(setq x y)},
1077 so there is no performance penalty for using it in compiled code.
1080 A call to any of the following Lisp functions:
1083 car cdr caar .. cddddr
1084 nth rest first .. tenth
1086 symbol-function symbol-value symbol-plist
1092 Note that for @code{nthcdr} and @code{getf}, the list argument
1093 of the function must itself be a valid @var{place} form. For
1094 example, @code{(setf (nthcdr 0 foo) 7)} will set @code{foo} itself
1095 to 7. Note that @code{push} and @code{pop} on an @code{nthcdr}
1096 place can be used to insert or delete at any position in a list.
1097 The use of @code{nthcdr} as a @var{place} form is an extension
1098 to standard Common Lisp.
1101 The following Emacs-specific functions are also @code{setf}-able.
1102 (Some of these are defined only in Emacs 19 or only in XEmacs.)
1105 buffer-file-name marker-position
1106 buffer-modified-p match-data
1107 buffer-name mouse-position
1108 buffer-string overlay-end
1109 buffer-substring overlay-get
1110 current-buffer overlay-start
1111 current-case-table point
1112 current-column point-marker
1113 current-global-map point-max
1114 current-input-mode point-min
1115 current-local-map process-buffer
1116 current-window-configuration process-filter
1117 default-file-modes process-sentinel
1118 default-value read-mouse-position
1119 documentation-property screen-height
1120 extent-data screen-menubar
1121 extent-end-position screen-width
1122 extent-start-position selected-window
1123 face-background selected-screen
1124 face-background-pixmap selected-frame
1125 face-font standard-case-table
1126 face-foreground syntax-table
1127 face-underline-p window-buffer
1128 file-modes window-dedicated-p
1129 frame-height window-display-table
1130 frame-parameters window-height
1131 frame-visible-p window-hscroll
1132 frame-width window-point
1133 get-register window-start
1135 global-key-binding x-get-cut-buffer
1136 keymap-parent x-get-cutbuffer
1137 local-key-binding x-get-secondary-selection
1138 mark x-get-selection
1142 Most of these have directly corresponding ``set'' functions, like
1143 @code{use-local-map} for @code{current-local-map}, or @code{goto-char}
1144 for @code{point}. A few, like @code{point-min}, expand to longer
1145 sequences of code when they are @code{setf}'d (@code{(narrow-to-region
1146 x (point-max))} in this case).
1149 A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])},
1150 where @var{subplace} is itself a legal generalized variable whose
1151 current value is a string, and where the value stored is also a
1152 string. The new string is spliced into the specified part of the
1153 destination string. For example:
1156 (setq a (list "hello" "world"))
1157 @result{} ("hello" "world")
1160 (substring (cadr a) 2 4)
1162 (setf (substring (cadr a) 2 4) "o")
1167 @result{} ("hello" "wood")
1170 The generalized variable @code{buffer-substring}, listed above,
1171 also works in this way by replacing a portion of the current buffer.
1174 A call of the form @code{(apply '@var{func} @dots{})} or
1175 @code{(apply (function @var{func}) @dots{})}, where @var{func}
1176 is a @code{setf}-able function whose store function is ``suitable''
1177 in the sense described in Steele's book; since none of the standard
1178 Emacs place functions are suitable in this sense, this feature is
1179 only interesting when used with places you define yourself with
1180 @code{define-setf-method} or the long form of @code{defsetf}.
1183 A macro call, in which case the macro is expanded and @code{setf}
1184 is applied to the resulting form.
1187 Any form for which a @code{defsetf} or @code{define-setf-method}
1191 Using any forms other than these in the @var{place} argument to
1192 @code{setf} will signal an error.
1194 The @code{setf} macro takes care to evaluate all subforms in
1195 the proper left-to-right order; for example,
1198 (setf (aref vec (incf i)) i)
1202 looks like it will evaluate @code{(incf i)} exactly once, before the
1203 following access to @code{i}; the @code{setf} expander will insert
1204 temporary variables as necessary to ensure that it does in fact work
1205 this way no matter what setf-method is defined for @code{aref}.
1206 (In this case, @code{aset} would be used and no such steps would
1207 be necessary since @code{aset} takes its arguments in a convenient
1210 However, if the @var{place} form is a macro which explicitly
1211 evaluates its arguments in an unusual order, this unusual order
1212 will be preserved. Adapting an example from Steele, given
1215 (defmacro wrong-order (x y) (list 'aref y x))
1219 the form @code{(setf (wrong-order @var{a} @var{b}) 17)} will
1220 evaluate @var{b} first, then @var{a}, just as in an actual call
1221 to @code{wrong-order}.
1224 @node Modify Macros, Customizing Setf, Basic Setf, Generalized Variables
1225 @subsection Modify Macros
1228 This package defines a number of other macros besides @code{setf}
1229 that operate on generalized variables. Many are interesting and
1230 useful even when the @var{place} is just a variable name.
1232 @defspec psetf [place form]@dots{}
1233 This macro is to @code{setf} what @code{psetq} is to @code{setq}:
1234 When several @var{place}s and @var{form}s are involved, the
1235 assignments take place in parallel rather than sequentially.
1236 Specifically, all subforms are evaluated from left to right, then
1237 all the assignments are done (in an undefined order).
1240 @defspec incf place &optional x
1241 This macro increments the number stored in @var{place} by one, or
1242 by @var{x} if specified. The incremented value is returned. For
1243 example, @code{(incf i)} is equivalent to @code{(setq i (1+ i))}, and
1244 @code{(incf (car x) 2)} is equivalent to @code{(setcar x (+ (car x) 2))}.
1246 Once again, care is taken to preserve the ``apparent'' order of
1247 evaluation. For example,
1250 (incf (aref vec (incf i)))
1254 appears to increment @code{i} once, then increment the element of
1255 @code{vec} addressed by @code{i}; this is indeed exactly what it
1256 does, which means the above form is @emph{not} equivalent to the
1257 ``obvious'' expansion,
1260 (setf (aref vec (incf i)) (1+ (aref vec (incf i)))) ; Wrong!
1264 but rather to something more like
1267 (let ((temp (incf i)))
1268 (setf (aref vec temp) (1+ (aref vec temp))))
1272 Again, all of this is taken care of automatically by @code{incf} and
1273 the other generalized-variable macros.
1275 As a more Emacs-specific example of @code{incf}, the expression
1276 @code{(incf (point) @var{n})} is essentially equivalent to
1277 @code{(forward-char @var{n})}.
1280 @defspec decf place &optional x
1281 This macro decrements the number stored in @var{place} by one, or
1282 by @var{x} if specified.
1286 This macro removes and returns the first element of the list stored
1287 in @var{place}. It is analogous to @code{(prog1 (car @var{place})
1288 (setf @var{place} (cdr @var{place})))}, except that it takes care
1289 to evaluate all subforms only once.
1292 @defspec push x place
1293 This macro inserts @var{x} at the front of the list stored in
1294 @var{place}. It is analogous to @code{(setf @var{place} (cons
1295 @var{x} @var{place}))}, except for evaluation of the subforms.
1298 @defspec pushnew x place @t{&key :test :test-not :key}
1299 This macro inserts @var{x} at the front of the list stored in
1300 @var{place}, but only if @var{x} was not @code{eql} to any
1301 existing element of the list. The optional keyword arguments
1302 are interpreted in the same way as for @code{adjoin}.
1303 @xref{Lists as Sets}.
1306 @defspec shiftf place@dots{} newvalue
1307 This macro shifts the @var{place}s left by one, shifting in the
1308 value of @var{newvalue} (which may be any Lisp expression, not just
1309 a generalized variable), and returning the value shifted out of
1310 the first @var{place}. Thus, @code{(shiftf @var{a} @var{b} @var{c}
1311 @var{d})} is equivalent to
1316 (psetf @var{a} @var{b}
1322 except that the subforms of @var{a}, @var{b}, and @var{c} are actually
1323 evaluated only once each and in the apparent order.
1326 @defspec rotatef place@dots{}
1327 This macro rotates the @var{place}s left by one in circular fashion.
1328 Thus, @code{(rotatef @var{a} @var{b} @var{c} @var{d})} is equivalent to
1331 (psetf @var{a} @var{b}
1338 except for the evaluation of subforms. @code{rotatef} always
1339 returns @code{nil}. Note that @code{(rotatef @var{a} @var{b})}
1340 conveniently exchanges @var{a} and @var{b}.
1343 The following macros were invented for this package; they have no
1344 analogues in Common Lisp.
1346 @defspec letf (bindings@dots{}) forms@dots{}
1347 This macro is analogous to @code{let}, but for generalized variables
1348 rather than just symbols. Each @var{binding} should be of the form
1349 @code{(@var{place} @var{value})}; the original contents of the
1350 @var{place}s are saved, the @var{value}s are stored in them, and
1351 then the body @var{form}s are executed. Afterwards, the @var{places}
1352 are set back to their original saved contents. This cleanup happens
1353 even if the @var{form}s exit irregularly due to a @code{throw} or an
1359 (letf (((point) (point-min))
1365 moves ``point'' in the current buffer to the beginning of the buffer,
1366 and also binds @code{a} to 17 (as if by a normal @code{let}, since
1367 @code{a} is just a regular variable). After the body exits, @code{a}
1368 is set back to its original value and point is moved back to its
1371 Note that @code{letf} on @code{(point)} is not quite like a
1372 @code{save-excursion}, as the latter effectively saves a marker
1373 which tracks insertions and deletions in the buffer. Actually,
1374 a @code{letf} of @code{(point-marker)} is much closer to this
1375 behavior. (@code{point} and @code{point-marker} are equivalent
1376 as @code{setf} places; each will accept either an integer or a
1377 marker as the stored value.)
1379 Since generalized variables look like lists, @code{let}'s shorthand
1380 of using @samp{foo} for @samp{(foo nil)} as a @var{binding} would
1381 be ambiguous in @code{letf} and is not allowed.
1383 However, a @var{binding} specifier may be a one-element list
1384 @samp{(@var{place})}, which is similar to @samp{(@var{place}
1385 @var{place})}. In other words, the @var{place} is not disturbed
1386 on entry to the body, and the only effect of the @code{letf} is
1387 to restore the original value of @var{place} afterwards. (The
1388 redundant access-and-store suggested by the @code{(@var{place}
1389 @var{place})} example does not actually occur.)
1391 In most cases, the @var{place} must have a well-defined value on
1392 entry to the @code{letf} form. The only exceptions are plain
1393 variables and calls to @code{symbol-value} and @code{symbol-function}.
1394 If the symbol is not bound on entry, it is simply made unbound by
1395 @code{makunbound} or @code{fmakunbound} on exit.
1398 @defspec letf* (bindings@dots{}) forms@dots{}
1399 This macro is to @code{letf} what @code{let*} is to @code{let}:
1400 It does the bindings in sequential rather than parallel order.
1403 @defspec callf @var{function} @var{place} @var{args}@dots{}
1404 This is the ``generic'' modify macro. It calls @var{function},
1405 which should be an unquoted function name, macro name, or lambda.
1406 It passes @var{place} and @var{args} as arguments, and assigns the
1407 result back to @var{place}. For example, @code{(incf @var{place}
1408 @var{n})} is the same as @code{(callf + @var{place} @var{n})}.
1412 (callf abs my-number)
1413 (callf concat (buffer-name) "<" (int-to-string n) ">")
1414 (callf union happy-people (list joe bob) :test 'same-person)
1417 @xref{Customizing Setf}, for @code{define-modify-macro}, a way
1418 to create even more concise notations for modify macros. Note
1419 again that @code{callf} is an extension to standard Common Lisp.
1422 @defspec callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{}
1423 This macro is like @code{callf}, except that @var{place} is
1424 the @emph{second} argument of @var{function} rather than the
1425 first. For example, @code{(push @var{x} @var{place})} is
1426 equivalent to @code{(callf2 cons @var{x} @var{place})}.
1429 The @code{callf} and @code{callf2} macros serve as building
1430 blocks for other macros like @code{incf}, @code{pushnew}, and
1431 @code{define-modify-macro}. The @code{letf} and @code{letf*}
1432 macros are used in the processing of symbol macros;
1433 @pxref{Macro Bindings}.
1435 @node Customizing Setf, , Modify Macros, Generalized Variables
1436 @subsection Customizing Setf
1439 Common Lisp defines three macros, @code{define-modify-macro},
1440 @code{defsetf}, and @code{define-setf-method}, that allow the
1441 user to extend generalized variables in various ways.
1443 @defspec define-modify-macro name arglist function [doc-string]
1444 This macro defines a ``read-modify-write'' macro similar to
1445 @code{incf} and @code{decf}. The macro @var{name} is defined
1446 to take a @var{place} argument followed by additional arguments
1447 described by @var{arglist}. The call
1450 (@var{name} @var{place} @var{args}...)
1457 (callf @var{func} @var{place} @var{args}...)
1461 which in turn is roughly equivalent to
1464 (setf @var{place} (@var{func} @var{place} @var{args}...))
1470 (define-modify-macro incf (&optional (n 1)) +)
1471 (define-modify-macro concatf (&rest args) concat)
1474 Note that @code{&key} is not allowed in @var{arglist}, but
1475 @code{&rest} is sufficient to pass keywords on to the function.
1477 Most of the modify macros defined by Common Lisp do not exactly
1478 follow the pattern of @code{define-modify-macro}. For example,
1479 @code{push} takes its arguments in the wrong order, and @code{pop}
1480 is completely irregular. You can define these macros ``by hand''
1481 using @code{get-setf-method}, or consult the source file
1482 @file{cl-macs.el} to see how to use the internal @code{setf}
1486 @defspec defsetf access-fn update-fn
1487 This is the simpler of two @code{defsetf} forms. Where
1488 @var{access-fn} is the name of a function which accesses a place,
1489 this declares @var{update-fn} to be the corresponding store
1490 function. From now on,
1493 (setf (@var{access-fn} @var{arg1} @var{arg2} @var{arg3}) @var{value})
1500 (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} @var{value})
1504 The @var{update-fn} is required to be either a true function, or
1505 a macro which evaluates its arguments in a function-like way. Also,
1506 the @var{update-fn} is expected to return @var{value} as its result.
1507 Otherwise, the above expansion would not obey the rules for the way
1508 @code{setf} is supposed to behave.
1510 As a special (non-Common-Lisp) extension, a third argument of @code{t}
1511 to @code{defsetf} says that the @code{update-fn}'s return value is
1512 not suitable, so that the above @code{setf} should be expanded to
1516 (let ((temp @var{value}))
1517 (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} temp)
1521 Some examples of the use of @code{defsetf}, drawn from the standard
1522 suite of setf methods, are:
1525 (defsetf car setcar)
1526 (defsetf symbol-value set)
1527 (defsetf buffer-name rename-buffer t)
1531 @defspec defsetf access-fn arglist (store-var) forms@dots{}
1532 This is the second, more complex, form of @code{defsetf}. It is
1533 rather like @code{defmacro} except for the additional @var{store-var}
1534 argument. The @var{forms} should return a Lisp form which stores
1535 the value of @var{store-var} into the generalized variable formed
1536 by a call to @var{access-fn} with arguments described by @var{arglist}.
1537 The @var{forms} may begin with a string which documents the @code{setf}
1538 method (analogous to the doc string that appears at the front of a
1541 For example, the simple form of @code{defsetf} is shorthand for
1544 (defsetf @var{access-fn} (&rest args) (store)
1545 (append '(@var{update-fn}) args (list store)))
1548 The Lisp form that is returned can access the arguments from
1549 @var{arglist} and @var{store-var} in an unrestricted fashion;
1550 macros like @code{setf} and @code{incf} which invoke this
1551 setf-method will insert temporary variables as needed to make
1552 sure the apparent order of evaluation is preserved.
1554 Another example drawn from the standard package:
1557 (defsetf nth (n x) (store)
1558 (list 'setcar (list 'nthcdr n x) store))
1562 @defspec define-setf-method access-fn arglist forms@dots{}
1563 This is the most general way to create new place forms. When
1564 a @code{setf} to @var{access-fn} with arguments described by
1565 @var{arglist} is expanded, the @var{forms} are evaluated and
1566 must return a list of five items:
1570 A list of @dfn{temporary variables}.
1573 A list of @dfn{value forms} corresponding to the temporary variables
1574 above. The temporary variables will be bound to these value forms
1575 as the first step of any operation on the generalized variable.
1578 A list of exactly one @dfn{store variable} (generally obtained
1579 from a call to @code{gensym}).
1582 A Lisp form which stores the contents of the store variable into
1583 the generalized variable, assuming the temporaries have been
1584 bound as described above.
1587 A Lisp form which accesses the contents of the generalized variable,
1588 assuming the temporaries have been bound.
1591 This is exactly like the Common Lisp macro of the same name,
1592 except that the method returns a list of five values rather
1593 than the five values themselves, since Emacs Lisp does not
1594 support Common Lisp's notion of multiple return values.
1596 Once again, the @var{forms} may begin with a documentation string.
1598 A setf-method should be maximally conservative with regard to
1599 temporary variables. In the setf-methods generated by
1600 @code{defsetf}, the second return value is simply the list of
1601 arguments in the place form, and the first return value is a
1602 list of a corresponding number of temporary variables generated
1603 by @code{gensym}. Macros like @code{setf} and @code{incf} which
1604 use this setf-method will optimize away most temporaries that
1605 turn out to be unnecessary, so there is little reason for the
1606 setf-method itself to optimize.
1609 @defun get-setf-method place &optional env
1610 This function returns the setf-method for @var{place}, by
1611 invoking the definition previously recorded by @code{defsetf}
1612 or @code{define-setf-method}. The result is a list of five
1613 values as described above. You can use this function to build
1614 your own @code{incf}-like modify macros. (Actually, it is
1615 better to use the internal functions @code{cl-setf-do-modify}
1616 and @code{cl-setf-do-store}, which are a bit easier to use and
1617 which also do a number of optimizations; consult the source
1618 code for the @code{incf} function for a simple example.)
1620 The argument @var{env} specifies the ``environment'' to be
1621 passed on to @code{macroexpand} if @code{get-setf-method} should
1622 need to expand a macro in @var{place}. It should come from
1623 an @code{&environment} argument to the macro or setf-method
1624 that called @code{get-setf-method}.
1626 See also the source code for the setf-methods for @code{apply}
1627 and @code{substring}, each of which works by calling
1628 @code{get-setf-method} on a simpler case, then massaging
1629 the result in various ways.
1632 Modern Common Lisp defines a second, independent way to specify
1633 the @code{setf} behavior of a function, namely ``@code{setf}
1634 functions'' whose names are lists @code{(setf @var{name})}
1635 rather than symbols. For example, @code{(defun (setf foo) @dots{})}
1636 defines the function that is used when @code{setf} is applied to
1637 @code{foo}. This package does not currently support @code{setf}
1638 functions. In particular, it is a compile-time error to use
1639 @code{setf} on a form which has not already been @code{defsetf}'d
1640 or otherwise declared; in newer Common Lisps, this would not be
1641 an error since the function @code{(setf @var{func})} might be
1648 @node Variable Bindings, Conditionals, Generalized Variables, Control Structure
1649 @section Variable Bindings
1652 These Lisp forms make bindings to variables and function names,
1653 analogous to Lisp's built-in @code{let} form.
1655 @xref{Modify Macros}, for the @code{letf} and @code{letf*} forms which
1656 are also related to variable bindings.
1659 * Dynamic Bindings:: The `progv' form
1660 * Lexical Bindings:: `lexical-let' and lexical closures
1661 * Function Bindings:: `flet' and `labels'
1662 * Macro Bindings:: `macrolet' and `symbol-macrolet'
1665 @node Dynamic Bindings, Lexical Bindings, Variable Bindings, Variable Bindings
1666 @subsection Dynamic Bindings
1669 The standard @code{let} form binds variables whose names are known
1670 at compile-time. The @code{progv} form provides an easy way to
1671 bind variables whose names are computed at run-time.
1673 @defspec progv symbols values forms@dots{}
1674 This form establishes @code{let}-style variable bindings on a
1675 set of variables computed at run-time. The expressions
1676 @var{symbols} and @var{values} are evaluated, and must return lists
1677 of symbols and values, respectively. The symbols are bound to the
1678 corresponding values for the duration of the body @var{form}s.
1679 If @var{values} is shorter than @var{symbols}, the last few symbols
1680 are made unbound (as if by @code{makunbound}) inside the body.
1681 If @var{symbols} is shorter than @var{values}, the excess values
1685 @node Lexical Bindings, Function Bindings, Dynamic Bindings, Variable Bindings
1686 @subsection Lexical Bindings
1689 The @dfn{CL} package defines the following macro which
1690 more closely follows the Common Lisp @code{let} form:
1692 @defspec lexical-let (bindings@dots{}) forms@dots{}
1693 This form is exactly like @code{let} except that the bindings it
1694 establishes are purely lexical. Lexical bindings are similar to
1695 local variables in a language like C: Only the code physically
1696 within the body of the @code{lexical-let} (after macro expansion)
1697 may refer to the bound variables.
1701 (defun foo (b) (+ a b))
1702 (let ((a 2)) (foo a))
1704 (lexical-let ((a 2)) (foo a))
1709 In this example, a regular @code{let} binding of @code{a} actually
1710 makes a temporary change to the global variable @code{a}, so @code{foo}
1711 is able to see the binding of @code{a} to 2. But @code{lexical-let}
1712 actually creates a distinct local variable @code{a} for use within its
1713 body, without any effect on the global variable of the same name.
1715 The most important use of lexical bindings is to create @dfn{closures}.
1716 A closure is a function object that refers to an outside lexical
1717 variable. For example:
1720 (defun make-adder (n)
1721 (lexical-let ((n n))
1722 (function (lambda (m) (+ n m)))))
1723 (setq add17 (make-adder 17))
1729 The call @code{(make-adder 17)} returns a function object which adds
1730 17 to its argument. If @code{let} had been used instead of
1731 @code{lexical-let}, the function object would have referred to the
1732 global @code{n}, which would have been bound to 17 only during the
1733 call to @code{make-adder} itself.
1736 (defun make-counter ()
1737 (lexical-let ((n 0))
1738 (function* (lambda (&optional (m 1)) (incf n m)))))
1739 (setq count-1 (make-counter))
1742 (funcall count-1 14)
1744 (setq count-2 (make-counter))
1754 Here we see that each call to @code{make-counter} creates a distinct
1755 local variable @code{n}, which serves as a private counter for the
1756 function object that is returned.
1758 Closed-over lexical variables persist until the last reference to
1759 them goes away, just like all other Lisp objects. For example,
1760 @code{count-2} refers to a function object which refers to an
1761 instance of the variable @code{n}; this is the only reference
1762 to that variable, so after @code{(setq count-2 nil)} the garbage
1763 collector would be able to delete this instance of @code{n}.
1764 Of course, if a @code{lexical-let} does not actually create any
1765 closures, then the lexical variables are free as soon as the
1766 @code{lexical-let} returns.
1768 Many closures are used only during the extent of the bindings they
1769 refer to; these are known as ``downward funargs'' in Lisp parlance.
1770 When a closure is used in this way, regular Emacs Lisp dynamic
1771 bindings suffice and will be more efficient than @code{lexical-let}
1775 (defun add-to-list (x list)
1776 (mapcar (function (lambda (y) (+ x y))) list))
1777 (add-to-list 7 '(1 2 5))
1782 Since this lambda is only used while @code{x} is still bound,
1783 it is not necessary to make a true closure out of it.
1785 You can use @code{defun} or @code{flet} inside a @code{lexical-let}
1786 to create a named closure. If several closures are created in the
1787 body of a single @code{lexical-let}, they all close over the same
1788 instance of the lexical variable.
1790 The @code{lexical-let} form is an extension to Common Lisp. In
1791 true Common Lisp, all bindings are lexical unless declared otherwise.
1794 @defspec lexical-let* (bindings@dots{}) forms@dots{}
1795 This form is just like @code{lexical-let}, except that the bindings
1796 are made sequentially in the manner of @code{let*}.
1799 @node Function Bindings, Macro Bindings, Lexical Bindings, Variable Bindings
1800 @subsection Function Bindings
1803 These forms make @code{let}-like bindings to functions instead
1806 @defspec flet (bindings@dots{}) forms@dots{}
1807 This form establishes @code{let}-style bindings on the function
1808 cells of symbols rather than on the value cells. Each @var{binding}
1809 must be a list of the form @samp{(@var{name} @var{arglist}
1810 @var{forms}@dots{})}, which defines a function exactly as if
1811 it were a @code{defun*} form. The function @var{name} is defined
1812 accordingly for the duration of the body of the @code{flet}; then
1813 the old function definition, or lack thereof, is restored.
1815 While @code{flet} in Common Lisp establishes a lexical binding of
1816 @var{name}, Emacs Lisp @code{flet} makes a dynamic binding. The
1817 result is that @code{flet} affects indirect calls to a function as
1818 well as calls directly inside the @code{flet} form itself.
1820 You can use @code{flet} to disable or modify the behavior of a
1821 function in a temporary fashion. This will even work on Emacs
1822 primitives, although note that some calls to primitive functions
1823 internal to Emacs are made without going through the symbol's
1824 function cell, and so will not be affected by @code{flet}. For
1828 (flet ((message (&rest args) (push args saved-msgs)))
1832 This code attempts to replace the built-in function @code{message}
1833 with a function that simply saves the messages in a list rather
1834 than displaying them. The original definition of @code{message}
1835 will be restored after @code{do-something} exits. This code will
1836 work fine on messages generated by other Lisp code, but messages
1837 generated directly inside Emacs will not be caught since they make
1838 direct C-language calls to the message routines rather than going
1839 through the Lisp @code{message} function.
1841 Functions defined by @code{flet} may use the full Common Lisp
1842 argument notation supported by @code{defun*}; also, the function
1843 body is enclosed in an implicit block as if by @code{defun*}.
1844 @xref{Program Structure}.
1847 @defspec labels (bindings@dots{}) forms@dots{}
1848 The @code{labels} form is a synonym for @code{flet}. (In Common
1849 Lisp, @code{labels} and @code{flet} differ in ways that depend on
1850 their lexical scoping; these distinctions vanish in dynamically
1854 @node Macro Bindings, , Function Bindings, Variable Bindings
1855 @subsection Macro Bindings
1858 These forms create local macros and ``symbol macros.''
1860 @defspec macrolet (bindings@dots{}) forms@dots{}
1861 This form is analogous to @code{flet}, but for macros instead of
1862 functions. Each @var{binding} is a list of the same form as the
1863 arguments to @code{defmacro*} (i.e., a macro name, argument list,
1864 and macro-expander forms). The macro is defined accordingly for
1865 use within the body of the @code{macrolet}.
1867 Because of the nature of macros, @code{macrolet} is lexically
1868 scoped even in Emacs Lisp: The @code{macrolet} binding will
1869 affect only calls that appear physically within the body
1870 @var{forms}, possibly after expansion of other macros in the
1874 @defspec symbol-macrolet (bindings@dots{}) forms@dots{}
1875 This form creates @dfn{symbol macros}, which are macros that look
1876 like variable references rather than function calls. Each
1877 @var{binding} is a list @samp{(@var{var} @var{expansion})};
1878 any reference to @var{var} within the body @var{forms} is
1879 replaced by @var{expansion}.
1883 (symbol-macrolet ((foo (car bar)))
1889 A @code{setq} of a symbol macro is treated the same as a @code{setf}.
1890 I.e., @code{(setq foo 4)} in the above would be equivalent to
1891 @code{(setf foo 4)}, which in turn expands to @code{(setf (car bar) 4)}.
1893 Likewise, a @code{let} or @code{let*} binding a symbol macro is
1894 treated like a @code{letf} or @code{letf*}. This differs from true
1895 Common Lisp, where the rules of lexical scoping cause a @code{let}
1896 binding to shadow a @code{symbol-macrolet} binding. In this package,
1897 only @code{lexical-let} and @code{lexical-let*} will shadow a symbol
1900 There is no analogue of @code{defmacro} for symbol macros; all symbol
1901 macros are local. A typical use of @code{symbol-macrolet} is in the
1902 expansion of another macro:
1905 (defmacro* my-dolist ((x list) &rest body)
1906 (let ((var (gensym)))
1907 (list 'loop 'for var 'on list 'do
1908 (list* 'symbol-macrolet (list (list x (list 'car var)))
1911 (setq mylist '(1 2 3 4))
1912 (my-dolist (x mylist) (incf x))
1918 In this example, the @code{my-dolist} macro is similar to @code{dolist}
1919 (@pxref{Iteration}) except that the variable @code{x} becomes a true
1920 reference onto the elements of the list. The @code{my-dolist} call
1921 shown here expands to
1924 (loop for G1234 on mylist do
1925 (symbol-macrolet ((x (car G1234)))
1930 which in turn expands to
1933 (loop for G1234 on mylist do (incf (car G1234)))
1936 @xref{Loop Facility}, for a description of the @code{loop} macro.
1937 This package defines a nonstandard @code{in-ref} loop clause that
1938 works much like @code{my-dolist}.
1941 @node Conditionals, Blocks and Exits, Variable Bindings, Control Structure
1942 @section Conditionals
1945 These conditional forms augment Emacs Lisp's simple @code{if},
1946 @code{and}, @code{or}, and @code{cond} forms.
1948 @defspec when test forms@dots{}
1949 This is a variant of @code{if} where there are no ``else'' forms,
1950 and possibly several ``then'' forms. In particular,
1953 (when @var{test} @var{a} @var{b} @var{c})
1957 is entirely equivalent to
1960 (if @var{test} (progn @var{a} @var{b} @var{c}) nil)
1964 @defspec unless test forms@dots{}
1965 This is a variant of @code{if} where there are no ``then'' forms,
1966 and possibly several ``else'' forms:
1969 (unless @var{test} @var{a} @var{b} @var{c})
1973 is entirely equivalent to
1976 (when (not @var{test}) @var{a} @var{b} @var{c})
1980 @defspec case keyform clause@dots{}
1981 This macro evaluates @var{keyform}, then compares it with the key
1982 values listed in the various @var{clause}s. Whichever clause matches
1983 the key is executed; comparison is done by @code{eql}. If no clause
1984 matches, the @code{case} form returns @code{nil}. The clauses are
1988 (@var{keylist} @var{body-forms}@dots{})
1992 where @var{keylist} is a list of key values. If there is exactly
1993 one value, and it is not a cons cell or the symbol @code{nil} or
1994 @code{t}, then it can be used by itself as a @var{keylist} without
1995 being enclosed in a list. All key values in the @code{case} form
1996 must be distinct. The final clauses may use @code{t} in place of
1997 a @var{keylist} to indicate a default clause that should be taken
1998 if none of the other clauses match. (The symbol @code{otherwise}
1999 is also recognized in place of @code{t}. To make a clause that
2000 matches the actual symbol @code{t}, @code{nil}, or @code{otherwise},
2001 enclose the symbol in a list.)
2003 For example, this expression reads a keystroke, then does one of
2004 four things depending on whether it is an @samp{a}, a @samp{b},
2005 a @key{RET} or @key{LFD}, or anything else.
2011 ((?\r ?\n) (do-ret-thing))
2012 (t (do-other-thing)))
2016 @defspec ecase keyform clause@dots{}
2017 This macro is just like @code{case}, except that if the key does
2018 not match any of the clauses, an error is signalled rather than
2019 simply returning @code{nil}.
2022 @defspec typecase keyform clause@dots{}
2023 This macro is a version of @code{case} that checks for types
2024 rather than values. Each @var{clause} is of the form
2025 @samp{(@var{type} @var{body}...)}. @xref{Type Predicates},
2026 for a description of type specifiers. For example,
2030 (integer (munch-integer x))
2031 (float (munch-float x))
2032 (string (munch-integer (string-to-int x)))
2033 (t (munch-anything x)))
2036 The type specifier @code{t} matches any type of object; the word
2037 @code{otherwise} is also allowed. To make one clause match any of
2038 several types, use an @code{(or ...)} type specifier.
2041 @defspec etypecase keyform clause@dots{}
2042 This macro is just like @code{typecase}, except that if the key does
2043 not match any of the clauses, an error is signalled rather than
2044 simply returning @code{nil}.
2047 @node Blocks and Exits, Iteration, Conditionals, Control Structure
2048 @section Blocks and Exits
2051 Common Lisp @dfn{blocks} provide a non-local exit mechanism very
2052 similar to @code{catch} and @code{throw}, but lexically rather than
2053 dynamically scoped. This package actually implements @code{block}
2054 in terms of @code{catch}; however, the lexical scoping allows the
2055 optimizing byte-compiler to omit the costly @code{catch} step if the
2056 body of the block does not actually @code{return-from} the block.
2058 @defspec block name forms@dots{}
2059 The @var{forms} are evaluated as if by a @code{progn}. However,
2060 if any of the @var{forms} execute @code{(return-from @var{name})},
2061 they will jump out and return directly from the @code{block} form.
2062 The @code{block} returns the result of the last @var{form} unless
2063 a @code{return-from} occurs.
2065 The @code{block}/@code{return-from} mechanism is quite similar to
2066 the @code{catch}/@code{throw} mechanism. The main differences are
2067 that block @var{name}s are unevaluated symbols, rather than forms
2068 (such as quoted symbols) which evaluate to a tag at run-time; and
2069 also that blocks are lexically scoped whereas @code{catch}/@code{throw}
2070 are dynamically scoped. This means that functions called from the
2071 body of a @code{catch} can also @code{throw} to the @code{catch},
2072 but the @code{return-from} referring to a block name must appear
2073 physically within the @var{forms} that make up the body of the block.
2074 They may not appear within other called functions, although they may
2075 appear within macro expansions or @code{lambda}s in the body. Block
2076 names and @code{catch} names form independent name-spaces.
2078 In true Common Lisp, @code{defun} and @code{defmacro} surround
2079 the function or expander bodies with implicit blocks with the
2080 same name as the function or macro. This does not occur in Emacs
2081 Lisp, but this package provides @code{defun*} and @code{defmacro*}
2082 forms which do create the implicit block.
2084 The Common Lisp looping constructs defined by this package,
2085 such as @code{loop} and @code{dolist}, also create implicit blocks
2086 just as in Common Lisp.
2088 Because they are implemented in terms of Emacs Lisp @code{catch}
2089 and @code{throw}, blocks have the same overhead as actual
2090 @code{catch} constructs (roughly two function calls). However,
2091 Zawinski and Furuseth's optimizing byte compiler (standard in
2092 Emacs 19) will optimize away the @code{catch} if the block does
2093 not in fact contain any @code{return} or @code{return-from} calls
2094 that jump to it. This means that @code{do} loops and @code{defun*}
2095 functions which don't use @code{return} don't pay the overhead to
2099 @defspec return-from name [result]
2100 This macro returns from the block named @var{name}, which must be
2101 an (unevaluated) symbol. If a @var{result} form is specified, it
2102 is evaluated to produce the result returned from the @code{block}.
2103 Otherwise, @code{nil} is returned.
2106 @defspec return [result]
2107 This macro is exactly like @code{(return-from nil @var{result})}.
2108 Common Lisp loops like @code{do} and @code{dolist} implicitly enclose
2109 themselves in @code{nil} blocks.
2112 @node Iteration, Loop Facility, Blocks and Exits, Control Structure
2116 The macros described here provide more sophisticated, high-level
2117 looping constructs to complement Emacs Lisp's basic @code{while}
2120 @defspec loop forms@dots{}
2121 The @dfn{CL} package supports both the simple, old-style meaning of
2122 @code{loop} and the extremely powerful and flexible feature known as
2123 the @dfn{Loop Facility} or @dfn{Loop Macro}. This more advanced
2124 facility is discussed in the following section; @pxref{Loop Facility}.
2125 The simple form of @code{loop} is described here.
2127 If @code{loop} is followed by zero or more Lisp expressions,
2128 then @code{(loop @var{exprs}@dots{})} simply creates an infinite
2129 loop executing the expressions over and over. The loop is
2130 enclosed in an implicit @code{nil} block. Thus,
2133 (loop (foo) (if (no-more) (return 72)) (bar))
2137 is exactly equivalent to
2140 (block nil (while t (foo) (if (no-more) (return 72)) (bar)))
2143 If any of the expressions are plain symbols, the loop is instead
2144 interpreted as a Loop Macro specification as described later.
2145 (This is not a restriction in practice, since a plain symbol
2146 in the above notation would simply access and throw away the
2147 value of a variable.)
2150 @defspec do (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
2151 This macro creates a general iterative loop. Each @var{spec} is
2155 (@var{var} [@var{init} [@var{step}]])
2158 The loop works as follows: First, each @var{var} is bound to the
2159 associated @var{init} value as if by a @code{let} form. Then, in
2160 each iteration of the loop, the @var{end-test} is evaluated; if
2161 true, the loop is finished. Otherwise, the body @var{forms} are
2162 evaluated, then each @var{var} is set to the associated @var{step}
2163 expression (as if by a @code{psetq} form) and the next iteration
2164 begins. Once the @var{end-test} becomes true, the @var{result}
2165 forms are evaluated (with the @var{var}s still bound to their
2166 values) to produce the result returned by @code{do}.
2168 The entire @code{do} loop is enclosed in an implicit @code{nil}
2169 block, so that you can use @code{(return)} to break out of the
2172 If there are no @var{result} forms, the loop returns @code{nil}.
2173 If a given @var{var} has no @var{step} form, it is bound to its
2174 @var{init} value but not otherwise modified during the @code{do}
2175 loop (unless the code explicitly modifies it); this case is just
2176 a shorthand for putting a @code{(let ((@var{var} @var{init})) @dots{})}
2177 around the loop. If @var{init} is also omitted it defaults to
2178 @code{nil}, and in this case a plain @samp{@var{var}} can be used
2179 in place of @samp{(@var{var})}, again following the analogy with
2182 This example (from Steele) illustrates a loop which applies the
2183 function @code{f} to successive pairs of values from the lists
2184 @code{foo} and @code{bar}; it is equivalent to the call
2185 @code{(mapcar* 'f foo bar)}. Note that this loop has no body
2186 @var{forms} at all, performing all its work as side effects of
2187 the rest of the loop.
2190 (do ((x foo (cdr x))
2192 (z nil (cons (f (car x) (car y)) z)))
2193 ((or (null x) (null y))
2198 @defspec do* (spec@dots{}) (end-test [result@dots{}]) forms@dots{}
2199 This is to @code{do} what @code{let*} is to @code{let}. In
2200 particular, the initial values are bound as if by @code{let*}
2201 rather than @code{let}, and the steps are assigned as if by
2202 @code{setq} rather than @code{psetq}.
2204 Here is another way to write the above loop:
2207 (do* ((xp foo (cdr xp))
2209 (x (car xp) (car xp))
2210 (y (car yp) (car yp))
2212 ((or (null xp) (null yp))
2218 @defspec dolist (var list [result]) forms@dots{}
2219 This is a more specialized loop which iterates across the elements
2220 of a list. @var{list} should evaluate to a list; the body @var{forms}
2221 are executed with @var{var} bound to each element of the list in
2222 turn. Finally, the @var{result} form (or @code{nil}) is evaluated
2223 with @var{var} bound to @code{nil} to produce the result returned by
2224 the loop. The loop is surrounded by an implicit @code{nil} block.
2227 @defspec dotimes (var count [result]) forms@dots{}
2228 This is a more specialized loop which iterates a specified number
2229 of times. The body is executed with @var{var} bound to the integers
2230 from zero (inclusive) to @var{count} (exclusive), in turn. Then
2231 the @code{result} form is evaluated with @var{var} bound to the total
2232 number of iterations that were done (i.e., @code{(max 0 @var{count})})
2233 to get the return value for the loop form. The loop is surrounded
2234 by an implicit @code{nil} block.
2237 @defspec do-symbols (var [obarray [result]]) forms@dots{}
2238 This loop iterates over all interned symbols. If @var{obarray}
2239 is specified and is not @code{nil}, it loops over all symbols in
2240 that obarray. For each symbol, the body @var{forms} are evaluated
2241 with @var{var} bound to that symbol. The symbols are visited in
2242 an unspecified order. Afterward the @var{result} form, if any,
2243 is evaluated (with @var{var} bound to @code{nil}) to get the return
2244 value. The loop is surrounded by an implicit @code{nil} block.
2247 @defspec do-all-symbols (var [result]) forms@dots{}
2248 This is identical to @code{do-symbols} except that the @var{obarray}
2249 argument is omitted; it always iterates over the default obarray.
2252 @xref{Mapping over Sequences}, for some more functions for
2253 iterating over vectors or lists.
2255 @node Loop Facility, Multiple Values, Iteration, Control Structure
2256 @section Loop Facility
2259 A common complaint with Lisp's traditional looping constructs is
2260 that they are either too simple and limited, such as Common Lisp's
2261 @code{dotimes} or Emacs Lisp's @code{while}, or too unreadable and
2262 obscure, like Common Lisp's @code{do} loop.
2264 To remedy this, recent versions of Common Lisp have added a new
2265 construct called the ``Loop Facility'' or ``@code{loop} macro,''
2266 with an easy-to-use but very powerful and expressive syntax.
2269 * Loop Basics:: `loop' macro, basic clause structure
2270 * Loop Examples:: Working examples of `loop' macro
2271 * For Clauses:: Clauses introduced by `for' or `as'
2272 * Iteration Clauses:: `repeat', `while', `thereis', etc.
2273 * Accumulation Clauses:: `collect', `sum', `maximize', etc.
2274 * Other Clauses:: `with', `if', `initially', `finally'
2277 @node Loop Basics, Loop Examples, Loop Facility, Loop Facility
2278 @subsection Loop Basics
2281 The @code{loop} macro essentially creates a mini-language within
2282 Lisp that is specially tailored for describing loops. While this
2283 language is a little strange-looking by the standards of regular Lisp,
2284 it turns out to be very easy to learn and well-suited to its purpose.
2286 Since @code{loop} is a macro, all parsing of the loop language
2287 takes place at byte-compile time; compiled @code{loop}s are just
2288 as efficient as the equivalent @code{while} loops written longhand.
2290 @defspec loop clauses@dots{}
2291 A loop construct consists of a series of @var{clause}s, each
2292 introduced by a symbol like @code{for} or @code{do}. Clauses
2293 are simply strung together in the argument list of @code{loop},
2294 with minimal extra parentheses. The various types of clauses
2295 specify initializations, such as the binding of temporary
2296 variables, actions to be taken in the loop, stepping actions,
2299 Common Lisp specifies a certain general order of clauses in a
2303 (loop @var{name-clause}
2304 @var{var-clauses}@dots{}
2305 @var{action-clauses}@dots{})
2308 The @var{name-clause} optionally gives a name to the implicit
2309 block that surrounds the loop. By default, the implicit block
2310 is named @code{nil}. The @var{var-clauses} specify what
2311 variables should be bound during the loop, and how they should
2312 be modified or iterated throughout the course of the loop. The
2313 @var{action-clauses} are things to be done during the loop, such
2314 as computing, collecting, and returning values.
2316 The Emacs version of the @code{loop} macro is less restrictive about
2317 the order of clauses, but things will behave most predictably if
2318 you put the variable-binding clauses @code{with}, @code{for}, and
2319 @code{repeat} before the action clauses. As in Common Lisp,
2320 @code{initially} and @code{finally} clauses can go anywhere.
2322 Loops generally return @code{nil} by default, but you can cause
2323 them to return a value by using an accumulation clause like
2324 @code{collect}, an end-test clause like @code{always}, or an
2325 explicit @code{return} clause to jump out of the implicit block.
2326 (Because the loop body is enclosed in an implicit block, you can
2327 also use regular Lisp @code{return} or @code{return-from} to
2328 break out of the loop.)
2331 The following sections give some examples of the Loop Macro in
2332 action, and describe the particular loop clauses in great detail.
2333 Consult the second edition of Steele's @dfn{Common Lisp, the Language},
2334 for additional discussion and examples of the @code{loop} macro.
2336 @node Loop Examples, For Clauses, Loop Basics, Loop Facility
2337 @subsection Loop Examples
2340 Before listing the full set of clauses that are allowed, let's
2341 look at a few example loops just to get a feel for the @code{loop}
2345 (loop for buf in (buffer-list)
2346 collect (buffer-file-name buf))
2350 This loop iterates over all Emacs buffers, using the list
2351 returned by @code{buffer-list}. For each buffer @code{buf},
2352 it calls @code{buffer-file-name} and collects the results into
2353 a list, which is then returned from the @code{loop} construct.
2354 The result is a list of the file names of all the buffers in
2355 Emacs' memory. The words @code{for}, @code{in}, and @code{collect}
2356 are reserved words in the @code{loop} language.
2359 (loop repeat 20 do (insert "Yowsa\n"))
2363 This loop inserts the phrase ``Yowsa'' twenty times in the
2367 (loop until (eobp) do (munch-line) (forward-line 1))
2371 This loop calls @code{munch-line} on every line until the end
2372 of the buffer. If point is already at the end of the buffer,
2373 the loop exits immediately.
2376 (loop do (munch-line) until (eobp) do (forward-line 1))
2380 This loop is similar to the above one, except that @code{munch-line}
2381 is always called at least once.
2384 (loop for x from 1 to 100
2387 finally return (list x (= y 729)))
2391 This more complicated loop searches for a number @code{x} whose
2392 square is 729. For safety's sake it only examines @code{x}
2393 values up to 100; dropping the phrase @samp{to 100} would
2394 cause the loop to count upwards with no limit. The second
2395 @code{for} clause defines @code{y} to be the square of @code{x}
2396 within the loop; the expression after the @code{=} sign is
2397 reevaluated each time through the loop. The @code{until}
2398 clause gives a condition for terminating the loop, and the
2399 @code{finally} clause says what to do when the loop finishes.
2400 (This particular example was written less concisely than it
2401 could have been, just for the sake of illustration.)
2403 Note that even though this loop contains three clauses (two
2404 @code{for}s and an @code{until}) that would have been enough to
2405 define loops all by themselves, it still creates a single loop
2406 rather than some sort of triple-nested loop. You must explicitly
2407 nest your @code{loop} constructs if you want nested loops.
2409 @node For Clauses, Iteration Clauses, Loop Examples, Loop Facility
2410 @subsection For Clauses
2413 Most loops are governed by one or more @code{for} clauses.
2414 A @code{for} clause simultaneously describes variables to be
2415 bound, how those variables are to be stepped during the loop,
2416 and usually an end condition based on those variables.
2418 The word @code{as} is a synonym for the word @code{for}. This
2419 word is followed by a variable name, then a word like @code{from}
2420 or @code{across} that describes the kind of iteration desired.
2421 In Common Lisp, the phrase @code{being the} sometimes precedes
2422 the type of iteration; in this package both @code{being} and
2423 @code{the} are optional. The word @code{each} is a synonym
2424 for @code{the}, and the word that follows it may be singular
2425 or plural: @samp{for x being the elements of y} or
2426 @samp{for x being each element of y}. Which form you use
2427 is purely a matter of style.
2429 The variable is bound around the loop as if by @code{let}:
2433 (loop for i from 1 to 10 do (do-something-with i))
2439 @item for @var{var} from @var{expr1} to @var{expr2} by @var{expr3}
2440 This type of @code{for} clause creates a counting loop. Each of
2441 the three sub-terms is optional, though there must be at least one
2442 term so that the clause is marked as a counting clause.
2444 The three expressions are the starting value, the ending value, and
2445 the step value, respectively, of the variable. The loop counts
2446 upwards by default (@var{expr3} must be positive), from @var{expr1}
2447 to @var{expr2} inclusively. If you omit the @code{from} term, the
2448 loop counts from zero; if you omit the @code{to} term, the loop
2449 counts forever without stopping (unless stopped by some other
2450 loop clause, of course); if you omit the @code{by} term, the loop
2451 counts in steps of one.
2453 You can replace the word @code{from} with @code{upfrom} or
2454 @code{downfrom} to indicate the direction of the loop. Likewise,
2455 you can replace @code{to} with @code{upto} or @code{downto}.
2456 For example, @samp{for x from 5 downto 1} executes five times
2457 with @code{x} taking on the integers from 5 down to 1 in turn.
2458 Also, you can replace @code{to} with @code{below} or @code{above},
2459 which are like @code{upto} and @code{downto} respectively except
2460 that they are exclusive rather than inclusive limits:
2463 (loop for x to 10 collect x)
2464 @result{} (0 1 2 3 4 5 6 7 8 9 10)
2465 (loop for x below 10 collect x)
2466 @result{} (0 1 2 3 4 5 6 7 8 9)
2469 The @code{by} value is always positive, even for downward-counting
2470 loops. Some sort of @code{from} value is required for downward
2471 loops; @samp{for x downto 5} is not a legal loop clause all by
2474 @item for @var{var} in @var{list} by @var{function}
2475 This clause iterates @var{var} over all the elements of @var{list},
2476 in turn. If you specify the @code{by} term, then @var{function}
2477 is used to traverse the list instead of @code{cdr}; it must be a
2478 function taking one argument. For example:
2481 (loop for x in '(1 2 3 4 5 6) collect (* x x))
2482 @result{} (1 4 9 16 25 36)
2483 (loop for x in '(1 2 3 4 5 6) by 'cddr collect (* x x))
2487 @item for @var{var} on @var{list} by @var{function}
2488 This clause iterates @var{var} over all the cons cells of @var{list}.
2491 (loop for x on '(1 2 3 4) collect x)
2492 @result{} ((1 2 3 4) (2 3 4) (3 4) (4))
2495 With @code{by}, there is no real reason that the @code{on} expression
2496 must be a list. For example:
2499 (loop for x on first-animal by 'next-animal collect x)
2503 where @code{(next-animal x)} takes an ``animal'' @var{x} and returns
2504 the next in the (assumed) sequence of animals, or @code{nil} if
2505 @var{x} was the last animal in the sequence.
2507 @item for @var{var} in-ref @var{list} by @var{function}
2508 This is like a regular @code{in} clause, but @var{var} becomes
2509 a @code{setf}-able ``reference'' onto the elements of the list
2510 rather than just a temporary variable. For example,
2513 (loop for x in-ref my-list do (incf x))
2517 increments every element of @code{my-list} in place. This clause
2518 is an extension to standard Common Lisp.
2520 @item for @var{var} across @var{array}
2521 This clause iterates @var{var} over all the elements of @var{array},
2522 which may be a vector or a string.
2525 (loop for x across "aeiou"
2526 do (use-vowel (char-to-string x)))
2529 @item for @var{var} across-ref @var{array}
2530 This clause iterates over an array, with @var{var} a @code{setf}-able
2531 reference onto the elements; see @code{in-ref} above.
2533 @item for @var{var} being the elements of @var{sequence}
2534 This clause iterates over the elements of @var{sequence}, which may
2535 be a list, vector, or string. Since the type must be determined
2536 at run-time, this is somewhat less efficient than @code{in} or
2537 @code{across}. The clause may be followed by the additional term
2538 @samp{using (index @var{var2})} to cause @var{var2} to be bound to
2539 the successive indices (starting at 0) of the elements.
2541 This clause type is taken from older versions of the @code{loop} macro,
2542 and is not present in modern Common Lisp. The @samp{using (sequence ...)}
2543 term of the older macros is not supported.
2545 @item for @var{var} being the elements of-ref @var{sequence}
2546 This clause iterates over a sequence, with @var{var} a @code{setf}-able
2547 reference onto the elements; see @code{in-ref} above.
2549 @item for @var{var} being the symbols [of @var{obarray}]
2550 This clause iterates over symbols, either over all interned symbols
2551 or over all symbols in @var{obarray}. The loop is executed with
2552 @var{var} bound to each symbol in turn. The symbols are visited in
2553 an unspecified order.
2558 (loop for sym being the symbols
2560 when (string-match "^map" (symbol-name sym))
2565 returns a list of all the functions whose names begin with @samp{map}.
2567 The Common Lisp words @code{external-symbols} and @code{present-symbols}
2568 are also recognized but are equivalent to @code{symbols} in Emacs Lisp.
2570 Due to a minor implementation restriction, it will not work to have
2571 more than one @code{for} clause iterating over symbols, hash tables,
2572 keymaps, overlays, or intervals in a given @code{loop}. Fortunately,
2573 it would rarely if ever be useful to do so. It @emph{is} legal to mix
2574 one of these types of clauses with other clauses like @code{for ... to}
2577 @item for @var{var} being the hash-keys of @var{hash-table}
2578 This clause iterates over the entries in @var{hash-table}. For each
2579 hash table entry, @var{var} is bound to the entry's key. If you write
2580 @samp{the hash-values} instead, @var{var} is bound to the values
2581 of the entries. The clause may be followed by the additional
2582 term @samp{using (hash-values @var{var2})} (where @code{hash-values}
2583 is the opposite word of the word following @code{the}) to cause
2584 @var{var} and @var{var2} to be bound to the two parts of each
2587 @item for @var{var} being the key-codes of @var{keymap}
2588 This clause iterates over the entries in @var{keymap}. In GNU Emacs 18
2589 and 19, keymaps are either alists or vectors, and key-codes are integers
2590 or symbols. In XEmacs, keymaps are a special new data type, and
2591 key-codes are symbols or lists of symbols. The iteration does not enter
2592 nested keymaps or inherited (parent) keymaps. You can use @samp{the
2593 key-bindings} to access the commands bound to the keys rather than the
2594 key codes, and you can add a @code{using} clause to access both the
2595 codes and the bindings together.
2597 @item for @var{var} being the key-seqs of @var{keymap}
2598 This clause iterates over all key sequences defined by @var{keymap}
2599 and its nested keymaps, where @var{var} takes on values which are
2600 strings in Emacs 18 or vectors in Emacs 19. The strings or vectors
2601 are reused for each iteration, so you must copy them if you wish to keep
2602 them permanently. You can add a @samp{using (key-bindings ...)}
2603 clause to get the command bindings as well.
2605 @item for @var{var} being the overlays [of @var{buffer}] @dots{}
2606 This clause iterates over the Emacs 19 ``overlays'' or XEmacs
2607 ``extents'' of a buffer (the clause @code{extents} is synonymous with
2608 @code{overlays}). Under Emacs 18, this clause iterates zero times. If
2609 the @code{of} term is omitted, the current buffer is used. This clause
2610 also accepts optional @samp{from @var{pos}} and @samp{to @var{pos}}
2611 terms, limiting the clause to overlays which overlap the specified
2614 @item for @var{var} being the intervals [of @var{buffer}] @dots{}
2615 This clause iterates over all intervals of a buffer with constant
2616 text properties. The variable @var{var} will be bound to conses
2617 of start and end positions, where one start position is always equal
2618 to the previous end position. The clause allows @code{of},
2619 @code{from}, @code{to}, and @code{property} terms, where the latter
2620 term restricts the search to just the specified property. The
2621 @code{of} term may specify either a buffer or a string. This
2622 clause is useful only in GNU Emacs 19; in other versions, all
2623 buffers and strings consist of a single interval.
2625 @item for @var{var} being the frames
2626 This clause iterates over all frames, i.e., X window system windows
2627 open on Emacs files. This clause works only under Emacs 19. The
2628 clause @code{screens} is a synonym for @code{frames}. The frames
2629 are visited in @code{next-frame} order starting from
2630 @code{selected-frame}.
2632 @item for @var{var} being the windows [of @var{frame}]
2633 This clause iterates over the windows (in the Emacs sense) of
2634 the current frame, or of the specified @var{frame}. (In Emacs 18
2635 there is only ever one frame, and the @code{of} term is not
2638 @item for @var{var} being the buffers
2639 This clause iterates over all buffers in Emacs. It is equivalent
2640 to @samp{for @var{var} in (buffer-list)}.
2642 @item for @var{var} = @var{expr1} then @var{expr2}
2643 This clause does a general iteration. The first time through
2644 the loop, @var{var} will be bound to @var{expr1}. On the second
2645 and successive iterations it will be set by evaluating @var{expr2}
2646 (which may refer to the old value of @var{var}). For example,
2647 these two loops are effectively the same:
2650 (loop for x on my-list by 'cddr do ...)
2651 (loop for x = my-list then (cddr x) while x do ...)
2654 Note that this type of @code{for} clause does not imply any sort
2655 of terminating condition; the above example combines it with a
2656 @code{while} clause to tell when to end the loop.
2658 If you omit the @code{then} term, @var{expr1} is used both for
2659 the initial setting and for successive settings:
2662 (loop for x = (random) when (> x 0) return x)
2666 This loop keeps taking random numbers from the @code{(random)}
2667 function until it gets a positive one, which it then returns.
2670 If you include several @code{for} clauses in a row, they are
2671 treated sequentially (as if by @code{let*} and @code{setq}).
2672 You can instead use the word @code{and} to link the clauses,
2673 in which case they are processed in parallel (as if by @code{let}
2677 (loop for x below 5 for y = nil then x collect (list x y))
2678 @result{} ((0 nil) (1 1) (2 2) (3 3) (4 4))
2679 (loop for x below 5 and y = nil then x collect (list x y))
2680 @result{} ((0 nil) (1 0) (2 1) (3 2) (4 3))
2684 In the first loop, @code{y} is set based on the value of @code{x}
2685 that was just set by the previous clause; in the second loop,
2686 @code{x} and @code{y} are set simultaneously so @code{y} is set
2687 based on the value of @code{x} left over from the previous time
2690 Another feature of the @code{loop} macro is @dfn{destructuring},
2691 similar in concept to the destructuring provided by @code{defmacro}.
2692 The @var{var} part of any @code{for} clause can be given as a list
2693 of variables instead of a single variable. The values produced
2694 during loop execution must be lists; the values in the lists are
2695 stored in the corresponding variables.
2698 (loop for (x y) in '((2 3) (4 5) (6 7)) collect (+ x y))
2702 In loop destructuring, if there are more values than variables
2703 the trailing values are ignored, and if there are more variables
2704 than values the trailing variables get the value @code{nil}.
2705 If @code{nil} is used as a variable name, the corresponding
2706 values are ignored. Destructuring may be nested, and dotted
2707 lists of variables like @code{(x . y)} are allowed.
2709 @node Iteration Clauses, Accumulation Clauses, For Clauses, Loop Facility
2710 @subsection Iteration Clauses
2713 Aside from @code{for} clauses, there are several other loop clauses
2714 that control the way the loop operates. They might be used by
2715 themselves, or in conjunction with one or more @code{for} clauses.
2718 @item repeat @var{integer}
2719 This clause simply counts up to the specified number using an
2720 internal temporary variable. The loops
2723 (loop repeat n do ...)
2724 (loop for temp to n do ...)
2728 are identical except that the second one forces you to choose
2729 a name for a variable you aren't actually going to use.
2731 @item while @var{condition}
2732 This clause stops the loop when the specified condition (any Lisp
2733 expression) becomes @code{nil}. For example, the following two
2734 loops are equivalent, except for the implicit @code{nil} block
2735 that surrounds the second one:
2738 (while @var{cond} @var{forms}@dots{})
2739 (loop while @var{cond} do @var{forms}@dots{})
2742 @item until @var{condition}
2743 This clause stops the loop when the specified condition is true,
2744 i.e., non-@code{nil}.
2746 @item always @var{condition}
2747 This clause stops the loop when the specified condition is @code{nil}.
2748 Unlike @code{while}, it stops the loop using @code{return nil} so that
2749 the @code{finally} clauses are not executed. If all the conditions
2750 were non-@code{nil}, the loop returns @code{t}:
2753 (if (loop for size in size-list always (> size 10))
2758 @item never @var{condition}
2759 This clause is like @code{always}, except that the loop returns
2760 @code{t} if any conditions were false, or @code{nil} otherwise.
2762 @item thereis @var{condition}
2763 This clause stops the loop when the specified form is non-@code{nil};
2764 in this case, it returns that non-@code{nil} value. If all the
2765 values were @code{nil}, the loop returns @code{nil}.
2768 @node Accumulation Clauses, Other Clauses, Iteration Clauses, Loop Facility
2769 @subsection Accumulation Clauses
2772 These clauses cause the loop to accumulate information about the
2773 specified Lisp @var{form}. The accumulated result is returned
2774 from the loop unless overridden, say, by a @code{return} clause.
2777 @item collect @var{form}
2778 This clause collects the values of @var{form} into a list. Several
2779 examples of @code{collect} appear elsewhere in this manual.
2781 The word @code{collecting} is a synonym for @code{collect}, and
2782 likewise for the other accumulation clauses.
2784 @item append @var{form}
2785 This clause collects lists of values into a result list using
2788 @item nconc @var{form}
2789 This clause collects lists of values into a result list by
2790 destructively modifying the lists rather than copying them.
2792 @item concat @var{form}
2793 This clause concatenates the values of the specified @var{form}
2794 into a string. (It and the following clause are extensions to
2795 standard Common Lisp.)
2797 @item vconcat @var{form}
2798 This clause concatenates the values of the specified @var{form}
2801 @item count @var{form}
2802 This clause counts the number of times the specified @var{form}
2803 evaluates to a non-@code{nil} value.
2805 @item sum @var{form}
2806 This clause accumulates the sum of the values of the specified
2807 @var{form}, which must evaluate to a number.
2809 @item maximize @var{form}
2810 This clause accumulates the maximum value of the specified @var{form},
2811 which must evaluate to a number. The return value is undefined if
2812 @code{maximize} is executed zero times.
2814 @item minimize @var{form}
2815 This clause accumulates the minimum value of the specified @var{form}.
2818 Accumulation clauses can be followed by @samp{into @var{var}} to
2819 cause the data to be collected into variable @var{var} (which is
2820 automatically @code{let}-bound during the loop) rather than an
2821 unnamed temporary variable. Also, @code{into} accumulations do
2822 not automatically imply a return value. The loop must use some
2823 explicit mechanism, such as @code{finally return}, to return
2824 the accumulated result.
2826 It is legal for several accumulation clauses of the same type to
2827 accumulate into the same place. From Steele:
2830 (loop for name in '(fred sue alice joe june)
2831 for kids in '((bob ken) () () (kris sunshine) ())
2834 @result{} (fred bob ken sue alice joe kris sunshine june)
2837 @node Other Clauses, , Accumulation Clauses, Loop Facility
2838 @subsection Other Clauses
2841 This section describes the remaining loop clauses.
2844 @item with @var{var} = @var{value}
2845 This clause binds a variable to a value around the loop, but
2846 otherwise leaves the variable alone during the loop. The following
2847 loops are basically equivalent:
2850 (loop with x = 17 do ...)
2851 (let ((x 17)) (loop do ...))
2852 (loop for x = 17 then x do ...)
2855 Naturally, the variable @var{var} might be used for some purpose
2856 in the rest of the loop. For example:
2859 (loop for x in my-list with res = nil do (push x res)
2863 This loop inserts the elements of @code{my-list} at the front of
2864 a new list being accumulated in @code{res}, then returns the
2865 list @code{res} at the end of the loop. The effect is similar
2866 to that of a @code{collect} clause, but the list gets reversed
2867 by virtue of the fact that elements are being pushed onto the
2868 front of @code{res} rather than the end.
2870 If you omit the @code{=} term, the variable is initialized to
2871 @code{nil}. (Thus the @samp{= nil} in the above example is
2874 Bindings made by @code{with} are sequential by default, as if
2875 by @code{let*}. Just like @code{for} clauses, @code{with} clauses
2876 can be linked with @code{and} to cause the bindings to be made by
2879 @item if @var{condition} @var{clause}
2880 This clause executes the following loop clause only if the specified
2881 condition is true. The following @var{clause} should be an accumulation,
2882 @code{do}, @code{return}, @code{if}, or @code{unless} clause.
2883 Several clauses may be linked by separating them with @code{and}.
2884 These clauses may be followed by @code{else} and a clause or clauses
2885 to execute if the condition was false. The whole construct may
2886 optionally be followed by the word @code{end} (which may be used to
2887 disambiguate an @code{else} or @code{and} in a nested @code{if}).
2889 The actual non-@code{nil} value of the condition form is available
2890 by the name @code{it} in the ``then'' part. For example:
2893 (setq funny-numbers '(6 13 -1))
2895 (loop for x below 10
2898 and if (memq x funny-numbers) return (cdr it) end
2900 collect x into evens
2901 finally return (vector odds evens))
2902 @result{} [(1 3 5 7 9) (0 2 4 6 8)]
2903 (setq funny-numbers '(6 7 13 -1))
2904 @result{} (6 7 13 -1)
2905 (loop <@r{same thing again}>)
2909 Note the use of @code{and} to put two clauses into the ``then''
2910 part, one of which is itself an @code{if} clause. Note also that
2911 @code{end}, while normally optional, was necessary here to make
2912 it clear that the @code{else} refers to the outermost @code{if}
2913 clause. In the first case, the loop returns a vector of lists
2914 of the odd and even values of @var{x}. In the second case, the
2915 odd number 7 is one of the @code{funny-numbers} so the loop
2916 returns early; the actual returned value is based on the result
2917 of the @code{memq} call.
2919 @item when @var{condition} @var{clause}
2920 This clause is just a synonym for @code{if}.
2922 @item unless @var{condition} @var{clause}
2923 The @code{unless} clause is just like @code{if} except that the
2924 sense of the condition is reversed.
2926 @item named @var{name}
2927 This clause gives a name other than @code{nil} to the implicit
2928 block surrounding the loop. The @var{name} is the symbol to be
2929 used as the block name.
2931 @item initially [do] @var{forms}...
2932 This keyword introduces one or more Lisp forms which will be
2933 executed before the loop itself begins (but after any variables
2934 requested by @code{for} or @code{with} have been bound to their
2935 initial values). @code{initially} clauses can appear anywhere;
2936 if there are several, they are executed in the order they appear
2937 in the loop. The keyword @code{do} is optional.
2939 @item finally [do] @var{forms}...
2940 This introduces Lisp forms which will be executed after the loop
2941 finishes (say, on request of a @code{for} or @code{while}).
2942 @code{initially} and @code{finally} clauses may appear anywhere
2943 in the loop construct, but they are executed (in the specified
2944 order) at the beginning or end, respectively, of the loop.
2946 @item finally return @var{form}
2947 This says that @var{form} should be executed after the loop
2948 is done to obtain a return value. (Without this, or some other
2949 clause like @code{collect} or @code{return}, the loop will simply
2950 return @code{nil}.) Variables bound by @code{for}, @code{with},
2951 or @code{into} will still contain their final values when @var{form}
2954 @item do @var{forms}...
2955 The word @code{do} may be followed by any number of Lisp expressions
2956 which are executed as an implicit @code{progn} in the body of the
2957 loop. Many of the examples in this section illustrate the use of
2960 @item return @var{form}
2961 This clause causes the loop to return immediately. The following
2962 Lisp form is evaluated to give the return value of the @code{loop}
2963 form. The @code{finally} clauses, if any, are not executed.
2964 Of course, @code{return} is generally used inside an @code{if} or
2965 @code{unless}, as its use in a top-level loop clause would mean
2966 the loop would never get to ``loop'' more than once.
2968 The clause @samp{return @var{form}} is equivalent to
2969 @samp{do (return @var{form})} (or @code{return-from} if the loop
2970 was named). The @code{return} clause is implemented a bit more
2971 efficiently, though.
2974 While there is no high-level way to add user extensions to @code{loop}
2975 (comparable to @code{defsetf} for @code{setf}, say), this package
2976 does offer two properties called @code{cl-loop-handler} and
2977 @code{cl-loop-for-handler} which are functions to be called when
2978 a given symbol is encountered as a top-level loop clause or
2979 @code{for} clause, respectively. Consult the source code in
2980 file @file{cl-macs.el} for details.
2982 This package's @code{loop} macro is compatible with that of Common
2983 Lisp, except that a few features are not implemented: @code{loop-finish}
2984 and data-type specifiers. Naturally, the @code{for} clauses which
2985 iterate over keymaps, overlays, intervals, frames, windows, and
2986 buffers are Emacs-specific extensions.
2988 @node Multiple Values, , Loop Facility, Control Structure
2989 @section Multiple Values
2992 Common Lisp functions can return zero or more results. Emacs Lisp
2993 functions, by contrast, always return exactly one result. This
2994 package makes no attempt to emulate Common Lisp multiple return
2995 values; Emacs versions of Common Lisp functions that return more
2996 than one value either return just the first value (as in
2997 @code{compiler-macroexpand}) or return a list of values (as in
2998 @code{get-setf-method}). This package @emph{does} define placeholders
2999 for the Common Lisp functions that work with multiple values, but
3000 in Emacs Lisp these functions simply operate on lists instead.
3001 The @code{values} form, for example, is a synonym for @code{list}
3004 @defspec multiple-value-bind (var@dots{}) values-form forms@dots{}
3005 This form evaluates @var{values-form}, which must return a list of
3006 values. It then binds the @var{var}s to these respective values,
3007 as if by @code{let}, and then executes the body @var{forms}.
3008 If there are more @var{var}s than values, the extra @var{var}s
3009 are bound to @code{nil}. If there are fewer @var{var}s than
3010 values, the excess values are ignored.
3013 @defspec multiple-value-setq (var@dots{}) form
3014 This form evaluates @var{form}, which must return a list of values.
3015 It then sets the @var{var}s to these respective values, as if by
3016 @code{setq}. Extra @var{var}s or values are treated the same as
3017 in @code{multiple-value-bind}.
3020 The older Quiroz package attempted a more faithful (but still
3021 imperfect) emulation of Common Lisp multiple values. The old
3022 method ``usually'' simulated true multiple values quite well,
3023 but under certain circumstances would leave spurious return
3024 values in memory where a later, unrelated @code{multiple-value-bind}
3025 form would see them.
3027 Since a perfect emulation is not feasible in Emacs Lisp, this
3028 package opts to keep it as simple and predictable as possible.
3030 @node Macros, Declarations, Control Structure, Top
3034 This package implements the various Common Lisp features of
3035 @code{defmacro}, such as destructuring, @code{&environment},
3036 and @code{&body}. Top-level @code{&whole} is not implemented
3037 for @code{defmacro} due to technical difficulties.
3038 @xref{Argument Lists}.
3040 Destructuring is made available to the user by way of the
3043 @defspec destructuring-bind arglist expr forms@dots{}
3044 This macro expands to code which executes @var{forms}, with
3045 the variables in @var{arglist} bound to the list of values
3046 returned by @var{expr}. The @var{arglist} can include all
3047 the features allowed for @code{defmacro} argument lists,
3048 including destructuring. (The @code{&environment} keyword
3049 is not allowed.) The macro expansion will signal an error
3050 if @var{expr} returns a list of the wrong number of arguments
3051 or with incorrect keyword arguments.
3054 This package also includes the Common Lisp @code{define-compiler-macro}
3055 facility, which allows you to define compile-time expansions and
3056 optimizations for your functions.
3058 @defspec define-compiler-macro name arglist forms@dots{}
3059 This form is similar to @code{defmacro}, except that it only expands
3060 calls to @var{name} at compile-time; calls processed by the Lisp
3061 interpreter are not expanded, nor are they expanded by the
3062 @code{macroexpand} function.
3064 The argument list may begin with a @code{&whole} keyword and a
3065 variable. This variable is bound to the macro-call form itself,
3066 i.e., to a list of the form @samp{(@var{name} @var{args}@dots{})}.
3067 If the macro expander returns this form unchanged, then the
3068 compiler treats it as a normal function call. This allows
3069 compiler macros to work as optimizers for special cases of a
3070 function, leaving complicated cases alone.
3072 For example, here is a simplified version of a definition that
3073 appears as a standard part of this package:
3076 (define-compiler-macro member* (&whole form a list &rest keys)
3077 (if (and (null keys)
3078 (eq (car-safe a) 'quote)
3079 (not (floatp-safe (cadr a))))
3085 This definition causes @code{(member* @var{a} @var{list})} to change
3086 to a call to the faster @code{memq} in the common case where @var{a}
3087 is a non-floating-point constant; if @var{a} is anything else, or
3088 if there are any keyword arguments in the call, then the original
3089 @code{member*} call is left intact. (The actual compiler macro
3090 for @code{member*} optimizes a number of other cases, including
3091 common @code{:test} predicates.)
3094 @defun compiler-macroexpand form
3095 This function is analogous to @code{macroexpand}, except that it
3096 expands compiler macros rather than regular macros. It returns
3097 @var{form} unchanged if it is not a call to a function for which
3098 a compiler macro has been defined, or if that compiler macro
3099 decided to punt by returning its @code{&whole} argument. Like
3100 @code{macroexpand}, it expands repeatedly until it reaches a form
3101 for which no further expansion is possible.
3104 @xref{Macro Bindings}, for descriptions of the @code{macrolet}
3105 and @code{symbol-macrolet} forms for making ``local'' macro
3108 @node Declarations, Symbols, Macros, Top
3109 @chapter Declarations
3112 Common Lisp includes a complex and powerful ``declaration''
3113 mechanism that allows you to give the compiler special hints
3114 about the types of data that will be stored in particular variables,
3115 and about the ways those variables and functions will be used. This
3116 package defines versions of all the Common Lisp declaration forms:
3117 @code{declare}, @code{locally}, @code{proclaim}, @code{declaim},
3120 Most of the Common Lisp declarations are not currently useful in
3121 Emacs Lisp, as the byte-code system provides little opportunity
3122 to benefit from type information, and @code{special} declarations
3123 are redundant in a fully dynamically-scoped Lisp. A few
3124 declarations are meaningful when the optimizing Emacs 19 byte
3125 compiler is being used, however. Under the earlier non-optimizing
3126 compiler, these declarations will effectively be ignored.
3128 @defun proclaim decl-spec
3129 This function records a ``global'' declaration specified by
3130 @var{decl-spec}. Since @code{proclaim} is a function, @var{decl-spec}
3131 is evaluated and thus should normally be quoted.
3134 @defspec declaim decl-specs@dots{}
3135 This macro is like @code{proclaim}, except that it takes any number
3136 of @var{decl-spec} arguments, and the arguments are unevaluated and
3137 unquoted. The @code{declaim} macro also puts an @code{(eval-when
3138 (compile load eval) ...)} around the declarations so that they will
3139 be registered at compile-time as well as at run-time. (This is vital,
3140 since normally the declarations are meant to influence the way the
3141 compiler treats the rest of the file that contains the @code{declaim}
3145 @defspec declare decl-specs@dots{}
3146 This macro is used to make declarations within functions and other
3147 code. Common Lisp allows declarations in various locations, generally
3148 at the beginning of any of the many ``implicit @code{progn}s''
3149 throughout Lisp syntax, such as function bodies, @code{let} bodies,
3150 etc. Currently the only declaration understood by @code{declare}
3154 @defspec locally declarations@dots{} forms@dots{}
3155 In this package, @code{locally} is no different from @code{progn}.
3158 @defspec the type form
3159 Type information provided by @code{the} is ignored in this package;
3160 in other words, @code{(the @var{type} @var{form})} is equivalent
3161 to @var{form}. Future versions of the optimizing byte-compiler may
3162 make use of this information.
3164 For example, @code{mapcar} can map over both lists and arrays. It is
3165 hard for the compiler to expand @code{mapcar} into an in-line loop
3166 unless it knows whether the sequence will be a list or an array ahead
3167 of time. With @code{(mapcar 'car (the vector foo))}, a future
3168 compiler would have enough information to expand the loop in-line.
3169 For now, Emacs Lisp will treat the above code as exactly equivalent
3170 to @code{(mapcar 'car foo)}.
3173 Each @var{decl-spec} in a @code{proclaim}, @code{declaim}, or
3174 @code{declare} should be a list beginning with a symbol that says
3175 what kind of declaration it is. This package currently understands
3176 @code{special}, @code{inline}, @code{notinline}, @code{optimize},
3177 and @code{warn} declarations. (The @code{warn} declaration is an
3178 extension of standard Common Lisp.) Other Common Lisp declarations,
3179 such as @code{type} and @code{ftype}, are silently ignored.
3183 Since all variables in Emacs Lisp are ``special'' (in the Common
3184 Lisp sense), @code{special} declarations are only advisory. They
3185 simply tell the optimizing byte compiler that the specified
3186 variables are intentionally being referred to without being
3187 bound in the body of the function. The compiler normally emits
3188 warnings for such references, since they could be typographical
3189 errors for references to local variables.
3191 The declaration @code{(declare (special @var{var1} @var{var2}))} is
3192 equivalent to @code{(defvar @var{var1}) (defvar @var{var2})} in the
3193 optimizing compiler, or to nothing at all in older compilers (which
3194 do not warn for non-local references).
3196 In top-level contexts, it is generally better to write
3197 @code{(defvar @var{var})} than @code{(declaim (special @var{var}))},
3198 since @code{defvar} makes your intentions clearer. But the older
3199 byte compilers can not handle @code{defvar}s appearing inside of
3200 functions, while @code{(declare (special @var{var}))} takes care
3201 to work correctly with all compilers.
3204 The @code{inline} @var{decl-spec} lists one or more functions
3205 whose bodies should be expanded ``in-line'' into calling functions
3206 whenever the compiler is able to arrange for it. For example,
3207 the Common Lisp function @code{cadr} is declared @code{inline}
3208 by this package so that the form @code{(cadr @var{x})} will
3209 expand directly into @code{(car (cdr @var{x}))} when it is called
3210 in user functions, for a savings of one (relatively expensive)
3213 The following declarations are all equivalent. Note that the
3214 @code{defsubst} form is a convenient way to define a function
3215 and declare it inline all at once, but it is available only in
3219 (declaim (inline foo bar))
3220 (eval-when (compile load eval) (proclaim '(inline foo bar)))
3221 (proclaim-inline foo bar) ; XEmacs only
3222 (defsubst foo (...) ...) ; instead of defun; Emacs 19 only
3225 @strong{Please note:} This declaration remains in effect after the
3226 containing source file is done. It is correct to use it to
3227 request that a function you have defined should be inlined,
3228 but it is impolite to use it to request inlining of an external
3231 In Common Lisp, it is possible to use @code{(declare (inline @dots{}))}
3232 before a particular call to a function to cause just that call to
3233 be inlined; the current byte compilers provide no way to implement
3234 this, so @code{(declare (inline @dots{}))} is currently ignored by
3238 The @code{notinline} declaration lists functions which should
3239 not be inlined after all; it cancels a previous @code{inline}
3243 This declaration controls how much optimization is performed by
3244 the compiler. Naturally, it is ignored by the earlier non-optimizing
3247 The word @code{optimize} is followed by any number of lists like
3248 @code{(speed 3)} or @code{(safety 2)}. Common Lisp defines several
3249 optimization ``qualities''; this package ignores all but @code{speed}
3250 and @code{safety}. The value of a quality should be an integer from
3251 0 to 3, with 0 meaning ``unimportant'' and 3 meaning ``very important.''
3252 The default level for both qualities is 1.
3254 In this package, with the Emacs 19 optimizing compiler, the
3255 @code{speed} quality is tied to the @code{byte-compile-optimize}
3256 flag, which is set to @code{nil} for @code{(speed 0)} and to
3257 @code{t} for higher settings; and the @code{safety} quality is
3258 tied to the @code{byte-compile-delete-errors} flag, which is
3259 set to @code{t} for @code{(safety 3)} and to @code{nil} for all
3260 lower settings. (The latter flag controls whether the compiler
3261 is allowed to optimize out code whose only side-effect could
3262 be to signal an error, e.g., rewriting @code{(progn foo bar)} to
3263 @code{bar} when it is not known whether @code{foo} will be bound
3266 Note that even compiling with @code{(safety 0)}, the Emacs
3267 byte-code system provides sufficient checking to prevent real
3268 harm from being done. For example, barring serious bugs in
3269 Emacs itself, Emacs will not crash with a segmentation fault
3270 just because of an error in a fully-optimized Lisp program.
3272 The @code{optimize} declaration is normally used in a top-level
3273 @code{proclaim} or @code{declaim} in a file; Common Lisp allows
3274 it to be used with @code{declare} to set the level of optimization
3275 locally for a given form, but this will not work correctly with the
3276 current version of the optimizing compiler. (The @code{declare}
3277 will set the new optimization level, but that level will not
3278 automatically be unset after the enclosing form is done.)
3281 This declaration controls what sorts of warnings are generated
3282 by the byte compiler. Again, only the optimizing compiler
3283 generates warnings. The word @code{warn} is followed by any
3284 number of ``warning qualities,'' similar in form to optimization
3285 qualities. The currently supported warning types are
3286 @code{redefine}, @code{callargs}, @code{unresolved}, and
3287 @code{free-vars}; in the current system, a value of 0 will
3288 disable these warnings and any higher value will enable them.
3289 See the documentation for the optimizing byte compiler for details.
3292 @node Symbols, Numbers, Declarations, Top
3296 This package defines several symbol-related features that were
3297 missing from Emacs Lisp.
3300 * Property Lists:: `getf', `remf'
3301 * Creating Symbols:: `gensym', `gentemp'
3304 @node Property Lists, Creating Symbols, Symbols, Symbols
3305 @section Property Lists
3308 These functions augment the standard Emacs Lisp functions @code{get}
3309 and @code{put} for operating on properties attached to objects.
3310 There are also functions for working with property lists as
3311 first-class data structures not attached to particular objects.
3313 @defun getf place property &optional default
3314 This function scans the list @var{place} as if it were a property
3315 list, i.e., a list of alternating property names and values. If
3316 an even-numbered element of @var{place} is found which is @code{eq}
3317 to @var{property}, the following odd-numbered element is returned.
3318 Otherwise, @var{default} is returned (or @code{nil} if no default
3324 (get sym prop) @equiv{} (getf (symbol-plist sym) prop)
3327 It is legal to use @code{getf} as a @code{setf} place, in which case
3328 its @var{place} argument must itself be a legal @code{setf} place.
3329 The @var{default} argument, if any, is ignored in this context.
3330 The effect is to change (via @code{setcar}) the value cell in the
3331 list that corresponds to @var{property}, or to cons a new property-value
3332 pair onto the list if the property is not yet present.
3335 (put sym prop val) @equiv{} (setf (getf (symbol-plist sym) prop) val)
3338 The @code{get} function is also @code{setf}-able. The fact that
3339 @code{default} is ignored can sometimes be useful:
3342 (incf (get 'foo 'usage-count 0))
3345 Here, symbol @code{foo}'s @code{usage-count} property is incremented
3346 if it exists, or set to 1 (an incremented 0) otherwise.
3348 When not used as a @code{setf} form, @code{getf} is just a regular
3349 function and its @var{place} argument can actually be any Lisp
3353 @defspec remf place property
3354 This macro removes the property-value pair for @var{property} from
3355 the property list stored at @var{place}, which is any @code{setf}-able
3356 place expression. It returns true if the property was found. Note
3357 that if @var{property} happens to be first on the list, this will
3358 effectively do a @code{(setf @var{place} (cddr @var{place}))},
3359 whereas if it occurs later, this simply uses @code{setcdr} to splice
3360 out the property and value cells.
3367 @node Creating Symbols, , Property Lists, Symbols
3368 @section Creating Symbols
3371 These functions create unique symbols, typically for use as
3372 temporary variables.
3374 @defun gensym &optional x
3375 This function creates a new, uninterned symbol (using @code{make-symbol})
3376 with a unique name. (The name of an uninterned symbol is relevant
3377 only if the symbol is printed.) By default, the name is generated
3378 from an increasing sequence of numbers, @samp{G1000}, @samp{G1001},
3379 @samp{G1002}, etc. If the optional argument @var{x} is a string, that
3380 string is used as a prefix instead of @samp{G}. Uninterned symbols
3381 are used in macro expansions for temporary variables, to ensure that
3382 their names will not conflict with ``real'' variables in the user's
3386 @defvar *gensym-counter*
3387 This variable holds the counter used to generate @code{gensym} names.
3388 It is incremented after each use by @code{gensym}. In Common Lisp
3389 this is initialized with 0, but this package initializes it with a
3390 random (time-dependent) value to avoid trouble when two files that
3391 each used @code{gensym} in their compilation are loaded together.
3393 @strong{XEmacs note:} As of XEmacs 21.0, an uninterned symbol remains
3394 uninterned even after being dumped to bytecode. Older versions of Emacs
3395 didn't distinguish the printed representation of interned and uninterned
3396 symbols, so their names had to be treated more carefully.
3399 @defun gentemp &optional x
3400 This function is like @code{gensym}, except that it produces a new
3401 @emph{interned} symbol. If the symbol that is generated already
3402 exists, the function keeps incrementing the counter and trying
3403 again until a new symbol is generated.
3406 The Quiroz @file{cl.el} package also defined a @code{defkeyword}
3407 form for creating self-quoting keyword symbols. This package
3408 automatically creates all keywords that are called for by
3409 @code{&key} argument specifiers, and discourages the use of
3410 keywords as data unrelated to keyword arguments, so the
3411 @code{defkeyword} form has been discontinued.
3417 @node Numbers, Sequences, Symbols, Top
3421 This section defines a few simple Common Lisp operations on numbers
3422 which were left out of Emacs Lisp.
3425 * Predicates on Numbers:: `plusp', `oddp', `floatp-safe', etc.
3426 * Numerical Functions:: `abs', `expt', `floor*', etc.
3427 * Random Numbers:: `random*', `make-random-state'
3428 * Implementation Parameters:: `most-positive-fixnum', `most-positive-float'
3435 @node Predicates on Numbers, Numerical Functions, Numbers, Numbers
3436 @section Predicates on Numbers
3439 These functions return @code{t} if the specified condition is
3440 true of the numerical argument, or @code{nil} otherwise.
3443 This predicate tests whether @var{number} is positive. It is an
3444 error if the argument is not a number.
3447 @defun minusp number
3448 This predicate tests whether @var{number} is negative. It is an
3449 error if the argument is not a number.
3453 This predicate tests whether @var{integer} is odd. It is an
3454 error if the argument is not an integer.
3457 @defun evenp integer
3458 This predicate tests whether @var{integer} is even. It is an
3459 error if the argument is not an integer.
3462 @defun floatp-safe object
3463 This predicate tests whether @var{object} is a floating-point
3464 number. On systems that support floating-point, this is equivalent
3465 to @code{floatp}. On other systems, this always returns @code{nil}.
3472 @node Numerical Functions, Random Numbers, Predicates on Numbers, Numbers
3473 @section Numerical Functions
3476 These functions perform various arithmetic operations on numbers.
3479 This function returns the absolute value of @var{number}. (Newer
3480 versions of Emacs provide this as a built-in function; this package
3481 defines @code{abs} only for Emacs 18 versions which don't provide
3485 @defun expt base power
3486 This function returns @var{base} raised to the power of @var{number}.
3487 (Newer versions of Emacs provide this as a built-in function; this
3488 package defines @code{expt} only for Emacs 18 versions which don't
3489 provide it as a primitive.)
3492 @defun gcd &rest integers
3493 This function returns the Greatest Common Divisor of the arguments.
3494 For one argument, it returns the absolute value of that argument.
3495 For zero arguments, it returns zero.
3498 @defun lcm &rest integers
3499 This function returns the Least Common Multiple of the arguments.
3500 For one argument, it returns the absolute value of that argument.
3501 For zero arguments, it returns one.
3504 @defun isqrt integer
3505 This function computes the ``integer square root'' of its integer
3506 argument, i.e., the greatest integer less than or equal to the true
3507 square root of the argument.
3510 @defun floor* number &optional divisor
3511 This function implements the Common Lisp @code{floor} function.
3512 It is called @code{floor*} to avoid name conflicts with the
3513 simpler @code{floor} function built-in to Emacs 19.
3515 With one argument, @code{floor*} returns a list of two numbers:
3516 The argument rounded down (toward minus infinity) to an integer,
3517 and the ``remainder'' which would have to be added back to the
3518 first return value to yield the argument again. If the argument
3519 is an integer @var{x}, the result is always the list @code{(@var{x} 0)}.
3520 If the argument is an Emacs 19 floating-point number, the first
3521 result is a Lisp integer and the second is a Lisp float between
3522 0 (inclusive) and 1 (exclusive).
3524 With two arguments, @code{floor*} divides @var{number} by
3525 @var{divisor}, and returns the floor of the quotient and the
3526 corresponding remainder as a list of two numbers. If
3527 @code{(floor* @var{x} @var{y})} returns @code{(@var{q} @var{r})},
3528 then @code{@var{q}*@var{y} + @var{r} = @var{x}}, with @var{r}
3529 between 0 (inclusive) and @var{r} (exclusive). Also, note
3530 that @code{(floor* @var{x})} is exactly equivalent to
3531 @code{(floor* @var{x} 1)}.
3533 This function is entirely compatible with Common Lisp's @code{floor}
3534 function, except that it returns the two results in a list since
3535 Emacs Lisp does not support multiple-valued functions.
3538 @defun ceiling* number &optional divisor
3539 This function implements the Common Lisp @code{ceiling} function,
3540 which is analogous to @code{floor} except that it rounds the
3541 argument or quotient of the arguments up toward plus infinity.
3542 The remainder will be between 0 and minus @var{r}.
3545 @defun truncate* number &optional divisor
3546 This function implements the Common Lisp @code{truncate} function,
3547 which is analogous to @code{floor} except that it rounds the
3548 argument or quotient of the arguments toward zero. Thus it is
3549 equivalent to @code{floor*} if the argument or quotient is
3550 positive, or to @code{ceiling*} otherwise. The remainder has
3551 the same sign as @var{number}.
3554 @defun round* number &optional divisor
3555 This function implements the Common Lisp @code{round} function,
3556 which is analogous to @code{floor} except that it rounds the
3557 argument or quotient of the arguments to the nearest integer.
3558 In the case of a tie (the argument or quotient is exactly
3559 halfway between two integers), it rounds to the even integer.
3562 @defun mod* number divisor
3563 This function returns the same value as the second return value
3567 @defun rem* number divisor
3568 This function returns the same value as the second return value
3572 These definitions are compatible with those in the Quiroz
3573 @file{cl.el} package, except that this package appends @samp{*}
3574 to certain function names to avoid conflicts with existing
3575 Emacs 19 functions, and that the mechanism for returning
3576 multiple values is different.
3582 @node Random Numbers, Implementation Parameters, Numerical Functions, Numbers
3583 @section Random Numbers
3586 This package also provides an implementation of the Common Lisp
3587 random number generator. It uses its own additive-congruential
3588 algorithm, which is much more likely to give statistically clean
3589 random numbers than the simple generators supplied by many
3592 @defun random* number &optional state
3593 This function returns a random nonnegative number less than
3594 @var{number}, and of the same type (either integer or floating-point).
3595 The @var{state} argument should be a @code{random-state} object
3596 which holds the state of the random number generator. The
3597 function modifies this state object as a side effect. If
3598 @var{state} is omitted, it defaults to the variable
3599 @code{*random-state*}, which contains a pre-initialized
3600 @code{random-state} object.
3603 @defvar *random-state*
3604 This variable contains the system ``default'' @code{random-state}
3605 object, used for calls to @code{random*} that do not specify an
3606 alternative state object. Since any number of programs in the
3607 Emacs process may be accessing @code{*random-state*} in interleaved
3608 fashion, the sequence generated from this variable will be
3609 irreproducible for all intents and purposes.
3612 @defun make-random-state &optional state
3613 This function creates or copies a @code{random-state} object.
3614 If @var{state} is omitted or @code{nil}, it returns a new copy of
3615 @code{*random-state*}. This is a copy in the sense that future
3616 sequences of calls to @code{(random* @var{n})} and
3617 @code{(random* @var{n} @var{s})} (where @var{s} is the new
3618 random-state object) will return identical sequences of random
3621 If @var{state} is a @code{random-state} object, this function
3622 returns a copy of that object. If @var{state} is @code{t}, this
3623 function returns a new @code{random-state} object seeded from the
3624 date and time. As an extension to Common Lisp, @var{state} may also
3625 be an integer in which case the new object is seeded from that
3626 integer; each different integer seed will result in a completely
3627 different sequence of random numbers.
3629 It is legal to print a @code{random-state} object to a buffer or
3630 file and later read it back with @code{read}. If a program wishes
3631 to use a sequence of pseudo-random numbers which can be reproduced
3632 later for debugging, it can call @code{(make-random-state t)} to
3633 get a new sequence, then print this sequence to a file. When the
3634 program is later rerun, it can read the original run's random-state
3638 @defun random-state-p object
3639 This predicate returns @code{t} if @var{object} is a
3640 @code{random-state} object, or @code{nil} otherwise.
3643 @node Implementation Parameters, , Random Numbers, Numbers
3644 @section Implementation Parameters
3647 This package defines several useful constants having to with numbers.
3649 @defvar most-positive-fixnum
3650 This constant equals the largest value a Lisp integer can hold.
3651 It is typically @code{2^23-1} or @code{2^25-1}.
3654 @defvar most-negative-fixnum
3655 This constant equals the smallest (most negative) value a Lisp
3659 The following parameters have to do with floating-point numbers.
3660 This package determines their values by exercising the computer's
3661 floating-point arithmetic in various ways. Because this operation
3662 might be slow, the code for initializing them is kept in a separate
3663 function that must be called before the parameters can be used.
3665 @defun cl-float-limits
3666 This function makes sure that the Common Lisp floating-point
3667 parameters like @code{most-positive-float} have been initialized.
3668 Until it is called, these parameters will be @code{nil}. If this
3669 version of Emacs does not support floats (e.g., most versions of
3670 Emacs 18), the parameters will remain @code{nil}. If the parameters
3671 have already been initialized, the function returns immediately.
3673 The algorithm makes assumptions that will be valid for most modern
3674 machines, but will fail if the machine's arithmetic is extremely
3675 unusual, e.g., decimal.
3678 Since true Common Lisp supports up to four different floating-point
3679 precisions, it has families of constants like
3680 @code{most-positive-single-float}, @code{most-positive-double-float},
3681 @code{most-positive-long-float}, and so on. Emacs has only one
3682 floating-point precision, so this package omits the precision word
3683 from the constants' names.
3685 @defvar most-positive-float
3686 This constant equals the largest value a Lisp float can hold.
3687 For those systems whose arithmetic supports infinities, this is
3688 the largest @emph{finite} value. For IEEE machines, the value
3689 is approximately @code{1.79e+308}.
3692 @defvar most-negative-float
3693 This constant equals the most-negative value a Lisp float can hold.
3694 (It is assumed to be equal to @code{(- most-positive-float)}.)
3697 @defvar least-positive-float
3698 This constant equals the smallest Lisp float value greater than zero.
3699 For IEEE machines, it is about @code{4.94e-324} if denormals are
3700 supported or @code{2.22e-308} if not.
3703 @defvar least-positive-normalized-float
3704 This constant equals the smallest @emph{normalized} Lisp float greater
3705 than zero, i.e., the smallest value for which IEEE denormalization
3706 will not result in a loss of precision. For IEEE machines, this
3707 value is about @code{2.22e-308}. For machines that do not support
3708 the concept of denormalization and gradual underflow, this constant
3709 will always equal @code{least-positive-float}.
3712 @defvar least-negative-float
3713 This constant is the negative counterpart of @code{least-positive-float}.
3716 @defvar least-negative-normalized-float
3717 This constant is the negative counterpart of
3718 @code{least-positive-normalized-float}.
3721 @defvar float-epsilon
3722 This constant is the smallest positive Lisp float that can be added
3723 to 1.0 to produce a distinct value. Adding a smaller number to 1.0
3724 will yield 1.0 again due to roundoff. For IEEE machines, epsilon
3725 is about @code{2.22e-16}.
3728 @defvar float-negative-epsilon
3729 This is the smallest positive value that can be subtracted from
3730 1.0 to produce a distinct value. For IEEE machines, it is about
3738 @node Sequences, Lists, Numbers, Top
3742 Common Lisp defines a number of functions that operate on
3743 @dfn{sequences}, which are either lists, strings, or vectors.
3744 Emacs Lisp includes a few of these, notably @code{elt} and
3745 @code{length}; this package defines most of the rest.
3748 * Sequence Basics:: Arguments shared by all sequence functions
3749 * Mapping over Sequences:: `mapcar*', `mapcan', `map', `every', etc.
3750 * Sequence Functions:: `subseq', `remove*', `substitute', etc.
3751 * Searching Sequences:: `find', `position', `count', `search', etc.
3752 * Sorting Sequences:: `sort*', `stable-sort', `merge'
3755 @node Sequence Basics, Mapping over Sequences, Sequences, Sequences
3756 @section Sequence Basics
3759 Many of the sequence functions take keyword arguments; @pxref{Argument
3760 Lists}. All keyword arguments are optional and, if specified,
3761 may appear in any order.
3763 The @code{:key} argument should be passed either @code{nil}, or a
3764 function of one argument. This key function is used as a filter
3765 through which the elements of the sequence are seen; for example,
3766 @code{(find x y :key 'car)} is similar to @code{(assoc* x y)}:
3767 It searches for an element of the list whose @code{car} equals
3768 @code{x}, rather than for an element which equals @code{x} itself.
3769 If @code{:key} is omitted or @code{nil}, the filter is effectively
3770 the identity function.
3772 The @code{:test} and @code{:test-not} arguments should be either
3773 @code{nil}, or functions of two arguments. The test function is
3774 used to compare two sequence elements, or to compare a search value
3775 with sequence elements. (The two values are passed to the test
3776 function in the same order as the original sequence function
3777 arguments from which they are derived, or, if they both come from
3778 the same sequence, in the same order as they appear in that sequence.)
3779 The @code{:test} argument specifies a function which must return
3780 true (non-@code{nil}) to indicate a match; instead, you may use
3781 @code{:test-not} to give a function which returns @emph{false} to
3782 indicate a match. The default test function is @code{:test 'eql}.
3784 Many functions which take @var{item} and @code{:test} or @code{:test-not}
3785 arguments also come in @code{-if} and @code{-if-not} varieties,
3786 where a @var{predicate} function is passed instead of @var{item},
3787 and sequence elements match if the predicate returns true on them
3788 (or false in the case of @code{-if-not}). For example:
3791 (remove* 0 seq :test '=) @equiv{} (remove-if 'zerop seq)
3795 to remove all zeros from sequence @code{seq}.
3797 Some operations can work on a subsequence of the argument sequence;
3798 these function take @code{:start} and @code{:end} arguments which
3799 default to zero and the length of the sequence, respectively.
3800 Only elements between @var{start} (inclusive) and @var{end}
3801 (exclusive) are affected by the operation. The @var{end} argument
3802 may be passed @code{nil} to signify the length of the sequence;
3803 otherwise, both @var{start} and @var{end} must be integers, with
3804 @code{0 <= @var{start} <= @var{end} <= (length @var{seq})}.
3805 If the function takes two sequence arguments, the limits are
3806 defined by keywords @code{:start1} and @code{:end1} for the first,
3807 and @code{:start2} and @code{:end2} for the second.
3809 A few functions accept a @code{:from-end} argument, which, if
3810 non-@code{nil}, causes the operation to go from right-to-left
3811 through the sequence instead of left-to-right, and a @code{:count}
3812 argument, which specifies an integer maximum number of elements
3813 to be removed or otherwise processed.
3815 The sequence functions make no guarantees about the order in
3816 which the @code{:test}, @code{:test-not}, and @code{:key} functions
3817 are called on various elements. Therefore, it is a bad idea to depend
3818 on side effects of these functions. For example, @code{:from-end}
3819 may cause the sequence to be scanned actually in reverse, or it may
3820 be scanned forwards but computing a result ``as if'' it were scanned
3821 backwards. (Some functions, like @code{mapcar*} and @code{every},
3822 @emph{do} specify exactly the order in which the function is called
3823 so side effects are perfectly acceptable in those cases.)
3825 Strings in GNU Emacs 19 may contain ``text properties'' as well
3826 as character data. Except as noted, it is undefined whether or
3827 not text properties are preserved by sequence functions. For
3828 example, @code{(remove* ?A @var{str})} may or may not preserve
3829 the properties of the characters copied from @var{str} into the
3832 @node Mapping over Sequences, Sequence Functions, Sequence Basics, Sequences
3833 @section Mapping over Sequences
3836 These functions ``map'' the function you specify over the elements
3837 of lists or arrays. They are all variations on the theme of the
3838 built-in function @code{mapcar}.
3840 @defun mapcar* function seq &rest more-seqs
3841 This function calls @var{function} on successive parallel sets of
3842 elements from its argument sequences. Given a single @var{seq}
3843 argument it is equivalent to @code{mapcar}; given @var{n} sequences,
3844 it calls the function with the first elements of each of the sequences
3845 as the @var{n} arguments to yield the first element of the result
3846 list, then with the second elements, and so on. The mapping stops as
3847 soon as the shortest sequence runs out. The argument sequences may
3848 be any mixture of lists, strings, and vectors; the return sequence
3851 Common Lisp's @code{mapcar} accepts multiple arguments but works
3852 only on lists; Emacs Lisp's @code{mapcar} accepts a single sequence
3853 argument. This package's @code{mapcar*} works as a compatible
3857 @defun map result-type function seq &rest more-seqs
3858 This function maps @var{function} over the argument sequences,
3859 just like @code{mapcar*}, but it returns a sequence of type
3860 @var{result-type} rather than a list. @var{result-type} must
3861 be one of the following symbols: @code{vector}, @code{string},
3862 @code{list} (in which case the effect is the same as for
3863 @code{mapcar*}), or @code{nil} (in which case the results are
3864 thrown away and @code{map} returns @code{nil}).
3867 @defun maplist function list &rest more-lists
3868 This function calls @var{function} on each of its argument lists,
3869 then on the @code{cdr}s of those lists, and so on, until the
3870 shortest list runs out. The results are returned in the form
3871 of a list. Thus, @code{maplist} is like @code{mapcar*} except
3872 that it passes in the list pointers themselves rather than the
3873 @code{car}s of the advancing pointers.
3876 @defun mapc function seq &rest more-seqs
3877 This function is like @code{mapcar*}, except that the values
3878 returned by @var{function} are ignored and thrown away rather
3879 than being collected into a list. The return value of @code{mapc}
3880 is @var{seq}, the first sequence.
3883 @defun mapl function list &rest more-lists
3884 This function is like @code{maplist}, except that it throws away
3885 the values returned by @var{function}.
3888 @defun mapcan function seq &rest more-seqs
3889 This function is like @code{mapcar*}, except that it concatenates
3890 the return values (which must be lists) using @code{nconc},
3891 rather than simply collecting them into a list.
3894 @defun mapcon function list &rest more-lists
3895 This function is like @code{maplist}, except that it concatenates
3896 the return values using @code{nconc}.
3899 @defun some predicate seq &rest more-seqs
3900 This function calls @var{predicate} on each element of @var{seq}
3901 in turn; if @var{predicate} returns a non-@code{nil} value,
3902 @code{some} returns that value, otherwise it returns @code{nil}.
3903 Given several sequence arguments, it steps through the sequences
3904 in parallel until the shortest one runs out, just as in
3905 @code{mapcar*}. You can rely on the left-to-right order in which
3906 the elements are visited, and on the fact that mapping stops
3907 immediately as soon as @var{predicate} returns non-@code{nil}.
3910 @defun every predicate seq &rest more-seqs
3911 This function calls @var{predicate} on each element of the sequence(s)
3912 in turn; it returns @code{nil} as soon as @var{predicate} returns
3913 @code{nil} for any element, or @code{t} if the predicate was true
3917 @defun notany predicate seq &rest more-seqs
3918 This function calls @var{predicate} on each element of the sequence(s)
3919 in turn; it returns @code{nil} as soon as @var{predicate} returns
3920 a non-@code{nil} value for any element, or @code{t} if the predicate
3921 was @code{nil} for all elements.
3924 @defun notevery predicate seq &rest more-seqs
3925 This function calls @var{predicate} on each element of the sequence(s)
3926 in turn; it returns a non-@code{nil} value as soon as @var{predicate}
3927 returns @code{nil} for any element, or @code{t} if the predicate was
3928 true for all elements.
3931 @defun reduce function seq @t{&key :from-end :start :end :initial-value :key}
3932 This function combines the elements of @var{seq} using an associative
3933 binary operation. Suppose @var{function} is @code{*} and @var{seq} is
3934 the list @code{(2 3 4 5)}. The first two elements of the list are
3935 combined with @code{(* 2 3) = 6}; this is combined with the next
3936 element, @code{(* 6 4) = 24}, and that is combined with the final
3937 element: @code{(* 24 5) = 120}. Note that the @code{*} function happens
3938 to be self-reducing, so that @code{(* 2 3 4 5)} has the same effect as
3939 an explicit call to @code{reduce}.
3941 If @code{:from-end} is true, the reduction is right-associative instead
3942 of left-associative:
3945 (reduce '- '(1 2 3 4))
3946 @equiv{} (- (- (- 1 2) 3) 4) @result{} -8
3947 (reduce '- '(1 2 3 4) :from-end t)
3948 @equiv{} (- 1 (- 2 (- 3 4))) @result{} -2
3951 If @code{:key} is specified, it is a function of one argument which
3952 is called on each of the sequence elements in turn.
3954 If @code{:initial-value} is specified, it is effectively added to the
3955 front (or rear in the case of @code{:from-end}) of the sequence.
3956 The @code{:key} function is @emph{not} applied to the initial value.
3958 If the sequence, including the initial value, has exactly one element
3959 then that element is returned without ever calling @var{function}.
3960 If the sequence is empty (and there is no initial value), then
3961 @var{function} is called with no arguments to obtain the return value.
3964 All of these mapping operations can be expressed conveniently in
3965 terms of the @code{loop} macro. In compiled code, @code{loop} will
3966 be faster since it generates the loop as in-line code with no
3969 @node Sequence Functions, Searching Sequences, Mapping over Sequences, Sequences
3970 @section Sequence Functions
3973 This section describes a number of Common Lisp functions for
3974 operating on sequences.
3976 @defun subseq sequence start &optional end
3977 This function returns a given subsequence of the argument
3978 @var{sequence}, which may be a list, string, or vector.
3979 The indices @var{start} and @var{end} must be in range, and
3980 @var{start} must be no greater than @var{end}. If @var{end}
3981 is omitted, it defaults to the length of the sequence. The
3982 return value is always a copy; it does not share structure
3983 with @var{sequence}.
3985 As an extension to Common Lisp, @var{start} and/or @var{end}
3986 may be negative, in which case they represent a distance back
3987 from the end of the sequence. This is for compatibility with
3988 Emacs' @code{substring} function. Note that @code{subseq} is
3989 the @emph{only} sequence function that allows negative
3990 @var{start} and @var{end}.
3992 You can use @code{setf} on a @code{subseq} form to replace a
3993 specified range of elements with elements from another sequence.
3994 The replacement is done as if by @code{replace}, described below.
3997 @defun concatenate result-type &rest seqs
3998 This function concatenates the argument sequences together to
3999 form a result sequence of type @var{result-type}, one of the
4000 symbols @code{vector}, @code{string}, or @code{list}. The
4001 arguments are always copied, even in cases such as
4002 @code{(concatenate 'list '(1 2 3))} where the result is
4003 identical to an argument.
4006 @defun fill seq item @t{&key :start :end}
4007 This function fills the elements of the sequence (or the specified
4008 part of the sequence) with the value @var{item}.
4011 @defun replace seq1 seq2 @t{&key :start1 :end1 :start2 :end2}
4012 This function copies part of @var{seq2} into part of @var{seq1}.
4013 The sequence @var{seq1} is not stretched or resized; the amount
4014 of data copied is simply the shorter of the source and destination
4015 (sub)sequences. The function returns @var{seq1}.
4017 If @var{seq1} and @var{seq2} are @code{eq}, then the replacement
4018 will work correctly even if the regions indicated by the start
4019 and end arguments overlap. However, if @var{seq1} and @var{seq2}
4020 are lists which share storage but are not @code{eq}, and the
4021 start and end arguments specify overlapping regions, the effect
4025 @defun remove* item seq @t{&key :test :test-not :key :count :start :end :from-end}
4026 This returns a copy of @var{seq} with all elements matching
4027 @var{item} removed. The result may share storage with or be
4028 @code{eq} to @var{seq} in some circumstances, but the original
4029 @var{seq} will not be modified. The @code{:test}, @code{:test-not},
4030 and @code{:key} arguments define the matching test that is used;
4031 by default, elements @code{eql} to @var{item} are removed. The
4032 @code{:count} argument specifies the maximum number of matching
4033 elements that can be removed (only the leftmost @var{count} matches
4034 are removed). The @code{:start} and @code{:end} arguments specify
4035 a region in @var{seq} in which elements will be removed; elements
4036 outside that region are not matched or removed. The @code{:from-end}
4037 argument, if true, says that elements should be deleted from the
4038 end of the sequence rather than the beginning (this matters only
4039 if @var{count} was also specified).
4042 @defun delete* item seq @t{&key :test :test-not :key :count :start :end :from-end}
4043 This deletes all elements of @var{seq} which match @var{item}.
4044 It is a destructive operation. Since Emacs Lisp does not support
4045 stretchable strings or vectors, this is the same as @code{remove*}
4046 for those sequence types. On lists, @code{remove*} will copy the
4047 list if necessary to preserve the original list, whereas
4048 @code{delete*} will splice out parts of the argument list.
4049 Compare @code{append} and @code{nconc}, which are analogous
4050 non-destructive and destructive list operations in Emacs Lisp.
4054 @findex remove-if-not
4056 @findex delete-if-not
4057 The predicate-oriented functions @code{remove-if}, @code{remove-if-not},
4058 @code{delete-if}, and @code{delete-if-not} are defined similarly.
4060 @defun delete item list
4061 This MacLisp-compatible function deletes from @var{list} all elements
4062 which are @code{equal} to @var{item}. The @code{delete} function is
4063 built-in to Emacs 19; this package defines it equivalently in Emacs 18.
4066 @defun remove item list
4067 This function removes from @var{list} all elements which are
4068 @code{equal} to @var{item}. This package defines it for symmetry
4069 with @code{delete}, even though @code{remove} is not built-in to
4073 @defun remq item list
4074 This function removes from @var{list} all elements which are
4075 @code{eq} to @var{item}. This package defines it for symmetry
4076 with @code{delq}, even though @code{remq} is not built-in to
4080 @defun remove-duplicates seq @t{&key :test :test-not :key :start :end :from-end}
4081 This function returns a copy of @var{seq} with duplicate elements
4082 removed. Specifically, if two elements from the sequence match
4083 according to the @code{:test}, @code{:test-not}, and @code{:key}
4084 arguments, only the rightmost one is retained. If @code{:from-end}
4085 is true, the leftmost one is retained instead. If @code{:start} or
4086 @code{:end} is specified, only elements within that subsequence are
4087 examined or removed.
4090 @defun delete-duplicates seq @t{&key :test :test-not :key :start :end :from-end}
4091 This function deletes duplicate elements from @var{seq}. It is
4092 a destructive version of @code{remove-duplicates}.
4095 @defun substitute new old seq @t{&key :test :test-not :key :count :start :end :from-end}
4096 This function returns a copy of @var{seq}, with all elements
4097 matching @var{old} replaced with @var{new}. The @code{:count},
4098 @code{:start}, @code{:end}, and @code{:from-end} arguments may be
4099 used to limit the number of substitutions made.
4102 @defun nsubstitute new old seq @t{&key :test :test-not :key :count :start :end :from-end}
4103 This is a destructive version of @code{substitute}; it performs
4104 the substitution using @code{setcar} or @code{aset} rather than
4105 by returning a changed copy of the sequence.
4108 @findex substitute-if
4109 @findex substitute-if-not
4110 @findex nsubstitute-if
4111 @findex nsubstitute-if-not
4112 The @code{substitute-if}, @code{substitute-if-not}, @code{nsubstitute-if},
4113 and @code{nsubstitute-if-not} functions are defined similarly. For
4114 these, a @var{predicate} is given in place of the @var{old} argument.
4116 @node Searching Sequences, Sorting Sequences, Sequence Functions, Sequences
4117 @section Searching Sequences
4120 These functions search for elements or subsequences in a sequence.
4121 (See also @code{member*} and @code{assoc*}; @pxref{Lists}.)
4123 @defun find item seq @t{&key :test :test-not :key :start :end :from-end}
4124 This function searches @var{seq} for an element matching @var{item}.
4125 If it finds a match, it returns the matching element. Otherwise,
4126 it returns @code{nil}. It returns the leftmost match, unless
4127 @code{:from-end} is true, in which case it returns the rightmost
4128 match. The @code{:start} and @code{:end} arguments may be used to
4129 limit the range of elements that are searched.
4132 @defun position item seq @t{&key :test :test-not :key :start :end :from-end}
4133 This function is like @code{find}, except that it returns the
4134 integer position in the sequence of the matching item rather than
4135 the item itself. The position is relative to the start of the
4136 sequence as a whole, even if @code{:start} is non-zero. The function
4137 returns @code{nil} if no matching element was found.
4140 @defun count item seq @t{&key :test :test-not :key :start :end}
4141 This function returns the number of elements of @var{seq} which
4142 match @var{item}. The result is always a nonnegative integer.
4148 @findex position-if-not
4150 @findex count-if-not
4151 The @code{find-if}, @code{find-if-not}, @code{position-if},
4152 @code{position-if-not}, @code{count-if}, and @code{count-if-not}
4153 functions are defined similarly.
4155 @defun mismatch seq1 seq2 @t{&key :test :test-not :key :start1 :end1 :start2 :end2 :from-end}
4156 This function compares the specified parts of @var{seq1} and
4157 @var{seq2}. If they are the same length and the corresponding
4158 elements match (according to @code{:test}, @code{:test-not},
4159 and @code{:key}), the function returns @code{nil}. If there is
4160 a mismatch, the function returns the index (relative to @var{seq1})
4161 of the first mismatching element. This will be the leftmost pair of
4162 elements which do not match, or the position at which the shorter of
4163 the two otherwise-matching sequences runs out.
4165 If @code{:from-end} is true, then the elements are compared from right
4166 to left starting at @code{(1- @var{end1})} and @code{(1- @var{end2})}.
4167 If the sequences differ, then one plus the index of the rightmost
4168 difference (relative to @var{seq1}) is returned.
4170 An interesting example is @code{(mismatch str1 str2 :key 'upcase)},
4171 which compares two strings case-insensitively.
4174 @defun search seq1 seq2 @t{&key :test :test-not :key :from-end :start1 :end1 :start2 :end2}
4175 This function searches @var{seq2} for a subsequence that matches
4176 @var{seq1} (or part of it specified by @code{:start1} and
4177 @code{:end1}.) Only matches which fall entirely within the region
4178 defined by @code{:start2} and @code{:end2} will be considered.
4179 The return value is the index of the leftmost element of the
4180 leftmost match, relative to the start of @var{seq2}, or @code{nil}
4181 if no matches were found. If @code{:from-end} is true, the
4182 function finds the @emph{rightmost} matching subsequence.
4185 @node Sorting Sequences, , Searching Sequences, Sequences
4186 @section Sorting Sequences
4188 @defun sort* seq predicate @t{&key :key}
4189 This function sorts @var{seq} into increasing order as determined
4190 by using @var{predicate} to compare pairs of elements. @var{predicate}
4191 should return true (non-@code{nil}) if and only if its first argument
4192 is less than (not equal to) its second argument. For example,
4193 @code{<} and @code{string-lessp} are suitable predicate functions
4194 for sorting numbers and strings, respectively; @code{>} would sort
4195 numbers into decreasing rather than increasing order.
4197 This function differs from Emacs' built-in @code{sort} in that it
4198 can operate on any type of sequence, not just lists. Also, it
4199 accepts a @code{:key} argument which is used to preprocess data
4200 fed to the @var{predicate} function. For example,
4203 (setq data (sort data 'string-lessp :key 'downcase))
4207 sorts @var{data}, a sequence of strings, into increasing alphabetical
4208 order without regard to case. A @code{:key} function of @code{car}
4209 would be useful for sorting association lists.
4211 The @code{sort*} function is destructive; it sorts lists by actually
4212 rearranging the @code{cdr} pointers in suitable fashion.
4215 @defun stable-sort seq predicate @t{&key :key}
4216 This function sorts @var{seq} @dfn{stably}, meaning two elements
4217 which are equal in terms of @var{predicate} are guaranteed not to
4218 be rearranged out of their original order by the sort.
4220 In practice, @code{sort*} and @code{stable-sort} are equivalent
4221 in Emacs Lisp because the underlying @code{sort} function is
4222 stable by default. However, this package reserves the right to
4223 use non-stable methods for @code{sort*} in the future.
4226 @defun merge type seq1 seq2 predicate @t{&key :key}
4227 This function merges two sequences @var{seq1} and @var{seq2} by
4228 interleaving their elements. The result sequence, of type @var{type}
4229 (in the sense of @code{concatenate}), has length equal to the sum
4230 of the lengths of the two input sequences. The sequences may be
4231 modified destructively. Order of elements within @var{seq1} and
4232 @var{seq2} is preserved in the interleaving; elements of the two
4233 sequences are compared by @var{predicate} (in the sense of
4234 @code{sort}) and the lesser element goes first in the result.
4235 When elements are equal, those from @var{seq1} precede those from
4236 @var{seq2} in the result. Thus, if @var{seq1} and @var{seq2} are
4237 both sorted according to @var{predicate}, then the result will be
4238 a merged sequence which is (stably) sorted according to
4242 @node Lists, Hash Tables, Sequences, Top
4246 The functions described here operate on lists.
4249 * List Functions:: `caddr', `first', `last', `list*', etc.
4250 * Substitution of Expressions:: `subst', `sublis', etc.
4251 * Lists as Sets:: `member*', `adjoin', `union', etc.
4252 * Association Lists:: `assoc*', `rassoc*', `acons', `pairlis'
4255 @node List Functions, Substitution of Expressions, Lists, Lists
4256 @section List Functions
4259 This section describes a number of simple operations on lists,
4260 i.e., chains of cons cells.
4263 This function is equivalent to @code{(car (cdr (cdr @var{x})))}.
4264 Likewise, this package defines all 28 @code{c@var{xxx}r} functions
4265 where @var{xxx} is up to four @samp{a}s and/or @samp{d}s.
4266 All of these functions are @code{setf}-able, and calls to them
4267 are expanded inline by the byte-compiler for maximum efficiency.
4271 This function is a synonym for @code{(car @var{x})}. Likewise,
4272 the functions @code{second}, @code{third}, @dots{}, through
4273 @code{tenth} return the given element of the list @var{x}.
4277 This function is a synonym for @code{(cdr @var{x})}.
4281 Common Lisp defines this function to act like @code{null}, but
4282 signalling an error if @code{x} is neither a @code{nil} nor a
4283 cons cell. This package simply defines @code{endp} as a synonym
4287 @defun list-length x
4288 This function returns the length of list @var{x}, exactly like
4289 @code{(length @var{x})}, except that if @var{x} is a circular
4290 list (where the cdr-chain forms a loop rather than terminating
4291 with @code{nil}), this function returns @code{nil}. (The regular
4292 @code{length} function would get stuck if given a circular list.)
4295 @defun last x &optional n
4296 This function returns the last cons, or the @var{n}th-to-last cons,
4297 of the list @var{x}. If @var{n} is omitted it defaults to 1.
4298 The ``last cons'' means the first cons cell of the list whose
4299 @code{cdr} is not another cons cell. (For normal lists, the
4300 @code{cdr} of the last cons will be @code{nil}.) This function
4301 returns @code{nil} if @var{x} is @code{nil} or shorter than
4302 @var{n}. Note that the last @emph{element} of the list is
4303 @code{(car (last @var{x}))}.
4306 @defun butlast x &optional n
4307 This function returns the list @var{x} with the last element,
4308 or the last @var{n} elements, removed. If @var{n} is greater
4309 than zero it makes a copy of the list so as not to damage the
4310 original list. In general, @code{(append (butlast @var{x} @var{n})
4311 (last @var{x} @var{n}))} will return a list equal to @var{x}.
4314 @defun nbutlast x &optional n
4315 This is a version of @code{butlast} that works by destructively
4316 modifying the @code{cdr} of the appropriate element, rather than
4317 making a copy of the list.
4320 @defun list* arg &rest others
4321 This function constructs a list of its arguments. The final
4322 argument becomes the @code{cdr} of the last cell constructed.
4323 Thus, @code{(list* @var{a} @var{b} @var{c})} is equivalent to
4324 @code{(cons @var{a} (cons @var{b} @var{c}))}, and
4325 @code{(list* @var{a} @var{b} nil)} is equivalent to
4326 @code{(list @var{a} @var{b})}.
4328 (Note that this function really is called @code{list*} in Common
4329 Lisp; it is not a name invented for this package like @code{member*}
4333 @defun ldiff list sublist
4334 If @var{sublist} is a sublist of @var{list}, i.e., is @code{eq} to
4335 one of the cons cells of @var{list}, then this function returns
4336 a copy of the part of @var{list} up to but not including
4337 @var{sublist}. For example, @code{(ldiff x (cddr x))} returns
4338 the first two elements of the list @code{x}. The result is a
4339 copy; the original @var{list} is not modified. If @var{sublist}
4340 is not a sublist of @var{list}, a copy of the entire @var{list}
4344 @defun copy-list list
4345 This function returns a copy of the list @var{list}. It copies
4346 dotted lists like @code{(1 2 . 3)} correctly.
4349 @defun copy-tree x &optional vecp
4350 This function returns a copy of the tree of cons cells @var{x}.
4351 Unlike @code{copy-sequence} (and its alias @code{copy-list}),
4352 which copies only along the @code{cdr} direction, this function
4353 copies (recursively) along both the @code{car} and the @code{cdr}
4354 directions. If @var{x} is not a cons cell, the function simply
4355 returns @var{x} unchanged. If the optional @var{vecp} argument
4356 is true, this function copies vectors (recursively) as well as
4360 @defun tree-equal x y @t{&key :test :test-not :key}
4361 This function compares two trees of cons cells. If @var{x} and
4362 @var{y} are both cons cells, their @code{car}s and @code{cdr}s are
4363 compared recursively. If neither @var{x} nor @var{y} is a cons
4364 cell, they are compared by @code{eql}, or according to the
4365 specified test. The @code{:key} function, if specified, is
4366 applied to the elements of both trees. @xref{Sequences}.
4373 @node Substitution of Expressions, Lists as Sets, List Functions, Lists
4374 @section Substitution of Expressions
4377 These functions substitute elements throughout a tree of cons
4378 cells. (@xref{Sequence Functions}, for the @code{substitute}
4379 function, which works on just the top-level elements of a list.)
4381 @defun subst new old tree @t{&key :test :test-not :key}
4382 This function substitutes occurrences of @var{old} with @var{new}
4383 in @var{tree}, a tree of cons cells. It returns a substituted
4384 tree, which will be a copy except that it may share storage with
4385 the argument @var{tree} in parts where no substitutions occurred.
4386 The original @var{tree} is not modified. This function recurses
4387 on, and compares against @var{old}, both @code{car}s and @code{cdr}s
4388 of the component cons cells. If @var{old} is itself a cons cell,
4389 then matching cells in the tree are substituted as usual without
4390 recursively substituting in that cell. Comparisons with @var{old}
4391 are done according to the specified test (@code{eql} by default).
4392 The @code{:key} function is applied to the elements of the tree
4393 but not to @var{old}.
4396 @defun nsubst new old tree @t{&key :test :test-not :key}
4397 This function is like @code{subst}, except that it works by
4398 destructive modification (by @code{setcar} or @code{setcdr})
4399 rather than copying.
4403 @findex subst-if-not
4405 @findex nsubst-if-not
4406 The @code{subst-if}, @code{subst-if-not}, @code{nsubst-if}, and
4407 @code{nsubst-if-not} functions are defined similarly.
4409 @defun sublis alist tree @t{&key :test :test-not :key}
4410 This function is like @code{subst}, except that it takes an
4411 association list @var{alist} of @var{old}-@var{new} pairs.
4412 Each element of the tree (after applying the @code{:key}
4413 function, if any), is compared with the @code{car}s of
4414 @var{alist}; if it matches, it is replaced by the corresponding
4418 @defun nsublis alist tree @t{&key :test :test-not :key}
4419 This is a destructive version of @code{sublis}.
4422 @node Lists as Sets, Association Lists, Substitution of Expressions, Lists
4423 @section Lists as Sets
4426 These functions perform operations on lists which represent sets
4429 @defun member item list
4430 This MacLisp-compatible function searches @var{list} for an element
4431 which is @code{equal} to @var{item}. The @code{member} function is
4432 built-in to Emacs 19; this package defines it equivalently in Emacs 18.
4433 See the following function for a Common-Lisp compatible version.
4436 @defun member* item list @t{&key :test :test-not :key}
4437 This function searches @var{list} for an element matching @var{item}.
4438 If a match is found, it returns the cons cell whose @code{car} was
4439 the matching element. Otherwise, it returns @code{nil}. Elements
4440 are compared by @code{eql} by default; you can use the @code{:test},
4441 @code{:test-not}, and @code{:key} arguments to modify this behavior.
4444 Note that this function's name is suffixed by @samp{*} to avoid
4445 the incompatible @code{member} function defined in Emacs 19.
4446 (That function uses @code{equal} for comparisons; it is equivalent
4447 to @code{(member* @var{item} @var{list} :test 'equal)}.)
4451 @findex member-if-not
4452 The @code{member-if} and @code{member-if-not} functions
4453 analogously search for elements which satisfy a given predicate.
4455 @defun tailp sublist list
4456 This function returns @code{t} if @var{sublist} is a sublist of
4457 @var{list}, i.e., if @var{sublist} is @code{eql} to @var{list} or to
4458 any of its @code{cdr}s.
4461 @defun adjoin item list @t{&key :test :test-not :key}
4462 This function conses @var{item} onto the front of @var{list},
4463 like @code{(cons @var{item} @var{list})}, but only if @var{item}
4464 is not already present on the list (as determined by @code{member*}).
4465 If a @code{:key} argument is specified, it is applied to
4466 @var{item} as well as to the elements of @var{list} during
4467 the search, on the reasoning that @var{item} is ``about'' to
4468 become part of the list.
4471 @defun union list1 list2 @t{&key :test :test-not :key}
4472 This function combines two lists which represent sets of items,
4473 returning a list that represents the union of those two sets.
4474 The result list will contain all items which appear in @var{list1}
4475 or @var{list2}, and no others. If an item appears in both
4476 @var{list1} and @var{list2} it will be copied only once. If
4477 an item is duplicated in @var{list1} or @var{list2}, it is
4478 undefined whether or not that duplication will survive in the
4479 result list. The order of elements in the result list is also
4483 @defun nunion list1 list2 @t{&key :test :test-not :key}
4484 This is a destructive version of @code{union}; rather than copying,
4485 it tries to reuse the storage of the argument lists if possible.
4488 @defun intersection list1 list2 @t{&key :test :test-not :key}
4489 This function computes the intersection of the sets represented
4490 by @var{list1} and @var{list2}. It returns the list of items
4491 which appear in both @var{list1} and @var{list2}.
4494 @defun nintersection list1 list2 @t{&key :test :test-not :key}
4495 This is a destructive version of @code{intersection}. It
4496 tries to reuse storage of @var{list1} rather than copying.
4497 It does @emph{not} reuse the storage of @var{list2}.
4500 @defun set-difference list1 list2 @t{&key :test :test-not :key}
4501 This function computes the ``set difference'' of @var{list1}
4502 and @var{list2}, i.e., the set of elements that appear in
4503 @var{list1} but @emph{not} in @var{list2}.
4506 @defun nset-difference list1 list2 @t{&key :test :test-not :key}
4507 This is a destructive @code{set-difference}, which will try
4508 to reuse @var{list1} if possible.
4511 @defun set-exclusive-or list1 list2 @t{&key :test :test-not :key}
4512 This function computes the ``set exclusive or'' of @var{list1}
4513 and @var{list2}, i.e., the set of elements that appear in
4514 exactly one of @var{list1} and @var{list2}.
4517 @defun nset-exclusive-or list1 list2 @t{&key :test :test-not :key}
4518 This is a destructive @code{set-exclusive-or}, which will try
4519 to reuse @var{list1} and @var{list2} if possible.
4522 @defun subsetp list1 list2 @t{&key :test :test-not :key}
4523 This function checks whether @var{list1} represents a subset
4524 of @var{list2}, i.e., whether every element of @var{list1}
4525 also appears in @var{list2}.
4528 @node Association Lists, , Lists as Sets, Lists
4529 @section Association Lists
4532 An @dfn{association list} is a list representing a mapping from
4533 one set of values to another; any list whose elements are cons
4534 cells is an association list.
4536 @defun assoc* item a-list @t{&key :test :test-not :key}
4537 This function searches the association list @var{a-list} for an
4538 element whose @code{car} matches (in the sense of @code{:test},
4539 @code{:test-not}, and @code{:key}, or by comparison with @code{eql})
4540 a given @var{item}. It returns the matching element, if any,
4541 otherwise @code{nil}. It ignores elements of @var{a-list} which
4542 are not cons cells. (This corresponds to the behavior of
4543 @code{assq} and @code{assoc} in Emacs Lisp; Common Lisp's
4544 @code{assoc} ignores @code{nil}s but considers any other non-cons
4545 elements of @var{a-list} to be an error.)
4548 @defun rassoc* item a-list @t{&key :test :test-not :key}
4549 This function searches for an element whose @code{cdr} matches
4550 @var{item}. If @var{a-list} represents a mapping, this applies
4551 the inverse of the mapping to @var{item}.
4554 @defun rassoc item a-list
4555 This function searches like @code{rassoc*} with a @code{:test}
4556 argument of @code{equal}. It is analogous to Emacs Lisp's
4557 standard @code{assoc} function, which derives from the MacLisp
4558 rather than the Common Lisp tradition.
4562 @findex assoc-if-not
4564 @findex rassoc-if-not
4565 The @code{assoc-if}, @code{assoc-if-not}, @code{rassoc-if},
4566 and @code{rassoc-if-not} functions are defined similarly.
4568 Two simple functions for constructing association lists are:
4570 @defun acons key value alist
4571 This is equivalent to @code{(cons (cons @var{key} @var{value}) @var{alist})}.
4574 @defun pairlis keys values &optional alist
4575 This is equivalent to @code{(nconc (mapcar* 'cons @var{keys} @var{values})
4579 @node Hash Tables, Structures, Lists, Top
4580 @chapter Hash Tables
4583 Hash tables are now implemented directly in the C code and documented in
4584 @ref{Hash Tables,,, lispref, XEmacs Lisp Reference Manual}.
4587 A @dfn{hash table} is a data structure that maps ``keys'' onto
4588 ``values.'' Keys and values can be arbitrary Lisp data objects.
4589 Hash tables have the property that the time to search for a given
4590 key is roughly constant; simpler data structures like association
4591 lists take time proportional to the number of entries in the list.
4593 @defun make-hash-table @t{&key :test :size}
4594 This function creates and returns a hash-table object whose
4595 function for comparing elements is @code{:test} (@code{eql}
4596 by default), and which is allocated to fit about @code{:size}
4597 elements. The @code{:size} argument is purely advisory; the
4598 table will stretch automatically if you store more elements in
4599 it. If @code{:size} is omitted, a reasonable default is used.
4601 Common Lisp allows only @code{eq}, @code{eql}, @code{equal},
4602 and @code{equalp} as legal values for the @code{:test} argument.
4603 In this package, any reasonable predicate function will work,
4604 though if you use something else you should check the details of
4605 the hashing function described below to make sure it is suitable
4608 Some versions of Emacs (like XEmacs) include a built-in hash
4609 table type; in these versions, @code{make-hash-table} with a test of
4610 @code{eq}, @code{eql}, or @code{equal} will use these built-in hash
4611 tables. In all other cases, it will return a hash-table object which
4612 takes the form of a list with an identifying ``tag'' symbol at the
4613 front. All of the hash table functions in this package can operate on
4614 both types of hash table; normally you will never know which type is
4617 This function accepts the additional Common Lisp keywords
4618 @code{:rehash-size} and @code{:rehash-threshold}, but it ignores
4622 @defun gethash key table &optional default
4623 This function looks up @var{key} in @var{table}. If @var{key}
4624 exists in the table, in the sense that it matches any of the existing
4625 keys according to the table's test function, then the associated value
4626 is returned. Otherwise, @var{default} (or @code{nil}) is returned.
4628 To store new data in the hash table, use @code{setf} on a call to
4629 @code{gethash}. If @var{key} already exists in the table, the
4630 corresponding value is changed to the stored value. If @var{key}
4631 does not already exist, a new entry is added to the table and the
4632 table is reallocated to a larger size if necessary. The @var{default}
4633 argument is allowed but ignored in this case. The situation is
4634 exactly analogous to that of @code{get}; @pxref{Property Lists}.
4637 @defun remhash key table
4638 This function removes the entry for @var{key} from @var{table}.
4639 If an entry was removed, it returns @code{t}. If @var{key} does
4640 not appear in the table, it does nothing and returns @code{nil}.
4643 @defun clrhash table
4644 This function removes all the entries from @var{table}, leaving
4645 an empty hash table.
4648 @defun maphash function table
4649 This function calls @var{function} for each entry in @var{table}.
4650 It passes two arguments to @var{function}, the key and the value
4651 of the given entry. The return value of @var{function} is ignored;
4652 @var{maphash} itself returns @code{nil}. @xref{Loop Facility}, for
4653 an alternate way of iterating over hash tables.
4656 @defun hash-table-count table This function returns the number of
4657 entries in @var{table}. @strong{Warning:} The current implementation of
4658 XEmacs hash-tables does not decrement the stored @code{count}
4659 when @code{remhash} removes an entry. Therefore, the return value of
4660 this function is not dependable if you have used @code{remhash} on the
4661 table and the table's test is @code{eq}, @code{eql}, or @code{equal}.
4662 A slower, but reliable, way to count the entries is
4663 @code{(loop for x being the hash-keys of @var{table} count t)}.
4666 @defun hash-table-p object This function returns @code{t} if
4667 @var{object} is a hash table, @code{nil} otherwise. It recognizes both
4668 types of hash tables (both XEmacs built-in tables and tables implemented
4669 with special lists.)
4672 Sometimes when dealing with hash tables it is useful to know the
4673 exact ``hash function'' that is used. This package implements
4674 hash tables using Emacs Lisp ``obarrays,'' which are the same
4675 data structure that Emacs Lisp uses to keep track of symbols.
4676 Each hash table includes an embedded obarray. Key values given
4677 to @code{gethash} are converted by various means into strings,
4678 which are then looked up in the obarray using @code{intern} and
4679 @code{intern-soft}. The symbol, or ``bucket,'' corresponding to
4680 a given key string includes as its @code{symbol-value} an association
4681 list of all key-value pairs which hash to that string. Depending
4682 on the test function, it is possible for many entries to hash to
4683 the same bucket. For example, if the test is @code{eql}, then the
4684 symbol @code{foo} and two separately built strings @code{"foo"} will
4685 create three entries in the same bucket. Search time is linear
4686 within buckets, so hash tables will be most effective if you arrange
4687 not to store too many things that hash the same.
4689 The following algorithm is used to convert Lisp objects to hash
4694 Strings are used directly as hash strings. (However, if the test
4695 function is @code{equalp}, strings are @code{downcase}d first.)
4698 Symbols are hashed according to their @code{symbol-name}.
4701 Integers are hashed into one of 16 buckets depending on their value
4702 modulo 16. Floating-point numbers are truncated to integers and
4706 Cons cells are hashed according to their @code{car}s; nonempty vectors
4707 are hashed according to their first element.
4710 All other types of objects hash into a single bucket named @code{"*"}.
4714 Thus, for example, searching among many buffer objects in a hash table
4715 will devolve to a (still fairly fast) linear-time search through a
4716 single bucket, whereas searching for different symbols will be very
4717 fast since each symbol will, in general, hash into its own bucket.
4719 The size of the obarray in a hash table is automatically adjusted
4720 as the number of elements increases.
4722 As a special case, @code{make-hash-table} with a @code{:size} argument
4723 of 0 or 1 will create a hash-table object that uses a single association
4724 list rather than an obarray of many lists. For very small tables this
4725 structure will be more efficient since lookup does not require
4726 converting the key to a string or looking it up in an obarray.
4727 However, such tables are guaranteed to take time proportional to
4728 their size to do a search.
4735 @node Structures, Assertions, Hash Tables, Top
4739 The Common Lisp @dfn{structure} mechanism provides a general way
4740 to define data types similar to C's @code{struct} types. A
4741 structure is a Lisp object containing some number of @dfn{slots},
4742 each of which can hold any Lisp data object. Functions are
4743 provided for accessing and setting the slots, creating or copying
4744 structure objects, and recognizing objects of a particular structure
4747 In true Common Lisp, each structure type is a new type distinct
4748 from all existing Lisp types. Since the underlying Emacs Lisp
4749 system provides no way to create new distinct types, this package
4750 implements structures as vectors (or lists upon request) with a
4751 special ``tag'' symbol to identify them.
4753 @defspec defstruct name slots@dots{}
4754 The @code{defstruct} form defines a new structure type called
4755 @var{name}, with the specified @var{slots}. (The @var{slots}
4756 may begin with a string which documents the structure type.)
4757 In the simplest case, @var{name} and each of the @var{slots}
4758 are symbols. For example,
4761 (defstruct person name age sex)
4765 defines a struct type called @code{person} which contains three
4766 slots. Given a @code{person} object @var{p}, you can access those
4767 slots by calling @code{(person-name @var{p})}, @code{(person-age @var{p})},
4768 and @code{(person-sex @var{p})}. You can also change these slots by
4769 using @code{setf} on any of these place forms:
4772 (incf (person-age birthday-boy))
4775 You can create a new @code{person} by calling @code{make-person},
4776 which takes keyword arguments @code{:name}, @code{:age}, and
4777 @code{:sex} to specify the initial values of these slots in the
4778 new object. (Omitting any of these arguments leaves the corresponding
4779 slot ``undefined,'' according to the Common Lisp standard; in Emacs
4780 Lisp, such uninitialized slots are filled with @code{nil}.)
4782 Given a @code{person}, @code{(copy-person @var{p})} makes a new
4783 object of the same type whose slots are @code{eq} to those of @var{p}.
4785 Given any Lisp object @var{x}, @code{(person-p @var{x})} returns
4786 true if @var{x} looks like a @code{person}, false otherwise. (Again,
4787 in Common Lisp this predicate would be exact; in Emacs Lisp the
4788 best it can do is verify that @var{x} is a vector of the correct
4789 length which starts with the correct tag symbol.)
4791 Accessors like @code{person-name} normally check their arguments
4792 (effectively using @code{person-p}) and signal an error if the
4793 argument is the wrong type. This check is affected by
4794 @code{(optimize (safety @dots{}))} declarations. Safety level 1,
4795 the default, uses a somewhat optimized check that will detect all
4796 incorrect arguments, but may use an uninformative error message
4797 (e.g., ``expected a vector'' instead of ``expected a @code{person}'').
4798 Safety level 0 omits all checks except as provided by the underlying
4799 @code{aref} call; safety levels 2 and 3 do rigorous checking that will
4800 always print a descriptive error message for incorrect inputs.
4801 @xref{Declarations}.
4804 (setq dave (make-person :name "Dave" :sex 'male))
4805 @result{} [cl-struct-person "Dave" nil male]
4806 (setq other (copy-person dave))
4807 @result{} [cl-struct-person "Dave" nil male]
4810 (eq (person-name dave) (person-name other))
4814 (person-p [1 2 3 4])
4818 (person-p '[cl-struct-person counterfeit person object])
4822 In general, @var{name} is either a name symbol or a list of a name
4823 symbol followed by any number of @dfn{struct options}; each @var{slot}
4824 is either a slot symbol or a list of the form @samp{(@var{slot-name}
4825 @var{default-value} @var{slot-options}@dots{})}. The @var{default-value}
4826 is a Lisp form which is evaluated any time an instance of the
4827 structure type is created without specifying that slot's value.
4829 Common Lisp defines several slot options, but the only one
4830 implemented in this package is @code{:read-only}. A non-@code{nil}
4831 value for this option means the slot should not be @code{setf}-able;
4832 the slot's value is determined when the object is created and does
4833 not change afterward.
4837 (name nil :read-only t)
4842 Any slot options other than @code{:read-only} are ignored.
4844 For obscure historical reasons, structure options take a different
4845 form than slot options. A structure option is either a keyword
4846 symbol, or a list beginning with a keyword symbol possibly followed
4847 by arguments. (By contrast, slot options are key-value pairs not
4851 (defstruct (person (:constructor create-person)
4857 The following structure options are recognized.
4862 @advance@leftskip-.5@tableindent
4865 The argument is a symbol whose print name is used as the prefix for
4866 the names of slot accessor functions. The default is the name of
4867 the struct type followed by a hyphen. The option @code{(:conc-name p-)}
4868 would change this prefix to @code{p-}. Specifying @code{nil} as an
4869 argument means no prefix, so that the slot names themselves are used
4870 to name the accessor functions.
4873 In the simple case, this option takes one argument which is an
4874 alternate name to use for the constructor function. The default
4875 is @code{make-@var{name}}, e.g., @code{make-person}. The above
4876 example changes this to @code{create-person}. Specifying @code{nil}
4877 as an argument means that no standard constructor should be
4880 In the full form of this option, the constructor name is followed
4881 by an arbitrary argument list. @xref{Program Structure}, for a
4882 description of the format of Common Lisp argument lists. All
4883 options, such as @code{&rest} and @code{&key}, are supported.
4884 The argument names should match the slot names; each slot is
4885 initialized from the corresponding argument. Slots whose names
4886 do not appear in the argument list are initialized based on the
4887 @var{default-value} in their slot descriptor. Also, @code{&optional}
4888 and @code{&key} arguments which don't specify defaults take their
4889 defaults from the slot descriptor. It is legal to include arguments
4890 which don't correspond to slot names; these are useful if they are
4891 referred to in the defaults for optional, keyword, or @code{&aux}
4892 arguments which @emph{do} correspond to slots.
4894 You can specify any number of full-format @code{:constructor}
4895 options on a structure. The default constructor is still generated
4896 as well unless you disable it with a simple-format @code{:constructor}
4902 (:constructor nil) ; no default constructor
4903 (:constructor new-person (name sex &optional (age 0)))
4904 (:constructor new-hound (&key (name "Rover")
4906 &aux (age (* 7 dog-years))
4911 The first constructor here takes its arguments positionally rather
4912 than by keyword. (In official Common Lisp terminology, constructors
4913 that work By Order of Arguments instead of by keyword are called
4914 ``BOA constructors.'' No, I'm not making this up.) For example,
4915 @code{(new-person "Jane" 'female)} generates a person whose slots
4916 are @code{"Jane"}, 0, and @code{female}, respectively.
4918 The second constructor takes two keyword arguments, @code{:name},
4919 which initializes the @code{name} slot and defaults to @code{"Rover"},
4920 and @code{:dog-years}, which does not itself correspond to a slot
4921 but which is used to initialize the @code{age} slot. The @code{sex}
4922 slot is forced to the symbol @code{canine} with no syntax for
4926 The argument is an alternate name for the copier function for
4927 this type. The default is @code{copy-@var{name}}. @code{nil}
4928 means not to generate a copier function. (In this implementation,
4929 all copier functions are simply synonyms for @code{copy-sequence}.)
4932 The argument is an alternate name for the predicate which recognizes
4933 objects of this type. The default is @code{@var{name}-p}. @code{nil}
4934 means not to generate a predicate function. (If the @code{:type}
4935 option is used without the @code{:named} option, no predicate is
4938 In true Common Lisp, @code{typep} is always able to recognize a
4939 structure object even if @code{:predicate} was used. In this
4940 package, @code{typep} simply looks for a function called
4941 @code{@var{typename}-p}, so it will work for structure types
4942 only if they used the default predicate name.
4945 This option implements a very limited form of C++-style inheritance.
4946 The argument is the name of another structure type previously
4947 created with @code{defstruct}. The effect is to cause the new
4948 structure type to inherit all of the included structure's slots
4949 (plus, of course, any new slots described by this struct's slot
4950 descriptors). The new structure is considered a ``specialization''
4951 of the included one. In fact, the predicate and slot accessors
4952 for the included type will also accept objects of the new type.
4954 If there are extra arguments to the @code{:include} option after
4955 the included-structure name, these options are treated as replacement
4956 slot descriptors for slots in the included structure, possibly with
4957 modified default values. Borrowing an example from Steele:
4960 (defstruct person name (age 0) sex)
4962 (defstruct (astronaut (:include person (age 45)))
4964 (favorite-beverage 'tang))
4967 (setq joe (make-person :name "Joe"))
4968 @result{} [cl-struct-person "Joe" 0 nil]
4969 (setq buzz (make-astronaut :name "Buzz"))
4970 @result{} [cl-struct-astronaut "Buzz" 45 nil nil tang]
4972 (list (person-p joe) (person-p buzz))
4974 (list (astronaut-p joe) (astronaut-p buzz))
4979 (astronaut-name joe)
4980 @result{} error: "astronaut-name accessing a non-astronaut"
4983 Thus, if @code{astronaut} is a specialization of @code{person},
4984 then every @code{astronaut} is also a @code{person} (but not the
4985 other way around). Every @code{astronaut} includes all the slots
4986 of a @code{person}, plus extra slots that are specific to
4987 astronauts. Operations that work on people (like @code{person-name})
4988 work on astronauts just like other people.
4990 @item :print-function
4991 In full Common Lisp, this option allows you to specify a function
4992 which is called to print an instance of the structure type. The
4993 Emacs Lisp system offers no hooks into the Lisp printer which would
4994 allow for such a feature, so this package simply ignores
4995 @code{:print-function}.
4998 The argument should be one of the symbols @code{vector} or @code{list}.
4999 This tells which underlying Lisp data type should be used to implement
5000 the new structure type. Vectors are used by default, but
5001 @code{(:type list)} will cause structure objects to be stored as
5004 The vector representation for structure objects has the advantage
5005 that all structure slots can be accessed quickly, although creating
5006 vectors is a bit slower in Emacs Lisp. Lists are easier to create,
5007 but take a relatively long time accessing the later slots.
5010 This option, which takes no arguments, causes a characteristic ``tag''
5011 symbol to be stored at the front of the structure object. Using
5012 @code{:type} without also using @code{:named} will result in a
5013 structure type stored as plain vectors or lists with no identifying
5016 The default, if you don't specify @code{:type} explicitly, is to
5017 use named vectors. Therefore, @code{:named} is only useful in
5018 conjunction with @code{:type}.
5021 (defstruct (person1) name age sex)
5022 (defstruct (person2 (:type list) :named) name age sex)
5023 (defstruct (person3 (:type list)) name age sex)
5025 (setq p1 (make-person1))
5026 @result{} [cl-struct-person1 nil nil nil]
5027 (setq p2 (make-person2))
5028 @result{} (person2 nil nil nil)
5029 (setq p3 (make-person3))
5030 @result{} (nil nil nil)
5037 @result{} error: function person3-p undefined
5040 Since unnamed structures don't have tags, @code{defstruct} is not
5041 able to make a useful predicate for recognizing them. Also,
5042 accessors like @code{person3-name} will be generated but they
5043 will not be able to do any type checking. The @code{person3-name}
5044 function, for example, will simply be a synonym for @code{car} in
5045 this case. By contrast, @code{person2-name} is able to verify
5046 that its argument is indeed a @code{person2} object before
5049 @item :initial-offset
5050 The argument must be a nonnegative integer. It specifies a
5051 number of slots to be left ``empty'' at the front of the
5052 structure. If the structure is named, the tag appears at the
5053 specified position in the list or vector; otherwise, the first
5054 slot appears at that position. Earlier positions are filled
5055 with @code{nil} by the constructors and ignored otherwise. If
5056 the type @code{:include}s another type, then @code{:initial-offset}
5057 specifies a number of slots to be skipped between the last slot
5058 of the included type and the first new slot.
5062 Except as noted, the @code{defstruct} facility of this package is
5063 entirely compatible with that of Common Lisp.
5069 @node Assertions, Efficiency Concerns, Structures, Top
5070 @chapter Assertions and Errors
5073 This section describes two macros that test @dfn{assertions}, i.e.,
5074 conditions which must be true if the program is operating correctly.
5075 Assertions never add to the behavior of a Lisp program; they simply
5076 make ``sanity checks'' to make sure everything is as it should be.
5078 If the optimization property @code{speed} has been set to 3, and
5079 @code{safety} is less than 3, then the byte-compiler will optimize
5080 away the following assertions. Because assertions might be optimized
5081 away, it is a bad idea for them to include side-effects.
5083 @defspec assert test-form [show-args string args@dots{}]
5084 This form verifies that @var{test-form} is true (i.e., evaluates to
5085 a non-@code{nil} value). If so, it returns @code{nil}. If the test
5086 is not satisfied, @code{assert} signals an error.
5088 A default error message will be supplied which includes @var{test-form}.
5089 You can specify a different error message by including a @var{string}
5090 argument plus optional extra arguments. Those arguments are simply
5091 passed to @code{error} to signal the error.
5093 If the optional second argument @var{show-args} is @code{t} instead
5094 of @code{nil}, then the error message (with or without @var{string})
5095 will also include all non-constant arguments of the top-level
5096 @var{form}. For example:
5099 (assert (> x 10) t "x is too small: %d")
5102 This usage of @var{show-args} is a change to Common Lisp. In
5103 true Common Lisp, the second argument gives a list of @var{places}
5104 which can be @code{setf}'d by the user before continuing from the
5108 @defspec check-type place type &optional string
5109 This form verifies that @var{place} evaluates to a value of type
5110 @var{type}. If so, it returns @code{nil}. If not, @code{check-type}
5111 signals a continuable @code{wrong-type-argument} error. The default
5112 error message lists the erroneous value along with @var{type} and
5113 @var{place} themselves. If @var{string} is specified, it is included in
5114 the error message in place of @var{type}. For example:
5117 (check-type x (integer 1 *) "a positive integer")
5120 @xref{Type Predicates}, for a description of the type specifiers
5121 that may be used for @var{type}.
5123 Note that as in Common Lisp, the first argument to @code{check-type}
5124 should be a @var{place} suitable for use by @code{setf}, because
5125 @code{check-type} signals a continuable error that allows the user to
5126 modify @var{place}, most simply by returning a value from the debugger.
5129 The following error-related macro is also defined:
5131 @defspec ignore-errors forms@dots{}
5132 This executes @var{forms} exactly like a @code{progn}, except that
5133 errors are ignored during the @var{forms}. More precisely, if
5134 an error is signalled then @code{ignore-errors} immediately
5135 aborts execution of the @var{forms} and returns @code{nil}.
5136 If the @var{forms} complete successfully, @code{ignore-errors}
5137 returns the result of the last @var{form}.
5140 @node Efficiency Concerns, Common Lisp Compatibility, Assertions, Top
5141 @appendix Efficiency Concerns
5146 Many of the advanced features of this package, such as @code{defun*},
5147 @code{loop}, and @code{setf}, are implemented as Lisp macros. In
5148 byte-compiled code, these complex notations will be expanded into
5149 equivalent Lisp code which is simple and efficient. For example,
5158 are expanded at compile-time to the Lisp forms
5162 (setcar p (cons x (car p)))
5166 which are the most efficient ways of doing these respective operations
5167 in Lisp. Thus, there is no performance penalty for using the more
5168 readable @code{incf} and @code{push} forms in your compiled code.
5170 @emph{Interpreted} code, on the other hand, must expand these macros
5171 every time they are executed. For this reason it is strongly
5172 recommended that code making heavy use of macros be compiled.
5173 (The features labelled ``Special Form'' instead of ``Function'' in
5174 this manual are macros.) A loop using @code{incf} a hundred times
5175 will execute considerably faster if compiled, and will also
5176 garbage-collect less because the macro expansion will not have
5177 to be generated, used, and thrown away a hundred times.
5179 You can find out how a macro expands by using the
5180 @code{cl-prettyexpand} function.
5182 @defun cl-prettyexpand form &optional full
5183 This function takes a single Lisp form as an argument and inserts
5184 a nicely formatted copy of it in the current buffer (which must be
5185 in Lisp mode so that indentation works properly). It also expands
5186 all Lisp macros which appear in the form. The easiest way to use
5187 this function is to go to the @code{*scratch*} buffer and type, say,
5190 (cl-prettyexpand '(loop for x below 10 collect x))
5194 and type @kbd{C-x C-e} immediately after the closing parenthesis;
5202 (setq G1004 (cons x G1004))
5208 will be inserted into the buffer. (The @code{block} macro is
5209 expanded differently in the interpreter and compiler, so
5210 @code{cl-prettyexpand} just leaves it alone. The temporary
5211 variable @code{G1004} was created by @code{gensym}.)
5213 If the optional argument @var{full} is true, then @emph{all}
5214 macros are expanded, including @code{block}, @code{eval-when},
5215 and compiler macros. Expansion is done as if @var{form} were
5216 a top-level form in a file being compiled. For example,
5219 (cl-prettyexpand '(pushnew 'x list))
5220 @print{} (setq list (adjoin 'x list))
5221 (cl-prettyexpand '(pushnew 'x list) t)
5222 @print{} (setq list (if (memq 'x list) list (cons 'x list)))
5223 (cl-prettyexpand '(caddr (member* 'a list)) t)
5224 @print{} (car (cdr (cdr (memq 'a list))))
5227 Note that @code{adjoin}, @code{caddr}, and @code{member*} all
5228 have built-in compiler macros to optimize them in common cases.
5236 @appendixsec Error Checking
5239 Common Lisp compliance has in general not been sacrificed for the
5240 sake of efficiency. A few exceptions have been made for cases
5241 where substantial gains were possible at the expense of marginal
5242 incompatibility. One example is the use of @code{memq} (which is
5243 treated very efficiently by the byte-compiler) to scan for keyword
5244 arguments; this can become confused in rare cases when keyword
5245 symbols are used as both keywords and data values at once. This
5246 is extremely unlikely to occur in practical code, and the use of
5247 @code{memq} allows functions with keyword arguments to be nearly
5248 as fast as functions that use @code{&optional} arguments.
5250 The Common Lisp standard (as embodied in Steele's book) uses the
5251 phrase ``it is an error if'' to indicate a situation which is not
5252 supposed to arise in complying programs; implementations are strongly
5253 encouraged but not required to signal an error in these situations.
5254 This package sometimes omits such error checking in the interest of
5255 compactness and efficiency. For example, @code{do} variable
5256 specifiers are supposed to be lists of one, two, or three forms;
5257 extra forms are ignored by this package rather than signalling a
5258 syntax error. The @code{endp} function is simply a synonym for
5259 @code{null} in this package. Functions taking keyword arguments
5260 will accept an odd number of arguments, treating the trailing
5261 keyword as if it were followed by the value @code{nil}.
5263 Argument lists (as processed by @code{defun*} and friends)
5264 @emph{are} checked rigorously except for the minor point just
5265 mentioned; in particular, keyword arguments are checked for
5266 validity, and @code{&allow-other-keys} and @code{:allow-other-keys}
5267 are fully implemented. Keyword validity checking is slightly
5268 time consuming (though not too bad in byte-compiled code);
5269 you can use @code{&allow-other-keys} to omit this check. Functions
5270 defined in this package such as @code{find} and @code{member*}
5271 do check their keyword arguments for validity.
5278 @appendixsec Optimizing Compiler
5281 The byte-compiler that comes with Emacs 18 normally fails to expand
5282 macros that appear in top-level positions in the file (i.e., outside
5283 of @code{defun}s or other enclosing forms). This would have
5284 disastrous consequences to programs that used such top-level macros
5285 as @code{defun*}, @code{eval-when}, and @code{defstruct}. To
5286 work around this problem, the @dfn{CL} package patches the Emacs
5287 18 compiler to expand top-level macros. This patch will apply to
5288 your own macros, too, if they are used in a top-level context.
5289 The patch will not harm versions of the Emacs 18 compiler which
5290 have already had a similar patch applied, nor will it affect the
5291 optimizing Emacs 19 byte-compiler written by Jamie Zawinski and
5292 Hallvard Furuseth. The patch is applied to the byte compiler's
5293 code in Emacs' memory, @emph{not} to the @file{bytecomp.elc} file
5296 The Emacs 19 compiler (for Emacs 18) is available from various
5297 Emacs Lisp archive sites such as @code{archive.cis.ohio-state.edu}.
5298 Its use is highly recommended; many of the Common Lisp macros emit
5299 code which can be improved by optimization. In particular,
5300 @code{block}s (whether explicit or implicit in constructs like
5301 @code{defun*} and @code{loop}) carry a fair run-time penalty; the
5302 optimizing compiler removes @code{block}s which are not actually
5303 referenced by @code{return} or @code{return-from} inside the block.
5305 @node Common Lisp Compatibility, Old CL Compatibility, Efficiency Concerns, Top
5306 @appendix Common Lisp Compatibility
5309 Following is a list of all known incompatibilities between this
5310 package and Common Lisp as documented in Steele (2nd edition).
5312 Certain function names, such as @code{member}, @code{assoc}, and
5313 @code{floor}, were already taken by (incompatible) Emacs Lisp
5314 functions; this package appends @samp{*} to the names of its
5315 Common Lisp versions of these functions.
5317 The word @code{defun*} is required instead of @code{defun} in order
5318 to use extended Common Lisp argument lists in a function. Likewise,
5319 @code{defmacro*} and @code{function*} are versions of those forms
5320 which understand full-featured argument lists. The @code{&whole}
5321 keyword does not work in @code{defmacro} argument lists (except
5322 inside recursive argument lists).
5324 In order to allow an efficient implementation, keyword arguments use
5325 a slightly cheesy parser which may be confused if a keyword symbol
5326 is passed as the @emph{value} of another keyword argument.
5327 (Specifically, @code{(memq :@var{keyword} @var{rest-of-arguments})}
5328 is used to scan for @code{:@var{keyword}} among the supplied
5331 The @code{eql} and @code{equal} predicates do not distinguish
5332 between IEEE floating-point plus and minus zero. The @code{equalp}
5333 predicate has several differences with Common Lisp; @pxref{Predicates}.
5335 The @code{setf} mechanism is entirely compatible, except that
5336 setf-methods return a list of five values rather than five
5337 values directly. Also, the new ``@code{setf} function'' concept
5338 (typified by @code{(defun (setf foo) @dots{})}) is not implemented.
5340 The @code{do-all-symbols} form is the same as @code{do-symbols}
5341 with no @var{obarray} argument. In Common Lisp, this form would
5342 iterate over all symbols in all packages. Since Emacs obarrays
5343 are not a first-class package mechanism, there is no way for
5344 @code{do-all-symbols} to locate any but the default obarray.
5346 The @code{loop} macro is complete except that @code{loop-finish}
5347 and type specifiers are unimplemented.
5349 The multiple-value return facility treats lists as multiple
5350 values, since Emacs Lisp cannot support multiple return values
5351 directly. The macros will be compatible with Common Lisp if
5352 @code{values} or @code{values-list} is always used to return to
5353 a @code{multiple-value-bind} or other multiple-value receiver;
5354 if @code{values} is used without @code{multiple-value-@dots{}}
5355 or vice-versa the effect will be different from Common Lisp.
5357 Many Common Lisp declarations are ignored, and others match
5358 the Common Lisp standard in concept but not in detail. For
5359 example, local @code{special} declarations, which are purely
5360 advisory in Emacs Lisp, do not rigorously obey the scoping rules
5361 set down in Steele's book.
5363 The variable @code{*gensym-counter*} starts out with a pseudo-random
5364 value rather than with zero. This is to cope with the fact that
5365 generated symbols become interned when they are written to and
5366 loaded back from a file.
5368 The @code{defstruct} facility is compatible, except that structures
5369 are of type @code{:type vector :named} by default rather than some
5370 special, distinct type. Also, the @code{:type} slot option is ignored.
5372 The second argument of @code{check-type} is treated differently.
5374 @node Old CL Compatibility, Porting Common Lisp, Common Lisp Compatibility, Top
5375 @appendix Old CL Compatibility
5378 Following is a list of all known incompatibilities between this package
5379 and the older Quiroz @file{cl.el} package.
5381 This package's emulation of multiple return values in functions is
5382 incompatible with that of the older package. That package attempted
5383 to come as close as possible to true Common Lisp multiple return
5384 values; unfortunately, it could not be 100% reliable and so was prone
5385 to occasional surprises if used freely. This package uses a simpler
5386 method, namely replacing multiple values with lists of values, which
5387 is more predictable though more noticeably different from Common Lisp.
5389 The @code{defkeyword} form and @code{keywordp} function are not
5390 implemented in this package.
5392 The @code{member}, @code{floor}, @code{ceiling}, @code{truncate},
5393 @code{round}, @code{mod}, and @code{rem} functions are suffixed
5394 by @samp{*} in this package to avoid collision with existing
5395 functions in Emacs 18 or Emacs 19. The older package simply
5396 redefined these functions, overwriting the built-in meanings and
5397 causing serious portability problems with Emacs 19. (Some more
5398 recent versions of the Quiroz package changed the names to
5399 @code{cl-member}, etc.; this package defines the latter names as
5400 aliases for @code{member*}, etc.)
5402 Certain functions in the old package which were buggy or inconsistent
5403 with the Common Lisp standard are incompatible with the conforming
5404 versions in this package. For example, @code{eql} and @code{member}
5405 were synonyms for @code{eq} and @code{memq} in that package, @code{setf}
5406 failed to preserve correct order of evaluation of its arguments, etc.
5408 Finally, unlike the older package, this package is careful to
5409 prefix all of its internal names with @code{cl-}. Except for a
5410 few functions which are explicitly defined as additional features
5411 (such as @code{floatp-safe} and @code{letf}), this package does not
5412 export any non-@samp{cl-} symbols which are not also part of Common
5420 @appendixsec The @code{cl-compat} package
5423 The @dfn{CL} package includes emulations of some features of the
5424 old @file{cl.el}, in the form of a compatibility package
5425 @code{cl-compat}. To use it, put @code{(require 'cl-compat)} in
5428 The old package defined a number of internal routines without
5429 @code{cl-} prefixes or other annotations. Call to these routines
5430 may have crept into existing Lisp code. @code{cl-compat}
5431 provides emulations of the following internal routines:
5432 @code{pair-with-newsyms}, @code{zip-lists}, @code{unzip-lists},
5433 @code{reassemble-arglists}, @code{duplicate-symbols-p},
5436 Some @code{setf} forms translated into calls to internal
5437 functions that user code might call directly. The functions
5438 @code{setnth}, @code{setnthcdr}, and @code{setelt} fall in
5439 this category; they are defined by @code{cl-compat}, but the
5440 best fix is to change to use @code{setf} properly.
5442 The @code{cl-compat} file defines the keyword functions
5443 @code{keywordp}, @code{keyword-of}, and @code{defkeyword},
5444 which are not defined by the new @dfn{CL} package because the
5445 use of keywords as data is discouraged.
5447 The @code{build-klist} mechanism for parsing keyword arguments
5448 is emulated by @code{cl-compat}; the @code{with-keyword-args}
5449 macro is not, however, and in any case it's best to change to
5450 use the more natural keyword argument processing offered by
5453 Multiple return values are treated differently by the two
5454 Common Lisp packages. The old package's method was more
5455 compatible with true Common Lisp, though it used heuristics
5456 that caused it to report spurious multiple return values in
5457 certain cases. The @code{cl-compat} package defines a set
5458 of multiple-value macros that are compatible with the old
5459 CL package; again, they are heuristic in nature, but they
5460 are guaranteed to work in any case where the old package's
5461 macros worked. To avoid name collision with the ``official''
5462 multiple-value facilities, the ones in @code{cl-compat} have
5463 capitalized names: @code{Values}, @code{Values-list},
5464 @code{Multiple-value-bind}, etc.
5466 The functions @code{cl-floor}, @code{cl-ceiling}, @code{cl-truncate},
5467 and @code{cl-round} are defined by @code{cl-compat} to use the
5468 old-style multiple-value mechanism, just as they did in the old
5469 package. The newer @code{floor*} and friends return their two
5470 results in a list rather than as multiple values. Note that
5471 older versions of the old package used the unadorned names
5472 @code{floor}, @code{ceiling}, etc.; @code{cl-compat} cannot use
5473 these names because they conflict with Emacs 19 built-ins.
5475 @node Porting Common Lisp, Function Index, Old CL Compatibility, Top
5476 @appendix Porting Common Lisp
5479 This package is meant to be used as an extension to Emacs Lisp,
5480 not as an Emacs implementation of true Common Lisp. Some of the
5481 remaining differences between Emacs Lisp and Common Lisp make it
5482 difficult to port large Common Lisp applications to Emacs. For
5483 one, some of the features in this package are not fully compliant
5484 with ANSI or Steele; @pxref{Common Lisp Compatibility}. But there
5485 are also quite a few features that this package does not provide
5486 at all. Here are some major omissions that you will want watch out
5487 for when bringing Common Lisp code into Emacs.
5491 Case-insensitivity. Symbols in Common Lisp are case-insensitive
5492 by default. Some programs refer to a function or variable as
5493 @code{foo} in one place and @code{Foo} or @code{FOO} in another.
5494 Emacs Lisp will treat these as three distinct symbols.
5496 Some Common Lisp code is written in all upper-case. While Emacs
5497 is happy to let the program's own functions and variables use
5498 this convention, calls to Lisp builtins like @code{if} and
5499 @code{defun} will have to be changed to lower-case.
5502 Lexical scoping. In Common Lisp, function arguments and @code{let}
5503 bindings apply only to references physically within their bodies
5504 (or within macro expansions in their bodies). Emacs Lisp, by
5505 contrast, uses @dfn{dynamic scoping} wherein a binding to a
5506 variable is visible even inside functions called from the body.
5508 Variables in Common Lisp can be made dynamically scoped by
5509 declaring them @code{special} or using @code{defvar}. In Emacs
5510 Lisp it is as if all variables were declared @code{special}.
5512 Often you can use code that was written for lexical scoping
5513 even in a dynamically scoped Lisp, but not always. Here is
5514 an example of a Common Lisp code fragment that would fail in
5518 (defun map-odd-elements (func list)
5520 for flag = t then (not flag)
5521 collect (if flag x (funcall func x))))
5523 (defun add-odd-elements (list x)
5524 (map-odd-elements (function (lambda (a) (+ a x))) list))
5528 In Common Lisp, the two functions' usages of @code{x} are completely
5529 independent. In Emacs Lisp, the binding to @code{x} made by
5530 @code{add-odd-elements} will have been hidden by the binding
5531 in @code{map-odd-elements} by the time the @code{(+ a x)} function
5534 (This package avoids such problems in its own mapping functions
5535 by using names like @code{cl-x} instead of @code{x} internally;
5536 as long as you don't use the @code{cl-} prefix for your own
5537 variables no collision can occur.)
5539 @xref{Lexical Bindings}, for a description of the @code{lexical-let}
5540 form which establishes a Common Lisp-style lexical binding, and some
5541 examples of how it differs from Emacs' regular @code{let}.
5544 Common Lisp allows the shorthand @code{#'x} to stand for
5545 @code{(function x)}, just as @code{'x} stands for @code{(quote x)}.
5546 In Common Lisp, one traditionally uses @code{#'} notation when
5547 referring to the name of a function. In Emacs Lisp, it works
5548 just as well to use a regular quote:
5551 (loop for x in y by #'cddr collect (mapcar #'plusp x)) ; Common Lisp
5552 (loop for x in y by 'cddr collect (mapcar 'plusp x)) ; Emacs Lisp
5555 When @code{#'} introduces a @code{lambda} form, it is best to
5556 write out @code{(function ...)} longhand in Emacs Lisp. You can
5557 use a regular quote, but then the byte-compiler won't know that
5558 the @code{lambda} expression is code that can be compiled.
5561 (mapcar #'(lambda (x) (* x 2)) list) ; Common Lisp
5562 (mapcar (function (lambda (x) (* x 2))) list) ; Emacs Lisp
5565 XEmacs supports @code{#'} notation starting with version 19.8.
5568 Reader macros. Common Lisp includes a second type of macro that
5569 works at the level of individual characters. For example, Common
5570 Lisp implements the quote notation by a reader macro called @code{'},
5571 whereas Emacs Lisp's parser just treats quote as a special case.
5572 Some Lisp packages use reader macros to create special syntaxes
5573 for themselves, which the Emacs parser is incapable of reading.
5576 Other syntactic features. Common Lisp provides a number of
5577 notations beginning with @code{#} that the Emacs Lisp parser
5578 won't understand. For example, @samp{#| ... |#} is an
5579 alternate comment notation, and @samp{#+lucid (foo)} tells
5580 the parser to ignore the @code{(foo)} except in Lucid Common
5583 The number prefixes `#b', `#o', and `#x', however, are supported
5584 by the Emacs Lisp parser to represent numbers in binary, octal,
5585 and hexadecimal notation (or radix), just like in Common Lisp.
5588 Packages. In Common Lisp, symbols are divided into @dfn{packages}.
5589 Symbols that are Lisp built-ins are typically stored in one package;
5590 symbols that are vendor extensions are put in another, and each
5591 application program would have a package for its own symbols.
5592 Certain symbols are ``exported'' by a package and others are
5593 internal; certain packages ``use'' or import the exported symbols
5594 of other packages. To access symbols that would not normally be
5595 visible due to this importing and exporting, Common Lisp provides
5596 a syntax like @code{package:symbol} or @code{package::symbol}.
5598 Emacs Lisp has a single namespace for all interned symbols, and
5599 then uses a naming convention of putting a prefix like @code{cl-}
5600 in front of the name. Some Emacs packages adopt the Common Lisp-like
5601 convention of using @code{cl:} or @code{cl::} as the prefix.
5602 However, the Emacs parser does not understand colons and just
5603 treats them as part of the symbol name. Thus, while @code{mapcar}
5604 and @code{lisp:mapcar} may refer to the same symbol in Common
5605 Lisp, they are totally distinct in Emacs Lisp. Common Lisp
5606 programs which refer to a symbol by the full name sometimes
5607 and the short name other times will not port cleanly to Emacs.
5609 Emacs Lisp does have a concept of ``obarrays,'' which are
5610 package-like collections of symbols, but this feature is not
5611 strong enough to be used as a true package mechanism.
5614 Keywords. The notation @code{:test-not} in Common Lisp really
5615 is a shorthand for @code{keyword:test-not}; keywords are just
5616 symbols in a built-in @code{keyword} package with the special
5617 property that all its symbols are automatically self-evaluating.
5618 Common Lisp programs often use keywords liberally to avoid
5619 having to use quotes.
5621 In Emacs Lisp a keyword is just a symbol whose name begins with
5622 a colon; since the Emacs parser does not treat them specially,
5623 they have to be explicitly made self-evaluating by a statement
5624 like @code{(setq :test-not ':test-not)}. This package arranges
5625 to execute such a statement whenever @code{defun*} or some
5626 other form sees a keyword being used as an argument. Common
5627 Lisp code that assumes that a symbol @code{:mumble} will be
5628 self-evaluating even though it was never introduced by a
5629 @code{defun*} will have to be fixed.
5632 The @code{format} function is quite different between Common
5633 Lisp and Emacs Lisp. It takes an additional ``destination''
5634 argument before the format string. A destination of @code{nil}
5635 means to format to a string as in Emacs Lisp; a destination
5636 of @code{t} means to write to the terminal (similar to
5637 @code{message} in Emacs). Also, format control strings are
5638 utterly different; @code{~} is used instead of @code{%} to
5639 introduce format codes, and the set of available codes is
5640 much richer. There are no notations like @code{\n} for
5641 string literals; instead, @code{format} is used with the
5642 ``newline'' format code, @code{~%}. More advanced formatting
5643 codes provide such features as paragraph filling, case
5644 conversion, and even loops and conditionals.
5646 While it would have been possible to implement most of Common
5647 Lisp @code{format} in this package (under the name @code{format*},
5648 of course), it was not deemed worthwhile. It would have required
5649 a huge amount of code to implement even a decent subset of
5650 @code{format*}, yet the functionality it would provide over
5651 Emacs Lisp's @code{format} would rarely be useful.
5654 Vector constants use square brackets in Emacs Lisp, but
5655 @code{#(a b c)} notation in Common Lisp. To further complicate
5656 matters, Emacs 19 introduces its own @code{#(} notation for
5657 something entirely different---strings with properties.
5660 Characters are distinct from integers in Common Lisp. The
5661 notation for character constants is also different: @code{#\A}
5662 instead of @code{?A}. Also, @code{string=} and @code{string-equal}
5663 are synonyms in Emacs Lisp whereas the latter is case-insensitive
5667 Data types. Some Common Lisp data types do not exist in Emacs
5668 Lisp. Rational numbers and complex numbers are not present,
5669 nor are large integers (all integers are ``fixnums''). All
5670 arrays are one-dimensional. There are no readtables or pathnames;
5671 streams are a set of existing data types rather than a new data
5672 type of their own. Hash tables, random-states, structures, and
5673 packages (obarrays) are built from Lisp vectors or lists rather
5674 than being distinct types.
5677 The Common Lisp Object System (CLOS) is not implemented,
5678 nor is the Common Lisp Condition System.
5681 Common Lisp features that are completely redundant with Emacs
5682 Lisp features of a different name generally have not been
5683 implemented. For example, Common Lisp writes @code{defconstant}
5684 where Emacs Lisp uses @code{defconst}. Similarly, @code{make-list}
5685 takes its arguments in different ways in the two Lisps but does
5686 exactly the same thing, so this package has not bothered to
5687 implement a Common Lisp-style @code{make-list}.
5690 A few more notable Common Lisp features not included in this
5691 package: @code{compiler-let}, @code{tagbody}, @code{prog},
5692 @code{ldb/dpb}, @code{parse-integer}, @code{cerror}.
5695 Recursion. While recursion works in Emacs Lisp just like it
5696 does in Common Lisp, various details of the Emacs Lisp system
5697 and compiler make recursion much less efficient than it is in
5698 most Lisps. Some schools of thought prefer to use recursion
5699 in Lisp over other techniques; they would sum a list of
5700 numbers using something like
5703 (defun sum-list (list)
5705 (+ (car list) (sum-list (cdr list)))
5710 where a more iteratively-minded programmer might write one of
5714 (let ((total 0)) (dolist (x my-list) (incf total x)) total)
5715 (loop for x in my-list sum x)
5718 While this would be mainly a stylistic choice in most Common Lisps,
5719 in Emacs Lisp you should be aware that the iterative forms are
5720 much faster than recursion. Also, Lisp programmers will want to
5721 note that the current Emacs Lisp compiler does not optimize tail
5725 @node Function Index, Variable Index, Porting Common Lisp, Top
5726 @unnumbered Function Index
5730 @node Variable Index, , Function Index, Top
5731 @unnumbered Variable Index