When To Use a Macro in Clojure

Ready to take your Clojure to the next level?

Deepen your Clojure skills with my Advanced Clojure Signature Course.

• 8 advanced modules
• 84 profound lessons
• 30 hours of video

buy now

Summary: Macros should be avoided to the extent possible. There are three circumstances where they are required.

There's a common theme in Lisp that you should only use macros when you need them. It is very common to see a new lisper overuse macros. I did it myself when I first learned Lisp. They are very powerful and make you the king of syntax.

Clojure macros do have their uses, but why should you avoid them if possible? The principle reason is that macros are not first-class in Clojure. You cannot access them at runtime. You cannot pass them as an argument to a function, nor do any of the other powerful stuff you've come to love from functional programming. In short, macros are not functional programming (though they can make use of it).

A function, on the other hand, is a first-class value, and so is available for awesome functional programming constructs. You should prefer functions to macros.

That said, macros are still useful because there are things macros can do that functions cannot. What are the powers of a macro that are unavailable to any other construct in Clojure? If you need any of these abilities, write a macro.

1. The code has to run at compile time

There are just some things that need to happen at compile time. I recently wrote a macro that returns the hash of the current git commit so that the hash can be embedded in the ClojureScript compilation. This needs to be done at compile time because the script will be run somewhere else, where it cannot get the commit hash. Another example is performing expensive calculations at compile time as an optimization.

Example:

(defmacro build-time []
  (str (java.util.Date.)))

The build-time macro returns a String representation of the time it is run.

Running code at compile time is not possible in anything other than macros.

2. You need access to unevaled arguments

Macros are useful for writing new, convenient syntactic constructs. And when we talk about syntax, we are typically talking about raw, unevaluated sexpressions.

Example:

(defmacro when
  "Evaluates test. If logical true, evaluates body in an implicit do."
  {:added "1.0"}
  [test & body]
  (list 'if test (cons 'do body)))

clojure.core/when is a syntactic sugar macro which transforms into an if with a do for a then and no else. The body should not be evaled before the test is checked.

Getting access to the unevaluated arguments is available by quoting (' or (quote ...)), but that is often unacceptable for syntactic constructs. Macros are the only way to do that.

3. You need to emit inline code

Sometimes calling a function is unacceptable. That call is either too expensive or is otherwise not the behavior you want.

For instance, in Javascript in the browser, you can call console.log('msg') to print out a message and the line number to the console. In ClojureScript, this becomes something like this: (.log js/console "msg"). Not convenient at all. My first thought was to create a function.^1

(defn log [msg]
  (.log js/console msg))

This worked alright for printing the message, but the line numbers were all pointing to the same line: the body of the function! console.log records the line exactly where it is called, so it needs to be inline. I replaced it with a macro, which highlights its purpose as syntactic sugar.

Example:

(defmacro log [msg]
  `(.log js/console ~msg))

The body replaces the call to log, so it is located where it is needed for the proper behavior.

If you need inline code, a macro is the only way.

Other considerations

Of course, any combination of these is also acceptable. And don't forget that although you might need a macro, macros are only available at compile time. So you should consider providing a function that does the same thing and then wrap it with a macro.

Conclusion

Macros are very powerful. Their power comes with a price: they are only available at compile time. Because of that, functions should be preferred to macros. The use of macros should be reserved for those special occasions when their power is needed.

1. As it should be :)