
ANSI Common Lisp 3 Evaluation and Compilation 3.8 Dictionary Evaluation and Compilation
3.8.12 macroexpand, macroexpand1 
Function 
 Syntax:

macroexpand
form &optional env
expansion, expandedp
macroexpand1
form &optional env
expansion, expandedp
 Arguments and Values:

form  a form.
env  an environment object.
The default is nil.
expansion  a form.
expandedp  a generalized boolean.
 Description:

macroexpand and macroexpand1 expand macros.
If form is a macro form,
then macroexpand1 expands the macro form call once.
macroexpand
repeatedly expands form until it is no longer a macro form.
In effect, macroexpand calls macroexpand1 repeatedly
until the secondary value it returns is nil.
If form is a macro form,
then the expansion is a macro expansion
and expandedp is true.
Otherwise,
the expansion is the given form
and expandedp is false.
Macro expansion is carried out as follows.
Once macroexpand1 has
determined that the form is a macro form,
it obtains an appropriate expansion function for the
macro or symbol macro.
The value of
*macroexpandhook* is
coerced to a function and
then called as a function of three arguments:
the expansion function,
the form,
and the env.
The value returned from this call is taken to be the expansion
of the form.
In addition to macro definitions in the global environment,
any local macro definitions established within env by macrolet
or symbolmacrolet are considered.
If only form is supplied as an argument,
then the environment is effectively null, and only global macro definitions
as established by defmacro are considered.
Macro definitions are shadowed by local function definitions.
 Examples:

(defmacro alpha (x y) `(beta ,x ,y)) ALPHA
(defmacro beta (x y) `(gamma ,x ,y)) BETA
(defmacro delta (x y) `(gamma ,x ,y)) EPSILON
(defmacro expand (form &environment env)
(multiplevaluebind (expansion expandedp)
(macroexpand form env)
`(values ',expansion ',expandedp))) EXPAND
(defmacro expand1 (form &environment env)
(multiplevaluebind (expansion expandedp)
(macroexpand1 form env)
`(values ',expansion ',expandedp))) EXPAND1
;; Simple examples involving just the global environment
(macroexpand1 '(alpha a b)) (BETA A B), true
(expand1 (alpha a b)) (BETA A B), true
(macroexpand '(alpha a b)) (GAMMA A B), true
(expand (alpha a b)) (GAMMA A B), true
(macroexpand1 'notamacro) NOTAMACRO, false
(expand1 notamacro) NOTAMACRO, false
(macroexpand '(notamacro a b)) (NOTAMACRO A B), false
(expand (notamacro a b)) (NOTAMACRO A B), false
;; Examples involving lexical environments
(macrolet ((alpha (x y) `(delta ,x ,y)))
(macroexpand1 '(alpha a b))) (BETA A B), true
(macrolet ((alpha (x y) `(delta ,x ,y)))
(expand1 (alpha a b))) (DELTA A B), true
(macrolet ((alpha (x y) `(delta ,x ,y)))
(macroexpand '(alpha a b))) (GAMMA A B), true
(macrolet ((alpha (x y) `(delta ,x ,y)))
(expand (alpha a b))) (GAMMA A B), true
(macrolet ((beta (x y) `(epsilon ,x ,y)))
(expand (alpha a b))) (EPSILON A B), true
(let ((x (list 1 2 3)))
(symbolmacrolet ((a (first x)))
(expand a))) (FIRST X), true
(let ((x (list 1 2 3)))
(symbolmacrolet ((a (first x)))
(macroexpand 'a))) A, false
(symbolmacrolet ((b (alpha x y)))
(expand1 b)) (ALPHA X Y), true
(symbolmacrolet ((b (alpha x y)))
(expand b)) (GAMMA X Y), true
(symbolmacrolet ((b (alpha x y))
(a b))
(expand1 a)) B, true
(symbolmacrolet ((b (alpha x y))
(a b))
(expand a)) (GAMMA X Y), true
;; Examples of shadowing behavior
(flet ((beta (x y) (+ x y)))
(expand (alpha a b))) (BETA A B), true
(macrolet ((alpha (x y) `(delta ,x ,y)))
(flet ((alpha (x y) (+ x y)))
(expand (alpha a b)))) (ALPHA A B), false
(let ((x (list 1 2 3)))
(symbolmacrolet ((a (first x)))
(let ((a x))
(expand a)))) A, false
 Affected By:

defmacro,
setf of macrofunction,
macrolet,
symbolmacrolet
 See Also:

*macroexpandhook*,
defmacro,
setf of macrofunction,
macrolet,
symbolmacrolet,
Section 3.1 Evaluation
 Notes:

Neither macroexpand nor macroexpand1
makes any explicit attempt to expand macro forms that are
either subforms of the form
or subforms of the expansion.
Such expansion might occur implicitly, however,
due to the semantics or implementation of the macro function.
 Allegro CL Implementation Details:

See cl:macroexpand and cl:macroexpand1
in implementation.htm
for information on the implementation of macroexpand and macroexpand1. Note
the links are to the documentation for the current Allegro CL
version. Replace /current/ in the URL with the Allegro CL version
number to see similar documentation is earlier releases.
