🍵 Matcha - first-class match specifications for Elixir

Officially announcing Matcha!


Available on GitHub and hex.pm, Matcha is a library for composing and using match specifications in Elixir. It’s intended to help you perform really fast, selective :ets queries, and refine how you can study the function calls in your running programs.


A really powerful but difficult-to-use feature of the BEAM VM are match specifications. I’ve wrapped them with Matcha to make them much more accessible to Elixir programmers, and am working hard to have great documentation on how to use them where they shine:

The Problem

The thing Matcha works to solve: match specifications are already kind of a a chore to use from erlang code. This is compounded when trying to use them from Elixir, since they really just encode an informal erlang AST. Alchemists have to be familiar with erlang syntax and do a lot of mental context switching to tap into their benefits.

Additionally, the APIs and documentation around how to build and use them in :ets and tracing is very dense. Some great guides exist out there, but I want to marry an easier-to-use-API with rich, first-class Elixir documentation and livebooks to make these topics more approachable.

The Solution

I get in to the why, how, and when of match specifications as they exist today in my ElixirConf 2022 talk. I also tease a library to help with them—and have been teasing it throughout its several years of intermittent development—and here we finally are.

Matcha employs Elixir’s macro system and compiler to convert familiar Elixir pattern matches into this oblique format, with rich compile-time validation, and exposes some nicer APIs for working with the resulting match specs.

The Future

In the holiday work lull, I’m able to find a little more time to pick up development again. My hope is to treat this thread as a bit of a devlog for now, and a changelog after a v0.2.0 release with a more stable API. Hopefully I can entice some of you to check things out, and even help me improve it—especially the documentation.

Follow this thread, or the forum’s #matcha topic, to stay abreast of further developments!



this is broken.

Fixed, thanks!

Great project!

By the way, is there any way to combine two specs together? Or put one spec into the other?

1 Like

There’s a bit of discussion around that on GH: FEATURE: add support for pattern / spec composition · Issue #23 · christhekeele/matcha · GitHub, but it wanders off in other directions pretty quickly.

In short, I think it’s a good idea, and want to add it! The main thing I’m waiting on is understanding a few more people’s usecases before figuring out how it’d work. If you wanted to contribute to that issue’s discussion, it’d be very helpful!

1 Like

I just played around with this library, love it so far :slight_smile: Not so intimidating to do efficient queries to ETS anymore :slight_smile:

1 Like

I’ve just added a helper to latest to merge matchspecs. It comes with a few caveats, but should be useful for composing matches. It’ll be available next release!


I meant something like

merge(spec(do: [head | _] -> head), spec(do: {left, right} -> left + right))

To result in

spec(do: [{left, right} | _] -> left + right)


broken again :stuck_out_tongue:

This seems pretty ambiguous, no? It’s not clear why the merge would know to replace the head binding specifically. What if there are two bindings?

It seems like, to get what you want, you’d need to be able to specify “higher order” specs of some kind that explicitly declare the “vars” or whatever that you’re replacing.

var_spec([head], do: [head | _] -> head)

This seems somewhat complex. I wonder if there is a better approach that might allow “nesting” but delegate composition to regular Elixir functions.

s1 = spec(do: {left, right} -> left + right})

spec bind: [head: s1] do
  [head | _] -> head

I have a library called Pathex which does this kind of nesting. But I just was curious if it is possible with match specs.

For multiple arguments I’d prefer to have the same behaviour. For example,

spec1 = spec(do: [head | tail] -> head + tail)
spec2 = spec(do: {left, right} -> left * right)

merge(spec1, spec2)
# Results in
spec(do: [{head_left, head_right} | {tail_left, tail_right}] -> (head_left * head_right) + (tail_left * tail_right))

Yep, this is my intuition about such a feature; I’m not aiming at supporting it mostly because that’s beyond the scope of normal matchspec usage.

The behaviour here seems rather undefined, I can think of dozens of ways to approach embedding complicated matchspecs in each other.

1 Like

Hmm. Where are you finding these dead links, in particular? I moved the guides and ExDoc doesn’t really support redirects; but I though any internal links were corrected with my last fix.

guides section has 3 links. all broken.

Ahh whoops, thanks again so much for reporting. Released v0.1.7 to fix just now.

Very cool to see this @christhekeele!

1 Like

Thanks for the help with the tracing docs, @Onor.io! Promise I’m getting to more of your notes…