@sap/cds-compiler 5.1.0 → 5.2.0

package/lib/gen/BaseParser.js

@@ -0,0 +1,720 @@
+// Base class for generated parser, for redepage v0.1.7
+
+'use strict';
+
+class BaseParser {
+  constructor( lexer, keywords, table ) {
+    this.keywords = keywords;
+    this.table = table;
+    this.lexer = lexer;
+    this.tokens = undefined;
+    this.eofIndex = undefined;
+    this.tokenIdx = 0;
+    this.conditionTokenIdx = -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.parsed = 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._traceIdOrPred( '-Id' );
+    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.conditionTokenIdx !== this.tokenIdx ||
+        follow?.includes( lk || lt ))
+      return true;
+
+    // Do we have possibilities to stay in rule with error recovery?
+    const expecting = this._expecting( 0 ); // dynamic follow-set
+    // TODO: improve performance: no check needed for a rule-end directly after
+    // a rule end: the second is definitely successful if the first was.
+    // TODO: do not calculate the complete dynamic follow-set, provide dedicated
+    // function to test whether the next token is valid
+    // we might also cache the result in the stack
+    // ok: lk or lt -> lk=e or (lt=e && (not cond || not keyw)
+    if (expecting[lk] ||
+        // if at failed condition, do not make Id in follow end the rule
+        // (assuming that there is no condition for `Id` at optional rule end):
+        expecting[lt] && !(lk && this.conditionTokenIdx === this.tokenIdx))
+      return true;
+
+    return 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._traceIdOrPred( '-Id' );
+    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)
+      return this.g( state, follow );
+    this._traceIdOrPred( '-Id' );
+    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._traceIdOrPred( '-Id' );
+    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, parsed = 'token' ) { // consume token
+    const la = this.tokens[this.tokenIdx];
+    la.parsed = parsed;
+    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
+  ckA( state ) {
+    // if it really should be considered an Id, `set this.la().parsed` yourself
+    return this.c( state, (this.l() === 'Id' ? 'keyword' : 'token') );
+  }
+
+  // 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)
+      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( `${ fail ? '¬' : '✓' } ${ cond }` );
+    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( `(${ this._prec })!` );
+      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( `${ fail ? '¬' : '✓' }(${ pp } < ${ prec }${ suffix || '' })` );
+    }
+    if (fail)
+      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
+    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 ))
+      return true;
+
+    // nothing to check if not a non-reserved keyword:
+    const { keyword: lk1 } = this.tokens[this.tokenIdx];
+    if (!lk1 || !this.keywords[lk1])
+      return true;
+
+    // now check it dynamically:
+    let cmd = this.table[this.s][lk1];
+    if (typeof cmd === 'string')
+      cmd = this.table[this.s][cmd];
+    if (!Array.isArray( cmd ) || cmd[2] !== 1)
+      throw Error( `Unexpected command '${ cmd?.[0] }' without prediction at state ${ this.s } for ‘${ lk1 }’` );
+
+    this._traceIdOrPred( '-P1' );
+    const nextState = (cmd[0] === 'ck') ? cmd[1] : this._pred_keyword( cmd[1], lk1 );
+
+    if (this._pred( nextState, lt2, lk2 ))
+      return true;
+    if (lt2 === 'IllegalToken') // TODO: keep?
+      return true
+    // TODO: instead of this IllegalToken test, set tokenIndex+nextState for extra
+    // expected calculation if parser fails after Id - we would then also add the
+    // expected tokens after keyword-interpretation
+    this._traceIdOrPred( '-Id' );
+    this.nextTokenAsId = true;
+    return false;               // do not execute action after it
+  }
+
+  // Now the helper methods =====================================================
+
+  // Standard weak-conflict predicate -------------------------------------------
+  // Weak (and fast) single-step walk and test (no rule exit, start is fine): for
+  // pg(), pr(). The main point is that we do not (again) consider predicates.
+  // Currently just tests against the token _type_ of the next token, not its
+  // specific keyword; see comments below for details.
+
+  _pred( nextState, lt2, lk2 ) {
+    if (nextState) {
+      // return this._pred_test( nextState, lt2 );
+      const r = this._pred_next( nextState, lt2, lk2 );
+      this._tracePush( this.s );
+      return r;
+    }
+    // dubious weak conflict at end of rule:
+    this._traceIdOrPred( '-P0' );
+    this._tracePush( this.s );
+    return true;                // dubious
+  }
+
+  _pred_keyword( state, keyword ) {
+    // returns next state for first token as keyword, for lP()
+    while (state) {
+      this._tracePush( `${ state }-P1` );
+      let cmd = this.table[state];
+      if (!Array.isArray( cmd )) {
+        const alt = cmd[keyword] || cmd.Id; // Id to cover optimized rule call
+        cmd = (typeof alt === 'string')
+          ? cmd[alt]
+          : typeof alt === 'number' && [ 'g', alt ] || alt || [ 'g', cmd[''] ];
+      }
+      switch (cmd[0]) {
+        case 'ck': case 'mk':
+          return cmd[1];        // state after token consumption
+        case 'g':
+          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 ) {
+    while (state) {
+      this._tracePush( `${ state }-P2` );
+      let cmd = this.table[state];
+      if (!Array.isArray( cmd )) {
+        const alt = keyword && cmd[keyword] || cmd[type];
+        cmd = (typeof alt === 'string')
+          ? cmd[alt]
+          : typeof alt === 'number' && [ 'g', alt ] || alt || [ 'default', cmd[''] ];
+      }
+      switch (cmd[0]) {
+        case 'c': case 'ck': case 'ciA':
+          return true;
+        case 'm':
+          return type === cmd[2];
+        case 'mi': case 'ci':
+          return type === 'Id' && (!keyword || this.keywords[keyword] !== false);
+        case 'miA':
+          return type === 'Id';
+        case 'mk':
+          return keyword === cmd[2];
+      }
+      // We could optimize with rule call - only 'Id' must be further investigated
+      state = cmd[1];
+    }
+    this._traceIdOrPred( 'f' );
+    this._tracePush( this.s );
+    // TODO: really false, not true?
+    // `false` means that la1 is not considered an unreserved keyword.  This is
+    // correct (consider `e: Association @Anno`), but probably not optimal for
+    // error reporting (consider `e: Association +`).  Improving that is more
+    // costly, as we really need to consider rule exits → stack.
+    return false;
+  }
+
+  _keyword_after_rule( keyword ) {
+    // TODO: this is a slow implementation - do dedicated traversal later
+    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[(typeof cmd[prop] === 'string') ? cmd[prop] : prop];
+    }
+    if (typeof cmd === 'number') // ‹followState› = short form for this.g(‹followState›)
+      cmd = [ 'g', cmd ];
+
+    if (!Array.isArray( cmd )) {
+      let reachedRuleEnd = false;
+      for (const tok in cmd) {
+        if (Object.hasOwn( cmd, tok ) && 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 ) || [ 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 null;
+  }
+
+  // Error recovery -------------------------------------------------------------
+
+  _recoverInline( expecting ) {
+    // Inline error recovery - single token deletion (TODO later: also try more !)
+    // token position has been advanced before calling this function
+    if (!expecting[this.lk()] && !expecting[this.l()])
+      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 (other than the one skipped one) in rule: found rule
+      if (this.tokenIdx - 1 > 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;
+    }
+
+    if (this.constructor.tracingParser)
+      this._trace( [ this.stack[length - 1].ruleState, 'recover inside rule' ] );
+    return true;              // to be re-checked with actions
+  }
+
+  _recoverPanicMode() {
+    --this.tokenIdx
+    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.tokenIdx;
+    }
+    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 ) {
+    --this.tokenIdx;
+    if (this.constructor.tracingParser) {
+      this.log( this.la().location.toString() + ':', 'Info:',
+                `leave all active ${ idx } rules prematurely, stop parsing` );
+    }
+    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 ?? '⚠' );
+  }
+  _traceIdOrPred( suffix ) {
+    if (this.constructor.tracingParser)
+      this.trace[this.trace.length - 1] += suffix;
+  }
+  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.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 tokenName( type ) {
+  if (typeof type !== 'string')
+    type = (!type.parsed || type.parsed === 'keyword') && type.keyword || type.type;
+  return (/^[A-Z]+/.test( type )) ? `‹${ type }›` : `‘${ type }’`;
+}
+
+function tokenFullName( token, sep ) {
+  return (token.parsed && token.parsed !== 'keyword' && token.parsed !== 'token' ||
+          token.type !== 'Id' && token.type !== token.text && token.text)
+    ? `‘${ token.text }’${ sep }${ tokenName( token ) }`
+    : tokenName( token );
+}
+
+module.exports = BaseParser;