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