Add identifier syntax to loop-expr and match-expr

Author: chorman0773

src/expressions/loop-expr.md

@@ -1,5 +1,8 @@
 # Loops and other breakable expressions
 
+r[expr.block]
+
+r[expr.loop.syntax]
 > **<sup>Syntax</sup>**\
 > _LoopExpression_ :\
 > &nbsp;&nbsp; [_LoopLabel_]<sup>?</sup> (\
@@ -17,6 +20,7 @@
 [_IteratorLoopExpression_]: #iterator-loops
 [_LabelBlockExpression_]: #labelled-block-expressions
 
+r[expr.loop.intro]
 Rust supports five loop expressions:
 
 *   A [`loop` expression](#infinite-loops) denotes an infinite loop.
@@ -25,29 +29,47 @@ Rust supports five loop expressions:
 *   A [`for` expression](#iterator-loops) extracts values from an iterator, looping until the iterator is empty.
 *   A [labelled block expression](#labelled-block-expressions) runs a loop exactly once, but allows exiting the loop early with `break`.
 
+r[expr.loop.break-label]
 All five types of loop support [`break` expressions](#break-expressions), and [labels](#loop-labels).
+
+r[expr.loop.continue]
 All except labelled block expressions support [`continue` expressions](#continue-expressions).
+
+r[expr.loop.explicit-result]
 Only `loop` and labelled block expressions support [evaluation to non-trivial values](#break-and-loop-values).
 
 ## Infinite loops
 
+r[expr.loop.infinite]
+
+r[expr.loop.infinite.syntax]
 > **<sup>Syntax</sup>**\
 > _InfiniteLoopExpression_ :\
 > &nbsp;&nbsp; `loop` [_BlockExpression_]
 
+r[expr.loop.infinite.intro]
 A `loop` expression repeats execution of its body continuously:
 `loop { println!("I live."); }`.
 
+r[expr.loop.infinite.diverging]
 A `loop` expression without an associated `break` expression is diverging and has type [`!`](../types/never.md).
+
+r[expr.loop.infinite.break]
 A `loop` expression containing associated [`break` expression(s)](#break-expressions) may terminate, and must have type compatible with the value of the `break` expression(s).
 
 ## Predicate loops
 
+r[expr.loop.while]
+
+r[expr.loop.while.syntax]
 > **<sup>Syntax</sup>**\
 > _PredicateLoopExpression_ :\
 > &nbsp;&nbsp; `while` [_Expression_]<sub>_except struct expression_</sub> [_BlockExpression_]
 
+r[expr.loop.while.intro]
 A `while` loop begins by evaluating the [boolean] loop conditional operand.
+
+r[expr.loop.while.condition]
 If the loop conditional operand evaluates to `true`, the loop body block executes, then control returns to the loop conditional operand.
 If the loop conditional expression evaluates to `false`, the `while` expression completes.
 
@@ -64,13 +86,19 @@ while i < 10 {
 
 ## Predicate pattern loops
 
+r[expr.loop.while.let]
+
+r[expr.loop.while.let.syntax]
 > **<sup>Syntax</sup>**\
 > [_PredicatePatternLoopExpression_] :\
 > &nbsp;&nbsp; `while` `let` [_Pattern_] `=` [_Scrutinee_]<sub>_except lazy boolean operator expression_</sub>
 >              [_BlockExpression_]
 
 
+r[expr.loop.while.let.intro]
 A `while let` loop is semantically similar to a `while` loop but in place of a condition expression it expects the keyword `let` followed by a pattern, an `=`, a [scrutinee] expression and a block expression.
+
+r[expr.loop.while.let.condition]
 If the value of the scrutinee matches the pattern, the loop body block executes then control returns to the pattern matching statement.
 Otherwise, the while expression completes.
 
@@ -87,6 +115,7 @@ while let _ = 5 {
 }
 ```
 
+r[expr.loop.while.let.desugar]
 A `while let` loop is equivalent to a `loop` expression containing a [`match` expression] as follows.
 
 <!-- ignore: expansion example -->
@@ -108,6 +137,7 @@ is equivalent to
 }
 ```
 
+r[expr.loop.while.let.or-pattern]
 Multiple patterns may be specified with the `|` operator.
 This has the same semantics as with `|` in `match` expressions:
 
@@ -119,16 +149,23 @@ while let Some(v @ 1) | Some(v @ 2) = vals.pop() {
 }
 ```
 
+r[expr.loop.while.let.restriction]
 As is the case in [`if let` expressions], the scrutinee cannot be a [lazy boolean operator expression][_LazyBooleanOperatorExpression_].
 
 ## Iterator loops
 
+r[expr.loop.for]
+
+r[expr.loop.for.syntax]
 > **<sup>Syntax</sup>**\
 > _IteratorLoopExpression_ :\
 > &nbsp;&nbsp; `for` [_Pattern_] `in` [_Expression_]<sub>_except struct expression_</sub>
 >              [_BlockExpression_]
 
+r[expr.loop.for.intro]
 A `for` expression is a syntactic construct for looping over elements provided by an implementation of `std::iter::IntoIterator`.
+
+r[expr.loop.for.condition]
 If the iterator yields a value, that value is matched against the irrefutable pattern, the body of the loop is executed, and then control returns to the head of the `for` loop.
 If the iterator is empty, the `for` expression completes.
 
@@ -152,6 +189,7 @@ for n in 1..11 {
 assert_eq!(sum, 55);
 ```
 
+r[expr.loop.for.desugar]
 A `for` loop is equivalent to a `loop` expression containing a [`match` expression] as follows:
 
 <!-- ignore: expansion example -->
@@ -181,22 +219,31 @@ is equivalent to
 }
 ```
 
+r[expr.loop.for.lang-items]
 `IntoIterator`, `Iterator`, and `Option` are always the standard library items here, not whatever those names resolve to in the current scope.
+
 The variable names `next`, `iter`, and `val` are for exposition only, they do not actually have names the user can type.
 
 > **Note**: that the outer `match` is used to ensure that any [temporary values] in `iter_expr` don't get dropped before the loop is finished.
 > `next` is declared before being assigned because it results in types being inferred correctly more often.
 
 ## Loop labels
 
+r[expr.loop.label]
+
+r[expr.loop.label.syntax]
 > **<sup>Syntax</sup>**\
 > _LoopLabel_ :\
 > &nbsp;&nbsp; [LIFETIME_OR_LABEL] `:`
 
+r[expr.loop.label.intro]
 A loop expression may optionally have a _label_. The label is written as a lifetime preceding the loop expression, as in `'foo: loop { break 'foo; }`, `'bar: while false {}`, `'humbug: for _ in 0..0 {}`.
+
+r[expr.loop.label.control-flow]
 If a label is present, then labeled `break` and `continue` expressions nested within this loop may exit out of this loop or return control to its head.
 See [break expressions](#break-expressions) and [continue expressions](#continue-expressions).
 
+r[expr.loop.label.ref]
 Labels follow the hygiene and shadowing rules of local variables. For example, this code will print "outer loop":
 
 ```rust
@@ -213,10 +260,14 @@ Labels follow the hygiene and shadowing rules of local variables. For example, t
 
 ## `break` expressions
 
+r[expr.loop.break]
+
+r[expr.loop.break.syntax]
 > **<sup>Syntax</sup>**\
 > _BreakExpression_ :\
 > &nbsp;&nbsp; `break` [LIFETIME_OR_LABEL]<sup>?</sup> [_Expression_]<sup>?</sup>
 
+r[expr.loop.break.intro]
 When `break` is encountered, execution of the associated loop body is immediately terminated, for example:
 
 ```rust
@@ -230,6 +281,7 @@ for x in 1..100 {
 assert_eq!(last, 12);
 ```
 
+r[expr.loop.break.label]
 A `break` expression is normally associated with the innermost `loop`, `for` or `while` loop enclosing the `break` expression,
 but a [label](#loop-labels) can be used to specify which enclosing loop is affected.
 Example:
@@ -242,16 +294,24 @@ Example:
 }
 ```
 
+r[expr.loop.break.value]
 A `break` expression is only permitted in the body of a loop, and has one of the forms `break`, `break 'label` or ([see below](#break-and-loop-values)) `break EXPR` or `break 'label EXPR`.
 
 ## Labelled block expressions
 
+r[expr.loop.block-labels]
+
 > **<sup>Syntax</sup>**\
 > _LabelBlockExpression_ :\
 > &nbsp;&nbsp; [_BlockExpression_]
 
+r[expr.loop.block-labels.intro]
 Labelled block expressions are exactly like block expressions, except that they allow using `break` expressions within the block.
+
+r[expr.loop.block-labels.break]
 Unlike loops, `break` expressions within a labelled block expression *must* have a label (i.e. the label is not optional).
+
+r[expr.loop.block-labels.restriction]
 Similarly, labelled block expressions *must* begin with a label.
 
 ```rust
@@ -275,19 +335,33 @@ let result = 'block: {
 
 ## `continue` expressions
 
+r[expr.loop.continue]
+
+r[expr.loop.continue.syntax]
 > **<sup>Syntax</sup>**\
 > _ContinueExpression_ :\
 > &nbsp;&nbsp; `continue` [LIFETIME_OR_LABEL]<sup>?</sup>
 
+r[expr.loop.continue.intro]
 When `continue` is encountered, the current iteration of the associated loop body is immediately terminated, returning control to the loop *head*.
+
+r[expr.loop.continue.while]
 In the case of a `while` loop, the head is the conditional expression controlling the loop.
+
+r[expr.loop.continue.for]
 In the case of a `for` loop, the head is the call-expression controlling the loop.
 
+r[expr.loop.continue.label]
 Like `break`, `continue` is normally associated with the innermost enclosing loop, but `continue 'label` may be used to specify the loop affected.
+
+r[expr.loop.continue.constraint]
 A `continue` expression is only permitted in the body of a loop.
 
 ## `break` and loop values
 
+r[expr.loop.break-value]
+
+r[expr.loop.break-value.intro]
 When associated with a `loop`, a break expression may be used to return a value from that loop, via one of the forms `break EXPR` or `break 'label EXPR`, where `EXPR` is an expression whose result is returned from the `loop`.
 For example:
 
@@ -305,6 +379,7 @@ let result = loop {
 assert_eq!(result, 13);
 ```
 
+r[expr.loop.break-value.loop]
 In the case a `loop` has an associated `break`, it is not considered diverging, and the `loop` must have a type compatible with each `break` expression.
 `break` without an expression is considered identical to `break` with expression `()`.
 

src/expressions/match-expr.md

@@ -1,5 +1,8 @@
 # `match` expressions
 
+r[expr.match]
+
+r[expr.match.syntax]
 > **<sup>Syntax</sup>**\
 > _MatchExpression_ :\
 > &nbsp;&nbsp; `match` _Scrutinee_ `{`\
@@ -23,15 +26,24 @@
 > _MatchArmGuard_ :\
 > &nbsp;&nbsp; `if` [_Expression_]
 
+r[expr.match.intro]
 A *`match` expression* branches on a pattern.
 The exact form of matching that occurs depends on the [pattern].
+
+r[expr.match.scrutinee]
 A `match` expression has a *[scrutinee] expression*, which is the value to compare to the patterns.
+
+r[expr.match.scrutinee-constraint]
 The scrutinee expression and the patterns must have the same type.
 
+r[expr.match.scrutinee-behaviour]
 A `match` behaves differently depending on whether or not the scrutinee expression is a [place expression or value expression][place expression].
+
+r[expr.match.scrutinee-value]
 If the scrutinee expression is a [value expression], it is first evaluated into a temporary location, and the resulting value is sequentially compared to the patterns in the arms until a match is found.
 The first arm with a matching pattern is chosen as the branch target of the `match`, any variables bound by the pattern are assigned to local variables in the arm's block, and control enters the block.
 
+r[expr.match.scrutinee-place]
 When the scrutinee expression is a [place expression], the match does not allocate a temporary location;
 however, a by-value binding may copy or move from the memory location.
 When possible, it is preferable to match on place expressions, as the lifetime of these matches inherits the lifetime of the place expression rather than being restricted to the inside of the match.
@@ -51,9 +63,13 @@ match x {
 }
 ```
 
+r[expr.match.pattern-vars]
 Variables bound within the pattern are scoped to the match guard and the arm's expression.
+
+r[expr.match.pattern-var-binding]
 The [binding mode] (move, copy, or reference) depends on the pattern.
 
+r[expr.match.or-pattern]
 Multiple match patterns may be joined with the `|` operator.
 Each pattern will be tested in left-to-right sequence until a successful match is found.
 
@@ -79,16 +95,27 @@ match S(1, 2) {
 > Note: The `2..=9` is a [Range Pattern], not a [Range Expression].
 > Thus, only those types of ranges supported by range patterns can be used in match arms.
 
+r[expr.match.or-patterns-restriction]
 Every binding in each `|` separated pattern must appear in all of the patterns in the arm.
+
+r[expr.match.binding-restriction]
 Every binding of the same name must have the same type, and have the same binding mode.
 
 ## Match guards
 
+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.behaviour]
 When the pattern matches successfully, the pattern guard expression is executed.
 If the expression evaluates to true, the pattern is successfully matched against.
+
+r[expr.match.guard.next]
 Otherwise, the next pattern, including other matches with the `|` operator in the same arm, is tested.
 
 ```rust
@@ -115,18 +142,29 @@ let message = match maybe_digit {
 > assert_eq!(i.get(), 2);
 > ```
 
+r[expr.match.guard.bound-variables]
 A pattern guard may refer to the variables bound within the pattern they follow.
+
+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.
+
+r[expr.match.guard.restriction]
 Moreover, by holding a shared reference while evaluating the guard, mutation inside guards is also prevented.
 
 ## Attributes on match arms
 
+r[expr.match.attributes]
+
+r[expr.match.attributes.outer]
 Outer attributes are allowed on match arms.
 The only attributes that have meaning on match arms are [`cfg`] and the [lint check attributes].
 
+r[expr.match.attributes.inner]
 [Inner attributes] are allowed directly after the opening brace of the match expression in the same expression contexts as [attributes on block expressions].
 
 [_Expression_]: ../expressions.md