Evolving Clojure Through Macros

Keywords

ver. 1.0.0

Learn how Clojure macros operate, how to write them safely, and when to prefer functions.

This unit teaches Clojure macros: what phase they run in, why Lisp makes them natural, how to write them with syntax-quote/unquote/unquote-splicing and auto-gensym, how to inspect core macros, and how to decide when a macro is appropriate versus a function. It covers the read → macroexpand → compile → run phases, demonstrates why control-flow constructs like unless must be macros, and walks through several worked examples and exercises for building real macros.

Full summary

The unit explains macros as compile-time code transformers made possible by Lisp’s code-as-data model. It locates macros in the language processing pipeline—text is read into data structures, macros run during macroexpand to rewrite those structures, then code is compiled to bytecode and later executed—so a macro exists only at expansion time.

A canonical failure-to-function example shows why some constructs cannot be ordinary functions: defining unless as a function evaluates both branches before the function runs, while a macro receives unevaluated forms and can choose which branch to evaluate. The unit then introduces the practical tools for writing readable, correct macros: syntax-quote (\``) to build templates while resolving namespaces, unquote (_{) to inject evaluated pieces, unquote-splicing (}@) to splice sequences into templates, and auto-gensym (name#`) to produce unique symbols and avoid variable capture.

Students read real implementations of small core macros (comment, declare, defonce, and, time) to see these techniques in context, then implement five macros that each demonstrate a distinct technique: transforming forms (infix), selecting among unevaluated bodies (randomly), generating definitions (defwebmethod, defnn), and capturing source forms for better diagnostics (assert-true). These exercises reinforce both the mechanics and the patterns of macro design.

Finally, the unit addresses costs and judgment: macros can extend the language but are not values (they can’t be passed around or composed at runtime) and execute at a different phase, which complicates reasoning and tooling. The guiding rule is pragmatic: prefer functions when they suffice; reach for macros only when you need compile-time rewriting or control over evaluation that functions cannot provide.

Materials

Lecture notesThe unit written out, to read at your own paceOpen → SlidesThe deck to present fromOpen →

Source document

Clojure in Action (2nd Edition), A. Rathore and F. Avila, Manning, Dec. 2015 — Link — Page 189-208

← State and the Concurrent World More on Functional Programming →

--- title: "Evolving Clojure Through Macros" keywords: - ver. 1.0.0 format: html: toc: false --- **Learn how Clojure macros operate, how to write them safely, and when to prefer functions.** > This unit teaches Clojure macros: what phase they run in, why Lisp makes them natural, how to write them with syntax-quote/unquote/unquote-splicing and auto-gensym, how to inspect core macros, and how to decide when a macro is appropriate versus a function. It covers the read → macroexpand → compile → run phases, demonstrates why control-flow constructs like `unless` must be macros, and walks through several worked examples and exercises for building real macros. ::: {.callout-note collapse="true" title="Full summary"} The unit explains macros as compile-time code transformers made possible by Lisp's code-as-data model. It locates macros in the language processing pipeline—text is read into data structures, macros run during macroexpand to rewrite those structures, then code is compiled to bytecode and later executed—so a macro exists only at expansion time. A canonical failure-to-function example shows why some constructs cannot be ordinary functions: defining `unless` as a function evaluates both branches before the function runs, while a macro receives unevaluated forms and can choose which branch to evaluate. The unit then introduces the practical tools for writing readable, correct macros: syntax-quote (`\``) to build templates while resolving namespaces, unquote (`~`) to inject evaluated pieces, unquote-splicing (`~@`) to splice sequences into templates, and auto-gensym (`name#`) to produce unique symbols and avoid variable capture. Students read real implementations of small core macros (`comment`, `declare`, `defonce`, `and`, `time`) to see these techniques in context, then implement five macros that each demonstrate a distinct technique: transforming forms (`infix`), selecting among unevaluated bodies (`randomly`), generating definitions (`defwebmethod`, `defnn`), and capturing source forms for better diagnostics (`assert-true`). These exercises reinforce both the mechanics and the patterns of macro design. Finally, the unit addresses costs and judgment: macros can extend the language but are not values (they can't be passed around or composed at runtime) and execute at a different phase, which complicates reasoning and tooling. The guiding rule is pragmatic: prefer functions when they suffice; reach for macros only when you need compile-time rewriting or control over evaluation that functions cannot provide. ::: ## Materials ::: {.hg-deck} <a class="hg-card" href="notes.qmd">Lecture notesThe unit written out, to read at your own paceOpen →</a> <a class="hg-card" href="slides.qmd">SlidesThe deck to present fromOpen →</a> ::: ## Source document - Clojure in Action (2nd Edition), _A. Rathore and F. Avila_, Manning, Dec. 2015 — [Link](https://www.manning.com/books/clojure-in-action-second-edition) — Page 189-208 ::: {.hg-nav} [← State and the Concurrent World](../6_state_and_the_concurrent_world/index.qmd){.hg-prev} [More on Functional Programming →](../8_more_on_functional_programming/index.qmd){.hg-next} :::