Unify while/while let and if/if let expressions.

This updates the `if` and `while` expressions so that they each are
presented as a single expression kind with multiple condition operators
instead of being logically separated from their `let` counterparts.

This also includes various fixes and additions.

src/SUMMARY.md

@@ -62,7 +62,7 @@
         - [Closure expressions](expressions/closure-expr.md)
         - [Loop expressions](expressions/loop-expr.md)
         - [Range expressions](expressions/range-expr.md)
-        - [If and if let expressions](expressions/if-expr.md)
+        - [If expressions](expressions/if-expr.md)
         - [Match expressions](expressions/match-expr.md)
         - [Return expressions](expressions/return-expr.md)
         - [Await expressions](expressions/await-expr.md)

src/attributes/type_system.md

@@ -133,7 +133,6 @@ Non-exhaustive types are always considered inhabited in downstream crates.
 [_StructExpression_]: ../expressions/struct-expr.md
 [_StructPattern_]: ../patterns.md#struct-patterns
 [_TupleStructPattern_]: ../patterns.md#tuple-struct-patterns
-[`if let`]: ../expressions/if-expr.md#if-let-expressions
 [`match`]: ../expressions/match-expr.md
 [attributes]: ../attributes.md
 [enum]: ../items/enumerations.md

src/const_eval.md

@@ -45,8 +45,8 @@ to be run.
   * pointer to address casts and
   * function pointer to address casts.
 * Calls of [const functions] and const methods.
-* [loop], [while] and [`while let`] expressions.
-* [if], [`if let`] and [match] expressions.
+* [loop] and [while] expressions.
+* [if] and [match] expressions.
 
 ## Const context
 
@@ -121,7 +121,6 @@ Conversely, the following are possible in a const function, but not in a const c
 [grouped]:              expressions/grouped-expr.md
 [interior mutability]:  interior-mutability.md
 [if]:                   expressions/if-expr.md#if-expressions
-[`if let`]:             expressions/if-expr.md#if-let-expressions
 [lazy boolean]:         expressions/operator-expr.md#lazy-boolean-operators
 [let statements]:       statements.md#let-statements
 [literals]:             expressions/literal-expr.md
@@ -138,4 +137,3 @@ Conversely, the following are possible in a const function, but not in a const c
 [struct]:               expressions/struct-expr.md
 [tuple expressions]:    expressions/tuple-expr.md
 [while]:                expressions/loop-expr.md#predicate-loops
-[`while let`]:          expressions/loop-expr.md#predicate-pattern-loops

src/destructors.md

@@ -388,12 +388,12 @@ variable or field from being dropped automatically.
 [tuple expression]: expressions/tuple-expr.md#tuple-expressions
 
 [`for`]: expressions/loop-expr.md#iterator-loops
-[`if let`]: expressions/if-expr.md#if-let-expressions
+[`if let`]: expressions/if-expr.md#if-let-patterns
 [`if`]: expressions/if-expr.md#if-expressions
 [`let` statement]: statements.md#let-statements
 [`loop`]: expressions/loop-expr.md#infinite-loops
 [`match`]: expressions/match-expr.md
-[`while let`]: expressions/loop-expr.md#predicate-pattern-loops
+[`while let`]: expressions/loop-expr.md#while-let-patterns
 [`while`]: expressions/loop-expr.md#predicate-loops
 
 [`<T as std::ops::Drop>::drop`]: ../std/ops/trait.Drop.html#tymethod.drop

src/expressions.md

@@ -38,7 +38,6 @@
 >       | [_UnsafeBlockExpression_]\
 >       | [_LoopExpression_]\
 >       | [_IfExpression_]\
->       | [_IfLetExpression_]\
 >       | [_MatchExpression_]\
 >    )
 
@@ -295,13 +294,13 @@ They are never allowed before:
 [call expressions]:     expressions/call-expr.md
 [field]:                expressions/field-expr.md
 [functional update]:    expressions/struct-expr.md#functional-update-syntax
-[`if let`]:             expressions/if-expr.md#if-let-expressions
+[`if let`]:             expressions/if-expr.md#if-let-patterns
 [match]:                expressions/match-expr.md
 [method-call]:          expressions/method-call-expr.md
 [paths]:                expressions/path-expr.md
 [struct]:               expressions/struct-expr.md
 [tuple expressions]:    expressions/tuple-expr.md
-[`while let`]:          expressions/loop-expr.md#predicate-pattern-loops
+[`while let`]:          expressions/loop-expr.md#while-let-patterns
 
 [array expressions]:    expressions/array-expr.md
 [array indexing]:       expressions/array-expr.md#array-and-slice-indexing-expressions
@@ -348,7 +347,6 @@ They are never allowed before:
 [_FieldExpression_]:              expressions/field-expr.md
 [_GroupedExpression_]:            expressions/grouped-expr.md
 [_IfExpression_]:                 expressions/if-expr.md#if-expressions
-[_IfLetExpression_]:              expressions/if-expr.md#if-let-expressions
 [_IndexExpression_]:              expressions/array-expr.md#array-and-slice-indexing-expressions
 [_LazyBooleanExpression_]:        expressions/operator-expr.md#lazy-boolean-operators
 [_LiteralExpression_]:            expressions/literal-expr.md

src/expressions/block-expr.md

@@ -145,7 +145,7 @@ let a = unsafe { an_unsafe_fn() };
 [Inner attributes] are allowed directly after the opening brace of a block expression in the following situations:
 
 * [Function] and [method] bodies.
-* Loop bodies ([`loop`], [`while`], [`while let`], and [`for`]).
+* Loop bodies ([`loop`], [`while`], and [`for`]).
 * Block expressions used as a [statement].
 * Block expressions as elements of [array expressions], [tuple expressions],
   [call expressions], and tuple-style [struct] expressions.
@@ -172,7 +172,6 @@ fn is_unix_platform() -> bool {
 [`loop`]: loop-expr.md#infinite-loops
 [`std::ops::Fn`]: ../../std/ops/trait.Fn.html
 [`std::future::Future`]: ../../std/future/trait.Future.html
-[`while let`]: loop-expr.md#predicate-pattern-loops
 [`while`]: loop-expr.md#predicate-loops
 [array expressions]: array-expr.md
 [call expressions]: call-expr.md

src/expressions/if-expr.md

@@ -2,29 +2,30 @@
 
 ## Syntax
 
-The same syntax is used by `if`, `if let` and chains of expressions.
-
 > **<sup>Syntax</sup>**\
 > _IfExpression_ :\
-> &nbsp;&nbsp; `if` _IfLetList_ [_BlockExpression_]\
-> &nbsp;&nbsp; ( `else` _IfLetList_ [_BlockExpression_] )<sup>\?</sup>
+> &nbsp;&nbsp; `if` _IfConditions_ [_BlockExpression_]\
+> &nbsp;&nbsp; (`else` ( [_BlockExpression_] | _IfExpression_ ) )<sup>\?</sup>
 >
-> _IfLet_ :\
->  &nbsp;&nbsp; [_Expression_]<sub>_except struct expression_</sub>
-> | `let` [_Pattern_] `=` [_Expression_]<sub>_except struct expression_</sub>
+> _IfConditions_ :\
+> &nbsp;&nbsp; _IfCondition_ ( && _IfCondition_ )*
 >
-> _IfLetList_ :\
-> &nbsp;&nbsp; _IfLet_ ( && _IfLet_ )*
-
-## `if`
+> _IfCondition_ :\
+> &nbsp;&nbsp; &nbsp;&nbsp; [_Expression_]<sub>_except struct expression_</sub>\
+> &nbsp;&nbsp; | `let` [_Pattern_] `=` [_Scrutinee_]
 
 An `if` expression is a conditional branch in program control.
-The syntax of an `if` expression is a condition operand, followed by a consequent block, any number of `else if` conditions and blocks, and an optional trailing `else` block.
-The condition operands must have the [boolean type].
-If a condition operand evaluates to `true`, the consequent block is executed and any subsequent `else if` or `else` block is skipped.
-If a condition operand evaluates to `false`, the consequent block is skipped and any subsequent `else if` condition is evaluated.
+The syntax of an `if` expression is a sequence of one or more condition operands separated by `&&`,
+followed by a consequent block, any number of `else if` conditions and blocks, and an optional trailing `else` block.
+
+Condition operands must be either an [_Expression_] with a [boolean type] or a conditional `let` match.
+If all of the condition operands evaluate to `true` and all of the `let` patterns successfully match their [scrutinee]s,
+the consequent block is executed and any subsequent `else if` or `else` block is skipped.
+If any condition operand evaluates to `false` or any `let` pattern does not match its scrutinee,
+the consequent block is skipped and any subsequent `else if` condition is evaluated.
 If all `if` and `else if` conditions evaluate to `false` then any `else` block is executed.
-An if expression evaluates to the same value as the executed block, or `()` if no block is evaluated.
+
+An `if` expression evaluates to the same value as the executed block, or `()` if no block is evaluated.
 An `if` expression must have the same type in all situations.
 
 ```rust
@@ -37,6 +38,7 @@ if x == 4 {
     println!("x is something else");
 }
 
+// `if` can be used as an expression.
 let y = if 12 * 15 > 150 {
     "Bigger"
 } else {
@@ -45,25 +47,23 @@ let y = if 12 * 15 > 150 {
 assert_eq!(y, "Bigger");
 ```
 
-## `if let`
+## `if let` patterns
 
-An `if let` expression is semantically similar to an `if` expression but in place of a condition operand it expects the keyword `let` followed by a pattern, an `=` and a [scrutinee] operand.
-If the value of the scrutinee matches the pattern, the corresponding block will execute.
-Otherwise, flow proceeds to the following `else` block if it exists.
-Like `if` expressions, `if let` expressions have a value determined by the block that is evaluated.
+`let` patterns in an `if` condition allow binding new variables into scope when the pattern matches successfully.
+The following examples illustrate bindings using `let` patterns:
 
 ```rust
 let dish = ("Ham", "Eggs");
 
-// this body will be skipped because the pattern is refuted
+// This body will be skipped because the pattern is refuted.
 if let ("Bacon", b) = dish {
     println!("Bacon is served with {}", b);
 } else {
     // This block is evaluated instead.
     println!("No bacon will be served");
 }
 
-// this body will execute
+// This body will execute.
 if let ("Ham", b) = dish {
     println!("Ham is served with {}", b);
 }
@@ -73,23 +73,8 @@ if let _ = 5 {
 }
 ```
 
-`if` and `if let` expressions can be intermixed:
-
-```rust
-let x = Some(3);
-let a = if let Some(1) = x {
-    1
-} else if x == Some(2) {
-    2
-} else if let Some(y) = x {
-    y
-} else {
-    -1
-};
-assert_eq!(a, 3);
-```
-
-Multiple patterns may be specified with the `|` operator. This has the same semantics as with `|` in `match` expressions:
+Multiple patterns may be specified with the `|` operator.
+This has the same semantics as with `|` in [`match` expressions]:
 
 ```rust
 enum E {
@@ -103,10 +88,13 @@ if let E::X(n) | E::Y(n) = v {
 }
 ```
 
-The expression cannot be a [lazy boolean operator expression][_LazyBooleanOperatorExpression_].
-Scrutinee expressions also cannot be a [lazy boolean operator expression][_LazyBooleanOperatorExpression_] due to ambiguity and precedence with [chains of expressions][_ChainsOfExpressions_].
+## Chains of conditions
 
-## Chains of expressions
+Multiple condition operands can be separated with `&&`.
+Similar to a `&&` [_LazyBooleanOperatorExpression_], 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.
+
+The bindings of each pattern are put into scope to be available for the next condition operand and the consequent block.
 
 The following is an example of chaining multiple expressions, mixing `let` bindings and boolean expressions, and with expressions able to reference pattern bindings from previous expressions:
 
@@ -121,9 +109,11 @@ fn single() {
         println!("Peek a boo");
     }
 }
+```
 
-The above is equivalent to the following without using expression chains:
+The above is equivalent to the following without using chains of conditions:
 
+```rust
 fn nested() {
     let outer_opt = Some(Some(1i32));
 
@@ -137,39 +127,23 @@ fn nested() {
 }
 ```
 
-In other words, chains are equivalent to nested [`if let` expressions]:
+If any condition operand is a `let` pattern, then none of the condition operands can be a `||` [lazy boolean operator expression][_LazyBooleanOperatorExpression_] due to ambiguity and precedence with the `let` scrutinee.
+If a `||` expression is needed, then parentheses can be used. For example:
 
-<!-- ignore: expansion example -->
-```rust,ignore
-if let PAT0 = EXPR0 && let PAT1 = EXPR1 {
-    /* body */
-} else {
-    /* else */
-}
+```rust
+# let foo = Some(123);
+# let condition1 = true;
+# let condition2 = false;
+// Parentheses are required here.
+if let Some(x) = foo && (condition1 || condition2) { /*...*/ }
 ```
 
-is equivalent to
-
-<!-- ignore: expansion example -->
-```rust,ignore
-if let PAT0 = EXPR0 {
-    if let PAT1 = EXPR1 {
-        /* body */
-    }
-    else {
-        /* else */
-    }
-} else {
-    /* else */
-}
-```
 
 [_BlockExpression_]: block-expr.md
-[_ChainsOfExpressions_]: #chains-of-expressions
 [_Expression_]: ../expressions.md
 [_LazyBooleanOperatorExpression_]: operator-expr.md#lazy-boolean-operators
 [_Pattern_]: ../patterns.md
 [_Scrutinee_]: match-expr.md
-[`match` expression]: match-expr.md
+[`match` expressions]: match-expr.md
 [boolean type]: ../types/boolean.md
 [scrutinee]: ../glossary.md#scrutinee