Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 38 Β· Macros

Macros: Code as Data in Common Lisp

Learn what Common Lisp macros are, why homoiconicity makes them possible, how a macro differs from a function and when evaluation order forces you to write one.

Macros are the feature people usually mean when they say Lisp is "programmable". A Lisp program is written as lists, and Lisp programs can build and take apart lists, so a program can write other programs before they ever run. A macro is a function that runs at compile time, receives unevaluated code as its arguments and returns new code to be compiled in its place.

This chapter turns that sentence into working skill. In this first lesson you will see why code is data, how a macro differs from a function, and the one question that tells you when you need a macro at all.

SBCL, CLISP and the other Common Lisp compilers cannot run on this site. The Common Lisp snippets are read-only and I only show output I am certain about. The runnable examples are JavaScript stand-ins: JS arrays play the role of Lisp lists, JS strings play the role of symbols, and null plays nil. They demonstrate the underlying idea, not real Lisp.

Code is a list

Look at this Common Lisp form:

LISP
(+ 1 (* 2 3))

It is a list of three elements: the symbol +, the number 1 and another list (* 2 3). The reader turns text into that nested list, and the evaluator walks it. Because the program is already a list, you can build one yourself:

LISP
(list '+ 1 (list '* 2 3))   ; => (+ 1 (* 2 3))
(eval (list '+ 1 (list '* 2 3)))   ; => 7

Languages whose source has the same shape as their basic data structure are called homoiconic. In most other languages, to generate code you must paste strings together and hope the result parses. In Lisp you manipulate a tree that is already the program.

JS Stand-in: a program is a tree

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

No output.

The evaluator here is tiny, but the point carries over: building doubled took one line of list construction.

What a macro does

A function receives values. By the time (square (+ 1 2)) calls square, the argument has already become 3. A macro receives the form itself, the list (+ 1 2), and returns a new form. The compiler then replaces the macro call with that result (this replacement is called macro expansion) and compiles it.

LISP
(defmacro square-it (x)
  (list '* x x))

(square-it 5)   ; expands to (* 5 5), so 25

Notice that square-it ran once, at compile time, producing (* 5 5). At run time only the multiplication remains; the macro itself has vanished. This is why macros add no call overhead and why they can introduce new syntax.

flowchart LR
    A["Source text<br/>(square-it 5)"] -->|reader| B["List<br/>(square-it 5)"]
    B -->|macro expansion| C["List<br/>(* 5 5)"]
    C -->|compiler| D["Machine code"]
    D -->|run time| E["25"]

The macro runs between reading and compiling; the program that runs never contains it.

When a function is not enough

The decisive question is: must some argument be left unevaluated, or evaluated in a special way? Consider writing your own if as a function:

LISP
(defun my-if (test then else)
  (cond (test then) (t else)))

(my-if (> 3 2) (print "yes") (print "no"))

Both (print "yes") and (print "no") are evaluated before my-if is called, so both lines print. A function cannot decide to skip an argument. The macro version never evaluates the branch it does not use:

LISP
(defmacro my-if (test then else)
  (list 'cond (list test then) (list t else)))
JS Stand-in: function versus macro

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

No output.

A real macro does better than a thunk: it rewrites the code so no extra function object exists at all. Thunks only imitate "do not evaluate yet".

Macro, function or special operator?

You want to… Use
compute a value from values a function
skip, repeat or reorder evaluation of arguments a macro
bind a name without quoting it ((with-x (v 1) …)) a macro
wrap code in cleanup (with-open-file) a macro
pass it to mapcar or apply a function (macros cannot be passed as values)

Many Common Lisp operators you already use are macros: when, unless, dolist, dotimes, loop, defun, setf, push, incf. Only about two dozen are special operators implemented by the compiler itself, such as if, let, quote, function and progn. Everything else is built from those with macros.

LISP
(macro-function 'when)       ; non-NIL: WHEN is a macro
(special-operator-p 'if)     ; T

Do not reach for a macro first

A macro is harder to debug, cannot be used with funcall, and is expanded when code is compiled, so redefining a macro does not update already compiled callers. The community rule of thumb: if a function can do the job, write a function. Use defmacro only when you need control over evaluation, new binding forms or compile-time computation. The next lessons show how to write macros safely: backquote templates, debugging expansions and avoiding variable capture.

Check your understanding

Quick check Β· 4 questions

of 4 answered You scored / 4 Β· perfect!

  1. 1. When does a macro run?

    A macro is expanded once while the code is compiled. Its result replaces the macro call, and the macro itself is gone at run time.
  2. 2. What does a macro receive as arguments?

    Macros work on code as data, so they get the forms exactly as written, not their values.
  3. 3. Why can my-if not be written correctly as a function?

    Argument evaluation happens before a function body runs. To skip an argument you need a macro (or a special operator).
  4. 4. Which of these can you NOT do with a macro?

    Macros are not first-class values, so (mapcar #'when ...) does not work. Use a function or wrap the macro call in a lambda.

Summary

  • Lisp source is made of lists, so programs can construct and transform programs (homoiconicity).
  • A macro is a compile-time function from forms to forms; its expansion replaces the call.
  • Use a macro when you must control evaluation, bind names or add syntax; otherwise use a function.
  • Many everyday operators (when, dolist, loop, defun) are macros built from a small set of special operators.
  • The JavaScript snippets here are stand-ins that model the ideas, not Common Lisp itself.

Next: defmacro and Backquote