A macro call looks just like a function call in that it is a list which starts with the name of the macro. The rest of the elements of the list are the arguments of the macro.
Evaluation of the macro call begins like evaluation of a function call except for one crucial difference: the macro arguments are the actual expressions appearing in the macro call. They are not evaluated before they are given to the macro definition. By contrast, the arguments of a function are results of evaluating the elements of the function call list.
Having obtained the arguments, Lisp invokes the macro definition just
as a function is invoked. The argument variables of the macro are bound
to the argument values from the macro call, or to a list of them in the
case of a
&rest argument. And the macro body executes and
returns its value just as a function body does.
The second crucial difference between macros and functions is that the value returned by the macro body is an alternate Lisp expression, also known as the expansion of the macro. The Lisp interpreter proceeds to evaluate the expansion as soon as it comes back from the macro.
Since the expansion is evaluated in the normal manner, it may contain calls to other macros. It may even be a call to the same macro, though this is unusual.
Note that Emacs tries to expand macros when loading an uncompiled Lisp file. This is not always possible, but if it is, it speeds up subsequent execution. See How Programs Do Loading.
You can see the expansion of a given macro call by calling
This function expands form, if it is a macro call. If the result
is another macro call, it is expanded in turn, until something which is
not a macro call results. That is the value returned by
macroexpand. If form is not a macro call to begin with, it
is returned as given.
macroexpand does not look at the subexpressions of
form (although some macro definitions may do so). Even if they
are macro calls themselves,
macroexpand does not expand them.
macroexpand does not expand calls to inline functions.
Normally there is no need for that, since a call to an inline function is
no harder to understand than a call to an ordinary function.
If environment is provided, it specifies an alist of macro definitions that shadow the currently defined macros. Byte compilation uses this feature.
(defmacro inc (var) (list 'setq var (list '1+ var)))
(macroexpand '(inc r)) ⇒ (setq r (1+ r))
(defmacro inc2 (var1 var2) (list 'progn (list 'inc var1) (list 'inc var2)))
(macroexpand '(inc2 r s))
⇒ (progn (inc r) (inc s)) ;
inc not expanded here.
macroexpand-all expands macros like
will look for and expand all macros in form, not just at the
top-level. If no macros are expanded, the return value is
Repeating the example used for
macroexpand above with
macroexpand-all, we see that
expand the embedded calls to
(macroexpand-all '(inc2 r s)) ⇒ (progn (setq r (1+ r)) (setq s (1+ s)))
This function expands macros like
macroexpand, but it only
performs one step of the expansion: if the result is another macro
macroexpand-1 will not expand it.