From 0b50be99feb356dd47b2bf21e74f656703919863 Mon Sep 17 00:00:00 2001 From: Mark Mansi Date: Sat, 22 Sep 2018 13:33:09 -0500 Subject: [PATCH 1/2] Add some notes on repetition --- src/macros-by-example.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/src/macros-by-example.md b/src/macros-by-example.md index 8723fc7e8..74bb32143 100644 --- a/src/macros-by-example.md +++ b/src/macros-by-example.md @@ -59,6 +59,10 @@ matches, in a structure that mimics the structure of the repetition encountered on a successful match. The job of the transcriber is to sort that structure out. +> **Edition Differences**: In the 2018 edition, a new Kleene operator was +> added: `?` means "at most once". This operator only works in edition 2018 and +> onward. `?` does not accept a repetition separator, unlike `+` and `*`. + The rules for transcription of these repetitions are called "Macro By Example". Essentially, one "layer" of repetition is discharged at a time, and all of them must be discharged by the time a name is transcribed. Therefore, `( $( $i:ident @@ -89,4 +93,8 @@ Rust syntax is restricted in two ways: pairs when they occur at the beginning of, or immediately after, a `$(...)*`; requiring a distinctive token in front can solve the problem. +> **Edition Differences**: As of the 2018 edition, `?` is not allowed as a +> repetition separator. This is to remove ambiguity with the new `?` Kleene +> operator. + [RFC 550]: https://github.com/rust-lang/rfcs/blob/master/text/0550-macro-future-proofing.md From 393aea78812d3ee9b09c8e6fe219e71fd64c6515 Mon Sep 17 00:00:00 2001 From: Mark Mansi Date: Thu, 27 Sep 2018 09:39:35 -0500 Subject: [PATCH 2/2] only diffs in edition notes --- src/macros-by-example.md | 32 +++++++++++++++++--------------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/src/macros-by-example.md b/src/macros-by-example.md index 74bb32143..0cebc8d55 100644 --- a/src/macros-by-example.md +++ b/src/macros-by-example.md @@ -51,17 +51,23 @@ designator is already known, and so only the name of a matched nonterminal comes after the dollar sign. In both the matcher and transcriber, the Kleene star-like operator indicates -repetition. The Kleene star operator consists of `$` and parentheses, optionally -followed by a separator token, followed by `*` or `+`. `*` means zero or more -repetitions, `+` means at least one repetition. The parentheses are not matched or -transcribed. On the matcher side, a name is bound to _all_ of the names it -matches, in a structure that mimics the structure of the repetition encountered -on a successful match. The job of the transcriber is to sort that structure -out. - -> **Edition Differences**: In the 2018 edition, a new Kleene operator was -> added: `?` means "at most once". This operator only works in edition 2018 and -> onward. `?` does not accept a repetition separator, unlike `+` and `*`. +repetition. The Kleene star operator consists of `$` and parentheses, +optionally followed by a separator token, followed by `*`, `+`, or `?`. `*` +means zero or more repetitions; `+` means _at least_ one repetition; `?` means +at most one repetition. The parentheses are not matched or transcribed. On the +matcher side, a name is bound to _all_ of the names it matches, in a structure +that mimics the structure of the repetition encountered on a successful match. +The job of the transcriber is to sort that structure out. Also, `?`, unlike `*` +and `+`, does _not_ allow a separator, since one could never match against it +anyway. + +> **Edition Differences**: The `?` Kleene operator did not exist before the +> 2018 edition. + +> **Edition Differences**: Prior to the 2018 Edition, `?` was an allowed +> separator token, rather than a Kleene operator. It is no longer allowed as a +> separator as of the 2018 edition. This avoids ambiguity with the `?` Kleene +> operator. The rules for transcription of these repetitions are called "Macro By Example". Essentially, one "layer" of repetition is discharged at a time, and all of them @@ -93,8 +99,4 @@ Rust syntax is restricted in two ways: pairs when they occur at the beginning of, or immediately after, a `$(...)*`; requiring a distinctive token in front can solve the problem. -> **Edition Differences**: As of the 2018 edition, `?` is not allowed as a -> repetition separator. This is to remove ambiguity with the new `?` Kleene -> operator. - [RFC 550]: https://github.com/rust-lang/rfcs/blob/master/text/0550-macro-future-proofing.md