or learn more

Understanding the Clojure -> macro

Sep 4, 2009

Translations: [日本語]

On page 109 of Paul Graham’s ANSI Common Lisp he describes a function compose taken from the Dylan programming language. The function described is very similar to the -> macro that often confuses many a new Clojurian. In order to better understand this little nasty, I’ve found it useful to think of it as an arrow indicating the flow of data from one function to another. That is, the follow:

(-> (Math/sqrt 25) int list)

Can literally be read:

  1. Take the result of (Math/sqrt 25)
  2. Feed it into the function int
  3. Feed that result into the function list

Graphically, this can be viewed as:

(Math/sqrt 25) --5.0--> (int 5.0) --5--> (list 5) 
=> (5)

Which expands into the following s-expression:

(list (int (Math/sqrt 25)))

When viewed this way, the -> macro can be said to “thread” 1 a sequence of forms into each in turn. This threading can be done within any form and is always stitched in as the second argument to the outermost s-expression. Clojurians will sometimes use the comma 2 as a visual marker for the stitch point:

(-> (/ 144 12) (/ ,,, 2 3) str keyword list)
=> (:2)

(-> (/ 144 12) (* ,,, 4 (/ 2 3)) str keyword (list ,,, :33))
=> (:32 :33)

Unfortunately, the documentation for -> does not do justice to its power, but hopefully things are a little more clear now.


  1. Not the java.lang.Thread kind of thread. 

  2. Since commas are considered whitespace. The number of comma’s used as a marker is a matter of taste. 

6 Comments, Comment or Ping

  1. The final example produces (:32 :33)

  2. (-> (/ 144 12) (* ,,, 4 (/ 2 3)) str keyword (list ,,, :33))

    evaluates to

    (:32 :33)

    for me. :)

    But thanks for the explanation. I’d be a bit more direct than you were (you very diplomatic, I thought) and state that the doc string for -> sucks. You should submit a patch to it.

  3. @Hugo @Andera

    D’oh! Serves me right for not re-REPLing the problem after changing it during the course of the modifications. :(

    Thanks for the comments. -m

  4. Anderson De Andrade

    Clojure API is missing examples for each function/macro.

    Some macros can be explained with just one line of code instead of juicy paragraphs. “Threads the expr through the forms”: I was thinking of processing threads.

  5. Understanding Clojure API is useful for each function/ macro. Some macros can be explained with just one line of code and I was thinking if this was the process threads. But I guess some API is missing on examples for each function/macro.

Reply to “Understanding the Clojure -> macro”