Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 38 ยท Macros

macroexpand and Debugging Macros

Learn macroexpand-1, macroexpand, pretty-printing and the habits that make Common Lisp macros debuggable: test expansions first, read errors and avoid compile-time surprises.

When a function misbehaves you print its arguments. When a macro misbehaves, the interesting thing is the code it generated, and that is what macroexpand shows. Debugging a macro is mostly reading its expansion and asking "is this the code I meant to write by hand?"

No Lisp compiler runs here, so Lisp snippets are read-only and the outputs shown are ones I am certain about (SBCL prints symbols in upper case). The JavaScript examples are labelled stand-ins that mimic expansion.

macroexpand-1 and macroexpand

macroexpand-1 expands the outermost macro call once. macroexpand repeats until the head is no longer a macro.

LISP
(defmacro my-unless (test &body body)
  `(if ,test nil (progn ,@body)))

(macroexpand-1 '(my-unless (> x 3) (print "small")))
;; => (IF (> X 3) NIL (PROGN (PRINT "small")))
;;    T

There are two return values: the expansion and T when a macro was expanded (NIL if the form was not a macro call). Quote the form, because you want to inspect it, not run it.

Standard macros work too, and the result can show you how the language is built:

LISP
(macroexpand-1 '(when a b c))
;; => (IF A (PROGN B C))
;;    T

Implementations may expand a standard macro into internal code ((macroexpand-1 '(push x list)) shows SETQ-like forms with implementation-specific variables), so treat those expansions as illustrations, not as portable promises.

Only the outer layer

macroexpand expands only the head of the form. If a macro's expansion contains other macro calls deeper inside, they stay unexpanded:

LISP
(macroexpand '(my-unless a (my-unless b c)))
;; => (IF A NIL (PROGN (MY-UNLESS B C)))

To see everything, use your environment's full walker. SBCL has sb-cltl2:macroexpand-all (after (require :sb-cltl2)), and SLIME and SLY offer C-c M-m (expand all) and C-c C-m (expand once) on the form at the cursor. The REPL commands are not portable across implementations, but the habit is.

JS Stand-in: macro table, expand-1 and expand-all

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Pretty printing and readability

Large expansions are unreadable on one line. Enable the pretty printer:

LISP
(let ((*print-pretty* t))
  (pprint (macroexpand-1 '(with-timing (:label "sort") (sort data #'<)))))

pprint lays the code out with indentation. In SLIME the macroexpansion buffer does this for you.

A debugging routine

  1. Write the code you want by hand first. If you cannot, you are not ready to write the macro.
  2. Write the macro. Keep it small; push logic into helper functions.
  3. macroexpand-1 a representative call and compare to your hand-written code.
  4. Test edge cases: an empty body, a body with several forms, arguments with side effects, nested uses.
  5. Check evaluation count. If an argument appears twice in the expansion, it is evaluated twice (see the next lesson).
LISP
(defmacro square-it (x) `(* ,x ,x))

(macroexpand-1 '(square-it (incf n)))
;; => (* (INCF N) (INCF N))   ; the side effect happens twice: a bug

Helper functions need eval-when

If a macro calls a helper function you defined with defun in the same file, the helper may not exist when the macro runs at compile time. Wrap it:

LISP
(eval-when (:compile-toplevel :load-toplevel :execute)
  (defun make-names (prefix n)
    (loop for i from 1 to n collect (intern (format nil "~a~d" prefix i)))))

(defmacro with-vars ((prefix n) &body body)
  `(let ,(mapcar (lambda (s) (list s 0)) (make-names prefix n))
     ,@body))

Without eval-when, compiling the file may fail with "undefined function MAKE-NAMES" while expanding with-vars, even though the function is defined above it. Alternatively, use macrolet or put helpers in a separate, already loaded system.

Reading macro errors

Errors in a macro show up at two stages:

  • Expansion time: the compiler reports an error in the macro call form, usually a wrong argument count or destructuring failure such as "error while parsing arguments to DEFMACRO MY-LET1".
  • Run time: the generated code is wrong, so the trace points at code you never wrote. The cure is always macroexpand-1.

Also remember that redefining a macro does not update compiled callers; recompile the files that use it (or reload the system) after changing a macro.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does macroexpand-1 do?

    macroexpand-1 performs one step on the head of the form. macroexpand repeats the step while the head is still a macro.
  2. 2. What is the second value returned by macroexpand-1?

    The second value reports whether an expansion happened.
  3. 3. Why can (macroexpand '(my-unless a (my-unless b c))) still contain MY-UNLESS?

    Only the outer call is rewritten; a code walker such as macroexpand-all is needed for the inner ones.
  4. 4. A macro helper defined with defun is 'undefined' while compiling a file. What is the usual fix?

    The macro runs at compile time, so the helper must be available then.

Summary

  • macroexpand-1 shows one step of expansion, macroexpand repeats it, and a code walker expands everywhere.
  • Always compare the expansion to the code you would write by hand.
  • Check for duplicated arguments (multiple evaluation) and for missing eval-when around helpers.
  • Recompile callers after redefining a macro.
  • The JavaScript expander is a stand-in that models head-only versus deep expansion.

Next: Variable Capture and gensym