Go to the next chapter.
Common Lisp is a huge language, and Common Lisp systems tend to be massive and extremely complex. Emacs Lisp, by contrast, is rather minimalist in the choice of Lisp features it offers the programmer. As Emacs Lisp programmers have grown in number, and the applications they write have grown more ambitious, it has become clear that Emacs Lisp could benefit from many of the conveniences of Common Lisp.
The CL package adds a number of Common Lisp functions and control structures to Emacs Lisp. While not a 100% complete implementation of Common Lisp, CL adds enough functionality to make Emacs Lisp programming significantly more convenient.
Some Common Lisp features have been omitted from this package for various reasons:
assoc function is incompatible with the
Common Lisp assoc. In such cases, this package usually
adds the suffix `*' to the function name of the Common
Lisp version of the function (e.g., assoc*).
The package described here was written by Dave Gillespie, `daveg@synaptics.com'. It is a total rewrite of the original 1986 `cl.el' package by Cesar Quiroz. Most features of the the Quiroz package have been retained; any incompatibilities are noted in the descriptions below. Care has been taken in this version to ensure that each function is defined efficiently, concisely, and with minimal impact on the rest of the Emacs environment.
Lisp code that uses features from the CL package should include at the beginning:
(require 'cl)
If you want to ensure that the new (Gillespie) version of CL
is the one that is present, add an additional (require 'cl-19)
call:
(require 'cl) (require 'cl-19)
The second call will fail (with "`cl-19.el' not found") if the old `cl.el' package was in use.
It is safe to arrange to load CL at all times, e.g.,
in your `.emacs' file. But it's a good idea, for portability,
to (require 'cl) in your code even if you do this.
The Common Lisp package is organized into four files:
cadr function won't need to pay
the overhead of loading the more advanced functions.
delete-if and assoc*.
The file `cl.el' includes all necessary autoload
commands for the functions and macros in the other three files.
All you have to do is (require 'cl), and `cl.el'
will take care of pulling in the other files when they are
needed.
There is another file, `cl-compat.el', which defines some
routines from the older `cl.el' package that are no longer
present in the new package. This includes internal routines
like setelt and zip-lists, deprecated features
like defkeyword, and an emulation of the old-style
multiple-values feature. See section Old CL Compatibility.
Installation of the CL package is simple: Just put the
byte-compiled files `cl.elc', `cl-extra.elc',
`cl-seq.elc', `cl-macs.elc', and `cl-compat.elc'
into a directory on your load-path.
There are no special requirements to compile this package: The files do not have to be loaded before they are compiled, nor do they need to be compiled in any particular order.
You may choose to put the files into your main `lisp/'
directory, replacing the original `cl.el' file there. Or,
you could put them into a directory that comes before `lisp/'
on your load-path so that the old `cl.el' is
effectively hidden.
Also, format the `cl.texinfo' file and put the resulting Info files in the `info/' directory or another suitable place.
You may instead wish to leave this package's components all in
their own directory, and then add this directory to your
load-path and (Emacs 19 only) Info-directory-list.
Add the directory to the front of the list so the old CL
package and its documentation are hidden.
Except where noted, all functions defined by this package have the same names and calling conventions as their Common Lisp counterparts.
Following is a complete list of functions whose names were changed from Common Lisp, usually to avoid conflicts with Emacs. In each case, a `*' has been appended to the Common Lisp name to obtain the Emacs name:
defun* defsubst* defmacro* function* member* assoc* rassoc* get* remove* delete* mapcar* sort* floor* ceiling* truncate* round* mod* rem* random*
Internal function and variable names in the package are prefixed
by cl-. Here is a complete list of functions not
prefixed by cl- which were not taken from Common Lisp:
member delete remove remq rassoc floatp-safe lexical-let lexical-let* callf callf2 letf letf* defsubst* defalias add-hook eval-when-compile
(Most of these are Emacs 19 features provided to Emacs 18 users,
or introduced, like remq, for reasons of symmetry
with similar features.)
The following simple functions and macros are defined in `cl.el'; they do not cause other components like `cl-extra' to be loaded.
eql floatp-safe abs endp evenp oddp plusp minusp last butlast nbutlast caar .. cddddr list* ldiff rest first .. tenth member [1] copy-list subst mapcar* [2] adjoin [3] acons pairlis when unless pop [4] push [4] pushnew [3,4] incf [4] decf [4] proclaim declaim add-hook
[1] This is the Emacs 19-compatible function, not member*.
[2] Only for one sequence argument or two list arguments.
[3] Only if :test is eq, equal, or unspecified,
and :key is not used.
[4] Only when place is a plain variable name.
@chapno=4
This section describes features of the CL package which have to
do with programs as a whole: advanced argument lists for functions,
and the eval-when construct.
@secno=1
Emacs Lisp's notation for argument lists of functions is a subset of
the Common Lisp notation. As well as the familiar &optional
and &rest markers, Common Lisp allows you to specify default
values for optional arguments, and it provides the additional markers
&key and &aux.
Since argument parsing is built-in to Emacs, there is no way for this package to implement Common Lisp argument lists seamlessly. Instead, this package defines alternates for several Lisp forms which you must use if you need Common Lisp argument lists.
{Special Form} defun* name arglist body...
This form is identical to the regular defun form, except
that arglist is allowed to be a full Common Lisp argument
list. Also, the function body is enclosed in an implicit block
called name; see section Blocks and Exits.
{Special Form} defsubst* name arglist body...
This is just like defun*, except that the function that
is defined is automatically proclaimed inline, i.e.,
calls to it may be expanded into in-line code by the byte compiler.
This is analogous to the defsubst form in Emacs 19;
defsubst* uses a different method (compiler macros) which
works in all version of Emacs, and also generates somewhat more
efficient inline expansions. In particular, defsubst*
arranges for the processing of keyword arguments, default values,
etc., to be done at compile-time whenever possible.
{Special Form} defmacro* name arglist body...
This is identical to the regular defmacro form,
except that arglist is allowed to be a full Common Lisp
argument list. The &environment keyword is supported as
described in Steele. The &whole keyword is supported only
within destructured lists (see below); top-level &whole
cannot be implemented with the current Emacs Lisp interpreter.
The macro expander body is enclosed in an implicit block called
name.
{Special Form} function* symbol-or-lambda
This is identical to the regular function form,
except that if the argument is a lambda form then that
form may use a full Common Lisp argument list.
Also, all forms (such as defsetf and flet) defined
in this package that include arglists in their syntax allow
full Common Lisp argument lists.
Note that it is not necessary to use defun* in
order to have access to most CL features in your function.
These features are always present; defun*'s only
difference from defun is its more flexible argument
lists and its implicit block.
The full form of a Common Lisp argument list is
(var... &optional (var initform svar)... &rest var &key ((keyword var) initform svar)... &aux (var initform)...)
Each of the five argument list sections is optional. The svar, initform, and keyword parts are optional; if they are omitted, then `(var') may be written simply `var'.
The first section consists of zero or more required arguments. These arguments must always be specified in a call to the function; there is no difference between Emacs Lisp and Common Lisp as far as required arguments are concerned.
The second section consists of optional arguments. These
arguments may be specified in the function call; if they are not,
initform specifies the default value used for the argument.
(No initform means to use nil as the default.) The
initform is evaluated with the bindings for the preceding
arguments already established; (a &optional (b (1+ a)))
matches one or two arguments, with the second argument defaulting
to one plus the first argument. If the svar is specified,
it is an auxiliary variable which is bound to t if the optional
argument was specified, or to nil if the argument was omitted.
If you don't use an svar, then there will be no way for your
function to tell whether it was called with no argument, or with
the default value passed explicitly as an argument.
The third section consists of a single rest argument. If
more arguments were passed to the function than are accounted for
by the required and optional arguments, those extra arguments are
collected into a list and bound to the "rest" argument variable.
Common Lisp's &rest is equivalent to that of Emacs Lisp.
Common Lisp accepts &body as a synonym for &rest in
macro contexts; this package accepts it all the time.
The fourth section consists of keyword arguments. These are optional arguments which are specified by name rather than positionally in the argument list. For example,
(defun* foo (a &optional b &key c d (e 17)))
defines a function which may be called with one, two, or more
arguments. The first two arguments are bound to a and
b in the usual way. The remaining arguments must be
pairs of the form :c, :d, or :e followed
by the value to be bound to the corresponding argument variable.
(Symbols whose names begin with a colon are called keywords,
and they are self-quoting in the same way as nil and
t.)
For example, the call (foo 1 2 :d 3 :c 4) sets the five
arguments to 1, 2, 4, 3, and 17, respectively. If the same keyword
appears more than once in the function call, the first occurrence
takes precedence over the later ones. Note that it is not possible
to specify keyword arguments without specifying the optional
argument b as well, since (foo 1 :c 2) would bind
b to the keyword :c, then signal an error because
2 is not a valid keyword.
If a keyword symbol is explicitly specified in the argument list as shown in the above diagram, then that keyword will be used instead of just the variable name prefixed with a colon. You can specify a keyword symbol which does not begin with a colon at all, but such symbols will not be self-quoting; you will have to quote them explicitly with an apostrophe in the function call.
Ordinarily it is an error to pass an unrecognized keyword to
a function, e.g., (foo 1 2 :c 3 :goober 4). You can ask
Lisp to ignore unrecognized keywords, either by adding the
marker &allow-other-keys after the keyword section
of the argument list, or by specifying an :allow-other-keys
argument in the call whose value is non-nil. If the
function uses both &rest and &key at the same time,
the "rest" argument is bound to the keyword list as it appears
in the call. For example:
(defun* find-thing (thing &rest rest &key need &allow-other-keys)
(or (apply 'member* thing thing-list :allow-other-keys t rest)
(if need (error "Thing not found"))))
This function takes a :need keyword argument, but also
accepts other keyword arguments which are passed on to the
member* function. allow-other-keys is used to
keep both find-thing and member* from complaining
about each others' keywords in the arguments.
In Common Lisp, keywords are recognized by the Lisp parser itself
and treated as special entities. In Emacs, keywords are just
symbols whose names begin with colons, which defun* has
arranged to set equal to themselves so that they will essentially
be self-quoting.
As a (significant) performance optimization, this package
implements the scan for keyword arguments by calling memq
to search for keywords in a "rest" argument. Technically
speaking, this is incorrect, since memq looks at the
odd-numbered values as well as the even-numbered keywords.
The net effect is that if you happen to pass a keyword symbol
as the value of another keyword argument, where that
keyword symbol happens to equal the name of a valid keyword
argument of the same function, then the keyword parser will
become confused. This minor bug can only affect you if you
use keyword symbols as general-purpose data in your program;
this practice is strongly discouraged in Emacs Lisp.
The fifth section of the argument list consists of auxiliary
variables. These are not really arguments at all, but simply
variables which are bound to nil or to the specified
initforms during execution of the function. There is no
difference between the following two functions, except for a
matter of stylistic taste:
(defun* foo (a b &aux (c (+ a b)) d)
body)
(defun* foo (a b)
(let ((c (+ a b)) d)
body))
Argument lists support destructuring. In Common Lisp,
destructuring is only allowed with defmacro; this package
allows it with defun* and other argument lists as well.
In destructuring, any argument variable (var in the above
diagram) can be replaced by a list of variables, or more generally,
a recursive argument list. The corresponding argument value must
be a list whose elements match this recursive argument list.
For example:
(defmacro* dolist ((var listform &optional resultform)
&rest body)
...)
This says that the first argument of dolist must be a list
of two or three items; if there are other arguments as well as this
list, they are stored in body. All features allowed in
regular argument lists are allowed in these recursive argument lists.
In addition, the clause `&whole var' is allowed at the
front of a recursive argument list. It binds var to the
whole list being matched; thus (&whole all a b) matches
a list of two things, with a bound to the first thing,
b bound to the second thing, and all bound to the
list itself. (Common Lisp allows &whole in top-level
defmacro argument lists as well, but Emacs Lisp does not
support this usage.)
One last feature of destructuring is that the argument list may be
dotted, so that the argument list (a b . c) is functionally
equivalent to (a b &rest c).
If the optimization quality safety is set to 0
(see section Declarations), error checking for wrong number of
arguments and invalid keyword arguments is disabled. By default,
argument lists are rigorously checked.
Normally, the byte-compiler does not actually execute the forms in
a file it compiles. For example, if a file contains (setq foo t),
the act of compiling it will not actually set foo to t.
This is true even if the setq was a top-level form (i.e., not
enclosed in a defun or other form). Sometimes, though, you
would like to have certain top-level forms evaluated at compile-time.
For example, the compiler effectively evaluates defmacro forms
at compile-time so that later parts of the file can refer to the
macros that are defined.
{Special Form} eval-when (situations...) forms...
This form controls when the body forms are evaluated.
The situations list may contain any set of the symbols
compile, load, and eval (or their long-winded
ANSI equivalents, :compile-toplevel, :load-toplevel,
and :execute).
The eval-when form is handled differently depending on
whether or not it is being compiled as a top-level form.
Specifically, it gets special treatment if it is being compiled
by a command such as byte-compile-file which compiles files
or buffers of code, and it appears either literally at the
top level of the file or inside a top-level progn.
For compiled top-level eval-whens, the body forms are
executed at compile-time if compile is in the situations
list, and the forms are written out to the file (to be executed
at load-time) if load is in the situations list.
For non-compiled-top-level forms, only the eval situation is
relevant. (This includes forms executed by the interpreter, forms
compiled with byte-compile rather than byte-compile-file,
and non-top-level forms.) The eval-when acts like a
progn if eval is specified, and like nil
(ignoring the body forms) if not.
The rules become more subtle when eval-whens are nested;
consult Steele (second edition) for the gruesome details (and
some gruesome examples).
Some simple examples:
;; Top-level forms in foo.el: (eval-when (compile) (setq foo1 'bar)) (eval-when (load) (setq foo2 'bar)) (eval-when (compile load) (setq foo3 'bar)) (eval-when (eval) (setq foo4 'bar)) (eval-when (eval compile) (setq foo5 'bar)) (eval-when (eval load) (setq foo6 'bar)) (eval-when (eval compile load) (setq foo7 'bar))
When `foo.el' is compiled, these variables will be set during the compilation itself:
foo1 foo3 foo5 foo7 ; `compile'
When `foo.elc' is loaded, these variables will be set:
foo2 foo3 foo6 foo7 ; `load'
And if `foo.el' is loaded uncompiled, these variables will be set:
foo4 foo5 foo6 foo7 ; `eval'
If these seven eval-whens had been, say, inside a defun,
then the first three would have been equivalent to nil and the
last four would have been equivalent to the corresponding setqs.
Note that (eval-when (load eval) ...) is equivalent
to (progn ...) in all contexts. The compiler treats
certain top-level forms, like defmacro (sort-of) and
require, as if they were wrapped in (eval-when
(compile load eval) ...).
Emacs 19 includes two special forms related to eval-when.
One of these, eval-when-compile, is not quite equivalent to
any eval-when construct and is described below. This package
defines a version of eval-when-compile for the benefit of
Emacs 18 users.
The other form, (eval-and-compile ...), is exactly
equivalent to `(eval-when (compile load eval) ...)' and
so is not itself defined by this package.
{Special Form} eval-when-compile forms...
The forms are evaluated at compile-time; at execution time,
this form acts like a quoted constant of the resulting value. Used
at top-level, eval-when-compile is just like `eval-when
(compile eval)'. In other contexts, eval-when-compile
allows code to be evaluated once at compile-time for efficiency
or other reasons.
This form is similar to the `#.' syntax of true Common Lisp.
{Special Form} load-time-value form
The form is evaluated at load-time; at execution time, this form acts like a quoted constant of the resulting value.
Early Common Lisp had a `#,' syntax that was similar to
this, but ANSI Common Lisp replaced it with load-time-value
and gave it more well-defined semantics.
In a compiled file, load-time-value arranges for form
to be evaluated when the `.elc' file is loaded and then used
as if it were a quoted constant. In code compiled by
byte-compile rather than byte-compile-file, the
effect is identical to eval-when-compile. In uncompiled
code, both eval-when-compile and load-time-value
act exactly like progn.
(defun report ()
(insert "This function was executed on: "
(current-time-string)
", compiled on: "
(eval-when-compile (current-time-string))
;; or '#.(current-time-string) in real Common Lisp
", and loaded on: "
(load-time-value (current-time-string))))
Byte-compiled, the above defun will result in the following code (or its compiled equivalent, of course) in the `.elc' file:
(setq --temp-- (current-time-string))
(defun report ()
(insert "This function was executed on: "
(current-time-string)
", compiled on: "
'"Wed Jun 23 18:33:43 1993"
", and loaded on: "
--temp--))
This section describes a feature from GNU Emacs 19 which this package makes available in other versions of Emacs.
{Function} defalias symbol function
This function sets symbol's function cell to function.
It is equivalent to fset, except that in GNU Emacs 19 it also
records the setting in load-history so that it can be undone
by a later unload-feature.
In other versions of Emacs, defalias is a synonym for
fset.
Go to the next chapter.