# HG changeset patch # User Glenn Morris # Date 1189054742 0 # Node ID 19c13888b6314cdc6e98b2d178c4b813866a681d # Parent 926f8ad9f714fbe09fab2b902f1e67aba8b154e1 Move here from ../../man diff -r 926f8ad9f714 -r 19c13888b631 doc/misc/cl.texi --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/misc/cl.texi Thu Sep 06 04:59:02 2007 +0000 @@ -0,0 +1,5377 @@ +\input texinfo @c -*-texinfo-*- +@setfilename ../info/cl +@settitle Common Lisp Extensions + +@copying +This file documents the GNU Emacs Common Lisp emulation package. + +Copyright @copyright{} 1993, 2001, 2002, 2003, 2004, 2005, 2006, 2007 +Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU +Manual'', and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@dircategory Emacs +@direntry +* CL: (cl). Partial Common Lisp support for Emacs Lisp. +@end direntry + +@finalout + +@titlepage +@sp 6 +@center @titlefont{Common Lisp Extensions} +@sp 4 +@center For GNU Emacs Lisp +@sp 1 +@center Version 2.02 +@sp 5 +@center Dave Gillespie +@center daveg@@synaptics.com +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@node Top, Overview, (dir), (dir) +@chapter Introduction + +@noindent +This document describes a set of Emacs Lisp facilities borrowed from +Common Lisp. All the facilities are described here in detail. While +this document does not assume any prior knowledge of Common Lisp, it +does assume a basic familiarity with Emacs Lisp. + +@menu +* Overview:: Installation, usage, etc. +* Program Structure:: Arglists, `eval-when', `defalias' +* Predicates:: `typep', `eql', and `equalp' +* Control Structure:: `setf', `do', `loop', etc. +* Macros:: Destructuring, `define-compiler-macro' +* Declarations:: `proclaim', `declare', etc. +* Symbols:: Property lists, `gensym' +* Numbers:: Predicates, functions, random numbers +* Sequences:: Mapping, functions, searching, sorting +* Lists:: `cadr', `sublis', `member*', `assoc*', etc. +* Structures:: `defstruct' +* Assertions:: `check-type', `assert', `ignore-errors'. + +* Efficiency Concerns:: Hints and techniques +* Common Lisp Compatibility:: All known differences with Steele +* Old CL Compatibility:: All known differences with old cl.el +* Porting Common Lisp:: Hints for porting Common Lisp code + +* GNU Free Documentation License:: The license for this documentation. +* Function Index:: +* Variable Index:: +@end menu + +@node Overview, Program Structure, Top, Top +@ifnottex +@chapter Overview +@end ifnottex + +@noindent +Common Lisp is a huge language, and Common Lisp systems tend to be +massive and extremely complex. Emacs Lisp, by contrast, is rather +minimalist in the choice of Lisp features it offers the programmer. +As Emacs Lisp programmers have grown in number, and the applications +they write have grown more ambitious, it has become clear that Emacs +Lisp could benefit from many of the conveniences of Common Lisp. + +The @dfn{CL} package adds a number of Common Lisp functions and +control structures to Emacs Lisp. While not a 100% complete +implementation of Common Lisp, @dfn{CL} adds enough functionality +to make Emacs Lisp programming significantly more convenient. + +@strong{Please note:} the @dfn{CL} functions are not standard parts of +the Emacs Lisp name space, so it is legitimate for users to define +them with other, conflicting meanings. To avoid conflicting with +those user activities, we have a policy that packages installed in +Emacs must not load @dfn{CL} at run time. (It is ok for them to load +@dfn{CL} at compile time only, with @code{eval-when-compile}, and use +the macros it provides.) If you are writing packages that you plan to +distribute and invite widespread use for, you might want to observe +the same rule. + +Some Common Lisp features have been omitted from this package +for various reasons: + +@itemize @bullet +@item +Some features are too complex or bulky relative to their benefit +to Emacs Lisp programmers. CLOS and Common Lisp streams are fine +examples of this group. + +@item +Other features cannot be implemented without modification to the +Emacs Lisp interpreter itself, such as multiple return values, +lexical scoping, case-insensitive symbols, and complex numbers. +The @dfn{CL} package generally makes no attempt to emulate these +features. + +@item +Some features conflict with existing things in Emacs Lisp. For +example, Emacs' @code{assoc} function is incompatible with the +Common Lisp @code{assoc}. In such cases, this package usually +adds the suffix @samp{*} to the function name of the Common +Lisp version of the function (e.g., @code{assoc*}). +@end itemize + +The package described here was written by Dave Gillespie, +@file{daveg@@synaptics.com}. It is a total rewrite of the original +1986 @file{cl.el} package by Cesar Quiroz. Most features of the +Quiroz package have been retained; any incompatibilities are +noted in the descriptions below. Care has been taken in this +version to ensure that each function is defined efficiently, +concisely, and with minimal impact on the rest of the Emacs +environment. + +@menu +* Usage:: How to use the CL package +* Organization:: The package's five component files +* Installation:: Compiling and installing CL +* Naming Conventions:: Notes on CL function names +@end menu + +@node Usage, Organization, Overview, Overview +@section Usage + +@noindent +Lisp code that uses features from the @dfn{CL} package should +include at the beginning: + +@example +(require 'cl) +@end example + +@noindent +If you want to ensure that the new (Gillespie) version of @dfn{CL} +is the one that is present, add an additional @code{(require 'cl-19)} +call: + +@example +(require 'cl) +(require 'cl-19) +@end example + +@noindent +The second call will fail (with ``@file{cl-19.el} not found'') if +the old @file{cl.el} package was in use. + +It is safe to arrange to load @dfn{CL} at all times, e.g., +in your @file{.emacs} file. But it's a good idea, for portability, +to @code{(require 'cl)} in your code even if you do this. + +@node Organization, Installation, Usage, Overview +@section Organization + +@noindent +The Common Lisp package is organized into four files: + +@table @file +@item cl.el +This is the ``main'' file, which contains basic functions +and information about the package. This file is relatively +compact---about 700 lines. + +@item cl-extra.el +This file contains the larger, more complex or unusual functions. +It is kept separate so that packages which only want to use Common +Lisp fundamentals like the @code{cadr} function won't need to pay +the overhead of loading the more advanced functions. + +@item cl-seq.el +This file contains most of the advanced functions for operating +on sequences or lists, such as @code{delete-if} and @code{assoc*}. + +@item cl-macs.el +This file contains the features of the packages which are macros +instead of functions. Macros expand when the caller is compiled, +not when it is run, so the macros generally only need to be +present when the byte-compiler is running (or when the macros are +used in uncompiled code such as a @file{.emacs} file). Most of +the macros of this package are isolated in @file{cl-macs.el} so +that they won't take up memory unless you are compiling. +@end table + +The file @file{cl.el} includes all necessary @code{autoload} +commands for the functions and macros in the other three files. +All you have to do is @code{(require 'cl)}, and @file{cl.el} +will take care of pulling in the other files when they are +needed. + +There is another file, @file{cl-compat.el}, which defines some +routines from the older @file{cl.el} package that are no longer +present in the new package. This includes internal routines +like @code{setelt} and @code{zip-lists}, deprecated features +like @code{defkeyword}, and an emulation of the old-style +multiple-values feature. @xref{Old CL Compatibility}. + +@node Installation, Naming Conventions, Organization, Overview +@section Installation + +@noindent +Installation of the @dfn{CL} package is simple: Just put the +byte-compiled files @file{cl.elc}, @file{cl-extra.elc}, +@file{cl-seq.elc}, @file{cl-macs.elc}, and @file{cl-compat.elc} +into a directory on your @code{load-path}. + +There are no special requirements to compile this package: +The files do not have to be loaded before they are compiled, +nor do they need to be compiled in any particular order. + +You may choose to put the files into your main @file{lisp/} +directory, replacing the original @file{cl.el} file there. Or, +you could put them into a directory that comes before @file{lisp/} +on your @code{load-path} so that the old @file{cl.el} is +effectively hidden. + +Also, format the @file{cl.texinfo} file and put the resulting +Info files in the @file{info/} directory or another suitable place. + +You may instead wish to leave this package's components all in +their own directory, and then add this directory to your +@code{load-path} and @code{Info-directory-list}. +Add the directory to the front of the list so the old @dfn{CL} +package and its documentation are hidden. + +@node Naming Conventions, , Installation, Overview +@section Naming Conventions + +@noindent +Except where noted, all functions defined by this package have the +same names and calling conventions as their Common Lisp counterparts. + +Following is a complete list of functions whose names were changed +from Common Lisp, usually to avoid conflicts with Emacs. In each +case, a @samp{*} has been appended to the Common Lisp name to obtain +the Emacs name: + +@example +defun* defsubst* defmacro* function* +member* assoc* rassoc* get* +remove* delete* mapcar* sort* +floor* ceiling* truncate* round* +mod* rem* random* +@end example + +Internal function and variable names in the package are prefixed +by @code{cl-}. Here is a complete list of functions @emph{not} +prefixed by @code{cl-} which were not taken from Common Lisp: + +@example +floatp-safe lexical-let lexical-let* +callf callf2 letf letf* +defsubst* +@end example + +The following simple functions and macros are defined in @file{cl.el}; +they do not cause other components like @file{cl-extra} to be loaded. + +@example +eql floatp-safe endp +evenp oddp plusp minusp +caaar .. cddddr +list* ldiff rest first .. tenth +copy-list subst mapcar* [2] +adjoin [3] acons pairlis pop [4] +push [4] pushnew [3,4] incf [4] decf [4] +proclaim declaim +@end example + +@noindent +[2] Only for one sequence argument or two list arguments. + +@noindent +[3] Only if @code{:test} is @code{eq}, @code{equal}, or unspecified, +and @code{:key} is not used. + +@noindent +[4] Only when @var{place} is a plain variable name. + +@iftex +@chapno=4 +@end iftex + +@node Program Structure, Predicates, Overview, Top +@chapter Program Structure + +@noindent +This section describes features of the @dfn{CL} package which have to +do with programs as a whole: advanced argument lists for functions, +and the @code{eval-when} construct. + +@menu +* Argument Lists:: `&key', `&aux', `defun*', `defmacro*'. +* Time of Evaluation:: The `eval-when' construct. +@end menu + +@iftex +@secno=1 +@end iftex + +@node Argument Lists, Time of Evaluation, Program Structure, Program Structure +@section Argument Lists + +@noindent +Emacs Lisp's notation for argument lists of functions is a subset of +the Common Lisp notation. As well as the familiar @code{&optional} +and @code{&rest} markers, Common Lisp allows you to specify default +values for optional arguments, and it provides the additional markers +@code{&key} and @code{&aux}. + +Since argument parsing is built-in to Emacs, there is no way for +this package to implement Common Lisp argument lists seamlessly. +Instead, this package defines alternates for several Lisp forms +which you must use if you need Common Lisp argument lists. + +@defspec defun* name arglist body... +This form is identical to the regular @code{defun} form, except +that @var{arglist} is allowed to be a full Common Lisp argument +list. Also, the function body is enclosed in an implicit block +called @var{name}; @pxref{Blocks and Exits}. +@end defspec + +@defspec defsubst* name arglist body... +This is just like @code{defun*}, except that the function that +is defined is automatically proclaimed @code{inline}, i.e., +calls to it may be expanded into in-line code by the byte compiler. +This is analogous to the @code{defsubst} form; +@code{defsubst*} uses a different method (compiler macros) which +works in all version of Emacs, and also generates somewhat more +efficient inline expansions. In particular, @code{defsubst*} +arranges for the processing of keyword arguments, default values, +etc., to be done at compile-time whenever possible. +@end defspec + +@defspec defmacro* name arglist body... +This is identical to the regular @code{defmacro} form, +except that @var{arglist} is allowed to be a full Common Lisp +argument list. The @code{&environment} keyword is supported as +described in Steele. The @code{&whole} keyword is supported only +within destructured lists (see below); top-level @code{&whole} +cannot be implemented with the current Emacs Lisp interpreter. +The macro expander body is enclosed in an implicit block called +@var{name}. +@end defspec + +@defspec function* symbol-or-lambda +This is identical to the regular @code{function} form, +except that if the argument is a @code{lambda} form then that +form may use a full Common Lisp argument list. +@end defspec + +Also, all forms (such as @code{defsetf} and @code{flet}) defined +in this package that include @var{arglist}s in their syntax allow +full Common Lisp argument lists. + +Note that it is @emph{not} necessary to use @code{defun*} in +order to have access to most @dfn{CL} features in your function. +These features are always present; @code{defun*}'s only +difference from @code{defun} is its more flexible argument +lists and its implicit block. + +The full form of a Common Lisp argument list is + +@example +(@var{var}... + &optional (@var{var} @var{initform} @var{svar})... + &rest @var{var} + &key ((@var{keyword} @var{var}) @var{initform} @var{svar})... + &aux (@var{var} @var{initform})...) +@end example + +Each of the five argument list sections is optional. The @var{svar}, +@var{initform}, and @var{keyword} parts are optional; if they are +omitted, then @samp{(@var{var})} may be written simply @samp{@var{var}}. + +The first section consists of zero or more @dfn{required} arguments. +These arguments must always be specified in a call to the function; +there is no difference between Emacs Lisp and Common Lisp as far as +required arguments are concerned. + +The second section consists of @dfn{optional} arguments. These +arguments may be specified in the function call; if they are not, +@var{initform} specifies the default value used for the argument. +(No @var{initform} means to use @code{nil} as the default.) The +@var{initform} is evaluated with the bindings for the preceding +arguments already established; @code{(a &optional (b (1+ a)))} +matches one or two arguments, with the second argument defaulting +to one plus the first argument. If the @var{svar} is specified, +it is an auxiliary variable which is bound to @code{t} if the optional +argument was specified, or to @code{nil} if the argument was omitted. +If you don't use an @var{svar}, then there will be no way for your +function to tell whether it was called with no argument, or with +the default value passed explicitly as an argument. + +The third section consists of a single @dfn{rest} argument. If +more arguments were passed to the function than are accounted for +by the required and optional arguments, those extra arguments are +collected into a list and bound to the ``rest'' argument variable. +Common Lisp's @code{&rest} is equivalent to that of Emacs Lisp. +Common Lisp accepts @code{&body} as a synonym for @code{&rest} in +macro contexts; this package accepts it all the time. + +The fourth section consists of @dfn{keyword} arguments. These +are optional arguments which are specified by name rather than +positionally in the argument list. For example, + +@example +(defun* foo (a &optional b &key c d (e 17))) +@end example + +@noindent +defines a function which may be called with one, two, or more +arguments. The first two arguments are bound to @code{a} and +@code{b} in the usual way. The remaining arguments must be +pairs of the form @code{:c}, @code{:d}, or @code{:e} followed +by the value to be bound to the corresponding argument variable. +(Symbols whose names begin with a colon are called @dfn{keywords}, +and they are self-quoting in the same way as @code{nil} and +@code{t}.) + +For example, the call @code{(foo 1 2 :d 3 :c 4)} sets the five +arguments to 1, 2, 4, 3, and 17, respectively. If the same keyword +appears more than once in the function call, the first occurrence +takes precedence over the later ones. Note that it is not possible +to specify keyword arguments without specifying the optional +argument @code{b} as well, since @code{(foo 1 :c 2)} would bind +@code{b} to the keyword @code{:c}, then signal an error because +@code{2} is not a valid keyword. + +If a @var{keyword} symbol is explicitly specified in the argument +list as shown in the above diagram, then that keyword will be +used instead of just the variable name prefixed with a colon. +You can specify a @var{keyword} symbol which does not begin with +a colon at all, but such symbols will not be self-quoting; you +will have to quote them explicitly with an apostrophe in the +function call. + +Ordinarily it is an error to pass an unrecognized keyword to +a function, e.g., @code{(foo 1 2 :c 3 :goober 4)}. You can ask +Lisp to ignore unrecognized keywords, either by adding the +marker @code{&allow-other-keys} after the keyword section +of the argument list, or by specifying an @code{:allow-other-keys} +argument in the call whose value is non-@code{nil}. If the +function uses both @code{&rest} and @code{&key} at the same time, +the ``rest'' argument is bound to the keyword list as it appears +in the call. For example: + +@smallexample +(defun* find-thing (thing &rest rest &key need &allow-other-keys) + (or (apply 'member* thing thing-list :allow-other-keys t rest) + (if need (error "Thing not found")))) +@end smallexample + +@noindent +This function takes a @code{:need} keyword argument, but also +accepts other keyword arguments which are passed on to the +@code{member*} function. @code{allow-other-keys} is used to +keep both @code{find-thing} and @code{member*} from complaining +about each others' keywords in the arguments. + +The fifth section of the argument list consists of @dfn{auxiliary +variables}. These are not really arguments at all, but simply +variables which are bound to @code{nil} or to the specified +@var{initforms} during execution of the function. There is no +difference between the following two functions, except for a +matter of stylistic taste: + +@example +(defun* foo (a b &aux (c (+ a b)) d) + @var{body}) + +(defun* foo (a b) + (let ((c (+ a b)) d) + @var{body})) +@end example + +Argument lists support @dfn{destructuring}. In Common Lisp, +destructuring is only allowed with @code{defmacro}; this package +allows it with @code{defun*} and other argument lists as well. +In destructuring, any argument variable (@var{var} in the above +diagram) can be replaced by a list of variables, or more generally, +a recursive argument list. The corresponding argument value must +be a list whose elements match this recursive argument list. +For example: + +@example +(defmacro* dolist ((var listform &optional resultform) + &rest body) + ...) +@end example + +This says that the first argument of @code{dolist} must be a list +of two or three items; if there are other arguments as well as this +list, they are stored in @code{body}. All features allowed in +regular argument lists are allowed in these recursive argument lists. +In addition, the clause @samp{&whole @var{var}} is allowed at the +front of a recursive argument list. It binds @var{var} to the +whole list being matched; thus @code{(&whole all a b)} matches +a list of two things, with @code{a} bound to the first thing, +@code{b} bound to the second thing, and @code{all} bound to the +list itself. (Common Lisp allows @code{&whole} in top-level +@code{defmacro} argument lists as well, but Emacs Lisp does not +support this usage.) + +One last feature of destructuring is that the argument list may be +dotted, so that the argument list @code{(a b . c)} is functionally +equivalent to @code{(a b &rest c)}. + +If the optimization quality @code{safety} is set to 0 +(@pxref{Declarations}), error checking for wrong number of +arguments and invalid keyword arguments is disabled. By default, +argument lists are rigorously checked. + +@node Time of Evaluation, , Argument Lists, Program Structure +@section Time of Evaluation + +@noindent +Normally, the byte-compiler does not actually execute the forms in +a file it compiles. For example, if a file contains @code{(setq foo t)}, +the act of compiling it will not actually set @code{foo} to @code{t}. +This is true even if the @code{setq} was a top-level form (i.e., not +enclosed in a @code{defun} or other form). Sometimes, though, you +would like to have certain top-level forms evaluated at compile-time. +For example, the compiler effectively evaluates @code{defmacro} forms +at compile-time so that later parts of the file can refer to the +macros that are defined. + +@defspec eval-when (situations...) forms... +This form controls when the body @var{forms} are evaluated. +The @var{situations} list may contain any set of the symbols +@code{compile}, @code{load}, and @code{eval} (or their long-winded +ANSI equivalents, @code{:compile-toplevel}, @code{:load-toplevel}, +and @code{:execute}). + +The @code{eval-when} form is handled differently depending on +whether or not it is being compiled as a top-level form. +Specifically, it gets special treatment if it is being compiled +by a command such as @code{byte-compile-file} which compiles files +or buffers of code, and it appears either literally at the +top level of the file or inside a top-level @code{progn}. + +For compiled top-level @code{eval-when}s, the body @var{forms} are +executed at compile-time if @code{compile} is in the @var{situations} +list, and the @var{forms} are written out to the file (to be executed +at load-time) if @code{load} is in the @var{situations} list. + +For non-compiled-top-level forms, only the @code{eval} situation is +relevant. (This includes forms executed by the interpreter, forms +compiled with @code{byte-compile} rather than @code{byte-compile-file}, +and non-top-level forms.) The @code{eval-when} acts like a +@code{progn} if @code{eval} is specified, and like @code{nil} +(ignoring the body @var{forms}) if not. + +The rules become more subtle when @code{eval-when}s are nested; +consult Steele (second edition) for the gruesome details (and +some gruesome examples). + +Some simple examples: + +@example +;; Top-level forms in foo.el: +(eval-when (compile) (setq foo1 'bar)) +(eval-when (load) (setq foo2 'bar)) +(eval-when (compile load) (setq foo3 'bar)) +(eval-when (eval) (setq foo4 'bar)) +(eval-when (eval compile) (setq foo5 'bar)) +(eval-when (eval load) (setq foo6 'bar)) +(eval-when (eval compile load) (setq foo7 'bar)) +@end example + +When @file{foo.el} is compiled, these variables will be set during +the compilation itself: + +@example +foo1 foo3 foo5 foo7 ; `compile' +@end example + +When @file{foo.elc} is loaded, these variables will be set: + +@example +foo2 foo3 foo6 foo7 ; `load' +@end example + +And if @file{foo.el} is loaded uncompiled, these variables will +be set: + +@example +foo4 foo5 foo6 foo7 ; `eval' +@end example + +If these seven @code{eval-when}s had been, say, inside a @code{defun}, +then the first three would have been equivalent to @code{nil} and the +last four would have been equivalent to the corresponding @code{setq}s. + +Note that @code{(eval-when (load eval) @dots{})} is equivalent +to @code{(progn @dots{})} in all contexts. The compiler treats +certain top-level forms, like @code{defmacro} (sort-of) and +@code{require}, as if they were wrapped in @code{(eval-when +(compile load eval) @dots{})}. +@end defspec + +Emacs includes two special forms related to @code{eval-when}. +One of these, @code{eval-when-compile}, is not quite equivalent to +any @code{eval-when} construct and is described below. + +The other form, @code{(eval-and-compile @dots{})}, is exactly +equivalent to @samp{(eval-when (compile load eval) @dots{})} and +so is not itself defined by this package. + +@defspec eval-when-compile forms... +The @var{forms} are evaluated at compile-time; at execution time, +this form acts like a quoted constant of the resulting value. Used +at top-level, @code{eval-when-compile} is just like @samp{eval-when +(compile eval)}. In other contexts, @code{eval-when-compile} +allows code to be evaluated once at compile-time for efficiency +or other reasons. + +This form is similar to the @samp{#.} syntax of true Common Lisp. +@end defspec + +@defspec load-time-value form +The @var{form} is evaluated at load-time; at execution time, +this form acts like a quoted constant of the resulting value. + +Early Common Lisp had a @samp{#,} syntax that was similar to +this, but ANSI Common Lisp replaced it with @code{load-time-value} +and gave it more well-defined semantics. + +In a compiled file, @code{load-time-value} arranges for @var{form} +to be evaluated when the @file{.elc} file is loaded and then used +as if it were a quoted constant. In code compiled by +@code{byte-compile} rather than @code{byte-compile-file}, the +effect is identical to @code{eval-when-compile}. In uncompiled +code, both @code{eval-when-compile} and @code{load-time-value} +act exactly like @code{progn}. + +@example +(defun report () + (insert "This function was executed on: " + (current-time-string) + ", compiled on: " + (eval-when-compile (current-time-string)) + ;; or '#.(current-time-string) in real Common Lisp + ", and loaded on: " + (load-time-value (current-time-string)))) +@end example + +@noindent +Byte-compiled, the above defun will result in the following code +(or its compiled equivalent, of course) in the @file{.elc} file: + +@example +(setq --temp-- (current-time-string)) +(defun report () + (insert "This function was executed on: " + (current-time-string) + ", compiled on: " + '"Wed Jun 23 18:33:43 1993" + ", and loaded on: " + --temp--)) +@end example +@end defspec + +@node Predicates, Control Structure, Program Structure, Top +@chapter Predicates + +@noindent +This section describes functions for testing whether various +facts are true or false. + +@menu +* Type Predicates:: `typep', `deftype', and `coerce' +* Equality Predicates:: `eql' and `equalp' +@end menu + +@node Type Predicates, Equality Predicates, Predicates, Predicates +@section Type Predicates + +@noindent +The @dfn{CL} package defines a version of the Common Lisp @code{typep} +predicate. + +@defun typep object type +Check if @var{object} is of type @var{type}, where @var{type} is a +(quoted) type name of the sort used by Common Lisp. For example, +@code{(typep foo 'integer)} is equivalent to @code{(integerp foo)}. +@end defun + +The @var{type} argument to the above function is either a symbol +or a list beginning with a symbol. + +@itemize @bullet +@item +If the type name is a symbol, Emacs appends @samp{-p} to the +symbol name to form the name of a predicate function for testing +the type. (Built-in predicates whose names end in @samp{p} rather +than @samp{-p} are used when appropriate.) + +@item +The type symbol @code{t} stands for the union of all types. +@code{(typep @var{object} t)} is always true. Likewise, the +type symbol @code{nil} stands for nothing at all, and +@code{(typep @var{object} nil)} is always false. + +@item +The type symbol @code{null} represents the symbol @code{nil}. +Thus @code{(typep @var{object} 'null)} is equivalent to +@code{(null @var{object})}. + +@item +The type symbol @code{atom} represents all objects that are not cons +cells. Thus @code{(typep @var{object} 'atom)} is equivalent to +@code{(atom @var{object})}. + +@item +The type symbol @code{real} is a synonym for @code{number}, and +@code{fixnum} is a synonym for @code{integer}. + +@item +The type symbols @code{character} and @code{string-char} match +integers in the range from 0 to 255. + +@item +The type symbol @code{float} uses the @code{floatp-safe} predicate +defined by this package rather than @code{floatp}, so it will work +correctly even in Emacs versions without floating-point support. + +@item +The type list @code{(integer @var{low} @var{high})} represents all +integers between @var{low} and @var{high}, inclusive. Either bound +may be a list of a single integer to specify an exclusive limit, +or a @code{*} to specify no limit. The type @code{(integer * *)} +is thus equivalent to @code{integer}. + +@item +Likewise, lists beginning with @code{float}, @code{real}, or +@code{number} represent numbers of that type falling in a particular +range. + +@item +Lists beginning with @code{and}, @code{or}, and @code{not} form +combinations of types. For example, @code{(or integer (float 0 *))} +represents all objects that are integers or non-negative floats. + +@item +Lists beginning with @code{member} or @code{member*} represent +objects @code{eql} to any of the following values. For example, +@code{(member 1 2 3 4)} is equivalent to @code{(integer 1 4)}, +and @code{(member nil)} is equivalent to @code{null}. + +@item +Lists of the form @code{(satisfies @var{predicate})} represent +all objects for which @var{predicate} returns true when called +with that object as an argument. +@end itemize + +The following function and macro (not technically predicates) are +related to @code{typep}. + +@defun coerce object type +This function attempts to convert @var{object} to the specified +@var{type}. If @var{object} is already of that type as determined by +@code{typep}, it is simply returned. Otherwise, certain types of +conversions will be made: If @var{type} is any sequence type +(@code{string}, @code{list}, etc.) then @var{object} will be +converted to that type if possible. If @var{type} is +@code{character}, then strings of length one and symbols with +one-character names can be coerced. If @var{type} is @code{float}, +then integers can be coerced in versions of Emacs that support +floats. In all other circumstances, @code{coerce} signals an +error. +@end defun + +@defspec deftype name arglist forms... +This macro defines a new type called @var{name}. It is similar +to @code{defmacro} in many ways; when @var{name} is encountered +as a type name, the body @var{forms} are evaluated and should +return a type specifier that is equivalent to the type. The +@var{arglist} is a Common Lisp argument list of the sort accepted +by @code{defmacro*}. The type specifier @samp{(@var{name} @var{args}...)} +is expanded by calling the expander with those arguments; the type +symbol @samp{@var{name}} is expanded by calling the expander with +no arguments. The @var{arglist} is processed the same as for +@code{defmacro*} except that optional arguments without explicit +defaults use @code{*} instead of @code{nil} as the ``default'' +default. Some examples: + +@example +(deftype null () '(satisfies null)) ; predefined +(deftype list () '(or null cons)) ; predefined +(deftype unsigned-byte (&optional bits) + (list 'integer 0 (if (eq bits '*) bits (1- (lsh 1 bits))))) +(unsigned-byte 8) @equiv{} (integer 0 255) +(unsigned-byte) @equiv{} (integer 0 *) +unsigned-byte @equiv{} (integer 0 *) +@end example + +@noindent +The last example shows how the Common Lisp @code{unsigned-byte} +type specifier could be implemented if desired; this package does +not implement @code{unsigned-byte} by default. +@end defspec + +The @code{typecase} and @code{check-type} macros also use type +names. @xref{Conditionals}. @xref{Assertions}. The @code{map}, +@code{concatenate}, and @code{merge} functions take type-name +arguments to specify the type of sequence to return. @xref{Sequences}. + +@node Equality Predicates, , Type Predicates, Predicates +@section Equality Predicates + +@noindent +This package defines two Common Lisp predicates, @code{eql} and +@code{equalp}. + +@defun eql a b +This function is almost the same as @code{eq}, except that if @var{a} +and @var{b} are numbers of the same type, it compares them for numeric +equality (as if by @code{equal} instead of @code{eq}). This makes a +difference only for versions of Emacs that are compiled with +floating-point support. Emacs floats are allocated +objects just like cons cells, which means that @code{(eq 3.0 3.0)} +will not necessarily be true---if the two @code{3.0}s were allocated +separately, the pointers will be different even though the numbers are +the same. But @code{(eql 3.0 3.0)} will always be true. + +The types of the arguments must match, so @code{(eql 3 3.0)} is +still false. + +Note that Emacs integers are ``direct'' rather than allocated, which +basically means @code{(eq 3 3)} will always be true. Thus @code{eq} +and @code{eql} behave differently only if floating-point numbers are +involved, and are indistinguishable on Emacs versions that don't +support floats. + +There is a slight inconsistency with Common Lisp in the treatment of +positive and negative zeros. Some machines, notably those with IEEE +standard arithmetic, represent @code{+0} and @code{-0} as distinct +values. Normally this doesn't matter because the standard specifies +that @code{(= 0.0 -0.0)} should always be true, and this is indeed +what Emacs Lisp and Common Lisp do. But the Common Lisp standard +states that @code{(eql 0.0 -0.0)} and @code{(equal 0.0 -0.0)} should +be false on IEEE-like machines; Emacs Lisp does not do this, and in +fact the only known way to distinguish between the two zeros in Emacs +Lisp is to @code{format} them and check for a minus sign. +@end defun + +@defun equalp a b +This function is a more flexible version of @code{equal}. In +particular, it compares strings case-insensitively, and it compares +numbers without regard to type (so that @code{(equalp 3 3.0)} is +true). Vectors and conses are compared recursively. All other +objects are compared as if by @code{equal}. + +This function differs from Common Lisp @code{equalp} in several +respects. First, Common Lisp's @code{equalp} also compares +@emph{characters} case-insensitively, which would be impractical +in this package since Emacs does not distinguish between integers +and characters. In keeping with the idea that strings are less +vector-like in Emacs Lisp, this package's @code{equalp} also will +not compare strings against vectors of integers. +@end defun + +Also note that the Common Lisp functions @code{member} and @code{assoc} +use @code{eql} to compare elements, whereas Emacs Lisp follows the +MacLisp tradition and uses @code{equal} for these two functions. +In Emacs, use @code{member*} and @code{assoc*} to get functions +which use @code{eql} for comparisons. + +@node Control Structure, Macros, Predicates, Top +@chapter Control Structure + +@noindent +The features described in the following sections implement +various advanced control structures, including the powerful +@code{setf} facility and a number of looping and conditional +constructs. + +@menu +* Assignment:: The `psetq' form +* Generalized Variables:: `setf', `incf', `push', etc. +* Variable Bindings:: `progv', `lexical-let', `flet', `macrolet' +* Conditionals:: `case', `typecase' +* Blocks and Exits:: `block', `return', `return-from' +* Iteration:: `do', `dotimes', `dolist', `do-symbols' +* Loop Facility:: The Common Lisp `loop' macro +* Multiple Values:: `values', `multiple-value-bind', etc. +@end menu + +@node Assignment, Generalized Variables, Control Structure, Control Structure +@section Assignment + +@noindent +The @code{psetq} form is just like @code{setq}, except that multiple +assignments are done in parallel rather than sequentially. + +@defspec psetq [symbol form]@dots{} +This special form (actually a macro) is used to assign to several +variables simultaneously. Given only one @var{symbol} and @var{form}, +it has the same effect as @code{setq}. Given several @var{symbol} +and @var{form} pairs, it evaluates all the @var{form}s in advance +and then stores the corresponding variables afterwards. + +@example +(setq x 2 y 3) +(setq x (+ x y) y (* x y)) +x + @result{} 5 +y ; @r{@code{y} was computed after @code{x} was set.} + @result{} 15 +(setq x 2 y 3) +(psetq x (+ x y) y (* x y)) +x + @result{} 5 +y ; @r{@code{y} was computed before @code{x} was set.} + @result{} 6 +@end example + +The simplest use of @code{psetq} is @code{(psetq x y y x)}, which +exchanges the values of two variables. (The @code{rotatef} form +provides an even more convenient way to swap two variables; +@pxref{Modify Macros}.) + +@code{psetq} always returns @code{nil}. +@end defspec + +@node Generalized Variables, Variable Bindings, Assignment, Control Structure +@section Generalized Variables + +@noindent +A ``generalized variable'' or ``place form'' is one of the many places +in Lisp memory where values can be stored. The simplest place form is +a regular Lisp variable. But the cars and cdrs of lists, elements +of arrays, properties of symbols, and many other locations are also +places where Lisp values are stored. + +The @code{setf} form is like @code{setq}, except that it accepts +arbitrary place forms on the left side rather than just +symbols. For example, @code{(setf (car a) b)} sets the car of +@code{a} to @code{b}, doing the same operation as @code{(setcar a b)} +but without having to remember two separate functions for setting +and accessing every type of place. + +Generalized variables are analogous to ``lvalues'' in the C +language, where @samp{x = a[i]} gets an element from an array +and @samp{a[i] = x} stores an element using the same notation. +Just as certain forms like @code{a[i]} can be lvalues in C, there +is a set of forms that can be generalized variables in Lisp. + +@menu +* Basic Setf:: `setf' and place forms +* Modify Macros:: `incf', `push', `rotatef', `letf', `callf', etc. +* Customizing Setf:: `define-modify-macro', `defsetf', `define-setf-method' +@end menu + +@node Basic Setf, Modify Macros, Generalized Variables, Generalized Variables +@subsection Basic Setf + +@noindent +The @code{setf} macro is the most basic way to operate on generalized +variables. + +@defspec setf [place form]@dots{} +This macro evaluates @var{form} and stores it in @var{place}, which +must be a valid generalized variable form. If there are several +@var{place} and @var{form} pairs, the assignments are done sequentially +just as with @code{setq}. @code{setf} returns the value of the last +@var{form}. + +The following Lisp forms will work as generalized variables, and +so may appear in the @var{place} argument of @code{setf}: + +@itemize @bullet +@item +A symbol naming a variable. In other words, @code{(setf x y)} is +exactly equivalent to @code{(setq x y)}, and @code{setq} itself is +strictly speaking redundant now that @code{setf} exists. Many +programmers continue to prefer @code{setq} for setting simple +variables, though, purely for stylistic or historical reasons. +The macro @code{(setf x y)} actually expands to @code{(setq x y)}, +so there is no performance penalty for using it in compiled code. + +@item +A call to any of the following Lisp functions: + +@smallexample +car cdr caar .. cddddr +nth rest first .. tenth +aref elt nthcdr +symbol-function symbol-value symbol-plist +get get* getf +gethash subseq +@end smallexample + +@noindent +Note that for @code{nthcdr} and @code{getf}, the list argument +of the function must itself be a valid @var{place} form. For +example, @code{(setf (nthcdr 0 foo) 7)} will set @code{foo} itself +to 7. Note that @code{push} and @code{pop} on an @code{nthcdr} +place can be used to insert or delete at any position in a list. +The use of @code{nthcdr} as a @var{place} form is an extension +to standard Common Lisp. + +@item +The following Emacs-specific functions are also @code{setf}-able. + +@smallexample +buffer-file-name marker-position +buffer-modified-p match-data +buffer-name mouse-position +buffer-string overlay-end +buffer-substring overlay-get +current-buffer overlay-start +current-case-table point +current-column point-marker +current-global-map point-max +current-input-mode point-min +current-local-map process-buffer +current-window-configuration process-filter +default-file-modes process-sentinel +default-value read-mouse-position +documentation-property screen-height +extent-data screen-menubar +extent-end-position screen-width +extent-start-position selected-window +face-background selected-screen +face-background-pixmap selected-frame +face-font standard-case-table +face-foreground syntax-table +face-underline-p window-buffer +file-modes window-dedicated-p +frame-height window-display-table +frame-parameters window-height +frame-visible-p window-hscroll +frame-width window-point +get-register window-start +getenv window-width +global-key-binding x-get-cut-buffer +keymap-parent x-get-cutbuffer +local-key-binding x-get-secondary-selection +mark x-get-selection +mark-marker +@end smallexample + +Most of these have directly corresponding ``set'' functions, like +@code{use-local-map} for @code{current-local-map}, or @code{goto-char} +for @code{point}. A few, like @code{point-min}, expand to longer +sequences of code when they are @code{setf}'d (@code{(narrow-to-region +x (point-max))} in this case). + +@item +A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])}, +where @var{subplace} is itself a valid generalized variable whose +current value is a string, and where the value stored is also a +string. The new string is spliced into the specified part of the +destination string. For example: + +@example +(setq a (list "hello" "world")) + @result{} ("hello" "world") +(cadr a) + @result{} "world" +(substring (cadr a) 2 4) + @result{} "rl" +(setf (substring (cadr a) 2 4) "o") + @result{} "o" +(cadr a) + @result{} "wood" +a + @result{} ("hello" "wood") +@end example + +The generalized variable @code{buffer-substring}, listed above, +also works in this way by replacing a portion of the current buffer. + +@item +A call of the form @code{(apply '@var{func} @dots{})} or +@code{(apply (function @var{func}) @dots{})}, where @var{func} +is a @code{setf}-able function whose store function is ``suitable'' +in the sense described in Steele's book; since none of the standard +Emacs place functions are suitable in this sense, this feature is +only interesting when used with places you define yourself with +@code{define-setf-method} or the long form of @code{defsetf}. + +@item +A macro call, in which case the macro is expanded and @code{setf} +is applied to the resulting form. + +@item +Any form for which a @code{defsetf} or @code{define-setf-method} +has been made. +@end itemize + +Using any forms other than these in the @var{place} argument to +@code{setf} will signal an error. + +The @code{setf} macro takes care to evaluate all subforms in +the proper left-to-right order; for example, + +@example +(setf (aref vec (incf i)) i) +@end example + +@noindent +looks like it will evaluate @code{(incf i)} exactly once, before the +following access to @code{i}; the @code{setf} expander will insert +temporary variables as necessary to ensure that it does in fact work +this way no matter what setf-method is defined for @code{aref}. +(In this case, @code{aset} would be used and no such steps would +be necessary since @code{aset} takes its arguments in a convenient +order.) + +However, if the @var{place} form is a macro which explicitly +evaluates its arguments in an unusual order, this unusual order +will be preserved. Adapting an example from Steele, given + +@example +(defmacro wrong-order (x y) (list 'aref y x)) +@end example + +@noindent +the form @code{(setf (wrong-order @var{a} @var{b}) 17)} will +evaluate @var{b} first, then @var{a}, just as in an actual call +to @code{wrong-order}. +@end defspec + +@node Modify Macros, Customizing Setf, Basic Setf, Generalized Variables +@subsection Modify Macros + +@noindent +This package defines a number of other macros besides @code{setf} +that operate on generalized variables. Many are interesting and +useful even when the @var{place} is just a variable name. + +@defspec psetf [place form]@dots{} +This macro is to @code{setf} what @code{psetq} is to @code{setq}: +When several @var{place}s and @var{form}s are involved, the +assignments take place in parallel rather than sequentially. +Specifically, all subforms are evaluated from left to right, then +all the assignments are done (in an undefined order). +@end defspec + +@defspec incf place &optional x +This macro increments the number stored in @var{place} by one, or +by @var{x} if specified. The incremented value is returned. For +example, @code{(incf i)} is equivalent to @code{(setq i (1+ i))}, and +@code{(incf (car x) 2)} is equivalent to @code{(setcar x (+ (car x) 2))}. + +Once again, care is taken to preserve the ``apparent'' order of +evaluation. For example, + +@example +(incf (aref vec (incf i))) +@end example + +@noindent +appears to increment @code{i} once, then increment the element of +@code{vec} addressed by @code{i}; this is indeed exactly what it +does, which means the above form is @emph{not} equivalent to the +``obvious'' expansion, + +@example +(setf (aref vec (incf i)) (1+ (aref vec (incf i)))) ; Wrong! +@end example + +@noindent +but rather to something more like + +@example +(let ((temp (incf i))) + (setf (aref vec temp) (1+ (aref vec temp)))) +@end example + +@noindent +Again, all of this is taken care of automatically by @code{incf} and +the other generalized-variable macros. + +As a more Emacs-specific example of @code{incf}, the expression +@code{(incf (point) @var{n})} is essentially equivalent to +@code{(forward-char @var{n})}. +@end defspec + +@defspec decf place &optional x +This macro decrements the number stored in @var{place} by one, or +by @var{x} if specified. +@end defspec + +@defspec pop place +This macro removes and returns the first element of the list stored +in @var{place}. It is analogous to @code{(prog1 (car @var{place}) +(setf @var{place} (cdr @var{place})))}, except that it takes care +to evaluate all subforms only once. +@end defspec + +@defspec push x place +This macro inserts @var{x} at the front of the list stored in +@var{place}. It is analogous to @code{(setf @var{place} (cons +@var{x} @var{place}))}, except for evaluation of the subforms. +@end defspec + +@defspec pushnew x place @t{&key :test :test-not :key} +This macro inserts @var{x} at the front of the list stored in +@var{place}, but only if @var{x} was not @code{eql} to any +existing element of the list. The optional keyword arguments +are interpreted in the same way as for @code{adjoin}. +@xref{Lists as Sets}. +@end defspec + +@defspec shiftf place@dots{} newvalue +This macro shifts the @var{place}s left by one, shifting in the +value of @var{newvalue} (which may be any Lisp expression, not just +a generalized variable), and returning the value shifted out of +the first @var{place}. Thus, @code{(shiftf @var{a} @var{b} @var{c} +@var{d})} is equivalent to + +@example +(prog1 + @var{a} + (psetf @var{a} @var{b} + @var{b} @var{c} + @var{c} @var{d})) +@end example + +@noindent +except that the subforms of @var{a}, @var{b}, and @var{c} are actually +evaluated only once each and in the apparent order. +@end defspec + +@defspec rotatef place@dots{} +This macro rotates the @var{place}s left by one in circular fashion. +Thus, @code{(rotatef @var{a} @var{b} @var{c} @var{d})} is equivalent to + +@example +(psetf @var{a} @var{b} + @var{b} @var{c} + @var{c} @var{d} + @var{d} @var{a}) +@end example + +@noindent +except for the evaluation of subforms. @code{rotatef} always +returns @code{nil}. Note that @code{(rotatef @var{a} @var{b})} +conveniently exchanges @var{a} and @var{b}. +@end defspec + +The following macros were invented for this package; they have no +analogues in Common Lisp. + +@defspec letf (bindings@dots{}) forms@dots{} +This macro is analogous to @code{let}, but for generalized variables +rather than just symbols. Each @var{binding} should be of the form +@code{(@var{place} @var{value})}; the original contents of the +@var{place}s are saved, the @var{value}s are stored in them, and +then the body @var{form}s are executed. Afterwards, the @var{places} +are set back to their original saved contents. This cleanup happens +even if the @var{form}s exit irregularly due to a @code{throw} or an +error. + +For example, + +@example +(letf (((point) (point-min)) + (a 17)) + ...) +@end example + +@noindent +moves ``point'' in the current buffer to the beginning of the buffer, +and also binds @code{a} to 17 (as if by a normal @code{let}, since +@code{a} is just a regular variable). After the body exits, @code{a} +is set back to its original value and point is moved back to its +original position. + +Note that @code{letf} on @code{(point)} is not quite like a +@code{save-excursion}, as the latter effectively saves a marker +which tracks insertions and deletions in the buffer. Actually, +a @code{letf} of @code{(point-marker)} is much closer to this +behavior. (@code{point} and @code{point-marker} are equivalent +as @code{setf} places; each will accept either an integer or a +marker as the stored value.) + +Since generalized variables look like lists, @code{let}'s shorthand +of using @samp{foo} for @samp{(foo nil)} as a @var{binding} would +be ambiguous in @code{letf} and is not allowed. + +However, a @var{binding} specifier may be a one-element list +@samp{(@var{place})}, which is similar to @samp{(@var{place} +@var{place})}. In other words, the @var{place} is not disturbed +on entry to the body, and the only effect of the @code{letf} is +to restore the original value of @var{place} afterwards. (The +redundant access-and-store suggested by the @code{(@var{place} +@var{place})} example does not actually occur.) + +In most cases, the @var{place} must have a well-defined value on +entry to the @code{letf} form. The only exceptions are plain +variables and calls to @code{symbol-value} and @code{symbol-function}. +If the symbol is not bound on entry, it is simply made unbound by +@code{makunbound} or @code{fmakunbound} on exit. +@end defspec + +@defspec letf* (bindings@dots{}) forms@dots{} +This macro is to @code{letf} what @code{let*} is to @code{let}: +It does the bindings in sequential rather than parallel order. +@end defspec + +@defspec callf @var{function} @var{place} @var{args}@dots{} +This is the ``generic'' modify macro. It calls @var{function}, +which should be an unquoted function name, macro name, or lambda. +It passes @var{place} and @var{args} as arguments, and assigns the +result back to @var{place}. For example, @code{(incf @var{place} +@var{n})} is the same as @code{(callf + @var{place} @var{n})}. +Some more examples: + +@example +(callf abs my-number) +(callf concat (buffer-name) "<" (int-to-string n) ">") +(callf union happy-people (list joe bob) :test 'same-person) +@end example + +@xref{Customizing Setf}, for @code{define-modify-macro}, a way +to create even more concise notations for modify macros. Note +again that @code{callf} is an extension to standard Common Lisp. +@end defspec + +@defspec callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{} +This macro is like @code{callf}, except that @var{place} is +the @emph{second} argument of @var{function} rather than the +first. For example, @code{(push @var{x} @var{place})} is +equivalent to @code{(callf2 cons @var{x} @var{place})}. +@end defspec + +The @code{callf} and @code{callf2} macros serve as building +blocks for other macros like @code{incf}, @code{pushnew}, and +@code{define-modify-macro}. The @code{letf} and @code{letf*} +macros are used in the processing of symbol macros; +@pxref{Macro Bindings}. + +@node Customizing Setf, , Modify Macros, Generalized Variables +@subsection Customizing Setf + +@noindent +Common Lisp defines three macros, @code{define-modify-macro}, +@code{defsetf}, and @code{define-setf-method}, that allow the +user to extend generalized variables in various ways. + +@defspec define-modify-macro name arglist function [doc-string] +This macro defines a ``read-modify-write'' macro similar to +@code{incf} and @code{decf}. The macro @var{name} is defined +to take a @var{place} argument followed by additional arguments +described by @var{arglist}. The call + +@example +(@var{name} @var{place} @var{args}...) +@end example + +@noindent +will be expanded to + +@example +(callf @var{func} @var{place} @var{args}...) +@end example + +@noindent +which in turn is roughly equivalent to + +@example +(setf @var{place} (@var{func} @var{place} @var{args}...)) +@end example + +For example: + +@example +(define-modify-macro incf (&optional (n 1)) +) +(define-modify-macro concatf (&rest args) concat) +@end example + +Note that @code{&key} is not allowed in @var{arglist}, but +@code{&rest} is sufficient to pass keywords on to the function. + +Most of the modify macros defined by Common Lisp do not exactly +follow the pattern of @code{define-modify-macro}. For example, +@code{push} takes its arguments in the wrong order, and @code{pop} +is completely irregular. You can define these macros ``by hand'' +using @code{get-setf-method}, or consult the source file +@file{cl-macs.el} to see how to use the internal @code{setf} +building blocks. +@end defspec + +@defspec defsetf access-fn update-fn +This is the simpler of two @code{defsetf} forms. Where +@var{access-fn} is the name of a function which accesses a place, +this declares @var{update-fn} to be the corresponding store +function. From now on, + +@example +(setf (@var{access-fn} @var{arg1} @var{arg2} @var{arg3}) @var{value}) +@end example + +@noindent +will be expanded to + +@example +(@var{update-fn} @var{arg1} @var{arg2} @var{arg3} @var{value}) +@end example + +@noindent +The @var{update-fn} is required to be either a true function, or +a macro which evaluates its arguments in a function-like way. Also, +the @var{update-fn} is expected to return @var{value} as its result. +Otherwise, the above expansion would not obey the rules for the way +@code{setf} is supposed to behave. + +As a special (non-Common-Lisp) extension, a third argument of @code{t} +to @code{defsetf} says that the @code{update-fn}'s return value is +not suitable, so that the above @code{setf} should be expanded to +something more like + +@example +(let ((temp @var{value})) + (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} temp) + temp) +@end example + +Some examples of the use of @code{defsetf}, drawn from the standard +suite of setf methods, are: + +@example +(defsetf car setcar) +(defsetf symbol-value set) +(defsetf buffer-name rename-buffer t) +@end example +@end defspec + +@defspec defsetf access-fn arglist (store-var) forms@dots{} +This is the second, more complex, form of @code{defsetf}. It is +rather like @code{defmacro} except for the additional @var{store-var} +argument. The @var{forms} should return a Lisp form which stores +the value of @var{store-var} into the generalized variable formed +by a call to @var{access-fn} with arguments described by @var{arglist}. +The @var{forms} may begin with a string which documents the @code{setf} +method (analogous to the doc string that appears at the front of a +function). + +For example, the simple form of @code{defsetf} is shorthand for + +@example +(defsetf @var{access-fn} (&rest args) (store) + (append '(@var{update-fn}) args (list store))) +@end example + +The Lisp form that is returned can access the arguments from +@var{arglist} and @var{store-var} in an unrestricted fashion; +macros like @code{setf} and @code{incf} which invoke this +setf-method will insert temporary variables as needed to make +sure the apparent order of evaluation is preserved. + +Another example drawn from the standard package: + +@example +(defsetf nth (n x) (store) + (list 'setcar (list 'nthcdr n x) store)) +@end example +@end defspec + +@defspec define-setf-method access-fn arglist forms@dots{} +This is the most general way to create new place forms. When +a @code{setf} to @var{access-fn} with arguments described by +@var{arglist} is expanded, the @var{forms} are evaluated and +must return a list of five items: + +@enumerate +@item +A list of @dfn{temporary variables}. + +@item +A list of @dfn{value forms} corresponding to the temporary variables +above. The temporary variables will be bound to these value forms +as the first step of any operation on the generalized variable. + +@item +A list of exactly one @dfn{store variable} (generally obtained +from a call to @code{gensym}). + +@item +A Lisp form which stores the contents of the store variable into +the generalized variable, assuming the temporaries have been +bound as described above. + +@item +A Lisp form which accesses the contents of the generalized variable, +assuming the temporaries have been bound. +@end enumerate + +This is exactly like the Common Lisp macro of the same name, +except that the method returns a list of five values rather +than the five values themselves, since Emacs Lisp does not +support Common Lisp's notion of multiple return values. + +Once again, the @var{forms} may begin with a documentation string. + +A setf-method should be maximally conservative with regard to +temporary variables. In the setf-methods generated by +@code{defsetf}, the second return value is simply the list of +arguments in the place form, and the first return value is a +list of a corresponding number of temporary variables generated +by @code{gensym}. Macros like @code{setf} and @code{incf} which +use this setf-method will optimize away most temporaries that +turn out to be unnecessary, so there is little reason for the +setf-method itself to optimize. +@end defspec + +@defun get-setf-method place &optional env +This function returns the setf-method for @var{place}, by +invoking the definition previously recorded by @code{defsetf} +or @code{define-setf-method}. The result is a list of five +values as described above. You can use this function to build +your own @code{incf}-like modify macros. (Actually, it is +better to use the internal functions @code{cl-setf-do-modify} +and @code{cl-setf-do-store}, which are a bit easier to use and +which also do a number of optimizations; consult the source +code for the @code{incf} function for a simple example.) + +The argument @var{env} specifies the ``environment'' to be +passed on to @code{macroexpand} if @code{get-setf-method} should +need to expand a macro in @var{place}. It should come from +an @code{&environment} argument to the macro or setf-method +that called @code{get-setf-method}. + +See also the source code for the setf-methods for @code{apply} +and @code{substring}, each of which works by calling +@code{get-setf-method} on a simpler case, then massaging +the result in various ways. +@end defun + +Modern Common Lisp defines a second, independent way to specify +the @code{setf} behavior of a function, namely ``@code{setf} +functions'' whose names are lists @code{(setf @var{name})} +rather than symbols. For example, @code{(defun (setf foo) @dots{})} +defines the function that is used when @code{setf} is applied to +@code{foo}. This package does not currently support @code{setf} +functions. In particular, it is a compile-time error to use +@code{setf} on a form which has not already been @code{defsetf}'d +or otherwise declared; in newer Common Lisps, this would not be +an error since the function @code{(setf @var{func})} might be +defined later. + +@iftex +@secno=4 +@end iftex + +@node Variable Bindings, Conditionals, Generalized Variables, Control Structure +@section Variable Bindings + +@noindent +These Lisp forms make bindings to variables and function names, +analogous to Lisp's built-in @code{let} form. + +@xref{Modify Macros}, for the @code{letf} and @code{letf*} forms which +are also related to variable bindings. + +@menu +* Dynamic Bindings:: The `progv' form +* Lexical Bindings:: `lexical-let' and lexical closures +* Function Bindings:: `flet' and `labels' +* Macro Bindings:: `macrolet' and `symbol-macrolet' +@end menu + +@node Dynamic Bindings, Lexical Bindings, Variable Bindings, Variable Bindings +@subsection Dynamic Bindings + +@noindent +The standard @code{let} form binds variables whose names are known +at compile-time. The @code{progv} form provides an easy way to +bind variables whose names are computed at run-time. + +@defspec progv symbols values forms@dots{} +This form establishes @code{let}-style variable bindings on a +set of variables computed at run-time. The expressions +@var{symbols} and @var{values} are evaluated, and must return lists +of symbols and values, respectively. The symbols are bound to the +corresponding values for the duration of the body @var{form}s. +If @var{values} is shorter than @var{symbols}, the last few symbols +are made unbound (as if by @code{makunbound}) inside the body. +If @var{symbols} is shorter than @var{values}, the excess values +are ignored. +@end defspec + +@node Lexical Bindings, Function Bindings, Dynamic Bindings, Variable Bindings +@subsection Lexical Bindings + +@noindent +The @dfn{CL} package defines the following macro which +more closely follows the Common Lisp @code{let} form: + +@defspec lexical-let (bindings@dots{}) forms@dots{} +This form is exactly like @code{let} except that the bindings it +establishes are purely lexical. Lexical bindings are similar to +local variables in a language like C: Only the code physically +within the body of the @code{lexical-let} (after macro expansion) +may refer to the bound variables. + +@example +(setq a 5) +(defun foo (b) (+ a b)) +(let ((a 2)) (foo a)) + @result{} 4 +(lexical-let ((a 2)) (foo a)) + @result{} 7 +@end example + +@noindent +In this example, a regular @code{let} binding of @code{a} actually +makes a temporary change to the global variable @code{a}, so @code{foo} +is able to see the binding of @code{a} to 2. But @code{lexical-let} +actually creates a distinct local variable @code{a} for use within its +body, without any effect on the global variable of the same name. + +The most important use of lexical bindings is to create @dfn{closures}. +A closure is a function object that refers to an outside lexical +variable. For example: + +@example +(defun make-adder (n) + (lexical-let ((n n)) + (function (lambda (m) (+ n m))))) +(setq add17 (make-adder 17)) +(funcall add17 4) + @result{} 21 +@end example + +@noindent +The call @code{(make-adder 17)} returns a function object which adds +17 to its argument. If @code{let} had been used instead of +@code{lexical-let}, the function object would have referred to the +global @code{n}, which would have been bound to 17 only during the +call to @code{make-adder} itself. + +@example +(defun make-counter () + (lexical-let ((n 0)) + (function* (lambda (&optional (m 1)) (incf n m))))) +(setq count-1 (make-counter)) +(funcall count-1 3) + @result{} 3 +(funcall count-1 14) + @result{} 17 +(setq count-2 (make-counter)) +(funcall count-2 5) + @result{} 5 +(funcall count-1 2) + @result{} 19 +(funcall count-2) + @result{} 6 +@end example + +@noindent +Here we see that each call to @code{make-counter} creates a distinct +local variable @code{n}, which serves as a private counter for the +function object that is returned. + +Closed-over lexical variables persist until the last reference to +them goes away, just like all other Lisp objects. For example, +@code{count-2} refers to a function object which refers to an +instance of the variable @code{n}; this is the only reference +to that variable, so after @code{(setq count-2 nil)} the garbage +collector would be able to delete this instance of @code{n}. +Of course, if a @code{lexical-let} does not actually create any +closures, then the lexical variables are free as soon as the +@code{lexical-let} returns. + +Many closures are used only during the extent of the bindings they +refer to; these are known as ``downward funargs'' in Lisp parlance. +When a closure is used in this way, regular Emacs Lisp dynamic +bindings suffice and will be more efficient than @code{lexical-let} +closures: + +@example +(defun add-to-list (x list) + (mapcar (lambda (y) (+ x y))) list) +(add-to-list 7 '(1 2 5)) + @result{} (8 9 12) +@end example + +@noindent +Since this lambda is only used while @code{x} is still bound, +it is not necessary to make a true closure out of it. + +You can use @code{defun} or @code{flet} inside a @code{lexical-let} +to create a named closure. If several closures are created in the +body of a single @code{lexical-let}, they all close over the same +instance of the lexical variable. + +The @code{lexical-let} form is an extension to Common Lisp. In +true Common Lisp, all bindings are lexical unless declared otherwise. +@end defspec + +@defspec lexical-let* (bindings@dots{}) forms@dots{} +This form is just like @code{lexical-let}, except that the bindings +are made sequentially in the manner of @code{let*}. +@end defspec + +@node Function Bindings, Macro Bindings, Lexical Bindings, Variable Bindings +@subsection Function Bindings + +@noindent +These forms make @code{let}-like bindings to functions instead +of variables. + +@defspec flet (bindings@dots{}) forms@dots{} +This form establishes @code{let}-style bindings on the function +cells of symbols rather than on the value cells. Each @var{binding} +must be a list of the form @samp{(@var{name} @var{arglist} +@var{forms}@dots{})}, which defines a function exactly as if +it were a @code{defun*} form. The function @var{name} is defined +accordingly for the duration of the body of the @code{flet}; then +the old function definition, or lack thereof, is restored. + +While @code{flet} in Common Lisp establishes a lexical binding of +@var{name}, Emacs Lisp @code{flet} makes a dynamic binding. The +result is that @code{flet} affects indirect calls to a function as +well as calls directly inside the @code{flet} form itself. + +You can use @code{flet} to disable or modify the behavior of a +function in a temporary fashion. This will even work on Emacs +primitives, although note that some calls to primitive functions +internal to Emacs are made without going through the symbol's +function cell, and so will not be affected by @code{flet}. For +example, + +@example +(flet ((message (&rest args) (push args saved-msgs))) + (do-something)) +@end example + +This code attempts to replace the built-in function @code{message} +with a function that simply saves the messages in a list rather +than displaying them. The original definition of @code{message} +will be restored after @code{do-something} exits. This code will +work fine on messages generated by other Lisp code, but messages +generated directly inside Emacs will not be caught since they make +direct C-language calls to the message routines rather than going +through the Lisp @code{message} function. + +Functions defined by @code{flet} may use the full Common Lisp +argument notation supported by @code{defun*}; also, the function +body is enclosed in an implicit block as if by @code{defun*}. +@xref{Program Structure}. +@end defspec + +@defspec labels (bindings@dots{}) forms@dots{} +The @code{labels} form is like @code{flet}, except that it +makes lexical bindings of the function names rather than +dynamic bindings. (In true Common Lisp, both @code{flet} and +@code{labels} make lexical bindings of slightly different sorts; +since Emacs Lisp is dynamically bound by default, it seemed +more appropriate for @code{flet} also to use dynamic binding. +The @code{labels} form, with its lexical binding, is fully +compatible with Common Lisp.) + +Lexical scoping means that all references to the named +functions must appear physically within the body of the +@code{labels} form. References may appear both in the body +@var{forms} of @code{labels} itself, and in the bodies of +the functions themselves. Thus, @code{labels} can define +local recursive functions, or mutually-recursive sets of +functions. + +A ``reference'' to a function name is either a call to that +function, or a use of its name quoted by @code{quote} or +@code{function} to be passed on to, say, @code{mapcar}. +@end defspec + +@node Macro Bindings, , Function Bindings, Variable Bindings +@subsection Macro Bindings + +@noindent +These forms create local macros and ``symbol macros.'' + +@defspec macrolet (bindings@dots{}) forms@dots{} +This form is analogous to @code{flet}, but for macros instead of +functions. Each @var{binding} is a list of the same form as the +arguments to @code{defmacro*} (i.e., a macro name, argument list, +and macro-expander forms). The macro is defined accordingly for +use within the body of the @code{macrolet}. + +Because of the nature of macros, @code{macrolet} is lexically +scoped even in Emacs Lisp: The @code{macrolet} binding will +affect only calls that appear physically within the body +@var{forms}, possibly after expansion of other macros in the +body. +@end defspec + +@defspec symbol-macrolet (bindings@dots{}) forms@dots{} +This form creates @dfn{symbol macros}, which are macros that look +like variable references rather than function calls. Each +@var{binding} is a list @samp{(@var{var} @var{expansion})}; +any reference to @var{var} within the body @var{forms} is +replaced by @var{expansion}. + +@example +(setq bar '(5 . 9)) +(symbol-macrolet ((foo (car bar))) + (incf foo)) +bar + @result{} (6 . 9) +@end example + +A @code{setq} of a symbol macro is treated the same as a @code{setf}. +I.e., @code{(setq foo 4)} in the above would be equivalent to +@code{(setf foo 4)}, which in turn expands to @code{(setf (car bar) 4)}. + +Likewise, a @code{let} or @code{let*} binding a symbol macro is +treated like a @code{letf} or @code{letf*}. This differs from true +Common Lisp, where the rules of lexical scoping cause a @code{let} +binding to shadow a @code{symbol-macrolet} binding. In this package, +only @code{lexical-let} and @code{lexical-let*} will shadow a symbol +macro. + +There is no analogue of @code{defmacro} for symbol macros; all symbol +macros are local. A typical use of @code{symbol-macrolet} is in the +expansion of another macro: + +@example +(defmacro* my-dolist ((x list) &rest body) + (let ((var (gensym))) + (list 'loop 'for var 'on list 'do + (list* 'symbol-macrolet (list (list x (list 'car var))) + body)))) + +(setq mylist '(1 2 3 4)) +(my-dolist (x mylist) (incf x)) +mylist + @result{} (2 3 4 5) +@end example + +@noindent +In this example, the @code{my-dolist} macro is similar to @code{dolist} +(@pxref{Iteration}) except that the variable @code{x} becomes a true +reference onto the elements of the list. The @code{my-dolist} call +shown here expands to + +@example +(loop for G1234 on mylist do + (symbol-macrolet ((x (car G1234))) + (incf x))) +@end example + +@noindent +which in turn expands to + +@example +(loop for G1234 on mylist do (incf (car G1234))) +@end example + +@xref{Loop Facility}, for a description of the @code{loop} macro. +This package defines a nonstandard @code{in-ref} loop clause that +works much like @code{my-dolist}. +@end defspec + +@node Conditionals, Blocks and Exits, Variable Bindings, Control Structure +@section Conditionals + +@noindent +These conditional forms augment Emacs Lisp's simple @code{if}, +@code{and}, @code{or}, and @code{cond} forms. + +@defspec case keyform clause@dots{} +This macro evaluates @var{keyform}, then compares it with the key +values listed in the various @var{clause}s. Whichever clause matches +the key is executed; comparison is done by @code{eql}. If no clause +matches, the @code{case} form returns @code{nil}. The clauses are +of the form + +@example +(@var{keylist} @var{body-forms}@dots{}) +@end example + +@noindent +where @var{keylist} is a list of key values. If there is exactly +one value, and it is not a cons cell or the symbol @code{nil} or +@code{t}, then it can be used by itself as a @var{keylist} without +being enclosed in a list. All key values in the @code{case} form +must be distinct. The final clauses may use @code{t} in place of +a @var{keylist} to indicate a default clause that should be taken +if none of the other clauses match. (The symbol @code{otherwise} +is also recognized in place of @code{t}. To make a clause that +matches the actual symbol @code{t}, @code{nil}, or @code{otherwise}, +enclose the symbol in a list.) + +For example, this expression reads a keystroke, then does one of +four things depending on whether it is an @samp{a}, a @samp{b}, +a @key{RET} or @kbd{C-j}, or anything else. + +@example +(case (read-char) + (?a (do-a-thing)) + (?b (do-b-thing)) + ((?\r ?\n) (do-ret-thing)) + (t (do-other-thing))) +@end example +@end defspec + +@defspec ecase keyform clause@dots{} +This macro is just like @code{case}, except that if the key does +not match any of the clauses, an error is signaled rather than +simply returning @code{nil}. +@end defspec + +@defspec typecase keyform clause@dots{} +This macro is a version of @code{case} that checks for types +rather than values. Each @var{clause} is of the form +@samp{(@var{type} @var{body}...)}. @xref{Type Predicates}, +for a description of type specifiers. For example, + +@example +(typecase x + (integer (munch-integer x)) + (float (munch-float x)) + (string (munch-integer (string-to-int x))) + (t (munch-anything x))) +@end example + +The type specifier @code{t} matches any type of object; the word +@code{otherwise} is also allowed. To make one clause match any of +several types, use an @code{(or ...)} type specifier. +@end defspec + +@defspec etypecase keyform clause@dots{} +This macro is just like @code{typecase}, except that if the key does +not match any of the clauses, an error is signaled rather than +simply returning @code{nil}. +@end defspec + +@node Blocks and Exits, Iteration, Conditionals, Control Structure +@section Blocks and Exits + +@noindent +Common Lisp @dfn{blocks} provide a non-local exit mechanism very +similar to @code{catch} and @code{throw}, but lexically rather than +dynamically scoped. This package actually implements @code{block} +in terms of @code{catch}; however, the lexical scoping allows the +optimizing byte-compiler to omit the costly @code{catch} step if the +body of the block does not actually @code{return-from} the block. + +@defspec block name forms@dots{} +The @var{forms} are evaluated as if by a @code{progn}. However, +if any of the @var{forms} execute @code{(return-from @var{name})}, +they will jump out and return directly from the @code{block} form. +The @code{block} returns the result of the last @var{form} unless +a @code{return-from} occurs. + +The @code{block}/@code{return-from} mechanism is quite similar to +the @code{catch}/@code{throw} mechanism. The main differences are +that block @var{name}s are unevaluated symbols, rather than forms +(such as quoted symbols) which evaluate to a tag at run-time; and +also that blocks are lexically scoped whereas @code{catch}/@code{throw} +are dynamically scoped. This means that functions called from the +body of a @code{catch} can also @code{throw} to the @code{catch}, +but the @code{return-from} referring to a block name must appear +physically within the @var{forms} that make up the body of the block. +They may not appear within other called functions, although they may +appear within macro expansions or @code{lambda}s in the body. Block +names and @code{catch} names form independent name-spaces. + +In true Common Lisp, @code{defun} and @code{defmacro} surround +the function or expander bodies with implicit blocks with the +same name as the function or macro. This does not occur in Emacs +Lisp, but this package provides @code{defun*} and @code{defmacro*} +forms which do create the implicit block. + +The Common Lisp looping constructs defined by this package, +such as @code{loop} and @code{dolist}, also create implicit blocks +just as in Common Lisp. + +Because they are implemented in terms of Emacs Lisp @code{catch} +and @code{throw}, blocks have the same overhead as actual +@code{catch} constructs (roughly two function calls). However, +the optimizing byte compiler will optimize away the @code{catch} +if the block does +not in fact contain any @code{return} or @code{return-from} calls +that jump to it. This means that @code{do} loops and @code{defun*} +functions which don't use @code{return} don't pay the overhead to +support it. +@end defspec + +@defspec return-from name [result] +This macro returns from the block named @var{name}, which must be +an (unevaluated) symbol. If a @var{result} form is specified, it +is evaluated to produce the result returned from the @code{block}. +Otherwise, @code{nil} is returned. +@end defspec + +@defspec return [result] +This macro is exactly like @code{(return-from nil @var{result})}. +Common Lisp loops like @code{do} and @code{dolist} implicitly enclose +themselves in @code{nil} blocks. +@end defspec + +@node Iteration, Loop Facility, Blocks and Exits, Control Structure +@section Iteration + +@noindent +The macros described here provide more sophisticated, high-level +looping constructs to complement Emacs Lisp's basic @code{while} +loop. + +@defspec loop forms@dots{} +The @dfn{CL} package supports both the simple, old-style meaning of +@code{loop} and the extremely powerful and flexible feature known as +the @dfn{Loop Facility} or @dfn{Loop Macro}. This more advanced +facility is discussed in the following section; @pxref{Loop Facility}. +The simple form of @code{loop} is described here. + +If @code{loop} is followed by zero or more Lisp expressions, +then @code{(loop @var{exprs}@dots{})} simply creates an infinite +loop executing the expressions over and over. The loop is +enclosed in an implicit @code{nil} block. Thus, + +@example +(loop (foo) (if (no-more) (return 72)) (bar)) +@end example + +@noindent +is exactly equivalent to + +@example +(block nil (while t (foo) (if (no-more) (return 72)) (bar))) +@end example + +If any of the expressions are plain symbols, the loop is instead +interpreted as a Loop Macro specification as described later. +(This is not a restriction in practice, since a plain symbol +in the above notation would simply access and throw away the +value of a variable.) +@end defspec + +@defspec do (spec@dots{}) (end-test [result@dots{}]) forms@dots{} +This macro creates a general iterative loop. Each @var{spec} is +of the form + +@example +(@var{var} [@var{init} [@var{step}]]) +@end example + +The loop works as follows: First, each @var{var} is bound to the +associated @var{init} value as if by a @code{let} form. Then, in +each iteration of the loop, the @var{end-test} is evaluated; if +true, the loop is finished. Otherwise, the body @var{forms} are +evaluated, then each @var{var} is set to the associated @var{step} +expression (as if by a @code{psetq} form) and the next iteration +begins. Once the @var{end-test} becomes true, the @var{result} +forms are evaluated (with the @var{var}s still bound to their +values) to produce the result returned by @code{do}. + +The entire @code{do} loop is enclosed in an implicit @code{nil} +block, so that you can use @code{(return)} to break out of the +loop at any time. + +If there are no @var{result} forms, the loop returns @code{nil}. +If a given @var{var} has no @var{step} form, it is bound to its +@var{init} value but not otherwise modified during the @code{do} +loop (unless the code explicitly modifies it); this case is just +a shorthand for putting a @code{(let ((@var{var} @var{init})) @dots{})} +around the loop. If @var{init} is also omitted it defaults to +@code{nil}, and in this case a plain @samp{@var{var}} can be used +in place of @samp{(@var{var})}, again following the analogy with +@code{let}. + +This example (from Steele) illustrates a loop which applies the +function @code{f} to successive pairs of values from the lists +@code{foo} and @code{bar}; it is equivalent to the call +@code{(mapcar* 'f foo bar)}. Note that this loop has no body +@var{forms} at all, performing all its work as side effects of +the rest of the loop. + +@example +(do ((x foo (cdr x)) + (y bar (cdr y)) + (z nil (cons (f (car x) (car y)) z))) + ((or (null x) (null y)) + (nreverse z))) +@end example +@end defspec + +@defspec do* (spec@dots{}) (end-test [result@dots{}]) forms@dots{} +This is to @code{do} what @code{let*} is to @code{let}. In +particular, the initial values are bound as if by @code{let*} +rather than @code{let}, and the steps are assigned as if by +@code{setq} rather than @code{psetq}. + +Here is another way to write the above loop: + +@example +(do* ((xp foo (cdr xp)) + (yp bar (cdr yp)) + (x (car xp) (car xp)) + (y (car yp) (car yp)) + z) + ((or (null xp) (null yp)) + (nreverse z)) + (push (f x y) z)) +@end example +@end defspec + +@defspec dolist (var list [result]) forms@dots{} +This is a more specialized loop which iterates across the elements +of a list. @var{list} should evaluate to a list; the body @var{forms} +are executed with @var{var} bound to each element of the list in +turn. Finally, the @var{result} form (or @code{nil}) is evaluated +with @var{var} bound to @code{nil} to produce the result returned by +the loop. Unlike with Emacs's built in @code{dolist}, the loop is +surrounded by an implicit @code{nil} block. +@end defspec + +@defspec dotimes (var count [result]) forms@dots{} +This is a more specialized loop which iterates a specified number +of times. The body is executed with @var{var} bound to the integers +from zero (inclusive) to @var{count} (exclusive), in turn. Then +the @code{result} form is evaluated with @var{var} bound to the total +number of iterations that were done (i.e., @code{(max 0 @var{count})}) +to get the return value for the loop form. Unlike with Emacs's built in +@code{dolist}, the loop is surrounded by an implicit @code{nil} block. +@end defspec + +@defspec do-symbols (var [obarray [result]]) forms@dots{} +This loop iterates over all interned symbols. If @var{obarray} +is specified and is not @code{nil}, it loops over all symbols in +that obarray. For each symbol, the body @var{forms} are evaluated +with @var{var} bound to that symbol. The symbols are visited in +an unspecified order. Afterward the @var{result} form, if any, +is evaluated (with @var{var} bound to @code{nil}) to get the return +value. The loop is surrounded by an implicit @code{nil} block. +@end defspec + +@defspec do-all-symbols (var [result]) forms@dots{} +This is identical to @code{do-symbols} except that the @var{obarray} +argument is omitted; it always iterates over the default obarray. +@end defspec + +@xref{Mapping over Sequences}, for some more functions for +iterating over vectors or lists. + +@node Loop Facility, Multiple Values, Iteration, Control Structure +@section Loop Facility + +@noindent +A common complaint with Lisp's traditional looping constructs is +that they are either too simple and limited, such as Common Lisp's +@code{dotimes} or Emacs Lisp's @code{while}, or too unreadable and +obscure, like Common Lisp's @code{do} loop. + +To remedy this, recent versions of Common Lisp have added a new +construct called the ``Loop Facility'' or ``@code{loop} macro,'' +with an easy-to-use but very powerful and expressive syntax. + +@menu +* Loop Basics:: `loop' macro, basic clause structure +* Loop Examples:: Working examples of `loop' macro +* For Clauses:: Clauses introduced by `for' or `as' +* Iteration Clauses:: `repeat', `while', `thereis', etc. +* Accumulation Clauses:: `collect', `sum', `maximize', etc. +* Other Clauses:: `with', `if', `initially', `finally' +@end menu + +@node Loop Basics, Loop Examples, Loop Facility, Loop Facility +@subsection Loop Basics + +@noindent +The @code{loop} macro essentially creates a mini-language within +Lisp that is specially tailored for describing loops. While this +language is a little strange-looking by the standards of regular Lisp, +it turns out to be very easy to learn and well-suited to its purpose. + +Since @code{loop} is a macro, all parsing of the loop language +takes place at byte-compile time; compiled @code{loop}s are just +as efficient as the equivalent @code{while} loops written longhand. + +@defspec loop clauses@dots{} +A loop construct consists of a series of @var{clause}s, each +introduced by a symbol like @code{for} or @code{do}. Clauses +are simply strung together in the argument list of @code{loop}, +with minimal extra parentheses. The various types of clauses +specify initializations, such as the binding of temporary +variables, actions to be taken in the loop, stepping actions, +and final cleanup. + +Common Lisp specifies a certain general order of clauses in a +loop: + +@example +(loop @var{name-clause} + @var{var-clauses}@dots{} + @var{action-clauses}@dots{}) +@end example + +The @var{name-clause} optionally gives a name to the implicit +block that surrounds the loop. By default, the implicit block +is named @code{nil}. The @var{var-clauses} specify what +variables should be bound during the loop, and how they should +be modified or iterated throughout the course of the loop. The +@var{action-clauses} are things to be done during the loop, such +as computing, collecting, and returning values. + +The Emacs version of the @code{loop} macro is less restrictive about +the order of clauses, but things will behave most predictably if +you put the variable-binding clauses @code{with}, @code{for}, and +@code{repeat} before the action clauses. As in Common Lisp, +@code{initially} and @code{finally} clauses can go anywhere. + +Loops generally return @code{nil} by default, but you can cause +them to return a value by using an accumulation clause like +@code{collect}, an end-test clause like @code{always}, or an +explicit @code{return} clause to jump out of the implicit block. +(Because the loop body is enclosed in an implicit block, you can +also use regular Lisp @code{return} or @code{return-from} to +break out of the loop.) +@end defspec + +The following sections give some examples of the Loop Macro in +action, and describe the particular loop clauses in great detail. +Consult the second edition of Steele's @dfn{Common Lisp, the Language}, +for additional discussion and examples of the @code{loop} macro. + +@node Loop Examples, For Clauses, Loop Basics, Loop Facility +@subsection Loop Examples + +@noindent +Before listing the full set of clauses that are allowed, let's +look at a few example loops just to get a feel for the @code{loop} +language. + +@example +(loop for buf in (buffer-list) + collect (buffer-file-name buf)) +@end example + +@noindent +This loop iterates over all Emacs buffers, using the list +returned by @code{buffer-list}. For each buffer @code{buf}, +it calls @code{buffer-file-name} and collects the results into +a list, which is then returned from the @code{loop} construct. +The result is a list of the file names of all the buffers in +Emacs' memory. The words @code{for}, @code{in}, and @code{collect} +are reserved words in the @code{loop} language. + +@example +(loop repeat 20 do (insert "Yowsa\n")) +@end example + +@noindent +This loop inserts the phrase ``Yowsa'' twenty times in the +current buffer. + +@example +(loop until (eobp) do (munch-line) (forward-line 1)) +@end example + +@noindent +This loop calls @code{munch-line} on every line until the end +of the buffer. If point is already at the end of the buffer, +the loop exits immediately. + +@example +(loop do (munch-line) until (eobp) do (forward-line 1)) +@end example + +@noindent +This loop is similar to the above one, except that @code{munch-line} +is always called at least once. + +@example +(loop for x from 1 to 100 + for y = (* x x) + until (>= y 729) + finally return (list x (= y 729))) +@end example + +@noindent +This more complicated loop searches for a number @code{x} whose +square is 729. For safety's sake it only examines @code{x} +values up to 100; dropping the phrase @samp{to 100} would +cause the loop to count upwards with no limit. The second +@code{for} clause defines @code{y} to be the square of @code{x} +within the loop; the expression after the @code{=} sign is +reevaluated each time through the loop. The @code{until} +clause gives a condition for terminating the loop, and the +@code{finally} clause says what to do when the loop finishes. +(This particular example was written less concisely than it +could have been, just for the sake of illustration.) + +Note that even though this loop contains three clauses (two +@code{for}s and an @code{until}) that would have been enough to +define loops all by themselves, it still creates a single loop +rather than some sort of triple-nested loop. You must explicitly +nest your @code{loop} constructs if you want nested loops. + +@node For Clauses, Iteration Clauses, Loop Examples, Loop Facility +@subsection For Clauses + +@noindent +Most loops are governed by one or more @code{for} clauses. +A @code{for} clause simultaneously describes variables to be +bound, how those variables are to be stepped during the loop, +and usually an end condition based on those variables. + +The word @code{as} is a synonym for the word @code{for}. This +word is followed by a variable name, then a word like @code{from} +or @code{across} that describes the kind of iteration desired. +In Common Lisp, the phrase @code{being the} sometimes precedes +the type of iteration; in this package both @code{being} and +@code{the} are optional. The word @code{each} is a synonym +for @code{the}, and the word that follows it may be singular +or plural: @samp{for x being the elements of y} or +@samp{for x being each element of y}. Which form you use +is purely a matter of style. + +The variable is bound around the loop as if by @code{let}: + +@example +(setq i 'happy) +(loop for i from 1 to 10 do (do-something-with i)) +i + @result{} happy +@end example + +@table @code +@item for @var{var} from @var{expr1} to @var{expr2} by @var{expr3} +This type of @code{for} clause creates a counting loop. Each of +the three sub-terms is optional, though there must be at least one +term so that the clause is marked as a counting clause. + +The three expressions are the starting value, the ending value, and +the step value, respectively, of the variable. The loop counts +upwards by default (@var{expr3} must be positive), from @var{expr1} +to @var{expr2} inclusively. If you omit the @code{from} term, the +loop counts from zero; if you omit the @code{to} term, the loop +counts forever without stopping (unless stopped by some other +loop clause, of course); if you omit the @code{by} term, the loop +counts in steps of one. + +You can replace the word @code{from} with @code{upfrom} or +@code{downfrom} to indicate the direction of the loop. Likewise, +you can replace @code{to} with @code{upto} or @code{downto}. +For example, @samp{for x from 5 downto 1} executes five times +with @code{x} taking on the integers from 5 down to 1 in turn. +Also, you can replace @code{to} with @code{below} or @code{above}, +which are like @code{upto} and @code{downto} respectively except +that they are exclusive rather than inclusive limits: + +@example +(loop for x to 10 collect x) + @result{} (0 1 2 3 4 5 6 7 8 9 10) +(loop for x below 10 collect x) + @result{} (0 1 2 3 4 5 6 7 8 9) +@end example + +The @code{by} value is always positive, even for downward-counting +loops. Some sort of @code{from} value is required for downward +loops; @samp{for x downto 5} is not a valid loop clause all by +itself. + +@item for @var{var} in @var{list} by @var{function} +This clause iterates @var{var} over all the elements of @var{list}, +in turn. If you specify the @code{by} term, then @var{function} +is used to traverse the list instead of @code{cdr}; it must be a +function taking one argument. For example: + +@example +(loop for x in '(1 2 3 4 5 6) collect (* x x)) + @result{} (1 4 9 16 25 36) +(loop for x in '(1 2 3 4 5 6) by 'cddr collect (* x x)) + @result{} (1 9 25) +@end example + +@item for @var{var} on @var{list} by @var{function} +This clause iterates @var{var} over all the cons cells of @var{list}. + +@example +(loop for x on '(1 2 3 4) collect x) + @result{} ((1 2 3 4) (2 3 4) (3 4) (4)) +@end example + +With @code{by}, there is no real reason that the @code{on} expression +must be a list. For example: + +@example +(loop for x on first-animal by 'next-animal collect x) +@end example + +@noindent +where @code{(next-animal x)} takes an ``animal'' @var{x} and returns +the next in the (assumed) sequence of animals, or @code{nil} if +@var{x} was the last animal in the sequence. + +@item for @var{var} in-ref @var{list} by @var{function} +This is like a regular @code{in} clause, but @var{var} becomes +a @code{setf}-able ``reference'' onto the elements of the list +rather than just a temporary variable. For example, + +@example +(loop for x in-ref my-list do (incf x)) +@end example + +@noindent +increments every element of @code{my-list} in place. This clause +is an extension to standard Common Lisp. + +@item for @var{var} across @var{array} +This clause iterates @var{var} over all the elements of @var{array}, +which may be a vector or a string. + +@example +(loop for x across "aeiou" + do (use-vowel (char-to-string x))) +@end example + +@item for @var{var} across-ref @var{array} +This clause iterates over an array, with @var{var} a @code{setf}-able +reference onto the elements; see @code{in-ref} above. + +@item for @var{var} being the elements of @var{sequence} +This clause iterates over the elements of @var{sequence}, which may +be a list, vector, or string. Since the type must be determined +at run-time, this is somewhat less efficient than @code{in} or +@code{across}. The clause may be followed by the additional term +@samp{using (index @var{var2})} to cause @var{var2} to be bound to +the successive indices (starting at 0) of the elements. + +This clause type is taken from older versions of the @code{loop} macro, +and is not present in modern Common Lisp. The @samp{using (sequence ...)} +term of the older macros is not supported. + +@item for @var{var} being the elements of-ref @var{sequence} +This clause iterates over a sequence, with @var{var} a @code{setf}-able +reference onto the elements; see @code{in-ref} above. + +@item for @var{var} being the symbols [of @var{obarray}] +This clause iterates over symbols, either over all interned symbols +or over all symbols in @var{obarray}. The loop is executed with +@var{var} bound to each symbol in turn. The symbols are visited in +an unspecified order. + +As an example, + +@example +(loop for sym being the symbols + when (fboundp sym) + when (string-match "^map" (symbol-name sym)) + collect sym) +@end example + +@noindent +returns a list of all the functions whose names begin with @samp{map}. + +The Common Lisp words @code{external-symbols} and @code{present-symbols} +are also recognized but are equivalent to @code{symbols} in Emacs Lisp. + +Due to a minor implementation restriction, it will not work to have +more than one @code{for} clause iterating over symbols, hash tables, +keymaps, overlays, or intervals in a given @code{loop}. Fortunately, +it would rarely if ever be useful to do so. It @emph{is} valid to mix +one of these types of clauses with other clauses like @code{for ... to} +or @code{while}. + +@item for @var{var} being the hash-keys of @var{hash-table} +This clause iterates over the entries in @var{hash-table}. For each +hash table entry, @var{var} is bound to the entry's key. If you write +@samp{the hash-values} instead, @var{var} is bound to the values +of the entries. The clause may be followed by the additional +term @samp{using (hash-values @var{var2})} (where @code{hash-values} +is the opposite word of the word following @code{the}) to cause +@var{var} and @var{var2} to be bound to the two parts of each +hash table entry. + +@item for @var{var} being the key-codes of @var{keymap} +This clause iterates over the entries in @var{keymap}. +The iteration does not enter nested keymaps or inherited (parent) keymaps. +You can use @samp{the key-bindings} to access the commands bound to +the keys rather than the key codes, and you can add a @code{using} +clause to access both the codes and the bindings together. + +@item for @var{var} being the key-seqs of @var{keymap} +This clause iterates over all key sequences defined by @var{keymap} +and its nested keymaps, where @var{var} takes on values which are +vectors. The strings or vectors +are reused for each iteration, so you must copy them if you wish to keep +them permanently. You can add a @samp{using (key-bindings ...)} +clause to get the command bindings as well. + +@item for @var{var} being the overlays [of @var{buffer}] @dots{} +This clause iterates over the ``overlays'' of a buffer +(the clause @code{extents} is synonymous +with @code{overlays}). If the @code{of} term is omitted, the current +buffer is used. +This clause also accepts optional @samp{from @var{pos}} and +@samp{to @var{pos}} terms, limiting the clause to overlays which +overlap the specified region. + +@item for @var{var} being the intervals [of @var{buffer}] @dots{} +This clause iterates over all intervals of a buffer with constant +text properties. The variable @var{var} will be bound to conses +of start and end positions, where one start position is always equal +to the previous end position. The clause allows @code{of}, +@code{from}, @code{to}, and @code{property} terms, where the latter +term restricts the search to just the specified property. The +@code{of} term may specify either a buffer or a string. + +@item for @var{var} being the frames +This clause iterates over all frames, i.e., X window system windows +open on Emacs files. The +clause @code{screens} is a synonym for @code{frames}. The frames +are visited in @code{next-frame} order starting from +@code{selected-frame}. + +@item for @var{var} being the windows [of @var{frame}] +This clause iterates over the windows (in the Emacs sense) of +the current frame, or of the specified @var{frame}. + +@item for @var{var} being the buffers +This clause iterates over all buffers in Emacs. It is equivalent +to @samp{for @var{var} in (buffer-list)}. + +@item for @var{var} = @var{expr1} then @var{expr2} +This clause does a general iteration. The first time through +the loop, @var{var} will be bound to @var{expr1}. On the second +and successive iterations it will be set by evaluating @var{expr2} +(which may refer to the old value of @var{var}). For example, +these two loops are effectively the same: + +@example +(loop for x on my-list by 'cddr do ...) +(loop for x = my-list then (cddr x) while x do ...) +@end example + +Note that this type of @code{for} clause does not imply any sort +of terminating condition; the above example combines it with a +@code{while} clause to tell when to end the loop. + +If you omit the @code{then} term, @var{expr1} is used both for +the initial setting and for successive settings: + +@example +(loop for x = (random) when (> x 0) return x) +@end example + +@noindent +This loop keeps taking random numbers from the @code{(random)} +function until it gets a positive one, which it then returns. +@end table + +If you include several @code{for} clauses in a row, they are +treated sequentially (as if by @code{let*} and @code{setq}). +You can instead use the word @code{and} to link the clauses, +in which case they are processed in parallel (as if by @code{let} +and @code{psetq}). + +@example +(loop for x below 5 for y = nil then x collect (list x y)) + @result{} ((0 nil) (1 1) (2 2) (3 3) (4 4)) +(loop for x below 5 and y = nil then x collect (list x y)) + @result{} ((0 nil) (1 0) (2 1) (3 2) (4 3)) +@end example + +@noindent +In the first loop, @code{y} is set based on the value of @code{x} +that was just set by the previous clause; in the second loop, +@code{x} and @code{y} are set simultaneously so @code{y} is set +based on the value of @code{x} left over from the previous time +through the loop. + +Another feature of the @code{loop} macro is @dfn{destructuring}, +similar in concept to the destructuring provided by @code{defmacro}. +The @var{var} part of any @code{for} clause can be given as a list +of variables instead of a single variable. The values produced +during loop execution must be lists; the values in the lists are +stored in the corresponding variables. + +@example +(loop for (x y) in '((2 3) (4 5) (6 7)) collect (+ x y)) + @result{} (5 9 13) +@end example + +In loop destructuring, if there are more values than variables +the trailing values are ignored, and if there are more variables +than values the trailing variables get the value @code{nil}. +If @code{nil} is used as a variable name, the corresponding +values are ignored. Destructuring may be nested, and dotted +lists of variables like @code{(x . y)} are allowed. + +@node Iteration Clauses, Accumulation Clauses, For Clauses, Loop Facility +@subsection Iteration Clauses + +@noindent +Aside from @code{for} clauses, there are several other loop clauses +that control the way the loop operates. They might be used by +themselves, or in conjunction with one or more @code{for} clauses. + +@table @code +@item repeat @var{integer} +This clause simply counts up to the specified number using an +internal temporary variable. The loops + +@example +(loop repeat n do ...) +(loop for temp to n do ...) +@end example + +@noindent +are identical except that the second one forces you to choose +a name for a variable you aren't actually going to use. + +@item while @var{condition} +This clause stops the loop when the specified condition (any Lisp +expression) becomes @code{nil}. For example, the following two +loops are equivalent, except for the implicit @code{nil} block +that surrounds the second one: + +@example +(while @var{cond} @var{forms}@dots{}) +(loop while @var{cond} do @var{forms}@dots{}) +@end example + +@item until @var{condition} +This clause stops the loop when the specified condition is true, +i.e., non-@code{nil}. + +@item always @var{condition} +This clause stops the loop when the specified condition is @code{nil}. +Unlike @code{while}, it stops the loop using @code{return nil} so that +the @code{finally} clauses are not executed. If all the conditions +were non-@code{nil}, the loop returns @code{t}: + +@example +(if (loop for size in size-list always (> size 10)) + (some-big-sizes) + (no-big-sizes)) +@end example + +@item never @var{condition} +This clause is like @code{always}, except that the loop returns +@code{t} if any conditions were false, or @code{nil} otherwise. + +@item thereis @var{condition} +This clause stops the loop when the specified form is non-@code{nil}; +in this case, it returns that non-@code{nil} value. If all the +values were @code{nil}, the loop returns @code{nil}. +@end table + +@node Accumulation Clauses, Other Clauses, Iteration Clauses, Loop Facility +@subsection Accumulation Clauses + +@noindent +These clauses cause the loop to accumulate information about the +specified Lisp @var{form}. The accumulated result is returned +from the loop unless overridden, say, by a @code{return} clause. + +@table @code +@item collect @var{form} +This clause collects the values of @var{form} into a list. Several +examples of @code{collect} appear elsewhere in this manual. + +The word @code{collecting} is a synonym for @code{collect}, and +likewise for the other accumulation clauses. + +@item append @var{form} +This clause collects lists of values into a result list using +@code{append}. + +@item nconc @var{form} +This clause collects lists of values into a result list by +destructively modifying the lists rather than copying them. + +@item concat @var{form} +This clause concatenates the values of the specified @var{form} +into a string. (It and the following clause are extensions to +standard Common Lisp.) + +@item vconcat @var{form} +This clause concatenates the values of the specified @var{form} +into a vector. + +@item count @var{form} +This clause counts the number of times the specified @var{form} +evaluates to a non-@code{nil} value. + +@item sum @var{form} +This clause accumulates the sum of the values of the specified +@var{form}, which must evaluate to a number. + +@item maximize @var{form} +This clause accumulates the maximum value of the specified @var{form}, +which must evaluate to a number. The return value is undefined if +@code{maximize} is executed zero times. + +@item minimize @var{form} +This clause accumulates the minimum value of the specified @var{form}. +@end table + +Accumulation clauses can be followed by @samp{into @var{var}} to +cause the data to be collected into variable @var{var} (which is +automatically @code{let}-bound during the loop) rather than an +unnamed temporary variable. Also, @code{into} accumulations do +not automatically imply a return value. The loop must use some +explicit mechanism, such as @code{finally return}, to return +the accumulated result. + +It is valid for several accumulation clauses of the same type to +accumulate into the same place. From Steele: + +@example +(loop for name in '(fred sue alice joe june) + for kids in '((bob ken) () () (kris sunshine) ()) + collect name + append kids) + @result{} (fred bob ken sue alice joe kris sunshine june) +@end example + +@node Other Clauses, , Accumulation Clauses, Loop Facility +@subsection Other Clauses + +@noindent +This section describes the remaining loop clauses. + +@table @code +@item with @var{var} = @var{value} +This clause binds a variable to a value around the loop, but +otherwise leaves the variable alone during the loop. The following +loops are basically equivalent: + +@example +(loop with x = 17 do ...) +(let ((x 17)) (loop do ...)) +(loop for x = 17 then x do ...) +@end example + +Naturally, the variable @var{var} might be used for some purpose +in the rest of the loop. For example: + +@example +(loop for x in my-list with res = nil do (push x res) + finally return res) +@end example + +This loop inserts the elements of @code{my-list} at the front of +a new list being accumulated in @code{res}, then returns the +list @code{res} at the end of the loop. The effect is similar +to that of a @code{collect} clause, but the list gets reversed +by virtue of the fact that elements are being pushed onto the +front of @code{res} rather than the end. + +If you omit the @code{=} term, the variable is initialized to +@code{nil}. (Thus the @samp{= nil} in the above example is +unnecessary.) + +Bindings made by @code{with} are sequential by default, as if +by @code{let*}. Just like @code{for} clauses, @code{with} clauses +can be linked with @code{and} to cause the bindings to be made by +@code{let} instead. + +@item if @var{condition} @var{clause} +This clause executes the following loop clause only if the specified +condition is true. The following @var{clause} should be an accumulation, +@code{do}, @code{return}, @code{if}, or @code{unless} clause. +Several clauses may be linked by separating them with @code{and}. +These clauses may be followed by @code{else} and a clause or clauses +to execute if the condition was false. The whole construct may +optionally be followed by the word @code{end} (which may be used to +disambiguate an @code{else} or @code{and} in a nested @code{if}). + +The actual non-@code{nil} value of the condition form is available +by the name @code{it} in the ``then'' part. For example: + +@example +(setq funny-numbers '(6 13 -1)) + @result{} (6 13 -1) +(loop for x below 10 + if (oddp x) + collect x into odds + and if (memq x funny-numbers) return (cdr it) end + else + collect x into evens + finally return (vector odds evens)) + @result{} [(1 3 5 7 9) (0 2 4 6 8)] +(setq funny-numbers '(6 7 13 -1)) + @result{} (6 7 13 -1) +(loop <@r{same thing again}>) + @result{} (13 -1) +@end example + +Note the use of @code{and} to put two clauses into the ``then'' +part, one of which is itself an @code{if} clause. Note also that +@code{end}, while normally optional, was necessary here to make +it clear that the @code{else} refers to the outermost @code{if} +clause. In the first case, the loop returns a vector of lists +of the odd and even values of @var{x}. In the second case, the +odd number 7 is one of the @code{funny-numbers} so the loop +returns early; the actual returned value is based on the result +of the @code{memq} call. + +@item when @var{condition} @var{clause} +This clause is just a synonym for @code{if}. + +@item unless @var{condition} @var{clause} +The @code{unless} clause is just like @code{if} except that the +sense of the condition is reversed. + +@item named @var{name} +This clause gives a name other than @code{nil} to the implicit +block surrounding the loop. The @var{name} is the symbol to be +used as the block name. + +@item initially [do] @var{forms}... +This keyword introduces one or more Lisp forms which will be +executed before the loop itself begins (but after any variables +requested by @code{for} or @code{with} have been bound to their +initial values). @code{initially} clauses can appear anywhere; +if there are several, they are executed in the order they appear +in the loop. The keyword @code{do} is optional. + +@item finally [do] @var{forms}... +This introduces Lisp forms which will be executed after the loop +finishes (say, on request of a @code{for} or @code{while}). +@code{initially} and @code{finally} clauses may appear anywhere +in the loop construct, but they are executed (in the specified +order) at the beginning or end, respectively, of the loop. + +@item finally return @var{form} +This says that @var{form} should be executed after the loop +is done to obtain a return value. (Without this, or some other +clause like @code{collect} or @code{return}, the loop will simply +return @code{nil}.) Variables bound by @code{for}, @code{with}, +or @code{into} will still contain their final values when @var{form} +is executed. + +@item do @var{forms}... +The word @code{do} may be followed by any number of Lisp expressions +which are executed as an implicit @code{progn} in the body of the +loop. Many of the examples in this section illustrate the use of +@code{do}. + +@item return @var{form} +This clause causes the loop to return immediately. The following +Lisp form is evaluated to give the return value of the @code{loop} +form. The @code{finally} clauses, if any, are not executed. +Of course, @code{return} is generally used inside an @code{if} or +@code{unless}, as its use in a top-level loop clause would mean +the loop would never get to ``loop'' more than once. + +The clause @samp{return @var{form}} is equivalent to +@samp{do (return @var{form})} (or @code{return-from} if the loop +was named). The @code{return} clause is implemented a bit more +efficiently, though. +@end table + +While there is no high-level way to add user extensions to @code{loop} +(comparable to @code{defsetf} for @code{setf}, say), this package +does offer two properties called @code{cl-loop-handler} and +@code{cl-loop-for-handler} which are functions to be called when +a given symbol is encountered as a top-level loop clause or +@code{for} clause, respectively. Consult the source code in +file @file{cl-macs.el} for details. + +This package's @code{loop} macro is compatible with that of Common +Lisp, except that a few features are not implemented: @code{loop-finish} +and data-type specifiers. Naturally, the @code{for} clauses which +iterate over keymaps, overlays, intervals, frames, windows, and +buffers are Emacs-specific extensions. + +@node Multiple Values, , Loop Facility, Control Structure +@section Multiple Values + +@noindent +Common Lisp functions can return zero or more results. Emacs Lisp +functions, by contrast, always return exactly one result. This +package makes no attempt to emulate Common Lisp multiple return +values; Emacs versions of Common Lisp functions that return more +than one value either return just the first value (as in +@code{compiler-macroexpand}) or return a list of values (as in +@code{get-setf-method}). This package @emph{does} define placeholders +for the Common Lisp functions that work with multiple values, but +in Emacs Lisp these functions simply operate on lists instead. +The @code{values} form, for example, is a synonym for @code{list} +in Emacs. + +@defspec multiple-value-bind (var@dots{}) values-form forms@dots{} +This form evaluates @var{values-form}, which must return a list of +values. It then binds the @var{var}s to these respective values, +as if by @code{let}, and then executes the body @var{forms}. +If there are more @var{var}s than values, the extra @var{var}s +are bound to @code{nil}. If there are fewer @var{var}s than +values, the excess values are ignored. +@end defspec + +@defspec multiple-value-setq (var@dots{}) form +This form evaluates @var{form}, which must return a list of values. +It then sets the @var{var}s to these respective values, as if by +@code{setq}. Extra @var{var}s or values are treated the same as +in @code{multiple-value-bind}. +@end defspec + +The older Quiroz package attempted a more faithful (but still +imperfect) emulation of Common Lisp multiple values. The old +method ``usually'' simulated true multiple values quite well, +but under certain circumstances would leave spurious return +values in memory where a later, unrelated @code{multiple-value-bind} +form would see them. + +Since a perfect emulation is not feasible in Emacs Lisp, this +package opts to keep it as simple and predictable as possible. + +@node Macros, Declarations, Control Structure, Top +@chapter Macros + +@noindent +This package implements the various Common Lisp features of +@code{defmacro}, such as destructuring, @code{&environment}, +and @code{&body}. Top-level @code{&whole} is not implemented +for @code{defmacro} due to technical difficulties. +@xref{Argument Lists}. + +Destructuring is made available to the user by way of the +following macro: + +@defspec destructuring-bind arglist expr forms@dots{} +This macro expands to code which executes @var{forms}, with +the variables in @var{arglist} bound to the list of values +returned by @var{expr}. The @var{arglist} can include all +the features allowed for @code{defmacro} argument lists, +including destructuring. (The @code{&environment} keyword +is not allowed.) The macro expansion will signal an error +if @var{expr} returns a list of the wrong number of arguments +or with incorrect keyword arguments. +@end defspec + +This package also includes the Common Lisp @code{define-compiler-macro} +facility, which allows you to define compile-time expansions and +optimizations for your functions. + +@defspec define-compiler-macro name arglist forms@dots{} +This form is similar to @code{defmacro}, except that it only expands +calls to @var{name} at compile-time; calls processed by the Lisp +interpreter are not expanded, nor are they expanded by the +@code{macroexpand} function. + +The argument list may begin with a @code{&whole} keyword and a +variable. This variable is bound to the macro-call form itself, +i.e., to a list of the form @samp{(@var{name} @var{args}@dots{})}. +If the macro expander returns this form unchanged, then the +compiler treats it as a normal function call. This allows +compiler macros to work as optimizers for special cases of a +function, leaving complicated cases alone. + +For example, here is a simplified version of a definition that +appears as a standard part of this package: + +@example +(define-compiler-macro member* (&whole form a list &rest keys) + (if (and (null keys) + (eq (car-safe a) 'quote) + (not (floatp-safe (cadr a)))) + (list 'memq a list) + form)) +@end example + +@noindent +This definition causes @code{(member* @var{a} @var{list})} to change +to a call to the faster @code{memq} in the common case where @var{a} +is a non-floating-point constant; if @var{a} is anything else, or +if there are any keyword arguments in the call, then the original +@code{member*} call is left intact. (The actual compiler macro +for @code{member*} optimizes a number of other cases, including +common @code{:test} predicates.) +@end defspec + +@defun compiler-macroexpand form +This function is analogous to @code{macroexpand}, except that it +expands compiler macros rather than regular macros. It returns +@var{form} unchanged if it is not a call to a function for which +a compiler macro has been defined, or if that compiler macro +decided to punt by returning its @code{&whole} argument. Like +@code{macroexpand}, it expands repeatedly until it reaches a form +for which no further expansion is possible. +@end defun + +@xref{Macro Bindings}, for descriptions of the @code{macrolet} +and @code{symbol-macrolet} forms for making ``local'' macro +definitions. + +@node Declarations, Symbols, Macros, Top +@chapter Declarations + +@noindent +Common Lisp includes a complex and powerful ``declaration'' +mechanism that allows you to give the compiler special hints +about the types of data that will be stored in particular variables, +and about the ways those variables and functions will be used. This +package defines versions of all the Common Lisp declaration forms: +@code{declare}, @code{locally}, @code{proclaim}, @code{declaim}, +and @code{the}. + +Most of the Common Lisp declarations are not currently useful in +Emacs Lisp, as the byte-code system provides little opportunity +to benefit from type information, and @code{special} declarations +are redundant in a fully dynamically-scoped Lisp. A few +declarations are meaningful when the optimizing byte +compiler is being used, however. Under the earlier non-optimizing +compiler, these declarations will effectively be ignored. + +@defun proclaim decl-spec +This function records a ``global'' declaration specified by +@var{decl-spec}. Since @code{proclaim} is a function, @var{decl-spec} +is evaluated and thus should normally be quoted. +@end defun + +@defspec declaim decl-specs@dots{} +This macro is like @code{proclaim}, except that it takes any number +of @var{decl-spec} arguments, and the arguments are unevaluated and +unquoted. The @code{declaim} macro also puts an @code{(eval-when +(compile load eval) ...)} around the declarations so that they will +be registered at compile-time as well as at run-time. (This is vital, +since normally the declarations are meant to influence the way the +compiler treats the rest of the file that contains the @code{declaim} +form.) +@end defspec + +@defspec declare decl-specs@dots{} +This macro is used to make declarations within functions and other +code. Common Lisp allows declarations in various locations, generally +at the beginning of any of the many ``implicit @code{progn}s'' +throughout Lisp syntax, such as function bodies, @code{let} bodies, +etc. Currently the only declaration understood by @code{declare} +is @code{special}. +@end defspec + +@defspec locally declarations@dots{} forms@dots{} +In this package, @code{locally} is no different from @code{progn}. +@end defspec + +@defspec the type form +Type information provided by @code{the} is ignored in this package; +in other words, @code{(the @var{type} @var{form})} is equivalent +to @var{form}. Future versions of the optimizing byte-compiler may +make use of this information. + +For example, @code{mapcar} can map over both lists and arrays. It is +hard for the compiler to expand @code{mapcar} into an in-line loop +unless it knows whether the sequence will be a list or an array ahead +of time. With @code{(mapcar 'car (the vector foo))}, a future +compiler would have enough information to expand the loop in-line. +For now, Emacs Lisp will treat the above code as exactly equivalent +to @code{(mapcar 'car foo)}. +@end defspec + +Each @var{decl-spec} in a @code{proclaim}, @code{declaim}, or +@code{declare} should be a list beginning with a symbol that says +what kind of declaration it is. This package currently understands +@code{special}, @code{inline}, @code{notinline}, @code{optimize}, +and @code{warn} declarations. (The @code{warn} declaration is an +extension of standard Common Lisp.) Other Common Lisp declarations, +such as @code{type} and @code{ftype}, are silently ignored. + +@table @code +@item special +Since all variables in Emacs Lisp are ``special'' (in the Common +Lisp sense), @code{special} declarations are only advisory. They +simply tell the optimizing byte compiler that the specified +variables are intentionally being referred to without being +bound in the body of the function. The compiler normally emits +warnings for such references, since they could be typographical +errors for references to local variables. + +The declaration @code{(declare (special @var{var1} @var{var2}))} is +equivalent to @code{(defvar @var{var1}) (defvar @var{var2})} in the +optimizing compiler, or to nothing at all in older compilers (which +do not warn for non-local references). + +In top-level contexts, it is generally better to write +@code{(defvar @var{var})} than @code{(declaim (special @var{var}))}, +since @code{defvar} makes your intentions clearer. But the older +byte compilers can not handle @code{defvar}s appearing inside of +functions, while @code{(declare (special @var{var}))} takes care +to work correctly with all compilers. + +@item inline +The @code{inline} @var{decl-spec} lists one or more functions +whose bodies should be expanded ``in-line'' into calling functions +whenever the compiler is able to arrange for it. For example, +the Common Lisp function @code{cadr} is declared @code{inline} +by this package so that the form @code{(cadr @var{x})} will +expand directly into @code{(car (cdr @var{x}))} when it is called +in user functions, for a savings of one (relatively expensive) +function call. + +The following declarations are all equivalent. Note that the +@code{defsubst} form is a convenient way to define a function +and declare it inline all at once. + +@example +(declaim (inline foo bar)) +(eval-when (compile load eval) (proclaim '(inline foo bar))) +(defsubst foo (...) ...) ; instead of defun +@end example + +@strong{Please note:} this declaration remains in effect after the +containing source file is done. It is correct to use it to +request that a function you have defined should be inlined, +but it is impolite to use it to request inlining of an external +function. + +In Common Lisp, it is possible to use @code{(declare (inline @dots{}))} +before a particular call to a function to cause just that call to +be inlined; the current byte compilers provide no way to implement +this, so @code{(declare (inline @dots{}))} is currently ignored by +this package. + +@item notinline +The @code{notinline} declaration lists functions which should +not be inlined after all; it cancels a previous @code{inline} +declaration. + +@item optimize +This declaration controls how much optimization is performed by +the compiler. Naturally, it is ignored by the earlier non-optimizing +compilers. + +The word @code{optimize} is followed by any number of lists like +@code{(speed 3)} or @code{(safety 2)}. Common Lisp defines several +optimization ``qualities''; this package ignores all but @code{speed} +and @code{safety}. The value of a quality should be an integer from +0 to 3, with 0 meaning ``unimportant'' and 3 meaning ``very important.'' +The default level for both qualities is 1. + +In this package, with the optimizing compiler, the +@code{speed} quality is tied to the @code{byte-compile-optimize} +flag, which is set to @code{nil} for @code{(speed 0)} and to +@code{t} for higher settings; and the @code{safety} quality is +tied to the @code{byte-compile-delete-errors} flag, which is +set to @code{t} for @code{(safety 3)} and to @code{nil} for all +lower settings. (The latter flag controls whether the compiler +is allowed to optimize out code whose only side-effect could +be to signal an error, e.g., rewriting @code{(progn foo bar)} to +@code{bar} when it is not known whether @code{foo} will be bound +at run-time.) + +Note that even compiling with @code{(safety 0)}, the Emacs +byte-code system provides sufficient checking to prevent real +harm from being done. For example, barring serious bugs in +Emacs itself, Emacs will not crash with a segmentation fault +just because of an error in a fully-optimized Lisp program. + +The @code{optimize} declaration is normally used in a top-level +@code{proclaim} or @code{declaim} in a file; Common Lisp allows +it to be used with @code{declare} to set the level of optimization +locally for a given form, but this will not work correctly with the +current version of the optimizing compiler. (The @code{declare} +will set the new optimization level, but that level will not +automatically be unset after the enclosing form is done.) + +@item warn +This declaration controls what sorts of warnings are generated +by the byte compiler. Again, only the optimizing compiler +generates warnings. The word @code{warn} is followed by any +number of ``warning qualities,'' similar in form to optimization +qualities. The currently supported warning types are +@code{redefine}, @code{callargs}, @code{unresolved}, and +@code{free-vars}; in the current system, a value of 0 will +disable these warnings and any higher value will enable them. +See the documentation for the optimizing byte compiler for details. +@end table + +@node Symbols, Numbers, Declarations, Top +@chapter Symbols + +@noindent +This package defines several symbol-related features that were +missing from Emacs Lisp. + +@menu +* Property Lists:: `get*', `remprop', `getf', `remf' +* Creating Symbols:: `gensym', `gentemp' +@end menu + +@node Property Lists, Creating Symbols, Symbols, Symbols +@section Property Lists + +@noindent +These functions augment the standard Emacs Lisp functions @code{get} +and @code{put} for operating on properties attached to symbols. +There are also functions for working with property lists as +first-class data structures not attached to particular symbols. + +@defun get* symbol property &optional default +This function is like @code{get}, except that if the property is +not found, the @var{default} argument provides the return value. +(The Emacs Lisp @code{get} function always uses @code{nil} as +the default; this package's @code{get*} is equivalent to Common +Lisp's @code{get}.) + +The @code{get*} function is @code{setf}-able; when used in this +fashion, the @var{default} argument is allowed but ignored. +@end defun + +@defun remprop symbol property +This function removes the entry for @var{property} from the property +list of @var{symbol}. It returns a true value if the property was +indeed found and removed, or @code{nil} if there was no such property. +(This function was probably omitted from Emacs originally because, +since @code{get} did not allow a @var{default}, it was very difficult +to distinguish between a missing property and a property whose value +was @code{nil}; thus, setting a property to @code{nil} was close +enough to @code{remprop} for most purposes.) +@end defun + +@defun getf place property &optional default +This function scans the list @var{place} as if it were a property +list, i.e., a list of alternating property names and values. If +an even-numbered element of @var{place} is found which is @code{eq} +to @var{property}, the following odd-numbered element is returned. +Otherwise, @var{default} is returned (or @code{nil} if no default +is given). + +In particular, + +@example +(get sym prop) @equiv{} (getf (symbol-plist sym) prop) +@end example + +It is valid to use @code{getf} as a @code{setf} place, in which case +its @var{place} argument must itself be a valid @code{setf} place. +The @var{default} argument, if any, is ignored in this context. +The effect is to change (via @code{setcar}) the value cell in the +list that corresponds to @var{property}, or to cons a new property-value +pair onto the list if the property is not yet present. + +@example +(put sym prop val) @equiv{} (setf (getf (symbol-plist sym) prop) val) +@end example + +The @code{get} and @code{get*} functions are also @code{setf}-able. +The fact that @code{default} is ignored can sometimes be useful: + +@example +(incf (get* 'foo 'usage-count 0)) +@end example + +Here, symbol @code{foo}'s @code{usage-count} property is incremented +if it exists, or set to 1 (an incremented 0) otherwise. + +When not used as a @code{setf} form, @code{getf} is just a regular +function and its @var{place} argument can actually be any Lisp +expression. +@end defun + +@defspec remf place property +This macro removes the property-value pair for @var{property} from +the property list stored at @var{place}, which is any @code{setf}-able +place expression. It returns true if the property was found. Note +that if @var{property} happens to be first on the list, this will +effectively do a @code{(setf @var{place} (cddr @var{place}))}, +whereas if it occurs later, this simply uses @code{setcdr} to splice +out the property and value cells. +@end defspec + +@iftex +@secno=2 +@end iftex + +@node Creating Symbols, , Property Lists, Symbols +@section Creating Symbols + +@noindent +These functions create unique symbols, typically for use as +temporary variables. + +@defun gensym &optional x +This function creates a new, uninterned symbol (using @code{make-symbol}) +with a unique name. (The name of an uninterned symbol is relevant +only if the symbol is printed.) By default, the name is generated +from an increasing sequence of numbers, @samp{G1000}, @samp{G1001}, +@samp{G1002}, etc. If the optional argument @var{x} is a string, that +string is used as a prefix instead of @samp{G}. Uninterned symbols +are used in macro expansions for temporary variables, to ensure that +their names will not conflict with ``real'' variables in the user's +code. +@end defun + +@defvar *gensym-counter* +This variable holds the counter used to generate @code{gensym} names. +It is incremented after each use by @code{gensym}. In Common Lisp +this is initialized with 0, but this package initializes it with a +random (time-dependent) value to avoid trouble when two files that +each used @code{gensym} in their compilation are loaded together. +(Uninterned symbols become interned when the compiler writes them +out to a file and the Emacs loader loads them, so their names have to +be treated a bit more carefully than in Common Lisp where uninterned +symbols remain uninterned after loading.) +@end defvar + +@defun gentemp &optional x +This function is like @code{gensym}, except that it produces a new +@emph{interned} symbol. If the symbol that is generated already +exists, the function keeps incrementing the counter and trying +again until a new symbol is generated. +@end defun + +The Quiroz @file{cl.el} package also defined a @code{defkeyword} +form for creating self-quoting keyword symbols. This package +automatically creates all keywords that are called for by +@code{&key} argument specifiers, and discourages the use of +keywords as data unrelated to keyword arguments, so the +@code{defkeyword} form has been discontinued. + +@iftex +@chapno=11 +@end iftex + +@node Numbers, Sequences, Symbols, Top +@chapter Numbers + +@noindent +This section defines a few simple Common Lisp operations on numbers +which were left out of Emacs Lisp. + +@menu +* Predicates on Numbers:: `plusp', `oddp', `floatp-safe', etc. +* Numerical Functions:: `abs', `floor*', etc. +* Random Numbers:: `random*', `make-random-state' +* Implementation Parameters:: `most-positive-float' +@end menu + +@iftex +@secno=1 +@end iftex + +@node Predicates on Numbers, Numerical Functions, Numbers, Numbers +@section Predicates on Numbers + +@noindent +These functions return @code{t} if the specified condition is +true of the numerical argument, or @code{nil} otherwise. + +@defun plusp number +This predicate tests whether @var{number} is positive. It is an +error if the argument is not a number. +@end defun + +@defun minusp number +This predicate tests whether @var{number} is negative. It is an +error if the argument is not a number. +@end defun + +@defun oddp integer +This predicate tests whether @var{integer} is odd. It is an +error if the argument is not an integer. +@end defun + +@defun evenp integer +This predicate tests whether @var{integer} is even. It is an +error if the argument is not an integer. +@end defun + +@defun floatp-safe object +This predicate tests whether @var{object} is a floating-point +number. On systems that support floating-point, this is equivalent +to @code{floatp}. On other systems, this always returns @code{nil}. +@end defun + +@iftex +@secno=3 +@end iftex + +@node Numerical Functions, Random Numbers, Predicates on Numbers, Numbers +@section Numerical Functions + +@noindent +These functions perform various arithmetic operations on numbers. + +@defun gcd &rest integers +This function returns the Greatest Common Divisor of the arguments. +For one argument, it returns the absolute value of that argument. +For zero arguments, it returns zero. +@end defun + +@defun lcm &rest integers +This function returns the Least Common Multiple of the arguments. +For one argument, it returns the absolute value of that argument. +For zero arguments, it returns one. +@end defun + +@defun isqrt integer +This function computes the ``integer square root'' of its integer +argument, i.e., the greatest integer less than or equal to the true +square root of the argument. +@end defun + +@defun floor* number &optional divisor +This function implements the Common Lisp @code{floor} function. +It is called @code{floor*} to avoid name conflicts with the +simpler @code{floor} function built-in to Emacs. + +With one argument, @code{floor*} returns a list of two numbers: +The argument rounded down (toward minus infinity) to an integer, +and the ``remainder'' which would have to be added back to the +first return value to yield the argument again. If the argument +is an integer @var{x}, the result is always the list @code{(@var{x} 0)}. +If the argument is a floating-point number, the first +result is a Lisp integer and the second is a Lisp float between +0 (inclusive) and 1 (exclusive). + +With two arguments, @code{floor*} divides @var{number} by +@var{divisor}, and returns the floor of the quotient and the +corresponding remainder as a list of two numbers. If +@code{(floor* @var{x} @var{y})} returns @code{(@var{q} @var{r})}, +then @code{@var{q}*@var{y} + @var{r} = @var{x}}, with @var{r} +between 0 (inclusive) and @var{r} (exclusive). Also, note +that @code{(floor* @var{x})} is exactly equivalent to +@code{(floor* @var{x} 1)}. + +This function is entirely compatible with Common Lisp's @code{floor} +function, except that it returns the two results in a list since +Emacs Lisp does not support multiple-valued functions. +@end defun + +@defun ceiling* number &optional divisor +This function implements the Common Lisp @code{ceiling} function, +which is analogous to @code{floor} except that it rounds the +argument or quotient of the arguments up toward plus infinity. +The remainder will be between 0 and minus @var{r}. +@end defun + +@defun truncate* number &optional divisor +This function implements the Common Lisp @code{truncate} function, +which is analogous to @code{floor} except that it rounds the +argument or quotient of the arguments toward zero. Thus it is +equivalent to @code{floor*} if the argument or quotient is +positive, or to @code{ceiling*} otherwise. The remainder has +the same sign as @var{number}. +@end defun + +@defun round* number &optional divisor +This function implements the Common Lisp @code{round} function, +which is analogous to @code{floor} except that it rounds the +argument or quotient of the arguments to the nearest integer. +In the case of a tie (the argument or quotient is exactly +halfway between two integers), it rounds to the even integer. +@end defun + +@defun mod* number divisor +This function returns the same value as the second return value +of @code{floor}. +@end defun + +@defun rem* number divisor +This function returns the same value as the second return value +of @code{truncate}. +@end defun + +These definitions are compatible with those in the Quiroz +@file{cl.el} package, except that this package appends @samp{*} +to certain function names to avoid conflicts with existing +Emacs functions, and that the mechanism for returning +multiple values is different. + +@iftex +@secno=8 +@end iftex + +@node Random Numbers, Implementation Parameters, Numerical Functions, Numbers +@section Random Numbers + +@noindent +This package also provides an implementation of the Common Lisp +random number generator. It uses its own additive-congruential +algorithm, which is much more likely to give statistically clean +random numbers than the simple generators supplied by many +operating systems. + +@defun random* number &optional state +This function returns a random nonnegative number less than +@var{number}, and of the same type (either integer or floating-point). +The @var{state} argument should be a @code{random-state} object +which holds the state of the random number generator. The +function modifies this state object as a side effect. If +@var{state} is omitted, it defaults to the variable +@code{*random-state*}, which contains a pre-initialized +@code{random-state} object. +@end defun + +@defvar *random-state* +This variable contains the system ``default'' @code{random-state} +object, used for calls to @code{random*} that do not specify an +alternative state object. Since any number of programs in the +Emacs process may be accessing @code{*random-state*} in interleaved +fashion, the sequence generated from this variable will be +irreproducible for all intents and purposes. +@end defvar + +@defun make-random-state &optional state +This function creates or copies a @code{random-state} object. +If @var{state} is omitted or @code{nil}, it returns a new copy of +@code{*random-state*}. This is a copy in the sense that future +sequences of calls to @code{(random* @var{n})} and +@code{(random* @var{n} @var{s})} (where @var{s} is the new +random-state object) will return identical sequences of random +numbers. + +If @var{state} is a @code{random-state} object, this function +returns a copy of that object. If @var{state} is @code{t}, this +function returns a new @code{random-state} object seeded from the +date and time. As an extension to Common Lisp, @var{state} may also +be an integer in which case the new object is seeded from that +integer; each different integer seed will result in a completely +different sequence of random numbers. + +It is valid to print a @code{random-state} object to a buffer or +file and later read it back with @code{read}. If a program wishes +to use a sequence of pseudo-random numbers which can be reproduced +later for debugging, it can call @code{(make-random-state t)} to +get a new sequence, then print this sequence to a file. When the +program is later rerun, it can read the original run's random-state +from the file. +@end defun + +@defun random-state-p object +This predicate returns @code{t} if @var{object} is a +@code{random-state} object, or @code{nil} otherwise. +@end defun + +@node Implementation Parameters, , Random Numbers, Numbers +@section Implementation Parameters + +@noindent +This package defines several useful constants having to with numbers. + +The following parameters have to do with floating-point numbers. +This package determines their values by exercising the computer's +floating-point arithmetic in various ways. Because this operation +might be slow, the code for initializing them is kept in a separate +function that must be called before the parameters can be used. + +@defun cl-float-limits +This function makes sure that the Common Lisp floating-point parameters +like @code{most-positive-float} have been initialized. Until it is +called, these parameters will be @code{nil}. If this version of Emacs +does not support floats, the parameters will remain @code{nil}. If the +parameters have already been initialized, the function returns +immediately. + +The algorithm makes assumptions that will be valid for most modern +machines, but will fail if the machine's arithmetic is extremely +unusual, e.g., decimal. +@end defun + +Since true Common Lisp supports up to four different floating-point +precisions, it has families of constants like +@code{most-positive-single-float}, @code{most-positive-double-float}, +@code{most-positive-long-float}, and so on. Emacs has only one +floating-point precision, so this package omits the precision word +from the constants' names. + +@defvar most-positive-float +This constant equals the largest value a Lisp float can hold. +For those systems whose arithmetic supports infinities, this is +the largest @emph{finite} value. For IEEE machines, the value +is approximately @code{1.79e+308}. +@end defvar + +@defvar most-negative-float +This constant equals the most-negative value a Lisp float can hold. +(It is assumed to be equal to @code{(- most-positive-float)}.) +@end defvar + +@defvar least-positive-float +This constant equals the smallest Lisp float value greater than zero. +For IEEE machines, it is about @code{4.94e-324} if denormals are +supported or @code{2.22e-308} if not. +@end defvar + +@defvar least-positive-normalized-float +This constant equals the smallest @emph{normalized} Lisp float greater +than zero, i.e., the smallest value for which IEEE denormalization +will not result in a loss of precision. For IEEE machines, this +value is about @code{2.22e-308}. For machines that do not support +the concept of denormalization and gradual underflow, this constant +will always equal @code{least-positive-float}. +@end defvar + +@defvar least-negative-float +This constant is the negative counterpart of @code{least-positive-float}. +@end defvar + +@defvar least-negative-normalized-float +This constant is the negative counterpart of +@code{least-positive-normalized-float}. +@end defvar + +@defvar float-epsilon +This constant is the smallest positive Lisp float that can be added +to 1.0 to produce a distinct value. Adding a smaller number to 1.0 +will yield 1.0 again due to roundoff. For IEEE machines, epsilon +is about @code{2.22e-16}. +@end defvar + +@defvar float-negative-epsilon +This is the smallest positive value that can be subtracted from +1.0 to produce a distinct value. For IEEE machines, it is about +@code{1.11e-16}. +@end defvar + +@iftex +@chapno=13 +@end iftex + +@node Sequences, Lists, Numbers, Top +@chapter Sequences + +@noindent +Common Lisp defines a number of functions that operate on +@dfn{sequences}, which are either lists, strings, or vectors. +Emacs Lisp includes a few of these, notably @code{elt} and +@code{length}; this package defines most of the rest. + +@menu +* Sequence Basics:: Arguments shared by all sequence functions +* Mapping over Sequences:: `mapcar*', `mapcan', `map', `every', etc. +* Sequence Functions:: `subseq', `remove*', `substitute', etc. +* Searching Sequences:: `find', `position', `count', `search', etc. +* Sorting Sequences:: `sort*', `stable-sort', `merge' +@end menu + +@node Sequence Basics, Mapping over Sequences, Sequences, Sequences +@section Sequence Basics + +@noindent +Many of the sequence functions take keyword arguments; @pxref{Argument +Lists}. All keyword arguments are optional and, if specified, +may appear in any order. + +The @code{:key} argument should be passed either @code{nil}, or a +function of one argument. This key function is used as a filter +through which the elements of the sequence are seen; for example, +@code{(find x y :key 'car)} is similar to @code{(assoc* x y)}: +It searches for an element of the list whose @code{car} equals +@code{x}, rather than for an element which equals @code{x} itself. +If @code{:key} is omitted or @code{nil}, the filter is effectively +the identity function. + +The @code{:test} and @code{:test-not} arguments should be either +@code{nil}, or functions of two arguments. The test function is +used to compare two sequence elements, or to compare a search value +with sequence elements. (The two values are passed to the test +function in the same order as the original sequence function +arguments from which they are derived, or, if they both come from +the same sequence, in the same order as they appear in that sequence.) +The @code{:test} argument specifies a function which must return +true (non-@code{nil}) to indicate a match; instead, you may use +@code{:test-not} to give a function which returns @emph{false} to +indicate a match. The default test function is @code{:test 'eql}. + +Many functions which take @var{item} and @code{:test} or @code{:test-not} +arguments also come in @code{-if} and @code{-if-not} varieties, +where a @var{predicate} function is passed instead of @var{item}, +and sequence elements match if the predicate returns true on them +(or false in the case of @code{-if-not}). For example: + +@example +(remove* 0 seq :test '=) @equiv{} (remove-if 'zerop seq) +@end example + +@noindent +to remove all zeros from sequence @code{seq}. + +Some operations can work on a subsequence of the argument sequence; +these function take @code{:start} and @code{:end} arguments which +default to zero and the length of the sequence, respectively. +Only elements between @var{start} (inclusive) and @var{end} +(exclusive) are affected by the operation. The @var{end} argument +may be passed @code{nil} to signify the length of the sequence; +otherwise, both @var{start} and @var{end} must be integers, with +@code{0 <= @var{start} <= @var{end} <= (length @var{seq})}. +If the function takes two sequence arguments, the limits are +defined by keywords @code{:start1} and @code{:end1} for the first, +and @code{:start2} and @code{:end2} for the second. + +A few functions accept a @code{:from-end} argument, which, if +non-@code{nil}, causes the operation to go from right-to-left +through the sequence instead of left-to-right, and a @code{:count} +argument, which specifies an integer maximum number of elements +to be removed or otherwise processed. + +The sequence functions make no guarantees about the order in +which the @code{:test}, @code{:test-not}, and @code{:key} functions +are called on various elements. Therefore, it is a bad idea to depend +on side effects of these functions. For example, @code{:from-end} +may cause the sequence to be scanned actually in reverse, or it may +be scanned forwards but computing a result ``as if'' it were scanned +backwards. (Some functions, like @code{mapcar*} and @code{every}, +@emph{do} specify exactly the order in which the function is called +so side effects are perfectly acceptable in those cases.) + +Strings may contain ``text properties'' as well +as character data. Except as noted, it is undefined whether or +not text properties are preserved by sequence functions. For +example, @code{(remove* ?A @var{str})} may or may not preserve +the properties of the characters copied from @var{str} into the +result. + +@node Mapping over Sequences, Sequence Functions, Sequence Basics, Sequences +@section Mapping over Sequences + +@noindent +These functions ``map'' the function you specify over the elements +of lists or arrays. They are all variations on the theme of the +built-in function @code{mapcar}. + +@defun mapcar* function seq &rest more-seqs +This function calls @var{function} on successive parallel sets of +elements from its argument sequences. Given a single @var{seq} +argument it is equivalent to @code{mapcar}; given @var{n} sequences, +it calls the function with the first elements of each of the sequences +as the @var{n} arguments to yield the first element of the result +list, then with the second elements, and so on. The mapping stops as +soon as the shortest sequence runs out. The argument sequences may +be any mixture of lists, strings, and vectors; the return sequence +is always a list. + +Common Lisp's @code{mapcar} accepts multiple arguments but works +only on lists; Emacs Lisp's @code{mapcar} accepts a single sequence +argument. This package's @code{mapcar*} works as a compatible +superset of both. +@end defun + +@defun map result-type function seq &rest more-seqs +This function maps @var{function} over the argument sequences, +just like @code{mapcar*}, but it returns a sequence of type +@var{result-type} rather than a list. @var{result-type} must +be one of the following symbols: @code{vector}, @code{string}, +@code{list} (in which case the effect is the same as for +@code{mapcar*}), or @code{nil} (in which case the results are +thrown away and @code{map} returns @code{nil}). +@end defun + +@defun maplist function list &rest more-lists +This function calls @var{function} on each of its argument lists, +then on the @code{cdr}s of those lists, and so on, until the +shortest list runs out. The results are returned in the form +of a list. Thus, @code{maplist} is like @code{mapcar*} except +that it passes in the list pointers themselves rather than the +@code{car}s of the advancing pointers. +@end defun + +@defun mapc function seq &rest more-seqs +This function is like @code{mapcar*}, except that the values returned +by @var{function} are ignored and thrown away rather than being +collected into a list. The return value of @code{mapc} is @var{seq}, +the first sequence. This function is more general than the Emacs +primitive @code{mapc}. +@end defun + +@defun mapl function list &rest more-lists +This function is like @code{maplist}, except that it throws away +the values returned by @var{function}. +@end defun + +@defun mapcan function seq &rest more-seqs +This function is like @code{mapcar*}, except that it concatenates +the return values (which must be lists) using @code{nconc}, +rather than simply collecting them into a list. +@end defun + +@defun mapcon function list &rest more-lists +This function is like @code{maplist}, except that it concatenates +the return values using @code{nconc}. +@end defun + +@defun some predicate seq &rest more-seqs +This function calls @var{predicate} on each element of @var{seq} +in turn; if @var{predicate} returns a non-@code{nil} value, +@code{some} returns that value, otherwise it returns @code{nil}. +Given several sequence arguments, it steps through the sequences +in parallel until the shortest one runs out, just as in +@code{mapcar*}. You can rely on the left-to-right order in which +the elements are visited, and on the fact that mapping stops +immediately as soon as @var{predicate} returns non-@code{nil}. +@end defun + +@defun every predicate seq &rest more-seqs +This function calls @var{predicate} on each element of the sequence(s) +in turn; it returns @code{nil} as soon as @var{predicate} returns +@code{nil} for any element, or @code{t} if the predicate was true +for all elements. +@end defun + +@defun notany predicate seq &rest more-seqs +This function calls @var{predicate} on each element of the sequence(s) +in turn; it returns @code{nil} as soon as @var{predicate} returns +a non-@code{nil} value for any element, or @code{t} if the predicate +was @code{nil} for all elements. +@end defun + +@defun notevery predicate seq &rest more-seqs +This function calls @var{predicate} on each element of the sequence(s) +in turn; it returns a non-@code{nil} value as soon as @var{predicate} +returns @code{nil} for any element, or @code{t} if the predicate was +true for all elements. +@end defun + +@defun reduce function seq @t{&key :from-end :start :end :initial-value :key} +This function combines the elements of @var{seq} using an associative +binary operation. Suppose @var{function} is @code{*} and @var{seq} is +the list @code{(2 3 4 5)}. The first two elements of the list are +combined with @code{(* 2 3) = 6}; this is combined with the next +element, @code{(* 6 4) = 24}, and that is combined with the final +element: @code{(* 24 5) = 120}. Note that the @code{*} function happens +to be self-reducing, so that @code{(* 2 3 4 5)} has the same effect as +an explicit call to @code{reduce}. + +If @code{:from-end} is true, the reduction is right-associative instead +of left-associative: + +@example +(reduce '- '(1 2 3 4)) + @equiv{} (- (- (- 1 2) 3) 4) @result{} -8 +(reduce '- '(1 2 3 4) :from-end t) + @equiv{} (- 1 (- 2 (- 3 4))) @result{} -2 +@end example + +If @code{:key} is specified, it is a function of one argument which +is called on each of the sequence elements in turn. + +If @code{:initial-value} is specified, it is effectively added to the +front (or rear in the case of @code{:from-end}) of the sequence. +The @code{:key} function is @emph{not} applied to the initial value. + +If the sequence, including the initial value, has exactly one element +then that element is returned without ever calling @var{function}. +If the sequence is empty (and there is no initial value), then +@var{function} is called with no arguments to obtain the return value. +@end defun + +All of these mapping operations can be expressed conveniently in +terms of the @code{loop} macro. In compiled code, @code{loop} will +be faster since it generates the loop as in-line code with no +function calls. + +@node Sequence Functions, Searching Sequences, Mapping over Sequences, Sequences +@section Sequence Functions + +@noindent +This section describes a number of Common Lisp functions for +operating on sequences. + +@defun subseq sequence start &optional end +This function returns a given subsequence of the argument +@var{sequence}, which may be a list, string, or vector. +The indices @var{start} and @var{end} must be in range, and +@var{start} must be no greater than @var{end}. If @var{end} +is omitted, it defaults to the length of the sequence. The +return value is always a copy; it does not share structure +with @var{sequence}. + +As an extension to Common Lisp, @var{start} and/or @var{end} +may be negative, in which case they represent a distance back +from the end of the sequence. This is for compatibility with +Emacs' @code{substring} function. Note that @code{subseq} is +the @emph{only} sequence function that allows negative +@var{start} and @var{end}. + +You can use @code{setf} on a @code{subseq} form to replace a +specified range of elements with elements from another sequence. +The replacement is done as if by @code{replace}, described below. +@end defun + +@defun concatenate result-type &rest seqs +This function concatenates the argument sequences together to +form a result sequence of type @var{result-type}, one of the +symbols @code{vector}, @code{string}, or @code{list}. The +arguments are always copied, even in cases such as +@code{(concatenate 'list '(1 2 3))} where the result is +identical to an argument. +@end defun + +@defun fill seq item @t{&key :start :end} +This function fills the elements of the sequence (or the specified +part of the sequence) with the value @var{item}. +@end defun + +@defun replace seq1 seq2 @t{&key :start1 :end1 :start2 :end2} +This function copies part of @var{seq2} into part of @var{seq1}. +The sequence @var{seq1} is not stretched or resized; the amount +of data copied is simply the shorter of the source and destination +(sub)sequences. The function returns @var{seq1}. + +If @var{seq1} and @var{seq2} are @code{eq}, then the replacement +will work correctly even if the regions indicated by the start +and end arguments overlap. However, if @var{seq1} and @var{seq2} +are lists which share storage but are not @code{eq}, and the +start and end arguments specify overlapping regions, the effect +is undefined. +@end defun + +@defun remove* item seq @t{&key :test :test-not :key :count :start :end :from-end} +This returns a copy of @var{seq} with all elements matching +@var{item} removed. The result may share storage with or be +@code{eq} to @var{seq} in some circumstances, but the original +@var{seq} will not be modified. The @code{:test}, @code{:test-not}, +and @code{:key} arguments define the matching test that is used; +by default, elements @code{eql} to @var{item} are removed. The +@code{:count} argument specifies the maximum number of matching +elements that can be removed (only the leftmost @var{count} matches +are removed). The @code{:start} and @code{:end} arguments specify +a region in @var{seq} in which elements will be removed; elements +outside that region are not matched or removed. The @code{:from-end} +argument, if true, says that elements should be deleted from the +end of the sequence rather than the beginning (this matters only +if @var{count} was also specified). +@end defun + +@defun delete* item seq @t{&key :test :test-not :key :count :start :end :from-end} +This deletes all elements of @var{seq} which match @var{item}. +It is a destructive operation. Since Emacs Lisp does not support +stretchable strings or vectors, this is the same as @code{remove*} +for those sequence types. On lists, @code{remove*} will copy the +list if necessary to preserve the original list, whereas +@code{delete*} will splice out parts of the argument list. +Compare @code{append} and @code{nconc}, which are analogous +non-destructive and destructive list operations in Emacs Lisp. +@end defun + +@findex remove-if +@findex remove-if-not +@findex delete-if +@findex delete-if-not +The predicate-oriented functions @code{remove-if}, @code{remove-if-not}, +@code{delete-if}, and @code{delete-if-not} are defined similarly. + +@defun remove-duplicates seq @t{&key :test :test-not :key :start :end :from-end} +This function returns a copy of @var{seq} with duplicate elements +removed. Specifically, if two elements from the sequence match +according to the @code{:test}, @code{:test-not}, and @code{:key} +arguments, only the rightmost one is retained. If @code{:from-end} +is true, the leftmost one is retained instead. If @code{:start} or +@code{:end} is specified, only elements within that subsequence are +examined or removed. +@end defun + +@defun delete-duplicates seq @t{&key :test :test-not :key :start :end :from-end} +This function deletes duplicate elements from @var{seq}. It is +a destructive version of @code{remove-duplicates}. +@end defun + +@defun substitute new old seq @t{&key :test :test-not :key :count :start :end :from-end} +This function returns a copy of @var{seq}, with all elements +matching @var{old} replaced with @var{new}. The @code{:count}, +@code{:start}, @code{:end}, and @code{:from-end} arguments may be +used to limit the number of substitutions made. +@end defun + +@defun nsubstitute new old seq @t{&key :test :test-not :key :count :start :end :from-end} +This is a destructive version of @code{substitute}; it performs +the substitution using @code{setcar} or @code{aset} rather than +by returning a changed copy of the sequence. +@end defun + +@findex substitute-if +@findex substitute-if-not +@findex nsubstitute-if +@findex nsubstitute-if-not +The @code{substitute-if}, @code{substitute-if-not}, @code{nsubstitute-if}, +and @code{nsubstitute-if-not} functions are defined similarly. For +these, a @var{predicate} is given in place of the @var{old} argument. + +@node Searching Sequences, Sorting Sequences, Sequence Functions, Sequences +@section Searching Sequences + +@noindent +These functions search for elements or subsequences in a sequence. +(See also @code{member*} and @code{assoc*}; @pxref{Lists}.) + +@defun find item seq @t{&key :test :test-not :key :start :end :from-end} +This function searches @var{seq} for an element matching @var{item}. +If it finds a match, it returns the matching element. Otherwise, +it returns @code{nil}. It returns the leftmost match, unless +@code{:from-end} is true, in which case it returns the rightmost +match. The @code{:start} and @code{:end} arguments may be used to +limit the range of elements that are searched. +@end defun + +@defun position item seq @t{&key :test :test-not :key :start :end :from-end} +This function is like @code{find}, except that it returns the +integer position in the sequence of the matching item rather than +the item itself. The position is relative to the start of the +sequence as a whole, even if @code{:start} is non-zero. The function +returns @code{nil} if no matching element was found. +@end defun + +@defun count item seq @t{&key :test :test-not :key :start :end} +This function returns the number of elements of @var{seq} which +match @var{item}. The result is always a nonnegative integer. +@end defun + +@findex find-if +@findex find-if-not +@findex position-if +@findex position-if-not +@findex count-if +@findex count-if-not +The @code{find-if}, @code{find-if-not}, @code{position-if}, +@code{position-if-not}, @code{count-if}, and @code{count-if-not} +functions are defined similarly. + +@defun mismatch seq1 seq2 @t{&key :test :test-not :key :start1 :end1 :start2 :end2 :from-end} +This function compares the specified parts of @var{seq1} and +@var{seq2}. If they are the same length and the corresponding +elements match (according to @code{:test}, @code{:test-not}, +and @code{:key}), the function returns @code{nil}. If there is +a mismatch, the function returns the index (relative to @var{seq1}) +of the first mismatching element. This will be the leftmost pair of +elements which do not match, or the position at which the shorter of +the two otherwise-matching sequences runs out. + +If @code{:from-end} is true, then the elements are compared from right +to left starting at @code{(1- @var{end1})} and @code{(1- @var{end2})}. +If the sequences differ, then one plus the index of the rightmost +difference (relative to @var{seq1}) is returned. + +An interesting example is @code{(mismatch str1 str2 :key 'upcase)}, +which compares two strings case-insensitively. +@end defun + +@defun search seq1 seq2 @t{&key :test :test-not :key :from-end :start1 :end1 :start2 :end2} +This function searches @var{seq2} for a subsequence that matches +@var{seq1} (or part of it specified by @code{:start1} and +@code{:end1}.) Only matches which fall entirely within the region +defined by @code{:start2} and @code{:end2} will be considered. +The return value is the index of the leftmost element of the +leftmost match, relative to the start of @var{seq2}, or @code{nil} +if no matches were found. If @code{:from-end} is true, the +function finds the @emph{rightmost} matching subsequence. +@end defun + +@node Sorting Sequences, , Searching Sequences, Sequences +@section Sorting Sequences + +@defun sort* seq predicate @t{&key :key} +This function sorts @var{seq} into increasing order as determined +by using @var{predicate} to compare pairs of elements. @var{predicate} +should return true (non-@code{nil}) if and only if its first argument +is less than (not equal to) its second argument. For example, +@code{<} and @code{string-lessp} are suitable predicate functions +for sorting numbers and strings, respectively; @code{>} would sort +numbers into decreasing rather than increasing order. + +This function differs from Emacs' built-in @code{sort} in that it +can operate on any type of sequence, not just lists. Also, it +accepts a @code{:key} argument which is used to preprocess data +fed to the @var{predicate} function. For example, + +@example +(setq data (sort* data 'string-lessp :key 'downcase)) +@end example + +@noindent +sorts @var{data}, a sequence of strings, into increasing alphabetical +order without regard to case. A @code{:key} function of @code{car} +would be useful for sorting association lists. It should only be a +simple accessor though, it's used heavily in the current +implementation. + +The @code{sort*} function is destructive; it sorts lists by actually +rearranging the @code{cdr} pointers in suitable fashion. +@end defun + +@defun stable-sort seq predicate @t{&key :key} +This function sorts @var{seq} @dfn{stably}, meaning two elements +which are equal in terms of @var{predicate} are guaranteed not to +be rearranged out of their original order by the sort. + +In practice, @code{sort*} and @code{stable-sort} are equivalent +in Emacs Lisp because the underlying @code{sort} function is +stable by default. However, this package reserves the right to +use non-stable methods for @code{sort*} in the future. +@end defun + +@defun merge type seq1 seq2 predicate @t{&key :key} +This function merges two sequences @var{seq1} and @var{seq2} by +interleaving their elements. The result sequence, of type @var{type} +(in the sense of @code{concatenate}), has length equal to the sum +of the lengths of the two input sequences. The sequences may be +modified destructively. Order of elements within @var{seq1} and +@var{seq2} is preserved in the interleaving; elements of the two +sequences are compared by @var{predicate} (in the sense of +@code{sort}) and the lesser element goes first in the result. +When elements are equal, those from @var{seq1} precede those from +@var{seq2} in the result. Thus, if @var{seq1} and @var{seq2} are +both sorted according to @var{predicate}, then the result will be +a merged sequence which is (stably) sorted according to +@var{predicate}. +@end defun + +@node Lists, Structures, Sequences, Top +@chapter Lists + +@noindent +The functions described here operate on lists. + +@menu +* List Functions:: `caddr', `first', `list*', etc. +* Substitution of Expressions:: `subst', `sublis', etc. +* Lists as Sets:: `member*', `adjoin', `union', etc. +* Association Lists:: `assoc*', `rassoc*', `acons', `pairlis' +@end menu + +@node List Functions, Substitution of Expressions, Lists, Lists +@section List Functions + +@noindent +This section describes a number of simple operations on lists, +i.e., chains of cons cells. + +@defun caddr x +This function is equivalent to @code{(car (cdr (cdr @var{x})))}. +Likewise, this package defines all 28 @code{c@var{xxx}r} functions +where @var{xxx} is up to four @samp{a}s and/or @samp{d}s. +All of these functions are @code{setf}-able, and calls to them +are expanded inline by the byte-compiler for maximum efficiency. +@end defun + +@defun first x +This function is a synonym for @code{(car @var{x})}. Likewise, +the functions @code{second}, @code{third}, @dots{}, through +@code{tenth} return the given element of the list @var{x}. +@end defun + +@defun rest x +This function is a synonym for @code{(cdr @var{x})}. +@end defun + +@defun endp x +Common Lisp defines this function to act like @code{null}, but +signaling an error if @code{x} is neither a @code{nil} nor a +cons cell. This package simply defines @code{endp} as a synonym +for @code{null}. +@end defun + +@defun list-length x +This function returns the length of list @var{x}, exactly like +@code{(length @var{x})}, except that if @var{x} is a circular +list (where the cdr-chain forms a loop rather than terminating +with @code{nil}), this function returns @code{nil}. (The regular +@code{length} function would get stuck if given a circular list.) +@end defun + +@defun list* arg &rest others +This function constructs a list of its arguments. The final +argument becomes the @code{cdr} of the last cell constructed. +Thus, @code{(list* @var{a} @var{b} @var{c})} is equivalent to +@code{(cons @var{a} (cons @var{b} @var{c}))}, and +@code{(list* @var{a} @var{b} nil)} is equivalent to +@code{(list @var{a} @var{b})}. + +(Note that this function really is called @code{list*} in Common +Lisp; it is not a name invented for this package like @code{member*} +or @code{defun*}.) +@end defun + +@defun ldiff list sublist +If @var{sublist} is a sublist of @var{list}, i.e., is @code{eq} to +one of the cons cells of @var{list}, then this function returns +a copy of the part of @var{list} up to but not including +@var{sublist}. For example, @code{(ldiff x (cddr x))} returns +the first two elements of the list @code{x}. The result is a +copy; the original @var{list} is not modified. If @var{sublist} +is not a sublist of @var{list}, a copy of the entire @var{list} +is returned. +@end defun + +@defun copy-list list +This function returns a copy of the list @var{list}. It copies +dotted lists like @code{(1 2 . 3)} correctly. +@end defun + +@defun copy-tree x &optional vecp +This function returns a copy of the tree of cons cells @var{x}. +Unlike @code{copy-sequence} (and its alias @code{copy-list}), +which copies only along the @code{cdr} direction, this function +copies (recursively) along both the @code{car} and the @code{cdr} +directions. If @var{x} is not a cons cell, the function simply +returns @var{x} unchanged. If the optional @var{vecp} argument +is true, this function copies vectors (recursively) as well as +cons cells. +@end defun + +@defun tree-equal x y @t{&key :test :test-not :key} +This function compares two trees of cons cells. If @var{x} and +@var{y} are both cons cells, their @code{car}s and @code{cdr}s are +compared recursively. If neither @var{x} nor @var{y} is a cons +cell, they are compared by @code{eql}, or according to the +specified test. The @code{:key} function, if specified, is +applied to the elements of both trees. @xref{Sequences}. +@end defun + +@iftex +@secno=3 +@end iftex + +@node Substitution of Expressions, Lists as Sets, List Functions, Lists +@section Substitution of Expressions + +@noindent +These functions substitute elements throughout a tree of cons +cells. (@xref{Sequence Functions}, for the @code{substitute} +function, which works on just the top-level elements of a list.) + +@defun subst new old tree @t{&key :test :test-not :key} +This function substitutes occurrences of @var{old} with @var{new} +in @var{tree}, a tree of cons cells. It returns a substituted +tree, which will be a copy except that it may share storage with +the argument @var{tree} in parts where no substitutions occurred. +The original @var{tree} is not modified. This function recurses +on, and compares against @var{old}, both @code{car}s and @code{cdr}s +of the component cons cells. If @var{old} is itself a cons cell, +then matching cells in the tree are substituted as usual without +recursively substituting in that cell. Comparisons with @var{old} +are done according to the specified test (@code{eql} by default). +The @code{:key} function is applied to the elements of the tree +but not to @var{old}. +@end defun + +@defun nsubst new old tree @t{&key :test :test-not :key} +This function is like @code{subst}, except that it works by +destructive modification (by @code{setcar} or @code{setcdr}) +rather than copying. +@end defun + +@findex subst-if +@findex subst-if-not +@findex nsubst-if +@findex nsubst-if-not +The @code{subst-if}, @code{subst-if-not}, @code{nsubst-if}, and +@code{nsubst-if-not} functions are defined similarly. + +@defun sublis alist tree @t{&key :test :test-not :key} +This function is like @code{subst}, except that it takes an +association list @var{alist} of @var{old}-@var{new} pairs. +Each element of the tree (after applying the @code{:key} +function, if any), is compared with the @code{car}s of +@var{alist}; if it matches, it is replaced by the corresponding +@code{cdr}. +@end defun + +@defun nsublis alist tree @t{&key :test :test-not :key} +This is a destructive version of @code{sublis}. +@end defun + +@node Lists as Sets, Association Lists, Substitution of Expressions, Lists +@section Lists as Sets + +@noindent +These functions perform operations on lists which represent sets +of elements. + +@defun member* item list @t{&key :test :test-not :key} +This function searches @var{list} for an element matching @var{item}. +If a match is found, it returns the cons cell whose @code{car} was +the matching element. Otherwise, it returns @code{nil}. Elements +are compared by @code{eql} by default; you can use the @code{:test}, +@code{:test-not}, and @code{:key} arguments to modify this behavior. +@xref{Sequences}. + +Note that this function's name is suffixed by @samp{*} to avoid +the incompatible @code{member} function defined in Emacs. +(That function uses @code{equal} for comparisons; it is equivalent +to @code{(member* @var{item} @var{list} :test 'equal)}.) +@end defun + +@findex member-if +@findex member-if-not +The @code{member-if} and @code{member-if-not} functions +analogously search for elements which satisfy a given predicate. + +@defun tailp sublist list +This function returns @code{t} if @var{sublist} is a sublist of +@var{list}, i.e., if @var{sublist} is @code{eql} to @var{list} or to +any of its @code{cdr}s. +@end defun + +@defun adjoin item list @t{&key :test :test-not :key} +This function conses @var{item} onto the front of @var{list}, +like @code{(cons @var{item} @var{list})}, but only if @var{item} +is not already present on the list (as determined by @code{member*}). +If a @code{:key} argument is specified, it is applied to +@var{item} as well as to the elements of @var{list} during +the search, on the reasoning that @var{item} is ``about'' to +become part of the list. +@end defun + +@defun union list1 list2 @t{&key :test :test-not :key} +This function combines two lists which represent sets of items, +returning a list that represents the union of those two sets. +The result list will contain all items which appear in @var{list1} +or @var{list2}, and no others. If an item appears in both +@var{list1} and @var{list2} it will be copied only once. If +an item is duplicated in @var{list1} or @var{list2}, it is +undefined whether or not that duplication will survive in the +result list. The order of elements in the result list is also +undefined. +@end defun + +@defun nunion list1 list2 @t{&key :test :test-not :key} +This is a destructive version of @code{union}; rather than copying, +it tries to reuse the storage of the argument lists if possible. +@end defun + +@defun intersection list1 list2 @t{&key :test :test-not :key} +This function computes the intersection of the sets represented +by @var{list1} and @var{list2}. It returns the list of items +which appear in both @var{list1} and @var{list2}. +@end defun + +@defun nintersection list1 list2 @t{&key :test :test-not :key} +This is a destructive version of @code{intersection}. It +tries to reuse storage of @var{list1} rather than copying. +It does @emph{not} reuse the storage of @var{list2}. +@end defun + +@defun set-difference list1 list2 @t{&key :test :test-not :key} +This function computes the ``set difference'' of @var{list1} +and @var{list2}, i.e., the set of elements that appear in +@var{list1} but @emph{not} in @var{list2}. +@end defun + +@defun nset-difference list1 list2 @t{&key :test :test-not :key} +This is a destructive @code{set-difference}, which will try +to reuse @var{list1} if possible. +@end defun + +@defun set-exclusive-or list1 list2 @t{&key :test :test-not :key} +This function computes the ``set exclusive or'' of @var{list1} +and @var{list2}, i.e., the set of elements that appear in +exactly one of @var{list1} and @var{list2}. +@end defun + +@defun nset-exclusive-or list1 list2 @t{&key :test :test-not :key} +This is a destructive @code{set-exclusive-or}, which will try +to reuse @var{list1} and @var{list2} if possible. +@end defun + +@defun subsetp list1 list2 @t{&key :test :test-not :key} +This function checks whether @var{list1} represents a subset +of @var{list2}, i.e., whether every element of @var{list1} +also appears in @var{list2}. +@end defun + +@node Association Lists, , Lists as Sets, Lists +@section Association Lists + +@noindent +An @dfn{association list} is a list representing a mapping from +one set of values to another; any list whose elements are cons +cells is an association list. + +@defun assoc* item a-list @t{&key :test :test-not :key} +This function searches the association list @var{a-list} for an +element whose @code{car} matches (in the sense of @code{:test}, +@code{:test-not}, and @code{:key}, or by comparison with @code{eql}) +a given @var{item}. It returns the matching element, if any, +otherwise @code{nil}. It ignores elements of @var{a-list} which +are not cons cells. (This corresponds to the behavior of +@code{assq} and @code{assoc} in Emacs Lisp; Common Lisp's +@code{assoc} ignores @code{nil}s but considers any other non-cons +elements of @var{a-list} to be an error.) +@end defun + +@defun rassoc* item a-list @t{&key :test :test-not :key} +This function searches for an element whose @code{cdr} matches +@var{item}. If @var{a-list} represents a mapping, this applies +the inverse of the mapping to @var{item}. +@end defun + +@findex assoc-if +@findex assoc-if-not +@findex rassoc-if +@findex rassoc-if-not +The @code{assoc-if}, @code{assoc-if-not}, @code{rassoc-if}, +and @code{rassoc-if-not} functions are defined similarly. + +Two simple functions for constructing association lists are: + +@defun acons key value alist +This is equivalent to @code{(cons (cons @var{key} @var{value}) @var{alist})}. +@end defun + +@defun pairlis keys values &optional alist +This is equivalent to @code{(nconc (mapcar* 'cons @var{keys} @var{values}) +@var{alist})}. +@end defun + +@iftex +@chapno=18 +@end iftex + +@node Structures, Assertions, Lists, Top +@chapter Structures + +@noindent +The Common Lisp @dfn{structure} mechanism provides a general way +to define data types similar to C's @code{struct} types. A +structure is a Lisp object containing some number of @dfn{slots}, +each of which can hold any Lisp data object. Functions are +provided for accessing and setting the slots, creating or copying +structure objects, and recognizing objects of a particular structure +type. + +In true Common Lisp, each structure type is a new type distinct +from all existing Lisp types. Since the underlying Emacs Lisp +system provides no way to create new distinct types, this package +implements structures as vectors (or lists upon request) with a +special ``tag'' symbol to identify them. + +@defspec defstruct name slots@dots{} +The @code{defstruct} form defines a new structure type called +@var{name}, with the specified @var{slots}. (The @var{slots} +may begin with a string which documents the structure type.) +In the simplest case, @var{name} and each of the @var{slots} +are symbols. For example, + +@example +(defstruct person name age sex) +@end example + +@noindent +defines a struct type called @code{person} which contains three +slots. Given a @code{person} object @var{p}, you can access those +slots by calling @code{(person-name @var{p})}, @code{(person-age @var{p})}, +and @code{(person-sex @var{p})}. You can also change these slots by +using @code{setf} on any of these place forms: + +@example +(incf (person-age birthday-boy)) +@end example + +You can create a new @code{person} by calling @code{make-person}, +which takes keyword arguments @code{:name}, @code{:age}, and +@code{:sex} to specify the initial values of these slots in the +new object. (Omitting any of these arguments leaves the corresponding +slot ``undefined,'' according to the Common Lisp standard; in Emacs +Lisp, such uninitialized slots are filled with @code{nil}.) + +Given a @code{person}, @code{(copy-person @var{p})} makes a new +object of the same type whose slots are @code{eq} to those of @var{p}. + +Given any Lisp object @var{x}, @code{(person-p @var{x})} returns +true if @var{x} looks like a @code{person}, false otherwise. (Again, +in Common Lisp this predicate would be exact; in Emacs Lisp the +best it can do is verify that @var{x} is a vector of the correct +length which starts with the correct tag symbol.) + +Accessors like @code{person-name} normally check their arguments +(effectively using @code{person-p}) and signal an error if the +argument is the wrong type. This check is affected by +@code{(optimize (safety @dots{}))} declarations. Safety level 1, +the default, uses a somewhat optimized check that will detect all +incorrect arguments, but may use an uninformative error message +(e.g., ``expected a vector'' instead of ``expected a @code{person}''). +Safety level 0 omits all checks except as provided by the underlying +@code{aref} call; safety levels 2 and 3 do rigorous checking that will +always print a descriptive error message for incorrect inputs. +@xref{Declarations}. + +@example +(setq dave (make-person :name "Dave" :sex 'male)) + @result{} [cl-struct-person "Dave" nil male] +(setq other (copy-person dave)) + @result{} [cl-struct-person "Dave" nil male] +(eq dave other) + @result{} nil +(eq (person-name dave) (person-name other)) + @result{} t +(person-p dave) + @result{} t +(person-p [1 2 3 4]) + @result{} nil +(person-p "Bogus") + @result{} nil +(person-p '[cl-struct-person counterfeit person object]) + @result{} t +@end example + +In general, @var{name} is either a name symbol or a list of a name +symbol followed by any number of @dfn{struct options}; each @var{slot} +is either a slot symbol or a list of the form @samp{(@var{slot-name} +@var{default-value} @var{slot-options}@dots{})}. The @var{default-value} +is a Lisp form which is evaluated any time an instance of the +structure type is created without specifying that slot's value. + +Common Lisp defines several slot options, but the only one +implemented in this package is @code{:read-only}. A non-@code{nil} +value for this option means the slot should not be @code{setf}-able; +the slot's value is determined when the object is created and does +not change afterward. + +@example +(defstruct person + (name nil :read-only t) + age + (sex 'unknown)) +@end example + +Any slot options other than @code{:read-only} are ignored. + +For obscure historical reasons, structure options take a different +form than slot options. A structure option is either a keyword +symbol, or a list beginning with a keyword symbol possibly followed +by arguments. (By contrast, slot options are key-value pairs not +enclosed in lists.) + +@example +(defstruct (person (:constructor create-person) + (:type list) + :named) + name age sex) +@end example + +The following structure options are recognized. + +@table @code +@iftex +@itemmax=0 in +@advance@leftskip-.5@tableindent +@end iftex +@item :conc-name +The argument is a symbol whose print name is used as the prefix for +the names of slot accessor functions. The default is the name of +the struct type followed by a hyphen. The option @code{(:conc-name p-)} +would change this prefix to @code{p-}. Specifying @code{nil} as an +argument means no prefix, so that the slot names themselves are used +to name the accessor functions. + +@item :constructor +In the simple case, this option takes one argument which is an +alternate name to use for the constructor function. The default +is @code{make-@var{name}}, e.g., @code{make-person}. The above +example changes this to @code{create-person}. Specifying @code{nil} +as an argument means that no standard constructor should be +generated at all. + +In the full form of this option, the constructor name is followed +by an arbitrary argument list. @xref{Program Structure}, for a +description of the format of Common Lisp argument lists. All +options, such as @code{&rest} and @code{&key}, are supported. +The argument names should match the slot names; each slot is +initialized from the corresponding argument. Slots whose names +do not appear in the argument list are initialized based on the +@var{default-value} in their slot descriptor. Also, @code{&optional} +and @code{&key} arguments which don't specify defaults take their +defaults from the slot descriptor. It is valid to include arguments +which don't correspond to slot names; these are useful if they are +referred to in the defaults for optional, keyword, or @code{&aux} +arguments which @emph{do} correspond to slots. + +You can specify any number of full-format @code{:constructor} +options on a structure. The default constructor is still generated +as well unless you disable it with a simple-format @code{:constructor} +option. + +@example +(defstruct + (person + (:constructor nil) ; no default constructor + (:constructor new-person (name sex &optional (age 0))) + (:constructor new-hound (&key (name "Rover") + (dog-years 0) + &aux (age (* 7 dog-years)) + (sex 'canine)))) + name age sex) +@end example + +The first constructor here takes its arguments positionally rather +than by keyword. (In official Common Lisp terminology, constructors +that work By Order of Arguments instead of by keyword are called +``BOA constructors.'' No, I'm not making this up.) For example, +@code{(new-person "Jane" 'female)} generates a person whose slots +are @code{"Jane"}, 0, and @code{female}, respectively. + +The second constructor takes two keyword arguments, @code{:name}, +which initializes the @code{name} slot and defaults to @code{"Rover"}, +and @code{:dog-years}, which does not itself correspond to a slot +but which is used to initialize the @code{age} slot. The @code{sex} +slot is forced to the symbol @code{canine} with no syntax for +overriding it. + +@item :copier +The argument is an alternate name for the copier function for +this type. The default is @code{copy-@var{name}}. @code{nil} +means not to generate a copier function. (In this implementation, +all copier functions are simply synonyms for @code{copy-sequence}.) + +@item :predicate +The argument is an alternate name for the predicate which recognizes +objects of this type. The default is @code{@var{name}-p}. @code{nil} +means not to generate a predicate function. (If the @code{:type} +option is used without the @code{:named} option, no predicate is +ever generated.) + +In true Common Lisp, @code{typep} is always able to recognize a +structure object even if @code{:predicate} was used. In this +package, @code{typep} simply looks for a function called +@code{@var{typename}-p}, so it will work for structure types +only if they used the default predicate name. + +@item :include +This option implements a very limited form of C++-style inheritance. +The argument is the name of another structure type previously +created with @code{defstruct}. The effect is to cause the new +structure type to inherit all of the included structure's slots +(plus, of course, any new slots described by this struct's slot +descriptors). The new structure is considered a ``specialization'' +of the included one. In fact, the predicate and slot accessors +for the included type will also accept objects of the new type. + +If there are extra arguments to the @code{:include} option after +the included-structure name, these options are treated as replacement +slot descriptors for slots in the included structure, possibly with +modified default values. Borrowing an example from Steele: + +@example +(defstruct person name (age 0) sex) + @result{} person +(defstruct (astronaut (:include person (age 45))) + helmet-size + (favorite-beverage 'tang)) + @result{} astronaut + +(setq joe (make-person :name "Joe")) + @result{} [cl-struct-person "Joe" 0 nil] +(setq buzz (make-astronaut :name "Buzz")) + @result{} [cl-struct-astronaut "Buzz" 45 nil nil tang] + +(list (person-p joe) (person-p buzz)) + @result{} (t t) +(list (astronaut-p joe) (astronaut-p buzz)) + @result{} (nil t) + +(person-name buzz) + @result{} "Buzz" +(astronaut-name joe) + @result{} error: "astronaut-name accessing a non-astronaut" +@end example + +Thus, if @code{astronaut} is a specialization of @code{person}, +then every @code{astronaut} is also a @code{person} (but not the +other way around). Every @code{astronaut} includes all the slots +of a @code{person}, plus extra slots that are specific to +astronauts. Operations that work on people (like @code{person-name}) +work on astronauts just like other people. + +@item :print-function +In full Common Lisp, this option allows you to specify a function +which is called to print an instance of the structure type. The +Emacs Lisp system offers no hooks into the Lisp printer which would +allow for such a feature, so this package simply ignores +@code{:print-function}. + +@item :type +The argument should be one of the symbols @code{vector} or @code{list}. +This tells which underlying Lisp data type should be used to implement +the new structure type. Vectors are used by default, but +@code{(:type list)} will cause structure objects to be stored as +lists instead. + +The vector representation for structure objects has the advantage +that all structure slots can be accessed quickly, although creating +vectors is a bit slower in Emacs Lisp. Lists are easier to create, +but take a relatively long time accessing the later slots. + +@item :named +This option, which takes no arguments, causes a characteristic ``tag'' +symbol to be stored at the front of the structure object. Using +@code{:type} without also using @code{:named} will result in a +structure type stored as plain vectors or lists with no identifying +features. + +The default, if you don't specify @code{:type} explicitly, is to +use named vectors. Therefore, @code{:named} is only useful in +conjunction with @code{:type}. + +@example +(defstruct (person1) name age sex) +(defstruct (person2 (:type list) :named) name age sex) +(defstruct (person3 (:type list)) name age sex) + +(setq p1 (make-person1)) + @result{} [cl-struct-person1 nil nil nil] +(setq p2 (make-person2)) + @result{} (person2 nil nil nil) +(setq p3 (make-person3)) + @result{} (nil nil nil) + +(person1-p p1) + @result{} t +(person2-p p2) + @result{} t +(person3-p p3) + @result{} error: function person3-p undefined +@end example + +Since unnamed structures don't have tags, @code{defstruct} is not +able to make a useful predicate for recognizing them. Also, +accessors like @code{person3-name} will be generated but they +will not be able to do any type checking. The @code{person3-name} +function, for example, will simply be a synonym for @code{car} in +this case. By contrast, @code{person2-name} is able to verify +that its argument is indeed a @code{person2} object before +proceeding. + +@item :initial-offset +The argument must be a nonnegative integer. It specifies a +number of slots to be left ``empty'' at the front of the +structure. If the structure is named, the tag appears at the +specified position in the list or vector; otherwise, the first +slot appears at that position. Earlier positions are filled +with @code{nil} by the constructors and ignored otherwise. If +the type @code{:include}s another type, then @code{:initial-offset} +specifies a number of slots to be skipped between the last slot +of the included type and the first new slot. +@end table +@end defspec + +Except as noted, the @code{defstruct} facility of this package is +entirely compatible with that of Common Lisp. + +@iftex +@chapno=23 +@end iftex + +@node Assertions, Efficiency Concerns, Structures, Top +@chapter Assertions and Errors + +@noindent +This section describes two macros that test @dfn{assertions}, i.e., +conditions which must be true if the program is operating correctly. +Assertions never add to the behavior of a Lisp program; they simply +make ``sanity checks'' to make sure everything is as it should be. + +If the optimization property @code{speed} has been set to 3, and +@code{safety} is less than 3, then the byte-compiler will optimize +away the following assertions. Because assertions might be optimized +away, it is a bad idea for them to include side-effects. + +@defspec assert test-form [show-args string args@dots{}] +This form verifies that @var{test-form} is true (i.e., evaluates to +a non-@code{nil} value). If so, it returns @code{nil}. If the test +is not satisfied, @code{assert} signals an error. + +A default error message will be supplied which includes @var{test-form}. +You can specify a different error message by including a @var{string} +argument plus optional extra arguments. Those arguments are simply +passed to @code{error} to signal the error. + +If the optional second argument @var{show-args} is @code{t} instead +of @code{nil}, then the error message (with or without @var{string}) +will also include all non-constant arguments of the top-level +@var{form}. For example: + +@example +(assert (> x 10) t "x is too small: %d") +@end example + +This usage of @var{show-args} is an extension to Common Lisp. In +true Common Lisp, the second argument gives a list of @var{places} +which can be @code{setf}'d by the user before continuing from the +error. Since Emacs Lisp does not support continuable errors, it +makes no sense to specify @var{places}. +@end defspec + +@defspec check-type form type [string] +This form verifies that @var{form} evaluates to a value of type +@var{type}. If so, it returns @code{nil}. If not, @code{check-type} +signals a @code{wrong-type-argument} error. The default error message +lists the erroneous value along with @var{type} and @var{form} +themselves. If @var{string} is specified, it is included in the +error message in place of @var{type}. For example: + +@example +(check-type x (integer 1 *) "a positive integer") +@end example + +@xref{Type Predicates}, for a description of the type specifiers +that may be used for @var{type}. + +Note that in Common Lisp, the first argument to @code{check-type} +must be a @var{place} suitable for use by @code{setf}, because +@code{check-type} signals a continuable error that allows the +user to modify @var{place}. +@end defspec + +The following error-related macro is also defined: + +@defspec ignore-errors forms@dots{} +This executes @var{forms} exactly like a @code{progn}, except that +errors are ignored during the @var{forms}. More precisely, if +an error is signaled then @code{ignore-errors} immediately +aborts execution of the @var{forms} and returns @code{nil}. +If the @var{forms} complete successfully, @code{ignore-errors} +returns the result of the last @var{form}. +@end defspec + +@node Efficiency Concerns, Common Lisp Compatibility, Assertions, Top +@appendix Efficiency Concerns + +@appendixsec Macros + +@noindent +Many of the advanced features of this package, such as @code{defun*}, +@code{loop}, and @code{setf}, are implemented as Lisp macros. In +byte-compiled code, these complex notations will be expanded into +equivalent Lisp code which is simple and efficient. For example, +the forms + +@example +(incf i n) +(push x (car p)) +@end example + +@noindent +are expanded at compile-time to the Lisp forms + +@example +(setq i (+ i n)) +(setcar p (cons x (car p))) +@end example + +@noindent +which are the most efficient ways of doing these respective operations +in Lisp. Thus, there is no performance penalty for using the more +readable @code{incf} and @code{push} forms in your compiled code. + +@emph{Interpreted} code, on the other hand, must expand these macros +every time they are executed. For this reason it is strongly +recommended that code making heavy use of macros be compiled. +(The features labeled ``Special Form'' instead of ``Function'' in +this manual are macros.) A loop using @code{incf} a hundred times +will execute considerably faster if compiled, and will also +garbage-collect less because the macro expansion will not have +to be generated, used, and thrown away a hundred times. + +You can find out how a macro expands by using the +@code{cl-prettyexpand} function. + +@defun cl-prettyexpand form &optional full +This function takes a single Lisp form as an argument and inserts +a nicely formatted copy of it in the current buffer (which must be +in Lisp mode so that indentation works properly). It also expands +all Lisp macros which appear in the form. The easiest way to use +this function is to go to the @code{*scratch*} buffer and type, say, + +@example +(cl-prettyexpand '(loop for x below 10 collect x)) +@end example + +@noindent +and type @kbd{C-x C-e} immediately after the closing parenthesis; +the expansion + +@example +(block nil + (let* ((x 0) + (G1004 nil)) + (while (< x 10) + (setq G1004 (cons x G1004)) + (setq x (+ x 1))) + (nreverse G1004))) +@end example + +@noindent +will be inserted into the buffer. (The @code{block} macro is +expanded differently in the interpreter and compiler, so +@code{cl-prettyexpand} just leaves it alone. The temporary +variable @code{G1004} was created by @code{gensym}.) + +If the optional argument @var{full} is true, then @emph{all} +macros are expanded, including @code{block}, @code{eval-when}, +and compiler macros. Expansion is done as if @var{form} were +a top-level form in a file being compiled. For example, + +@example +(cl-prettyexpand '(pushnew 'x list)) + @print{} (setq list (adjoin 'x list)) +(cl-prettyexpand '(pushnew 'x list) t) + @print{} (setq list (if (memq 'x list) list (cons 'x list))) +(cl-prettyexpand '(caddr (member* 'a list)) t) + @print{} (car (cdr (cdr (memq 'a list)))) +@end example + +Note that @code{adjoin}, @code{caddr}, and @code{member*} all +have built-in compiler macros to optimize them in common cases. +@end defun + +@ifinfo +@example + +@end example +@end ifinfo +@appendixsec Error Checking + +@noindent +Common Lisp compliance has in general not been sacrificed for the +sake of efficiency. A few exceptions have been made for cases +where substantial gains were possible at the expense of marginal +incompatibility. + +The Common Lisp standard (as embodied in Steele's book) uses the +phrase ``it is an error if'' to indicate a situation which is not +supposed to arise in complying programs; implementations are strongly +encouraged but not required to signal an error in these situations. +This package sometimes omits such error checking in the interest of +compactness and efficiency. For example, @code{do} variable +specifiers are supposed to be lists of one, two, or three forms; +extra forms are ignored by this package rather than signaling a +syntax error. The @code{endp} function is simply a synonym for +@code{null} in this package. Functions taking keyword arguments +will accept an odd number of arguments, treating the trailing +keyword as if it were followed by the value @code{nil}. + +Argument lists (as processed by @code{defun*} and friends) +@emph{are} checked rigorously except for the minor point just +mentioned; in particular, keyword arguments are checked for +validity, and @code{&allow-other-keys} and @code{:allow-other-keys} +are fully implemented. Keyword validity checking is slightly +time consuming (though not too bad in byte-compiled code); +you can use @code{&allow-other-keys} to omit this check. Functions +defined in this package such as @code{find} and @code{member*} +do check their keyword arguments for validity. + +@ifinfo +@example + +@end example +@end ifinfo +@appendixsec Optimizing Compiler + +@noindent +Use of the optimizing Emacs compiler is highly recommended; many of the Common +Lisp macros emit +code which can be improved by optimization. In particular, +@code{block}s (whether explicit or implicit in constructs like +@code{defun*} and @code{loop}) carry a fair run-time penalty; the +optimizing compiler removes @code{block}s which are not actually +referenced by @code{return} or @code{return-from} inside the block. + +@node Common Lisp Compatibility, Old CL Compatibility, Efficiency Concerns, Top +@appendix Common Lisp Compatibility + +@noindent +Following is a list of all known incompatibilities between this +package and Common Lisp as documented in Steele (2nd edition). + +Certain function names, such as @code{member}, @code{assoc}, and +@code{floor}, were already taken by (incompatible) Emacs Lisp +functions; this package appends @samp{*} to the names of its +Common Lisp versions of these functions. + +The word @code{defun*} is required instead of @code{defun} in order +to use extended Common Lisp argument lists in a function. Likewise, +@code{defmacro*} and @code{function*} are versions of those forms +which understand full-featured argument lists. The @code{&whole} +keyword does not work in @code{defmacro} argument lists (except +inside recursive argument lists). + +The @code{eql} and @code{equal} predicates do not distinguish +between IEEE floating-point plus and minus zero. The @code{equalp} +predicate has several differences with Common Lisp; @pxref{Predicates}. + +The @code{setf} mechanism is entirely compatible, except that +setf-methods return a list of five values rather than five +values directly. Also, the new ``@code{setf} function'' concept +(typified by @code{(defun (setf foo) @dots{})}) is not implemented. + +The @code{do-all-symbols} form is the same as @code{do-symbols} +with no @var{obarray} argument. In Common Lisp, this form would +iterate over all symbols in all packages. Since Emacs obarrays +are not a first-class package mechanism, there is no way for +@code{do-all-symbols} to locate any but the default obarray. + +The @code{loop} macro is complete except that @code{loop-finish} +and type specifiers are unimplemented. + +The multiple-value return facility treats lists as multiple +values, since Emacs Lisp cannot support multiple return values +directly. The macros will be compatible with Common Lisp if +@code{values} or @code{values-list} is always used to return to +a @code{multiple-value-bind} or other multiple-value receiver; +if @code{values} is used without @code{multiple-value-@dots{}} +or vice-versa the effect will be different from Common Lisp. + +Many Common Lisp declarations are ignored, and others match +the Common Lisp standard in concept but not in detail. For +example, local @code{special} declarations, which are purely +advisory in Emacs Lisp, do not rigorously obey the scoping rules +set down in Steele's book. + +The variable @code{*gensym-counter*} starts out with a pseudo-random +value rather than with zero. This is to cope with the fact that +generated symbols become interned when they are written to and +loaded back from a file. + +The @code{defstruct} facility is compatible, except that structures +are of type @code{:type vector :named} by default rather than some +special, distinct type. Also, the @code{:type} slot option is ignored. + +The second argument of @code{check-type} is treated differently. + +@node Old CL Compatibility, Porting Common Lisp, Common Lisp Compatibility, Top +@appendix Old CL Compatibility + +@noindent +Following is a list of all known incompatibilities between this package +and the older Quiroz @file{cl.el} package. + +This package's emulation of multiple return values in functions is +incompatible with that of the older package. That package attempted +to come as close as possible to true Common Lisp multiple return +values; unfortunately, it could not be 100% reliable and so was prone +to occasional surprises if used freely. This package uses a simpler +method, namely replacing multiple values with lists of values, which +is more predictable though more noticeably different from Common Lisp. + +The @code{defkeyword} form and @code{keywordp} function are not +implemented in this package. + +The @code{member}, @code{floor}, @code{ceiling}, @code{truncate}, +@code{round}, @code{mod}, and @code{rem} functions are suffixed +by @samp{*} in this package to avoid collision with existing +functions in Emacs. The older package simply +redefined these functions, overwriting the built-in meanings and +causing serious portability problems. (Some more +recent versions of the Quiroz package changed the names to +@code{cl-member}, etc.; this package defines the latter names as +aliases for @code{member*}, etc.) + +Certain functions in the old package which were buggy or inconsistent +with the Common Lisp standard are incompatible with the conforming +versions in this package. For example, @code{eql} and @code{member} +were synonyms for @code{eq} and @code{memq} in that package, @code{setf} +failed to preserve correct order of evaluation of its arguments, etc. + +Finally, unlike the older package, this package is careful to +prefix all of its internal names with @code{cl-}. Except for a +few functions which are explicitly defined as additional features +(such as @code{floatp-safe} and @code{letf}), this package does not +export any non-@samp{cl-} symbols which are not also part of Common +Lisp. + +@ifinfo +@example + +@end example +@end ifinfo +@appendixsec The @code{cl-compat} package + +@noindent +The @dfn{CL} package includes emulations of some features of the +old @file{cl.el}, in the form of a compatibility package +@code{cl-compat}. To use it, put @code{(require 'cl-compat)} in +your program. + +The old package defined a number of internal routines without +@code{cl-} prefixes or other annotations. Call to these routines +may have crept into existing Lisp code. @code{cl-compat} +provides emulations of the following internal routines: +@code{pair-with-newsyms}, @code{zip-lists}, @code{unzip-lists}, +@code{reassemble-arglists}, @code{duplicate-symbols-p}, +@code{safe-idiv}. + +Some @code{setf} forms translated into calls to internal +functions that user code might call directly. The functions +@code{setnth}, @code{setnthcdr}, and @code{setelt} fall in +this category; they are defined by @code{cl-compat}, but the +best fix is to change to use @code{setf} properly. + +The @code{cl-compat} file defines the keyword functions +@code{keywordp}, @code{keyword-of}, and @code{defkeyword}, +which are not defined by the new @dfn{CL} package because the +use of keywords as data is discouraged. + +The @code{build-klist} mechanism for parsing keyword arguments +is emulated by @code{cl-compat}; the @code{with-keyword-args} +macro is not, however, and in any case it's best to change to +use the more natural keyword argument processing offered by +@code{defun*}. + +Multiple return values are treated differently by the two +Common Lisp packages. The old package's method was more +compatible with true Common Lisp, though it used heuristics +that caused it to report spurious multiple return values in +certain cases. The @code{cl-compat} package defines a set +of multiple-value macros that are compatible with the old +CL package; again, they are heuristic in nature, but they +are guaranteed to work in any case where the old package's +macros worked. To avoid name collision with the ``official'' +multiple-value facilities, the ones in @code{cl-compat} have +capitalized names: @code{Values}, @code{Values-list}, +@code{Multiple-value-bind}, etc. + +The functions @code{cl-floor}, @code{cl-ceiling}, @code{cl-truncate}, +and @code{cl-round} are defined by @code{cl-compat} to use the +old-style multiple-value mechanism, just as they did in the old +package. The newer @code{floor*} and friends return their two +results in a list rather than as multiple values. Note that +older versions of the old package used the unadorned names +@code{floor}, @code{ceiling}, etc.; @code{cl-compat} cannot use +these names because they conflict with Emacs built-ins. + +@node Porting Common Lisp, GNU Free Documentation License, Old CL Compatibility, Top +@appendix Porting Common Lisp + +@noindent +This package is meant to be used as an extension to Emacs Lisp, +not as an Emacs implementation of true Common Lisp. Some of the +remaining differences between Emacs Lisp and Common Lisp make it +difficult to port large Common Lisp applications to Emacs. For +one, some of the features in this package are not fully compliant +with ANSI or Steele; @pxref{Common Lisp Compatibility}. But there +are also quite a few features that this package does not provide +at all. Here are some major omissions that you will want to watch out +for when bringing Common Lisp code into Emacs. + +@itemize @bullet +@item +Case-insensitivity. Symbols in Common Lisp are case-insensitive +by default. Some programs refer to a function or variable as +@code{foo} in one place and @code{Foo} or @code{FOO} in another. +Emacs Lisp will treat these as three distinct symbols. + +Some Common Lisp code is written entirely in upper case. While Emacs +is happy to let the program's own functions and variables use +this convention, calls to Lisp builtins like @code{if} and +@code{defun} will have to be changed to lower case. + +@item +Lexical scoping. In Common Lisp, function arguments and @code{let} +bindings apply only to references physically within their bodies +(or within macro expansions in their bodies). Emacs Lisp, by +contrast, uses @dfn{dynamic scoping} wherein a binding to a +variable is visible even inside functions called from the body. + +Variables in Common Lisp can be made dynamically scoped by +declaring them @code{special} or using @code{defvar}. In Emacs +Lisp it is as if all variables were declared @code{special}. + +Often you can use code that was written for lexical scoping +even in a dynamically scoped Lisp, but not always. Here is +an example of a Common Lisp code fragment that would fail in +Emacs Lisp: + +@example +(defun map-odd-elements (func list) + (loop for x in list + for flag = t then (not flag) + collect (if flag x (funcall func x)))) + +(defun add-odd-elements (list x) + (map-odd-elements (lambda (a) (+ a x))) list) +@end example + +@noindent +In Common Lisp, the two functions' usages of @code{x} are completely +independent. In Emacs Lisp, the binding to @code{x} made by +@code{add-odd-elements} will have been hidden by the binding +in @code{map-odd-elements} by the time the @code{(+ a x)} function +is called. + +(This package avoids such problems in its own mapping functions +by using names like @code{cl-x} instead of @code{x} internally; +as long as you don't use the @code{cl-} prefix for your own +variables no collision can occur.) + +@xref{Lexical Bindings}, for a description of the @code{lexical-let} +form which establishes a Common Lisp-style lexical binding, and some +examples of how it differs from Emacs' regular @code{let}. + +@item +Reader macros. Common Lisp includes a second type of macro that +works at the level of individual characters. For example, Common +Lisp implements the quote notation by a reader macro called @code{'}, +whereas Emacs Lisp's parser just treats quote as a special case. +Some Lisp packages use reader macros to create special syntaxes +for themselves, which the Emacs parser is incapable of reading. + +The lack of reader macros, incidentally, is the reason behind +Emacs Lisp's unusual backquote syntax. Since backquotes are +implemented as a Lisp package and not built-in to the Emacs +parser, they are forced to use a regular macro named @code{`} +which is used with the standard function/macro call notation. + +@item +Other syntactic features. Common Lisp provides a number of +notations beginning with @code{#} that the Emacs Lisp parser +won't understand. For example, @samp{#| ... |#} is an +alternate comment notation, and @samp{#+lucid (foo)} tells +the parser to ignore the @code{(foo)} except in Lucid Common +Lisp. + +@item +Packages. In Common Lisp, symbols are divided into @dfn{packages}. +Symbols that are Lisp built-ins are typically stored in one package; +symbols that are vendor extensions are put in another, and each +application program would have a package for its own symbols. +Certain symbols are ``exported'' by a package and others are +internal; certain packages ``use'' or import the exported symbols +of other packages. To access symbols that would not normally be +visible due to this importing and exporting, Common Lisp provides +a syntax like @code{package:symbol} or @code{package::symbol}. + +Emacs Lisp has a single namespace for all interned symbols, and +then uses a naming convention of putting a prefix like @code{cl-} +in front of the name. Some Emacs packages adopt the Common Lisp-like +convention of using @code{cl:} or @code{cl::} as the prefix. +However, the Emacs parser does not understand colons and just +treats them as part of the symbol name. Thus, while @code{mapcar} +and @code{lisp:mapcar} may refer to the same symbol in Common +Lisp, they are totally distinct in Emacs Lisp. Common Lisp +programs which refer to a symbol by the full name sometimes +and the short name other times will not port cleanly to Emacs. + +Emacs Lisp does have a concept of ``obarrays,'' which are +package-like collections of symbols, but this feature is not +strong enough to be used as a true package mechanism. + +@item +The @code{format} function is quite different between Common +Lisp and Emacs Lisp. It takes an additional ``destination'' +argument before the format string. A destination of @code{nil} +means to format to a string as in Emacs Lisp; a destination +of @code{t} means to write to the terminal (similar to +@code{message} in Emacs). Also, format control strings are +utterly different; @code{~} is used instead of @code{%} to +introduce format codes, and the set of available codes is +much richer. There are no notations like @code{\n} for +string literals; instead, @code{format} is used with the +``newline'' format code, @code{~%}. More advanced formatting +codes provide such features as paragraph filling, case +conversion, and even loops and conditionals. + +While it would have been possible to implement most of Common +Lisp @code{format} in this package (under the name @code{format*}, +of course), it was not deemed worthwhile. It would have required +a huge amount of code to implement even a decent subset of +@code{format*}, yet the functionality it would provide over +Emacs Lisp's @code{format} would rarely be useful. + +@item +Vector constants use square brackets in Emacs Lisp, but +@code{#(a b c)} notation in Common Lisp. To further complicate +matters, Emacs has its own @code{#(} notation for +something entirely different---strings with properties. + +@item +Characters are distinct from integers in Common Lisp. The +notation for character constants is also different: @code{#\A} +instead of @code{?A}. Also, @code{string=} and @code{string-equal} +are synonyms in Emacs Lisp whereas the latter is case-insensitive +in Common Lisp. + +@item +Data types. Some Common Lisp data types do not exist in Emacs +Lisp. Rational numbers and complex numbers are not present, +nor are large integers (all integers are ``fixnums''). All +arrays are one-dimensional. There are no readtables or pathnames; +streams are a set of existing data types rather than a new data +type of their own. Hash tables, random-states, structures, and +packages (obarrays) are built from Lisp vectors or lists rather +than being distinct types. + +@item +The Common Lisp Object System (CLOS) is not implemented, +nor is the Common Lisp Condition System. However, the EIEIO package +from @uref{ftp://ftp.ultranet.com/pub/zappo} does implement some +CLOS functionality. + +@item +Common Lisp features that are completely redundant with Emacs +Lisp features of a different name generally have not been +implemented. For example, Common Lisp writes @code{defconstant} +where Emacs Lisp uses @code{defconst}. Similarly, @code{make-list} +takes its arguments in different ways in the two Lisps but does +exactly the same thing, so this package has not bothered to +implement a Common Lisp-style @code{make-list}. + +@item +A few more notable Common Lisp features not included in this +package: @code{compiler-let}, @code{tagbody}, @code{prog}, +@code{ldb/dpb}, @code{parse-integer}, @code{cerror}. + +@item +Recursion. While recursion works in Emacs Lisp just like it +does in Common Lisp, various details of the Emacs Lisp system +and compiler make recursion much less efficient than it is in +most Lisps. Some schools of thought prefer to use recursion +in Lisp over other techniques; they would sum a list of +numbers using something like + +@example +(defun sum-list (list) + (if list + (+ (car list) (sum-list (cdr list))) + 0)) +@end example + +@noindent +where a more iteratively-minded programmer might write one of +these forms: + +@example +(let ((total 0)) (dolist (x my-list) (incf total x)) total) +(loop for x in my-list sum x) +@end example + +While this would be mainly a stylistic choice in most Common Lisps, +in Emacs Lisp you should be aware that the iterative forms are +much faster than recursion. Also, Lisp programmers will want to +note that the current Emacs Lisp compiler does not optimize tail +recursion. +@end itemize + +@node GNU Free Documentation License, Function Index, Porting Common Lisp, Top +@appendix GNU Free Documentation License +@include doclicense.texi + +@node Function Index, Variable Index, GNU Free Documentation License, Top +@unnumbered Function Index + +@printindex fn + +@node Variable Index, , Function Index, Top +@unnumbered Variable Index + +@printindex vr + +@setchapternewpage odd +@contents +@bye + +@ignore + arch-tag: b61e7200-3bfa-4a70-a9d3-095e152696f8 +@end ignore