Tracking issue for RFC 2535, 2530, 2175, "Or patterns, i.e Foo(Bar(x) | Baz(x))"

[Centril]

This is a tracking issue for the RFC "Or patterns, i.e Foo(Bar(x) | Baz(x))" (rust-lang/rfcs#2535).

This issue also tracks the changes in rust-lang/rfcs#2175 and rust-lang/rfcs#2530 since RFC 2535 subsume those.

Status:

• the feature was stabilized in Stabilize or_patterns (RFC 2535, 2530, 2175) #79278 though we are still working on implementing the edition migration (Migration for or patterns #83318)

Steps:

• Implement the RFC (cc @rust-lang/compiler -- can anyone write up mentoring instructions?)
• Polish the implementation
• Dogfood or-patterns in the compiler and standard library (done in Dogfood or_patterns in the standard library #71220, Dogfood or_patterns in rustdoc #71221, and Dogfood more or_patterns in the compiler #71231)
• Accumulate good test coverage
• Adjust documentation (see instructions on forge)
• Stabilization PR (see instructions on forge)

Unresolved questions:

• Should we allow top_pat or pat<allow_top_alt> in inferrable_param such that closures permit |Ok(x) | Err(x)| without first wrapping in parenthesis?

  We defer this decision to stabilization as it may depend on experimentation. Our current inclination is to keep the RFC as-is because the ambiguity is not just for the compiler; for humans, it is likely also ambiguous and thus harder to read.

  This also applies to functions which, although do not look as ambiguous, benefit from better consistency with closures. With respect to function arguments there's also the issue that not disambiguating with parenthesis makes it less clear whether the type ascription applies to the or-pattern as a whole or just the last alternative.

• Should the pat macro fragment specifier match top_pat in different
  Rust editions or should it match pat<no_top_alt> as currently specified? We defer such decisions to stabilization because it depends on the outcome of crater runs to see what the extent of the breakage would be.

The benefit of avoiding pat<no_top_alt> in as many places as possible would both be grammatical consistency and fewer surprises for uses. The drawbacks would be possible ambiguity or backtracking for closures and breakage for macros.

Implementation history:

• On 2019-08-18, basic parsing landed in Initial implementation of or-patterns #61708 landed which was written by @dlrobertson and reviewed by @varkor, @Centril, @petrochenkov, @matthewjasper, and @alexreg.

• On 2019-08-27, full and polished parsing landed in Fully implement or-pattern parsing #63693 which was written by @Centril and reviewed by @estebank.

• On 2019-08-29, a typo in Fully implement or-pattern parsing #63693 was fixed in or-pattern: fix typo in error message #63938 which was written by @tshepang and reviewed by @Centril.

• On 2019-09-05, unused_parens: account for or-patterns and &(mut x) #64128, written by @Centril and reviewed by @davidtwco, landed. The PR fixed issue or_patterns: unused_parens lints erroneously on _a @ (0 | 1) #64106 where the compiler would spuriously emit unused_parens warnings on:

  • ref? mut? x @ (p_0 | ... | p_n)
  • box (p_0 | ... | p_n)
  • & mut? (p_0 | ... | p_n)
  • |(p_0 | ... | p_n)| $expr
  • fn foo((p_0 | ... | p_n): $type)

• On 2019-09-06, or-patterns: Uniformly use PatKind::Or in AST & Fix/Cleanup resolve #64111, written by @Centril and reviewed by @petrochenkov, landed. The PR fixed the late-resolution behavior of or-patterns in nested positions including the already-bound check and binding-consistency check. Moreover, the AST now uniformly uses ast::PatKind::Or and has no special means of representing or-patterns at the top level.

• On 2019-09-25, or-patterns: Push PatKind/PatternKind::Or at top level to HIR & HAIR #64508, written by @Centril and reviewed by @matthewjasper, @varkor, and @nikomatsakis, landed. The PR adjusted the HIR and HAIR to consistently use or-patterns at the top & nested levels. Moreover, liveness, typeck, and dead_code analyses were adjusted also. Notably, The PR did however not adjust exhaustiveness checking. Tangentially, check_match: refactor + improve non-exhaustive diagnostics for default binding modes #64271, landed 2019-09-12, written by @Centril and reviewed by @estebank, adjusted check_match diagnostics logic to be better prepared for or-patterns.

• On 2019-09-29, syntax: recover trailing | in or-patterns #64887, written by @Centril and reviewed by @estebank, landed. The PR improved parser recovery for trailing | in pattern contexts.

• On 2019-10-27, Clarify pattern-matching usefulness algorithm #65874, written by @Nadrieril and reviewed by @varkor, @arielb1, @nnethercote, and @Centril, landed. The PR refactored the usefulness/exhaustiveness algorithm in match checking. This laid the foundation upon which exhaustiveness checking for or-patterns was later initially implemented in Initial implementation of or-pattern usefulness checking #66612.

• On 2019-11-23, resolve: more declarative fresh_binding #66639, written by @Centril and reviewed by @petrochenkov, landed. In this follow-up to or-patterns: Uniformly use PatKind::Or in AST & Fix/Cleanup resolve #64111, the resolve logic for adding fresh bindings was simplified and re-written in a more declarative fashion.

• On 2019-12-01, Initial implementation of or-pattern usefulness checking #66612, written by @Nadrieril and reviewed by @varkor, @Centril, and @matthewjasper, landed. In this follow-up to Clarify pattern-matching usefulness algorithm #65874, an initial implementation of exhaustiveness / usefulness checking for or-patterns was implemented.

• On 2019-12-03, Remove hack for top-level or-patterns in match checking #66967, written by @Nadrieril and reviewed by @varkor and @Centril, landed. In this follow-up to Initial implementation of or-pattern usefulness checking #66612, the top-level hack for or-patterns in exhaustiveness checking was removed, making or-patterns truly first-class in match checking.

• On 2019-12-21, is_binding_pat: use explicit match & include or-pats in grammar #67428, written by @Centril and reviewed by @matthewjasper, landed. This PR adjusted regionck's resolve_local::is_binding_pat such that the P& grammar includes or-patterns.

• On 2019-12-22, Cleanup lower_pattern_unadjusted & Improve slice pat typeck #67439, written by @Centril and reviewed by @matthewjasper, landed. Among other things, this PR simplified HAIR lowering of or-patterns a smidgen.

• On 2019-12-26, Prepare for lowering or-patterns #67592, written by @matthewjasper and reviewed by @Centril, landed. This PR did some preparatory cleanups in MIR lowering of match expressions before the MIR level support for or-patterns is added. Moreover, the PR gated or-patterns in const contexts under const_if_match.

• On 2020-02-04, Implement MIR lowering for or-patterns #67668, written by @matthewjasper and reviewed by @pnkfelix, @Centril, @nagisa, @varkor, and @eddyb, landed. The PR finally added the support for or-patterns in MIR building (dynamic semantics, borrow checking, ...). Now, nested or-patterns can actually be used on nightly with #![feature(or_patterns)].

• On 2020-02-06, or_patterns: add regression test for #68785 #68842, written by @Centril and reviewed by @estebank landed. The PR added a regression test for an issue fixed by Implement MIR lowering for or-patterns #67668.

• On 2020-02-15, typeck: clarify def_bm adjustments & add tests for or-patterns #68856, written by @Centril and reviewed by @matthewjasper landed. The PR polished the type checking of patterns with respect to default binding modes. In relation to or-patterns, the PR declared that or-patterns are pass-through (AdjustMode::Pass) in terms of default binding modes. This was already the case in the implementation (and already stabilized for top level or-patterns) but the PR removed the FIXME that left the question open.

• On 2020-02-28, 2020-03-08, and 2020-03-08, PRs typeck: use Pattern obligation cause more for better diagnostics #69452, check_binding_alt_eq_ty: improve precision wrt. if let #69599, and resolve, inconsistent binding mode: tweak wording #69687 landed. These were written by @Centril and were reviewed by @estebank, @davidtwco, and @estebank respectively. All PRs tweaked and improved diagnostics wrt. or-patterns.

• On 2020-03-08, test(pattern): add tests for combinations of pattern features #69690, written by @thekuom and reviewed by @Centril, landed. The relevant part of the PR added tests for the dynamic semantics of or-patterns combined with x @ y patterns, box patterns, and slice patterns.

• On 2020-03-10, test(patterns): add patterns feature tests to borrowck test suite #69817, written by @thekuom and reviewed by @Centril, landed. The PR added borrow checker tests in combination with other pattern features.

• On 2020-03-11, Exhaustiveness checking, Matrix::push: recursively expand or-patterns #69891, written by @Centril and reviewed by @varkor and @Nadrieril, landed. The PR fixed a bug (ICE "Or-pattern should have been expanded earlier on" #69875) in exhaustiveness checking where the patterns 0 | (1 | 2) and x @ 0 | x @ (1 | 2) would result in an ICE.

• On 2020-03-27, Fix incorrect pattern warning "unreachable pattern" #70413, written by @AminArria and reviewed by @varkor, @Nadrieril, and @Centril, landed. The PR fixed Incorrect "unreachable pattern" warning. #70372, a false positive in the linting behavior of unreachable_patterns when combining or-patterns, bindings, and guards.

• On 2020-04-13, Fix warning for unused variables in or pattern (issue #67691) #67766, written by @sapir and reviewed by @matthewjasper, landed. The PR fixed Incorrect unused_variables diagnostic for or-ed patterns #67691, a bug in the unused_variables lint pertaining to or-patterns.

[dlrobertson]

@alexreg thanks for the ping. Haven't really thought about it too much. I've mostly been experimenting with the code, but at this point I am not keen on changing more than the pattern matching code for the following reasons:

• I don't see much of a benefit in allowing |Ok(x) | Err(x)|
• | feels very ambiguous here. When we hit a | when parsing a closure, is it a or-pattern
  or the end of the closure argument patterns? We would have to parse past the end to find out.

That being said, I'm still new, so I might be missing something.

[Centril]

@dlrobertson Thanks for working on this. The more important part to test with crater is whether top_pat can be used for pat macro fragments or if it has regressions so it would be good to start with top_pat and maybe switch to pat<no_top_alt> based on the data.

I think it's also worth considering fn foo(Ok(x) | Err(x): Result<A, B>) { .. } without parens since that doesn't look ambiguous like with closures (the part about type ascription is also irrelevant since both p and q must have the same type in p | q so it shouldn't matter what the ascription applies to). But we can leave that for later.

[mark-i-m]

The 2015/18 edition behavior has merged in #80100.

Does it make sense to start an FCP for stabilization?

[mark-i-m]

Happy New Year, all! 🎉

With the merging of #80459, the pat2018/pat2021 behavior that @joshtriplett described from the lang-team consensus is implemented behind feature gate edition_macro_pats.

If everything looks reasonable, I think we can stabilize or_patterns in rust 1.51. #79278 is up to date and ready for an FCP.

[joshtriplett]

@petrochenkov Filed #81415 to check for lang-team consensus.

[joshtriplett]

@petrochenkov It looks like we have consensus to make that change, so please feel free to simplify that bit of the grammar by allowing leading | everywhere we allow or patterns.

[mark-i-m]

I think we can make this change independently of stabilizing or-patterns because macros in 2015/18 can't see the change yet anyway, correct?

[CAD97]

The head comment should probably be updated to reflect the stableization of the feature.