1 This is ../info/cl.info, produced by makeinfo version 4.0 from cl.texi.
3 INFO-DIR-SECTION XEmacs Editor
5 * Common Lisp: (cl). GNU Emacs Common Lisp emulation package.
8 This file documents the GNU Emacs Common Lisp emulation package.
10 Copyright (C) 1993 Free Software Foundation, Inc.
12 Permission is granted to make and distribute verbatim copies of this
13 manual provided the copyright notice and this permission notice are
14 preserved on all copies.
16 Permission is granted to copy and distribute modified versions of
17 this manual under the conditions for verbatim copying, provided also
18 that the section entitled "GNU General Public License" is included
19 exactly as in the original, and provided that the entire resulting
20 derived work is distributed under the terms of a permission notice
21 identical to this one.
23 Permission is granted to copy and distribute translations of this
24 manual into another language, under the above conditions for modified
25 versions, except that the section entitled "GNU General Public License"
26 may be included in a translation approved by the author instead of in
30 File: cl.info, Node: Top, Next: Overview, Up: (dir)
32 Common Lisp Extensions
33 **********************
35 This document describes a set of Emacs Lisp facilities borrowed from
36 Common Lisp. All the facilities are described here in detail; for more
37 discussion and examples, Guy L. Steele's `Common Lisp, the Language',
38 second edition, is the definitive book on Common Lisp. While this
39 document does not assume any prior knowledge of Common Lisp, it does
40 assume a basic familiarity with Emacs Lisp.
44 * Overview:: Installation, usage, etc.
45 * Program Structure:: Arglists, `eval-when', `defalias'
46 * Predicates:: `typep', `eql', and `equalp'
47 * Control Structure:: `setf', `when', `do', `loop', etc.
48 * Macros:: Destructuring, `define-compiler-macro'
49 * Declarations:: `proclaim', `declare', etc.
50 * Symbols:: Property lists, `gensym'
51 * Numbers:: Predicates, functions, random numbers
52 * Sequences:: Mapping, functions, searching, sorting
53 * Lists:: `cadr', `sublis', `member*', `assoc*', etc.
54 * Hash Tables:: `make-hash-table', `gethash', etc.
55 * Structures:: `defstruct'
56 * Assertions:: `check-type', `assert', `ignore-errors'.
58 * Efficiency Concerns:: Hints and techniques
59 * Common Lisp Compatibility:: All known differences with Steele
60 * Old CL Compatibility:: All known differences with old cl.el
61 * Porting Common Lisp:: Hints for porting Common Lisp code
67 File: cl.info, Node: Overview, Next: Program Structure, Prev: Top, Up: Top
72 Common Lisp is a huge language, and Common Lisp systems tend to be
73 massive and extremely complex. Emacs Lisp, by contrast, is rather
74 minimalist in the choice of Lisp features it offers the programmer. As
75 Emacs Lisp programmers have grown in number, and the applications they
76 write have grown more ambitious, it has become clear that Emacs Lisp
77 could benefit from many of the conveniences of Common Lisp.
79 The "CL" package adds a number of Common Lisp functions and control
80 structures to Emacs Lisp. While not a 100% complete implementation of
81 Common Lisp, "CL" adds enough functionality to make Emacs Lisp
82 programming significantly more convenient.
84 Some Common Lisp features have been omitted from this package for
87 * Some features are too complex or bulky relative to their benefit
88 to Emacs Lisp programmers. CLOS and Common Lisp streams are fine
89 examples of this group.
91 * Other features cannot be implemented without modification to the
92 Emacs Lisp interpreter itself, such as multiple return values,
93 lexical scoping, case-insensitive symbols, and complex numbers.
94 The "CL" package generally makes no attempt to emulate these
97 * Some features conflict with existing things in Emacs Lisp. For
98 example, Emacs' `assoc' function is incompatible with the Common
99 Lisp `assoc'. In such cases, this package usually adds the suffix
100 `*' to the function name of the Common Lisp version of the
101 function (e.g., `assoc*').
103 The package described here was written by Dave Gillespie,
104 `daveg@synaptics.com'. It is a total rewrite of the original 1986
105 `cl.el' package by Cesar Quiroz. Most features of the Quiroz package
106 have been retained; any incompatibilities are noted in the descriptions
107 below. Care has been taken in this version to ensure that each
108 function is defined efficiently, concisely, and with minimal impact on
109 the rest of the Emacs environment.
113 * Usage:: How to use the CL package
114 * Organization:: The package's five component files
115 * Installation:: Compiling and installing CL
116 * Naming Conventions:: Notes on CL function names
119 File: cl.info, Node: Usage, Next: Organization, Prev: Overview, Up: Overview
124 Lisp code that uses features from the "CL" package should include at
129 If you want to ensure that the new (Gillespie) version of "CL" is the
130 one that is present, add an additional `(require 'cl-19)' call:
135 The second call will fail (with "`cl-19.el' not found") if the old
136 `cl.el' package was in use.
138 It is safe to arrange to load "CL" at all times, e.g., in your
139 `.emacs' file. But it's a good idea, for portability, to `(require
140 'cl)' in your code even if you do this.
143 File: cl.info, Node: Organization, Next: Installation, Prev: Usage, Up: Overview
148 The Common Lisp package is organized into four files:
151 This is the "main" file, which contains basic functions and
152 information about the package. This file is relatively
153 compact--about 700 lines.
156 This file contains the larger, more complex or unusual functions.
157 It is kept separate so that packages which only want to use Common
158 Lisp fundamentals like the `cadr' function won't need to pay the
159 overhead of loading the more advanced functions.
162 This file contains most of the advanced functions for operating on
163 sequences or lists, such as `delete-if' and `assoc*'.
166 This file contains the features of the packages which are macros
167 instead of functions. Macros expand when the caller is compiled,
168 not when it is run, so the macros generally only need to be
169 present when the byte-compiler is running (or when the macros are
170 used in uncompiled code such as a `.emacs' file). Most of the
171 macros of this package are isolated in `cl-macs.el' so that they
172 won't take up memory unless you are compiling.
174 The file `cl.el' includes all necessary `autoload' commands for the
175 functions and macros in the other three files. All you have to do is
176 `(require 'cl)', and `cl.el' will take care of pulling in the other
177 files when they are needed.
179 There is another file, `cl-compat.el', which defines some routines
180 from the older `cl.el' package that are no longer present in the new
181 package. This includes internal routines like `setelt' and
182 `zip-lists', deprecated features like `defkeyword', and an emulation of
183 the old-style multiple-values feature. *Note Old CL Compatibility::.
186 File: cl.info, Node: Installation, Next: Naming Conventions, Prev: Organization, Up: Overview
191 Installation of the "CL" package is simple: Just put the byte-compiled
192 files `cl.elc', `cl-extra.elc', `cl-seq.elc', `cl-macs.elc', and
193 `cl-compat.elc' into a directory on your `load-path'.
195 There are no special requirements to compile this package: The files
196 do not have to be loaded before they are compiled, nor do they need to
197 be compiled in any particular order.
199 You may choose to put the files into your main `lisp/' directory,
200 replacing the original `cl.el' file there. Or, you could put them into
201 a directory that comes before `lisp/' on your `load-path' so that the
202 old `cl.el' is effectively hidden.
204 Also, format the `cl.texinfo' file and put the resulting Info files
205 in the `info/' directory or another suitable place.
207 You may instead wish to leave this package's components all in their
208 own directory, and then add this directory to your `load-path' and
209 (Emacs 19 only) `Info-directory-list'. Add the directory to the front
210 of the list so the old "CL" package and its documentation are hidden.
213 File: cl.info, Node: Naming Conventions, Prev: Installation, Up: Overview
218 Except where noted, all functions defined by this package have the same
219 names and calling conventions as their Common Lisp counterparts.
221 Following is a complete list of functions whose names were changed
222 from Common Lisp, usually to avoid conflicts with Emacs. In each case,
223 a `*' has been appended to the Common Lisp name to obtain the Emacs
226 defun* defsubst* defmacro* function*
227 member* assoc* rassoc* remove*
228 delete* mapcar* sort* floor*
229 ceiling* truncate* round* mod*
232 Internal function and variable names in the package are prefixed by
233 `cl-'. Here is a complete list of functions _not_ prefixed by `cl-'
234 which were not taken from Common Lisp:
236 member delete remove remq
237 rassoc floatp-safe lexical-let lexical-let*
238 callf callf2 letf letf*
239 defsubst* defalias add-hook eval-when-compile
241 (Most of these are Emacs 19 features provided to Emacs 18 users, or
242 introduced, like `remq', for reasons of symmetry with similar features.)
244 The following simple functions and macros are defined in `cl.el';
245 they do not cause other components like `cl-extra' to be loaded.
247 eql floatp-safe abs endp
248 evenp oddp plusp minusp
249 last butlast nbutlast caar .. cddddr
250 list* ldiff rest first .. tenth
251 member [1] copy-list subst mapcar* [2]
252 adjoin [3] acons pairlis when
253 unless pop [4] push [4] pushnew [3,4]
254 incf [4] decf [4] proclaim declaim
257 [1] This is the Emacs 19-compatible function, not `member*'.
259 [2] Only for one sequence argument or two list arguments.
261 [3] Only if `:test' is `eq', `equal', or unspecified, and `:key' is not
264 [4] Only when PLACE is a plain variable name.
267 File: cl.info, Node: Program Structure, Next: Predicates, Prev: Overview, Up: Top
272 This section describes features of the "CL" package which have to do
273 with programs as a whole: advanced argument lists for functions, and
274 the `eval-when' construct.
278 * Argument Lists:: `&key', `&aux', `defun*', `defmacro*'.
279 * Time of Evaluation:: The `eval-when' construct.
280 * Function Aliases:: The `defalias' function.
283 File: cl.info, Node: Argument Lists, Next: Time of Evaluation, Prev: Program Structure, Up: Program Structure
288 Emacs Lisp's notation for argument lists of functions is a subset of
289 the Common Lisp notation. As well as the familiar `&optional' and
290 `&rest' markers, Common Lisp allows you to specify default values for
291 optional arguments, and it provides the additional markers `&key' and
294 Since argument parsing is built-in to Emacs, there is no way for
295 this package to implement Common Lisp argument lists seamlessly.
296 Instead, this package defines alternates for several Lisp forms which
297 you must use if you need Common Lisp argument lists.
299 - Special Form: defun* name arglist body...
300 This form is identical to the regular `defun' form, except that
301 ARGLIST is allowed to be a full Common Lisp argument list. Also,
302 the function body is enclosed in an implicit block called NAME;
303 *note Blocks and Exits::.
305 - Special Form: defsubst* name arglist body...
306 This is just like `defun*', except that the function that is
307 defined is automatically proclaimed `inline', i.e., calls to it
308 may be expanded into in-line code by the byte compiler. This is
309 analogous to the `defsubst' form in Emacs 19; `defsubst*' uses a
310 different method (compiler macros) which works in all version of
311 Emacs, and also generates somewhat more efficient inline
312 expansions. In particular, `defsubst*' arranges for the
313 processing of keyword arguments, default values, etc., to be done
314 at compile-time whenever possible.
316 - Special Form: defmacro* name arglist body...
317 This is identical to the regular `defmacro' form, except that
318 ARGLIST is allowed to be a full Common Lisp argument list. The
319 `&environment' keyword is supported as described in Steele. The
320 `&whole' keyword is supported only within destructured lists (see
321 below); top-level `&whole' cannot be implemented with the current
322 Emacs Lisp interpreter. The macro expander body is enclosed in an
323 implicit block called NAME.
325 - Special Form: function* symbol-or-lambda
326 This is identical to the regular `function' form, except that if
327 the argument is a `lambda' form then that form may use a full
328 Common Lisp argument list.
330 Also, all forms (such as `defsetf' and `flet') defined in this
331 package that include ARGLISTs in their syntax allow full Common Lisp
334 Note that it is _not_ necessary to use `defun*' in order to have
335 access to most "CL" features in your function. These features are
336 always present; `defun*''s only difference from `defun' is its more
337 flexible argument lists and its implicit block.
339 The full form of a Common Lisp argument list is
342 &optional (VAR INITFORM SVAR)...
344 &key ((KEYWORD VAR) INITFORM SVAR)...
345 &aux (VAR INITFORM)...)
347 Each of the five argument list sections is optional. The SVAR,
348 INITFORM, and KEYWORD parts are optional; if they are omitted, then
349 `(VAR)' may be written simply `VAR'.
351 The first section consists of zero or more "required" arguments.
352 These arguments must always be specified in a call to the function;
353 there is no difference between Emacs Lisp and Common Lisp as far as
354 required arguments are concerned.
356 The second section consists of "optional" arguments. These
357 arguments may be specified in the function call; if they are not,
358 INITFORM specifies the default value used for the argument. (No
359 INITFORM means to use `nil' as the default.) The INITFORM is evaluated
360 with the bindings for the preceding arguments already established; `(a
361 &optional (b (1+ a)))' matches one or two arguments, with the second
362 argument defaulting to one plus the first argument. If the SVAR is
363 specified, it is an auxiliary variable which is bound to `t' if the
364 optional argument was specified, or to `nil' if the argument was
365 omitted. If you don't use an SVAR, then there will be no way for your
366 function to tell whether it was called with no argument, or with the
367 default value passed explicitly as an argument.
369 The third section consists of a single "rest" argument. If more
370 arguments were passed to the function than are accounted for by the
371 required and optional arguments, those extra arguments are collected
372 into a list and bound to the "rest" argument variable. Common Lisp's
373 `&rest' is equivalent to that of Emacs Lisp. Common Lisp accepts
374 `&body' as a synonym for `&rest' in macro contexts; this package
375 accepts it all the time.
377 The fourth section consists of "keyword" arguments. These are
378 optional arguments which are specified by name rather than positionally
379 in the argument list. For example,
381 (defun* foo (a &optional b &key c d (e 17)))
383 defines a function which may be called with one, two, or more
384 arguments. The first two arguments are bound to `a' and `b' in the
385 usual way. The remaining arguments must be pairs of the form `:c',
386 `:d', or `:e' followed by the value to be bound to the corresponding
387 argument variable. (Symbols whose names begin with a colon are called
388 "keywords", and they are self-quoting in the same way as `nil' and `t'.)
390 For example, the call `(foo 1 2 :d 3 :c 4)' sets the five arguments
391 to 1, 2, 4, 3, and 17, respectively. If the same keyword appears more
392 than once in the function call, the first occurrence takes precedence
393 over the later ones. Note that it is not possible to specify keyword
394 arguments without specifying the optional argument `b' as well, since
395 `(foo 1 :c 2)' would bind `b' to the keyword `:c', then signal an error
396 because `2' is not a valid keyword.
398 If a KEYWORD symbol is explicitly specified in the argument list as
399 shown in the above diagram, then that keyword will be used instead of
400 just the variable name prefixed with a colon. You can specify a
401 KEYWORD symbol which does not begin with a colon at all, but such
402 symbols will not be self-quoting; you will have to quote them
403 explicitly with an apostrophe in the function call.
405 Ordinarily it is an error to pass an unrecognized keyword to a
406 function, e.g., `(foo 1 2 :c 3 :goober 4)'. You can ask Lisp to ignore
407 unrecognized keywords, either by adding the marker `&allow-other-keys'
408 after the keyword section of the argument list, or by specifying an
409 `:allow-other-keys' argument in the call whose value is non-`nil'. If
410 the function uses both `&rest' and `&key' at the same time, the "rest"
411 argument is bound to the keyword list as it appears in the call. For
414 (defun* find-thing (thing &rest rest &key need &allow-other-keys)
415 (or (apply 'member* thing thing-list :allow-other-keys t rest)
416 (if need (error "Thing not found"))))
418 This function takes a `:need' keyword argument, but also accepts other
419 keyword arguments which are passed on to the `member*' function.
420 `allow-other-keys' is used to keep both `find-thing' and `member*' from
421 complaining about each others' keywords in the arguments.
423 As a (significant) performance optimization, this package implements
424 the scan for keyword arguments by calling `memq' to search for keywords
425 in a "rest" argument. Technically speaking, this is incorrect, since
426 `memq' looks at the odd-numbered values as well as the even-numbered
427 keywords. The net effect is that if you happen to pass a keyword symbol
428 as the _value_ of another keyword argument, where that keyword symbol
429 happens to equal the name of a valid keyword argument of the same
430 function, then the keyword parser will become confused. This minor bug
431 can only affect you if you use keyword symbols as general-purpose data
432 in your program; this practice is strongly discouraged in Emacs Lisp.
434 The fifth section of the argument list consists of "auxiliary
435 variables". These are not really arguments at all, but simply
436 variables which are bound to `nil' or to the specified INITFORMS during
437 execution of the function. There is no difference between the
438 following two functions, except for a matter of stylistic taste:
440 (defun* foo (a b &aux (c (+ a b)) d)
447 Argument lists support "destructuring". In Common Lisp,
448 destructuring is only allowed with `defmacro'; this package allows it
449 with `defun*' and other argument lists as well. In destructuring, any
450 argument variable (VAR in the above diagram) can be replaced by a list
451 of variables, or more generally, a recursive argument list. The
452 corresponding argument value must be a list whose elements match this
453 recursive argument list. For example:
455 (defmacro* dolist ((var listform &optional resultform)
459 This says that the first argument of `dolist' must be a list of two
460 or three items; if there are other arguments as well as this list, they
461 are stored in `body'. All features allowed in regular argument lists
462 are allowed in these recursive argument lists. In addition, the clause
463 `&whole VAR' is allowed at the front of a recursive argument list. It
464 binds VAR to the whole list being matched; thus `(&whole all a b)'
465 matches a list of two things, with `a' bound to the first thing, `b'
466 bound to the second thing, and `all' bound to the list itself. (Common
467 Lisp allows `&whole' in top-level `defmacro' argument lists as well,
468 but Emacs Lisp does not support this usage.)
470 One last feature of destructuring is that the argument list may be
471 dotted, so that the argument list `(a b . c)' is functionally
472 equivalent to `(a b &rest c)'.
474 If the optimization quality `safety' is set to 0 (*note
475 Declarations::), error checking for wrong number of arguments and
476 invalid keyword arguments is disabled. By default, argument lists are
480 File: cl.info, Node: Time of Evaluation, Next: Function Aliases, Prev: Argument Lists, Up: Program Structure
485 Normally, the byte-compiler does not actually execute the forms in a
486 file it compiles. For example, if a file contains `(setq foo t)', the
487 act of compiling it will not actually set `foo' to `t'. This is true
488 even if the `setq' was a top-level form (i.e., not enclosed in a
489 `defun' or other form). Sometimes, though, you would like to have
490 certain top-level forms evaluated at compile-time. For example, the
491 compiler effectively evaluates `defmacro' forms at compile-time so that
492 later parts of the file can refer to the macros that are defined.
494 - Special Form: eval-when (situations...) forms...
495 This form controls when the body FORMS are evaluated. The
496 SITUATIONS list may contain any set of the symbols `compile',
497 `load', and `eval' (or their long-winded ANSI equivalents,
498 `:compile-toplevel', `:load-toplevel', and `:execute').
500 The `eval-when' form is handled differently depending on whether
501 or not it is being compiled as a top-level form. Specifically, it
502 gets special treatment if it is being compiled by a command such
503 as `byte-compile-file' which compiles files or buffers of code,
504 and it appears either literally at the top level of the file or
505 inside a top-level `progn'.
507 For compiled top-level `eval-when's, the body FORMS are executed
508 at compile-time if `compile' is in the SITUATIONS list, and the
509 FORMS are written out to the file (to be executed at load-time) if
510 `load' is in the SITUATIONS list.
512 For non-compiled-top-level forms, only the `eval' situation is
513 relevant. (This includes forms executed by the interpreter, forms
514 compiled with `byte-compile' rather than `byte-compile-file', and
515 non-top-level forms.) The `eval-when' acts like a `progn' if
516 `eval' is specified, and like `nil' (ignoring the body FORMS) if
519 The rules become more subtle when `eval-when's are nested; consult
520 Steele (second edition) for the gruesome details (and some
523 Some simple examples:
525 ;; Top-level forms in foo.el:
526 (eval-when (compile) (setq foo1 'bar))
527 (eval-when (load) (setq foo2 'bar))
528 (eval-when (compile load) (setq foo3 'bar))
529 (eval-when (eval) (setq foo4 'bar))
530 (eval-when (eval compile) (setq foo5 'bar))
531 (eval-when (eval load) (setq foo6 'bar))
532 (eval-when (eval compile load) (setq foo7 'bar))
534 When `foo.el' is compiled, these variables will be set during the
537 foo1 foo3 foo5 foo7 ; `compile'
539 When `foo.elc' is loaded, these variables will be set:
541 foo2 foo3 foo6 foo7 ; `load'
543 And if `foo.el' is loaded uncompiled, these variables will be set:
545 foo4 foo5 foo6 foo7 ; `eval'
547 If these seven `eval-when's had been, say, inside a `defun', then
548 the first three would have been equivalent to `nil' and the last
549 four would have been equivalent to the corresponding `setq's.
551 Note that `(eval-when (load eval) ...)' is equivalent to `(progn
552 ...)' in all contexts. The compiler treats certain top-level
553 forms, like `defmacro' (sort-of) and `require', as if they were
554 wrapped in `(eval-when (compile load eval) ...)'.
556 Emacs 19 includes two special forms related to `eval-when'. One of
557 these, `eval-when-compile', is not quite equivalent to any `eval-when'
558 construct and is described below. This package defines a version of
559 `eval-when-compile' for the benefit of Emacs 18 users.
561 The other form, `(eval-and-compile ...)', is exactly equivalent to
562 `(eval-when (compile load eval) ...)' and so is not itself defined by
565 - Special Form: eval-when-compile forms...
566 The FORMS are evaluated at compile-time; at execution time, this
567 form acts like a quoted constant of the resulting value. Used at
568 top-level, `eval-when-compile' is just like `eval-when (compile
569 eval)'. In other contexts, `eval-when-compile' allows code to be
570 evaluated once at compile-time for efficiency or other reasons.
572 This form is similar to the `#.' syntax of true Common Lisp.
574 - Special Form: load-time-value form
575 The FORM is evaluated at load-time; at execution time, this form
576 acts like a quoted constant of the resulting value.
578 Early Common Lisp had a `#,' syntax that was similar to this, but
579 ANSI Common Lisp replaced it with `load-time-value' and gave it
580 more well-defined semantics.
582 In a compiled file, `load-time-value' arranges for FORM to be
583 evaluated when the `.elc' file is loaded and then used as if it
584 were a quoted constant. In code compiled by `byte-compile' rather
585 than `byte-compile-file', the effect is identical to
586 `eval-when-compile'. In uncompiled code, both `eval-when-compile'
587 and `load-time-value' act exactly like `progn'.
590 (insert "This function was executed on: "
591 (current-time-string)
593 (eval-when-compile (current-time-string))
594 ;; or '#.(current-time-string) in real Common Lisp
596 (load-time-value (current-time-string))))
598 Byte-compiled, the above defun will result in the following code
599 (or its compiled equivalent, of course) in the `.elc' file:
601 (setq --temp-- (current-time-string))
603 (insert "This function was executed on: "
604 (current-time-string)
606 '"Wed Jun 23 18:33:43 1993"
611 File: cl.info, Node: Function Aliases, Prev: Time of Evaluation, Up: Program Structure
616 This section describes a feature from GNU Emacs 19 which this package
617 makes available in other versions of Emacs.
619 - Function: defalias symbol function
620 This function sets SYMBOL's function cell to FUNCTION. It is
621 equivalent to `fset', except that in GNU Emacs 19 it also records
622 the setting in `load-history' so that it can be undone by a later
625 In other versions of Emacs, `defalias' is a synonym for `fset'.
628 File: cl.info, Node: Predicates, Next: Control Structure, Prev: Program Structure, Up: Top
633 This section describes functions for testing whether various facts are
638 * Type Predicates:: `typep', `deftype', and `coerce'
639 * Equality Predicates:: `eql' and `equalp'
642 File: cl.info, Node: Type Predicates, Next: Equality Predicates, Prev: Predicates, Up: Predicates
647 The "CL" package defines a version of the Common Lisp `typep' predicate.
649 - Function: typep object type
650 Check if OBJECT is of type TYPE, where TYPE is a (quoted) type
651 name of the sort used by Common Lisp. For example, `(typep foo
652 'integer)' is equivalent to `(integerp foo)'.
654 The TYPE argument to the above function is either a symbol or a list
655 beginning with a symbol.
657 * If the type name is a symbol, Emacs appends `-p' to the symbol
658 name to form the name of a predicate function for testing the
659 type. (Built-in predicates whose names end in `p' rather than
660 `-p' are used when appropriate.)
662 * The type symbol `t' stands for the union of all types. `(typep
663 OBJECT t)' is always true. Likewise, the type symbol `nil' stands
664 for nothing at all, and `(typep OBJECT nil)' is always false.
666 * The type symbol `null' represents the symbol `nil'. Thus `(typep
667 OBJECT 'null)' is equivalent to `(null OBJECT)'.
669 * The type symbol `real' is a synonym for `number', and `fixnum' is
670 a synonym for `integer'.
672 * The type symbols `character' and `string-char' match characters.
673 In Emacs-19 and XEmacs-19, characters are the same thing as
674 integers in the range 0-255. In XEmacs-20, where characters are a
675 first-class data type, this checks for actual characters, and
676 `(typep 8BIT-INTEGER 'character)' will return `nil'.
678 * The type symbol `float' uses the `floatp-safe' predicate defined
679 by this package rather than `floatp', so it will work correctly
680 even in Emacs versions without floating-point support.
682 * The type list `(integer LOW HIGH)' represents all integers between
683 LOW and HIGH, inclusive. Either bound may be a list of a single
684 integer to specify an exclusive limit, or a `*' to specify no
685 limit. The type `(integer * *)' is thus equivalent to `integer'.
687 * Likewise, lists beginning with `float', `real', or `number'
688 represent numbers of that type falling in a particular range.
690 * Lists beginning with `and', `or', and `not' form combinations of
691 types. For example, `(or integer (float 0 *))' represents all
692 objects that are integers or non-negative floats.
694 * Lists beginning with `member' or `member*' represent objects `eql'
695 to any of the following values. For example, `(member 1 2 3 4)'
696 is equivalent to `(integer 1 4)', and `(member nil)' is equivalent
699 * Lists of the form `(satisfies PREDICATE)' represent all objects
700 for which PREDICATE returns true when called with that object as
703 The following function and macro (not technically predicates) are
706 - Function: coerce object type
707 This function attempts to convert OBJECT to the specified TYPE.
708 If OBJECT is already of that type as determined by `typep', it is
709 simply returned. Otherwise, certain types of conversions will be
710 made: If TYPE is any sequence type (`string', `list', etc.) then
711 OBJECT will be converted to that type if possible. If TYPE is
712 `character', then strings of length one and symbols with
713 one-character names can be coerced. If TYPE is `float', then
714 integers can be coerced in versions of Emacs that support floats.
715 In all other circumstances, `coerce' signals an error.
717 - Special Form: deftype name arglist forms...
718 This macro defines a new type called NAME. It is similar to
719 `defmacro' in many ways; when NAME is encountered as a type name,
720 the body FORMS are evaluated and should return a type specifier
721 that is equivalent to the type. The ARGLIST is a Common Lisp
722 argument list of the sort accepted by `defmacro*'. The type
723 specifier `(NAME ARGS...)' is expanded by calling the expander
724 with those arguments; the type symbol `NAME' is expanded by
725 calling the expander with no arguments. The ARGLIST is processed
726 the same as for `defmacro*' except that optional arguments without
727 explicit defaults use `*' instead of `nil' as the "default"
728 default. Some examples:
730 (deftype null () '(satisfies null)) ; predefined
731 (deftype list () '(or null cons)) ; predefined
732 (deftype unsigned-byte (&optional bits)
733 (list 'integer 0 (if (eq bits '*) bits (1- (lsh 1 bits)))))
734 (unsigned-byte 8) == (integer 0 255)
735 (unsigned-byte) == (integer 0 *)
736 unsigned-byte == (integer 0 *)
738 The last example shows how the Common Lisp `unsigned-byte' type
739 specifier could be implemented if desired; this package does not
740 implement `unsigned-byte' by default.
742 The `typecase' and `check-type' macros also use type names. *Note
743 Conditionals::. *Note Assertions::. The `map', `concatenate', and
744 `merge' functions take type-name arguments to specify the type of
745 sequence to return. *Note Sequences::.
748 File: cl.info, Node: Equality Predicates, Prev: Type Predicates, Up: Predicates
753 This package defines two Common Lisp predicates, `eql' and `equalp'.
756 This function is almost the same as `eq', except that if A and B
757 are numbers of the same type, it compares them for numeric
758 equality (as if by `equal' instead of `eq'). This makes a
759 difference only for versions of Emacs that are compiled with
760 floating-point support, such as Emacs 19. Emacs floats are
761 allocated objects just like cons cells, which means that `(eq 3.0
762 3.0)' will not necessarily be true--if the two `3.0's were
763 allocated separately, the pointers will be different even though
764 the numbers are the same. But `(eql 3.0 3.0)' will always be true.
766 The types of the arguments must match, so `(eql 3 3.0)' is still
769 Note that Emacs integers are "direct" rather than allocated, which
770 basically means `(eq 3 3)' will always be true. Thus `eq' and
771 `eql' behave differently only if floating-point numbers are
772 involved, and are indistinguishable on Emacs versions that don't
775 There is a slight inconsistency with Common Lisp in the treatment
776 of positive and negative zeros. Some machines, notably those with
777 IEEE standard arithmetic, represent `+0' and `-0' as distinct
778 values. Normally this doesn't matter because the standard
779 specifies that `(= 0.0 -0.0)' should always be true, and this is
780 indeed what Emacs Lisp and Common Lisp do. But the Common Lisp
781 standard states that `(eql 0.0 -0.0)' and `(equal 0.0 -0.0)' should
782 be false on IEEE-like machines; Emacs Lisp does not do this, and in
783 fact the only known way to distinguish between the two zeros in
784 Emacs Lisp is to `format' them and check for a minus sign.
786 - Function: equalp a b
787 This function is a more flexible version of `equal'. In
788 particular, it compares strings and characters case-insensitively,
789 and it compares numbers without regard to type (so that `(equalp 3
790 3.0)' is true). Vectors and conses are compared recursively. All
791 other objects are compared as if by `equal'.
793 This function differs from Common Lisp `equalp' in several
794 respects. In keeping with the idea that strings are less
795 vector-like in Emacs Lisp, this package's `equalp' also will not
796 compare strings against vectors of integers.
798 Also note that the Common Lisp functions `member' and `assoc' use
799 `eql' to compare elements, whereas Emacs Lisp follows the MacLisp
800 tradition and uses `equal' for these two functions. In Emacs, use
801 `member*' and `assoc*' to get functions which use `eql' for comparisons.
804 File: cl.info, Node: Control Structure, Next: Macros, Prev: Predicates, Up: Top
809 The features described in the following sections implement various
810 advanced control structures, including the powerful `setf' facility and
811 a number of looping and conditional constructs.
815 * Assignment:: The `psetq' form
816 * Generalized Variables:: `setf', `incf', `push', etc.
817 * Variable Bindings:: `progv', `lexical-let', `flet', `macrolet'
818 * Conditionals:: `when', `unless', `case', `typecase'
819 * Blocks and Exits:: `block', `return', `return-from'
820 * Iteration:: `do', `dotimes', `dolist', `do-symbols'
821 * Loop Facility:: The Common Lisp `loop' macro
822 * Multiple Values:: `values', `multiple-value-bind', etc.
825 File: cl.info, Node: Assignment, Next: Generalized Variables, Prev: Control Structure, Up: Control Structure
830 The `psetq' form is just like `setq', except that multiple assignments
831 are done in parallel rather than sequentially.
833 - Special Form: psetq [symbol form]...
834 This special form (actually a macro) is used to assign to several
835 variables simultaneously. Given only one SYMBOL and FORM, it has
836 the same effect as `setq'. Given several SYMBOL and FORM pairs,
837 it evaluates all the FORMs in advance and then stores the
838 corresponding variables afterwards.
841 (setq x (+ x y) y (* x y))
844 y ; `y' was computed after `x' was set.
847 (psetq x (+ x y) y (* x y))
850 y ; `y' was computed before `x' was set.
853 The simplest use of `psetq' is `(psetq x y y x)', which exchanges
854 the values of two variables. (The `rotatef' form provides an even
855 more convenient way to swap two variables; *note Modify Macros::.)
857 `psetq' always returns `nil'.
860 File: cl.info, Node: Generalized Variables, Next: Variable Bindings, Prev: Assignment, Up: Control Structure
862 Generalized Variables
863 =====================
865 A "generalized variable" or "place form" is one of the many places in
866 Lisp memory where values can be stored. The simplest place form is a
867 regular Lisp variable. But the cars and cdrs of lists, elements of
868 arrays, properties of symbols, and many other locations are also places
869 where Lisp values are stored.
871 The `setf' form is like `setq', except that it accepts arbitrary
872 place forms on the left side rather than just symbols. For example,
873 `(setf (car a) b)' sets the car of `a' to `b', doing the same operation
874 as `(setcar a b)' but without having to remember two separate functions
875 for setting and accessing every type of place.
877 Generalized variables are analogous to "lvalues" in the C language,
878 where `x = a[i]' gets an element from an array and `a[i] = x' stores an
879 element using the same notation. Just as certain forms like `a[i]' can
880 be lvalues in C, there is a set of forms that can be generalized
885 * Basic Setf:: `setf' and place forms
886 * Modify Macros:: `incf', `push', `rotatef', `letf', `callf', etc.
887 * Customizing Setf:: `define-modify-macro', `defsetf', `define-setf-method'
890 File: cl.info, Node: Basic Setf, Next: Modify Macros, Prev: Generalized Variables, Up: Generalized Variables
895 The `setf' macro is the most basic way to operate on generalized
898 - Special Form: setf [place form]...
899 This macro evaluates FORM and stores it in PLACE, which must be a
900 valid generalized variable form. If there are several PLACE and
901 FORM pairs, the assignments are done sequentially just as with
902 `setq'. `setf' returns the value of the last FORM.
904 The following Lisp forms will work as generalized variables, and
905 so may legally appear in the PLACE argument of `setf':
907 * A symbol naming a variable. In other words, `(setf x y)' is
908 exactly equivalent to `(setq x y)', and `setq' itself is
909 strictly speaking redundant now that `setf' exists. Many
910 programmers continue to prefer `setq' for setting simple
911 variables, though, purely for stylistic or historical reasons.
912 The macro `(setf x y)' actually expands to `(setq x y)', so
913 there is no performance penalty for using it in compiled code.
915 * A call to any of the following Lisp functions:
917 car cdr caar .. cddddr
918 nth rest first .. tenth
920 symbol-function symbol-value symbol-plist
924 Note that for `nthcdr' and `getf', the list argument of the
925 function must itself be a valid PLACE form. For example,
926 `(setf (nthcdr 0 foo) 7)' will set `foo' itself to 7. Note
927 that `push' and `pop' on an `nthcdr' place can be used to
928 insert or delete at any position in a list. The use of
929 `nthcdr' as a PLACE form is an extension to standard Common
932 * The following Emacs-specific functions are also `setf'-able.
933 (Some of these are defined only in Emacs 19 or only in
936 buffer-file-name marker-position
937 buffer-modified-p match-data
938 buffer-name mouse-position
939 buffer-string overlay-end
940 buffer-substring overlay-get
941 current-buffer overlay-start
942 current-case-table point
943 current-column point-marker
944 current-global-map point-max
945 current-input-mode point-min
946 current-local-map process-buffer
947 current-window-configuration process-filter
948 default-file-modes process-sentinel
949 default-value read-mouse-position
950 documentation-property screen-height
951 extent-data screen-menubar
952 extent-end-position screen-width
953 extent-start-position selected-window
954 face-background selected-screen
955 face-background-pixmap selected-frame
956 face-font standard-case-table
957 face-foreground syntax-table
958 face-underline-p window-buffer
959 file-modes window-dedicated-p
960 frame-height window-display-table
961 frame-parameters window-height
962 frame-visible-p window-hscroll
963 frame-width window-point
964 get-register window-start
966 global-key-binding x-get-cut-buffer
967 keymap-parent x-get-cutbuffer
968 local-key-binding x-get-secondary-selection
972 Most of these have directly corresponding "set" functions,
973 like `use-local-map' for `current-local-map', or `goto-char'
974 for `point'. A few, like `point-min', expand to longer
975 sequences of code when they are `setf''d (`(narrow-to-region
976 x (point-max))' in this case).
978 * A call of the form `(substring SUBPLACE N [M])', where
979 SUBPLACE is itself a legal generalized variable whose current
980 value is a string, and where the value stored is also a
981 string. The new string is spliced into the specified part of
982 the destination string. For example:
984 (setq a (list "hello" "world"))
988 (substring (cadr a) 2 4)
990 (setf (substring (cadr a) 2 4) "o")
997 The generalized variable `buffer-substring', listed above,
998 also works in this way by replacing a portion of the current
1001 * A call of the form `(apply 'FUNC ...)' or `(apply (function
1002 FUNC) ...)', where FUNC is a `setf'-able function whose store
1003 function is "suitable" in the sense described in Steele's
1004 book; since none of the standard Emacs place functions are
1005 suitable in this sense, this feature is only interesting when
1006 used with places you define yourself with
1007 `define-setf-method' or the long form of `defsetf'.
1009 * A macro call, in which case the macro is expanded and `setf'
1010 is applied to the resulting form.
1012 * Any form for which a `defsetf' or `define-setf-method' has
1015 Using any forms other than these in the PLACE argument to `setf'
1016 will signal an error.
1018 The `setf' macro takes care to evaluate all subforms in the proper
1019 left-to-right order; for example,
1021 (setf (aref vec (incf i)) i)
1023 looks like it will evaluate `(incf i)' exactly once, before the
1024 following access to `i'; the `setf' expander will insert temporary
1025 variables as necessary to ensure that it does in fact work this
1026 way no matter what setf-method is defined for `aref'. (In this
1027 case, `aset' would be used and no such steps would be necessary
1028 since `aset' takes its arguments in a convenient order.)
1030 However, if the PLACE form is a macro which explicitly evaluates
1031 its arguments in an unusual order, this unusual order will be
1032 preserved. Adapting an example from Steele, given
1034 (defmacro wrong-order (x y) (list 'aref y x))
1036 the form `(setf (wrong-order A B) 17)' will evaluate B first, then
1037 A, just as in an actual call to `wrong-order'.
projects / chise / xemacs-chise.git- / blob