From b8debdeb901094c3a083dfb402102578489bf775 Mon Sep 17 00:00:00 2001 From: Yuki Okushi Date: Fri, 15 Apr 2022 17:51:49 +0900 Subject: [PATCH] Update `parser_tt` docs following rust-lang/rust#95555 --- src/macro-expansion.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/src/macro-expansion.md b/src/macro-expansion.md index e3b5a27e6..840bfabe8 100644 --- a/src/macro-expansion.md +++ b/src/macro-expansion.md @@ -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 @@ -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, - ms: &[TokenTree], -) -> NamedParseResult + &mut self, + parser: &mut Cow<'_, Parser<'_>>, + matcher: &[MatcherLoc] +) -> ParseResult ``` We use these items in macro parser: @@ -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 @@ -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)