Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document the 2021 edition changes to macros-by-example pat metavariables #1135

Merged
merged 2 commits into from
Jan 13, 2022
Merged

Document the 2021 edition changes to macros-by-example pat metavariables #1135

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
efc2cf3
Document the 2021 edition changes to macros-by-example `pat` metavari…
mattheww Jan 9, 2022
94a041f
Clarify that the macro_rules! `pat` behaviour depends on the macro de…
mattheww Jan 11, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 12 additions & 2 deletions src/macros-by-example.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ fragment specifiers are:
* `stmt`: a [_Statement_] without the trailing semicolon (except for item
statements that require semicolons)
* `pat_param`: a [_PatternNoTopAlt_]
* `pat`: equivalent to `pat_param`
* `pat`: at least any [_PatternNoTopAlt_], and possibly more depending on edition
* `expr`: an [_Expression_]
* `ty`: a [_Type_]
* `ident`: an [IDENTIFIER_OR_KEYWORD] or [RAW_IDENTIFIER]
Expand All @@ -140,6 +140,12 @@ the syntax element that matched them. The keyword metavariable `$crate` can be
used to refer to the current crate; see [Hygiene] below. Metavariables can be
transcribed more than once or not at all.

> **Edition Differences**: Starting with the 2021 edition, `pat` fragment-specifiers match top-level or-patterns (that is, they accept [_Pattern_]).
>
> Before the 2021 edition, they match exactly the same fragments as `pat_param` (that is, they accept [_PatternNoTopAlt_]).
>
> The relevant edition is the one in effect for the `macro_rules!` definition.

## Repetitions

In both the matcher and transcriber, repetitions are indicated by placing the
Expand Down Expand Up @@ -451,7 +457,8 @@ Matchers like `$i:expr,` or `$i:expr;` would be legal, however, because `,` and
`;` are legal expression separators. The specific rules are:

* `expr` and `stmt` may only be followed by one of: `=>`, `,`, or `;`.
* `pat` and `pat_param` may only be followed by one of: `=>`, `,`, `=`, `|`, `if`, or `in`.
* `pat_param` may only be followed by one of: `=>`, `,`, `=`, `|`, `if`, or `in`.
* `pat` may only be followed by one of: `=>`, `,`, `=`, `if`, or `in`.
* `path` and `ty` may only be followed by one of: `=>`, `,`, `=`, `|`, `;`,
`:`, `>`, `>>`, `[`, `{`, `as`, `where`, or a macro variable of `block`
fragment specifier.
Expand All @@ -460,6 +467,8 @@ Matchers like `$i:expr,` or `$i:expr;` would be legal, however, because `,` and
`ident`, `ty`, or `path` fragment specifier.
* All other fragment specifiers have no restrictions.

> **Edition Differences**: Before the 2021 edition, `pat` may also be followed by `|`.

When repetitions are involved, then the rules apply to every possible number of
expansions, taking separators into account. This means:

Expand Down Expand Up @@ -490,6 +499,7 @@ For more detail, see the [formal specification].
[_Item_]: items.md
[_LiteralExpression_]: expressions/literal-expr.md
[_MetaListIdents_]: attributes.md#meta-item-attribute-syntax
[_Pattern_]: patterns.md
[_PatternNoTopAlt_]: patterns.md
[_Statement_]: statements.md
[_TokenTree_]: macros.md#macro-invocation
Expand Down