cl: Argument Lists
2.1 Argument Lists
==================
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.
-- Macro: cl-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;
Blocks and Exits.
-- Macro: cl-iter-defun name arglist body...
This form is identical to the regular ‘iter-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; Blocks and Exits.
-- Macro: cl-defsubst name arglist body...
This is just like ‘cl-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; ‘cl-defsubst’ uses a different
method (compiler macros) which works in all versions of Emacs, and
also generates somewhat more efficient inline expansions. In
particular, ‘cl-defsubst’ arranges for the processing of keyword
arguments, default values, etc., to be done at compile-time
whenever possible.
-- Macro: cl-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’s book
‘Common Lisp, the Language’. 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.
-- Macro: cl-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 ‘cl-flet’ and ‘cl-labels’) defined in this
package that include ARGLISTs in their syntax allow full Common Lisp
argument lists.
Note that it is _not_ necessary to use ‘cl-defun’ in order to have
access to most CL features in your function. These features are always
present; ‘cl-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,
(cl-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.
You can also explicitly specify the keyword argument; it need not be
simply the variable name prefixed with a colon. For example,
(cl-defun bar (&key (a 1) ((baz b) 4)))
specifies a keyword ‘:a’ that sets the variable ‘a’ with default
value 1, as well as a keyword ‘baz’ that sets the variable ‘b’ with
default value 4. In this case, because ‘baz’ is not self-quoting, you
must quote it explicitly in the function call, like this:
(bar :a 10 'baz 42)
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:
(cl-defun find-thing (thing &rest rest &key need &allow-other-keys)
(or (apply 'cl-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 ‘cl-member’ function.
‘allow-other-keys’ is used to keep both ‘find-thing’ and ‘cl-member’
from complaining about each others’ keywords in the arguments.
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:
(cl-defun foo (a b &aux (c (+ a b)) d)
BODY)
(cl-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 ‘cl-defun’ and other argument lists as well. In destructuring, any
argument variable (VAR in the above example) 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:
(cl-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 (
Declarations), error checking for wrong number of arguments and
invalid keyword arguments is disabled. By default, argument lists are
rigorously checked.
Info Catalog
cl: Program Structure
cl: Time of Evaluation