Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 38 ยท Macros

Reader Macros, Compiler Macros and macrolet

Go beyond defmacro in Common Lisp: reader macros and the readtable, macrolet and symbol-macrolet for local syntax, compiler macros for optimization and eval-when staging.

defmacro rewrites forms after the reader has built them. Common Lisp offers three more tools that work at other stages of the pipeline: reader macros change how text becomes forms, local macros (macrolet, symbol-macrolet) scope a rewrite to a region of code, and compiler macros let you optimize calls to an existing function. This lesson explains when each is the right tool.

Lisp snippets are read-only; no Common Lisp runtime exists on this site. The JavaScript examples are stand-ins that model each stage and are labelled as such.

The pipeline

flowchart LR
    T["Text"] -->|"reader (reader macros)"| F["Forms"]
    F -->|"macroexpand (defmacro, macrolet)"| E["Expanded forms"]
    E -->|"compiler (compiler macros)"| C["Machine code"]

Each tool acts at a different stage; pick the earliest stage that solves your problem.

Reader macros and the readtable

The reader consults a readtable that maps characters to functions. You already use reader macros: 'x becomes (quote x), #'f becomes (function f), and #(1 2 3) becomes a vector. You can add your own with set-macro-character:

LISP
(set-macro-character #\! 
  (lambda (stream char)
    (declare (ignore char))
    `(not ,(read stream t nil t))))

'(!ready)       ; => ((NOT READY))

The function receives the stream and the character, reads what follows, and returns the form to use in the source. set-dispatch-macro-character defines #-style two-character syntax such as #j"...".

Reader macros are powerful and dangerous: they change how all following code reads, so a library that globally sets one can break unrelated code. Good practice is to use a named readtable (the named-readtables library provides in-readtable) or bind *readtable* around a small region:

LISP
(let ((*readtable* (copy-readtable)))
  (set-macro-character #\! ...)
  (read-from-string "(!ready)"))

Copying the readtable keeps your change local. Remember that the standard readtable itself must never be modified.

JS Stand-in: a tiny reader with a custom character

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

No output.

macrolet: macros with local scope

macrolet defines macros that exist only inside its body, useful for removing repetition within one function without polluting the package:

LISP
(defun draw (canvas)
  (macrolet ((with-pen ((color) &body body)
               `(let ((old (pen canvas)))
                  (setf (pen canvas) ,color)
                  (unwind-protect (progn ,@body)
                    (setf (pen canvas) old)))))
    (with-pen (:red) (line canvas 0 0 10 10))
    (with-pen (:blue) (line canvas 10 10 20 0))))

The macro is private to draw. (In a real macro you would gensym old, as in the capture lesson.)

symbol-macrolet: names that expand

symbol-macrolet makes a symbol expand into a form. It lets you give a short name to a complicated place, and because the symbol is replaced by the form, setf works through it:

LISP
(let ((board (make-array '(3 3) :initial-element 0)))
  (symbol-macrolet ((center (aref board 1 1)))
    (setf center 5)
    (incf center)
    center))    ; => 6

with-slots in CLOS is built on this idea: each slot name becomes (slot-value obj 'slot).

JS Stand-in: symbol macros as getter/setter pairs

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

No output.

Compiler macros

A compiler macro is attached to a function with define-compiler-macro. The compiler may expand calls to that function into a faster form, but it is allowed to decline, so the function must still work alone and give identical results.

LISP
(defun power (x n)
  (expt x n))

(define-compiler-macro power (&whole form x n)
  (if (eql n 2)
      `(let ((v ,x)) (* v v))     ; v should be a gensym in real code
      form))

When the call is (power y 2), the compiler may replace it with a multiplication; for any other call, returning &whole form leaves the original untouched. Because compilers may ignore them and they can make behavior hard to follow, use compiler macros only where profiling shows a real win. Alexandria and other libraries use them for inline optimizations such as curry.

eval-when and load order

Macros and their helpers must exist at the right time. eval-when lists the situations in which a form is evaluated:

Situation Meaning
:compile-toplevel while compiling the file
:load-toplevel when the compiled file is loaded
:execute when the form is evaluated directly (REPL, load of source)
LISP
(eval-when (:compile-toplevel :load-toplevel :execute)
  (defparameter *prefix* "app-"))

Reader macros that other forms in the same file rely on need eval-when too, or must live in a separate file loaded earlier. ASDF systems (see the tooling chapter) give you that ordering.

Which tool when?

Goal Tool
new surface syntax at the character level reader macro (rare)
a new special form usable everywhere defmacro
a helper only inside one function macrolet
a short name for a place symbol-macrolet
optimize calls to an existing function compiler macro

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. At which stage does a reader macro act?

    The reader calls the macro function for the character and uses the form it returns.
  2. 2. Why is *readtable* usually copied before changing it?

    Modifying the shared readtable changes how all later code is read.
  3. 3. What is special about symbol-macrolet?

    The symbol is replaced by the form, so it can be both read and set (as with-slots does).
  4. 4. What must be true of a function that has a compiler macro?

    Compilers are allowed to ignore compiler macros, so correctness cannot depend on them.

Summary

  • Reader macros change text-to-form conversion; keep them local with a copied or named readtable.
  • macrolet scopes a macro to one body; symbol-macrolet gives a symbol a form (and a setf-able place).
  • Compiler macros optimize calls to a function and must preserve its behavior.
  • eval-when controls when helpers and definitions exist at compile, load and execute time.
  • The JavaScript snippets are stand-ins for the reader and place concepts.

Next: CLOS: Classes and Instances