Given that @tclem and I have found the matcher API frustrating, I've
taken a stab at improving its ergonomics, and I've found some success
in separating composition of matchers from predicate-based narrowing
thereof.
The biggest change here is the elimination of the old `match`
combinator, which proved to be clumsy in that it complected narrowing
and composition. Top-down matching combinators are now written with
the `need` combinator and the `>>>` combinator, which is more readable
and more versatile. Here's a matcher that accepts functions with
Python docstrings:
```haskell
docstringMatcher :: ( Decl.Function :< fs
, [] :< fs
, Lit.TextElement :< fs
, term ~ Term (Sum fs) ann
) => Matcher term term
docstringMatcher = target <*
(need Decl.functionBody
>>> narrow @[]
>>> mhead
>>> narrow @Lit.TextElement
>>> ensure Lit.isTripleQuoted))
```
Pretty readable, right? Each step of the tree regular expression -
choosing function bodies, ensuring said bodies are lists, examining
the first element, and choosing only TextElements containing
triple-quoted strings - is made implicit. The old way would have
looked something like this:
```haskell
docstringMatcher = target <* match Decl.functionBody
$ narrow
$ matchM listToMaybe
$ target <* ensure Lit.isTripleQuoted
```
which is a good deal more disorganized and less flexible
in the quite-common case of applying functions during a
matching pass. Separating the act of composition from
function application is a big win here.
Further comments are inline.
@tclem and I found ourselves wanting an arrow-like combinator that
promotes a given function to a Matcher. While I think an Arrow
instance is going a little overboard, there's no harm in adding a
'purely' function, the naming of which is commensurate with the
rewriting DSL.
This also renames the module, since there's not anything really
abstract about matching (indeed, it is quite concrete).
This patch adds the `Matcher` monad, which is capable of filtering any
recursive data structure, bottom-up, yielding a list of (or an
optional) result. These functions are probably going to be used over
`Term` values, so API is provided to wrap common projection functions.
The API was more or less copied directly from that of Clang's AST
matching facilities.
There are a lot of things we can do in the future:
* Binding results yielded in matchers to associated names, for future
transformation stages to look up and modify.
* Actual transformation stages.
* Optimizations. This is not very fast.
A million thanks to @robrix, whose sage advice managed to turn my
kooky idea for an API into something really special and exciting.
