The function macro-function determines whether a given symbol is the name of a macro. The defmacro construct provides a convenient way to define new macros.
The first argument must be a symbol. If the symbol has a function definition that is a macro definition, whether a local one established in the environment env by macrolet or a global one established as if by defmacro, then the expansion function (a function of two arguments, the macro-call form and an environment) is returned. If the symbol has no function definition, or has a definition as an ordinary function or as a special operator but not as a macro, then nil is returned. The function macroexpand or macroexpand-1 is the best way to invoke the expansion function.
It is possible for both macro-function and special-operator-p to be true of a symbol. This is possible because an implementation is permitted to implement any macro also as a special operator for speed. On the other hand, the macro definition must be available for use by programs that understand only the standard special operators listed in table 5.1.
setf may be used with macro-function to install a macro as a symbol’s global function definition:
The value installed must be a function that accepts two arguments, an entire macro call and an environment, and computes the expansion for that call. Performing this operation causes the symbol to have only that macro definition as its global function definition; any previous definition, whether as a macro or as a function, is lost. One cannot use setf to establish a local macro definition; it is an error to supply a second argument to macro-function when using it with setf. It is an error to attempt to redefine the name of a special operator.
See also compiler-macro-function.
defmacro is a macro-defining macro that arranges to decompose the macro-call form in an elegant and useful way. defmacro has essentially the same syntax as defun: name is the symbol whose macro definition we are creating, lambda-list is similar in form to a lambda-list, and the forms constitute the body of the expander function. The defmacro construct arranges to install this expander function, as the global macro definition of name.
While defining forms normally appear at top level, it is meaningful to place them in non-top-level contexts. Furthermore, defmacro should define the expander function within the enclosing lexical environment, not within the global environment.
The body of the expander function defined by defmacro is implicitly enclosed in a block construct whose name is the same as the name of the defined macro. Therefore return-from may be used to exit from the function.
The name is returned as the value of the defmacro form.
If we view the macro call as a list containing a function name and some argument forms, in effect the expander function and the list of (unevaluated) argument forms is given to apply. The parameter specifiers are processed as for any lambda-expression, using the macro-call argument forms as the arguments. Then the body forms are evaluated as an implicit progn, and the value of the last form is returned as the expansion of the macro call.
If the optional documentation string doc-string is present (if not followed by a declaration, it may be present only if at least one form is also specified, as it is otherwise taken to be a form), then it is attached to the name as a documentation string of type function; see documentation.
These three markers are now allowed in other constructs as well.
See lambda-list-keywords.
X3J13 voted in March 1989 to specify that macro environment objects received with the &environment argument of a macro function have only dynamic extent. The consequences are undefined if such objects are referred to outside the dynamic extent of that particular invocation of the macro function. This allows implementations to use somewhat more efficient techniques for representing environment objects.
X3J13 voted in March 1989 to clarify the permitted uses of &body, &whole, and &environment:
defmacro, unlike any other Common Lisp construct that has a lambda-list as part of its syntax, provides an additional facility known as destructuring.
See destructuring-bind, which provides the destructuring facility separately.
Anywhere in the lambda-list where a parameter name may appear, and where ordinary lambda-list syntax (as described in section 5.2.2) does not otherwise allow a list, a lambda-list may appear in place of the parameter name. When this is done, then the argument form that would match the parameter is treated as a (possibly dotted) list, to be used as an argument forms list for satisfying the parameters in the embedded lambda-list. As an example, one could write the macro definition for dolist in this manner:
More examples of embedded lambda-lists in defmacro are shown below.
Another destructuring rule is that defmacro allows any lambda-list (whether top-level or embedded) to 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. For example, the definition skeleton for dolist shown above could instead have been written
If the compiler encounters a defmacro, the new macro is added to the compilation environment, and a compiled form of the expansion function is also added to the output file so that the new macro will be operative at run time. If this is not the desired effect, the defmacro form can be wrapped in an eval-when construct.
It is permissible to use defmacro to redefine a macro (for example, to install a corrected version of an incorrect definition), or to redefine a function as a macro. It is an error to attempt to redefine the name of a special form (see table 5.1) as a macro. See macrolet, which establishes macro definitions over a restricted lexical scope.
See also define-compiler-macro.
Suppose, for the sake of example, that it were desirable to implement a conditional construct analogous to the Fortran arithmetic IF statement. (This of course requires a certain stretching of the imagination and suspension of disbelief.) The construct should accept four forms: a test-value, a neg-form, a zero-form, and a pos-form. One of the last three forms is chosen to be executed according to whether the value of the test-form is positive, negative, or zero. Using defmacro, a definition for such a construct might look like this:
Note the use of the backquote facility in this definition (see section 22.1.3). Also note the use of gensym to generate a new variable name. This is necessary to avoid conflict with any variables that might be referred to in neg-form, zero-form, or pos-form.
If the form is executed by the interpreter, it will cause the function definition of the symbol arithmetic-if to be a macro associated with which is a two-argument expansion function roughly equivalent to
The lambda-expression is produced by the defmacro declaration. The calls to list are the (hypothetical) result of the backquote (‘) macro character and its associated commas. The precise macro expansion function may depend on the implementation, for example providing some degree of explicit error checking on the number of argument forms in the macro call.
Now, if eval encounters
this will be expanded into something like
and eval tries again on this new form. (It should be clear now that the backquote facility is very useful in writing macros, since the form to be returned is normally a complex list structure, typically consisting of a mostly constant template with a few evaluated forms here and there. The backquote template provides a “picture” of the resulting code, with places to be filled in indicated by preceding commas.)
To expand on this example, stretching credibility to its limit, we might allow the pos-form and zero-form to be omitted, allowing their values to default to nil, in much the same way that the else form of a Common Lisp if construct may be omitted:
Then one could write
which would be expanded into something like
The resulting code is correct but rather silly-looking. One might rewrite the macro definition to produce better code when pos-form and possibly zero-form are omitted, or one might simply rely on the Common Lisp implementation to provide a compiler smart enough to improve the code itself.
Destructuring is a very powerful facility that allows the defmacro lambda-list to express the structure of a complicated macro-call syntax. If no lambda-list keywords appear, then the defmacro lambda-list is simply a list, nested to some extent, containing parameter names at the leaves. The macro-call form must have the same list structure. For example, consider this macro definition:
Now consider this macro call:
This would cause the expansion function to receive the following values for its parameters:
| Parameter | Value |
| mouth | m |
| eye1 | (car eyes) |
| eye2 | (cdr eyes) |
| fin1 | f1 |
| length1 | (count-scales f1) |
| fin2 | f2 |
| length2 | (count-scales f2) |
| tail | my-favorite-tail |
The following macro call would be in error because there would be no argument form to match the parameter length1:
The following macro call would be in error because a symbol appears in the call where the structure of the lambda-list requires a list.
The fact that the value of the variable my-favorite-head might happen to be a list is irrelevant here. It is the macro call itself whose structure must match that of the defmacro lambda-list.
The use of lambda-list keywords adds even greater flexibility. For example, suppose it is convenient within the expansion function for halibut to be able to refer to the list whose components are called mouth, eye1, and eye2 as head. One may write this:
Now consider the same valid macro call as before:
This would cause the expansion function to receive the same values for its parameters and also a value for the parameter head:
| Parameter | Value |
| head | (m (car eyes) (cdr eyes)) |
The stipulation that an embedded lambda-list is permitted only where ordinary lambda-list syntax would permit a parameter name but not a list is made to prevent ambiguity. For example, one may not write
because ordinary lambda-list syntax does permit a list following &optional; the list (a b &rest c) would be interpreted as describing an optional parameter named a whose default value is that of the form b, with a supplied-p parameter named &rest (not legal), and an extraneous symbol c in the list (also not legal). An almost correct way to express this is
The extra set of parentheses removes the ambiguity. However, the definition is now incorrect because a macro call such as (loser (car pool)) would not provide any argument form for the lambda-list (a b &rest c), and so the default value against which to match the lambda-list would be nil because no explicit default value was specified. This is in error because nil is an empty list; it does not have forms to satisfy the parameters a and b. The fully correct definition would be either
or
These differ slightly: the first requires that if the macro call specifies a explicitly then it must also specify b explicitly, whereas the second does not have this requirement. For example,
would be a valid call for the second definition but not for the first.