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: Structures, Next: Assertions, Prev: Hash Tables, Up: Top
35 The Common Lisp "structure" mechanism provides a general way to define
36 data types similar to C's `struct' types. A structure is a Lisp object
37 containing some number of "slots", each of which can hold any Lisp data
38 object. Functions are provided for accessing and setting the slots,
39 creating or copying structure objects, and recognizing objects of a
40 particular structure type.
42 In true Common Lisp, each structure type is a new type distinct from
43 all existing Lisp types. Since the underlying Emacs Lisp system
44 provides no way to create new distinct types, this package implements
45 structures as vectors (or lists upon request) with a special "tag"
46 symbol to identify them.
48 - Special Form: defstruct name slots...
49 The `defstruct' form defines a new structure type called NAME,
50 with the specified SLOTS. (The SLOTS may begin with a string
51 which documents the structure type.) In the simplest case, NAME
52 and each of the SLOTS are symbols. For example,
54 (defstruct person name age sex)
56 defines a struct type called `person' which contains three slots.
57 Given a `person' object P, you can access those slots by calling
58 `(person-name P)', `(person-age P)', and `(person-sex P)'. You
59 can also change these slots by using `setf' on any of these place
62 (incf (person-age birthday-boy))
64 You can create a new `person' by calling `make-person', which
65 takes keyword arguments `:name', `:age', and `:sex' to specify the
66 initial values of these slots in the new object. (Omitting any of
67 these arguments leaves the corresponding slot "undefined,"
68 according to the Common Lisp standard; in Emacs Lisp, such
69 uninitialized slots are filled with `nil'.)
71 Given a `person', `(copy-person P)' makes a new object of the same
72 type whose slots are `eq' to those of P.
74 Given any Lisp object X, `(person-p X)' returns true if X looks
75 like a `person', false otherwise. (Again, in Common Lisp this
76 predicate would be exact; in Emacs Lisp the best it can do is
77 verify that X is a vector of the correct length which starts with
78 the correct tag symbol.)
80 Accessors like `person-name' normally check their arguments
81 (effectively using `person-p') and signal an error if the argument
82 is the wrong type. This check is affected by `(optimize (safety
83 ...))' declarations. Safety level 1, the default, uses a somewhat
84 optimized check that will detect all incorrect arguments, but may
85 use an uninformative error message (e.g., "expected a vector"
86 instead of "expected a `person'"). Safety level 0 omits all
87 checks except as provided by the underlying `aref' call; safety
88 levels 2 and 3 do rigorous checking that will always print a
89 descriptive error message for incorrect inputs. *Note
92 (setq dave (make-person :name "Dave" :sex 'male))
93 => [cl-struct-person "Dave" nil male]
94 (setq other (copy-person dave))
95 => [cl-struct-person "Dave" nil male]
98 (eq (person-name dave) (person-name other))
106 (person-p '[cl-struct-person counterfeit person object])
109 In general, NAME is either a name symbol or a list of a name
110 symbol followed by any number of "struct options"; each SLOT is
111 either a slot symbol or a list of the form `(SLOT-NAME
112 DEFAULT-VALUE SLOT-OPTIONS...)'. The DEFAULT-VALUE is a Lisp form
113 which is evaluated any time an instance of the structure type is
114 created without specifying that slot's value.
116 Common Lisp defines several slot options, but the only one
117 implemented in this package is `:read-only'. A non-`nil' value
118 for this option means the slot should not be `setf'-able; the
119 slot's value is determined when the object is created and does not
123 (name nil :read-only t)
127 Any slot options other than `:read-only' are ignored.
129 For obscure historical reasons, structure options take a different
130 form than slot options. A structure option is either a keyword
131 symbol, or a list beginning with a keyword symbol possibly followed
132 by arguments. (By contrast, slot options are key-value pairs not
135 (defstruct (person (:constructor create-person)
140 The following structure options are recognized.
143 The argument is a symbol whose print name is used as the
144 prefix for the names of slot accessor functions. The default
145 is the name of the struct type followed by a hyphen. The
146 option `(:conc-name p-)' would change this prefix to `p-'.
147 Specifying `nil' as an argument means no prefix, so that the
148 slot names themselves are used to name the accessor functions.
151 In the simple case, this option takes one argument which is an
152 alternate name to use for the constructor function. The
153 default is `make-NAME', e.g., `make-person'. The above
154 example changes this to `create-person'. Specifying `nil' as
155 an argument means that no standard constructor should be
158 In the full form of this option, the constructor name is
159 followed by an arbitrary argument list. *Note Program
160 Structure::, for a description of the format of Common Lisp
161 argument lists. All options, such as `&rest' and `&key', are
162 supported. The argument names should match the slot names;
163 each slot is initialized from the corresponding argument.
164 Slots whose names do not appear in the argument list are
165 initialized based on the DEFAULT-VALUE in their slot
166 descriptor. Also, `&optional' and `&key' arguments which
167 don't specify defaults take their defaults from the slot
168 descriptor. It is legal to include arguments which don't
169 correspond to slot names; these are useful if they are
170 referred to in the defaults for optional, keyword, or `&aux'
171 arguments which _do_ correspond to slots.
173 You can specify any number of full-format `:constructor'
174 options on a structure. The default constructor is still
175 generated as well unless you disable it with a simple-format
176 `:constructor' option.
180 (:constructor nil) ; no default constructor
181 (:constructor new-person (name sex &optional (age 0)))
182 (:constructor new-hound (&key (name "Rover")
184 &aux (age (* 7 dog-years))
188 The first constructor here takes its arguments positionally
189 rather than by keyword. (In official Common Lisp
190 terminology, constructors that work By Order of Arguments
191 instead of by keyword are called "BOA constructors." No, I'm
192 not making this up.) For example, `(new-person "Jane"
193 'female)' generates a person whose slots are `"Jane"', 0, and
194 `female', respectively.
196 The second constructor takes two keyword arguments, `:name',
197 which initializes the `name' slot and defaults to `"Rover"',
198 and `:dog-years', which does not itself correspond to a slot
199 but which is used to initialize the `age' slot. The `sex'
200 slot is forced to the symbol `canine' with no syntax for
204 The argument is an alternate name for the copier function for
205 this type. The default is `copy-NAME'. `nil' means not to
206 generate a copier function. (In this implementation, all
207 copier functions are simply synonyms for `copy-sequence'.)
210 The argument is an alternate name for the predicate which
211 recognizes objects of this type. The default is `NAME-p'.
212 `nil' means not to generate a predicate function. (If the
213 `:type' option is used without the `:named' option, no
214 predicate is ever generated.)
216 In true Common Lisp, `typep' is always able to recognize a
217 structure object even if `:predicate' was used. In this
218 package, `typep' simply looks for a function called
219 `TYPENAME-p', so it will work for structure types only if
220 they used the default predicate name.
223 This option implements a very limited form of C++-style
224 inheritance. The argument is the name of another structure
225 type previously created with `defstruct'. The effect is to
226 cause the new structure type to inherit all of the included
227 structure's slots (plus, of course, any new slots described
228 by this struct's slot descriptors). The new structure is
229 considered a "specialization" of the included one. In fact,
230 the predicate and slot accessors for the included type will
231 also accept objects of the new type.
233 If there are extra arguments to the `:include' option after
234 the included-structure name, these options are treated as
235 replacement slot descriptors for slots in the included
236 structure, possibly with modified default values. Borrowing
237 an example from Steele:
239 (defstruct person name (age 0) sex)
241 (defstruct (astronaut (:include person (age 45)))
243 (favorite-beverage 'tang))
246 (setq joe (make-person :name "Joe"))
247 => [cl-struct-person "Joe" 0 nil]
248 (setq buzz (make-astronaut :name "Buzz"))
249 => [cl-struct-astronaut "Buzz" 45 nil nil tang]
251 (list (person-p joe) (person-p buzz))
253 (list (astronaut-p joe) (astronaut-p buzz))
259 => error: "astronaut-name accessing a non-astronaut"
261 Thus, if `astronaut' is a specialization of `person', then
262 every `astronaut' is also a `person' (but not the other way
263 around). Every `astronaut' includes all the slots of a
264 `person', plus extra slots that are specific to astronauts.
265 Operations that work on people (like `person-name') work on
266 astronauts just like other people.
269 In full Common Lisp, this option allows you to specify a
270 function which is called to print an instance of the
271 structure type. The Emacs Lisp system offers no hooks into
272 the Lisp printer which would allow for such a feature, so
273 this package simply ignores `:print-function'.
276 The argument should be one of the symbols `vector' or `list'.
277 This tells which underlying Lisp data type should be used to
278 implement the new structure type. Vectors are used by
279 default, but `(:type list)' will cause structure objects to
280 be stored as lists instead.
282 The vector representation for structure objects has the
283 advantage that all structure slots can be accessed quickly,
284 although creating vectors is a bit slower in Emacs Lisp.
285 Lists are easier to create, but take a relatively long time
286 accessing the later slots.
289 This option, which takes no arguments, causes a
290 characteristic "tag" symbol to be stored at the front of the
291 structure object. Using `:type' without also using `:named'
292 will result in a structure type stored as plain vectors or
293 lists with no identifying features.
295 The default, if you don't specify `:type' explicitly, is to
296 use named vectors. Therefore, `:named' is only useful in
297 conjunction with `:type'.
299 (defstruct (person1) name age sex)
300 (defstruct (person2 (:type list) :named) name age sex)
301 (defstruct (person3 (:type list)) name age sex)
303 (setq p1 (make-person1))
304 => [cl-struct-person1 nil nil nil]
305 (setq p2 (make-person2))
306 => (person2 nil nil nil)
307 (setq p3 (make-person3))
315 => error: function person3-p undefined
317 Since unnamed structures don't have tags, `defstruct' is not
318 able to make a useful predicate for recognizing them. Also,
319 accessors like `person3-name' will be generated but they will
320 not be able to do any type checking. The `person3-name'
321 function, for example, will simply be a synonym for `car' in
322 this case. By contrast, `person2-name' is able to verify
323 that its argument is indeed a `person2' object before
327 The argument must be a nonnegative integer. It specifies a
328 number of slots to be left "empty" at the front of the
329 structure. If the structure is named, the tag appears at the
330 specified position in the list or vector; otherwise, the first
331 slot appears at that position. Earlier positions are filled
332 with `nil' by the constructors and ignored otherwise. If the
333 type `:include's another type, then `:initial-offset'
334 specifies a number of slots to be skipped between the last
335 slot of the included type and the first new slot.
337 Except as noted, the `defstruct' facility of this package is
338 entirely compatible with that of Common Lisp.
341 File: cl.info, Node: Assertions, Next: Efficiency Concerns, Prev: Structures, Up: Top
343 Assertions and Errors
344 *********************
346 This section describes two macros that test "assertions", i.e.,
347 conditions which must be true if the program is operating correctly.
348 Assertions never add to the behavior of a Lisp program; they simply
349 make "sanity checks" to make sure everything is as it should be.
351 If the optimization property `speed' has been set to 3, and `safety'
352 is less than 3, then the byte-compiler will optimize away the following
353 assertions. Because assertions might be optimized away, it is a bad
354 idea for them to include side-effects.
356 - Special Form: assert test-form [show-args string args...]
357 This form verifies that TEST-FORM is true (i.e., evaluates to a
358 non-`nil' value). If so, it returns `nil'. If the test is not
359 satisfied, `assert' signals an error.
361 A default error message will be supplied which includes TEST-FORM.
362 You can specify a different error message by including a STRING
363 argument plus optional extra arguments. Those arguments are simply
364 passed to `error' to signal the error.
366 If the optional second argument SHOW-ARGS is `t' instead of `nil',
367 then the error message (with or without STRING) will also include
368 all non-constant arguments of the top-level FORM. For example:
370 (assert (> x 10) t "x is too small: %d")
372 This usage of SHOW-ARGS is an extension to Common Lisp. In true
373 Common Lisp, the second argument gives a list of PLACES which can
374 be `setf''d by the user before continuing from the error. Since
375 Emacs Lisp does not support continuable errors, it makes no sense
378 - Special Form: check-type form type [string]
379 This form verifies that FORM evaluates to a value of type TYPE.
380 If so, it returns `nil'. If not, `check-type' signals a
381 `wrong-type-argument' error. The default error message lists the
382 erroneous value along with TYPE and FORM themselves. If STRING is
383 specified, it is included in the error message in place of TYPE.
386 (check-type x (integer 1 *) "a positive integer")
388 *Note Type Predicates::, for a description of the type specifiers
389 that may be used for TYPE.
391 Note that in Common Lisp, the first argument to `check-type' must
392 be a PLACE suitable for use by `setf', because `check-type'
393 signals a continuable error that allows the user to modify PLACE.
395 The following error-related macro is also defined:
397 - Special Form: ignore-errors forms...
398 This executes FORMS exactly like a `progn', except that errors are
399 ignored during the FORMS. More precisely, if an error is
400 signalled then `ignore-errors' immediately aborts execution of the
401 FORMS and returns `nil'. If the FORMS complete successfully,
402 `ignore-errors' returns the result of the last FORM.
405 File: cl.info, Node: Efficiency Concerns, Next: Common Lisp Compatibility, Prev: Assertions, Up: Top
413 Many of the advanced features of this package, such as `defun*',
414 `loop', and `setf', are implemented as Lisp macros. In byte-compiled
415 code, these complex notations will be expanded into equivalent Lisp
416 code which is simple and efficient. For example, the forms
421 are expanded at compile-time to the Lisp forms
424 (setcar p (cons x (car p)))
426 which are the most efficient ways of doing these respective operations
427 in Lisp. Thus, there is no performance penalty for using the more
428 readable `incf' and `push' forms in your compiled code.
430 _Interpreted_ code, on the other hand, must expand these macros
431 every time they are executed. For this reason it is strongly
432 recommended that code making heavy use of macros be compiled. (The
433 features labelled "Special Form" instead of "Function" in this manual
434 are macros.) A loop using `incf' a hundred times will execute
435 considerably faster if compiled, and will also garbage-collect less
436 because the macro expansion will not have to be generated, used, and
437 thrown away a hundred times.
439 You can find out how a macro expands by using the `cl-prettyexpand'
442 - Function: cl-prettyexpand form &optional full
443 This function takes a single Lisp form as an argument and inserts
444 a nicely formatted copy of it in the current buffer (which must be
445 in Lisp mode so that indentation works properly). It also expands
446 all Lisp macros which appear in the form. The easiest way to use
447 this function is to go to the `*scratch*' buffer and type, say,
449 (cl-prettyexpand '(loop for x below 10 collect x))
451 and type `C-x C-e' immediately after the closing parenthesis; the
458 (setq G1004 (cons x G1004))
462 will be inserted into the buffer. (The `block' macro is expanded
463 differently in the interpreter and compiler, so `cl-prettyexpand'
464 just leaves it alone. The temporary variable `G1004' was created
467 If the optional argument FULL is true, then _all_ macros are
468 expanded, including `block', `eval-when', and compiler macros.
469 Expansion is done as if FORM were a top-level form in a file being
470 compiled. For example,
472 (cl-prettyexpand '(pushnew 'x list))
473 -| (setq list (adjoin 'x list))
474 (cl-prettyexpand '(pushnew 'x list) t)
475 -| (setq list (if (memq 'x list) list (cons 'x list)))
476 (cl-prettyexpand '(caddr (member* 'a list)) t)
477 -| (car (cdr (cdr (memq 'a list))))
479 Note that `adjoin', `caddr', and `member*' all have built-in
480 compiler macros to optimize them in common cases.
486 Common Lisp compliance has in general not been sacrificed for the sake
487 of efficiency. A few exceptions have been made for cases where
488 substantial gains were possible at the expense of marginal
489 incompatibility. One example is the use of `memq' (which is treated
490 very efficiently by the byte-compiler) to scan for keyword arguments;
491 this can become confused in rare cases when keyword symbols are used as
492 both keywords and data values at once. This is extremely unlikely to
493 occur in practical code, and the use of `memq' allows functions with
494 keyword arguments to be nearly as fast as functions that use
495 `&optional' arguments.
497 The Common Lisp standard (as embodied in Steele's book) uses the
498 phrase "it is an error if" to indicate a situation which is not
499 supposed to arise in complying programs; implementations are strongly
500 encouraged but not required to signal an error in these situations.
501 This package sometimes omits such error checking in the interest of
502 compactness and efficiency. For example, `do' variable specifiers are
503 supposed to be lists of one, two, or three forms; extra forms are
504 ignored by this package rather than signalling a syntax error. The
505 `endp' function is simply a synonym for `null' in this package.
506 Functions taking keyword arguments will accept an odd number of
507 arguments, treating the trailing keyword as if it were followed by the
510 Argument lists (as processed by `defun*' and friends) _are_ checked
511 rigorously except for the minor point just mentioned; in particular,
512 keyword arguments are checked for validity, and `&allow-other-keys' and
513 `:allow-other-keys' are fully implemented. Keyword validity checking
514 is slightly time consuming (though not too bad in byte-compiled code);
515 you can use `&allow-other-keys' to omit this check. Functions defined
516 in this package such as `find' and `member*' do check their keyword
517 arguments for validity.
523 The byte-compiler that comes with Emacs 18 normally fails to expand
524 macros that appear in top-level positions in the file (i.e., outside of
525 `defun's or other enclosing forms). This would have disastrous
526 consequences to programs that used such top-level macros as `defun*',
527 `eval-when', and `defstruct'. To work around this problem, the "CL"
528 package patches the Emacs 18 compiler to expand top-level macros. This
529 patch will apply to your own macros, too, if they are used in a
530 top-level context. The patch will not harm versions of the Emacs 18
531 compiler which have already had a similar patch applied, nor will it
532 affect the optimizing Emacs 19 byte-compiler written by Jamie Zawinski
533 and Hallvard Furuseth. The patch is applied to the byte compiler's
534 code in Emacs' memory, _not_ to the `bytecomp.elc' file stored on disk.
536 The Emacs 19 compiler (for Emacs 18) is available from various Emacs
537 Lisp archive sites such as `archive.cis.ohio-state.edu'. Its use is
538 highly recommended; many of the Common Lisp macros emit code which can
539 be improved by optimization. In particular, `block's (whether explicit
540 or implicit in constructs like `defun*' and `loop') carry a fair
541 run-time penalty; the optimizing compiler removes `block's which are
542 not actually referenced by `return' or `return-from' inside the block.
545 File: cl.info, Node: Common Lisp Compatibility, Next: Old CL Compatibility, Prev: Efficiency Concerns, Up: Top
547 Common Lisp Compatibility
548 *************************
550 Following is a list of all known incompatibilities between this package
551 and Common Lisp as documented in Steele (2nd edition).
553 Certain function names, such as `member', `assoc', and `floor', were
554 already taken by (incompatible) Emacs Lisp functions; this package
555 appends `*' to the names of its Common Lisp versions of these functions.
557 The word `defun*' is required instead of `defun' in order to use
558 extended Common Lisp argument lists in a function. Likewise,
559 `defmacro*' and `function*' are versions of those forms which
560 understand full-featured argument lists. The `&whole' keyword does not
561 work in `defmacro' argument lists (except inside recursive argument
564 In order to allow an efficient implementation, keyword arguments use
565 a slightly cheesy parser which may be confused if a keyword symbol is
566 passed as the _value_ of another keyword argument. (Specifically,
567 `(memq :KEYWORD REST-OF-ARGUMENTS)' is used to scan for `:KEYWORD'
568 among the supplied keyword arguments.)
570 The `eql' and `equal' predicates do not distinguish between IEEE
571 floating-point plus and minus zero. The `equalp' predicate has several
572 differences with Common Lisp; *note Predicates::.
574 The `setf' mechanism is entirely compatible, except that
575 setf-methods return a list of five values rather than five values
576 directly. Also, the new "`setf' function" concept (typified by `(defun
577 (setf foo) ...)') is not implemented.
579 The `do-all-symbols' form is the same as `do-symbols' with no
580 OBARRAY argument. In Common Lisp, this form would iterate over all
581 symbols in all packages. Since Emacs obarrays are not a first-class
582 package mechanism, there is no way for `do-all-symbols' to locate any
583 but the default obarray.
585 The `loop' macro is complete except that `loop-finish' and type
586 specifiers are unimplemented.
588 The multiple-value return facility treats lists as multiple values,
589 since Emacs Lisp cannot support multiple return values directly. The
590 macros will be compatible with Common Lisp if `values' or `values-list'
591 is always used to return to a `multiple-value-bind' or other
592 multiple-value receiver; if `values' is used without
593 `multiple-value-...' or vice-versa the effect will be different from
596 Many Common Lisp declarations are ignored, and others match the
597 Common Lisp standard in concept but not in detail. For example, local
598 `special' declarations, which are purely advisory in Emacs Lisp, do not
599 rigorously obey the scoping rules set down in Steele's book.
601 The variable `*gensym-counter*' starts out with a pseudo-random
602 value rather than with zero. This is to cope with the fact that
603 generated symbols become interned when they are written to and loaded
606 The `defstruct' facility is compatible, except that structures are
607 of type `:type vector :named' by default rather than some special,
608 distinct type. Also, the `:type' slot option is ignored.
610 The second argument of `check-type' is treated differently.
613 File: cl.info, Node: Old CL Compatibility, Next: Porting Common Lisp, Prev: Common Lisp Compatibility, Up: Top
618 Following is a list of all known incompatibilities between this package
619 and the older Quiroz `cl.el' package.
621 This package's emulation of multiple return values in functions is
622 incompatible with that of the older package. That package attempted to
623 come as close as possible to true Common Lisp multiple return values;
624 unfortunately, it could not be 100% reliable and so was prone to
625 occasional surprises if used freely. This package uses a simpler
626 method, namely replacing multiple values with lists of values, which is
627 more predictable though more noticeably different from Common Lisp.
629 The `defkeyword' form and `keywordp' function are not implemented in
632 The `member', `floor', `ceiling', `truncate', `round', `mod', and
633 `rem' functions are suffixed by `*' in this package to avoid collision
634 with existing functions in Emacs 18 or Emacs 19. The older package
635 simply redefined these functions, overwriting the built-in meanings and
636 causing serious portability problems with Emacs 19. (Some more recent
637 versions of the Quiroz package changed the names to `cl-member', etc.;
638 this package defines the latter names as aliases for `member*', etc.)
640 Certain functions in the old package which were buggy or inconsistent
641 with the Common Lisp standard are incompatible with the conforming
642 versions in this package. For example, `eql' and `member' were
643 synonyms for `eq' and `memq' in that package, `setf' failed to preserve
644 correct order of evaluation of its arguments, etc.
646 Finally, unlike the older package, this package is careful to prefix
647 all of its internal names with `cl-'. Except for a few functions which
648 are explicitly defined as additional features (such as `floatp-safe'
649 and `letf'), this package does not export any non-`cl-' symbols which
650 are not also part of Common Lisp.
653 The `cl-compat' package
654 =======================
656 The "CL" package includes emulations of some features of the old
657 `cl.el', in the form of a compatibility package `cl-compat'. To use
658 it, put `(require 'cl-compat)' in your program.
660 The old package defined a number of internal routines without `cl-'
661 prefixes or other annotations. Call to these routines may have crept
662 into existing Lisp code. `cl-compat' provides emulations of the
663 following internal routines: `pair-with-newsyms', `zip-lists',
664 `unzip-lists', `reassemble-arglists', `duplicate-symbols-p',
667 Some `setf' forms translated into calls to internal functions that
668 user code might call directly. The functions `setnth', `setnthcdr',
669 and `setelt' fall in this category; they are defined by `cl-compat',
670 but the best fix is to change to use `setf' properly.
672 The `cl-compat' file defines the keyword functions `keywordp',
673 `keyword-of', and `defkeyword', which are not defined by the new "CL"
674 package because the use of keywords as data is discouraged.
676 The `build-klist' mechanism for parsing keyword arguments is
677 emulated by `cl-compat'; the `with-keyword-args' macro is not, however,
678 and in any case it's best to change to use the more natural keyword
679 argument processing offered by `defun*'.
681 Multiple return values are treated differently by the two Common
682 Lisp packages. The old package's method was more compatible with true
683 Common Lisp, though it used heuristics that caused it to report
684 spurious multiple return values in certain cases. The `cl-compat'
685 package defines a set of multiple-value macros that are compatible with
686 the old CL package; again, they are heuristic in nature, but they are
687 guaranteed to work in any case where the old package's macros worked.
688 To avoid name collision with the "official" multiple-value facilities,
689 the ones in `cl-compat' have capitalized names: `Values',
690 `Values-list', `Multiple-value-bind', etc.
692 The functions `cl-floor', `cl-ceiling', `cl-truncate', and
693 `cl-round' are defined by `cl-compat' to use the old-style
694 multiple-value mechanism, just as they did in the old package. The
695 newer `floor*' and friends return their two results in a list rather
696 than as multiple values. Note that older versions of the old package
697 used the unadorned names `floor', `ceiling', etc.; `cl-compat' cannot
698 use these names because they conflict with Emacs 19 built-ins.
701 File: cl.info, Node: Porting Common Lisp, Next: Function Index, Prev: Old CL Compatibility, Up: Top
706 This package is meant to be used as an extension to Emacs Lisp, not as
707 an Emacs implementation of true Common Lisp. Some of the remaining
708 differences between Emacs Lisp and Common Lisp make it difficult to
709 port large Common Lisp applications to Emacs. For one, some of the
710 features in this package are not fully compliant with ANSI or Steele;
711 *note Common Lisp Compatibility::. But there are also quite a few
712 features that this package does not provide at all. Here are some
713 major omissions that you will want watch out for when bringing Common
714 Lisp code into Emacs.
716 * Case-insensitivity. Symbols in Common Lisp are case-insensitive
717 by default. Some programs refer to a function or variable as
718 `foo' in one place and `Foo' or `FOO' in another. Emacs Lisp will
719 treat these as three distinct symbols.
721 Some Common Lisp code is written in all upper-case. While Emacs
722 is happy to let the program's own functions and variables use this
723 convention, calls to Lisp builtins like `if' and `defun' will have
724 to be changed to lower-case.
726 * Lexical scoping. In Common Lisp, function arguments and `let'
727 bindings apply only to references physically within their bodies
728 (or within macro expansions in their bodies). Emacs Lisp, by
729 contrast, uses "dynamic scoping" wherein a binding to a variable
730 is visible even inside functions called from the body.
732 Variables in Common Lisp can be made dynamically scoped by
733 declaring them `special' or using `defvar'. In Emacs Lisp it is
734 as if all variables were declared `special'.
736 Often you can use code that was written for lexical scoping even
737 in a dynamically scoped Lisp, but not always. Here is an example
738 of a Common Lisp code fragment that would fail in Emacs Lisp:
740 (defun map-odd-elements (func list)
742 for flag = t then (not flag)
743 collect (if flag x (funcall func x))))
745 (defun add-odd-elements (list x)
746 (map-odd-elements (function (lambda (a) (+ a x))) list))
748 In Common Lisp, the two functions' usages of `x' are completely
749 independent. In Emacs Lisp, the binding to `x' made by
750 `add-odd-elements' will have been hidden by the binding in
751 `map-odd-elements' by the time the `(+ a x)' function is called.
753 (This package avoids such problems in its own mapping functions by
754 using names like `cl-x' instead of `x' internally; as long as you
755 don't use the `cl-' prefix for your own variables no collision can
758 *Note Lexical Bindings::, for a description of the `lexical-let'
759 form which establishes a Common Lisp-style lexical binding, and
760 some examples of how it differs from Emacs' regular `let'.
762 * Common Lisp allows the shorthand `#'x' to stand for `(function
763 x)', just as `'x' stands for `(quote x)'. In Common Lisp, one
764 traditionally uses `#'' notation when referring to the name of a
765 function. In Emacs Lisp, it works just as well to use a regular
768 (loop for x in y by #'cddr collect (mapcar #'plusp x)) ; Common Lisp
769 (loop for x in y by 'cddr collect (mapcar 'plusp x)) ; Emacs Lisp
771 When `#'' introduces a `lambda' form, it is best to write out
772 `(function ...)' longhand in Emacs Lisp. You can use a regular
773 quote, but then the byte-compiler won't know that the `lambda'
774 expression is code that can be compiled.
776 (mapcar #'(lambda (x) (* x 2)) list) ; Common Lisp
777 (mapcar (function (lambda (x) (* x 2))) list) ; Emacs Lisp
779 XEmacs supports `#'' notation starting with version 19.8.
781 * Reader macros. Common Lisp includes a second type of macro that
782 works at the level of individual characters. For example, Common
783 Lisp implements the quote notation by a reader macro called `'',
784 whereas Emacs Lisp's parser just treats quote as a special case.
785 Some Lisp packages use reader macros to create special syntaxes
786 for themselves, which the Emacs parser is incapable of reading.
788 * Other syntactic features. Common Lisp provides a number of
789 notations beginning with `#' that the Emacs Lisp parser won't
790 understand. For example, `#| ... |#' is an alternate comment
791 notation, and `#+lucid (foo)' tells the parser to ignore the
792 `(foo)' except in Lucid Common Lisp.
794 The number prefixes `#b', `#o', and `#x', however, are supported
795 by the Emacs Lisp parser to represent numbers in binary, octal,
796 and hexadecimal notation (or radix), just like in Common Lisp.
798 * Packages. In Common Lisp, symbols are divided into "packages".
799 Symbols that are Lisp built-ins are typically stored in one
800 package; symbols that are vendor extensions are put in another,
801 and each application program would have a package for its own
802 symbols. Certain symbols are "exported" by a package and others
803 are internal; certain packages "use" or import the exported symbols
804 of other packages. To access symbols that would not normally be
805 visible due to this importing and exporting, Common Lisp provides
806 a syntax like `package:symbol' or `package::symbol'.
808 Emacs Lisp has a single namespace for all interned symbols, and
809 then uses a naming convention of putting a prefix like `cl-' in
810 front of the name. Some Emacs packages adopt the Common Lisp-like
811 convention of using `cl:' or `cl::' as the prefix. However, the
812 Emacs parser does not understand colons and just treats them as
813 part of the symbol name. Thus, while `mapcar' and `lisp:mapcar'
814 may refer to the same symbol in Common Lisp, they are totally
815 distinct in Emacs Lisp. Common Lisp programs which refer to a
816 symbol by the full name sometimes and the short name other times
817 will not port cleanly to Emacs.
819 Emacs Lisp does have a concept of "obarrays," which are
820 package-like collections of symbols, but this feature is not
821 strong enough to be used as a true package mechanism.
823 * Keywords. The notation `:test-not' in Common Lisp really is a
824 shorthand for `keyword:test-not'; keywords are just symbols in a
825 built-in `keyword' package with the special property that all its
826 symbols are automatically self-evaluating. Common Lisp programs
827 often use keywords liberally to avoid having to use quotes.
829 In Emacs Lisp a keyword is just a symbol whose name begins with a
830 colon; since the Emacs parser does not treat them specially, they
831 have to be explicitly made self-evaluating by a statement like
832 `(setq :test-not ':test-not)'. This package arranges to execute
833 such a statement whenever `defun*' or some other form sees a
834 keyword being used as an argument. Common Lisp code that assumes
835 that a symbol `:mumble' will be self-evaluating even though it was
836 never introduced by a `defun*' will have to be fixed.
838 * The `format' function is quite different between Common Lisp and
839 Emacs Lisp. It takes an additional "destination" argument before
840 the format string. A destination of `nil' means to format to a
841 string as in Emacs Lisp; a destination of `t' means to write to
842 the terminal (similar to `message' in Emacs). Also, format
843 control strings are utterly different; `~' is used instead of `%'
844 to introduce format codes, and the set of available codes is much
845 richer. There are no notations like `\n' for string literals;
846 instead, `format' is used with the "newline" format code, `~%'.
847 More advanced formatting codes provide such features as paragraph
848 filling, case conversion, and even loops and conditionals.
850 While it would have been possible to implement most of Common Lisp
851 `format' in this package (under the name `format*', of course), it
852 was not deemed worthwhile. It would have required a huge amount
853 of code to implement even a decent subset of `format*', yet the
854 functionality it would provide over Emacs Lisp's `format' would
857 * Vector constants use square brackets in Emacs Lisp, but `#(a b c)'
858 notation in Common Lisp. To further complicate matters, Emacs 19
859 introduces its own `#(' notation for something entirely
860 different--strings with properties.
862 * Characters are distinct from integers in Common Lisp. The
863 notation for character constants is also different: `#\A' instead
864 of `?A'. Also, `string=' and `string-equal' are synonyms in Emacs
865 Lisp whereas the latter is case-insensitive in Common Lisp.
867 * Data types. Some Common Lisp data types do not exist in Emacs
868 Lisp. Rational numbers and complex numbers are not present, nor
869 are large integers (all integers are "fixnums"). All arrays are
870 one-dimensional. There are no readtables or pathnames; streams
871 are a set of existing data types rather than a new data type of
872 their own. Hash tables, random-states, structures, and packages
873 (obarrays) are built from Lisp vectors or lists rather than being
876 * The Common Lisp Object System (CLOS) is not implemented, nor is
877 the Common Lisp Condition System.
879 * Common Lisp features that are completely redundant with Emacs Lisp
880 features of a different name generally have not been implemented.
881 For example, Common Lisp writes `defconstant' where Emacs Lisp
882 uses `defconst'. Similarly, `make-list' takes its arguments in
883 different ways in the two Lisps but does exactly the same thing,
884 so this package has not bothered to implement a Common Lisp-style
887 * A few more notable Common Lisp features not included in this
888 package: `compiler-let', `tagbody', `prog', `ldb/dpb',
889 `parse-integer', `cerror'.
891 * Recursion. While recursion works in Emacs Lisp just like it does
892 in Common Lisp, various details of the Emacs Lisp system and
893 compiler make recursion much less efficient than it is in most
894 Lisps. Some schools of thought prefer to use recursion in Lisp
895 over other techniques; they would sum a list of numbers using
898 (defun sum-list (list)
900 (+ (car list) (sum-list (cdr list)))
903 where a more iteratively-minded programmer might write one of
906 (let ((total 0)) (dolist (x my-list) (incf total x)) total)
907 (loop for x in my-list sum x)
909 While this would be mainly a stylistic choice in most Common Lisps,
910 in Emacs Lisp you should be aware that the iterative forms are
911 much faster than recursion. Also, Lisp programmers will want to
912 note that the current Emacs Lisp compiler does not optimize tail