crates/parser/src/grammar.rs

   1 //! This is the actual "grammar" of the Rust language.
   2 //!
   3 //! Each function in this module and its children corresponds
   4 //! to a production of the formal grammar. Submodules roughly
   5 //! correspond to different *areas* of the grammar. By convention,
   6 //! each submodule starts with `use super::*` import and exports
   7 //! "public" productions via `pub(super)`.
   8 //!
   9 //! See docs for [`Parser`](super::parser::Parser) to learn about API,
  10 //! available to the grammar, and see docs for [`Event`](super::event::Event)
  11 //! to learn how this actually manages to produce parse trees.
  12 //!
  13 //! Code in this module also contains inline tests, which start with
  14 //! `// test name-of-the-test` comment and look like this:
  15 //!
  16 //! ```
  17 //! // test function_with_zero_parameters
  18 //! // fn foo() {}
  19 //! ```
  20 //!
  21 //! After adding a new inline-test, run `cargo test -p xtask` to
  22 //! extract it as a standalone text-fixture into
  23 //! `crates/syntax/test_data/parser/`, and run `cargo test` once to
  24 //! create the "gold" value.
  25 //!
  26 //! Coding convention: rules like `where_clause` always produce either a
  27 //! node or an error, rules like `opt_where_clause` may produce nothing.
  28 //! Non-opt rules typically start with `assert!(p.at(FIRST_TOKEN))`, the
  29 //! caller is responsible for branching on the first token.
  30
  31 mod attributes;
  32 mod expressions;
  33 mod items;
  34 mod params;
  35 mod paths;
  36 mod patterns;
  37 mod generic_args;
  38 mod generic_params;
  39 mod types;
  40
  41 use crate::{
  42     parser::{CompletedMarker, Marker, Parser},
  43     SyntaxKind::{self, *},
  44     TokenSet, T,
  45 };
  46
  47 pub(crate) mod entry {
  48     use super::*;
  49
  50     pub(crate) mod prefix {
  51         use super::*;
  52
  53         pub(crate) fn vis(p: &mut Parser) {
  54             let _ = opt_visibility(p, false);
  55         }
  56
  57         pub(crate) fn block(p: &mut Parser) {
  58             expressions::block_expr(p);
  59         }
  60
  61         pub(crate) fn stmt(p: &mut Parser) {
  62             expressions::stmt(p, expressions::Semicolon::Forbidden);
  63         }
  64
  65         pub(crate) fn pat(p: &mut Parser) {
  66             patterns::pattern_single(p);
  67         }
  68
  69         pub(crate) fn ty(p: &mut Parser) {
  70             types::type_(p);
  71         }
  72         pub(crate) fn expr(p: &mut Parser) {
  73             let _ = expressions::expr(p);
  74         }
  75         pub(crate) fn path(p: &mut Parser) {
  76             let _ = paths::type_path(p);
  77         }
  78         pub(crate) fn item(p: &mut Parser) {
  79             items::item_or_macro(p, true);
  80         }
  81         // Parse a meta item , which excluded [], e.g : #[ MetaItem ]
  82         pub(crate) fn meta_item(p: &mut Parser) {
  83             attributes::meta(p);
  84         }
  85     }
  86
  87     pub(crate) mod top {
  88         use super::*;
  89
  90         pub(crate) fn source_file(p: &mut Parser) {
  91             let m = p.start();
  92             p.eat(SHEBANG);
  93             items::mod_contents(p, false);
  94             m.complete(p, SOURCE_FILE);
  95         }
  96
  97         pub(crate) fn macro_stmts(p: &mut Parser) {
  98             let m = p.start();
  99
 100             while !p.at(EOF) {
 101                 expressions::stmt(p, expressions::Semicolon::Optional);
 102             }
 103
 104             m.complete(p, MACRO_STMTS);
 105         }
 106
 107         pub(crate) fn macro_items(p: &mut Parser) {
 108             let m = p.start();
 109             items::mod_contents(p, false);
 110             m.complete(p, MACRO_ITEMS);
 111         }
 112
 113         pub(crate) fn pattern(p: &mut Parser) {
 114             let m = p.start();
 115             patterns::pattern_single(p);
 116             if p.at(EOF) {
 117                 m.abandon(p);
 118                 return;
 119             }
 120             while !p.at(EOF) {
 121                 p.bump_any();
 122             }
 123             m.complete(p, ERROR);
 124         }
 125
 126         pub(crate) fn type_(p: &mut Parser) {
 127             let m = p.start();
 128             types::type_(p);
 129             if p.at(EOF) {
 130                 m.abandon(p);
 131                 return;
 132             }
 133             while !p.at(EOF) {
 134                 p.bump_any();
 135             }
 136             m.complete(p, ERROR);
 137         }
 138
 139         pub(crate) fn expr(p: &mut Parser) {
 140             let m = p.start();
 141             expressions::expr(p);
 142             if p.at(EOF) {
 143                 m.abandon(p);
 144                 return;
 145             }
 146             while !p.at(EOF) {
 147                 p.bump_any();
 148             }
 149             m.complete(p, ERROR);
 150         }
 151
 152         pub(crate) fn meta_item(p: &mut Parser) {
 153             let m = p.start();
 154             attributes::meta(p);
 155             if p.at(EOF) {
 156                 m.abandon(p);
 157                 return;
 158             }
 159             while !p.at(EOF) {
 160                 p.bump_any();
 161             }
 162             m.complete(p, ERROR);
 163         }
 164     }
 165 }
 166
 167 pub(crate) fn reparser(
 168     node: SyntaxKind,
 169     first_child: Option<SyntaxKind>,
 170     parent: Option<SyntaxKind>,
 171 ) -> Option<fn(&mut Parser)> {
 172     let res = match node {
 173         BLOCK_EXPR => expressions::block_expr,
 174         RECORD_FIELD_LIST => items::record_field_list,
 175         RECORD_EXPR_FIELD_LIST => items::record_expr_field_list,
 176         VARIANT_LIST => items::variant_list,
 177         MATCH_ARM_LIST => items::match_arm_list,
 178         USE_TREE_LIST => items::use_tree_list,
 179         EXTERN_ITEM_LIST => items::extern_item_list,
 180         TOKEN_TREE if first_child? == T!['{'] => items::token_tree,
 181         ASSOC_ITEM_LIST => match parent? {
 182             IMPL | TRAIT => items::assoc_item_list,
 183             _ => return None,
 184         },
 185         ITEM_LIST => items::item_list,
 186         _ => return None,
 187     };
 188     Some(res)
 189 }
 190
 191 #[derive(Clone, Copy, PartialEq, Eq)]
 192 enum BlockLike {
 193     Block,
 194     NotBlock,
 195 }
 196
 197 impl BlockLike {
 198     fn is_block(self) -> bool {
 199         self == BlockLike::Block
 200     }
 201 }
 202
 203 fn opt_visibility(p: &mut Parser, in_tuple_field: bool) -> bool {
 204     match p.current() {
 205         T![pub] => {
 206             let m = p.start();
 207             p.bump(T![pub]);
 208             if p.at(T!['(']) {
 209                 match p.nth(1) {
 210                     // test crate_visibility
 211                     // pub(crate) struct S;
 212                     // pub(self) struct S;
 213                     // pub(super) struct S;
 214
 215                     // test pub_parens_typepath
 216                     // struct B(pub (super::A));
 217                     // struct B(pub (crate::A,));
 218                     T![crate] | T![self] | T![super] | T![ident] if p.nth(2) != T![:] => {
 219                         // If we are in a tuple struct, then the parens following `pub`
 220                         // might be an tuple field, not part of the visibility. So in that
 221                         // case we don't want to consume an identifier.
 222
 223                         // test pub_tuple_field
 224                         // struct MyStruct(pub (u32, u32));
 225                         if !(in_tuple_field && matches!(p.nth(1), T![ident])) {
 226                             p.bump(T!['(']);
 227                             paths::use_path(p);
 228                             p.expect(T![')']);
 229                         }
 230                     }
 231                     // test crate_visibility_in
 232                     // pub(in super::A) struct S;
 233                     // pub(in crate) struct S;
 234                     T![in] => {
 235                         p.bump(T!['(']);
 236                         p.bump(T![in]);
 237                         paths::use_path(p);
 238                         p.expect(T![')']);
 239                     }
 240                     _ => (),
 241                 }
 242             }
 243             m.complete(p, VISIBILITY);
 244             true
 245         }
 246         // test crate_keyword_vis
 247         // crate fn main() { }
 248         // struct S { crate field: u32 }
 249         // struct T(crate u32);
 250         T![crate] => {
 251             if p.nth_at(1, T![::]) {
 252                 // test crate_keyword_path
 253                 // fn foo() { crate::foo(); }
 254                 return false;
 255             }
 256             let m = p.start();
 257             p.bump(T![crate]);
 258             m.complete(p, VISIBILITY);
 259             true
 260         }
 261         _ => false,
 262     }
 263 }
 264
 265 fn opt_rename(p: &mut Parser) {
 266     if p.at(T![as]) {
 267         let m = p.start();
 268         p.bump(T![as]);
 269         if !p.eat(T![_]) {
 270             name(p);
 271         }
 272         m.complete(p, RENAME);
 273     }
 274 }
 275
 276 fn abi(p: &mut Parser) {
 277     assert!(p.at(T![extern]));
 278     let abi = p.start();
 279     p.bump(T![extern]);
 280     p.eat(STRING);
 281     abi.complete(p, ABI);
 282 }
 283
 284 fn opt_ret_type(p: &mut Parser) -> bool {
 285     if p.at(T![->]) {
 286         let m = p.start();
 287         p.bump(T![->]);
 288         types::type_no_bounds(p);
 289         m.complete(p, RET_TYPE);
 290         true
 291     } else {
 292         false
 293     }
 294 }
 295
 296 fn name_r(p: &mut Parser, recovery: TokenSet) {
 297     if p.at(IDENT) {
 298         let m = p.start();
 299         p.bump(IDENT);
 300         m.complete(p, NAME);
 301     } else {
 302         p.err_recover("expected a name", recovery);
 303     }
 304 }
 305
 306 fn name(p: &mut Parser) {
 307     name_r(p, TokenSet::EMPTY);
 308 }
 309
 310 fn name_ref(p: &mut Parser) {
 311     if p.at(IDENT) {
 312         let m = p.start();
 313         p.bump(IDENT);
 314         m.complete(p, NAME_REF);
 315     } else {
 316         p.err_and_bump("expected identifier");
 317     }
 318 }
 319
 320 fn name_ref_or_index(p: &mut Parser) {
 321     assert!(p.at(IDENT) || p.at(INT_NUMBER));
 322     let m = p.start();
 323     p.bump_any();
 324     m.complete(p, NAME_REF);
 325 }
 326
 327 fn lifetime(p: &mut Parser) {
 328     assert!(p.at(LIFETIME_IDENT));
 329     let m = p.start();
 330     p.bump(LIFETIME_IDENT);
 331     m.complete(p, LIFETIME);
 332 }
 333
 334 fn error_block(p: &mut Parser, message: &str) {
 335     assert!(p.at(T!['{']));
 336     let m = p.start();
 337     p.error(message);
 338     p.bump(T!['{']);
 339     expressions::expr_block_contents(p);
 340     p.eat(T!['}']);
 341     m.complete(p, ERROR);
 342 }