I use Clojure's threading macros perhaps more than I should, but I do so because they mimic the way I think about the code I write. A lisp programme is a tree and yet most of the programmes that we write are, or should be, lines of functions acting on a datastructure1 2.

The value of threading macros

1
2

(* 3 (+ 2 (- 10 (+ 10 (/ 2 2)))))
                         ^

To grok this code I have to start from the bottommost leaf, in this case (/ 2 2), yet it is at the line's far right contrary to where it is natural for me and most of the world3 to start reading. Conversely the same code written with a threading macro mirrors how we think about what the code is doing.

1
2

(-> 2 (/ 2) (+ 10) (- 10) (+ 2) (* 3))
    ^

They also force the programmer into writing simpler code because threading macros don't handle trees well.

1
2
3
4
5
6

(-> 2
    (/ 2)
    (+ 10)
    (- (-> 25 (/ 5) (* 2)))
    (+ 2)
    (* 3))

What a mess. It's much better to split it into two linear forms.

1
2
3

;; Better do this
(let [x (-> 25 (/ 5) (* 2))]
  (-> 2 (/ 2) (+ 10) (- x) (+ 2) (* 3)))

So threading macros help make easy things simple and complex things hard4.

as->

as-> allows one to use a symbol to specify where the threaded value goes in each form. It is helpful when the threaded value's position in the function's arguments changes. Some Clojure functions take the datastructure as the first argument, others take a function.

1
2
3

(as-> (db/get id) $
  (update $ :foo f x y)
  (map g $))

some->

some-> works similarly to ->, except that evaluation of the form terminates as soon as the threaded value becomes nil. It's named for some? which only returns false if its argument is nil. It is, generally, unnecessary in Clojure. Why? Because Clojure's core functions, and the functions that we write, gracefully handle nil.

1
2
3
4
5
6
7

(map + nil) ; => ()
(assoc nil :k :v) ; => {:k :v}
(dissoc nil :k) ; => nil
(str nil) ; => ""
(+ nil) ; => nil
(- nil) ; => NullPointerException,
        ; it's not always the case

The same cannot be said for calling functions in Java. Try adding a value to a null HashMap, or .toString on a null object, and you'll throw a NullPointerException.

1
2
3
4
5
6
7
8
9

(-> id
    db/find-by-id
    (.put "foo" "bar")
    db/save)

(-> id
    db/find-by-id
    (assoc :id id "foo" "bar")
    db/save)

If db/find-by-id returns nil, implying a missing entity, the first form will explode when it tries to .put on a null object. The second gracefully creates and saves a new entity. If we still need to deal with the Java method, we can do so by either wrapping the form in a try form, or use some->.

1
2
3
4
5
6

(if-some [save-result (some-> id
                              db/find-by-id
                              (.put "foo" "bar")
                              db/save)]
  (handle-success save-result)
  (handle-missing-entity id))

if-some is just like if-let, except instead of the test failing for falsy values, it fails for nil values. Equivalently, the test passes for (some? test) instead of (true? test).

When db/find-by-id returns nil, some-> immediately returns nil without evaluating the remaining forms of the threading macro, .put and db/save. if-some then handles the case of a missing entity. Otherwise, as long as db/save returns any non-nil value, it is bound to save-result and (handle-success save-result) will be called, even if the result is false.

cond->

I have found cond->, named for cond, to be the biggest code-saver out of any of Clojure's rarer standard library functions. Again, I use it mostly when working with Java, specifically with Builders. A Builder is one of the most common patterns you will see in object-oriented languages, it works to progressively build up an object, allowing for each field to have a default value, set fields by more convoluted means5, or verify fields before they are set6.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

public class EnterpriseIntegrator {

    private String foo;
    private String bar;
    private String qux;
    private String quux;

    public EnterpriseIntegrator (
        String foo, String bar, String qux, String quux) {
        // ...
    };

    public newBuilder () {
        return new EnterpriseIntegratorBuilder();
    }
}

public class EnterpriseIntegratorBuilder {

    private String foo = "foo";
    private String bar = "bar";
    private String qux = "qux";
    private String quux = "quux";

    public EnterpriseIntegratorBuilder foo (String foo) {
        this.foo = foo;
        return this;
    }

    // ...

    public EnterpriseIntegrator build () {
        return new EnterpriseIntegrator (
            this.foo, this.bar, this.qux, this.quux);
    }
}

Of course, if this was Clojure we could just do this:

1
2
3

(def defaults {:foo "foo" :bar "bar" :qux "qux" :quux "quux"})
(merge defaults {:foo "foobar" :bar "baz"})
;; => {:foo "foobar" :bar "baz" :qux "qux" :quux "quux"}

But occasionally we will need to use a Java-style Builder.

1
2
3
4
5

(-> (new EnterpriseIntegratorBuilder)
    (.foo f)
    (.bar b)
    (.qux q)
    (.quux qu))

This blows up in ones face if this code get called by someone who wants to use the default value and doesn't want to set foo. In that case f is nil and a NullPointerException is thrown. cond-> is a threading macro that allows us to only evaluate a form if a predicate returns true, and can be used to avoid this style of error.

1
2
3
4

(cond-> x
  (pred-1 f) (.foo "foo")
  (pred-2 b) (.bar "bar")
  (pred-3 q) (.qux "qux"))

If the predicate returns true, the next form is used as it would be in ->. Unlike some->, if a predicate fails the macro doesn't terminate, it just moves onto the next predicate.

If (pred-2 b) is the only predicate to fail, it becomes equivalent to this:

1
2
3

(-> x
    (.foo "foo")
    (.qux "qux"))

We can use this to check that a variable is non-nil before trying to set the field on the Builder.

1
2
3
4
5
6

(defn ->EnterpriseIntegrator [{:keys [foo bar baz]}]
  (cond-> (new EnterpriseIntegrator)
    (some? foo) (.foo foo)
    (some? bar) (.bar bar)
    (some? baz) (.baz baz)
    true (.build)))

And finally we call build to return the EnterpriseIntegrator.

Other macros

->, some->, and cond-> each have a matching macro, ->>, some->>, and cond->>, which inserts the threaded value as the last argument in each form. I don't find them often to be of much use.

You can see Clojure's official guide on the subject here.

1

"It is better to have 100 functions operate on one data structure than to have 10 functions operate on 10 data structures." — Alan Perlis, Epigrams on Programming

2

The Language of the System by Rich Hickey, Conj 2012. Having abandoned object-oriented languages, don't recreate them in the large by building a system of components that look like objects. Instead, choose to structure your system like you structure your functional programmes, pipelines of functions.

3

The major exceptions being Arabic, Hebrew, and Urdu.

4

https://en.wikipedia.org/wiki/Chiasmus

5
1
2
3
4
5

public EnterpriseIntegratorBuilder setCredentials (Credentials creds) {
    this.username = creds.getUsername();
    this.password = creds.getPassword();
    return this;
}
6
1
2
3
4
5
6

public EnterpriseIntegratorBuilder setTimeoutMillis (int to) {
    if (to > 0) {
        this.timeoutMillis = to;
    } // else one can use the default value or throw an exception
    return this;
}