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