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