Matchure: Serious Clojure Pattern Matching

One of the things I find myself yearning for in a lot of programming languages is a powerful pattern matching system. I wrote one for ruby, but ruby’s syntax just wasn’t flexible enough to make something as elegant as I’d like. When I started using clojure, it seemed like a great little project for getting to know clojure’s macro facilities as well as clojure itself. I set out to build a kickass pattern matching library for clojure that fit in with the language’s way of doing things and was at least as expressive than any other pattern matching facility I’ve used.

The outcome of this effort, is matchure (github, clojars), a pattern matching library for clojure featuring

  • equality checks,
  • sequence destructuring,
  • map destructuring,
  • regexp matches,
  • variable binding,
  • “instance of” checking,
  • arbitrary clojure expressions,
  • and boolean operators (and, or, not).

All of which compile down to high performance clojure.


Clojure, like most lisps, has a built-in facility which gets you part of the way there: destructuring in most variable-binding contexts. For example,

(let [a 1]
; returns 1

binds 1 to the variable a. You can just as easily grab the first value out of a sequence:

(let [[fst & rst] (list 1 2 3)]
  [fst rst])
; returns [1 (2 3)]

This facility is even more powerful. You can also destructure maps as well. There’s just one problem: let doesn’t work well as a way of testing values.

(let [[fst & rst] (list)]
  [fst rst])
; returns [nil nil]

This is, in part, why I wrote matchure. Matchure provides a pattern matching facility that makes it really easy to perform complex tests against values and bind parts of them to variables.

Syntax and Examples

Like any lisp, clojure is homoiconic – clojure code is represented by clojure data structures. Unlike other lisps, however, clojure has a rich set of data structures with literal representations. '(1 2 3) is a linked list, [1 2 3] is a vector, with fast random access, and {:a 1, :b 2} is a hash map. Furthermore, these syntaxes have special places within clojure itself. Lists are clojure function or macro calls and vectors are used anywhere variables are bound or sequences are destructured. Aside from being a literal representation in code, the hash syntax is used for destructuring maps in let bindings.

Matchure takes this rich set of literal representations and uses it as a natural way to match patterns. At the moment, there are three main forms, if-match, when-match, and cond-match. They work similarly to the clojure built-ins, but match values.

At the most basic level, matchure can be used to test for equality.

(if-match [nil nil] true) ;=> true
(if-match [1 1] true) ;=> true
(if-match ["asdf" "asdf"] true) ;=> true
(let [s "asdf"]
  (if-match ["asdf" s] true)) ;=> true

Regular expression literals test for a match

(if-match [#"hello" "hello world"] true) ;=> true

and fully qualified class names test for instance? relationships.

(if-match [java.lang.String "foo"] true) ;=> true
(if-match [java.lang.Comparable "foo"] true) ;=> true

Matchure supports _ and ? as wildcards, so both of these match anything

(if-match [_ "foo"] true) ;=> true
(if-match [? "foo"] true) ;=> true

_ is idiomatic in clojure when you want to ignore a value. In matchure, ? has special meaning. ? can be thought of as “the thing this part of the pattern is matching against”. As such, ? always matches successfully. It is also used in binding variables. ?foo matches successfully and stores the matched value in the variable foo.

(if-match [?foo "bar"] foo) ;=> "bar"

just like regular clojure, list literals represent clojure code. Here, too, the special meaning of ? comes into play. You can perform arbitrary tests this way using ? to represent the matched against value:

(if-match [(odd? ?) 1] true) ;=> true

Just like with let, you can destructure sequences

(if-match [[?fst & ?rst] [1 2 3]] [fst rst]) ;=> [1 (2 3)]

and maps

(if-match [{:foo (even? ?)} {:foo 2}] true) ;=> true

Finally, unlike any other pattern matching facility I’ve seen, matchure has support for boolean operators.

(if-match [[(and ?fst (even? ?)) & ?rst] [2 3 4]] [fst rst]) ;=> [2 (3 4)]
(if-match [[(and ?fst (even? ?)) & ?rst] [1 2 3]] [fst rst] :failed-match) ;=>:failed-match

or and not are also supported.

You can get the code from github, or use it in your clojure project by grabbing it from clojars.

  • Sam TH says:

    There are many pattern matching facilities that support `and’, `or’, `not’, and other operators. For example:


  • Thanks Sam. I figured there probably were. “Any other pattern matching facility I’ve seen” doesn’t cover very many.

  • Good brief and this post helped me alot in my college assignement. Thanks you on your information.

  • Paul Hobbs says:

    This is awesome! Thank you for sharing this. =]

  • Eric Normand says:

    I wrote something similar for Common Lisp back in the day. It didn’t get any traction.

    There were two cool things about it: it would bind variables to matches from the regex and unification libraries (so you could access them in the body of the cond); and it was extensible with new match types.

    The reason it didn’t get traction is that nobody wants another conditional form in the CL community. It only saves a few indents, and only for rather procedural code.

    Anyway, it’s pretty cool, what you did. Thanks.

  • Comments are closed.