parser.ts

/**
 * @fileoverview A TypeScript parser for the AssemblyScript subset.
 *
 * Takes the tokens produced by the `Tokenizer` and builds an abstract
 * syntax tree composed of `Node`s wrapped in a `Source` out of it.
 *
 * @license Apache-2.0
 */

import {
  CommonFlags,
  LIBRARY_PREFIX,
  PATH_DELIMITER
} from "./common";

import {
  Tokenizer,
  Token,
  Range,
  CommentHandler,
  IdentifierHandling,
  isIllegalVariableIdentifier
} from "./tokenizer";

import {
  DiagnosticCode,
  DiagnosticEmitter,
  DiagnosticMessage
} from "./diagnostics";

import {
  normalizePath
} from "./util";

import {
  Node,
  NodeKind,
  Source,
  SourceKind,
  TypeNode,
  TypeName,
  NamedTypeNode,
  FunctionTypeNode,
  ArrowKind,

  Expression,
  AssertionKind,
  CallExpression,
  ClassExpression,
  FunctionExpression,
  IdentifierExpression,
  StringLiteralExpression,

  Statement,
  BlockStatement,
  BreakStatement,
  ClassDeclaration,
  ContinueStatement,
  DeclarationStatement,
  DecoratorNode,
  DoStatement,
  EnumDeclaration,
  EnumValueDeclaration,
  ExportImportStatement,
  ExportMember,
  ExportStatement,
  ExpressionStatement,
  ForOfStatement,
  FunctionDeclaration,
  IfStatement,
  ImportDeclaration,
  ImportStatement,
  IndexSignatureNode,
  NamespaceDeclaration,
  ParameterNode,
  ParameterKind,
  ReturnStatement,
  SwitchCase,
  SwitchStatement,
  ThrowStatement,
  TryStatement,
  TypeDeclaration,
  TypeParameterNode,
  VariableStatement,
  VariableDeclaration,
  VoidStatement,
  WhileStatement,

  mangleInternalPath
} from "./ast";

/** Represents a dependee. */
class Dependee {
  constructor(
    public source: Source,
    public reportNode: Node
  ) {}
}

/** Parser interface. */
export class Parser extends DiagnosticEmitter {

  /** Source file names to be requested next. */
  backlog: string[] = new Array();
  /** Source file names already seen, that is processed or backlogged. */
  seenlog: Set<string> = new Set();
  /** Source file names already completely processed. */
  donelog: Set<string> = new Set();
  /** Optional handler to intercept comments while tokenizing. */
  onComment: CommentHandler | null = null;
  /** Current file being parsed. */
  currentSource: Source | null = null;
  /** Map of dependees being depended upon by a source, by path. */
  dependees: Map<string, Dependee> = new Map();
  /** An array of parsed sources. */
  sources: Source[];

  /** Constructs a new parser. */
  constructor(
    diagnostics: DiagnosticMessage[] | null = null,
    sources: Source[] | null = null
  ) {
    super(diagnostics);
    this.sources = sources ? sources : new Array<Source>();
  }

  /** Parses a file and adds its definitions to the program. */
  parseFile(
    /** Source text of the file, or `null` to indicate not found. */
    text: string | null,
    /** Normalized path of the file. */
    path: string,
    /** Whether this is an entry file. */
    isEntry: bool
  ): void {
    // the frontend gives us paths with file extensions
    var normalizedPath = normalizePath(path);
    var internalPath = mangleInternalPath(path);

    // check if already processed
    if (this.donelog.has(internalPath)) return;
    this.donelog.add(internalPath); // do not parse again
    this.seenlog.add(internalPath); // do not request again

    // check if this is an error
    if (text === null) {
      let dependees = this.dependees;
      let dependee: Dependee | null = null;
      if (dependees.has(internalPath)) dependee = assert(dependees.get(internalPath));
      this.error(
        DiagnosticCode.File_0_not_found,
        dependee
          ? dependee.reportNode.range
          : null,
        path
      );
      return;
    }

    // create the source element
    var source = new Source(
      isEntry
        ? SourceKind.USER_ENTRY
        : path.startsWith(LIBRARY_PREFIX)
          ? path.indexOf(PATH_DELIMITER, LIBRARY_PREFIX.length) < 0
            ? SourceKind.LIBRARY_ENTRY
            : SourceKind.LIBRARY
          : SourceKind.USER,
      normalizedPath,
      text
    );

    this.sources.push(source);
    this.currentSource = source;

    // tokenize and parse
    var tn = new Tokenizer(source, this.diagnostics);
    tn.onComment = this.onComment;
    var statements = source.statements;
    while (!tn.skip(Token.ENDOFFILE)) {
      let statement = this.parseTopLevelStatement(tn, null);
      if (statement) {
        statements.push(statement);
      } else {
        this.skipStatement(tn);
      }
    }
  }

  /** Parses a top-level statement. */
  parseTopLevelStatement(
    tn: Tokenizer,
    namespace: NamespaceDeclaration | null = null
  ): Statement | null {
    var flags = CommonFlags.NONE;
    var startPos: i32 = -1;

    // check decorators
    var decorators: DecoratorNode[] | null = null;
    while (tn.skip(Token.AT)) {
      if (startPos < 0) startPos = tn.tokenPos;
      let decorator = this.parseDecorator(tn);
      if (!decorator) {
        this.skipStatement(tn);
        continue;
      }
      if (!decorators) decorators = [decorator];
      else decorators.push(decorator);
    }

    // check modifiers
    var exportStart: i32 = 0;
    var exportEnd: i32 = 0;
    var defaultStart: i32 = 0;
    var defaultEnd: i32 = 0;
    if (tn.skip(Token.EXPORT)) {
      if (startPos < 0) startPos = tn.tokenPos;
      flags |= CommonFlags.EXPORT;
      exportStart = tn.tokenPos;
      exportEnd = tn.pos;
      if (tn.skip(Token.DEFAULT)) {
        defaultStart = tn.tokenPos;
        defaultEnd = tn.pos;
      }
    }

    var declareStart: i32 = 0;
    var declareEnd: i32 = 0;
    var contextIsAmbient = namespace != null && namespace.is(CommonFlags.AMBIENT);
    if (tn.skip(Token.DECLARE)) {
      if (contextIsAmbient) {
        this.error(
          DiagnosticCode.A_declare_modifier_cannot_be_used_in_an_already_ambient_context,
          tn.range()
        ); // recoverable
      } else {
        if (startPos < 0) startPos = tn.tokenPos;
        declareStart = startPos;
        declareEnd = tn.pos;
        flags |= CommonFlags.DECLARE | CommonFlags.AMBIENT;
      }
    } else if (contextIsAmbient) {
      flags |= CommonFlags.AMBIENT;
    }

    // parse the statement
    var statement: Statement | null = null;

    // handle declarations
    var first = tn.peek();
    if (startPos < 0) startPos = tn.nextTokenPos;
    switch (first) {
      case Token.CONST: {
        tn.next();
        flags |= CommonFlags.CONST;
        if (tn.skip(Token.ENUM)) {
          statement = this.parseEnum(tn, flags, decorators, startPos);
        } else {
          statement = this.parseVariable(tn, flags, decorators, startPos);
        }
        decorators = null;
        break;
      }
      case Token.LET: flags |= CommonFlags.LET;
      case Token.VAR: {
        tn.next();
        statement = this.parseVariable(tn, flags, decorators, startPos);
        decorators = null;
        break;
      }
      case Token.ENUM: {
        tn.next();
        statement = this.parseEnum(tn, flags, decorators, startPos);
        decorators = null;
        break;
      }
      case Token.FUNCTION: {
        tn.next();
        statement = this.parseFunction(tn, flags, decorators, startPos);
        decorators = null;
        break;
      }
      case Token.ABSTRACT: {
        let state = tn.mark();
        tn.next();
        let abstractStart = tn.tokenPos;
        let abstractEnd = tn.pos;
        let next = tn.peek(true);
        if (tn.nextTokenOnNewLine) {
          tn.reset(state);
          statement = this.parseStatement(tn, true);
          break;
        }
        if (next != Token.CLASS) {
          if (next == Token.INTERFACE) {
            this.error(
              DiagnosticCode._abstract_modifier_can_only_appear_on_a_class_method_or_property_declaration,
              tn.range(abstractStart, abstractEnd)
            );
          }
          tn.reset(state);
          statement = this.parseStatement(tn, true);
          break;
        } else {
          tn.discard(state);
        }
        flags |= CommonFlags.ABSTRACT;
        // fall through
      }
      case Token.CLASS:
      case Token.INTERFACE: {
        tn.next();
        statement = this.parseClassOrInterface(tn, flags, decorators, startPos);
        decorators = null;
        break;
      }
      case Token.NAMESPACE: {
        let state = tn.mark();
        tn.next();
        if (tn.peek(false, IdentifierHandling.PREFER) == Token.IDENTIFIER) {
          tn.discard(state);
          statement = this.parseNamespace(tn, flags, decorators, startPos);
          decorators = null;
        } else {
          tn.reset(state);
          statement = this.parseStatement(tn, true);
        }
        break;
      }
      case Token.IMPORT: {
        tn.next();
        flags |= CommonFlags.IMPORT;
        if (flags & CommonFlags.EXPORT) {
          statement = this.parseExportImport(tn, startPos);
        } else {
          statement = this.parseImport(tn);
        }
        break;
      }
      case Token.TYPE: { // also identifier
        let state = tn.mark();
        tn.next();
        if (tn.peek(false, IdentifierHandling.PREFER) == Token.IDENTIFIER) {
          tn.discard(state);
          statement = this.parseTypeDeclaration(tn, flags, decorators, startPos);
          decorators = null;
        } else {
          tn.reset(state);
          statement = this.parseStatement(tn, true);
        }
        break;
      }
      default: {

        // handle plain exports
        if (flags & CommonFlags.EXPORT) {
          if (defaultEnd && tn.skipIdentifier(IdentifierHandling.PREFER)) {
            if (declareEnd) {
              this.error(
                DiagnosticCode.An_export_assignment_cannot_have_modifiers,
                tn.range(declareStart, declareEnd)
              );
            }
            statement = this.parseExportDefaultAlias(tn, startPos, defaultStart, defaultEnd);
            defaultStart = defaultEnd = 0; // consume
          } else {
            statement = this.parseExport(tn, startPos, (flags & CommonFlags.DECLARE) != 0);
          }

        // handle non-declaration statements
        } else {
          if (exportEnd) {
            this.error(
              DiagnosticCode._0_modifier_cannot_be_used_here,
              tn.range(exportStart, exportEnd), "export"
            ); // recoverable
          }
          if (declareEnd) {
            this.error(
              DiagnosticCode._0_modifier_cannot_be_used_here,
              tn.range(declareStart, declareEnd), "declare"
            ); // recoverable
          }
          if (!namespace) {
            statement = this.parseStatement(tn, true);
          } // TODO: else?
        }
        break;
      }
    }

    // check for decorators that weren't consumed
    if (decorators) {
      for (let i = 0, k = decorators.length; i < k; ++i) {
        this.error(
          DiagnosticCode.Decorators_are_not_valid_here,
          decorators[i].range
        );
      }
    }

    // check if this an `export default` declaration
    if (defaultEnd && statement !== null) {
      switch (statement.kind) {
        case NodeKind.ENUMDECLARATION:
        case NodeKind.FUNCTIONDECLARATION:
        case NodeKind.CLASSDECLARATION:
        case NodeKind.INTERFACEDECLARATION:
        case NodeKind.NAMESPACEDECLARATION: {
          return Node.createExportDefaultStatement(<DeclarationStatement>statement, tn.range(startPos, tn.pos));
        }
        default: {
          this.error(
            DiagnosticCode._0_modifier_cannot_be_used_here,
            tn.range(defaultStart, defaultEnd), "default"
          );
        }
      }
    }
    return statement;
  }

  /** Obtains the next file to parse. */
  nextFile(): string | null {
    var backlog = this.backlog;
    return backlog.length ? assert(backlog.shift()) : null;
  }

  /** Obtains the path of the dependee of the given imported file. */
  getDependee(dependent: string): string | null {
    var dependees = this.dependees;
    if (dependees.has(dependent)) {
      let dependee = assert(dependees.get(dependent));
      return dependee.source.internalPath;
    }
    return null;
  }

  /** Finishes parsing. */
  finish(): void {
    if (this.backlog.length) throw new Error("backlog is not empty");
    this.backlog = [];
    this.seenlog.clear();
    this.donelog.clear();
    this.dependees.clear();
  }

  // types

  /** Parses a type name. */
  parseTypeName(
    tn: Tokenizer
  ): TypeName | null {

    // at: Identifier ('.' Identifier)*

    var first = Node.createSimpleTypeName(tn.readIdentifier(), tn.range());
    var current = first;
    while (tn.skip(Token.DOT)) {
      if (tn.skip(Token.IDENTIFIER)) {
        let next = Node.createSimpleTypeName(tn.readIdentifier(), tn.range());
        current.next = next;
        current = next;
      } else {
        this.error(
          DiagnosticCode.Identifier_expected,
          tn.range(tn.pos)
        );
        return null;
      }
    }
    return first;
  }

  /** Parses a type. */
  parseType(
    tn: Tokenizer,
    acceptParenthesized: bool = true,
    suppressErrors: bool = false
  ): TypeNode | null {

    // before: Type

    // NOTE: this parses our limited subset
    var token = tn.next();
    var startPos = tn.tokenPos;

    var type: TypeNode;

    // '(' ...
    if (token == Token.OPENPAREN) {

      // '(' FunctionSignature ')' '|' 'null'?
      let isNullableSignature = tn.skip(Token.OPENPAREN);
      // FunctionSignature?
      let signature = this.tryParseFunctionType(tn);
      if (signature) {
        if (isNullableSignature) {
          if (!tn.skip(Token.CLOSEPAREN)) {
            this.error(
              DiagnosticCode._0_expected,
              tn.range(), ")"
            );
            return null;
          }
          if (!tn.skip(Token.BAR)) {
            this.error(
              DiagnosticCode._0_expected,
              tn.range(), "|"
            );
            return null;
          }
          if (!tn.skip(Token.NULL)) {
            this.error(
              DiagnosticCode._0_expected,
              tn.range(), "null"
            );
          }
          signature.isNullable = true;
        }
        return signature;
      } else if (isNullableSignature || this.tryParseSignatureIsSignature) {
        this.error(
          DiagnosticCode.Unexpected_token,
          tn.range()
        );
        return null;
      }

      // Type (',' Type)* ')'
      if (acceptParenthesized) {
        let innerType = this.parseType(tn, false, suppressErrors);
        if (!innerType) return null;
        if (!tn.skip(Token.CLOSEPAREN)) {
          if (!suppressErrors) {
            this.error(
              DiagnosticCode._0_expected,
              tn.range(tn.pos), ")"
            );
          }
          return null;
        }
        type = innerType;
        type.range.start = startPos;
        type.range.end = tn.pos;
      } else {
        this.error(
          DiagnosticCode.Unexpected_token,
          tn.range()
        );
        return null;
      }

    // 'void'
    } else if (token == Token.VOID) {
      type = Node.createNamedType(
        Node.createSimpleTypeName("void", tn.range()), [], false, tn.range(startPos, tn.pos)
      );

    // 'this'
    } else if (token == Token.THIS) {
      type = Node.createNamedType(
        Node.createSimpleTypeName("this", tn.range()), [], false, tn.range(startPos, tn.pos)
      );

    // 'true'
    } else if (token == Token.TRUE || token == Token.FALSE) {
      type = Node.createNamedType(
        Node.createSimpleTypeName("bool", tn.range()), [], false, tn.range(startPos, tn.pos)
      );

    // 'null'
    } else if (token == Token.NULL) {
      type = Node.createNamedType(
        Node.createSimpleTypeName("null", tn.range()), [], false, tn.range(startPos, tn.pos)
      );

    // StringLiteral
    } else if (token == Token.STRINGLITERAL) {
      tn.readString();
      type = Node.createNamedType(
        Node.createSimpleTypeName("string", tn.range()), [], false, tn.range(startPos, tn.pos)
      );

    // Identifier
    } else if (token == Token.IDENTIFIER) {
      let name = this.parseTypeName(tn);
      if (!name) return null;
      let parameters: TypeNode[] | null = null;

      // Name<T>
      if (tn.skip(Token.LESSTHAN)) {
        do {
          let parameter = this.parseType(tn, true, suppressErrors);
          if (!parameter) return null;
          if (!parameters) parameters = [ parameter ];
          else parameters.push(parameter);
        } while (tn.skip(Token.COMMA));
        if (!tn.skip(Token.GREATERTHAN)) {
          if (!suppressErrors) {
            this.error(
              DiagnosticCode._0_expected,
              tn.range(tn.pos), ">"
            );
          }
          return null;
        }
      }
      if (!parameters) parameters = [];
      type = Node.createNamedType(name, parameters, false, tn.range(startPos, tn.pos));
    } else {
      if (!suppressErrors) {
        this.error(
          DiagnosticCode.Type_expected,
          tn.range()
        );
      }
      return null;
    }
    // ... | null
    while (tn.skip(Token.BAR)) {
      if (tn.skip(Token.NULL)) {
        type.isNullable = true;
      } else {
        let notNullStart = tn.pos;
        let notNull = this.parseType(tn, false, true);
        if (!suppressErrors) {
          this.error(
            DiagnosticCode._0_expected,
            notNull ? notNull.range : tn.range(notNullStart), "null"
          );
        }
        return null;
      }
    }
    // ... [][]
    while (tn.skip(Token.OPENBRACKET)) {
      let bracketStart = tn.tokenPos;
      if (!tn.skip(Token.CLOSEBRACKET)) {
        if (!suppressErrors) {
          this.error(
            DiagnosticCode._0_expected,
            tn.range(), "]"
          );
        }
        return null;
      }
      let bracketRange = tn.range(bracketStart, tn.pos);

      // ...[] | null
      let nullable = false;
      if (tn.skip(Token.BAR)) {
        if (tn.skip(Token.NULL)) {
          nullable = true;
        } else {
          if (!suppressErrors) {
            this.error(
              DiagnosticCode._0_expected,
              tn.range(), "null"
            );
          }
          return null;
        }
      }
      type = Node.createNamedType(
        Node.createSimpleTypeName("Array", bracketRange),
        [ type ],
        nullable,
        tn.range(startPos, tn.pos)
      );
      if (nullable) break;
    }

    return type;
  }

  // Indicates whether tryParseSignature determined that it is handling a Signature
  private tryParseSignatureIsSignature: bool = false;

  /** Parses a function type, as used in type declarations. */
  tryParseFunctionType(
    tn: Tokenizer
  ): FunctionTypeNode | null {

    // at '(': ('...'? Identifier '?'? ':' Type (','  '...'? Identifier '?'? ':' Type)* )? ')' '=>' Type

    var state = tn.mark();
    var startPos = tn.tokenPos;
    var parameters: ParameterNode[] | null = null;
    var thisType: NamedTypeNode | null = null;
    var isSignature: bool = false;
    var firstParamNameNoType: IdentifierExpression | null = null;
    var firstParamKind: ParameterKind = ParameterKind.DEFAULT;

    if (tn.skip(Token.CLOSEPAREN)) {
      isSignature = true;
      tn.discard(state);
      parameters = [];

    } else {
      isSignature = false; // not yet known
      do {
        let paramStart: i32 = -1;
        let kind = ParameterKind.DEFAULT;
        if (tn.skip(Token.DOT_DOT_DOT)) {
          paramStart = tn.tokenPos;
          isSignature = true;
          tn.discard(state);
          kind = ParameterKind.REST;
        }
        if (tn.skip(Token.THIS)) {
          if (paramStart < 0) paramStart = tn.tokenPos;
          if (tn.skip(Token.COLON)) {
            isSignature = true;
            tn.discard(state);
            let t = this.parseType(tn, false);
            if (!t) return null;
            if (t.kind != NodeKind.NAMEDTYPE) {
              this.error(
                DiagnosticCode.Identifier_expected,
                t.range
              );
              this.tryParseSignatureIsSignature = true;
              return null;
            }
            thisType = <NamedTypeNode>t;
          } else {
            tn.reset(state);
            this.tryParseSignatureIsSignature = false;
            return null;
          }
        } else if (tn.skipIdentifier()) {
          if (paramStart < 0) paramStart = tn.tokenPos;
          let name = Node.createIdentifierExpression(tn.readIdentifier(), tn.range(tn.tokenPos, tn.pos));
          if (tn.skip(Token.QUESTION)) {
            isSignature = true;
            tn.discard(state);
            if (kind == ParameterKind.REST) {
              this.error(
                DiagnosticCode.A_rest_parameter_cannot_be_optional,
                tn.range()
              ); // recoverable
            } else {
              kind = ParameterKind.OPTIONAL;
            }
          }
          if (tn.skip(Token.COLON)) {
            isSignature = true;
            tn.discard(state);
            let type = this.parseType(tn); // not suppressing errors because known
            if (!type) {
              this.tryParseSignatureIsSignature = isSignature;
              return null;
            }
            let param = Node.createParameter(kind, name, type, null, tn.range(paramStart, tn.pos));
            if (!parameters) parameters = [ param ];
            else parameters.push(param);
          } else {
            if (!isSignature) {
              if (tn.peek() == Token.COMMA) {
                isSignature = true;
                tn.discard(state);
              }
            }
            if (isSignature) {
              let param = Node.createParameter(kind, name, Node.createOmittedType(tn.range(tn.pos)), null, tn.range(paramStart, tn.pos));
              if (!parameters) parameters = [ param ];
              else parameters.push(param);
              this.error(
                DiagnosticCode.Type_expected,
                param.type.range
              ); // recoverable
            } else if (!parameters) {
              // on '(' Identifier ^',' we don't yet know whether this is a
              // parenthesized or a function type, hence we have to delay the
              // respective diagnostic until we know for sure.
              firstParamNameNoType = name;
              firstParamKind = kind;
            }
          }
        } else {
          if (isSignature) {
            this.error(
              DiagnosticCode.Identifier_expected,
              tn.range()
            );
          } else {
            tn.reset(state);
          }
          this.tryParseSignatureIsSignature = isSignature;
          return null;
        }
      } while (tn.skip(Token.COMMA));
      if (!tn.skip(Token.CLOSEPAREN)) {
        if (isSignature) {
          this.error(
            DiagnosticCode._0_expected,
            tn.range(), ")"
          );
        } else {
          tn.reset(state);
        }
        this.tryParseSignatureIsSignature = isSignature;
        return null;
      }
    }

    var returnType: TypeNode | null;
    if (tn.skip(Token.EQUALS_GREATERTHAN)) {
      if (!isSignature) {
        isSignature = true;
        tn.discard(state);
        if (firstParamNameNoType) { // now we know
          let param = Node.createParameter(
            firstParamKind,
            firstParamNameNoType,
            Node.createOmittedType(firstParamNameNoType.range.atEnd),
            null,
            firstParamNameNoType.range
          );
          if (!parameters) parameters = [ param ];
          else parameters.push(param);
          this.error(
            DiagnosticCode.Type_expected,
            param.type.range
          ); // recoverable
        }
      }
      returnType = this.parseType(tn);
      if (!returnType) {
        this.tryParseSignatureIsSignature = isSignature;
        return null;
      }
    } else {
      if (isSignature) {
        this.error(
          DiagnosticCode._0_expected,
          tn.range(), "=>"
        );
      } else {
        tn.reset(state);
      }
      this.tryParseSignatureIsSignature = isSignature;
      return null;
    }
    this.tryParseSignatureIsSignature = true;
    if (!parameters) parameters = [];
    return Node.createFunctionType(
      parameters,
      returnType,
      thisType,
      false,
      tn.range(startPos, tn.pos)
    );
  }

  // statements

  parseDecorator(
    tn: Tokenizer
  ): DecoratorNode | null {

    // at '@': Identifier ('.' Identifier)* '(' Arguments

    var startPos = tn.tokenPos;
    if (tn.skipIdentifier()) {
      let name = tn.readIdentifier();
      let expression: Expression = Node.createIdentifierExpression(name, tn.range(startPos, tn.pos));
      while (tn.skip(Token.DOT)) {
        if (tn.skipIdentifier(IdentifierHandling.PREFER)) {
          name = tn.readIdentifier();
          expression = Node.createPropertyAccessExpression(
            expression,
            Node.createIdentifierExpression(name, tn.range()),
            tn.range(startPos, tn.pos)
          );
        } else {
          this.error(
            DiagnosticCode.Identifier_expected,
            tn.range()
          );
          return null;
        }
      }
      let args: Expression[] | null;
      if (tn.skip(Token.OPENPAREN)) {
        args = this.parseArguments(tn);
        if (args) {
          return Node.createDecorator(expression, args, tn.range(startPos, tn.pos));
        }
      } else {
        return Node.createDecorator(expression, null, tn.range(startPos, tn.pos));
      }
    } else {
      this.error(
        DiagnosticCode.Identifier_expected,
        tn.range()
      );
    }
    return null;
  }

  parseVariable(
    tn: Tokenizer,
    flags: CommonFlags,
    decorators: DecoratorNode[] | null,
    startPos: i32,
    isFor: bool = false
  ): VariableStatement | null {

    // at ('const' | 'let' | 'var'): VariableDeclaration (',' VariableDeclaration)* ';'?

    var declarations = new Array<VariableDeclaration>();
    do {
      let declaration = this.parseVariableDeclaration(tn, flags, decorators, isFor);
      if (!declaration) return null;
      declarations.push(declaration);
    } while (tn.skip(Token.COMMA));

    var ret = Node.createVariableStatement(decorators, declarations, tn.range(startPos, tn.pos));
    tn.skip(Token.SEMICOLON);
    return ret;
  }

  parseVariableDeclaration(
    tn: Tokenizer,
    parentFlags: CommonFlags,
    parentDecorators: DecoratorNode[] | null,
    isFor: bool = false
  ): VariableDeclaration | null {

    // before: Identifier (':' Type)? ('=' Expression)?

    if (!tn.skipIdentifier()) {
      this.error(
        DiagnosticCode.Identifier_expected,
        tn.range()
      );
      return null;
    }
    var identifier = Node.createIdentifierExpression(tn.readIdentifier(), tn.range());
    if (isIllegalVariableIdentifier(identifier.text)) {
      this.error(
        DiagnosticCode.Identifier_expected,
        identifier.range
      );
    }
    var flags = parentFlags;
    if (tn.skip(Token.EXCLAMATION)) {
      flags |= CommonFlags.DEFINITELY_ASSIGNED;
    }

    var type: TypeNode | null = null;
    if (tn.skip(Token.COLON)) {
      type = this.parseType(tn, true);
    }

    var initializer: Expression | null = null;
    if (tn.skip(Token.EQUALS)) {
      if (flags & CommonFlags.AMBIENT) {
        this.error(
          DiagnosticCode.Initializers_are_not_allowed_in_ambient_contexts,
          tn.range()
        ); // recoverable
      }
      initializer = this.parseExpression(tn, Precedence.COMMA + 1);
      if (!initializer) return null;
    } else if (!isFor) {
      if (flags & CommonFlags.CONST) {
        if (!(flags & CommonFlags.AMBIENT)) {
          this.error(
            DiagnosticCode._const_declarations_must_be_initialized,
            identifier.range
          ); // recoverable
        }
      } else if (!type) { // neither type nor initializer
        this.error(
          DiagnosticCode.Type_expected,
          tn.range(tn.pos)
        ); // recoverable
      }
    }
    var range = Range.join(identifier.range, tn.range());
    if ((flags & CommonFlags.DEFINITELY_ASSIGNED) != 0 && initializer !== null) {
      this.error(
        DiagnosticCode.A_definite_assignment_assertion_is_not_permitted_in_this_context,
        range
      );
    }
    return Node.createVariableDeclaration(
      identifier,
      parentDecorators,
      flags,
      type,
      initializer,
      range
    );
  }

  parseEnum(