align match? fns

[dchelimsky]

There are currently 3 versions of match?:

• matcher-combinators.core/match?
• matcher-combinators.standalone/match?
• matcher-combinators.test/match? (clojure.test assert-expr - not really a function)

They all have different semantics, which is cause for much confusion.

This PR aligns them as follows:

• all three have an arity-2 version e.g. (match? expected actual), where expected could be a value or a matcher
• the core and standalone functions each have an arity-1 version e.g. (match? match-result)
• all arities of all 3 versions return a boolean

What changed?

• standalone.match? with one arg expects a match-result and returns a boolean
  • this is a breaking change, but using the 1-arity version of this is an edge case and should not have a wide-reaching impact
• core.match? now supports 1 argument
  • previously it only supported 2
• the fdefs for both versions are the same, and have moved to a new specs namespace so they are only loaded when needed (in tests)

[dchelimsky]

NOTE: since this is a breaking change, we should hold off on releasing 2.0.0 until this is vetted and merged.

[gabrielgiussi]

Which is the use case for the 1-arity version?

[dchelimsky]

Which is the use case for the 1-arity version?

It separates the details exposed by the match function, used in e.g. the match? assert-expr, from the "matchiness" (boolean result) indicated by those details.

https://github.com/nubank/matcher-combinators/blob/7339a68f8a9e9c0afe80fa86f904426c0fa38a97/src/clj/matcher_combinators/clj_test.clj#L51-L52

We only use the result# in this case when match? returns false in order to report out to the user, but this code doesn't have to know the semantics of the result of match.

[dchelimsky]

Suggestion from @rafaelzlisboa in standup today: perhaps the 2 arities of match? should be different functions. Moving this to Draft state while we explore this further.

[dchelimsky]

We went with #128 instead.