Mastering Clojure Macros

Write Cleaner, Faster, Smarter Code

by Colin Jones

Level up your skills by taking advantage of Clojure’s powerful macro system. Macros make hard things possible and normal things easy. They can be tricky to use, and this book will help you deftly navigate the terrain. You’ll discover how to write straightforward code that avoids duplication and clarifies your intentions. You’ll learn how and why to write macros. You’ll learn to recognize situations when using a macro would (and wouldn’t!) be helpful. And you’ll use macros to remove unnecessary code and build new language features.

Clojure offers some sharp tools in its toolbox, and one of the sharpest is its macro system. This book will help you write macros using Clojure, and more importantly, recognize when you should be using macros in the first place.

The Lisp “code-as-data” philosophy gives tremendous advantages to macro authors and users. You can use macros to evaluate code in other contexts, move computations to compile time, and create beautiful API layers. You don’t need to wait on the Clojure language itself to add new features, you’ll learn how to implement even the lowest-level features as macros. You’ll step through representative samples of how to use macros in production libraries and applications, find clear details on how to construct macros, and learn pointers to avoid obstacles that often trip up macro amateurs.

Clojure macros are more straightforward to use than metaprogramming features in many other languages, but they’re different enough from normal programming to present challenges of their own. Mastering Clojure Macros examines some of these issues, along with alternatives to macros where they exist.

By the time you finish this book, you’ll be thinking like a macro professional.

The book examples have been developed under Clojure 1.6.0, although earlier and later versions of Clojure may work as well. You’ll want to use Leiningen 2.x in order to follow along with the examples that use external projects.

Tips for Clojure Macros

As Clojure programmers, we use macros all the time, even if we don’t write them ourselves. So understanding the details of how macros work is a time investment that pays off right away.

• As a first approximation, write macros only where functions won’t do.
• Use syntax-quoting and gensyms to avoid accidental symbol capture.
• Keep track of whether a piece of code will be run at compile time or run time.
• Try writing the code you want to generate first (assuming specific inputs), and then the macro that expands to that code.
• If you have the input you need to do work at compile time, you may be able to use macros to speed up your app’s runtime.
• Often macros can be replaced by higher-order functions using thunks (functions of no arguments), but you do lose some of the syntax benefits.
• Consider the assumptions a new user of your macro will make, and how you can make their jobs easier through error messages, documentation, or other tools.
• Read and understand the code for macros that you use from the Clojure language and other open-source libraries. It’ll teach you a lot about what to do, and what to avoid.

Q & A

1. I already know some Clojure and have written some macros. Will this be review for me?

You actually sound like my target audience: someone who knows Clojure but is interested in digging a little deeper into macros. It’s hard for me to say for sure without being in your place, but there should be some interesting challenges for everyone. Take a look at the sample chapters and see what you think!

2. What’s a macro?

You can think of a macro as being sort of like a function, but one that transforms and replaces the code that it’s given at compile time. So it allows you to write code that generates other code: metaprogramming! And in Lisps, since the code is represented just like the data structures in the language, a lot of times it’s pretty similar to regular programming.

3. I’ve heard that you should avoid macros - why write a book about them?

Ah, right, so people say you shouldn’t use a macro where a function will do, which I’m 100% on board with. I think when you start out as a Clojure programmer, it’s easy to go overboard because (among other reasons) they can be sort of contagious. I talk about some of the problems with macros in Chapter 3, “Use Your Powers Wisely.” But back to the question: I actually learned a lot of what I know about macros from a couple of great macro-focused books, On Lisp and Let Over Lambda. And I figured it would’ve been nice to have had a book in Clojure, so I could focus on the ideas I wanted to learn instead of a new language.

4. I noticed a category of macro you left out of the book.

That’s not a question. Yes, unfortunately I didn’t have room to cover all the use cases I’ve seen, so there are a number of interesting use cases that I didn’t talk about. Send me an example and a note, though - I’m compiling some interesting macros at clojuremacros.com and I’d love to consider your macro idea for inclusion there! And if you’ve got any other questions, come on over to forums where I’m happy to discuss the book with you!

• Errata, typos, suggestions

• Source Code (zip file)

Releases:

• P1.0 2014/08/20

• Acknowledgments
• Introduction
  • Why Clojure?
  • Why Macros?
  • Metaprogramming in Non-Lisps
  • Who Is This Book For?
  • What’s in This Book?
  • How to Read This Book
  • Online Resources
• Build a Solid Foundation
  • Code Is Data
  • Transforming Code
  • Evaluating Your First Macro
  • Macroexpansion
• Advance Your Macro Techniques excerpt
  • Syntax-Quoting and Unquoting
  • Approaching Hygiene with the Gensym
  • Secret Macro Voodoo
• Use Your Powers Wisely
  • Macros Aren’t Values
  • Macros Can Be Contagious
  • Macros Can Be Tricky to Get Right
• Evaluate Code in Context
  • Dynamic Bindings
  • Evaluating (or Not) in Time and Place
  • Rescuing Errors
  • Cleaning Up Resources
• Speed Up Your Systems excerpt
  • Benchmarking Your Code
  • Hiding Performance Optimizations
  • Moving Execution to Compile Time
• Build APIs That Say Just What They Mean
  • Compojure
  • Clojure Koans
  • Decoupling Macros from Functions
• Bend Control Flow to Your Will
  • Loops and Loops and Loops and…
  • Turning Expressions Inside Out with Threading Macros
  • Delimited Continuations
• Implement New Language Features
  • Implementing Pattern Matching
  • Error Handling in Macros
  • Code-Walking Macros
  • Macros Are [Not] Magic