hphp/hack/src/parser/declaration_parser.rs

   1 // Copyright (c) 2019, Facebook, Inc.
   2 // All rights reserved.
   3 //
   4 // This source code is licensed under the MIT license found in the
   5 // LICENSE file in the "hack" directory of this source tree.
   6
   7 use crate::expression_parser::ExpressionParser;
   8 use crate::lexer::Lexer;
   9 use crate::parser_env::ParserEnv;
  10 use crate::parser_trait::{Context, ExpectedTokens, ParserTrait, SeparatedListKind};
  11 use crate::smart_constructors::{NodeType, SmartConstructors};
  12 use crate::statement_parser::StatementParser;
  13 use crate::type_parser::TypeParser;
  14 use parser_core_types::lexable_token::LexableToken;
  15 use parser_core_types::lexable_trivia::LexableTrivia;
  16 use parser_core_types::syntax_error::{self as Errors, SyntaxError};
  17 use parser_core_types::token_kind::TokenKind;
  18 use parser_core_types::trivia_kind::TriviaKind;
  19
  20 #[derive(Debug)]
  21 pub struct DeclarationParser<'a, S, T>
  22 where
  23     S: SmartConstructors<'a, T>,
  24     S::R: NodeType,
  25 {
  26     lexer: Lexer<'a, S::Token>,
  27     env: ParserEnv,
  28     context: Context<'a, S::Token>,
  29     errors: Vec<SyntaxError>,
  30     sc: S,
  31 }
  32
  33 impl<'a, S, T: Clone> Clone for DeclarationParser<'a, S, T>
  34 where
  35     S: SmartConstructors<'a, T>,
  36     S::R: NodeType,
  37 {
  38     fn clone(&self) -> Self {
  39         Self {
  40             lexer: self.lexer.clone(),
  41             env: self.env.clone(),
  42             context: self.context.clone(),
  43             errors: self.errors.clone(),
  44             sc: self.sc.clone(),
  45         }
  46     }
  47 }
  48
  49 impl<'a, S, T: Clone> ParserTrait<'a, S, T> for DeclarationParser<'a, S, T>
  50 where
  51     S: SmartConstructors<'a, T>,
  52     S::R: NodeType,
  53 {
  54     fn make(
  55         lexer: Lexer<'a, S::Token>,
  56         env: ParserEnv,
  57         context: Context<'a, S::Token>,
  58         errors: Vec<SyntaxError>,
  59         sc: S,
  60     ) -> Self {
  61         Self {
  62             lexer,
  63             env,
  64             context,
  65             errors,
  66             sc,
  67         }
  68     }
  69
  70     fn into_parts(
  71         self,
  72     ) -> (
  73         Lexer<'a, S::Token>,
  74         Context<'a, S::Token>,
  75         Vec<SyntaxError>,
  76         S,
  77     ) {
  78         (self.lexer, self.context, self.errors, self.sc)
  79     }
  80
  81     fn lexer(&self) -> &Lexer<'a, S::Token> {
  82         &self.lexer
  83     }
  84
  85     fn lexer_mut(&mut self) -> &mut Lexer<'a, S::Token> {
  86         &mut self.lexer
  87     }
  88
  89     fn continue_from<P: ParserTrait<'a, S, T>>(&mut self, other: P)
  90     where
  91         T: Clone,
  92     {
  93         let (lexer, context, errors, sc) = other.into_parts();
  94         self.lexer = lexer;
  95         self.context = context;
  96         self.errors = errors;
  97         self.sc = sc;
  98     }
  99
 100     fn add_error(&mut self, error: SyntaxError) {
 101         self.errors.push(error)
 102     }
 103
 104     fn env(&self) -> &ParserEnv {
 105         &self.env
 106     }
 107
 108     fn sc_mut(&mut self) -> &mut S {
 109         &mut self.sc
 110     }
 111
 112     fn skipped_tokens_mut(&mut self) -> &mut Vec<S::Token> {
 113         &mut self.context.skipped_tokens
 114     }
 115
 116     fn skipped_tokens(&self) -> &[S::Token] {
 117         &self.context.skipped_tokens
 118     }
 119
 120     fn context_mut(&mut self) -> &mut Context<'a, S::Token> {
 121         &mut self.context
 122     }
 123
 124     fn context(&self) -> &Context<'a, S::Token> {
 125         &self.context
 126     }
 127 }
 128
 129 impl<'a, S, T: Clone> DeclarationParser<'a, S, T>
 130 where
 131     S: SmartConstructors<'a, T>,
 132     S::R: NodeType,
 133 {
 134     fn with_type_parser<F, U>(&mut self, f: F) -> U
 135     where
 136         T: Clone,
 137         F: Fn(&mut TypeParser<'a, S, T>) -> U,
 138     {
 139         let mut type_parser: TypeParser<S, T> = TypeParser::make(
 140             self.lexer.clone(),
 141             self.env.clone(),
 142             self.context.clone(),
 143             self.errors.clone(),
 144             self.sc.clone(),
 145         );
 146         let res = f(&mut type_parser);
 147         self.continue_from(type_parser);
 148         res
 149     }
 150
 151     fn parse_type_specifier(&mut self, allow_var: bool, allow_attr: bool) -> S::R {
 152         self.with_type_parser(|p: &mut TypeParser<'a, S, T>| {
 153             p.parse_type_specifier(allow_var, allow_attr)
 154         })
 155     }
 156
 157     fn with_statement_parser<F, U>(&mut self, f: F) -> U
 158     where
 159         T: Clone,
 160         F: Fn(&mut StatementParser<'a, S, T>) -> U,
 161     {
 162         let mut statement_parser: StatementParser<S, T> = StatementParser::make(
 163             self.lexer.clone(),
 164             self.env.clone(),
 165             self.context.clone(),
 166             self.errors.clone(),
 167             self.sc.clone(),
 168         );
 169         let res = f(&mut statement_parser);
 170         self.continue_from(statement_parser);
 171         res
 172     }
 173
 174     fn parse_simple_type_or_type_constant(&mut self) -> S::R {
 175         self.with_type_parser(|x: &mut TypeParser<'a, S, T>| x.parse_simple_type_or_type_constant())
 176     }
 177
 178     fn parse_simple_type_or_generic(&mut self) -> S::R {
 179         self.with_type_parser(|p: &mut TypeParser<'a, S, T>| p.parse_simple_type_or_generic())
 180     }
 181
 182     fn with_expression_parser<F, U>(&mut self, f: F) -> U
 183     where
 184         T: Clone,
 185         F: Fn(&mut ExpressionParser<'a, S, T>) -> U,
 186     {
 187         let mut expression_parser: ExpressionParser<S, T> = ExpressionParser::make(
 188             self.lexer.clone(),
 189             self.env.clone(),
 190             self.context.clone(),
 191             self.errors.clone(),
 192             self.sc.clone(),
 193         );
 194         let res = f(&mut expression_parser);
 195         self.continue_from(expression_parser);
 196         res
 197     }
 198
 199     fn parse_expression(&mut self) -> S::R {
 200         self.with_expression_parser(|p: &mut ExpressionParser<'a, S, T>| p.parse_expression())
 201     }
 202
 203     fn parse_compound_statement(&mut self) -> S::R {
 204         self.with_statement_parser(|p: &mut StatementParser<'a, S, T>| p.parse_compound_statement())
 205     }
 206
 207     fn parse_enumerator_list_opt(&mut self) -> S::R {
 208         // SPEC
 209         // enumerator-list:
 210         //   enumerator
 211         //   enumerator-list   enumerator
 212         //
 213         self.parse_terminated_list(|x: &mut Self| x.parse_enumerator(), TokenKind::RightBrace)
 214     }
 215
 216     fn parse_enum_declaration(&mut self, attrs: S::R) -> S::R {
 217         //
 218         // enum-declaration:
 219         //   attribute-specification-opt enum  name  enum-base  type-constraint-opt /
 220         //     {  enumerator-list-opt  }
 221         // enum-base:
 222         //   :  int
 223         //   :  string
 224         //
 225         // TODO: SPEC ERROR: The spec states that the only legal enum types
 226         // are "int" and "string", but Hack allows any type, and apparently
 227         // some of those are meaningful and desired.  Figure out what types
 228         // are actually legal and illegal as enum base types; put them in the
 229         // spec, and add an error pass that says when they are wrong.
 230         let enum_ = self.assert_token(TokenKind::Enum);
 231         let name = self.require_name();
 232         let colon = self.require_colon();
 233         let base =
 234             self.parse_type_specifier(false /* allow_var */, true /* allow_attr */);
 235         let enum_type = self.parse_type_constraint_opt();
 236         let (left_brace, enumerators, right_brace) =
 237             self.parse_braced_list(|x: &mut Self| x.parse_enumerator_list_opt());
 238         S!(
 239             make_enum_declaration,
 240             self,
 241             attrs,
 242             enum_,
 243             name,
 244             colon,
 245             base,
 246             enum_type,
 247             left_brace,
 248             enumerators,
 249             right_brace,
 250         )
 251     }
 252
 253     fn parse_record_field(&mut self) -> S::R {
 254         // SPEC
 255         //  record_field:
 256         //    record-constant : type field-initializer-opt,
 257         //  record-constant:
 258         //    name
 259         //  field-initializer:
 260         //    = expression
 261         let name = self.require_name_allow_non_reserved();
 262         let colon = self.require_colon();
 263         let field_type = self.parse_type_specifier(false, true);
 264         let init = self.parse_simple_initializer_opt();
 265         let comma = self.require_comma();
 266         S!(
 267             make_record_field,
 268             self,
 269             name,
 270             colon,
 271             field_type,
 272             init,
 273             comma
 274         )
 275     }
 276
 277     fn parse_record_fields(&mut self) -> S::R {
 278         // SPEC
 279         //  record-list:
 280         //    record-field
 281         //    record-list record-field
 282         self.parse_terminated_list(|x| x.parse_record_field(), TokenKind::RightBrace)
 283     }
 284
 285     fn parse_record_declaration(&mut self, attrs: S::R) -> S::R {
 286         // record-declaration:
 287         //   (abstract|final) record name { record-list }
 288         let modifier =
 289             self.require_token_one_of(&[TokenKind::Abstract, TokenKind::Final], Errors::error1037);
 290         let record = self.assert_token(TokenKind::RecordDec);
 291         let name = self.require_name();
 292         let (record_extends, record_extends_list) = self.parse_extends_opt();
 293         let (left_brace, record_fields, right_brace) =
 294             self.parse_braced_list(|x| x.parse_record_fields());
 295         S!(
 296             make_record_declaration,
 297             self,
 298             attrs,
 299             modifier,
 300             record,
 301             name,
 302             record_extends,
 303             record_extends_list,
 304             left_brace,
 305             record_fields,
 306             right_brace
 307         )
 308     }
 309
 310     pub fn parse_leading_markup_section(&mut self) -> Option<S::R> {
 311         let mut parser1 = self.clone();
 312         let (markup_section, has_suffix) =
 313             parser1.with_statement_parser(|p: &mut StatementParser<'a, S, T>| p.parse_header());
 314         // proceed successfully if we've consumed <?..., or dont need it
 315         // We purposefully ignore leading trivia before the <?hh, and handle
 316         // the error on a later pass
 317         if has_suffix {
 318             self.continue_from(parser1);
 319             Some(markup_section)
 320         } else {
 321             if self.lexer().source().length() > 0
 322                 && self.lexer().source().file_path().ends_with(".php")
 323             {
 324                 self.with_error(Errors::error1001);
 325             }
 326             None
 327         }
 328     }
 329
 330     fn parse_namespace_body(&mut self) -> S::R {
 331         match self.peek_token_kind() {
 332             TokenKind::Semicolon => {
 333                 let token = self.fetch_token();
 334                 S!(make_namespace_empty_body, self, token)
 335             }
 336             TokenKind::LeftBrace => {
 337                 let left = self.fetch_token();
 338                 let body = self.parse_terminated_list(
 339                     |x: &mut Self| x.parse_declaration(),
 340                     TokenKind::RightBrace,
 341                 );
 342                 let right = self.require_right_brace();
 343                 S!(make_namespace_body, self, left, body, right)
 344             }
 345             _ => {
 346                 // ERROR RECOVERY: return an inert namespace (one with all of its
 347                 // components 'missing'), and recover--without advancing the parser--
 348                 // back to the level that the namespace was declared in.
 349                 self.with_error(Errors::error1038);
 350                 let missing1 = S!(make_missing, self, self.pos());
 351                 let missing2 = S!(make_missing, self, self.pos());
 352                 let missing3 = S!(make_missing, self, self.pos());
 353                 S!(make_namespace_body, self, missing1, missing2, missing3)
 354             }
 355         }
 356     }
 357
 358     fn is_group_use(&self) -> bool {
 359         let mut parser = self.clone();
 360         // We want a heuristic to determine whether to parse the use clause as
 361         // a group use or normal use clause.  We distinguish the two by (1) whether
 362         // there is a namespace prefix -- in this case it is definitely a group use
 363         // clause -- or, if there is a name followed by a curly. That's illegal, but
 364         // we should give an informative error message about that.
 365         parser.assert_token(TokenKind::Use);
 366         parser.parse_namespace_use_kind_opt();
 367         let token = parser.next_token();
 368         match token.kind() {
 369             TokenKind::Backslash => {
 370                 let missing = S!(make_missing, parser, parser.pos());
 371                 let backslash = S!(make_token, parser, token);
 372                 let (_name, is_backslash) = parser.scan_qualified_name_extended(missing, backslash);
 373                 is_backslash || parser.peek_token_kind() == TokenKind::LeftBrace
 374             }
 375             TokenKind::Name => {
 376                 let token = S!(make_token, parser, token);
 377                 let roken_ref = &token as *const _;
 378                 let (name, is_backslash) = parser.scan_remaining_qualified_name_extended(token);
 379                 // Here we rely on the implementation details of
 380                 // scan_remaining_qualified_name_extended. It's returning
 381                 // *exactly* token if there is nothing except it in the name.
 382                 is_backslash && (&name as *const _ == roken_ref)
 383                     || parser.peek_token_kind() == TokenKind::LeftBrace
 384             }
 385             _ => false,
 386         }
 387     }
 388
 389     fn parse_namespace_use_kind_opt(&mut self) -> S::R {
 390         // SPEC
 391         // namespace-use-kind:
 392         //   namespace
 393         //   function
 394         //   const
 395         let mut parser1 = self.clone();
 396         let token = parser1.next_token();
 397         match token.kind() {
 398             TokenKind::Type | TokenKind::Namespace | TokenKind::Function | TokenKind::Const => {
 399                 self.continue_from(parser1);
 400                 S!(make_token, self, token)
 401             }
 402             _ => S!(make_missing, self, self.pos()),
 403         }
 404     }
 405
 406     fn parse_group_use(&mut self) -> S::R {
 407         // See below for grammar.
 408         let use_token = self.assert_token(TokenKind::Use);
 409         let use_kind = self.parse_namespace_use_kind_opt();
 410         // We already know that this is a name, qualified name, or prefix.
 411         // If this is not a prefix, it will be detected as an error in a later pass
 412         let prefix = self.scan_name_or_qualified_name();
 413         let (left, clauses, right) =
 414             self.parse_braced_comma_list_opt_allow_trailing(|x: &mut Self| {
 415                 x.parse_namespace_use_clause()
 416             });
 417         let semi = self.require_semicolon();
 418         S!(
 419             make_namespace_group_use_declaration,
 420             self,
 421             use_token,
 422             use_kind,
 423             prefix,
 424             left,
 425             clauses,
 426             right,
 427             semi,
 428         )
 429     }
 430
 431     fn parse_namespace_use_clause(&mut self) -> S::R {
 432         // SPEC
 433         // namespace-use-clause:
 434         //   qualified-name  namespace-aliasing-clauseopt
 435         // namespace-use-kind-clause:
 436         //   namespace-use-kind-opt qualified-name  namespace-aliasing-clauseopt
 437         // namespace-aliasing-clause:
 438         //   as  name
 439         //
 440         let use_kind = self.parse_namespace_use_kind_opt();
 441         let name = self.require_qualified_name();
 442         let (as_token, alias) = if self.peek_token_kind() == TokenKind::As {
 443             let as_token = self.next_token();
 444             let as_token = S!(make_token, self, as_token);
 445             let alias = self.require_name();
 446             (as_token, alias)
 447         } else {
 448             let missing1 = S!(make_missing, self, self.pos());
 449             let missing2 = S!(make_missing, self, self.pos());
 450             (missing1, missing2)
 451         };
 452         S!(
 453             make_namespace_use_clause,
 454             self,
 455             use_kind,
 456             name,
 457             as_token,
 458             alias
 459         )
 460     }
 461
 462     fn parse_namespace_use_declaration(&mut self) -> S::R {
 463         // SPEC
 464         // namespace-use-declaration:
 465         //   use namespace-use-kind-opt namespace-use-clauses  ;
 466         //   use namespace-use-kind namespace-name-as-a-prefix
 467         //     { namespace-use-clauses }  ;
 468         // use namespace-name-as-a-prefix { namespace-use-kind-clauses  }  ;
 469         //
 470         // TODO: Add the grammar for the namespace-use-clauses; ensure that it
 471         // indicates that trailing commas are allowed in the list.
 472         //
 473         // ERROR RECOVERY
 474         // In the "simple" format, the kind may only be specified up front.
 475         //
 476         // The grammar in the specification says that in the "group"
 477         // format, if the kind is specified up front then it may not
 478         // be specified in each clause. However, HHVM's parser disallows
 479         // the kind in each clause regardless of whether it is specified up front.
 480         // We will fix the specification to match HHVM.
 481         //
 482         // The grammar in the specification also says that in the "simple" format,
 483         // the kind may only be specified up front.  But HHVM allows the kind to
 484         // be specified in each clause.  Again, we will fix the specification to match
 485         // HHVM.
 486         //
 487         // TODO: Update the grammar comment above when the specification is fixed.
 488         // (This work is being tracked by spec work items 102, 103 and 104.)
 489         //
 490         // We do not enforce these rules here. Rather, we allow the kind to be anywhere,
 491         // and detect the errors in a later pass.
 492         if self.is_group_use() {
 493             self.parse_group_use()
 494         } else {
 495             let use_token = self.assert_token(TokenKind::Use);
 496             let use_kind = self.parse_namespace_use_kind_opt();
 497             let (clauses, _) = self.parse_comma_list_allow_trailing(
 498                 TokenKind::Semicolon,
 499                 Errors::error1004,
 500                 |x: &mut Self| x.parse_namespace_use_clause(),
 501             );
 502             let semi = self.require_semicolon();
 503             S!(
 504                 make_namespace_use_declaration,
 505                 self,
 506                 use_token,
 507                 use_kind,
 508                 clauses,
 509                 semi
 510             )
 511         }
 512     }
 513
 514     fn parse_namespace_declaration(&mut self) -> S::R {
 515         // SPEC
 516         // namespace-definition:
 517         //   namespace  namespace-name  ;
 518         //   namespace  namespace-name-opt  { declaration-list }
 519         //
 520         // TODO: An error case not caught by the parser that should be caught
 521         // in a later pass:
 522         // Qualified names are a superset of legal namespace names.
 523         let namespace_token = self.assert_token(TokenKind::Namespace);
 524         let name = match self.peek_token_kind() {
 525             TokenKind::Name => {
 526                 let token = self.next_token();
 527                 let token = S!(make_token, self, token);
 528                 self.scan_remaining_qualified_name(token)
 529             }
 530             TokenKind::LeftBrace => S!(make_missing, self, self.pos()),
 531             TokenKind::Semicolon => {
 532                 // ERROR RECOVERY Plainly the name is missing.
 533                 self.with_error(Errors::error1004);
 534                 S!(make_missing, self, self.pos())
 535             }
 536             _ =>
 537             // TODO: Death to PHPisms; keywords as namespace names
 538             {
 539                 self.require_name_allow_non_reserved()
 540             }
 541         };
 542         let body = self.parse_namespace_body();
 543         S!(
 544             make_namespace_declaration,
 545             self,
 546             namespace_token,
 547             name,
 548             body
 549         )
 550     }
 551
 552     pub fn parse_classish_declaration(&mut self, attribute_spec: S::R) -> S::R {
 553         let modifiers = self.parse_classish_modifiers();
 554         let token = self.parse_classish_token();
 555         let name = self.require_class_name();
 556         let generic_type_parameter_list = self.parse_generic_type_parameter_list_opt();
 557         let (classish_extends, classish_extends_list) = self.parse_extends_opt();
 558         let (classish_implements, classish_implements_list) = self.parse_classish_implements_opt();
 559         let classish_where_clause = self.parse_classish_where_clause_opt();
 560         let body = self.parse_classish_body();
 561         S!(
 562             make_classish_declaration,
 563             self,
 564             attribute_spec,
 565             modifiers,
 566             token,
 567             name,
 568             generic_type_parameter_list,
 569             classish_extends,
 570             classish_extends_list,
 571             classish_implements,
 572             classish_implements_list,
 573             classish_where_clause,
 574             body,
 575         )
 576     }
 577
 578     fn parse_classish_where_clause_opt(&mut self) -> S::R {
 579         if self.peek_token_kind() == TokenKind::Where {
 580             self.parse_where_clause()
 581         } else {
 582             S!(make_missing, self, self.pos())
 583         }
 584     }
 585
 586     fn parse_classish_implements_opt(&mut self) -> (S::R, S::R) {
 587         if self.peek_token_kind() != TokenKind::Implements {
 588             let missing1 = S!(make_missing, self, self.pos());
 589             let missing2 = S!(make_missing, self, self.pos());
 590             (missing1, missing2)
 591         } else {
 592             let implements_token = self.next_token();
 593             let implements_token = S!(make_token, self, implements_token);
 594             let implements_list = self.parse_special_type_list();
 595             (implements_token, implements_list)
 596         }
 597     }
 598
 599     fn parse_classish_modifiers(&mut self) -> S::R {
 600         let mut acc = vec![];
 601         loop {
 602             match self.peek_token_kind() {
 603                 TokenKind::Abstract | TokenKind::Final => {
 604                     // TODO(T25649779)
 605                     let token = self.next_token();
 606                     let token = S!(make_token, self, token);
 607                     acc.push(token);
 608                 }
 609                 _ => return S!(make_list, self, acc, self.pos()),
 610             }
 611         }
 612     }
 613
 614     fn parse_classish_token(&mut self) -> S::R {
 615         let spellcheck_tokens = vec![TokenKind::Class, TokenKind::Trait, TokenKind::Interface];
 616         let token_str = &self.current_token_text();
 617         let token_kind = self.peek_token_kind();
 618         match token_kind {
 619             TokenKind::Class | TokenKind::Trait | TokenKind::Interface => {
 620                 let token = self.next_token();
 621                 S!(make_token, self, token)
 622             }
 623             // Spellcheck case
 624             TokenKind::Name if Self::is_misspelled_from(&spellcheck_tokens, token_str) => {
 625                 // Default won't be used, since we already checked is_misspelled_from
 626                 let suggested_kind = Self::suggested_kind_from(&spellcheck_tokens, token_str)
 627                     .unwrap_or(TokenKind::Name);
 628                 self.skip_and_log_misspelled_token(suggested_kind);
 629                 S!(make_missing, self, self.pos())
 630             }
 631             _ => {
 632                 self.with_error(Errors::error1035);
 633                 S!(make_missing, self, self.pos())
 634             }
 635         }
 636     }
 637
 638     fn parse_special_type(&mut self) -> (S::R, bool) {
 639         let mut parser1 = self.clone();
 640         let token = parser1.next_xhp_class_name_or_other_token();
 641         match token.kind() {
 642             TokenKind::Comma => {
 643                 // ERROR RECOVERY. We expected a type but we got a comma.
 644                 // Give the error that we expected a type, not a name, even though
 645                 // not every type is legal here.
 646                 self.continue_from(parser1);
 647                 self.with_error(Errors::error1007);
 648                 let comma = S!(make_token, self, token);
 649                 let missing = S!(make_missing, self, self.pos());
 650                 let list_item = S!(make_list_item, self, missing, comma);
 651                 (list_item, false)
 652             }
 653             TokenKind::Backslash
 654             | TokenKind::Namespace
 655             | TokenKind::Name
 656             | TokenKind::XHPClassName => {
 657                 let item = self
 658                     .parse_type_specifier(false /* allow_var */, true /* allow_attr */);
 659                 let comma = self.optional_token(TokenKind::Comma);
 660                 let is_missing = comma.is_missing();
 661                 let list_item = S!(make_list_item, self, item, comma);
 662                 (list_item, is_missing)
 663             }
 664             TokenKind::Parent
 665             | TokenKind::Enum
 666             | TokenKind::RecordDec
 667             | TokenKind::Shape
 668             | TokenKind::SelfToken
 669                 if self.env.hhvm_compat_mode =>
 670             {
 671                 // HHVM allows these keywords here for some reason
 672                 let item = self.parse_simple_type_or_type_constant();
 673                 let comma = self.optional_token(TokenKind::Comma);
 674                 let is_missing = comma.is_missing();
 675                 let list_item = S!(make_list_item, self, item, comma);
 676                 (list_item, is_missing)
 677             }
 678             _ => {
 679                 // ERROR RECOVERY: We are expecting a type; give an error as above.
 680                 // Don't eat the offending token.
 681                 self.with_error(Errors::error1007);
 682                 let missing1 = S!(make_missing, self, self.pos());
 683                 let missing2 = S!(make_missing, self, self.pos());
 684                 let list_item = S!(make_list_item, self, missing1, missing2);
 685                 (list_item, true)
 686             }
 687         }
 688     }
 689
 690     fn parse_special_type_list(&mut self) -> S::R {
 691         // An extends / implements list is a comma-separated list of types, but
 692         // very special types; we want the types to consist of a name and an
 693         // optional generic type argument list.
 694         //
 695         // TODO: Can the type name be of the form "foo::bar"? Those do not
 696         // necessarily start with names. Investigate this.
 697         //
 698         // Normally we'd use one of the separated list helpers, but there is no
 699         // specific end token we could use to detect the end of the list, and we
 700         // want to bail out if we get something that is not a type of the right form.
 701         // So we have custom logic here.
 702         //
 703         // TODO: This is one of the rare cases in Hack where a comma-separated list
 704         // may not have a trailing comma. Is that desirable, or was that an
 705         // oversight when the trailing comma rules were added?  If possible we
 706         // should keep the rule as-is, and disallow the trailing comma; it makes
 707         // parsing and error recovery easier.
 708         let mut items = vec![];
 709         loop {
 710             let (item, is_missing) = self.parse_special_type();
 711
 712             items.push(item);
 713             if is_missing {
 714                 break;
 715             }
 716         }
 717         S!(make_list, self, items, self.pos())
 718     }
 719
 720     fn parse_extends_opt(&mut self) -> (S::R, S::R) {
 721         let token_kind = self.peek_token_kind();
 722         if token_kind != TokenKind::Extends {
 723             let missing1 = S!(make_missing, self, self.pos());
 724             let missing2 = S!(make_missing, self, self.pos());
 725             (missing1, missing2)
 726         } else {
 727             let token = self.next_token();
 728             let extends_token = S!(make_token, self, token);
 729             let extends_list = self.parse_special_type_list();
 730             (extends_token, extends_list)
 731         }
 732     }
 733
 734     fn parse_classish_body(&mut self) -> S::R {
 735         let left_brace_token = self.require_left_brace();
 736         let classish_element_list = self.parse_classish_element_list_opt();
 737         let right_brace_token = self.require_right_brace();
 738         S!(
 739             make_classish_body,
 740             self,
 741             left_brace_token,
 742             classish_element_list,
 743             right_brace_token
 744         )
 745     }
 746
 747     fn parse_classish_element_list_opt(&mut self) -> S::R {
 748         // TODO: ERROR RECOVERY: consider bailing if the token cannot possibly
 749         // start a classish element.
 750         // ERROR RECOVERY: we're in the body of a classish, so we add visibility
 751         // modifiers to our context.
 752         self.expect_in_new_scope(ExpectedTokens::Visibility);
 753         let element_list = self.parse_terminated_list(
 754             |x: &mut Self| x.parse_classish_element(),
 755             TokenKind::RightBrace,
 756         );
 757         self.pop_scope(ExpectedTokens::Visibility);
 758         element_list
 759     }
 760
 761     fn parse_xhp_children_paren(&mut self) -> S::R {
 762         // SPEC (Draft)
 763         // ( xhp-children-expressions )
 764         //
 765         // xhp-children-expressions:
 766         //   xhp-children-expression
 767         //   xhp-children-expressions , xhp-children-expression
 768         //
 769         // TODO: The parenthesized list of children expressions is NOT allowed
 770         // to be comma-terminated. Is this intentional? It is inconsistent with
 771         // practice throughout the rest of Hack. There is no syntactic difficulty
 772         // in allowing a comma before the close paren. Consider allowing it.
 773         let (left, exprs, right) =
 774             self.parse_parenthesized_comma_list(|x: &mut Self| x.parse_xhp_children_expression());
 775         S!(
 776             make_xhp_children_parenthesized_list,
 777             self,
 778             left,
 779             exprs,
 780             right
 781         )
 782     }
 783
 784     fn parse_xhp_children_term(&mut self) -> S::R {
 785         // SPEC (Draft)
 786         // xhp-children-term:
 787         // ( xhp-children-expressions ) trailing-opt
 788         // name trailing-opt
 789         // xhp-class-name trailing-opt
 790         // xhp-category-name trailing-opt
 791         // trailing: * ? +
 792         //
 793         // Note that there may be only zero or one trailing unary operator.
 794         // "foo*?" is not a legal xhp child expression.
 795         //
 796         let mut parser1 = self.clone();
 797         let token = parser1.next_xhp_children_name_or_other();
 798         let kind = token.kind();
 799         let name = S!(make_token, parser1, token);
 800         match kind {
 801             TokenKind::Name | TokenKind::XHPClassName | TokenKind::XHPCategoryName => {
 802                 self.continue_from(parser1);
 803                 self.parse_xhp_children_trailing(name)
 804             }
 805             TokenKind::LeftParen => {
 806                 let term = self.parse_xhp_children_paren();
 807                 self.parse_xhp_children_trailing(term)
 808             }
 809             _ => {
 810                 // ERROR RECOVERY: Eat the offending token, keep going.
 811                 self.with_error(Errors::error1053);
 812                 name
 813             }
 814         }
 815     }
 816
 817     fn parse_xhp_children_trailing(&mut self, term: S::R) -> S::R {
 818         let token_kind = self.peek_token_kind();
 819         match token_kind {
 820             TokenKind::Star | TokenKind::Plus | TokenKind::Question => {
 821                 let token = self.next_token();
 822                 let token = S!(make_token, self, token);
 823                 S!(make_postfix_unary_expression, self, term, token)
 824             }
 825             _ => term,
 826         }
 827     }
 828
 829     fn parse_xhp_children_bar(&mut self, left: S::R) -> S::R {
 830         let token_kind = self.peek_token_kind();
 831         match token_kind {
 832             TokenKind::Bar => {
 833                 let token = self.next_token();
 834                 let token = S!(make_token, self, token);
 835                 let right = self.parse_xhp_children_term();
 836                 let result = S!(make_binary_expression, self, left, token, right);
 837                 self.parse_xhp_children_bar(result)
 838             }
 839             _ => left,
 840         }
 841     }
 842
 843     fn parse_xhp_children_expression(&mut self) -> S::R {
 844         // SPEC (Draft)
 845         // xhp-children-expression:
 846         //   xhp-children-term
 847         //   xhp-children-expression | xhp-children-term
 848         //
 849         // Note that the bar operator is left-associative. (Not that it matters
 850         // semantically.
 851         let term = self.parse_xhp_children_term();
 852         self.parse_xhp_children_bar(term)
 853     }
 854
 855     fn parse_xhp_children_declaration(&mut self) -> S::R {
 856         // SPEC (Draft)
 857         // xhp-children-declaration:
 858         //   children empty ;
 859         //   children xhp-children-expression ;
 860         let children = self.assert_token(TokenKind::Children);
 861         let token_kind = self.peek_token_kind();
 862         let expr = match token_kind {
 863             TokenKind::Empty => {
 864                 let token = self.next_token();
 865                 S!(make_token, self, token)
 866             }
 867             _ => self.parse_xhp_children_expression(),
 868         };
 869         let semi = self.require_semicolon();
 870         S!(make_xhp_children_declaration, self, children, expr, semi)
 871     }
 872
 873     fn parse_xhp_category(&mut self) -> S::R {
 874         let token = self.next_xhp_category_name();
 875         let token_kind = token.kind();
 876         let category = S!(make_token, self, token);
 877         match token_kind {
 878             TokenKind::XHPCategoryName => category,
 879             _ => {
 880                 self.with_error(Errors::error1052);
 881                 category
 882             }
 883         }
 884     }
 885
 886     fn parse_xhp_type_specifier(&mut self) -> S::R {
 887         // SPEC (Draft)
 888         // xhp-type-specifier:
 889         //   enum { xhp-attribute-enum-list  ,-opt  }
 890         //   type-specifier
 891         //
 892         // The list of enum values must have at least one value and can be
 893         // comma-terminated.
 894         //
 895         // xhp-enum-list:
 896         //   xhp-attribute-enum-value
 897         //   xhp-enum-list , xhp-attribute-enum-value
 898         //
 899         // xhp-attribute-enum-value:
 900         //   any integer literal
 901         //   any single-quoted-string literal
 902         //   any double-quoted-string literal
 903         //
 904         // TODO: What are the semantics of encapsulated expressions in double-quoted
 905         // string literals here?
 906         // ERROR RECOVERY: We parse any expressions here;
 907         // TODO: give an error in a later pass if the expressions are not literals.
 908         // (This work is tracked by task T21175355)
 909         //
 910         // An empty list is illegal, but we allow it here and give an error in
 911         // a later pass.
 912         let mut parser1 = self.clone();
 913         let token = parser1.next_token();
 914         let (token, optional) = match token.kind() {
 915             TokenKind::Question => {
 916                 let enum_token = parser1.next_token();
 917                 let token = S!(make_token, parser1, token);
 918                 (enum_token, token)
 919             }
 920             _ => {
 921                 let missing = S!(make_missing, parser1, self.pos());
 922                 (token, missing)
 923             }
 924         };
 925         match token.kind() {
 926             TokenKind::Enum => {
 927                 self.continue_from(parser1);
 928                 let enum_token = S!(make_token, self, token);
 929                 let (left_brace, values, right_brace) = self
 930                     .parse_braced_comma_list_opt_allow_trailing(|x: &mut Self| {
 931                         x.parse_expression()
 932                     });
 933                 S!(
 934                     make_xhp_enum_type,
 935                     self,
 936                     optional,
 937                     enum_token,
 938                     left_brace,
 939                     values,
 940                     right_brace
 941                 )
 942             }
 943             _ => self.parse_type_specifier(true, true),
 944         }
 945     }
 946
 947     fn parse_xhp_required_opt(&mut self) -> S::R {
 948         // SPEC (Draft)
 949         // xhp-required :
 950         //   @  (required | lateinit)
 951         //
 952         // Note that these are two tokens. They can have whitespace between them.
 953         if self.peek_token_kind() == TokenKind::At {
 954             let at = self.assert_token(TokenKind::At);
 955             let req_kind = self.next_token();
 956             let kind = req_kind.kind();
 957             let req = S!(make_token, self, req_kind);
 958             match kind {
 959                 TokenKind::Required => S!(make_xhp_required, self, at, req),
 960                 TokenKind::Lateinit => S!(make_xhp_lateinit, self, at, req),
 961                 _ => {
 962                     self.with_error(Errors::error1051);
 963                     S!(make_missing, self, self.pos())
 964                 }
 965             }
 966         } else {
 967             S!(make_missing, self, self.pos())
 968         }
 969     }
 970
 971     fn parse_xhp_class_attribute_typed(&mut self) -> S::R {
 972         // xhp-type-specifier xhp-name initializer-opt xhp-required-opt
 973         let ty = self.parse_xhp_type_specifier();
 974         let name = self.require_xhp_name();
 975         let init = self.parse_simple_initializer_opt();
 976         let req = self.parse_xhp_required_opt();
 977         S!(make_xhp_class_attribute, self, ty, name, init, req)
 978     }
 979
 980     fn parse_xhp_category_declaration(&mut self) -> S::R {
 981         // SPEC (Draft)
 982         // xhp-category-declaration:
 983         //   category xhp-category-list ,-opt  ;
 984         //
 985         // xhp-category-list:
 986         //   xhp-category-name
 987         //   xhp-category-list  ,  xhp-category-name
 988         let category = self.assert_token(TokenKind::Category);
 989         let (items, _) = self.parse_comma_list_allow_trailing(
 990             TokenKind::Semicolon,
 991             Errors::error1052,
 992             |x: &mut Self| x.parse_xhp_category(),
 993         );
 994         let semi = self.require_semicolon();
 995         S!(make_xhp_category_declaration, self, category, items, semi)
 996     }
 997
 998     fn parse_xhp_class_attribute(&mut self) -> S::R {
 999         // SPEC (Draft)
1000         // xhp-attribute-declaration:
1001         //   xhp-class-name
1002         //   xhp-type-specifier xhp-name initializer-opt xhp-required-opt
1003         //
1004         // ERROR RECOVERY:
1005         // The xhp type specifier could be an xhp class name. To disambiguate we peek
1006         // ahead a token; if it's a comma or semi, we're done. If not, then we assume
1007         // that we are in the more complex case.
1008         if self.is_next_xhp_class_name() {
1009             let mut parser1 = self.clone();
1010             let class_name = parser1.require_class_name();
1011             match parser1.peek_token_kind() {
1012                 TokenKind::Comma | TokenKind::Semicolon => {
1013                     self.continue_from(parser1);
1014                     let type_specifier = S!(make_simple_type_specifier, self, class_name);
1015                     S!(make_xhp_simple_class_attribute, self, type_specifier)
1016                 }
1017                 _ => self.parse_xhp_class_attribute_typed(),
1018             }
1019         } else {
1020             self.parse_xhp_class_attribute_typed()
1021         }
1022     }
1023
1024     fn parse_xhp_class_attribute_declaration(&mut self) -> S::R {
1025         // SPEC: (Draft)
1026         // xhp-class-attribute-declaration :
1027         //   attribute xhp-attribute-declaration-list ;
1028         //
1029         // xhp-attribute-declaration-list:
1030         //   xhp-attribute-declaration
1031         //   xhp-attribute-declaration-list , xhp-attribute-declaration
1032         //
1033         // TODO: The list of attributes may NOT be terminated with a trailing comma
1034         // before the semicolon. This is inconsistent with the rest of Hack.
1035         // Allowing a comma before the semi does not introduce any syntactic
1036         // difficulty; consider allowing it.
1037         let attr_token = self.assert_token(TokenKind::Attribute);
1038         // TODO: Better error message.
1039         let attrs =
1040             self.parse_comma_list(TokenKind::Semicolon, Errors::error1004, |x: &mut Self| {
1041                 x.parse_xhp_class_attribute()
1042             });
1043         let semi = self.require_semicolon();
1044         S!(
1045             make_xhp_class_attribute_declaration,
1046             self,
1047             attr_token,
1048             attrs,
1049             semi
1050         )
1051     }
1052
1053     fn parse_qualified_name_type(&mut self) -> S::R {
1054         // Here we're parsing a name followed by an optional generic type
1055         // argument list; if we don't have a name, give an error.
1056         match self.peek_token_kind() {
1057             TokenKind::Backslash | TokenKind::Name => self.parse_simple_type_or_generic(),
1058             _ => self.require_qualified_name(),
1059         }
1060     }
1061
1062     fn parse_qualified_name_type_opt(&mut self) -> S::R {
1063         // Here we're parsing a name followed by an optional generic type
1064         // argument list; if we don't have a name, give an error.
1065         match self.peek_token_kind() {
1066             TokenKind::Backslash | TokenKind::Construct | TokenKind::Name => {
1067                 self.parse_simple_type_or_generic()
1068             }
1069             _ => S!(make_missing, self, self.pos()),
1070         }
1071     }
1072
1073     fn parse_require_clause(&mut self) -> S::R {
1074         // SPEC
1075         // require-extends-clause:
1076         //   require  extends  qualified-name  ;
1077         //
1078         // require-implements-clause:
1079         //   require  implements  qualified-name  ;
1080         //
1081         // We must also parse "require extends :foo;"
1082         // TODO: What about "require extends :foo<int>;" ?
1083         // TODO: The spec is incomplete; we need to be able to parse
1084         // require extends Foo<int>;
1085         // (This work is being tracked by spec issue 105.)
1086         // TODO: Check whether we also need to handle
1087         // require extends foo::bar
1088         // and so on.
1089         //
1090         // ERROR RECOVERY: Detect if the implements/extends, name and semi are
1091         // missing.
1092         let req = self.assert_token(TokenKind::Require);
1093         let token_kind = self.peek_token_kind();
1094         let req_kind = match token_kind {
1095             TokenKind::Implements | TokenKind::Extends => {
1096                 let req_kind_token = self.next_token();
1097                 S!(make_token, self, req_kind_token)
1098             }
1099             _ => {
1100                 self.with_error(Errors::error1045);
1101                 S!(make_missing, self, self.pos())
1102             }
1103         };
1104         let name = if self.is_next_xhp_class_name() {
1105             self.parse_simple_type_or_generic()
1106         } else {
1107             self.parse_qualified_name_type()
1108         };
1109         let semi = self.require_semicolon();
1110         S!(make_require_clause, self, req, req_kind, name, semi)
1111     }
1112
1113     // This duplicates work from parse_methodish_or_const_or_type_const,
1114     // but this function is only invoked after an attribute spec, while
1115     // parse_methodish_or_const_or_type_const is called after a modifier.
1116     // Having this function prevents constants from having attributes as
1117     // this cannot be checked in parser_errors as there is no field in constant
1118     // declaration to store 'attributes'.
1119     fn parse_methodish_or_property_or_type_constant(&mut self, attribute_spec: S::R) -> S::R {
1120         let mut parser1 = self.clone();
1121         let modifiers = parser1.parse_modifiers();
1122         let current_token_kind = parser1.peek_token_kind();
1123         let next_token = parser1.peek_token_with_lookahead(1);
1124         let next_token_kind = next_token.kind();
1125         match (current_token_kind, next_token_kind) {
1126             (TokenKind::Const, TokenKind::Type) => {
1127                 self.continue_from(parser1);
1128                 let const_ = self.assert_token(TokenKind::Const);
1129                 self.parse_type_const_declaration(attribute_spec, modifiers, const_)
1130             }
1131             _ => self.parse_methodish_or_property(attribute_spec),
1132         }
1133     }
1134
1135     fn has_leading_trivia(token: &S::Token, kind: TriviaKind) -> bool {
1136         token.leading().iter().any(|x| x.kind() == kind)
1137     }
1138
1139     fn parse_methodish_or_property(&mut self, attribute_spec: S::R) -> S::R {
1140         let modifiers = self.parse_modifiers();
1141         // ERROR RECOVERY: match against two tokens, because if one token is
1142         // in error but the next isn't, then it's likely that the user is
1143         // simply still typing. Throw an error on what's being typed, then eat
1144         // it and keep going.
1145         let current_token_kind = self.peek_token_kind();
1146         let next_token = self.peek_token_with_lookahead(1);
1147         let next_token_kind = next_token.kind();
1148         match (current_token_kind, next_token_kind) {
1149             // Detected the usual start to a method, so continue parsing as method.
1150             (TokenKind::Async, _) | (TokenKind::Coroutine, _) | (TokenKind::Function, _) => {
1151                 self.parse_methodish(attribute_spec, modifiers)
1152             }
1153             (TokenKind::LeftParen, _) => self.parse_property_declaration(attribute_spec, modifiers),
1154
1155             // We encountered one unexpected token, but the next still indicates that
1156             // we should be parsing a methodish. Throw an error, process the token
1157             // as an extra, and keep going.
1158             (_, TokenKind::Async) | (_, TokenKind::Coroutine) | (_, TokenKind::Function)
1159                 if !(Self::has_leading_trivia(&next_token, TriviaKind::EndOfLine)) =>
1160             {
1161                 self.with_error_on_whole_token(Errors::error1056);
1162                 self.skip_and_log_unexpected_token(false);
1163                 self.parse_methodish(attribute_spec, modifiers)
1164             }
1165             // Otherwise, continue parsing as a property (which might be a lambda).
1166             _ => self.parse_property_declaration(attribute_spec, modifiers),
1167         }
1168     }
1169
1170     fn parse_trait_use_precedence_item(&mut self, name: S::R) -> S::R {
1171         let keyword = self.assert_token(TokenKind::Insteadof);
1172         let removed_names = self.parse_trait_name_list(|x: TokenKind| x == TokenKind::Semicolon);
1173         S!(
1174             make_trait_use_precedence_item,
1175             self,
1176             name,
1177             keyword,
1178             removed_names
1179         )
1180     }
1181
1182     fn parse_trait_use_alias_item(&mut self, aliasing_name: S::R) -> S::R {
1183         let keyword = self.require_token(TokenKind::As, Errors::expected_as_or_insteadof);
1184         let modifiers = self.parse_modifiers();
1185         let aliased_name = self.parse_qualified_name_type_opt();
1186         S!(
1187             make_trait_use_alias_item,
1188             self,
1189             aliasing_name,
1190             keyword,
1191             modifiers,
1192             aliased_name
1193         )
1194     }
1195
1196     fn parse_trait_use_conflict_resolution_item(&mut self) -> S::R {
1197         let qualifier = self.parse_qualified_name_type();
1198         let name = if self.peek_token_kind() == TokenKind::ColonColon {
1199             // scope resolution expression case
1200             let cc_token = self.require_coloncolon();
1201             let name = self
1202                 .require_token_one_of(&[TokenKind::Name, TokenKind::Construct], Errors::error1004);
1203             S!(
1204                 make_scope_resolution_expression,
1205                 self,
1206                 qualifier,
1207                 cc_token,
1208                 name
1209             )
1210         } else {
1211             // plain qualified name case
1212             qualifier
1213         };
1214         match self.peek_token_kind() {
1215             TokenKind::Insteadof => self.parse_trait_use_precedence_item(name),
1216             TokenKind::As | _ => self.parse_trait_use_alias_item(name),
1217         }
1218     }
1219
1220     // SPEC:
1221     // trait-use-conflict-resolution:
1222     //   use trait-name-list  {  trait-use-conflict-resolution-list  }
1223     //
1224     // trait-use-conflict-resolution-list:
1225     //   trait-use-conflict-resolution-item
1226     //   trait-use-conflict-resolution-item  trait-use-conflict-resolution-list
1227     //
1228     // trait-use-conflict-resolution-item:
1229     //   trait-use-alias-item
1230     //   trait-use-precedence-item
1231     //
1232     // trait-use-alias-item:
1233     //   trait-use-conflict-resolution-item-name  as  name;
1234     //   trait-use-conflict-resolution-item-name  as  visibility-modifier  name;
1235     //   trait-use-conflict-resolution-item-name  as  visibility-modifier;
1236     //
1237     // trait-use-precedence-item:
1238     //   scope-resolution-expression  insteadof  trait-name-list
1239     //
1240     // trait-use-conflict-resolution-item-name:
1241     //   qualified-name
1242     //   scope-resolution-expression
1243     fn parse_trait_use_conflict_resolution(
1244         &mut self,
1245         use_token: S::R,
1246         trait_name_list: S::R,
1247     ) -> S::R {
1248         let left_brace = self.assert_token(TokenKind::LeftBrace);
1249         let clauses = self.parse_separated_list_opt(
1250             TokenKind::Semicolon,
1251             SeparatedListKind::TrailingAllowed,
1252             TokenKind::RightBrace,
1253             Errors::error1004,
1254             |x: &mut Self| x.parse_trait_use_conflict_resolution_item(),
1255         );
1256         let right_brace = self.require_token(TokenKind::RightBrace, Errors::error1006);
1257         S!(
1258             make_trait_use_conflict_resolution,
1259             self,
1260             use_token,
1261             trait_name_list,
1262             left_brace,
1263             clauses,
1264             right_brace,
1265         )
1266     }
1267
1268     // SPEC:
1269     // trait-use-clause:
1270     //   use  trait-name-list  ;
1271     //
1272     // trait-name-list:
1273     //   qualified-name  generic-type-parameter-listopt
1274     //   trait-name-list  ,  qualified-name  generic-type-parameter-listopt
1275     fn parse_trait_name_list<P>(&mut self, predicate: P) -> S::R
1276     where
1277         P: Fn(TokenKind) -> bool,
1278     {
1279         let (items, _) = self.parse_separated_list_predicate(
1280             TokenKind::Comma,
1281             SeparatedListKind::NoTrailing,
1282             predicate,
1283             Errors::error1004,
1284             |x: &mut Self| x.parse_qualified_name_type(),
1285         );
1286         items
1287     }
1288
1289     fn parse_trait_use(&mut self) -> S::R {
1290         let use_token = self.assert_token(TokenKind::Use);
1291         let trait_name_list =
1292             self.parse_trait_name_list(|x| x == TokenKind::Semicolon || x == TokenKind::LeftBrace);
1293         if self.peek_token_kind() == TokenKind::LeftBrace {
1294             self.parse_trait_use_conflict_resolution(use_token, trait_name_list)
1295         } else {
1296             let semi = self.require_semicolon();
1297             S!(make_trait_use, self, use_token, trait_name_list, semi)
1298         }
1299     }
1300
1301     fn parse_property_declaration(&mut self, attribute_spec: S::R, modifiers: S::R) -> S::R {
1302         // SPEC:
1303         // property-declaration:
1304         //   attribute-spec-opt  property-modifier  type-specifier
1305         //   property-declarator-list  ;
1306         //
1307         // property-declarator-list:
1308         //   property-declarator
1309         //   property-declarator-list  ,  property-declarator
1310         //
1311         // The type specifier is optional in non-strict mode and required in
1312         // strict mode. We give an error in a later pass.
1313         let prop_type = match self.peek_token_kind() {
1314             TokenKind::Variable => S!(make_missing, self, self.pos()),
1315             _ => self.parse_type_specifier(false /* allow_var */, false /* allow_attr */),
1316         };
1317         let decls =
1318             self.parse_comma_list(TokenKind::Semicolon, Errors::error1008, |x: &mut Self| {
1319                 x.parse_property_declarator()
1320             });
1321         let semi = self.require_semicolon();
1322         S!(
1323             make_property_declaration,
1324             self,
1325             attribute_spec,
1326             modifiers,
1327             prop_type,
1328             decls,
1329             semi
1330         )
1331     }
1332
1333     fn parse_property_declarator(&mut self) -> S::R {
1334         // SPEC:
1335         // property-declarator:
1336         //   variable-name  property-initializer-opt
1337         // property-initializer:
1338         //   =  expression
1339         let name = self.require_variable();
1340         let simple_init = self.parse_simple_initializer_opt();
1341         S!(make_property_declarator, self, name, simple_init)
1342     }
1343
1344     fn is_type_in_const(&self) -> bool {
1345         let mut parser1 = self.clone();
1346         let _ = parser1.parse_type_specifier(false, true);
1347         let _ = parser1.require_name_allow_all_keywords();
1348         self.errors.len() == parser1.errors.len()
1349     }
1350
1351     // SPEC:
1352     // const-declaration:
1353     //   abstract_opt  const  type-specifier_opt  constant-declarator-list  ;
1354     //   visibility  const  type-specifier_opt  constant-declarator-list  ;
1355     // constant-declarator-list:
1356     //   constant-declarator
1357     //   constant-declarator-list  ,  constant-declarator
1358     // constant-declarator:
1359     //   name  constant-initializer_opt
1360     // constant-initializer:
1361     //   =  const-expression
1362     fn parse_const_declaration(&mut self, modifiers: S::R, const_: S::R) -> S::R {
1363         let type_spec = if self.is_type_in_const() {
1364             self.parse_type_specifier(/* allow_var = */ false, /* allow_attr = */ true)
1365         } else {
1366             S!(make_missing, self, self.pos())
1367         };
1368
1369         let const_list =
1370             self.parse_comma_list(TokenKind::Semicolon, Errors::error1004, |x: &mut Self| {
1371                 x.parse_constant_declarator()
1372             });
1373         let semi = self.require_semicolon();
1374         S!(
1375             make_const_declaration,
1376             self,
1377             modifiers,
1378             const_,
1379             type_spec,
1380             const_list,
1381             semi
1382         )
1383     }
1384
1385     fn parse_constant_declarator(&mut self) -> S::R {
1386         // TODO: We allow const names to be keywords here; in particular we
1387         // require that const string TRUE = "true"; be legal.  Likely this
1388         // should be more strict. What are the rules for which keywords are
1389         // legal constant names and which are not?
1390         // Note that if this logic is changed, it should be changed in
1391         // is_type_in_const above as well.
1392         //
1393         // This permits abstract variables to have an initializer, and vice-versa.
1394         // This is deliberate, and those errors will be detected after the syntax
1395         // tree is created.
1396         let const_name = self.require_name_allow_all_keywords();
1397         let initializer_ = self.parse_simple_initializer_opt();
1398         S!(make_constant_declarator, self, const_name, initializer_)
1399     }
1400
1401     // SPEC:
1402     // type-constant-declaration:
1403     //   abstract-type-constant-declaration
1404     //   concrete-type-constant-declaration
1405     // abstract-type-constant-declaration:
1406     //   abstract  const  type  name  type-constraintopt  ;
1407     // concrete-type-constant-declaration:
1408     //   const  type  name  type-constraintopt  =  type-specifier  ;
1409     //
1410     // ERROR RECOVERY:
1411     //
1412     // An abstract type constant may only occur in an interface or an abstract
1413     // class. We allow that to be parsed here, and the type checker detects the
1414     // error.
1415     // CONSIDER: We could detect this error in a post-parse pass; it is entirely
1416     // syntactic.  Consider moving the error detection out of the type checker.
1417     //
1418     // An interface may not contain a non-abstract type constant that has a
1419     // type constraint.  We allow that to be parsed here, and the type checker
1420     // detects the error.
1421     // CONSIDER: We could detect this error in a post-parse pass; it is entirely
1422     // syntactic.  Consider moving the error detection out of the type checker.
1423     fn parse_type_const_declaration(
1424         &mut self,
1425         attributes: S::R,
1426         modifiers: S::R,
1427         const_: S::R,
1428     ) -> S::R {
1429         let type_token = self.assert_token(TokenKind::Type);
1430         let name = self.require_name_allow_non_reserved();
1431         let generic_type_parameter_list = self.parse_generic_type_parameter_list_opt();
1432         let type_constraint = self.parse_type_constraint_opt();
1433         let (equal_token, type_specifier) = if self.peek_token_kind() == TokenKind::Equal {
1434             let equal_token = self.assert_token(TokenKind::Equal);
1435             let type_spec = self
1436                 .parse_type_specifier(/* allow_var = */ false, /* allow_attr = */ true);
1437             (equal_token, type_spec)
1438         } else {
1439             let missing1 = S!(make_missing, self, self.pos());
1440             let missing2 = S!(make_missing, self, self.pos());
1441             (missing1, missing2)
1442         };
1443         let semicolon = self.require_semicolon();
1444         S!(
1445             make_type_const_declaration,
1446             self,
1447             attributes,
1448             modifiers,
1449             const_,
1450             type_token,
1451             name,
1452             generic_type_parameter_list,
1453             type_constraint,
1454             equal_token,
1455             type_specifier,
1456             semicolon,
1457         )
1458     }
1459
1460     // SPEC:
1461     // attribute_specification :=
1462     //   attribute_list
1463     //   old_attribute_specification
1464     // attribute_list :=
1465     //   attribute
1466     //   attribute_list attribute
1467     // attribute := @ attribute_name attribute_value_list_opt
1468     // old_attribute_specification := << old_attribute_list >>
1469     // old_attribute_list :=
1470     //   old_attribute
1471     //   old_attribute_list , old_attribute
1472     // old_attribute := attribute_name attribute_value_list_opt
1473     // attribute_name := name
1474     // attribute_value_list := ( attribute_values_opt )
1475     // attribute_values :=
1476     //   attribute_value
1477     //   attribute_values , attribute_value
1478     // attribute_value := expression
1479     //
1480     // TODO: The list of attrs can have a trailing comma. Update the spec.
1481     // TODO: The list of values can have a trailing comma. Update the spec.
1482     // (Both these work items are tracked by spec issue 106.)
1483     pub fn parse_old_attribute_specification_opt(&mut self) -> S::R {
1484         if self.peek_token_kind() == TokenKind::LessThanLessThan {
1485             let (left, items, right) =
1486                 self.parse_double_angled_comma_list_allow_trailing(|x: &mut Self| {
1487                     x.parse_old_attribute()
1488                 });
1489             S!(make_old_attribute_specification, self, left, items, right)
1490         } else {
1491             S!(make_missing, self, self.pos())
1492         }
1493     }
1494
1495     fn parse_file_attribute_specification_opt(&mut self) -> S::R {
1496         if self.peek_token_kind() == TokenKind::LessThanLessThan {
1497             let left = self.assert_token(TokenKind::LessThanLessThan);
1498             let keyword = self.assert_token(TokenKind::File);
1499             let colon = self.require_colon();
1500             let (items, _) = self.parse_comma_list_allow_trailing(
1501                 TokenKind::GreaterThanGreaterThan,
1502                 Errors::expected_user_attribute,
1503                 |x: &mut Self| x.parse_old_attribute(),
1504             );
1505             let right = self.require_token(TokenKind::GreaterThanGreaterThan, Errors::error1029);
1506             S!(
1507                 make_file_attribute_specification,
1508                 self,
1509                 left,
1510                 keyword,
1511                 colon,
1512                 items,
1513                 right
1514             )
1515         } else {
1516             S!(make_missing, self, self.pos())
1517         }
1518     }
1519
1520     fn parse_return_type_hint_opt(&mut self) -> (S::R, S::R) {
1521         let token_kind = self.peek_token_kind();
1522         if token_kind == TokenKind::Colon {
1523             let token = self.next_token();
1524             let colon_token = S!(make_token, self, token);
1525             let return_type =
1526                 self.with_type_parser(|p: &mut TypeParser<'a, S, T>| p.parse_return_type());
1527             (colon_token, return_type)
1528         } else {
1529             let missing1 = S!(make_missing, self, self.pos());
1530             let missing2 = S!(make_missing, self, self.pos());
1531             (missing1, missing2)
1532         }
1533     }
1534
1535     pub fn parse_parameter_list_opt(&mut self) -> (S::R, S::R, S::R) {
1536         // SPEC
1537         // TODO: The specification is wrong in several respects concerning
1538         // variadic parameters. Variadic parameters are permitted to have a
1539         // type and name but this is not mentioned in the spec. And variadic
1540         // parameters are not mentioned at all in the grammar for constructor
1541         // parameter lists.  (This is tracked by spec issue 107.)
1542         //
1543         // parameter-list:
1544         //   variadic-parameter
1545         //   parameter-declaration-list
1546         //   parameter-declaration-list  ,
1547         //   parameter-declaration-list  ,  variadic-parameter
1548         //
1549         // parameter-declaration-list:
1550         //   parameter-declaration
1551         //   parameter-declaration-list  ,  parameter-declaration
1552         //
1553         // variadic-parameter:
1554         //   ...
1555         //   attribute-specification-opt visiblity-modifier-opt type-specifier \
1556         //     ...  variable-name
1557         //
1558         // This function parses the parens as well.
1559         // ERROR RECOVERY: We allow variadic parameters in all positions; a later
1560         // pass gives an error if a variadic parameter is in an incorrect position
1561         // or followed by a trailing comma, or if the parameter has a
1562         // default value.
1563         self.parse_parenthesized_comma_list_opt_allow_trailing(|x: &mut Self| x.parse_parameter())
1564     }
1565
1566     fn parse_parameter(&mut self) -> S::R {
1567         let mut parser1 = self.clone();
1568         let token = parser1.next_token();
1569         match token.kind() {
1570             TokenKind::DotDotDot => {
1571                 let next_kind = parser1.peek_token_kind();
1572                 if next_kind == TokenKind::Variable {
1573                     self.parse_parameter_declaration()
1574                 } else {
1575                     let missing1 = S!(make_missing, parser1, self.pos());
1576                     let missing2 = S!(make_missing, parser1, self.pos());
1577                     self.continue_from(parser1);
1578                     let token = S!(make_token, self, token);
1579                     S!(make_variadic_parameter, self, missing1, missing2, token)
1580                 }
1581             }
1582             _ => self.parse_parameter_declaration(),
1583         }
1584     }
1585
1586     fn parse_parameter_declaration(&mut self) -> S::R {
1587         // SPEC
1588         //
1589         // TODO: Add call-convention-opt to the specification.
1590         // (This work is tracked by task T22582676.)
1591         //
1592         // TODO: Update grammar for inout parameters.
1593         // (This work is tracked by task T22582715.)
1594         //
1595         // parameter-declaration:
1596         //   attribute-specification-opt \
1597         //   call-convention-opt \
1598         //   type-specifier  variable-name \
1599         //   default-argument-specifier-opt
1600         //
1601         // ERROR RECOVERY
1602         // In strict mode, we require a type specifier. This error is not caught
1603         // at parse time but rather by a later pass.
1604         // Visibility modifiers are only legal in constructor parameter
1605         // lists; we give an error in a later pass.
1606         // Variadic params cannot be declared inout; we permit that here but
1607         // give an error in a later pass.
1608         // Variadic params and inout params cannot have default values; these
1609         // errors are also reported in a later pass.
1610         let attrs = self.parse_attribute_specification_opt();
1611         let visibility = self.parse_visibility_modifier_opt();
1612         let callconv = self.parse_call_convention_opt();
1613         let token = self.peek_token();
1614         let type_specifier = match token.kind() {
1615             TokenKind::Variable | TokenKind::DotDotDot | TokenKind::Ampersand => {
1616                 S!(make_missing, self, self.pos())
1617             }
1618             _ => {
1619                 self.parse_type_specifier(/* allow_var = */ false, /* allow_attr */ false)
1620             }
1621         };
1622         let name = self.parse_decorated_variable_opt();
1623         let default = self.parse_simple_initializer_opt();
1624         S!(
1625             make_parameter_declaration,
1626             self,
1627             attrs,
1628             visibility,
1629             callconv,
1630             type_specifier,
1631             name,
1632             default
1633         )
1634     }
1635
1636     fn parse_decorated_variable_opt(&mut self) -> S::R {
1637         match self.peek_token_kind() {
1638             TokenKind::DotDotDot | TokenKind::Ampersand => self.parse_decorated_variable(),
1639             _ => self.require_variable(),
1640         }
1641     }
1642
1643     // TODO: This is wrong. The variable here is not anexpression* that has
1644     // an optional decoration on it.  It's a declaration. We shouldn't be using the
1645     // same data structure for a decorated expression as a declaration; one
1646     // is ause* and the other is a *definition*.
1647     fn parse_decorated_variable(&mut self) -> S::R {
1648         // ERROR RECOVERY
1649         // Detection of (variadic, byRef) inout params happens in post-parsing.
1650         // Although a parameter can have at most one variadic/reference decorator,
1651         // we deliberately allow multiple decorators in the initial parse and produce
1652         // an error in a later pass.
1653         let decorator = self.fetch_token();
1654         let variable = match self.peek_token_kind() {
1655             TokenKind::DotDotDot | TokenKind::Ampersand => self.parse_decorated_variable(),
1656             _ => self.require_variable(),
1657         };
1658         S!(make_decorated_expression, self, decorator, variable)
1659     }
1660
1661     fn parse_visibility_modifier_opt(&mut self) -> S::R {
1662         let token_kind = self.peek_token_kind();
1663         match token_kind {
1664             TokenKind::Public | TokenKind::Protected | TokenKind::Private => {
1665                 let token = self.next_token();
1666                 S!(make_token, self, token)
1667             }
1668             _ => S!(make_missing, self, self.pos()),
1669         }
1670     }
1671
1672     // SPEC
1673     //
1674     // TODO: Add this to the specification.
1675     // (This work is tracked by task T22582676.)
1676     //
1677     // call-convention:
1678     //   inout
1679     fn parse_call_convention_opt(&mut self) -> S::R {
1680         let token_kind = self.peek_token_kind();
1681         match token_kind {
1682             TokenKind::Inout => {
1683                 let token = self.next_token();
1684                 S!(make_token, self, token)
1685             }
1686             _ => S!(make_missing, self, self.pos()),
1687         }
1688     }
1689
1690     // SPEC
1691     // default-argument-specifier:
1692     //   =  const-expression
1693     //
1694     // constant-initializer:
1695     //   =  const-expression
1696     fn parse_simple_initializer_opt(&mut self) -> S::R {
1697         let token_kind = self.peek_token_kind();
1698         match token_kind {
1699             TokenKind::Equal => {
1700                 let token = self.next_token();
1701                 // TODO: Detect if expression is not const
1702                 let token = S!(make_token, self, token);
1703                 let default_value = self.parse_expression();
1704                 S!(make_simple_initializer, self, token, default_value)
1705             }
1706             _ => S!(make_missing, self, self.pos()),
1707         }
1708     }
1709
1710     pub fn parse_function_declaration(&mut self, attribute_specification: S::R) -> S::R {
1711         let modifiers = self.parse_modifiers();
1712         let header =
1713             self.parse_function_declaration_header(modifiers, /* is_methodish =*/ false);
1714         let body = self.parse_compound_statement();
1715         S!(
1716             make_function_declaration,
1717             self,
1718             attribute_specification,
1719             header,
1720             body
1721         )
1722     }
1723
1724     fn parse_constraint_operator(&mut self) -> S::R {
1725         // TODO: Put this in the specification
1726         // (This work is tracked by spec issue 100.)
1727         // constraint-operator:
1728         //   =
1729         //   as
1730         //   super
1731         let token_kind = self.peek_token_kind();
1732         match token_kind {
1733             TokenKind::Equal | TokenKind::As | TokenKind::Super => {
1734                 let token = self.next_token();
1735                 S!(make_token, self, token)
1736             }
1737             _ =>
1738             // ERROR RECOVERY: don't eat the offending token.
1739             // TODO: Give parse error
1740             {
1741                 S!(make_missing, self, self.pos())
1742             }
1743         }
1744     }
1745
1746     fn parse_where_constraint(&mut self) -> S::R {
1747         // TODO: Put this in the specification
1748         // (This work is tracked by spec issue 100.)
1749         // constraint:
1750         //   type-specifier  constraint-operator  type-specifier
1751         let left =
1752             self.parse_type_specifier(/* allow_var = */ false, /* allow_attr = */ true);
1753         let op = self.parse_constraint_operator();
1754         let right =
1755             self.parse_type_specifier(/* allow_var = */ false, /* allow_attr = */ true);
1756         S!(make_where_constraint, self, left, op, right)
1757     }
1758
1759     fn parse_where_constraint_list_item(&mut self) -> Option<S::R> {
1760         match self.peek_token_kind() {
1761             TokenKind::Semicolon | TokenKind::LeftBrace => None,
1762             _ => {
1763                 let where_constraint = self.parse_where_constraint();
1764                 let comma = self.optional_token(TokenKind::Comma);
1765                 let result = S!(make_list_item, self, where_constraint, comma);
1766                 Some(result)
1767             }
1768         }
1769     }
1770
1771     fn parse_where_clause(&mut self) -> S::R {
1772         // TODO: Add this to the specification
1773         // (This work is tracked by spec issue 100.)
1774         // where-clause:
1775         //   where   constraint-list
1776         //
1777         // constraint-list:
1778         //   constraint
1779         //   constraint-list , constraint
1780         let keyword = self.assert_token(TokenKind::Where);
1781         let constraints =
1782             self.parse_list_until_none(|x: &mut Self| x.parse_where_constraint_list_item());
1783         S!(make_where_clause, self, keyword, constraints)
1784     }
1785
1786     fn parse_where_clause_opt(&mut self) -> S::R {
1787         if self.peek_token_kind() != TokenKind::Where {
1788             S!(make_missing, self, self.pos())
1789         } else {
1790             self.parse_where_clause()
1791         }
1792     }
1793
1794     fn parse_function_declaration_header(&mut self, modifiers: S::R, is_methodish: bool) -> S::R {
1795         // SPEC
1796         // function-definition-header:
1797         //   attribute-specification-opt  async-opt  coroutine-opt  function  name  /
1798         //   generic-type-parameter-list-opt  (  parameter-list-opt  ) :  /
1799         //   return-type   where-clause-opt
1800         // TODO: The spec does not specify "where" clauses. Add them.
1801         // (This work is tracked by spec issue 100.)
1802         //
1803         // In strict mode, we require a type specifier. This error is not caught
1804         // at parse time but rather by a later pass.
1805         let function_token = self.require_function();
1806         let label = self.parse_function_label_opt(is_methodish);
1807         let generic_type_parameter_list = self.parse_generic_type_parameter_list_opt();
1808         let (left_paren_token, parameter_list, right_paren_token) = self.parse_parameter_list_opt();
1809         let (colon_token, return_type) = self.parse_return_type_hint_opt();
1810         let where_clause = self.parse_where_clause_opt();
1811         S!(
1812             make_function_declaration_header,
1813             self,
1814             modifiers,
1815             function_token,
1816             label,
1817             generic_type_parameter_list,
1818             left_paren_token,
1819             parameter_list,
1820             right_paren_token,
1821             colon_token,
1822             return_type,
1823             where_clause,
1824         )
1825     }
1826
1827     // A function label is either a function name or a __construct label.
1828     fn parse_function_label_opt(&mut self, is_methodish: bool) -> S::R {
1829         let report_error = |x: &mut Self, token: S::Token| {
1830             x.with_error(Errors::error1044);
1831             let token = S!(make_token, x, token);
1832             S!(make_error, x, token)
1833         };
1834         let token_kind = self.peek_token_kind();
1835         match token_kind {
1836             TokenKind::Name | TokenKind::Construct => {
1837                 let token = self.next_token();
1838                 S!(make_token, self, token)
1839             }
1840             TokenKind::LeftParen => {
1841                 // It turns out, it was just a verbose lambda; YOLO PHP
1842                 S!(make_missing, self, self.pos())
1843             }
1844             TokenKind::Isset | TokenKind::Unset | TokenKind::Empty => {
1845                 // We need to parse those as names as they are defined in hhi
1846                 let token = self.next_token_as_name();
1847                 S!(make_token, self, token)
1848             }
1849             _ => {
1850                 let token = if is_methodish {
1851                     self.next_token_as_name()
1852                 } else {
1853                     self.next_token_non_reserved_as_name()
1854                 };
1855                 if token.kind() == TokenKind::Name {
1856                     S!(make_token, self, token)
1857                 } else {
1858                     // ERROR RECOVERY: Eat the offending token.
1859                     report_error(self, token)
1860                 }
1861             }
1862         }
1863     }
1864
1865     fn parse_old_attribute(&mut self) -> S::R {
1866         self.with_expression_parser(|p: &mut ExpressionParser<'a, S, T>| p.parse_constructor_call())
1867     }
1868
1869     pub fn parse_attribute_specification_opt(&mut self) -> S::R {
1870         match self.peek_token_kind() {
1871             TokenKind::At if self.env.allow_new_attribute_syntax => {
1872                 self.parse_new_attribute_specification_opt()
1873             }
1874             TokenKind::LessThanLessThan => self.parse_old_attribute_specification_opt(),
1875             _ => S!(make_missing, self, self.pos()),
1876         }
1877     }
1878
1879     fn parse_new_attribute_specification_opt(&mut self) -> S::R {
1880         let attributes = self.parse_list_while(
1881             |p: &mut Self| p.parse_new_attribute(),
1882             |p: &Self| p.peek_token_kind() == TokenKind::At,
1883         );
1884         S!(make_attribute_specification, self, attributes)
1885     }
1886
1887     fn parse_new_attribute(&mut self) -> S::R {
1888         let at = self.assert_token(TokenKind::At);
1889         let token = self.peek_token();
1890         let constructor_call = match token.kind() {
1891             TokenKind::Name => self.with_expression_parser(|p: &mut ExpressionParser<'a, S, T>| {
1892                 p.parse_constructor_call()
1893             }),
1894             _ => {
1895                 self.with_error(Errors::expected_user_attribute);
1896                 S!(make_missing, self, self.pos())
1897             }
1898         };
1899         S!(make_attribute, self, at, constructor_call)
1900     }
1901
1902     // Parses modifiers and passes them into the parse methods for the
1903     // respective class body element.
1904     fn parse_methodish_or_property_or_const_or_type_const(&mut self) -> S::R {
1905         let mut parser1 = self.clone();
1906         let modifiers = parser1.parse_modifiers();
1907         let kind0 = parser1.peek_token_kind_with_lookahead(0);
1908         let kind1 = parser1.peek_token_kind_with_lookahead(1);
1909         let kind2 = parser1.peek_token_kind_with_lookahead(2);
1910         match (kind0, kind1, kind2) {
1911             (TokenKind::Const, TokenKind::Type, TokenKind::Semicolon) => {
1912                 self.continue_from(parser1);
1913                 let const_ = self.assert_token(TokenKind::Const);
1914                 self.parse_const_declaration(modifiers, const_)
1915             }
1916             (TokenKind::Const, TokenKind::Type, _) if kind2 != TokenKind::Equal => {
1917                 let attributes = S!(make_missing, self, self.pos());
1918                 let modifiers = self.parse_modifiers();
1919                 let const_ = self.assert_token(TokenKind::Const);
1920                 self.parse_type_const_declaration(attributes, modifiers, const_)
1921             }
1922             (TokenKind::Const, _, _) => {
1923                 self.continue_from(parser1);
1924                 let const_ = self.assert_token(TokenKind::Const);
1925                 self.parse_const_declaration(modifiers, const_)
1926             }
1927             _ => {
1928                 let missing = S!(make_missing, self, self.pos());
1929                 self.parse_methodish_or_property(missing)
1930             }
1931         }
1932     }
1933
1934     // SPEC
1935     // method-declaration:
1936     //   attribute-spec-opt method-modifiers function-definition
1937     //   attribute-spec-opt method-modifiers function-definition-header ;
1938     // method-modifiers:
1939     //   method-modifier
1940     //   method-modifiers method-modifier
1941     // method-modifier:
1942     //   visibility-modifier (i.e. private, public, protected)
1943     //   static
1944     //   abstract
1945     //   final
1946     fn parse_methodish(&mut self, attribute_spec: S::R, modifiers: S::R) -> S::R {
1947         let header =
1948             self.parse_function_declaration_header(modifiers, /* is_methodish:*/ true);
1949         let token_kind = self.peek_token_kind();
1950         match token_kind {
1951             TokenKind::LeftBrace => {
1952                 let body = self.parse_compound_statement();
1953                 let missing = S!(make_missing, self, self.pos());
1954                 S!(
1955                     make_methodish_declaration,
1956                     self,
1957                     attribute_spec,
1958                     header,
1959                     body,
1960                     missing
1961                 )
1962             }
1963             TokenKind::Semicolon => {
1964                 let pos = self.pos();
1965                 let token = self.next_token();
1966                 let missing = S!(make_missing, self, pos);
1967                 let semicolon = S!(make_token, self, token);
1968                 S!(
1969                     make_methodish_declaration,
1970                     self,
1971                     attribute_spec,
1972                     header,
1973                     missing,
1974                     semicolon
1975                 )
1976             }
1977             TokenKind::Equal => {
1978                 let equal = self.assert_token(TokenKind::Equal);
1979                 let qualifier = self.parse_qualified_name_type();
1980                 let cc_token = self.require_coloncolon();
1981                 let name = self.require_token_one_of(
1982                     &[TokenKind::Name, TokenKind::Construct],
1983                     Errors::error1004,
1984                 );
1985                 let name = S!(
1986                     make_scope_resolution_expression,
1987                     self,
1988                     qualifier,
1989                     cc_token,
1990                     name
1991                 );
1992                 let semi = self.require_semicolon();
1993                 S!(
1994                     make_methodish_trait_resolution,
1995                     self,
1996                     attribute_spec,
1997                     header,
1998                     equal,
1999                     name,
2000                     semi
2001                 )
2002             }
2003             _ => {
2004                 // ERROR RECOVERY: We expected either a block or a semicolon; we got
2005                 // neither. Use the offending token as the body of the method.
2006                 // TODO: Is this the right error recovery?
2007                 let pos = self.pos();
2008                 let token = self.next_token();
2009                 self.with_error(Errors::error1041);
2010                 let token = S!(make_token, self, token);
2011                 let error = S!(make_error, self, token);
2012                 let missing = S!(make_missing, self, pos);
2013                 S!(
2014                     make_methodish_declaration,
2015                     self,
2016                     attribute_spec,
2017                     header,
2018                     error,
2019                     missing
2020                 )
2021             }
2022         }
2023     }
2024     fn parse_modifiers(&mut self) -> S::R {
2025         let mut items = vec![];
2026         loop {
2027             let token_kind = self.peek_token_kind();
2028             match token_kind {
2029                 TokenKind::Abstract
2030                 | TokenKind::Static
2031                 | TokenKind::Public
2032                 | TokenKind::Protected
2033                 | TokenKind::Private
2034                 | TokenKind::Async
2035                 | TokenKind::Coroutine
2036                 | TokenKind::Final => {
2037                     let token = self.next_token();
2038                     let item = S!(make_token, self, token);
2039                     items.push(item)
2040                 }
2041                 _ => break,
2042             }
2043         }
2044         S!(make_list, self, items, self.pos())
2045     }
2046
2047     fn parse_enum_or_classish_or_function_declaration(&mut self) -> S::R {
2048         // An enum, type alias, function, interface, trait or class may all
2049         // begin with an attribute.
2050         let mut parser1 = self.clone();
2051         let attribute_specification = parser1.parse_attribute_specification_opt();
2052
2053         let mut parser2 = parser1.clone();
2054         let token = parser2.next_token();
2055         match token.kind() {
2056             TokenKind::Enum => {
2057                 self.continue_from(parser1);
2058                 self.parse_enum_declaration(attribute_specification)
2059             }
2060             TokenKind::Type | TokenKind::Newtype => {
2061                 self.continue_from(parser1);
2062
2063                 self.parse_alias_declaration(attribute_specification)
2064             }
2065             TokenKind::Async | TokenKind::Coroutine | TokenKind::Function => {
2066                 if attribute_specification.is_missing() {
2067                     // if attribute section is missing - it might be either
2068                     // function declaration or expression statement containing
2069                     // anonymous function - use statement parser to determine in which case
2070                     // we are currently in
2071                     self.with_statement_parser(|p: &mut StatementParser<'a, S, T>| {
2072                         p.parse_possible_php_function(/* toplevel=*/ true)
2073                     })
2074                 } else {
2075                     self.continue_from(parser1);
2076                     self.parse_function_declaration(attribute_specification)
2077                 }
2078             }
2079             TokenKind::Abstract
2080             | TokenKind::Final
2081             | TokenKind::Interface
2082             | TokenKind::Trait
2083             | TokenKind::Class => {
2084                 self.continue_from(parser1);
2085                 self.parse_classish_declaration(attribute_specification)
2086             }
2087             _ => {
2088                 // ERROR RECOVERY: we encountered an unexpected token, raise an error and continue
2089                 // TODO: This is wrong; we have lost the attribute specification
2090                 // from the tree.
2091                 self.continue_from(parser2);
2092                 self.with_error(Errors::error1057(self.token_text(&token)));
2093                 let token = S!(make_token, self, token);
2094                 S!(make_error, self, token)
2095             }
2096         }
2097     }
2098
2099     fn parse_classish_element(&mut self) -> S::R {
2100         // We need to identify an element of a class, trait, etc. Possibilities
2101         // are:
2102         //
2103         // // constant-declaration:
2104         // const T $x = v ;
2105         // abstract const T $x ;
2106         // public const T $x = v ; // PHP7 only
2107         //
2108         // // type-constant-declaration
2109         // const type T = X;
2110         // abstract const type T;
2111         //
2112         // // property-declaration:
2113         // public/private/protected/static T $x;
2114         // TODO: We may wish to parse "T $x" and give an error indicating
2115         // TODO: that we were expecting either const or public.
2116         // Note that a visibility modifier is required; static is optional;
2117         // any order is allowed.
2118         //
2119         // // method-declaration
2120         // <<attr>> public/private/protected/abstract/final/static async function
2121         // Note that a modifier is required, the attr and async are optional.
2122         // TODO: Hack requires a visibility modifier, unless "static" is supplied,
2123         // TODO: in which case the method is considered to be public.  Is this
2124         // TODO: desired? Resolve this disagreement with the spec.
2125         //
2126         // // constructor-declaration
2127         // <<attr>> public/private/protected/abstract/final function __construct
2128         // Note that we allow static constructors in this parser; we produce an
2129         // error in the post-parse error detection pass.
2130         //
2131         // // trait clauses
2132         // require  extends  qualified-name
2133         // require  implements  qualified-name
2134         //
2135         // // XHP class attribute declaration
2136         // attribute ... ;
2137         //
2138         // // XHP category declaration
2139         // category ... ;
2140         //
2141         // // XHP children declaration
2142         // children ... ;
2143         //
2144         // // Pocket Universe Enumeration
2145         // final? enum id { ... (pocket-field ;) * }
2146         match self.peek_token_kind() {
2147             TokenKind::Children => self.parse_xhp_children_declaration(),
2148             TokenKind::Category => self.parse_xhp_category_declaration(),
2149             TokenKind::Use => self.parse_trait_use(),
2150             TokenKind::Const
2151             | TokenKind::Abstract
2152             | TokenKind::Public
2153             | TokenKind::Protected
2154             | TokenKind::Private
2155             | TokenKind::Static => self.parse_methodish_or_property_or_const_or_type_const(),
2156             TokenKind::Enum => self.parse_class_enum(false),
2157             TokenKind::Final => {
2158                 match self.peek_token_kind_with_lookahead(1) {
2159                     TokenKind::Enum => self.parse_class_enum(/* final:*/ true),
2160                     _ => {
2161                         // Parse class methods, constructors, properties
2162                         // or type constants.
2163                         let attr = self.parse_attribute_specification_opt();
2164                         self.parse_methodish_or_property_or_type_constant(attr)
2165                     }
2166                 }
2167             }
2168             TokenKind::Async | TokenKind::LessThanLessThan => {
2169                 // Parse methods, constructors, properties, or type constants.
2170                 let attr = self.parse_attribute_specification_opt();
2171                 self.parse_methodish_or_property_or_type_constant(attr)
2172             }
2173             TokenKind::At if self.env.allow_new_attribute_syntax => {
2174                 let attr = self.parse_attribute_specification_opt();
2175                 self.parse_methodish_or_property_or_type_constant(attr)
2176             }
2177             TokenKind::Require => {
2178                 // We give an error if these are found where they should not be,
2179                 // in a later pass.
2180                 self.parse_require_clause()
2181             }
2182             TokenKind::Attribute => self.parse_xhp_class_attribute_declaration(),
2183             TokenKind::Function => {
2184                 // ERROR RECOVERY
2185                 // Hack requires that a function inside a class be marked
2186                 // with a visibility modifier, but PHP does not have this requirement.
2187                 // We accept the lack of a modifier here, and produce an error in
2188                 // a later pass.
2189                 let missing1 = S!(make_missing, self, self.pos());
2190                 let missing2 = S!(make_missing, self, self.pos());
2191                 self.parse_methodish(missing1, missing2)
2192             }
2193             kind if self.expects(kind) => S!(make_missing, self, self.pos()),
2194             _ => {
2195                 // If this is a property declaration which is missing its visibility
2196                 // modifier, accept it here, but emit an error in a later pass.
2197                 let mut parser1 = self.clone();
2198                 let missing1 = S!(make_missing, parser1, self.pos());
2199                 let missing2 = S!(make_missing, parser1, self.pos());
2200                 let property = parser1.parse_property_declaration(missing1, missing2);
2201                 if self.errors.len() == parser1.errors.len() {
2202                     self.continue_from(parser1);
2203                     property
2204                 } else {
2205                     // TODO ERROR RECOVERY could be improved here.
2206                     let token = self.fetch_token();
2207                     self.with_error(Errors::error1033);
2208                     S!(make_error, self, token)
2209                     // Parser does not detect the error where non-static instance variables
2210                     // or methods are within abstract final classes in its first pass, but
2211                     // instead detects it in its second pass.
2212                 }
2213             }
2214         }
2215     }
2216
2217     fn parse_generic_type_parameter_list_opt(&mut self) -> S::R {
2218         match self.peek_token_kind_with_possible_attributized_type_list() {
2219             TokenKind::LessThan => self.with_type_parser(|p: &mut TypeParser<'a, S, T>| {
2220                 p.parse_generic_type_parameter_list()
2221             }),
2222             _ => S!(make_missing, self, self.pos()),
2223         }
2224     }
2225
2226     fn parse_type_constraint_opt(&mut self) -> S::R {
2227         self.with_type_parser(|p: &mut TypeParser<'a, S, T>| p.parse_type_constraint_opt())
2228     }
2229
2230     fn parse_alias_declaration(&mut self, attr: S::R) -> S::R {
2231         // SPEC
2232         // alias-declaration:
2233         //   attribute-spec-opt type  name
2234         //     generic-type-parameter-list-opt  =  type-specifier  ;
2235         //   attribute-spec-opt newtype  name
2236         //     generic-type-parameter-list-opt type-constraint-opt
2237         //       =  type-specifier  ;
2238         let token = self.fetch_token();
2239         // Not `require_name` but `require_name_allow_non_reserved`, because the parser
2240         // must allow keywords in the place of identifiers; at least to parse .hhi
2241         // files.
2242         let name = self.require_name_allow_non_reserved();
2243         let generic = self.parse_generic_type_parameter_list_opt();
2244         let constr = self.parse_type_constraint_opt();
2245         let equal = self.require_equal();
2246         let ty = self.parse_type_specifier(false /* allow_var */, true /* allow_attr */);
2247         let semi = self.require_semicolon();
2248         S!(
2249             make_alias_declaration,
2250             self,
2251             attr,
2252             token,
2253             name,
2254             generic,
2255             constr,
2256             equal,
2257             ty,
2258             semi
2259         )
2260     }
2261
2262     fn parse_enumerator(&mut self) -> S::R {
2263         // SPEC
2264         // enumerator:
2265         //   enumerator-constant  =  constant-expression ;
2266         // enumerator-constant:
2267         //   name
2268         //
2269         // TODO: Add an error to a later pass that determines the value is
2270         // a constant.
2271
2272         // TODO: We must allow TRUE to be a legal enum member name; here we allow
2273         // any keyword.  Consider making this more strict.
2274         let name = self.require_name_allow_all_keywords();
2275         let equal = self.require_equal();
2276         let value = self.parse_expression();
2277         let semicolon = self.require_semicolon();
2278         S!(make_enumerator, self, name, equal, value, semicolon)
2279     }
2280
2281     fn parse_inclusion_directive(&mut self) -> S::R {
2282         // SPEC:
2283         // inclusion-directive:
2284         //   require-multiple-directive
2285         //   require-once-directive
2286         //
2287         // require-multiple-directive:
2288         //   require  include-filename  ;
2289         //
2290         // include-filename:
2291         //   expression
2292         //
2293         // require-once-directive:
2294         //   require_once  include-filename  ;
2295         //
2296         // In non-strict mode we allow an inclusion directive (without semi) to be
2297         // used as an expression. It is therefore easier to actually parse this as:
2298         //
2299         // inclusion-directive:
2300         //   inclusion-expression  ;
2301         //
2302         // inclusion-expression:
2303         //   require include-filename
2304         //   require_once include-filename
2305         let expr = self.parse_expression();
2306         let semi = self.require_semicolon();
2307         S!(make_inclusion_directive, self, expr, semi)
2308     }
2309
2310     fn parse_declaration(&mut self) -> S::R {
2311         self.expect_in_new_scope(ExpectedTokens::Classish);
2312         let mut parser1 = self.clone();
2313         let token = parser1.next_token();
2314         let result =
2315             match token.kind() {
2316                 TokenKind::Include
2317                 | TokenKind::Include_once
2318                 | TokenKind::Require
2319                 | TokenKind::Require_once => self.parse_inclusion_directive(),
2320                 TokenKind::Type | TokenKind::Newtype
2321                     if {
2322                         let kind = parser1.peek_token_kind();
2323                         kind == TokenKind::Name || kind == TokenKind::Classname
2324                     } =>
2325                 {
2326                     let missing = S!(make_missing, self, self.pos());
2327                     self.parse_alias_declaration(missing)
2328                 }
2329                 TokenKind::Enum => {
2330                     let missing = S!(make_missing, self, self.pos());
2331                     self.parse_enum_declaration(missing)
2332                 }
2333                 TokenKind::RecordDec => {
2334                     let missing = S!(make_missing, self, self.pos());
2335                     self.parse_record_declaration(missing)
2336                 }
2337                 // The keyword namespace before a name should be parsed as
2338                 // "the current namespace we are in", essentially a no op.
2339                 // example:
2340                 // namespace\f1(); should be parsed as a call to the function f1 in
2341                 // the current namespace.
2342                 TokenKind::Namespace if parser1.peek_token_kind() == TokenKind::Backslash => self
2343                     .with_statement_parser(|p: &mut StatementParser<'a, S, T>| p.parse_statement()),
2344                 TokenKind::Namespace => self.parse_namespace_declaration(),
2345                 TokenKind::Use => self.parse_namespace_use_declaration(),
2346                 TokenKind::Trait | TokenKind::Interface | TokenKind::Class => {
2347                     let missing = S!(make_missing, self, self.pos());
2348                     self.parse_classish_declaration(missing)
2349                 }
2350                 TokenKind::Abstract | TokenKind::Final => {
2351                     let missing = S!(make_missing, self, self.pos());
2352                     match parser1.peek_token_kind() {
2353                         TokenKind::RecordDec => self.parse_record_declaration(missing),
2354                         _ => self.parse_classish_declaration(missing),
2355                     }
2356                 }
2357                 TokenKind::Async | TokenKind::Coroutine | TokenKind::Function => self
2358                     .with_statement_parser(|p: &mut StatementParser<'a, S, T>| {
2359                         p.parse_possible_php_function(true)
2360                     }),
2361                 TokenKind::At if self.env.allow_new_attribute_syntax => {
2362                     self.parse_enum_or_classish_or_function_declaration()
2363                 }
2364                 TokenKind::LessThanLessThan => match parser1.peek_token_kind() {
2365                     TokenKind::File
2366                         if parser1.peek_token_kind_with_lookahead(1) == TokenKind::Colon =>
2367                     {
2368                         self.parse_file_attribute_specification_opt()
2369                     }
2370                     _ => self.parse_enum_or_classish_or_function_declaration(),
2371                 },
2372                 // TODO figure out what global const differs from class const
2373                 TokenKind::Const => {
2374                     let missing1 = S!(make_missing, parser1, self.pos());
2375                     self.continue_from(parser1);
2376                     let token = S!(make_token, self, token);
2377                     self.parse_const_declaration(missing1, token)
2378                 }
2379                 // TODO: What if it's not a legal statement? Do we still make progress here?
2380                 _ => self
2381                     .with_statement_parser(|p: &mut StatementParser<'a, S, T>| p.parse_statement()),
2382             };
2383
2384         self.pop_scope(ExpectedTokens::Classish);
2385         result
2386     }
2387
2388     fn parse_pocket_mapping(&mut self) -> S::R {
2389         // SPEC
2390         // pocket-mapping ::=
2391         //   | 'type' identifier '=' type-expression
2392         //   | identifier '=' expression
2393         match self.peek_token_kind() {
2394             TokenKind::Type => {
2395                 let typ = self.require_token(TokenKind::Type, Errors::type_keyword);
2396                 let tyname = self.require_name();
2397                 let equal = self.require_equal();
2398                 let ty = self.parse_type_specifier(false, true);
2399                 S!(
2400                     make_pocket_mapping_type_declaration,
2401                     self,
2402                     typ,
2403                     tyname,
2404                     equal,
2405                     ty
2406                 )
2407             }
2408             TokenKind::Name => {
2409                 let id = self.require_name();
2410                 let equal = self.require_equal();
2411                 let simple_init = self.parse_expression();
2412                 let sc_init = S!(make_simple_initializer, self, equal, simple_init);
2413                 S!(make_pocket_mapping_id_declaration, self, id, sc_init)
2414             }
2415             _ => {
2416                 self.with_error(Errors::pocket_universe_invalid_field);
2417                 S!(make_missing, self, self.pos())
2418             }
2419         }
2420     }
2421
2422     fn parse_pocket_field(&mut self) -> S::R {
2423         // SPEC
2424         // pocket-field ::=
2425         //   | enum-member ;
2426         //   | enum-member '(' (pocket-mapping ',')')' ;
2427         //   | 'case' type-expression identifier ;
2428         //   | 'case' 'type' identifier ;
2429         //
2430         // enum-member ::= ':@' name
2431         match self.peek_token_kind() {
2432             TokenKind::ColonAt => {
2433                 let glyph = self.assert_token(TokenKind::ColonAt);
2434                 let enum_name = self.require_name();
2435                 match self.peek_token_kind() {
2436                     TokenKind::LeftParen => {
2437                         let (left_paren, mappings, right_paren) =
2438                             self.parse_parenthesized_comma_list(|x| x.parse_pocket_mapping());
2439                         let semi = self.require_semicolon();
2440                         S!(
2441                             make_pocket_atom_mapping_declaration,
2442                             self,
2443                             glyph,
2444                             enum_name,
2445                             left_paren,
2446                             mappings,
2447                             right_paren,
2448                             semi,
2449                         )
2450                     }
2451                     _ => {
2452                         let missing_left = S!(make_missing, self, self.pos());
2453                         let missing_mappings = S!(make_missing, self, self.pos());
2454                         let missing_right = S!(make_missing, self, self.pos());
2455                         let semi = self.require_semicolon();
2456                         S!(
2457                             make_pocket_atom_mapping_declaration,
2458                             self,
2459                             glyph,
2460                             enum_name,
2461                             missing_left,
2462                             missing_mappings,
2463                             missing_right,
2464                             semi,
2465                         )
2466                     }
2467                 }
2468             }
2469             TokenKind::Case => {
2470                 let case_tok = self.assert_token(TokenKind::Case);
2471                 match self.peek_token_kind() {
2472                     TokenKind::Type => {
2473                         let type_tok = self.assert_token(TokenKind::Type);
2474                         let name = self.require_name();
2475                         let semi = self.require_semicolon();
2476                         S!(
2477                             make_pocket_field_type_declaration,
2478                             self,
2479                             case_tok,
2480                             type_tok,
2481                             name,
2482                             semi
2483                         )
2484                     }
2485                     _ => {
2486                         let ty = self.parse_type_specifier(false, true);
2487                         let name = self.require_name();
2488                         let semi = self.require_semicolon();
2489                         S!(
2490                             make_pocket_field_type_expr_declaration,
2491                             self,
2492                             case_tok,
2493                             ty,
2494                             name,
2495                             semi
2496                         )
2497                     }
2498                 }
2499             }
2500             _ => {
2501                 self.with_error(Errors::pocket_universe_invalid_field);
2502                 S!(make_missing, self, self.pos())
2503             }
2504         }
2505     }
2506
2507     fn parse_pocket_fields_opt(&mut self) -> S::R {
2508         // SPEC
2509         // pocket-field-list:
2510         //   pocket-field
2511         //   pocket-field-list pocket-field
2512         self.parse_terminated_list(|x| x.parse_pocket_field(), TokenKind::RightBrace)
2513     }
2514
2515     fn parse_class_enum(&mut self, final_: bool /* = false */) -> S::R {
2516         // SPEC
2517         // 'final'? 'enum' identifier '{' pocket-field-list '}'
2518         //
2519         // from parse_classish_declaration.. probably could do better
2520         // read Final
2521         let final_tok = if final_ {
2522             self.require_token(TokenKind::Final, Errors::pocket_universe_final_expected)
2523         } else {
2524             S!(make_missing, self, self.pos())
2525         };
2526         // read Enum
2527         let enum_tok = self.require_token(TokenKind::Enum, Errors::pocket_universe_enum_expected);
2528         let name = self.require_name();
2529         let (left_brace, pocket_fields, right_brace) =
2530             self.parse_braced_list(|x| x.parse_pocket_fields_opt());
2531         S!(
2532             make_pocket_enum_declaration,
2533             self,
2534             final_tok,
2535             enum_tok,
2536             name,
2537             left_brace,
2538             pocket_fields,
2539             right_brace,
2540         )
2541     }
2542
2543     pub fn parse_script(&mut self) -> S::R {
2544         // TODO(kasper): no_markup for ".hack" files
2545         let header = self.parse_leading_markup_section();
2546         let mut declarations = vec![];
2547         if let Some(x) = header {
2548             declarations.push(x)
2549         };
2550         loop {
2551             let token_kind = self.peek_token_kind();
2552             match token_kind {
2553                 TokenKind::EndOfFile => {
2554                     let token = self.next_token();
2555                     let token = S!(make_token, self, token);
2556                     let end_of_file = S!(make_end_of_file, self, token);
2557                     declarations.push(end_of_file);
2558                     break;
2559                 }
2560                 _ => declarations.push(self.parse_declaration()),
2561             }
2562         }
2563         let declarations = S!(make_list, self, declarations, self.pos());
2564         let result = S!(make_script, self, declarations);
2565         assert_eq!(self.peek_token_kind(), TokenKind::EndOfFile);
2566         result
2567     }
2568 }