Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 36 ยท Functions and Higher-Order Functions

Composition and Threading Macros in Clojure

Write readable data pipelines with the threading macros ->, ->>, as->, some->, some->> and cond->, learn when to use comp or transducers instead, and refactor nested calls into pipelines.

Clojure code nests: the result of one call is the argument of the next. A pipeline of five steps becomes five levels of parentheses, read from the inside out. Threading macros rewrite such code so you read it top to bottom, in the order things happen. They are macros that change the shape of code before it runs, so they cost nothing at runtime.

The problem

Suppose you want the names of adults, upper-cased, sorted and joined:

CLOJURE
(str/join ", "
  (sort
    (map str/upper-case
      (map :name
        (filter #(>= (:age %) 18) people)))))

You have to start at the innermost call and work outwards. The threading macros let you write the same thing in reading order.

->> : thread last

->> takes a value and inserts it as the last argument of each following form. That is exactly what the sequence functions (map, filter, reduce, take...) expect, because they take the collection last:

CLOJURE
(->> people
     (filter #(>= (:age %) 18))
     (map :name)
     (map str/upper-case)
     sort
     (str/join ", "))

Each line receives the result of the previous one. A bare symbol such as sort is treated as (sort) and so becomes (sort previous).

-> : thread first

-> inserts the value as the first argument of each form. This suits functions on maps, strings and records, where the main subject comes first (assoc, update, dissoc, get):

CLOJURE
(-> {:name "ada" :age 36}
    (assoc :city "London")
    (update :name str/capitalize)
    (update :age inc)
    (dissoc :city))
;; => {:name "Ada", :age 37}

A quick rule: collection-processing functions (map, filter) take the collection last, use ->>; subject-first functions (assoc, get, update, str/trim) take it first, use ->.

JS Stand-in: a pipeline written top to bottom

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JavaScript can chain array methods because they are methods of the array. Clojure achieves the same readability for any functions with a macro.

as-> : name the value

When some steps need the value first and others last, as-> binds it to a name you choose, and you place the name where you want it:

CLOJURE
(as-> [3 1 2] v
  (sort v)
  (map inc v)
  (conj (vec v) 100)
  (get v 0))
;; => 2

Use it sparingly, it is a sign to check whether the steps could be reorganised.

some-> and some->> : stop at nil

some-> threads like -> but stops and returns nil the moment a step produces nil. It is the safe way to chain lookups that might be missing:

CLOJURE
(some-> {:user {:profile {:email "[email protected]"}}}
        :user :profile :email str/upper-case)
;; => "[email protected]"

(some-> {:user nil} :user :profile :email str/upper-case)
;; => nil   without a NullPointerException

some->> does the same for last-argument threading.

cond-> : conditional steps

cond-> threads a value through steps that apply only when their test is truthy; the tests are not threaded:

CLOJURE
(defn build-query [params]
  (cond-> {:table "users"}
    (:active params) (assoc :where "active = true")
    (:limit params)  (assoc :limit (:limit params))
    (:sort params)   (assoc :order-by (:sort params))))

(build-query {:active true :limit 10})
;; => {:table "users", :where "active = true", :limit 10}

This replaces a chain of if statements that each rebind the same name.

Which threading macro?

-> Value goes first. For maps and strings.
->> Value goes last. For map and filter.
as-> Name it, place it anywhere.
some-> Stop at the first nil.

cond-> adds steps only when a test is true.

1 / 2

Seeing what a macro does

A threading macro just rewrites your code. You can check the rewrite with macroexpand:

CLOJURE
(macroexpand '(-> x (f a) (g b)))
;; => (g (f x a) b)

(macroexpand '(->> x (f a) (g b)))
;; => (g b (f a x))

Thinking of the expansion explains every result: -> slides the value into the first slot, ->> into the last.

JS Stand-in: what -> and ->> expand to

Press Run (or Ctrl + Enter) to see the console output here.

No output.

comp versus threading

Both express pipelines, with a key difference: threading runs a pipeline on a value now, while comp builds a reusable function.

CLOJURE
(def clean (comp str/lower-case str/trim))   ; reusable function
(clean "  HELLO ")                           ; "hello"

(-> "  HELLO " str/trim str/lower-case)       ; run once, in reading order

Note that comp applies functions right to left while -> reads left to right. To build a left-to-right reusable function, wrap a threading form in fn, or use (apply comp (reverse fns)).

Transducers: reusable sequence pipelines

If you thread several map and filter steps, each one creates an intermediate lazy sequence. A transducer pipeline combines the same steps into a single pass, with no intermediate collections, and can be reused on vectors, channels and more:

CLOJURE
(def xf
  (comp (filter odd?)
        (map #(* % %))
        (take 3)))

(into [] xf (range 20))          ; [1 9 25]
(transduce xf + (range 20))      ; 35

Note that comp here composes the transformation steps in the order that data flows (filter first). Transducers are an optimisation and a reuse tool; write the plain ->> version first and switch only when profiling asks for it.

If a threaded pipeline grows beyond five or six steps, extract named functions for the middle parts. A pipeline of well-named steps documents itself.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Where does ->> insert the threaded value in each form?

    ->> puts the value last, which matches map, filter and reduce.
  2. 2. What does (-> 5 (- 2) (* 3)) return?

    ->: (- 5 2) is 3, then (* 3 3) is 9.
  3. 3. What is the purpose of some->?

    some-> avoids a NullPointerException when a step might be missing.
  4. 4. What does (->> [1 2 3 4] (filter even?) (map #(* % %))) return?

    The even numbers 2 and 4 are squared, giving (4 16).
  5. 5. How does comp differ from ->>?

    comp returns a function (applied right to left); threading evaluates a pipeline immediately.

Summary

  • -> threads a value as the first argument, ->> as the last; both rewrite code at compile time.
  • as-> names the value; some-> and some->> stop at nil; cond-> applies steps conditionally.
  • comp builds a reusable function (right to left); transducers combine steps into one pass.
  • Use macroexpand to see exactly what a macro produces.
  • Extract named functions when a pipeline gets long.

Next: The Sequence Abstraction