RFC: Add a matches!(expression, pattern) macro.

[SimonSapin]

Rendered view: https://github.com/SimonSapin/rfcs/blob/matches-macro/active/0000-matches-macro.md

Please note: This is different from the if let proposal. I believe the two proposals are complementary rather than competing.

[SimonSapin]

This was first proposed as rust-lang/rust#14685 and discussed by the team in the 2014-07-08 weekly meeting. The main concern there as far as I can tell was about adding things to the prelude. See the Alternatives part of this RFC for more discussion on this.

[glaebhoerl]

This is the is operator that was discussed at the if let proposal.

The most reasonable version of it IMHO is that is is a keyword, and is an infix binary operator, where EXPRESSION is PATTERN is an expression of type bool and does basically the same thing as matches!(EXPRESSION, PATTERN), and doesn't allow binding names.

(This is intended as an answer to the second question, without implying any opinion about the first.)

[lilyball]

It's worth noting that the benefit of matches!() over is is that matches!() can very easily allow for alternative patterns, as is being suggested here. However is cannot support alternative patterns without either being confusing (because | is a valid operator that one would expect to operate on the bool result of the is operator) or requiring additional syntax to enclose the set of patterns.

While I appreciate the syntactic simplicity of is, this suggests that matches!() may be the better approach (what with being implementable as a macro_rules! macro and not requiring the language grammar be extended in any way).

[netvl]

Looks like an extra line.

[netvl]

+1 looks great! This is one of these small things which can make your life a lot nicer.

[lilyball]

👍 I agree that this is complementary to if let, and I think it's potentially useful enough to justify placing in the prelude.

[Valloric]

This is both very useful and complementary to if let. There are several places in my codebase where I'd like to use this.

[huonw]

NB. this is a macro_rules! macro, so can easily be copy-pasted into codebases that wish to use it right now, and could even be provided as a Cargo plugin repository (possibly permanently, possibly temporarily, depending on the outcome of this RFC).

[esbullington]

This would be a very welcome addition. One comment: until I saw the macro itself, I was expecting matches! to produce something like an array of matches, instead of a boolean. To be explicit, I was interpreting matches! as a plural noun instead of a third-person verb.

RFC author proposes is_match! as a possible alternative syntax, and I believe this would remove the ambiguity I experienced initially. But either way, including it in prelude would be great.

[SimonSapin]

@huonw What’s a Cargo plugin repository? It sounds related to the second alternative in the RFC.

@esbullington Yes, matches with an S is intended as a third-person verb, not a plural noun.

[huonw]

@SimonSapin something like https://github.com/BurntSushi/quickcheck/blob/master/quickcheck_macros/Cargo.toml , loaded like https://github.com/BurntSushi/quickcheck/blob/master/examples/attribute.rs and still usable as a normal dependency https://github.com/BurntSushi/quickcheck#installation

[asb]

I really like this proposal, and prefer the is_match! suggested alternative name.

[glaebhoerl]

One consideration with respect to the question of whether a matches! macro, or a built-in is operator, would be preferable:

Having EXPR is PAT would make the various methods we currently provide such as is_some(), is_none(), is_ok(), is_err(), and so on totally redundant, and we could simply remove them.

Would we also be ready to remove them in favor of telling people to use matches!()?

[netvl]

if some_expression.is_some() { ... }

versus

if some_expression is Some(_) { ... }

versus

if matches!(some_expression, Some(_)) { ... }

Personally I think that the last variant is totally ugly. is operator looks nice, though.

There is ambiguity problem with is, though.

enum X {
    A { x: int }
}

if some_expression is A { .. } { ... }

[glaebhoerl]

@netvl I assume the same 'fix' could be applied as in some other points in the grammar with similar potential ambiguities, where struct literals (edit: or structural enum variants I guess) are disallowed except if wrapped in parentheses (IIRC). Perhaps someone more familiar with this could clarify.

[netvl]

@glaebhoerl, yes, that would be quite natural. Just wanted to point this out.

[lilyball]

I don't particularly like is_match!(). I think my preference would actually be for the simpler match!(). We don't allow keywords to be used when defining macro_rules! macros, but a syntax extension doesn't hit that issue, and I'm not sure if we have any such restriction on invoking a macro named after a keyword (I would hope not, as the trailing exclamation mark is typically considered part of the name). And if not match!(), I prefer matches!().

As for macro vs is, I like the syntactic simplicity of is, but there's no obvious way to allow for alternative patterns, and that seemed to be one of the desired features of matches!().

Regarding is_some() etc, I think it's reasonable for commonly-used generic enums like Option and Result to retain their existing methods for testing their variants. But lesser-used enums could then avoid having to define such functions if callers can be expected to have matches!() available to them.

[liigo]

How about match_single!?
Or even new syntax if exp match pat {}?
I personally like the later

[lilyball]

@liigo The latter has no benefits over is. It still doesn't allow for alternates.

[glaebhoerl]

@kballard I'm not deeply familiar with the grammer, but couldn't you just allow enclosing the RHS of is (the pattern) in parentheses to allow for using alternates?

[lilyball]

@glaebhoerl You could certainly create a rule like that, but it just looks weird to me. Maybe it's not that bad, I don't know, but it's hard to argue that it's good when we could get the same functionality through a macro.

[lilyball]

Basically, while I like the simplicity of is, and there are ways to come up with syntax to allow for pattern alternates, there's just not enough of a clear usability benefit over the macro approach to justify changing the grammar of the language.

[glaebhoerl]

Yes, that was what I was thinking at first as well; while the possibility that is would let us get rid of all the is_* methods made me think again. If it's just "built-in is operator versus library-defined matches! macro", then yeah, why not the macro, but if it's "built-in is operator versus library-defined matches! macro plus having to provide is_* methods", then that's not so clear any more, because now the operator has concrete benefits alongside the nicer syntax. (Again, presuming you can just do if my_foo is (Some(true) | None) for disjunction, which doesn't look that bad to me.)

[treeman]

Sounds good to me. I prefer matches! and match! over is_match!.

Visually this looks good to me:

if foo is Some(true) | None { ... }

but this might be confused with bit-wise or. If that's not possible I prefer the macro approach over is.

[blaenk]

I think this is very useful. +1

[alexcrichton]

This was discussed in today's weekly meeting, and the conclusion is that we would like to not merge this for now. We are primarily worried about adding such a feature to the prelude. We all very much desire a macro import/export system, and this RFC would likely be a shoo-in if we were to have one (so long as it were not in the prelude).

With that in mind, the decision was made to postpone this for now until such a system exists. Thanks for the RFC, however, @SimonSapin!

[mdinger]

Visually, using an or instead of | to avoid conflict with bitwise operations looks nice. I suppose that would require | in match to change as well for consistency.
if some_expr is '+' or '-' { ... }

I saw that the benefit/change ratio might not be high (vs matches!) enough for this but I thought it might be useful to the discussion.

[SimonSapin]

I’ve published this macro on crates.io:

https://crates.io/crates/matches
https://github.com/SimonSapin/rust-std-candidates

[SimonSapin]

Nightly broke this, and it’s apparently not possible to fix without changing the usage syntax :( rust-lang/rust#20563 (comment)

[Laaas]

Since you can now use macros, perhaps this should be reopened?

[SimonSapin]

The discussion in rust-lang/rust#35896 appears to be ongoing and not quite settled yet.

Also, this proposal is very old and I have limited bandwidth to champion it these days. Consider making a new RFC / PR. (Feel free to copy some or all of this one.)