---

yaml
---
r: 31476
b: refs/heads/dist-snap
c: e11e90f
h: refs/heads/master
v: v3

Author: graydon

[refs]

@@ -7,6 +7,6 @@ refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b
 refs/heads/try2: d0c6ce338884ee21843f4b40bf6bf18d222ce5df
 refs/heads/incoming: d9317a174e434d4c99fc1a37fd7dc0d2f5328d37
-refs/heads/dist-snap: eabd233dcd208bc21ca0f8eea02d87d56e5314eb
+refs/heads/dist-snap: e11e90f31cedabec1e84b505bbf64103c3421574
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596
 refs/tags/release-0.3: b5f0d0f648d9a6153664837026ba1be43d3e2503

branches/dist-snap/src/libsyntax/ast.rs

@@ -362,46 +362,68 @@ type capture_item = @{
 #[auto_serialize]
 type capture_clause = @~[capture_item];
 
+//
+// When the main rust parser encounters a syntax-extension invocation, it
+// parses the arguments to the invocation as a token-tree. This is a very
+// loose structure, such that all sorts of different AST-fragments can
+// be passed to syntax extensions using a uniform type.
+//
+// If the syntax extension is an MBE macro, it will attempt to match its
+// LHS "matchers" against the provided token tree, and if it finds a
+// match, will transcribe the RHS token tree, splicing in any captured
+// early_parser::matched_nonterminals into the tt_nonterminals it finds.
+//
+// The RHS of an MBE macro is the only place a tt_nonterminal or tt_seq
+// makes any real sense. You could write them elsewhere but nothing
+// else knows what to do with them, so you'll probably get a syntax
+// error.
+//
 #[auto_serialize]
 #[doc="For macro invocations; parsing is delegated to the macro"]
 enum token_tree {
+    tt_tok(span, token::token),
     tt_delim(~[token_tree]),
-    tt_flat(span, token::token),
-    /* These only make sense for right-hand-sides of MBE macros*/
-    tt_dotdotdot(span, ~[token_tree], option<token::token>, bool),
-    tt_interpolate(span, ident)
+    // These only make sense for right-hand-sides of MBE macros
+    tt_seq(span, ~[token_tree], option<token::token>, bool),
+    tt_nonterminal(span, ident)
 }
 
-#[auto_serialize]
-type matcher = spanned<matcher_>;
-
-#[auto_serialize]
 //
 // Matchers are nodes defined-by and recognized-by the main rust parser and
-// language, but they're only ever found inside syntax-extension invocations.
-// They represent a small sub-language for pattern-matching token-trees, and
-// are thus primarily used by the macro-defining extension itself.
+// language, but they're only ever found inside syntax-extension invocations;
+// indeed, the only thing that ever _activates_ the rules in the rust parser
+// for parsing a matcher is a matcher looking for the 'mtcs' nonterminal
+// itself. Matchers represent a small sub-language for pattern-matching
+// token-trees, and are thus primarily used by the macro-defining extension
+// itself.
 //
-// mtc_tok   ===>   A matcher that matches a single token,
-//                  denoted by the token itself. So long as
-//                  there's no $ involved.
+// match_tok
+// ---------
 //
+//     A matcher that matches a single token, denoted by the token itself. So
+//     long as there's no $ involved.
 //
-// mtc_rep   ===>   A matcher that matches a sequence of
-//                  sub-matchers, denoted various ways:
+//
+// match_seq
+// ---------
+//
+//     A matcher that matches a sequence of sub-matchers, denoted various
+//     possible ways:
 //
 //             $(M)*       zero or more Ms
 //             $(M)+       one or more Ms
 //             $(M),+      one or more comma-separated Ms
 //             $(A B C);*  zero or more semi-separated 'A B C' seqs
 //
 //
-// mtc_bb ===> A matcher that matches one of a few interesting named rust
-//             nonterminals, such as types, expressions, items, or raw
-//             token-trees. A black-box matcher on expr, for example, binds an
-//             expr to a given ident, and that ident can re-occur as an
-//             interpolation in the RHS of a macro-by-example rule. For
-//             example:
+// match_nonterminal
+// -----------------
+//
+//     A matcher that matches one of a few interesting named rust
+//     nonterminals, such as types, expressions, items, or raw token-trees. A
+//     black-box matcher on expr, for example, binds an expr to a given ident,
+//     and that ident can re-occur as an interpolation in the RHS of a
+//     macro-by-example rule. For example:
 //
 //        $foo:expr   =>     1 + $foo    // interpolate an expr
 //        $foo:tt     =>     $foo        // interpolate a token-tree
@@ -411,21 +433,25 @@ type matcher = spanned<matcher_>;
 //
 // As a final, horrifying aside, note that macro-by-example's input is
 // also matched by one of these matchers. Holy self-referential! It is matched
-// by an mtc_rep, specifically this one:
+// by an match_seq, specifically this one:
 //
 //                   $( $lhs:mtcs => $rhs:tt );+
 //
 // If you understand that, you have closed to loop and understand the whole
 // macro system. Congratulations.
 //
+#[auto_serialize]
+type matcher = spanned<matcher_>;
+
+#[auto_serialize]
 enum matcher_ {
-    /* match one token */
-    mtc_tok(token::token),
-    /* match repetitions of a sequence: body, separator, zero ok?,
-    lo, hi position-in-match-array used: */
-    mtc_rep(~[matcher], option<token::token>, bool, uint, uint),
-    /* parse a Rust NT: name to bind, name of NT, position in match array : */
-    mtc_bb(ident, ident, uint)
+    // match one token
+    match_tok(token::token),
+    // match repetitions of a sequence: body, separator, zero ok?,
+    // lo, hi position-in-match-array used:
+    match_seq(~[matcher], option<token::token>, bool, uint, uint),
+    // parse a Rust NT: name to bind, name of NT, position in match array:
+    match_nonterminal(ident, ident, uint)
 }
 
 #[auto_serialize]

branches/dist-snap/src/libsyntax/ext/base.rs

@@ -4,18 +4,6 @@ import diagnostic::span_handler;
 import codemap::{codemap, span, expn_info, expanded_from};
 import std::map::str_hash;
 
-
-// Nomenclature / abbreviations in the ext modules:
-//
-//     ms: matcher span, wraps a matcher with fake span
-//    mtc: matcher
-//   mtcs: matchers
-//     tt: token tree
-//     bt: backtrace
-//     cx: expansion context
-//     mr: macro result
-//
-
 // obsolete old-style #macro code:
 //
 //    syntax_expander, normal, macro_defining, macro_definer,
@@ -288,28 +276,29 @@ fn get_mac_body(cx: ext_ctxt, sp: span, args: ast::mac_body)
 // using new syntax. This will be obsolete when #old_macros go away.
 fn tt_args_to_original_flavor(cx: ext_ctxt, sp: span, arg: ~[ast::token_tree])
     -> ast::mac_arg {
-    import ast::{matcher, matcher_, mtc_tok, mtc_rep, mtc_bb};
+    import ast::{matcher, matcher_, match_tok, match_seq, match_nonterminal};
     import parse::lexer::{new_tt_reader, tt_reader_as_reader, reader};
-    import tt::earley_parser::{parse_or_else, seq, leaf};
+    import tt::earley_parser::{parse_or_else, matched_seq,
+                               matched_nonterminal};
 
     // these spans won't matter, anyways
     fn ms(m: matcher_) -> matcher {
         {node: m, span: {lo: 0u, hi: 0u, expn_info: none}}
     }
 
-    let argument_gram = ~[ms(mtc_rep(~[
-        ms(mtc_bb(@~"arg",@~"expr", 0u))
+    let argument_gram = ~[ms(match_seq(~[
+        ms(match_nonterminal(@~"arg",@~"expr", 0u))
     ], some(parse::token::COMMA), true, 0u, 1u))];
 
     let arg_reader = new_tt_reader(cx.parse_sess().span_diagnostic,
                                    cx.parse_sess().interner, none, arg);
     let args =
         alt parse_or_else(cx.parse_sess(), cx.cfg(), arg_reader as reader,
                           argument_gram).get(@~"arg") {
-          @seq(s, _) {
+          @matched_seq(s, _) {
             do s.map() |lf| {
                 alt lf {
-                  @leaf(parse::token::w_expr(arg)) {
+                  @matched_nonterminal(parse::token::nt_expr(arg)) {
                     arg /* whew! list of exprs, here we come! */
                   }
                   _ { fail ~"badly-structured parse result"; }

branches/dist-snap/src/libsyntax/ext/expand.rs

@@ -1,7 +1,7 @@
 import std::map::hashmap;
 
 import ast::{crate, expr_, expr_mac, mac_invoc, mac_invoc_tt,
-             tt_delim, tt_flat, item_mac};
+             tt_delim, tt_tok, item_mac};
 import fold::*;
 import ext::base::*;
 import ext::qquote::{qq_helper};