Making Macros Simpler

The unless macro is a great simple example, but most macros are more complex. In this section, we’ll build a set of increasingly complex macros, introducing Clojure features as we go. For your reference, the following table summarizes the features introduced.

First let’s build a replica of Clojure’s .. macro. We’ll call it chain, since it chains a series of method calls. Here are some sample expansions of chain:

Begin by implementing the simple case where the chain calls only one method. The macro needs only to make a simple list:

chain needs to support any number of arguments, so the rest of the implementation should define a recursion. The list manipulation becomes more complex, since you need to build two lists and concat them together:

Test chain using macroexpand to make sure it generates the correct expansions:

The chain macro works fine as written, but it’s difficult to read the expression that handles more than one argument:

The definition of chain oscillates between macro code and the body to be generated. The intermingling of the two makes the entire thing hard to read. And this is just a baby of a form, only one line in length. As macro forms grow more complex, assembly functions such as list and concat quickly obscure the meaning of the macro.

One solution to this kind of problem is a templating language. If macros were created from templates, you could take a “fill-in-the-blanks” approach to creating them. The definition of chain might look like this:

In this hypothetical templating language, the ${} lets you substitute arguments into the macro expansion.

Notice how much easier the definition is to read and how it clearly shows what the expansion will look like.

Syntax Quote, Unquote, and Splicing Unquote

Clojure macros support templating without introducing a separate language. The syntax quote character, which is a backquote (‘), works almost like normal quoting. But inside a syntax-quoted list, the unquote character (~, a tilde) turns quoting off again. The overall effect is templates that look like this:

Test that this new version of chain can correctly generate a single method call:

Unfortunately, the syntax quote/unquote approach won’t quite work for the multiple-argument variant of chain:

When you expand this chain, the parentheses aren’t quite right:

The last argument to chain is a list of more arguments. When you drop more into the macro “template,” it has parentheses because it’s a list. But you don’t want these parentheses; you want more to be spliced into the list. This comes up often enough that there is a reader macro for it: splicing unquote (~@). Rewrite chain using splicing unquote to splice in more:

Now, the expansion should be spot on:

Many macros follow the pattern of chain, aka Clojure ..

1. Begin the macro body with a syntax quote (‘) to treat the entire thing as a template.
2. Insert individual arguments with an unquote (~).
3. Splice in more arguments with splicing unquote (~@).

The macros we’ve built so far have been simple enough to avoid creating any bindings with let or binding. Let’s create such a macro next.

Creating Names in a Macro

Clojure has a time macro that times an expression, writing the elapsed time to the console:

Let’s build a variant of time called bench, designed to collect data across many runs. Instead of writing to the console, bench will return a map that includes both the return value of the original expression and the elapsed time.

The best way to begin writing a macro is to write its desired expansion by hand. bench should expand like this:

The let binds start to the start time and then executes the expression to be benched, binding it to result. Finally, the form returns a map including the result and the elapsed time since start.

With the expansion in hand, you can now work backward and write the macro to generate the expansion. Using the technique from the previous section, try writing bench using syntax quoting and unquoting:

If you try to call this version of bench, Clojure will complain:

Clojure is accusing you of trying to let a qualified name, which is illegal. Calling macroexpand-1 confirms the problem:

When a syntax-quoted form encounters a symbol, it resolves the symbol to a fully qualified name. At the moment, this seems like an irritant, because you want to create local names, specifically start and result. But Clojure’s approach protects you from a nasty macro bug called symbol capture.

What would happen if macro expansion did allow the unqualified symbols start and result, and then bench was later used in a scope where those names were already bound to something else? The macro would capture the names and bind them to different values, with bizarre results. If bench captured its symbols, it would appear to work fine most of the time. Adding 1 and 2 gives you 3:

…until the unlucky day that you picked a local name like start, which collided with a name inside bench:

bench captures the symbol start and binds it to (System/nanoTime). All of a sudden, “1 plus 2” seems to equal 1228277342451783002.

Clojure’s insistence on resolving names in macros helps protect you from symbol capture, but you still don’t have a working bench. You need some way to introduce local names, ideally unique ones that can’t collide with any names used by the caller.

Clojure provides a reader form for creating unique local names. Inside a syntax-quoted form, you can append an octothorpe (#) to an unqualified name, and Clojure will create an autogenerated symbol, or auto-gensym: a symbol based on the name plus an underscore and a unique ID. Try it at the REPL:

With automatically generated symbols at your disposal, it’s easy to implement bench correctly:

Test it at the REPL:

Clojure makes it easy to generate unique names, but if you’re determined, you can still force symbol capture. The sample code for the book includes an evil-bench that shows a combination of syntax quoting, quoting, and unquoting that leads to symbol capture. Don’t use symbol capture unless you have a thorough understanding of macros.