@sap/cds-compiler 5.1.2 → 5.3.0

package/lib/gen/BaseParser.js

@@ -0,0 +1,778 @@
+// Base class for generated parser, for redepage v0.1.12
+
+'use strict';
+
+class BaseParser {
+  constructor( lexer, keywords, table ) {
+    this.keywords = keywords;
+    this.table = compileTable( table );
+    this.lexer = lexer;
+    this.tokens = undefined;
+    this.eofIndex = undefined;
+    this.tokenIdx = 0;
+    this.conditionTokenIdx = -1;
+    this.fixKeywordTokenIdx = -1;
+    this.conditionStackLength = -1;
+    this.nextTokenAsId = false;
+
+    this.s = null;
+    this.errorState = null;
+    this.stack = [];            // [{ ruleState, followState, tokenIdx }]
+    this.dynamic_ = {};
+    this.prec_ = null;
+    this.$hasErrors = null;
+    // trace:
+    this.trace = [ -1 ];
+  }
+
+  init() {
+    this.lexer.tokenize( this );
+    this.eofIndex = this.tokens.length - 1;
+    return this;
+  }
+
+  // methods for actions --------------------------------------------------------
+
+  la() {                        // lookahead: complete token
+    return this.tokens[this.tokenIdx];
+  }
+  lb() {                        // look back: complete token
+    return this.tokens[this.tokenIdx - 1];
+  }
+  lr() {                        // return the first token matched by current rule
+    return this.tokens[this.stack[this.stack.length - 1].tokenIdx];
+  }
+
+  // lookahead, error: ----------------------------------------------------------
+
+  l() {                         // lookahead: token type
+    return this.tokens[this.tokenIdx].type;
+  }
+
+  // instead of l() if keyword (reserved and/or unreserved) is in one of the cases
+  lk() {                        // keyword lookahead
+    const la = this.tokens[this.tokenIdx];
+    if (!this.nextTokenAsId)
+      return la.keyword || la.type;
+    this.nextTokenAsId = false;
+    return la.type;
+  }
+
+  e() {                         // error: report and recover
+    const la = this.tokens[this.tokenIdx];
+    const expecting = this._expecting();
+    if (this.trace.length > 1)
+      this._trace( 'detected parsing error,' );
+    this.reportUnexpectedToken_( la );
+    la.parsedAs = 0;
+
+    if (this.conditionTokenIdx === this.tokenIdx &&
+        this.conditionStackLength === this.stack.length &&
+        (la.keyword && expecting[la.keyword] || expecting[la.type])) {
+      // called with/after gc()/gp(), and the token would actually match
+      const { tokenIdx, ruleState } = this.stack.at( -1 );
+      this.s = (this.tokenIdx > tokenIdx) ? this.errorState : ruleState;
+      return false;             // error recovery: ignore condition/precedence
+    }
+
+    if (this.tokenIdx >= this.eofIndex)
+      return this._stopParsing( this.stack.length );
+    // TODO: also sync to what comes next in current rule, at least after rule call,
+    // this way we do not have to do the check of g(0) in re() as we did before 2023-12-07
+    // (not sure yet whether to make it part of recoverInline or recoverPanicMode),
+    if (!this._recoverInline( expecting ))
+      this._recoverPanicMode();
+    return false;
+  }
+
+  // instead of e() in default if lk() had been used and 'Id' is in a non-default case
+  ei() {                // error (after trying to test again as identifier)
+    if (!this.tokens[this.tokenIdx].keyword) // lk() had directly returned the type
+      return this.e();
+    this.nextTokenAsId = true;
+    return false;               // do not execute action after it
+  }
+
+  // goto state: ----------------------------------------------------------------
+
+  // go to end of the rule, in tracing parser: g(0)
+  gr( follow ) {                // intersection follow set for fast exit
+    if (this.stack[this.stack.length - 1].tokenIdx === this.tokenIdx)
+      return this.e();  // match at least one token
+    this.s = 0;
+    // TODO: also have recursive flag in stack: was rule was called recursively?
+    // extra val 'gr' when rule was called when it could reach the rule end
+    const { type: lt, keyword: lk } = this.tokens[this.tokenIdx];
+    if (lk &&            // Id also for unreserved, except after condition failure
+        follow?.[0] === 'Id' && this.keywords[lk] !== false &&
+        this.fixKeywordTokenIdx !== this.tokenIdx ||
+        follow?.includes( lk || lt )) {
+      this._tracePush( [ 'E', true ] );
+      return true;
+    }
+    this._tracePush( [ 'E', 0 ] );
+    // TODO: caching
+    const { dynamic_ } = this;
+    let match;
+    let depth = this.stack.length;
+    while (match == null && --depth) {
+      this.dynamic_ = Object.getPrototypeOf( this.dynamic_ );
+      const { followState } = this.stack[depth];
+      match = this._pred_next( followState, lt, lk, 'E' );
+      this._traceSubPush( match ?? 0 );
+    }
+    this.dynamic_ = dynamic_;
+    // If the parser reaches this point with match = null, even the top-level rule
+    // does not have a required token (typically `EOF`) at the end → the parser
+    // must accept any token → rule exit possible (but no output '✔' in trace).
+    return (match ?? true) || this.e();
+  }
+
+  // go to state; non-tracing parser: `this.s=‹state›` or `this.gr()`
+  g( state, follow ) {
+    if (!(state == null ? this.e() : state || this.gr( follow )))
+      return false;
+    this.s = state;             // is just `this.s=‹state›` in non-trace parser
+    this._tracePush( this.s );
+    return true;
+  }
+
+  // instead of gi() for `Id_all`
+  giA( state, follow ) { // go to state (after trying to test again as identifier)
+    if (!this.tokens[this.tokenIdx].keyword) // lk() had directly returned the type
+      return this.g( state, follow );
+    this.nextTokenAsId = true;
+    return false;               // do not execute action after it
+  }
+
+  // instead of g() in default if lk() had been used and 'Id' is in a non-default case
+  gi( state, follow ) { // go to state (after trying to test again as identifier)
+    const lk = this.tokens[this.tokenIdx].keyword;
+    // As opposed to ei(), we also check for reserved keywords here; this way, we
+    // do not have to add reserved keywords from the follow-set to the `switch`.
+    if (!lk || this.keywords[lk] === false) // TODO: consider fixKeywordTokenIdx ?
+      return this.g( state, follow );
+    this.nextTokenAsId = true;
+    return false;               // do not execute action after it
+  }
+
+  // instead of gi() at rule end (RuleEnd_ in follow-set) for `Id_restricted`
+  giR( state, follow ) { // go to state (after trying to test again as identifier)
+    const lk = this.tokens[this.tokenIdx].keyword;
+    if (!lk || this.keywords[lk] === false || this._keyword_after_rule( lk ))
+      return this.g( state, follow );
+    this.nextTokenAsId = true;
+    return false;               // do not execute action after it
+  }
+
+  // instead of g() in a non-default case if there is a LL1 conflict
+  gP( state ) {                // goto state with standard weak-conflict prediction
+    return this.lP() && this.g( state );
+  }
+
+  // match and consume token: ---------------------------------------------------
+
+  m( state, token ) {           // match token = compare and consume
+    return (this.tokens[this.tokenIdx].type === token)
+      ? this.c( state )
+      : this.e();
+  }
+
+  // instead of m() for identifiers via `Id` or `Id_restricted`
+  mi( state, ident = true ) {   // match identifier token
+    return (this.tokens[this.tokenIdx].type === 'Id')
+      ? this.ci( state, ident )
+      : this.e();
+  }
+
+  // instead of mi() for `Id_all`
+  miA( state, ident = true ) {  // match identifier token
+    return (this.tokens[this.tokenIdx].type === 'Id')
+      ? this.ciA( state, ident )
+      : this.e();
+  }
+
+  // instead of m() for reserved keywords or unreserved without conflict:
+  mk( state, token ) {          // match keyword token
+    return (this.tokens[this.tokenIdx].keyword === token)
+      ? this.ck( state )
+      : this.e();
+  }
+
+  c( state, parsedAs = 'token' ) { // consume token
+    const la = this.tokens[this.tokenIdx];
+    la.parsedAs = parsedAs;
+    if (this.tokenIdx < this.eofIndex) ++this.tokenIdx;
+    // TODO: handle identifier-including-reserved-words later (e.g. for id after a `.`)
+    this.s = state;
+    this.errorState = state;
+    if (this.constructor.tracingParser)
+      this._trace( `consume ${ tokenFullName( la, ' as ' ) },`, la );
+    return true;
+  }
+
+  // instead of c() for identifiers, used both with l() and lk()
+  ci( state, ident = 'ident' ) {   // consume identifier token
+    const la = this.tokens[this.tokenIdx];
+    if (this.keywords[la.keyword] === false)
+      this.reportReservedWord_( la );
+    // with error recovery: use that (consider this having a good score)
+    return this.c( state, ident )
+  }
+
+  // instead of ci() for `Id_all`, used both with l() and lk()
+  ciA( state, ident = 'ident' ) {  // consume identifier token, the "All" variant
+    return this.c( state, ident )
+  }
+
+  // instead of c() for reserved or unreserved without conflict, requires lk()
+  ck( state ) {                 // consume keyword token
+    return this.c( state, 'keyword' )
+  }
+
+  // instead of ck() if there is a LL1 conflict
+  ckP( state, first2 ) {      // consume unreserved keyword with weak conflict
+    return this.lP( first2 ) && this.ck( state );
+  }
+
+  // for parser token or token set via `/`
+  ckA( state ) {
+    // if it really should be considered an Id, `set this.la().parsedAs` yourself
+    return this.c( state, (this.l() === 'Id' ? 'keyword' : 'token') );
+  }
+
+  skipToken_() {
+    ++this.tokenIdx;
+  }
+
+  // condition and precedence handling ------------------------------------------
+
+  // state must match the goto-state of the default (there must be no default
+  // action), or null for error, lP() must have been used before.  There is no
+  // “or Id” behavior other than via gpP()
+
+  // “go if user condition fails”
+  gc( state, cond ) {
+    if (this.conditionTokenIdx === this.tokenIdx &&
+        this.conditionStackLength === this.stack.length) {
+      this._tracePush( [ 'C' ] );
+      return true;              // error recovery: ignore condition
+    }
+    this.conditionTokenIdx = this.tokenIdx;
+    this.conditionStackLength = this.stack.length;
+    // TODO: let this[cond]( true ) return recovery badness in error case
+    const fail = !this[cond]( true );
+    if (this.constructor.tracingParser)
+      this._tracePush( [ 'C', cond, !fail ] );
+    // TODO TOOL: in this case, the default case must not have actions (tool must
+    // add state if it does)
+    if (fail) {                 // TODO: extra gcK() method instead of check below
+      // TODO: extra method necessary for academic case
+      // ( 'unreserved' 'foo' | <cond> Id 'bar' )` with input `unreserved bar`
+      const { keyword } = this.la();
+      if (keyword && this.table[keyword])
+        this.fixKeywordTokenIdx = this.tokenIdx;
+    }
+    return !fail || this.g( state ) && false;
+  }
+
+  ec( cond ) {
+    return this.gc( null, cond );
+  }
+
+  // “go if precedence condition fails”
+  gp( state, prec, mode ) {
+    if (this.conditionTokenIdx === this.tokenIdx &&
+        this.conditionStackLength === this.stack.length) {
+      this._tracePush( [ 'C' ] );
+      return true;              // error recovery: ignore condition
+    }
+    this.conditionTokenIdx = this.tokenIdx;
+    this.conditionStackLength = this.stack.length;
+    const parentPrec = this.stack.at( -1 ).prec ?? -Infinity;
+    const fail = prec <= parentPrec ||
+          this.prec_ != null && // previous op parsed by current rule
+          // <…,postfix> || <…,assoc=none>, <…,postfix=once>:
+          (mode === 'post' && prec > this.prec_ || mode === 'none' && prec >= this.prec_);
+    if (this.constructor.tracingParser) {
+      const pp = (parentPrec === -Infinity) ? '-∞' : parentPrec;
+      const tp = (this.prec_ == null) ? '∞' : this.prec_;
+      const suffix = mode === 'post' && `≤${ tp }` || mode === 'none' && `<${ tp }`;
+      this._tracePush( [ 'C', `${ pp }<${ prec }${ suffix || '' }`, !fail ] );
+    }
+    if (fail) {                 // TODO: extra gcK() method instead of check below
+      // TODO: extra method necessary for academic case
+      // ( 'unreserved' 'foo' | <cond> Id 'bar' )` with input `unreserved bar`
+      const { keyword } = this.la();
+      if (keyword && this.table[this.s][keyword])
+        this.fixKeywordTokenIdx = this.tokenIdx;
+      return this.g( state ) && false;                // TODO: reset this.prec_ ?
+    }
+    this.prec_ = (mode === 'right') ? prec - 1 : prec; // -1: <…,assoc=right>, <…,prefix>
+    return true;
+  }
+
+  ep( prec, mode ) {
+    return this.gp( null, prec, mode );
+  }
+
+  // rule start, end and call: --------------------------------------------------
+
+  rule_( state, followState = -1 ) { // start rule
+    this.stack.push( {
+      ruleState: state,
+      followState,
+      tokenIdx: this.tokenIdx,
+      prec: this.prec_,
+    } );
+    this.dynamic_ = Object.create( this.dynamic_ );
+    this.s = state;
+    this.prec_ = null;
+    this.conditionTokenIdx = -1;
+    this.errorState ??= state;
+    this._trace( [ state, 'call rule', '', ' at alt start', -1 ] );
+  }
+
+  exit_( rulePrecMethod ) {     // exit rule
+    if (this.s)
+      throw Error( `this.s === ${ this.s } // illegally set by action, or runtime/generator bug` );
+    this.dynamic_ = Object.getPrototypeOf( this.dynamic_ );
+    const caller = this.stack.pop();
+    this.s = caller.followState;
+    this.prec_ = (rulePrecMethod) ? this[rulePrecMethod]( caller ) : caller.prec;
+    this._trace( [ caller.ruleState, 'exit rule', '', '', 1 ] );
+    //if (this.errorState == 0 || this.s != null)
+    this.errorState = this.s;
+    // execute actions if not in error recovery (pass-through) and at least one
+    // token has been matched in rule:
+    return this.s != null && this.tokenIdx > caller.tokenIdx;
+  }
+
+  // predicate used before rule call if with LL(1) conflict, 'Id' in other case
+  lP( first2 ) {             // only start rule if this predicate returns true
+    // nothing to check if not a non-reserved keyword:
+    const { keyword: lk1 } = this.tokens[this.tokenIdx];
+    if (!lk1 || !this.keywords[lk1])
+      return true;
+
+    const { type: lt2, keyword: lk2 } = this.tokens[this.tokenIdx + 1];
+    // Argument first2 is just a performance hint with ckP():
+    if (lk2 && first2?.[0] === 'Id' && this.keywords[lk2] !== false ||
+        first2?.includes( lk2 || lt2 )) {
+      this._tracePush( [ 'P', true ] );
+      return true;
+    }
+    this._tracePush( [ 'P' ] );
+    // now check it dynamically:
+    let cmd = this.table[this.s][lk1];
+    if (cmd[2] !== 1)
+      throw Error( `Unexpected command '${ cmd?.[0] }' without prediction at state ${ this.s } for ‘${ lk1 }’` );
+
+    // if not the keyword match, the command is “goto” or “rule call”
+    const nextState = (cmd[0] === 'ck') ? cmd[1] : this._pred_keyword( cmd[1], lk1 );
+
+    ++this.tokenIdx;            // for user lookahead fns and conditions
+    const match = this._pred_next( nextState, lt2, lk2, 'P' );
+    --this.tokenIdx;
+
+    const r = match ?? true;
+    if (match == null)
+      this._traceSubPush( 0 );
+    if (lt2 === 'IllegalToken')
+      return true
+    // TODO: instead of this IllegalToken test, implement a “confirm unreserved
+    // keyword as Id” prediction which tests whether the token after the then-Id
+    // matches.
+    this._traceSubPush( r );
+    if (!r)
+      this.nextTokenAsId = true;
+    return r;
+  }
+
+  // Now the helper methods =====================================================
+
+  // Standard weak-conflict predicate -------------------------------------------
+
+  _pred_keyword( state, keyword ) {
+    // returns state after matching the first token as keyword, for lP()
+    while (state) {
+      this._traceSubPush( state );
+      let cmd = this.table[state];
+      if (!Array.isArray( cmd ))
+        cmd = cmd[keyword] || cmd.Id || cmd[''];
+      switch (cmd[0]) {
+        case 'ck': case 'mk':
+          return cmd[1];        // state after token consumption
+        case 'g':               // TODO: another rule call?
+          break;
+        default:
+          if (typeof cmd[0] !== 'number')
+            throw Error( `Unexpected command ${ cmd[0] } at state ${ this.s }` );
+      }
+      state = cmd[1];
+    }
+    // reached end of rule without having consumed a token
+    throw Error( 'Not supported: option for unreserved keywords in follow set' );
+  }
+
+  _pred_next( state, type, keyword, mode ) {
+    let hasEnteredRule = false;
+    while (state) {
+      this._traceSubPush( state );
+      let cmd = this.table[state];
+      if (!Array.isArray( cmd )) {
+        const lookahead = cmd[' lookahead'];
+        cmd = lookahead
+          ? cmd[this[lookahead]( mode )] || cmd['']
+          : keyword && cmd[keyword] || cmd[type] || cmd[''];
+      }
+      switch (cmd[0]) {
+        case 'c': case 'ck': case 'ciA': case 'ckA': // TODO: re-check ckA
+          return true;
+        case 'ci':
+          if (!keyword ||
+              this.keywords[keyword] !== false && this.fixKeywordTokenIdx !== this.tokenIdx)
+            return true;
+          cmd = this.table[state]['']; // is currently always 'g' or 'e'
+          break;
+        case 'm':
+          return type === cmd[2];
+        case 'mi':
+          return type === 'Id' &&
+            (!keyword ||
+             this.keywords[keyword] !== false && this.fixKeywordTokenIdx !== this.tokenIdx);
+        case 'miA':
+          return type === 'Id';
+        case 'mk':
+          return keyword === cmd[2];
+        case 'g': case 'e':
+          break;
+        default:
+          if (typeof cmd[0] !== 'number')
+            throw Error( `Unexpected command ${ cmd[0] } at state ${ this.s }` );
+          // If the parser enters a rule, reaching the rule end (can happen with
+          // option `minTokensMatched`) means "no match".
+          hasEnteredRule = true;
+          // If we want to support conditions before matching the first token in a
+          // rule, we would have to handle `this.stack` and `this.dynamically_`.
+      }
+      // We could optimize with rule call - only 'Id' must be further investigated
+      state = cmd[1];
+    }
+    // If invalid state, the second token does not match, e.g. for `VIRTUAL +`
+    // or `VIRTUAL §` (with IllegalToken):
+    if (state == null)
+      return false;
+
+    // Otherwise, the parser could end the rule after having matched the keyword
+    // with prediction.  TODO: as we do not look behind the current rule for the
+    // prediction, the tool can normally omit the prediction (and output a
+    // message), no so with `ruleStartingWithUnreserved`.  We will rather look
+    // behind the current rule _after_ having decided that the token is to be
+    // matched as identifier.
+    return !hasEnteredRule && null; // let caller decide how to interpret this
+  }
+
+  _keyword_after_rule( keyword ) {
+    // TODO: this is a slow implementation - do dedicated traversal later
+    // It is used in giR() only and this is currently used just once.
+    // TODO: using mode = 'R' and tracing R(…)
+    // TODO: investigate why this was not written before adding
+    // `<default=fallback>` in rule `fromRefWithOptAlias`.
+    return this._expecting()[keyword];
+  }
+
+  // Set of expected tokens: for error reporting and recovery -------------------
+
+  // Calculate array of expected tokens
+  _expecting( errorState, length ) {
+    // Remark: rules must not have been exited too early, see _expecting call in re()
+    const stack = this.stack.slice( 0, length || this.stack.length );
+      // Immediately exit rules when no tokens have yet been consumed:
+    let caller = stack.at( -1 );
+    while (stack.length && this.tokenIdx === caller.tokenIdx) {
+      --stack.length;
+      caller = stack.at( -1 );
+    }
+    // Now calculate dictionary of expected tokens:
+    const expecting = Object.create(null);
+    let state = errorState ?? this.errorState;
+    // At potential rule end, we must add follow sets of outer rules
+    // TODO: we also need to unravel this.dynamic_ for translateParserToken_()
+    while ((!state || this._exp_collect( expecting, this.table[state] )) && stack.length)
+      state = stack.pop().followState;
+    return expecting;
+  }
+
+  // TODO: use iterative alg, no recursive call, return state instead -----------
+  // Add expected tokens to dictionary `expecting` starting at command `cmd`.
+  // Return true if the rule end is reached, i.e. we also need to add the expected
+  // tokens at the follow state of the current rule.  Argument `prop` is the token
+  // name for `cmd` in a decision.
+  _exp_collect( expecting, cmd, prop ) {
+    if (prop != null)
+      cmd = cmd[prop];
+    if (!Array.isArray( cmd )) {
+      let reachedRuleEnd = false;
+      for (const tok in cmd) {
+        if (Object.hasOwn( cmd, tok ) && tok.charAt(0) !== ' ' &&
+            this._exp_collect( expecting, cmd, tok ))
+          reachedRuleEnd = true;
+      }
+      return reachedRuleEnd;
+    }
+    switch (cmd[0]) {
+      case 'c': case 'ck':
+        expecting[prop] = true;
+        return false;
+      case 'ckA':
+        for (const tok of this.translateParserToken_( prop ))
+          expecting[tok] = true;
+        return false;
+      case 'm': case 'mk':
+        expecting[cmd[2]] = true;
+        return false;
+      case 'ci': case 'ciA': case 'mi': case 'miA':
+        expecting['Id'] = true;
+        return false;
+      case 'g': case 'gi':
+        if (!cmd[1])
+          return cmd[1] === 0;
+        //(this.stack[this.stack.length - 1].tokenIdx === this.tokenIdx);
+        // TODO: add some assertion in generation that a decision has no two `g`s
+        // to the same state (both in cases and default)
+        // UPDATE: no, there will be at least gP()s
+        // TOOD: do properly for (...)+ - currently, the token for directly
+        // exiting the rule is also collected
+        return this._exp_collect( expecting, this.table[cmd[1]] );
+      default:
+        // a called rule must match at least one token → after having called a
+        // rule, do not collect expecting tokens after exiting the rule
+        if (typeof cmd[0] === 'number')
+          this._exp_collect( expecting, this.table[cmd[1]] );
+        return false;
+    }
+  }
+
+  translateParserToken_( token ) {
+    return [ token ];
+  }
+
+  // Error recovery -------------------------------------------------------------
+
+  _recoverInline( expecting ) {
+    const { type: lt2, keyword: lk2 } = this.tokens[this.tokenIdx + 1];
+    if (!(lk2 && expecting[lk2] || expecting[lt2]))
+      return false;
+
+    // Immediately exit rules (except start) when no tokens have yet been consumed:
+    let { length } = this.stack;
+    while (--length > 0) {
+      const caller = this.stack[length];
+      // matched tokens in rule: found rule
+      if (this.tokenIdx > caller.tokenIdx)
+        break;
+      caller.followState = null;
+    }
+
+    if (++length < this.stack.length) {
+      this.s = null;
+      this.stack[length].followState = this.errorState;
+      // assume the erroneous token to be skipped before having called the rule:
+      ++this.stack[length].tokenIdx
+      this.errorState = null;
+    }
+    else {                      // no rule to leave immediately
+      this.s = this.errorState;
+    }
+
+    this.skipToken_();
+    if (this.constructor.tracingParser)
+      this._trace( [ this.stack[length - 1].ruleState, 'recover inside rule' ] );
+    return true;              // to be re-checked with actions
+  }
+
+  _recoverPanicMode() {
+    const { length } = this.stack;
+    // Panic mode: resume at token in then-expecting set:
+    const followSets = { EOF: 0 };
+    for (let idx = 0; idx < length; ++idx) {
+      const caller = this.stack[idx];
+      const exp = this._expecting( caller.followState, length );
+      for (const t of Object.keys( exp )) {
+        // no sync to 'Id' - TODO: provide grammar and rule options
+        if (t !== 'Id')         // TODO: see below
+          followSets[t] = idx;
+      }
+    }
+    const tokenIdx = this.tokenIdx;
+    // console.log( this.la().location.toString(), followSets )
+    while (this.tokenIdx <= this.eofIndex) {
+      // TODO: exclude reserved words for test with this.l()
+      const depth = followSets[this.lk()] || followSets[this.l()];
+      // TODO: handle Id here
+      if (depth != null)
+        return this._error_panic( depth, length, tokenIdx );
+      this.skipToken_();
+    }
+    throw Error( 'EOF was added...' );
+  }
+
+  _error_panic( low, high, tokenIdx ) {
+    this.s = null;              // mark current rule for exit
+    if (this.constructor.tracingParser) {
+      this._trace( this.stack.length - 1 > low
+                   ? `recover by exiting ${ this.stack.length - low} rules prematurely,`
+                   : 'recover by exiting current rule prematurely,' );
+    }
+    // eventually mark outer rules for exit:
+    // TODO: re-check for rule calls which are at the optional rule end:
+    //   x: 'x not'; b: 'b'? x {console.log('x→b')} 'b'?; a: b {console.log('b→a')} 'a'
+    // with start rule `a` and input `x a`: output should be x→b + b→a
+    // with start rule `a` and input `b a`: output should be b→a
+    //
+    // → the rule is: if a rule can continue at the specified state and has
+    // matched at least one token, then its action is executed, otherwise not
+    for (let idx = low + 1; idx < high; ++idx) {
+      this.stack[idx].followState = null;
+    }
+    const resume = this.stack[low];
+    if (tokenIdx === resume.tokenIdx) // no tokens matched other than those by skipping
+      resume.tokenIdx = this.tokenIdx; // make exit_() return false
+    this.errorState = null;
+  }
+
+  _stopParsing( idx ) {
+    if (this.constructor.tracingParser) {
+      this.log( this.la().location.toString() + ':', 'Info:',
+                `leave all active ${ idx } rules prematurely, stop parsing` );
+    }
+    // TODO: run this.skipToken_() on all remaining tokens?  Does ANTLR consumes
+    // those in error recovery mode?  Probably not.
+    for (const c of this.stack)
+      c.followState = null;
+    this.errorState = null;
+    this.s = null;
+    return false;
+  }
+
+  // small methods --------------------------------------------------------------
+
+  log( ...args ) {
+    console.log( ...args );
+  }
+
+  expectingForMessage_( sep = ',' ) {
+    return Object.keys( this._expecting() ).map( tokenName ).sort().join( sep );
+  }
+
+  reportError_( location, text ) {
+    this.$hasErrors = true;
+    this.log( `${ location }: Error:`, text );
+  }
+
+  reportUnexpectedToken_( token ) {
+    this.reportError_( token.location,
+                       `unexpected token ${ tokenFullName( token, ': ' ) } - expecting: ` +
+                       this.expectingForMessage_() );
+  }
+
+  reportReservedWord_( token ) {
+    this.reportError_( token.location,
+                       `unexpected reserved word ‘${ token.text }’ - expecting: ` +
+                       this.expectingForMessage_() );
+  }
+
+  errorAndRecoverOutside( token, text ) { // TODO: re-check
+    this.reportError_( token.location, text );
+    ++this.tokenIdx;
+    return this._recoverPanicMode( this.stack.length );
+  }
+
+  _tracePush( state ) {
+    if (this.constructor.tracingParser)
+      this.trace.push( state ?? '⚠' );
+  }
+  _traceSubPush( state ) {
+    if (this.constructor.tracingParser)
+      this.trace.at(-1).push( state );
+  }
+  traceAction( location ) {     // will be put into tracing parser
+    this._trace( 'execute action,', { location } );
+  }
+
+  _trace( msg, la ) {
+    if (!this.constructor.tracingParser)
+      return;
+    if (Array.isArray( msg ))
+      msg = this._rule( ...msg );
+    this.trace.push( this.s ?? '⚠' );
+    this.log( (la || this.la()).location.toString() + ':',
+              'Info:', msg, 'states:', this.trace.map( traceStep ).join( ' → ' ) );
+    this.trace = [ this.s ?? '⚠' ];
+  }
+
+  // TODO: rename to ruleName_, leaving out the msg stuff
+  _rule( state, msg, post = '', postOther = post, depthDiff ) {
+    const start = --state;
+    while (typeof this.table[state] !== 'string')
+      --state;
+    const { length } = this.stack;
+    const depth = depthDiff ? `, depth ${ length + depthDiff } → ${ length }` : '';
+    return `${ msg } “${ this.table[state] }”${ state < start ? postOther : post }${ depth },`;
+  }
+
+  inSameRule_( lowState, highState ) {
+    if (lowState > highState)
+      [ lowState, highState ] = [ highState, lowState ];
+    while (lowState < highState) {
+      if (typeof this.table[++lowState] === 'string') // rule boundary
+        return false;
+    }
+    return true;
+  }
+
+}
+
+function traceStep( step ) {
+  if (!Array.isArray( step ))
+    return step;
+  const result = { true: '✔', false: '✖' }[step.at( -1 )] ?? '';
+  const intro = (typeof step[1] === 'number') ? '→' : '';
+  const arg = step.slice( 1, result ? -1 : undefined ).join( '→' );
+  return `${ step[0] }(${ intro }${ arg })${ result }`;
+}
+
+function tokenName( type ) {
+  if (typeof type !== 'string')
+    type = (!type.parsedAs || type.parsedAs === 'keyword') && type.keyword || type.type;
+  return (/^[A-Z]+/.test( type )) ? `‹${ type }›` : `‘${ type }’`;
+}
+
+function tokenFullName( token, sep ) {
+  return (token.parsedAs && token.parsedAs !== 'keyword' && token.parsedAs !== 'token' ||
+          token.type !== 'Id' && token.type !== token.text && token.text)
+    ? `‘${ token.text }’${ sep }${ tokenName( token ) }`
+    : tokenName( token );
+}
+
+function compileTable( table ) {
+  if (table.$compiled)
+    return table;
+  for (const line of table) {
+    if (typeof line !== 'object' || Array.isArray( line ))
+      continue;
+    const cache = Object.create( null ); // very sparse array
+    for (const prop of Object.keys( line )) {
+      const alt = line[prop];
+      if (!Array.isArray( alt ) && prop.charAt(0) !== ' ') // string or number
+        line[prop] = (typeof alt === 'string') ? line[alt] : (cache[alt] ??= [ 'g', alt ]);
+    }
+    if (!line[''])
+      line[''] = [ 'e' ];
+  }
+  table.$compiled = true;
+  return table;
+}
+
+module.exports = BaseParser;