🍵 Matcha - first-class match specifications for Elixir

christhekeele · March 24, 2023, 7:02am

DEVLOG.md 2023-03-24

It’s been a while! I thought I’d provide few updates, and talk about the roadmap a little.

I’ve not yet cut out v0.1.8, as I want to finish up two bugfixes first. However:

Mirror OTP 25’s support for binary_part/2, binary_part/3, byte_size/1 in match specs
Got the OTP team to support ceil/2, floor/3, is_boolean/1, is_function/2, tuple_size/1 in match specs, landing in the upcoming OTP 26 release ()
- already added support to Matcha for when OTP 26 is released
- this should mean that Matcha supports all guard-safe functions in match specs written in both Elixir and Erlang!
  - except erlang’s is_record/2, which Elixir has a work-around for in OTP 26, and is a longstanding issue in erlang

Started livebook guides and cheatsheets for adopting Matcha
- They are intended to be a “converting my project’s match specs to use Matcha” tutorial
- They’re still in progress as I finalize the “high level” APIs, but early feedback is welcome
Added a CONTRIBUTORS.md
- Thank you for your attention, time, and feedback helping me get Matcha to where it is,
- future contributors will be attributed similarly in this file
Many more functions documented

Prevent Matcha from emitting warnings when not using :mnesia
Fix remaining issues compiling Kernel.and/2 and Kernel.or/2 when used in match spec bodies
Fix remaining issues compiling Kernel.is_exception/{1,2} and Kernel.is_struct/{1,2} when used in match spec bodies
This is… pretty much all of the known issues with the compiler resolved, except for the aforementioned remaining two I’m blocking a release on.
- Matcha has a 1:2 code/test LoC ratio, and this is mostly centered around discovering edge cases in the compiler today, so I’m feeling pretty darn good about it!

Many more codepaths tested (mostly around edge cases in the compiler to discover resolved bugs)

There are those two known edge-cases with spec compilation I intend to address before releasing the above progress.

This release is when I’m declaring Matcha “ready to use”!
The main obstacle is fleshing out documentation. I’ve spent more time on guides than module/fn docs, and it shows.
- one of Matcha’s most ambitious goals is explaining how/when to use match specs in an approachable fashion, so I’m happy to dwell on this.
I’ve also spent more time on the Elixir → ms compiler than higher-level APIs to use specs built by the compiler, so tests/documentation need to be fleshed out as these settle.

I intend to rework Matcha’s tracing APIs to support even more use-cases in this release
I will end up ditching the :recon dependency for a custom implementation, for a few reasons
- I’d like to keep Matcha dependency-less
- :recon only supports tracing function calls safely, I’d like to support tracing send/receive events as well
- I intend to apply :recon’s safety heuristics to these things other than function calls, so will ape a lot of the great work done there

This is still the release where any breaking change will imply a major version bump
- I only anticipate hesitating to publish this post v0.3.0 if the high-level trace and table APIs prove to need a little more work post-release
I want full documentation/test/typespec coverage before I make this release

That’s the hot tea on Matcha, thanks for reading!