A nim macro-based pattern matching library.
A library that provides a
match macro which can be used as a pattern matching construct.
matches macro which returns true if a value is matched.
maybeMatches macro which returns an
Option[tuple] of the matched "variables".
var rectangles = @[Rectangle(a: 0, b: 2), Rectangle(a: 4, b: 4), Rectangle(a: 4, b: 4), Rectangle(a: 4, b: 4)] match(rectangles): @: fail() @[_, *(a: 4, b: 4) @others]: # (a: 4, b: 4) is a shorthand for `TypeName(field: value)`, see the next examples check(others == a[1 .. ^1]) # we match the rest, because they all match subpattern _: fail()
It's still experimental, there are some bugs left and the design of the DSL might still change depending on feedback of the community. For now it's a personal project, but I'd love if other people would join as contributors. It's inspired by @andreaferretti 's patty and @krux02 's ast-pattern-matching (and more stuff, there is a credits section!)
- nested subpatterns
- capture subpatterns and values with
- match many elements in seq with
- two kinds of custom unpackers (thanks to @krux02 for making me aware of the scala pattern matching design and apply/unapply: they work differently here though)
- support for recognizing other types as variant
- if guards
- matches expression
- option matching
- Ability to generate code with zero overhead compared to manually written if/case/for equivalents
- Expressive and flexible syntax for patterns and extensible hooks
- Nice error reporting and pretty understandable generated code
The goals are ordered by priority.
Speed is very important: the goal is to be able to use matching everywhere where you'd use a complicated
If there are cases, when we're slower:
This should be considered a bug.
This is a limitation of the library: which is not cool.
Currently not every feature is optimized well(there are some blockers, and some features are still experimental).
The library is supposed to be extensible: please take a look at the unpackers section. For example we already implement the option matching with a
I have a plan about the error reporting part: basically with several hooks inside the current code we should be able to produce good messages. My plan API is
matchDebug(a): # generates an error message describing the comparisons we had and raises it if we hit unimplemented else # or lastMatchError() # if we detect this call, we generate an error message: we don't do it by default to not slow down the code
With some discipline we can generate pretty readable code from our macro. This would be also beneficial for the end user, as we can map his invocation with the generated code and help him see the problem easily.
There are 3 cases:
- The user had a logical error in his patterns: easily seen with the generated code
- The user used a pattern in an unexpected way: this way he can see how its expansion differs from his expectation
- Our patterns worked incorrectly: the user can issue a bug
Just test for equality with the value. Works also if you pass an existing variable instead of 2. For now you can't just pass various expressions tho (2 + 2), as I want to reserve syntax for the patterns
let a = 2 match(a): 2: echo "2" _: echo "no 2"
The library tests with
match(a): Rectangle: # matches Rectangle(a: 0), Rectangle(a: 2, b: 4) echo "rectangle" _: echo "other"
We have a shorthand syntax for objects. You can type only the fields, and then we check only them: this is a good idea because usually you know the type of the object that you are passing, so there is rarely ambiguity. Of course you can still add the type if you want. You can use this for tuples too.
You can pass just some of the fields!
var rectangle = Rectangle(a: 0, b: 0) match(rectangle): (a: 0, b: 0): # matches Rectangle(a: 0, b: 0) echo "ok" Rectangle(a: -2): # matches Rectangle(a: -2) (a: -2, e: 4) echo "weird" _: echo 0
You can match subpatterns.
var a = A(b: B(c: 0, e: 2)) match(a): A(b: B(c: 0)): echo "ok" _: echo "fail"
We capture with
@name for all our usecases: wsubpatterns and values.
stuff @name which shouldn't be ambigious in general(please read the answers and questions section)
match(a): C(e: E(f: @f) @e): # matches C(e: E(f: 0)) and creates local variables f = 0 and e = E(..) echo e echo f _: echo "fail"
We recognize when you do
enumLabel(..) and we match variants then. That's very nice if you are threating them as abstract data types.
match(a): Merge(original: @original, other: @other): echo original Normal(message: @message): echo message _: echo a
You can use
_ as a wildcard, it always succeeds. It's also used as
match(a): @[_]: # matches any value echo a _: echo "nope"
match(a): @[4, 5]: # matches @[4, 5] echo "ok" _: echo "no"
Many elements in seq
You can match repeated properties
var rectangles = @[e, e, Rectangle(a: 0)] match(a): @[_, _, *(a: @list)]: # creates a local variable list which collects the a fields in the matches elements : @ echo list _: echo @
Here we match the elements after 1 and collect their a fields. You can also just
@name the whole subpattern: it should be always a seq.
allIt for the test, but in a case like this, we optimize it out, as it is always true(we just load values).
We can have unpackers for types: you define
proc unpack(t: Type): T for your type.
The powerful thing is,
T can be anything that has a len and
[int](we will add a concept for that later, but it covers seq, tuple).
For example we do this for Rectangle
proc unpack(rectangle: Rectangle): seq[int] = @[rectangle.a, rectangle.b]
Of course we are lucky here, but you can do transformations for more complicated cases.
When you do this, you can use the unpacked values like
Type(value, value) .
We even recognize the enum case, so you can do it for variants too.
we also have function unpackers:
proc name(t: Type): T. This way you can have many unpackers for the same type. This is useful , especially if a builtin type already has a default unpacker, and you need a custom one.
You match passing them as calls with their expected values:
proc data(email: Email): tuple[name: string, domain: string] = let words = email.raw.split('@', 1) (name: words, domain: words) proc tokens(email: Email): seq[string] = # slow result = @ var token = "" for i, c in email.raw: if not c.isAlphaNumeric(): if token.len > 0: result.add(token) token = "" result.add($c) else: token.add(c) if token.len > 0: result.add(token) match(email): data(name: "academy"): # matches data(email) with (name: "academy") echo email tokens(@[_, _, _, _, @token]): # matches tokens(email) echo token
(I got the idea for the email example from @andreaferretti's patty)
Support for types as variants
Sometimes a type acts like a variant, but isn't defined like one: you can teach the library to do it.
It uses internally
eKind to get the kind field of a variant, so you just need to override it
proc eKind*(a: A): AKind = a.stuff
match(a); (b: @e) and e == 4: # generates local variable e and checks e echo e _: echo -1
We can add
or too: does it make sense?
inspired by @andreaferretti's patty ideas
let a = @[0, 0] match(a): @[@x, @x]: # creates a local variable x only if both values are equal echo "equal" _: echo "not"
We check if all the subvalues are equal: that wasn't very easy to implement
match can be used as an expression:
let a = 2 let s = match(a): 2: "it's a 2" _: "it's not a 2"
matches macro allows to match against a single expression:
it returns a boolean value which is
true when it matches the value.
if a.matches((b: 2, c: 4)): echo 0
You can also have captures with
maybeMatches: it returns an
let c = a.maybeMatches((a: @a, b: @b)) if c.isSome: echo c.a echo c.b
- error reporting
gara means a train station in bulgarian. why a train station? I am travelling with trains these days, and I like bulgarian words.
Questions and answers
I don't like @name : it's bizarre and surprising for users
I like it, but I'd welcome ideas for a better syntax! Please, first check this list:
expr @ nameI can't see how to make it consistent with the
(field: capture)case, the same with other binary
expr @ ``name``I think this is more surprising, as it's used for 2 different puproses in quotes and in names
It's not type safe
I want to leave all the type checking to the Nim compiler. The library translates your patterns to Nim code, so the only problem should be that sometimes it might be hard to debug why something is failing: I'll try to improve that with error messages.
It is too complicated
I like to think it is relatively simple: I've tried to limit new syntax and to optimize it for variants, so e.g. in
name(..) we first check if name is enum, then type, then we assume it might be an unpacker. In the beginning I even had
~enum syntax for matching variants, but it seemed crazy.
Otherwise a lot of custom or new functionality should be doable with unpackers or with a bit upgraded unpackers, please check them out
I took inspiration from their libraries and discussions (An early version of this dsl was even a PR to @krux02 's lib).
Thanks to @mratsim for giving me the
@name idea with one of his github comments on possible nim pattern matching syntax, I initially had way more inconsistent notation in mind.
Thanks to @narimiran for giving design ideas and doc fixes!