Program Structure Program Structure Time of Evaluation
Emacs Lisp's notation for argument lists of functions is a subset of
the Common Lisp notation. As well as the familiar
&rest markers, Common Lisp allows you to specify default
values for optional arguments, and it provides the additional markers
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.
defunform, 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 Blocks and Exits.
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
defsubstform 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.
defmacroform, except that arglist is allowed to be a full Common Lisp argument list. The
&environmentkeyword is supported as described in Steele. The
&wholekeyword is supported only within destructured lists (see below); top-level
&wholecannot be implemented with the current Emacs Lisp interpreter. The macro expander body is enclosed in an implicit block called name.
functionform, except that if the argument is a
lambdaform then that form may use a full Common Lisp argument list.
Also, all forms (such as
in this package that include arglists in their syntax allow
full Common Lisp argument lists.
Note that it is not necessary to use
order to have access to most CL features in your function.
These features are always present;
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 `
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.
&rest is equivalent to that of Emacs Lisp.
Common Lisp accepts
&body as a synonym for
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
b in the usual way. The remaining arguments must be
pairs of the form
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
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
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
&allow-other-keys after the keyword section
of the argument list, or by specifying an
argument in the call whose value is non-
nil. If the
function uses both
&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
allow-other-keys is used to
member* from complaining
about each others' keywords in the arguments.
As a (significant) performance optimization, this package
implements the scan for keyword arguments by calling
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.
(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
(a b &rest c).
If the optimization quality
safety is set to 0
(see Declarations), error checking for wrong number of
arguments and invalid keyword arguments is disabled. By default,
argument lists are rigorously checked.