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