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.

[Centril]

I've closed #48215 in favor of this issue to track all related changes since rust-lang/rfcs#2535 subsumes RFC 2175.

I would suggest that #![feature(or_patterns)] should imply #![feature(if_while_or_patterns)] and then we will eventually stabilize both gates if/once we stabilize or_patterns.

[CAD97]

Minor thing that I just noticed: anonymous enums with the syntax of "tuple-but-|-instead-of-,", (A|B), is syntactically ambiguous with this feature, since we have parenthesized patterns.

[Centril]

@CAD97 example of a snippet that would show the ambiguity?

[CAD97]

I confused things between patterns and types:

match it {
    it: (A|B) => (), // it with type ascription (A|B)
    it @ (A|B) => (), // it binding to pattern (A|B)
}

So long as patterns and types aren't valid in the same position, this is ok. (I confused myself since tuples are valid patterns.)

[varkor]

I've got a branch for this that I think is close, but as I'm quite busy at the moment, I'm not sure how soon I'll finish it; if anyone else would like to take this over in the meantime, just leave a comment.

[alexreg]

@varkor Where's your branch? I'm happy to take over if you like... especially if it gets const generics to land any sooner. ;-)

[varkor]

@alexreg: it's at https://github.com/varkor/rust/tree/or-patterns. I think where I left it, there was some crash when you tried using or-patterns, but most of the boilerplate is in. Feel free to play around with it to see if you can get it working. (Though I'm not prioritising this over const generics, don't worry 😉)