specify if let guards with updated scoping rules

src/destructors.md

@@ -141,8 +141,8 @@ patterns_in_parameters(
 r[destructors.scope.bindings]
 ### Scopes of local variables
 
-r[destructors.scope.bindings.intro]
-Local variables declared in a `let` statement are associated to the scope of the block that contains the `let` statement. Local variables declared in a `match` expression are associated to the arm scope of the `match` arm that they are declared in.
+r[destructors.scope.bindings.let]
+Local variables declared in a `let` statement are associated to the scope of the block that contains the `let` statement.
 
 ```rust
 # struct PrintOnDrop(&'static str);
@@ -158,6 +158,49 @@ let declared_first = PrintOnDrop("Dropped last in outer scope");
 let declared_last = PrintOnDrop("Dropped first in outer scope");
 ```
 
+r[destructors.scope.bindings.match-arm]
+Local variables declared in a `match` expression or pattern-matching `match` guard are associated to the arm scope of the `match` arm that they are declared in.
+
+```rust
+# #![allow(irrefutable_let_patterns)]
+# struct PrintOnDrop(&'static str);
+# impl Drop for PrintOnDrop {
+#     fn drop(&mut self) {
+#         println!("drop({})", self.0);
+#     }
+# }
+match PrintOnDrop("Dropped last in the first arm's scope") {
+    // When guard evaluation succeeds, control-flow stays in the arm and
+    // values may be moved from the scrutinee into the arm's bindings,
+    // causing them to be dropped in the arm's scope.
+    x if let y = PrintOnDrop("Dropped second in the first arm's scope")
+        && let z = PrintOnDrop("Dropped first in the first arm's scope") =>
+    {
+        let declared_in_block = PrintOnDrop("Dropped in inner scope");
+        // Pattern-matching guards' bindings and temporaries are dropped in
+        // reverse order, dropping each guard condition operand's bindings
+        // before its temporaries. Lastly, variables bound by the arm's
+        // pattern are dropped.
+    }
+    _ => unreachable!(),
+}
+
+match PrintOnDrop("Dropped in the enclosing temporary scope") {
+    // When guard evaluation fails, control-flow leaves the arm scope,
+    // causing bindings and temporaries from earlier pattern-matching
+    // guard condition operands to be dropped. This occurs before evaluating
+    // the next arm's guard or body.
+    _ if let y = PrintOnDrop("Dropped in the first arm's scope")
+        && false => unreachable!(),
+    // When a guard is executed multiple times due to self-overlapping
+    // or-patterns, control-flow leaves the arm scope when the guard fails
+    // and re-enters the arm scope before executing the guard again.
+    _ | _ if let y = PrintOnDrop("Dropped in the second arm's scope twice")
+        && false => unreachable!(),
+    _ => {},
+}
+```
+
 r[destructors.scope.bindings.patterns]
 Variables in patterns are dropped in reverse order of declaration within the pattern.
 
@@ -225,8 +268,8 @@ Apart from lifetime extension, the temporary scope of an expression is the small
 * A statement.
 * The body of an [`if`], [`while`] or [`loop`] expression.
 * The `else` block of an `if` expression.
-* The non-pattern matching condition expression of an `if` or `while` expression, or a `match` guard.
-* The body expression for a match arm.
+* The non-pattern matching condition expression of an `if` or `while` expression or a non-pattern-matching `match` [guard condition operand].
+* The pattern-matching guard, if present, and body expression for a `match` arm.
 * Each operand of a [lazy boolean expression].
 * The pattern-matching condition(s) and consequent body of [`if`] ([destructors.scope.temporary.edition2024]).
 * The pattern-matching condition and loop body of [`while`].
@@ -289,8 +332,16 @@ while let x = PrintOnDrop("while let scrutinee").0 {
 // Scrutinee is dropped at the end of the function, before local variables
 // (because this is the tail expression of the function body block).
 match PrintOnDrop("Matched value in final expression") {
-    // Dropped once the condition has been evaluated
+    // Non-pattern-matching guards' temporaries are dropped once the
+    // condition has been evaluated
     _ if PrintOnDrop("guard condition").0 == "" => (),
+    // Pattern-matching guards' temporaries are dropped when leaving the
+    // arm's scope
+    _ if let "guard scrutinee" = PrintOnDrop("guard scrutinee").0 => {
+        let _ = &PrintOnDrop("lifetime-extended temporary in inner scope");
+        // `lifetime-extended temporary in inner scope` is dropped here
+    }
+    // `guard scrutinee` is dropped here
     _ => (),
 }
 ```
@@ -597,6 +648,7 @@ There is one additional case to be aware of: when a panic reaches a [non-unwindi
 [destructors]: destructors.md
 [destructuring assignment]: expr.assign.destructure
 [expression]: expressions.md
+[guard condition operand]: expressions/match-expr.md#match-guard-chains
 [identifier pattern]: patterns.md#identifier-patterns
 [initialized]: glossary.md#initialized
 [interior mutability]: interior-mutability.md

src/expressions/match-expr.md

@@ -17,7 +17,27 @@ MatchArms ->
 
 MatchArm -> OuterAttribute* Pattern MatchArmGuard?
 
-MatchArmGuard -> `if` Expression
+MatchArmGuard -> `if` MatchConditions
+
+MatchConditions ->
+     MatchGuardChain
+   | Expression
+
+MatchGuardChain -> MatchGuardCondition ( `&&` MatchGuardCondition )*
+
+MatchGuardCondition ->
+     Expression _except [ExcludedMatchConditions]_
+   | OuterAttribute* `let` Pattern `=` MatchGuardScrutinee
+
+MatchGuardScrutinee -> Expression _except [ExcludedMatchConditions]_
+
+@root ExcludedMatchConditions ->
+      LazyBooleanExpression
+    | RangeExpr
+    | RangeFromExpr
+    | RangeInclusiveExpr
+    | AssignmentExpression
+    | CompoundAssignmentExpression
 ```
 <!-- TODO: The exception above isn't accurate, see https://github.com/rust-lang/reference/issues/569 -->
 
@@ -97,11 +117,11 @@ r[expr.match.guard]
 r[expr.match.guard.intro]
 Match arms can accept _match guards_ to further refine the criteria for matching a case.
 
-r[expr.match.guard.type]
-Pattern guards appear after the pattern and consist of a `bool`-typed expression following the `if` keyword.
+r[expr.match.guard.condition]
+Pattern guards appear after the pattern following the `if` keyword and consist of an [Expression] with a [boolean type][type.bool] or a conditional `let` match.
 
 r[expr.match.guard.behavior]
-When the pattern matches successfully, the pattern guard expression is executed. If the expression evaluates to true, the pattern is successfully matched against.
+When the pattern matches successfully, the pattern guard is executed. If all of the guard condition operands evaluate to `true` and all of the `let` patterns successfully match their [scrutinee]s, the match arm is successfully matched against and the arm body is executed.
 
 r[expr.match.guard.next]
 Otherwise, the next pattern, including other matches with the `|` operator in the same arm, is tested.
@@ -137,11 +157,74 @@ r[expr.match.guard.shared-ref]
 Before evaluating the guard, a shared reference is taken to the part of the scrutinee the variable matches on. While evaluating the guard, this shared reference is then used when accessing the variable.
 
 r[expr.match.guard.value]
-Only when the guard evaluates to true is the value moved, or copied, from the scrutinee into the variable. This allows shared borrows to be used inside guards without moving out of the scrutinee in case guard fails to match.
+Only when the guard evaluates successfully is the value moved, or copied, from the scrutinee into the variable. This allows shared borrows to be used inside guards without moving out of the scrutinee in case guard fails to match.
 
 r[expr.match.guard.no-mutation]
 Moreover, by holding a shared reference while evaluating the guard, mutation inside guards is also prevented.
 
+r[expr.match.guard.let]
+Guards can use `let` patterns to conditionally match a scrutinee and to bind new variables into scope when the pattern matches successfully.
+
+> [!EXAMPLE]
+> In this example, the guard condition `let Some(first_char) = name.chars().next()` is evaluated. If the `let` pattern successfully matches (i.e. the string has at least one character), the arm's body is executed. Otherwise, pattern matching continues to the next arm.
+>
+> The `let` pattern creates a new binding (`first_char`), which can be used alongside the original pattern bindings (`name`) in the arm's body.
+> ```rust
+> # enum Command {
+> #     Run(String),
+> #     Stop,
+> # }
+> let cmd = Command::Run("example".to_string());
+>
+> match cmd {
+>     Command::Run(name) if let Some(first_char) = name.chars().next() => {
+>         // Both `name` and `first_char` are available here
+>         println!("Running: {name} (starts with '{first_char}')");
+>     }
+>     Command::Run(name) => {
+>         println!("{name} is empty");
+>     }
+>     _ => {}
+> }
+> ```
+
+r[expr.match.guard.chains]
+## Match guard chains
+
+r[expr.match.guard.chains.intro]
+Multiple guard condition operands can be separated with `&&`.
+
+> [!EXAMPLE]
+> ```rust
+> # let foo = Some([123]);
+> # let already_checked = false;
+> match foo {
+>     Some(xs) if let [single] = xs && !already_checked => { dbg!(single); }
+>     _ => {}
+> }
+> ```
+
+r[expr.match.guard.chains.order]
+Similar to a `&&` [LazyBooleanExpression], each operand is evaluated from left-to-right until an operand evaluates as `false` or a `let` match fails, in which case the subsequent operands are not evaluated.
+
+r[expr.match.guard.chains.bindings]
+The bindings of each `let` pattern are put into scope to be available for the next condition operand and the match arm body.
+
+r[expr.match.guard.chains.or]
+If any guard condition operand is a `let` pattern, then none of the condition operands can be a `||` [lazy boolean operator expression][expr.bool-logic] due to ambiguity and precedence with the `let` scrutinee.
+
+> [!EXAMPLE]
+> If a `||` expression is needed, then parentheses can be used. For example:
+>
+> ```rust
+> # let foo = Some(123);
+> match foo {
+>     // Parentheses are required here.
+>     Some(x) if (x < -100 || x > 20) => {}
+>     _ => {}
+> }
+> ```
+
 r[expr.match.attributes]
 ## Attributes on match arms
 

src/names/scopes.md

@@ -48,6 +48,8 @@ r[names.scopes.pattern-bindings.let-chains]
 * [`if let`] and [`while let`] bindings are valid in the following conditions as well as the consequent block.
 r[names.scopes.pattern-bindings.match-arm]
 * [`match` arms] bindings are within the [match guard] and the match arm expression.
+r[names.scopes.pattern-bindings.match-guard-let]
+* [`match` guard `let`] bindings are valid in the following guard conditions and the match arm expression.
 
 r[names.scopes.pattern-bindings.items]
 Local variable scopes do not extend into item declarations.
@@ -331,6 +333,7 @@ impl ImplExample {
 [`macro_use` prelude]: preludes.md#macro_use-prelude
 [`macro_use`]: ../macros-by-example.md#the-macro_use-attribute
 [`match` arms]: ../expressions/match-expr.md
+[`match` guard `let`]: expr.match.guard.let
 [`Self`]: ../paths.md#self-1
 [Associated consts]: ../items/associated-items.md#associated-constants
 [associated items]: ../items/associated-items.md