Basic usage

Matching Literals

The simplest thing you can do is match literals:

(let [x true
      y true
      z true]
  (match [x y z]
    [_ false true] 1
    [false true _ ] 2
    [_ _ false] 3
    [_ _ true] 4
    :else 5))

Note that the only clause that matches the values of the local variables is the fourth one. "Wildcards", the _, in the pattern signifies values that are present that you don't actually care about.

When matching on a single variable you may omit the brackets:

(let [x true]
  (match x
    true 1
    false 2
    :else 5))

Binding

You may match values and give them names for later use:

(let [x 1 y 2]
  (match [x y]
    [1 b] b
    [a 2] a
   :else nil))

This may seem pointless here but in complex patterns this feature becomes more useful (consider red black tree balancing for example).

Sequential types

You may match sequences by using the sequence matching facility:

(let [x [1 2 nil nil nil]]
  (match [x]
    [([1] :seq)] :a0
    [([1 2] :seq)] :a1
    [([1 2 nil nil nil] :seq)] :a2
    :else nil))

Note this works on all ISeqs as well as Sequential types.

Vector types

You can also match vector types, the benefit is much better performance when you want to test something internal without looking at earlier values - random access:

(let [x [1 2 3]]
  (match [x]
    [[_ _ 2]] :a0
    [[1 1 3]] :a1
    [[1 2 3]] :a2
    :else :a3))

core.match will optimize this case and test the third column first.

Rest patterns

Both seq and vector patterns support rest patterns. As in Clojure's builtin destructuring, rest pattern will capture the "rest" of a collection.

(let [x '(1 2)]
  (match [x]
    [([1] :seq)] :a0
    [([1 & r] :seq)] [:a1 r]
    :else nil))

Map patterns

core.match supports matching maps. Here is a simple example:

(let [x {:a 1 :b 1}]
  (match [x]
    [{:a _ :b 2}] :a0
    [{:a 1 :b 1}] :a1
    [{:c 3 :d _ :e 4}] :a2
    :else nil))

This will return :a1. Note that if you specify a key but you don't care about its value, you are asserting that the key must at least be present. For example:

(let [x {:a 1 :b 1}]
  (match [x]
    [{:c _}] :a0
    :else :no-match))

will return :no-match since the map does not have the key :c.

It's also useful to specify that some map has only a set of specified keys, this can be accomplished with the :only map pattern modifier:

(let [x {:a 1 :b 2}]
  (match [x]
    [({:a _ :b 2} :only [:a :b])] :a0
    [{:a 1 :c _}] :a1
    [{:c 3 :d _ :e 4}] :a2
    :else nil))

This will return :a0 however the following:

(let [x {:a 1 :b 2 :c 3}]
  (match [x]
    [({:a _ :b 2} :only [:a :b])] :a0
    [{:a 1 :c _}] :a1
    [{:c 3 :d _ :e 4}] :a2
    :else nil))

Will return :a1.

Or patterns

core.match supports "or"" patterns - sugar for specifying alternatives.

(let [x 4 y 6 z 9]
  (match [x y z]
    [(:or 1 2 3) _ _] :a0
    [4 (:or 5 6 7) _] :a1
    :else nil))

This is much more succinct that having to define six separate clauses.

Guards

core.match supports arbitrary guards on patterns:

(match [1 2]
  [(_ :guard #(odd? %)) (_ :guard odd?)] :a1
  [(_ :guard #(odd? %)) _] :a2
  :else :a4)