Macro Lambda Lists

A macro lambda list is used in describing macros defined by the operators in Figure 3–17.

With the additional restriction that an environment parameter may appear only once (at any of the positions indicated), a macro lambda list has the following syntax:

A macro lambda list can contain the lambda list keywords shown in Figure 3–18.

  &allow-other-keys  &environment  &rest      &aux               &key          &whole     &body              &optional             

Optional parameters (introduced by &optional) and keyword parameters (introduced by &key) can be supplied in a macro lambda list, just as in an ordinary lambda list. Both may contain default initialization forms and supplied-p parameters.

&body

is identical in function to &rest, but it can be used to inform certain output-formatting and editing functions that the remainder of the form is treated as a body, and should be indented accordingly. Only one of &body or &rest can be used at any particular level; see Destructuring by Lambda Lists.

&body can appear at any level of a macro lambda list; for details, see Destructuring by Lambda Lists.

&whole

is followed by a single variable that is bound to the entire macro-call form; this is the value that the macro function receives as its first argument.

If &whole and a following variable appear, they must appear first in lambda-list,

before any other parameter or lambda list keyword.

&whole can appear at any level of a macro lambda list. At inner levels, the &whole variable is bound to the corresponding part of the argument, as with &rest, but unlike &rest, other arguments are also allowed. The use of &whole does not affect the pattern of arguments specified.

&environment

is followed by a single variable that is bound to an environment representing the lexical environment in which the macro call is to be interpreted. This environment should be used with

macro-function,

get-setf-expansion,

compiler-macro-function,

and macroexpand (for example) in computing the expansion of the macro, to ensure that any lexical bindings or definitions established in the compilation environment are taken into account.

&environment can only appear at the top level of a macro lambda list, and can only appear once, but can appear anywhere in that list;

the &environment parameter is bound along with &whole before any other variables in the lambda list, regardless of where &environment appears in the lambda list.

The object that is bound to the environment parameter has dynamic extent.

Destructuring allows a macro lambda list to express the structure of a macro call syntax. If no lambda list keywords appear, then the macro lambda list is a tree containing parameter names at the leaves. The pattern and the macro form must have compatible tree structure; that is, their tree structure must be equivalent, or it must differ only in that some leaves of the pattern match non-atomic objects of the macro form.

For information about error detection in this situation, see Destructuring Mismatch.

A destructuring lambda list (whether at top level or embedded) can be dotted, ending in a parameter name. This situation is treated exactly as if the parameter name that ends the list had appeared preceded by &rest.

It is permissible for a macro form (or a subexpression of a macro form) to be a dotted list only when (... &rest var) or (... . var) is used to match it. It is the responsibility of the macro to recognize and deal with such situations.

[Editorial Note by KMP: Apparently the dotted-macro-forms cleanup doesn’t allow for the macro to ‘manually’ notice dotted forms and fix them as well. It shouldn’t be required that this be done only by &REST or a dotted pattern; it should only matter that ultimately the non-macro result of a full-macro expansion not contain dots. Anyway, I plan to address this editorially unless someone raises an objection.]