Skip to content

Commit

Permalink
Update parser_tt docs following rust-lang/rust#95555
Browse files Browse the repository at this point in the history
  • Loading branch information
JohnTitor committed Apr 15, 2022
1 parent bd89a7c commit 1b06477
Showing 1 changed file with 13 additions and 11 deletions.
24 changes: 13 additions & 11 deletions src/macro-expansion.md
Original file line number Diff line number Diff line change
Expand Up @@ -227,7 +227,7 @@ only within the macro (i.e. it should not be visible outside the macro).
[code_dir]: https://github.com/rust-lang/rust/tree/master/compiler/rustc_expand/src/mbe
[code_mp]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_expand/mbe/macro_parser
[code_mr]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_expand/mbe/macro_rules
[code_parse_int]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_expand/mbe/macro_parser/fn.parse_tt.html
[code_parse_int]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_expand/mbe/macro_parser/struct.TtParser.html#method.parse_tt
[parsing]: ./the-parser.html
The context is attached to AST nodes. All AST nodes generated by macros have
Expand Down Expand Up @@ -503,9 +503,10 @@ The interface of the macro parser is as follows (this is slightly simplified):

```rust,ignore
fn parse_tt(
parser: &mut Cow<Parser>,
ms: &[TokenTree],
) -> NamedParseResult
&mut self,
parser: &mut Cow<'_, Parser<'_>>,
matcher: &[MatcherLoc]
) -> ParseResult
```

We use these items in macro parser:
Expand All @@ -515,20 +516,20 @@ We use these items in macro parser:
ask the MBE parser to parse. We will consume the raw stream of tokens and
output a binding of metavariables to corresponding token trees. The parsing
session can be used to report parser errors.
- `ms` a _matcher_. This is a sequence of token trees that we want to match
the token stream against.
- `matcher` is a sequence of `MatcherLoc`s that we want to match
the token stream against. They're converted from token trees before matching.

In the analogy of a regex parser, the token stream is the input and we are matching it
against the pattern `ms`. Using our examples, the token stream could be the stream of
tokens containing the inside of the example invocation `print foo`, while `ms`
against the pattern `matcher`. Using our examples, the token stream could be the stream of
tokens containing the inside of the example invocation `print foo`, while `matcher`
might be the sequence of token (trees) `print $mvar:ident`.

The output of the parser is a `NamedParseResult`, which indicates which of
The output of the parser is a [`ParseResult`], which indicates which of
three cases has occurred:

- Success: the token stream matches the given matcher `ms`, and we have produced a binding
- Success: the token stream matches the given `matcher`, and we have produced a binding
from metavariables to the corresponding token trees.
- Failure: the token stream does not match `ms`. This results in an error message such as
- Failure: the token stream does not match `matcher`. This results in an error message such as
"No rule expected token _blah_".
- Error: some fatal error has occurred _in the parser_. For example, this
happens if there are more than one pattern match, since that indicates
Expand Down Expand Up @@ -607,6 +608,7 @@ Because the Rust ABI is unstable, we use the C ABI for this conversion.
[stablets]: https://doc.rust-lang.org/proc_macro/struct.TokenStream.html
[pm]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_expand/proc_macro/index.html
[pms]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_expand/proc_macro_server/index.html
[`ParseResult`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_expand/mbe/macro_parser/enum.ParseResult.html

TODO: more here. [#1160](https://github.com/rust-lang/rustc-dev-guide/issues/1160)

Expand Down

0 comments on commit 1b06477

Please sign in to comment.