@sap/cds-compiler 5.1.2 → 5.3.0

package/lib/parsers/AstBuildingParser.js

@@ -0,0 +1,1290 @@
+'use strict';
+
+const BaseParser = require( '../gen/BaseParser' );
+
+const { Location } = require( '../base/location' );
+const { dictAdd, dictAddArray } = require('../base/dictionaries');
+const { functionsWithoutParens } = require('../base/builtins');
+
+const { pathName } = require('../compiler/utils');
+const { quotedLiteralPatterns, specialFunctions } = require('../compiler/builtins');
+const parserTokens = { // TODO: precompile into specialFunction
+  GenericIntro: 'intro',
+  GenericExpr: 'expr',
+  GenericSeparator: 'separator',
+};
+
+const { parseMultiLineStringLiteral } = require('../language/multiLineStringParser');
+const { normalizeNewLine, normalizeNumberString } = require('../language/textUtils');
+const { parseDocComment } = require('../language/docCommentParser');
+
+const $location = Symbol.for('cds.$location');
+
+const extensionDicts = {
+  elements: true, enum: true, params: true, returns: true,
+};
+
+const keywordTypeNames = {
+  association: 'cds.Association', composition: 'cds.Composition',
+};
+
+const queryOps = {
+  SELECT: 'query',
+  union: 'query',
+  intersect: 'query',
+  except: 'query',
+  minus: 'query',
+};
+
+const PRECEDENCE_OF_IN_PREDICATE = 10;
+const PRECEDENCE_OF_EQUAL = 10;
+
+class AstBuildingParser extends BaseParser {
+  constructor( lexer, keywords, table, options, messageFunctions ) {
+    super( lexer, keywords, table ); // lexer has file
+    this.options = options;
+    this.$messageFunctions = messageFunctions;
+    this.docComments = [];
+    this.docCommentIndex = 0;
+    this.comments = [];
+
+    this.afterBrace$ = -1;
+    this.topLevel$ = -1;
+  }
+
+  // messages, conditions and other parsing-specific things ---------------------
+  error( id, location, args = {}, text = null ) {
+    // eslint-disable-next-line cds-compiler/message-call-format
+    return this.$messageFunctions.error( id, location?.location || location, args, text );
+  }
+  message( id, location, args = {}, text = null ) {
+    // eslint-disable-next-line cds-compiler/message-call-format
+    return this.$messageFunctions.message( id, location?.location || location, args, text );
+  }
+  warning( id, location, args = {}, text = null ) {
+    // eslint-disable-next-line cds-compiler/message-call-format
+    return this.$messageFunctions.warning( id, location?.location || location, args, text );
+  }
+  info( id, location, args = {}, text = null ) {
+    // eslint-disable-next-line cds-compiler/message-call-format
+    return this.$messageFunctions.info( id, location?.location || location, args, text );
+  }
+
+  expectingArray() {
+    const expecting = this._expecting();
+    let array = Object.keys( expecting );
+    // compatibility: replace true+false by Boolean
+    if (expecting.true && expecting.false)
+      array = [ 'Boolean', ...array.filter( n => n !== 'true' && n !== 'false' ) ];
+    return array.map( antlrName )
+      .sort( (a, b) => (tokenPrecedence(a) < tokenPrecedence(b) ? -1 : 1) );
+  }
+
+  reportUnexpectedToken_( token ) {
+    const expecting = this.expectingArray();
+    const err = this.error( 'syntax-unexpected-token', token,
+                            { offending: antlrName( token ), expecting } );
+    // No 'unwanted' variant, no 'syntax-missing-token'
+    err.expectedTokens = expecting;
+  }
+  reportReservedWord_( token ) {
+    const err = this.message( 'syntax-unexpected-reserved-word', token,
+                              { code: token.text, delimited: token.text } );
+    // TODO: at least if one expected keyword is similar, mention expected set
+    err.expectedTokens = this.expectingArray();
+  }
+
+  setPrecInCallingRule() {
+    const caller = this.stack.at( -1 );
+    if (this.inSameRule_( caller.ruleState, caller.followState ))
+      caller.prec = this.prec_;
+  }
+
+  tableAlias() {
+    const { keyword } = this.la();
+    if (keyword && this.keywords[keyword])
+      return false;
+    if (this.lb().type !== ')')
+      return true;
+    // after ')' we need to check the expression category = must not already be a
+    // table, like a simplified version of `<prec=-2, postfix=once>` which we
+    // cannot do additionally
+    if (this.prec_ != null && this.prec_ <= -2)
+      return false;
+    this.prec_ = -2;
+    return true;
+  }
+
+  prepareSpecialFunction() {
+    const func = this.tokens[this.tokenIdx - 2].keyword?.toUpperCase();
+    // TODO: use lower-case in specialFunctions
+    const spec = specialFunctions[func];
+    this.dynamic_.call = { func, argPos: 0 };
+    this.dynamic_.generic = spec ? spec[0] : specialFunctions[''][0];
+  }
+
+  nextFunctionArgument() {
+    const { call } = this.dynamic_;
+    const spec = specialFunctions[call.func];
+    ++call.argPos;
+    this.dynamic_.generic = spec ? spec[call.argPos] : specialFunctions[''][1];
+  }
+
+  lGenericIntroOrExpr( tryGenericIntro = true ) {
+    const { keyword, type } = this.la();
+    // TODO: use lower-case in specialFunctions
+    const text = keyword?.toUpperCase() ?? type;
+    const generic = this.dynamic_.generic?.[text];
+    if (tryGenericIntro) {
+      if (this.dynamic_.generic?.IN === 'separator')
+        this.prec_ = PRECEDENCE_OF_IN_PREDICATE; // only expressions if `in` is separator
+      if (generic !== 'expr')
+        return (generic === 'intro') ? 'GenericIntro' : 'Id';
+      const next = this.tokens[this.tokenIdx + 1];
+      if (next.type !== ',' && next.type !== ')' &&
+          this.dynamic_.generic[next.keyword?.toUpperCase()] !== 'separator')
+        return 'GenericIntro';
+    }
+    return (generic === 'expr') ? 'GenericExpr' : 'Id';
+  }
+
+  lGenericExpr() {
+    return this.lGenericIntroOrExpr( false );
+  }
+
+  lGenericSeparator() {
+    const { keyword, type } = this.la();
+    // TODO: use lower-case in specialFunctions
+    const text = keyword?.toUpperCase() ?? type;
+    const generic = this.dynamic_.generic?.[text];
+    return (generic === 'separator') ? 'GenericSeparator' : ',';
+  }
+
+  translateParserToken_( tokenName ) {
+    const realTokens = this.dynamic_.generic?.[parserTokens[tokenName]];
+    // TODO: avoid parserTokens dict, use lower-case in specialFunctions
+    return realTokens?.map( s => s.toLowerCase() ) ?? [];
+  }
+
+  isDotForPath() {
+    if (this.dynamic_.inSelectItem == null)
+      return true;
+    // false for outer select item, true for inner; TODO: it would be best to set
+    // this.dynamic_.inSelectItem to null in filters
+    const next = this.tokens[this.tokenIdx + 1].type;
+    return next !== '*' && next !== '{';
+  }
+
+  // <prec=10, postfix=once> + test that the next token is not `null`
+  // TODO TOOL: allow to provide argument with condition: <cond=isNegatedRelation, arg=10>
+  isNegatedRelation() {
+    const parentPrec = this.stack.at( -1 ).prec;
+    if (parentPrec != null && parentPrec >= 10 ||
+        this.prec_ != null && this.prec_ <= 10 ||
+        this.tokens[this.tokenIdx + 1].keyword === 'null')
+      return false;
+    this.prec_ = 10;
+    return true;
+  }
+
+  isNamedArg() {
+    const { type } = this.tokens[this.tokenIdx + 1];
+    return type === ':' || type === '=>';
+  }
+
+  /**
+   * `namespace` is forbidden after a definitions/extend or after previous
+   * `namespace`
+   */
+  namespaceRestriction() {
+    return ++this.topLevel$ < 1;
+  }
+
+  /**
+   * `extend`/`annotate` is forbidden inside `extend … with definitions` and
+   * variants
+   */
+  extensionRestriction() {
+    // TODO: use `syntax-unexpected-extension` as message
+    const r = this.dynamic_.inExtension;
+    this.dynamic_.inExtension = true;
+    return !r;
+  }
+
+  /**
+   * `annotation` def is only allowed top-level
+   */
+  vocabularyRestriction( test ) {
+    // TODO: use `syntax-unexpected-vocabulary` as message
+    if (!test)
+      this.dynamic_.inBlock = true;
+    return !this.dynamic_.inBlock;
+  }
+
+  /**
+   * Prepare element restrictions and check validility of final anno assignments.
+   * TODO TOOL: `arg` for actions/conditions
+   *
+   * Called in rule `elementDef` at the following places:
+   * - <prepare> after `:` (before calling `typeExpression`):
+   *   disallow `= calcExpr` and final annotation assignments
+   *   without further <prepare=calcOrDefaultRestriction>
+   * - <prepare> in empty alternative to type expression:
+   *   allow `= calcExpr` and final annotation assignments
+   * - <cond> before final annotation assignments: allowed?
+   *
+   * Called in rule `returnsSpec`:
+   * - <prepare> after `returns`: disallow `default`.
+   */
+  elementRestriction( test ) {
+    if (!test) {                // after `:` for typeExpression, or without type
+      const withoutType = this.lb().type !== ':';
+      const afterReturns = this.lb().keyword === 'returns';
+      this.dynamic_.elementCtx = [ withoutType, withoutType, afterReturns ];
+    }
+    // or before final annotation assignments
+    return this.dynamic_.elementCtx?.[1];
+  }
+
+  /**
+   * Prepare `= calcExpr` restriction and check whether it can be used.
+   *
+   * Called at the following places:
+   * - <prepare> before (optionally) calling rule `nullabilityAndDefault`,
+   *   except for managed associations/compositions:
+   *   allow `= calcExpr`, allow final annotation assignments if not after `}`
+   *   (TODO: should we allow `String @anno:{ … } not null @MoreAnnos`?)
+   * - <cond> before `default`: disallow calc expr (+ restrict default expr),
+   *   allowed? (not for `returns`)
+   * - <cond> before `=` for calc expressions: allowed?
+   *
+   * To have any effect, <prepare=elementRestriction> must have been called.
+   */
+  calcOrDefaultRestriction( test, arg ) {
+    const { elementCtx } = this.dynamic_;
+    if (!test) {                                 // at beginning of rule `nullabilityAndDefault`
+      if (!elementCtx)
+        return true;
+      elementCtx[0] = !arg;  // using `= expr` is ok (except for assoc)
+      elementCtx[1] = this.lb().type !== '}'; // allow final annos not after block
+    }
+    else if (this.l() === '=') { // <cond> before `= calcExpression`
+      return elementCtx?.[0];
+    }
+    else {                      // <cond> before `default`
+      if (elementCtx)
+        elementCtx[0] = false;
+      this.prec_ = PRECEDENCE_OF_EQUAL; // only expressions for DEFAULT expr
+    }
+    return !elementCtx?.[2];    // default allowed?
+  }
+
+  inExpandInline() {            // not as <cond>
+    this.dynamic_.inSelectItem = 'nested';
+  }
+
+  /**
+   * `virtual` and `key` cannot be used inside expand/inline
+   * (also inside sub queries in those, which will be rejected later anyway)
+   */
+  notInExpandInline( test ) {
+    if (!test)
+      this.dynamic_.inSelectItem = true;
+    return this.dynamic_.inSelectItem !== 'nested';
+  }
+
+  /**
+   * `;` between statements is optional only after a `}` (ex braces of structure
+   * values for annotations).
+   */
+  afterBrace( test ) {
+    if (!test)
+      this.afterBrace$ = this.tokenIdx;
+    return this.afterBrace$ === this.tokenIdx;
+  }
+
+  /**
+   * For annotations at the beginning of columns outside parentheses
+   */
+  annoInSameLine( test ) {
+    if (!test)
+      this.dynamic_.safeAnno = true;
+    return this.dynamic_.safeAnno ||
+      this.lb().location.line === this.la().location.line;
+  }
+
+  /**
+   * `...` can appear in the top-level array value only and not after `...`
+   * without `up to`.
+   */
+  ellipsisRestriction( test ) {
+    if (!test) {
+      this.dynamic_.arrayAnno = [ !this.dynamic_.arrayAnno ];
+    }
+    else {                      // on '...'
+      const { arrayAnno } = this.dynamic_;
+      if (!arrayAnno[0])
+        return false;
+      if (this.tokens[this.tokenIdx + 1]?.type === ',')
+        arrayAnno[0] = false;
+    }
+    return true;
+  }
+
+  beforeColon() {
+    return this.tokens[this.tokenIdx + 1]?.text === ':';
+  }
+
+  // Space handling etc, locations ----------------------------------------------
+
+  // Use the following method for language constructs which we (currently) do
+  // not really compile, just use to produce a CSN for functions parse.cql() and
+  // parse.expr().
+  // This function has a similar interface to our message functions on purpose!
+  // (tokenAhead ~= location)
+  csnParseOnly( msgId, tokenAhead, textArgs ) {
+    if (this.options.parseOnly)
+      return;
+    // assumes no value < -1:
+    const location = (tokenAhead > 0)
+      ? this.combineLocation( this.la(), this.tokens[this.tokenIdx + tokenAhead] )
+      : this.tokens[this.tokenIdx + tokenAhead].location;
+    this.error( msgId, location, textArgs );
+  }
+
+  warnIfColonFollows( anno ) {
+    if (this.l() === ':') {
+      this.warning( 'syntax-missing-parens', anno.name,
+                    { code: '@‹anno›', op: ':', newcode: '@(‹anno›…)' },
+                    // eslint-disable-next-line @stylistic/js/max-len
+                    'When $(CODE) is followed by $(OP), use $(NEWCODE) for annotation assignments at this position' );
+    }
+  }
+
+  noAssignmentInSameLine() {
+    const next = this.la();
+    if (next.text === '@' && next.line <= this.lb().endLine) {
+      this.warning( 'syntax-missing-semicolon', next, { code: ';' },
+                    // eslint-disable-next-line @stylistic/js/max-len
+                    'Add a $(CODE) and/or newline before the annotation assignment to indicate that it belongs to the next statement' );
+    }
+  }
+
+  // For :param, #variant, #symbol, @(…) and @Begin and `@` inside annotation paths
+  reportUnexpectedSpace( prefix = this.lb(),
+                         location = this.la().location,
+                         isError = false ) {
+    const prefixLoc = prefix.location;
+    if (prefixLoc.endLine !== location.line ||
+        prefixLoc.endCol !== location.col) {
+      const wsLocation = {
+        __proto__: Location.prototype,
+        file: location.file,
+        line: prefixLoc.endLine,           // !
+        col: prefixLoc.endCol,             // !
+        endLine: location.line,
+        endCol: location.col,
+      };
+      if (isError) {
+        this.message( 'syntax-invalid-space', wsLocation, { op: prefix.text },
+                      'Delete the whitespace after $(OP)' );
+      }
+      else {
+        this.warning( 'syntax-unexpected-space', wsLocation, { op: prefix.text },
+                      'Delete the whitespace after $(OP)' );
+      }
+    }
+    return prefixLoc;
+  }
+
+  startLocation( { location } = this.lr() ) {
+    return {
+      __proto__: Location.prototype,
+      file: location.file,
+      line: location.line,
+      col: location.col,
+      endLine: undefined,
+      endCol: undefined,
+    };
+  }
+
+  attachLocation( art ) {
+    if (!art)
+      return art;
+    art.location ??= this.startLocation();
+    if (this.s == null)         // do not set end location if error
+      return art;
+    const { location } = this.lb();
+    art.location.endLine = location.endLine;
+    art.location.endCol = location.endCol;
+    return art;
+  }
+
+  ruleTokensText() {
+    let tokenIdx = this.stack.at(-1).tokenIdx + 1;
+    const stop = this.tokenIdx - 1;
+
+    let { text: result, location: prev } = this.tokens[tokenIdx];
+    while (++tokenIdx < stop) {
+      const { text, location } = this.tokens[tokenIdx];
+      if (location.line > prev.endLine ||
+          location.line === prev.endLine && location.col > prev.endCol)
+        result += ' ';
+      result += normalizeNewLine( text );
+      prev = location;
+    }
+    return result;
+  }
+
+  // AST building ---------------------------------------------------------------
+
+  assignAnnotation( art, val, name, prefix = '' ) {
+    const { path } = name;
+    const pathname = pathName( path );
+    if (!pathname)
+      return;
+    let absolute = '';
+    if (name.variant) {
+      const variant = pathName( name.variant.path );
+      absolute = `${ prefix }${ pathname }#${ variant }`;
+      // We do not care anymore whether we get a second '#' with flattening.  This
+      // can be produced via CSN and with delimited ids anyway.  If backends care,
+      // they need to have their own check.
+    }
+    else if (!prefix || pathname !== '$value') {
+      absolute = `${ prefix }${ pathname }`;
+    }
+    else {
+      absolute = prefix.slice( 0, -1 ); // remove final dot
+    }
+
+    val.name = name;
+    if (val.$flatten) {
+      for (const a of val.$flatten)
+        this.assignAnnotation( art, a, a.name, `${ absolute }.` );
+    }
+    else {
+      name.id = absolute;
+      this.addAnnotation( art, `@${ absolute }`, val );
+    }
+    if (!prefix) {                // set deprecated $annotations for cds-lsp
+      const { line, col } = name.location;
+      const location = {
+        __proto__: Location.prototype,
+        ...val.location,
+        line,
+        col,
+      };
+      art.$annotations ??= [];
+      art.$annotations.push( { value: val, location } );
+    }
+  }
+
+  addAnnotation( art, prop, anno ) {
+    const old = art[prop];
+    if (old) {
+      this.error( 'syntax-duplicate-anno', old.name, { anno: prop },
+                  'Assignment for $(ANNO) is overwritten by another one below' );
+    }
+    art[prop] = anno;
+  }
+
+  identAst( token = this.lb() ) {
+    const { text, keyword, location } = token;
+    if (keyword)          // no delimited id, see Lexer.js
+      return { id: text, location };
+    const close = keyword === 0 ? Infinity : -1;
+    const id = (text.charAt(0) === '!')
+      ? text.slice( 2, close ).replace( /]]/g, ']' )
+      : text.slice( 1, close ).replace( /""/g, '"' );
+
+    if (keyword !== 0) {
+      if (!id) {
+        this.message( 'syntax-invalid-name', location, {} );
+      }
+      else if (text.charAt(0) !== '!') {
+        this.message( 'syntax-deprecated-ident', location, { delimited: id },
+                      // eslint-disable-next-line @stylistic/js/max-len
+                      'Deprecated delimited identifier syntax, use $(DELIMITED) - strings are delimited by single quotes' );
+      }
+    }
+    // $delimited is used to complain about ![$self] and other magic vars usage;
+    // we might complain about that already here via @arg{category}
+    return { id, location, $delimited: true };
+  }
+
+  fragileAlias( safe = false ) {
+    const ast = this.identAst();
+    if (safe || ast.$delimited || !/^[a-zA-Z][a-zA-Z_]+$/.test( ast.id )) {
+      this.warning( 'syntax-deprecated-auto-as', ast.location, { keyword: 'as' },
+                    'Add keyword $(KEYWORD) in front of the alias name' );
+    }
+    else {                         // configurable error
+      this.message( 'syntax-missing-as', ast.location, { keyword: 'as' },
+                    'Add keyword $(KEYWORD) in front of the alias name' );
+    }
+    return ast;
+  }
+
+  identAstWithPrefix( prefix, token = this.lb() ) {
+    const ast = this.identAst( token );
+    const { line, col } = prefix.location;
+    // TODO main: location method `withEndLocation`
+    ast.location = {
+      __proto__: Location.prototype,
+      ...token.location,
+      line,
+      col,
+    };
+    ast.id = prefix.text + ast.id;
+    return ast;
+  }
+
+  classifyImplicitName( category, ref ) {
+    if (!ref || ref.path) {
+      const tokenIndex = ref?.path[ref.path.length - 1]?.location.tokenIndex;
+      const token = this.prevTokenWithIndex( tokenIndex ) ?? this.tokens[this.tokenIdx - 1];
+      const { parsedAs } = token;
+      if (parsedAs && parsedAs !== 'token' && parsedAs !== 'keyword') {
+        token.parsedAs = category;
+        return { token, parsedAs };
+      }
+    }
+    return null;
+  }
+
+  taggedIfQuery( query ) {
+    return (query.op && queryOps[query.op.val])
+      ? { query, location: query.$parens?.at( -1 ) ?? query.location }
+      : query;
+  }
+
+  addNamedArg( args, idToken, expr ) {
+    expr.name = this.identAst( idToken );
+    (args.args ?? args)[expr.name.id] = expr;
+  }
+
+  ixprAst( args ) {
+    if (args.length === 1)
+      return args[0];
+    return this.attachLocation( { op: { val: 'ixpr', location: this.lr().location }, args } );
+  }
+
+  // Create AST node for quoted literals like string and e.g. date'2017-02-22'.
+  // This function might issue a message and might change the `literal` and
+  // `val` property according to `quotedLiteralPatterns` above.
+  quotedLiteral( token = this.lb() ) {
+    const { location, text } = token;
+    let literal = 'string';
+    let pos;
+    let val;
+
+    if (text.startsWith( '`' )) {
+      val = parseMultiLineStringLiteral.call( this, token ); // TODO: remove `call()` syntax
+    }
+    else {
+      pos = text.search( '\'' ) + 1; // pos of char after quote
+      val = text.slice( pos, -1 ).replace( /''/g, '\'' );
+    }
+
+    if (pos > 1)
+      literal = text.slice( 0, pos - 1 ).toLowerCase();
+    const p = quotedLiteralPatterns[literal] || {};
+
+    if (p.test_fn && !p.test_fn( val ) && !this.options.parseOnly)
+      this.warning( 'syntax-invalid-literal', location, { '#': p.test_variant } );
+
+    if (p.unexpected_char) {
+      const idx = val.search( p.unexpected_char );
+      if (idx > -1) {
+        this.warning( 'syntax-invalid-literal', {
+          file: location.file,
+          line: location.line,
+          endLine: location.line,
+          col: atChar(idx),
+          endCol: atChar( idx + (val[idx] === '\'' ? 2 : 1) ),
+        }, { '#': p.unexpected_variant } );
+      }
+    }
+    return { literal, val: p.normalize?.(val) || val, location };
+
+    function atChar( i ) {
+      // Is only used with single-line strings.
+      return location.col + pos + i;
+    }
+  }
+
+  // If a '-' is directly before an unsigned number, consider it part of the number;
+  // otherwise (including for '+'), represent it as extra unary prefix operator.
+  signedExpression( ixpr, expr ) {
+    // if (args.length !== 1) throw new CompilerAssertion()
+    const sign = ixpr.args[0];
+    const nval
+          = (sign.val === '-' &&
+             expr && // expr may be null if `-` rule can't be parsed
+             expr.literal === 'number' &&
+             sign.location.endLine === expr.location.line &&
+             sign.location.endCol === expr.location.col &&
+             ( typeof expr.val === 'number'
+               ? expr.val >= 0 && -expr.val
+               : !expr.val.startsWith('-') && `-${ expr.val }`)) || false;
+    if (nval === false) {
+      ixpr.args.push( expr );
+      return this.attachLocation( ixpr );
+    }
+    expr.val = nval;
+    --expr.location.col;
+    return expr;
+  }
+
+  /**
+   * Given `token`, return a number literal (XSN).  If the number is not an unsigned integer
+   * or it can't be represented in JS, emit an error.
+   */
+  unsignedIntegerLiteral() {
+    const token = this.lb();
+    const { location } = token;
+    const text = token.text || '0';
+    const num = Number.parseFloat( text ); // not Number.parseInt() !
+    if (!Number.isSafeInteger(num)) {
+      this.error( 'syntax-expecting-unsigned-int', token,
+                  { '#': !text.match(/^\d*$/) ? 'normal' : 'unsafe' } );
+    }
+    else if (text.match(/^\d+[.]\d+$/)) {
+      // More restrictive check: 10.0 emits a message, because we don't expect
+      // any decimal places.
+      const dotLoc = { ...location };
+      dotLoc.col += text.indexOf('.');
+      dotLoc.endCol = dotLoc.col + 1;
+      this.info( 'syntax-ignoring-decimal', dotLoc );
+    }
+    return { literal: 'number', val: num, location };
+  }
+
+  numberLiteral( sign = null ) {
+    const token = this.lb();
+    let { location } = token;
+    const { keyword, location: nextLoc } = this.la();
+    if (keyword &&             // is only set with keyword and/or non-delimited Id
+        nextLoc.line === location.endLine && nextLoc.col === location.endCol) {
+      this.message( 'syntax-expecting-space', nextLoc, {},
+                    'Expecting a space between a number and a keyword/identifier' );
+    }
+
+    const text = (sign) ? sign.text + token.text : token.text;
+    if (sign) {
+      this.reportUnexpectedSpace( sign, location );
+      location = {
+        __proto__: Location.prototype,
+        ...sign.location,
+        endLine: location.endLine,
+        endCol: location.endCol,
+      };
+    }
+    const val = Number.parseFloat( text || '0' ); // not Number.parseInt() !
+    const normalized = normalizeNumberString( text );
+    if (normalized === `${ val }` || sign && normalized === `${ sign.text }${ val }`)
+      return { literal: 'number', val, location };
+    return { literal: 'number', val: normalized, location };
+  }
+
+  adjustAnnoNumber( value ) {
+    const { val } = value;
+    if (value.literal !== 'number' || typeof val === 'number')
+      return;
+    // a number in CDL, but stored as string in `val` - due to rounding or scientific notation
+    const num = Number.parseFloat( val || '0' );
+    const infinite = !Number.isFinite( num );
+    if (infinite || relevantDigits( val ) !== relevantDigits( num.toString() )) {
+      this.warning( 'syntax-invalid-anno-number', value,
+                    { '#': (infinite ? 'infinite' : 'rounded' ), rawvalue: val, value: num },
+                    {
+                      std: 'Annotation number $(RAWVALUE) is put as $(VALUE) into the CSN',
+                      rounded: 'Annotation number $(RAWVALUE) is rounded to $(VALUE)',
+                      // eslint-disable-next-line @stylistic/js/max-len
+                      infinite: 'Annotation value $(RAWVALUE) is infinite as number and put as string into the CSN',
+                    } );
+    }
+    if (!infinite)
+      value.val = num;
+  }
+
+  /**
+   * Store doc comment between previous and current token as `art.doc`.  If `art`
+   * is not provided (with EOF), just complain about remaining doc comment tokens.
+   *
+   * The doc comment token is not a “standard” token for the following reasons:
+   *  - misplaced doc comments would lead to a parse error (incompatible),
+   *  - would influence the prediction and error recovery,
+   *  - is only slightly "more declarative" in the grammar.
+   */
+  docComment( art ) {
+    const { line: prevLine, col: prevCol } = this.lb()?.location ?? { line: 0, col: 0 };
+    const { line: currLine, col: currCol } = this.la().location;
+    let token;
+    for (;;) {
+      token = this.docComments[this.docCommentIndex];
+      if (!token)
+        return;                 // no further doc comment
+      const { line, col } = token.location;
+      if (art && (line > currLine || line === currLine && col > currCol))
+        return;               // next doc comment after current token
+
+      ++this.docCommentIndex;
+      if (!art || line < prevLine || line === prevLine && col < prevCol) {
+        if (this.options.docComment !== false) {
+          this.info( 'syntax-ignoring-doc-comment', token.location, {},
+                     'Ignoring doc comment as it is not written at a defined position' );
+        }
+      }
+      else { // next doc comment between previous & current token
+        // With explicit docComment:false, we don't emit a warning.
+        if (art.doc && this.options.docComment !== false) {
+          this.warning( 'syntax-duplicate-doc-comment', art.doc, {},
+                        'Doc comment is overwritten by another one below' );
+        }
+        token.parsedAs = 'doc';
+        const val = !this.options.docComment || parseDocComment( token.text );
+        art.doc = { val, location: token.location };
+      }
+    }
+  }
+
+  setNullability( art, val, location = this.lb().location ) {
+    const notNull = { val, location };
+    if (art.notNull) {
+      this.reportDuplicateClause( 'notNull', art.notNull, notNull,
+                                  (val ? 'not null' : 'null') );
+    }
+    art.notNull = notNull;
+  }
+
+  setAssocAndComposition( art, assoc, card, target ) {
+    const { location } = assoc;
+    art.type = {
+      path: [ { id: keywordTypeNames[assoc.keyword], location } ],
+      scope: 'global',
+      location,
+    };
+    art.target = target;
+    if (!card)
+      return;
+
+    const targetMax = (card.keyword === 'one')
+      ? { val: 1, literal: 'number', location: card.location }
+      : { val: '*', literal: 'string', location: card.location };
+    // TODO: `literal` needed?
+    if (art.cardinality) {
+      this.reportDuplicateClause( 'cardinality', targetMax, art.cardinality.targetMax,
+                                  card.keyword, true );
+    }
+    else {
+      art.cardinality = { targetMax, location: targetMax.location };
+    }
+  }
+
+  reportExpandInline( column, isInline ) {
+    const { name } = column;
+    if (column.value && !column.value.path) {
+      const token = this.la();
+      // improve error location when using "inline" `.{…}` after ref (arguments and
+      // filters not covered, not worth the effort); after an expression where
+      // the last token is an identifier, not the `.` is wrong, but the `{`:
+      // if (isInline && !name && this._input.LT(-1).type >= this.constructor.Identifier)
+      //   token = this._input.LT(2); -- TODO: still valid?
+      this.error( 'syntax-unexpected-nested-proj', token,
+                  { code: isInline ? '.{ ‹inline› }' : '{ ‹expand› }' },
+                  'Unexpected $(CODE); nested projections can only be used after a reference' );
+      // continuation semantics:
+      // - add elements anyway (could lead to duplicate errors as usual)
+      // - no errors for refs inside expand/inline, but for refs in sibling expr
+      // - think about: reference to these (sub) elements from other view
+    }
+    if (isInline && name) {
+      const alias = this.tokens[this.tokenIdx - 2];
+      const location = (isInline === true)
+        ? alias.location
+        : this.combineLocation( isInline, alias );
+      this.error( 'syntax-unexpected-alias', location, { code: '.{ ‹inline› }' },
+                  'Unexpected alias name before $(CODE)' );
+      // continuation semantics: ignore AS
+    }
+  }
+
+  reportDuplicateClause( prop, erroneous, chosen, code, literalValIfNotEq ) {
+    // probably easier for message linters not to use (?:) for the message id...?
+    const args = {
+      '#': prop,
+      code,
+      line: chosen.location.line,
+      col: chosen.location.col,
+    };
+    if (erroneous.val === chosen.val) {
+      this.warning( 'syntax-duplicate-equal-clause', erroneous.location, args );
+    }
+    else {
+      if (literalValIfNotEq)
+        args.code = chosen.val;
+      this.message( 'syntax-duplicate-clause', erroneous.location, args );
+    }
+  }
+
+  setTypeFacet( art, name, value ) {
+    const { text } = name;
+    if (text !== 'length' && text !== 'scale' && text !== 'precision' && text !== 'srid') {
+      this.error( 'syntax-undefined-param', name.location, { name: text },
+                  'There is no type parameter called $(NAME)');
+    }
+    else {
+      if (art[text] !== undefined)
+        this.error( 'syntax-duplicate-argument', art[text].location, { '#': 'type', name: text } );
+      // continuation semantics: use last
+      art[text] = value;
+    }
+  }
+
+  locationOfPrevTokens( offset ) {
+    const { file, line, col } = this.tokens[this.tokenIdx - offset].location;
+    const { endLine, endCol } = this.lb().location;
+    return {
+      file,
+      line,
+      col,
+      endLine,
+      endCol,
+    };
+  }
+
+  // TODO: also define method `combineWith` in Location
+  combineLocation( { location: start }, { location: end } = this.lb() ) {
+    const { file, line, col } = start;
+
+    return {
+      file, line, col, endLine: end.endLine, endCol: end.endCol,
+    };
+  }
+
+  // `tokenIndex` is index in “combined” token array (parsing-relevant, doc
+  // comments, comments) → cannot be used directly
+  prevTokenWithIndex( tokenIndex ) {
+    if (tokenIndex != null) {
+      let { tokenIdx } = this;
+      while (--tokenIdx >= 0) {
+        const token = this.tokens[tokenIdx];
+        if (token.location.tokenIndex === tokenIndex)
+          return token;
+      }
+    }
+    return null;
+  }
+
+  // TODO: rename to `valAst`
+  valueWithLocation( val = undefined, token = this.lb() ) {
+    if (val === undefined)
+      val = token.keyword ?? token.text;
+    return { val, location: token.location };
+  }
+
+  surroundByParens( expr, open = this.lr(), close = this.lb() ) {
+    expr.$parens ??= [];
+    expr.$parens.push( this.combineLocation( open, close ) );
+    return expr;
+  }
+
+  // make sure that the parens of `IN (…)` do not disappear:
+  // TODO: make this a to-csn thing
+  secureParens( expr ) {
+    const op = expr?.op?.val;
+    const $parens = expr?.$parens;
+    if (!$parens || expr.query || op && op !== 'call' && op !== 'cast')
+      return expr;
+    // ensure that references, literals and functions keep their surrounding parentheses
+    // (is for expressions the case anyway)
+    const location = $parens.pop();
+    if (!$parens.length)
+      delete expr.$parens;
+    return {
+      op: { val: 'xpr', location: this.startLocation() },
+      args: [ expr ],
+      location,
+    };
+  }
+
+  pushXprToken( expr ) {
+    const token = this.lb();
+    (expr.args ?? expr).push( {
+      val: token.keyword ?? token.type,
+      location: token.location,
+      literal: 'token',
+    } );
+  }
+
+  applyOpToken( expr, nary = null ) {
+    const token = this.lb();
+    const op = { val: token.keyword ?? token.type, location: token.location, literal: 'token' };
+    if (nary === 'nary' && !expr?.$parens) {
+      const { args } = expr;
+      const prev = args?.[1];
+      if (prev?.val === op.val && prev?.literal === 'token') {
+        args.push( op );
+        return expr;
+      }
+    }
+    return {
+      op: { val: nary ?? 'ixpr', location: token.location },
+      args: (expr ? [ expr, op ] : [ op ] ),
+    };
+  }
+
+  valuePathAst( ref ) {
+    // TODO: XSN representation of functions is a bit strange - rework
+    // TODO: rework this function
+    const { path } = ref;
+    if (path?.length === 1) {
+      const { args, id, location } = path[0];
+      if (args
+          ? path[0].$syntax === ':'
+          : path[0].$delimited || !functionsWithoutParens.includes( id.toUpperCase() ))
+        return this.attachLocation( ref );
+
+      const funcToken = this.prevTokenWithIndex( location.tokenIndex );
+      // TODO: we could have an opt(?) parameter funcToken for speed-up (passing this.lr())
+      if (funcToken)
+        funcToken.parsedAs = 'func';
+      // TODO: XSN representation of functions is a bit strange - rework
+      const op = { location, val: 'call' };
+      return this.attachLocation( { op, func: ref, args } );
+    }
+
+    // $syntax === ':' => path(P: 1)
+    // $syntax !== ':' => path(P => 1) or path(1) or path()
+    const firstFunc = path.findIndex( i => i.args && i.$syntax !== ':' );
+    if (firstFunc === -1) // also covers empty paths
+      return ref;
+
+    // Method Call ---------------------------
+    // Transform the path into `.`-operators.
+    // Everything after the first function is also a function, and not a reference.
+
+    for (let i = firstFunc; i < path.length; ++i) {
+      if (path[i].args && path[i].$syntax === ':') {
+        // Error for `a(P => 1).b.c(P: 1)`: no ref after function.
+        this.error( 'syntax-invalid-ref', path[i].args[$location], {
+          code: '=>',
+        }, 'References after function calls can\'t be resolved. Use $(CODE) in function arguments');
+        break;
+      }
+    }
+
+    const args = [];
+    if (firstFunc > 0) {
+      args.push({
+        path: path.slice(0, firstFunc),
+        location: this.combineLocation( path[0], path[path.length - 1] ),
+      });
+    }
+
+    const pathRest = path.slice(firstFunc);
+    for (const method of pathRest) {
+      if (method !== pathRest[0] || firstFunc > 0) {
+        args.push({
+          // TODO: Update parser to have proper location for `.`?
+          location: this.startLocation( method ),
+          val: '.',
+          literal: 'token',
+        });
+      }
+      // this.prevTokenWithIndex( method.location.tokenIndex ).parsedAs = 'func';
+      const func = {
+        op: { location: method.location, val: 'call' },
+        func: { path: [ method ] },
+        location: method.location,
+      };
+      if (method.args)
+        func.args = method.args;
+      args.push(func);
+    }
+
+    return {
+      op: { val: 'ixpr', location: this.startLocation() },
+      args,
+      location: ref.location,
+    };
+  }
+
+  associationInSelectItem( art ) {
+    const { value } = art;
+    const path = value?.path;
+    // we cannot compare "just one token before `:`" because there might be annos
+    if (path && path.length === 1 && !art.name && !art.expand && !art.inline) {
+      const name = value.path[0];
+      if (path.length === 1 && !name.args && !name.cardinality && !name.where) {
+        art.name = name;
+        delete art.value;
+        return;
+      }
+    }
+    this.error( 'syntax-unexpected-assoc', this.la(), {},
+                'Unexpected association definition in select item' );
+  }
+
+  // must be in action directly after having parsed '{', '(`, or a keyword before
+  createDict( start ) {
+    const dict = Object.create(null);
+    dict[$location] = this.startLocation( start || this.lb() );
+    return dict;
+  }
+
+  // must be in action directly after having parsed '[' or '(` or `{`
+  createArray( start ) {
+    const array = [];
+    array[$location] = this.startLocation( start || this.lb() );
+    return array;
+  }
+
+  // must be in action directly after having parsed '}' or ')`
+  finalizeDictOrArray( dict ) {
+    const loc = dict[$location];
+    if (!loc)
+      return;
+    const stop = this.lb().location;
+    loc.endLine = stop.endLine;
+    loc.endCol = stop.endCol;
+  }
+
+  finalizeExtensionsDict( dict ) {
+    this.finalizeDictOrArray( dict );
+    for (const name in dict) {
+      const def = dict[name];
+      if (!def.$duplicates)
+        continue;
+
+      if (def.kind !== 'annotate') {
+        const numDefines
+              = def.$duplicates.reduce( addOneForDefinition, addOneForDefinition( 0, def ) );
+        this.handleDuplicateExtension( def, name, numDefines );
+        for (const dup of def.$duplicates)
+          this.handleDuplicateExtension( dup, name, numDefines );
+        continue;
+      }
+      // move annotations, 'doc' and 'elements' etc to main member
+      for (const dup of def.$duplicates) {
+        for (const prop of Object.keys( dup )) {
+          if (prop.charAt(0) === '@') {
+            this.addAnnotation( def, prop, dup[prop] );
+            delete dup[prop]; // we want to keep $duplicates, but not have duplicate props
+          }
+          else if (prop === 'doc') {
+            // With explicit docComment:false, we don't emit a warning.
+            if (def.doc && this.options.docComment !== false) {
+              this.warning( 'syntax-duplicate-doc-comment', def.doc.location, {},
+                            'Doc comment is overwritten by another one below' );
+            }
+            def.doc = dup.doc;
+            delete dup[prop]; // we want to keep $duplicates for LSP, but not have duplicate props
+          }
+          else if (extensionDicts[prop]) {
+            if (def[prop])
+              this.message( 'syntax-duplicate-annotate', [ def.name.location ], { name, prop } );
+            def[prop] = dup[prop]; // continuation semantics: last wins
+            delete dup[prop]; // we want to keep $duplicates for LSP, but not have duplicate props
+          }
+        }
+        if (dup.$annotations) {   // update deprecated $annotations for cds-lsp / annotation modeler
+          if (def.$annotations)
+            def.$annotations.push( ...dup.$annotations );
+          else
+            def.$annotations = dup.$annotations;
+        }
+      }
+      // We keep duplicate statements for LSP, as it needs to traverse all
+      // identifiers; annotations were removed above to avoid traversing
+      // annotations twice.
+    }
+  }
+
+  /**
+   * Handle duplicate extensions.  Does not handle `annotate`.
+   *
+   * @param {XSN.Extension} ext
+   * @param {string} name
+   * @param {number} numDefines
+   */
+  handleDuplicateExtension( ext, name, numDefines ) {
+    if (ext.kind === 'extend') {
+      this.error( 'syntax-duplicate-extend', [ ext.name.location ],
+                  { name, '#': (numDefines ? 'define' : 'extend') } );
+    }
+    else if (numDefines === 1) {
+      ext.$errorReported = 'syntax-duplicate-extend';
+    } // a definition, but not duplicate
+  }
+
+  // Add new definition `art` to dictionary property `env` of node `parent`.
+  // Return `art`.
+  //
+  // If argument `kind` is provided, set `art.kind` to that value.
+  // If argument `name` is provided, set `art.name`:
+  //  - if `name` is an array, `name.id` consist of the ID of the last array item
+  //    (for elements via columns, foreign keys, table aliases)
+  //  - if `name` is an object, `name.id` is either set, or the (local) name is calculated
+  //    from the IDs of all items in `name.path` (for main artifact definitions).
+  addDef( art, parent, env, kind, name ) {
+    if (Array.isArray(name)) {
+      const last = name.length && name[name.length - 1];
+      art.name = { // A.B.C -> 'C'
+        id: last?.id || '', location: last.location, $inferred: 'as',
+      };
+    }
+    else if (name) {
+      art.name = name;
+      if (!name.id && kind === null) {
+        name.id = name.variant
+          ? `${ pathName( name.path ) }#${ pathName( name.variant.path ) }`
+          : pathName( name.path );
+      }
+    }
+    else {
+      art.name = { id: '' };
+    }
+    if (kind)
+      art.kind = kind;
+
+    const id = art.name?.id || pathName( art.name?.path ); // returns '' for corrupted name
+
+    parent[env] ??= Object.create(null);
+    if (env === 'artifacts' || env === 'vocabularies') {
+      dictAddArray( parent[env], id, art );
+    }
+    else if (kind || this.options.parseOnly) { // TODO: do not check parseOnly
+      dictAdd( parent[env], id, art );
+    }
+    else {
+      dictAdd( parent[env], id, art, ( duplicateName, loc ) => {
+        // do not use function(), otherwise `this` is wrong:
+        if (kind === 0) {
+          this.error( 'syntax-duplicate-argument', loc, { name: duplicateName },
+                      'Duplicate value for parameter $(NAME)' );
+        }
+        else if (kind === '') {
+          this.error( 'syntax-duplicate-excluding', loc,
+                      { name: duplicateName, keyword: 'excluding' } );
+        }
+        else {
+          this.error( 'syntax-duplicate-property', loc, { name: duplicateName },
+                      'Duplicate value for structure property $(NAME)' );
+        }
+      } );
+    }
+    return art;
+  }
+
+  /**
+   * Add `annotate/extend Main.Artifact:elem.sub` to `‹xsn›.extensions`:
+   * - the array item is an extend/annotate for `Main.Artifact`,
+   * - for each path item in `elem.sub`, we add an `elements` property containing
+   *   one extend/annotate for the corresponding element
+   * - The deepest extend/annotate is the object which is to be extended
+   *
+   * @param {object} ext The object containing the location and annotations for the extension.
+   * @param {object} parent The parent containing the `extensions` property, i.e. the source.
+   * @param {string} kind Either `annotate` or `extend`.
+   * @param {object} artName The "name object" for `Main.Artifact`.
+   * @param {XSN.Path} elemPath Path as returned by `simplePath` rule.
+   */
+  addExtension( ext, parent, kind, artName, elemPath ) {
+    const { location } = ext;
+    if (!Array.isArray( elemPath ) || !elemPath.length) {
+      ext.kind = kind;
+      ext.name = artName;
+      parent.extensions.push( ext );
+      return;
+    }
+    // Note: the element extensions share a common `location`, also with the
+    // extension of the main artifact; its end location will usually set later
+    const main = { kind, name: artName, location };
+    parent.extensions.push( main );
+    parent = main;
+
+    const last = elemPath[elemPath.length - 1];
+    for (const seg of elemPath) {
+      parent.elements = Object.create(null); // no dict location → no createDict()
+      parent = this.addDef( (seg === last ? ext : { location }),
+                            parent, 'elements', kind, seg );
+    }
+  }
+}
+
+function addOneForDefinition( count, ext ) {
+  return (ext.kind === 'extend') ? count : count + 1;
+}
+
+// Significant digits (before exponent) without leading and trailing zeros
+function relevantDigits( val ) {
+  const init = /^[-+0.]+/g;     // global flag to have lastIndex
+  const zeros = /[0.]+/g;
+  if (init.test( val ))         // sets init.lastIndex
+    zeros.lastIndex = init.lastIndex;
+
+  let r;
+  while ((r = zeros.exec( val )) != null &&
+         zeros.lastIndex < val.length &&
+         val.charAt( zeros.lastIndex ).toLowerCase() !== 'e')
+    ;
+  return val.slice( init.lastIndex, r?.index ).replace( /\./, '' );
+}
+
+
+// For compatibility with ANTLR-based parser:
+function antlrName( type ) {
+  if (typeof type !== 'string')
+    type = (!type.parsedAs || type.parsedAs === 'keyword') && type.keyword || type.type;
+  if (/^[A-Z]+/.test( type ))// eslint-disable-next-line no-nested-ternary
+    return (type === 'Id') ? 'Identifier' : (type === 'EOF') ? '<EOF>' : type;
+  return (/^[a-z]+/.test( type )) ? type.toUpperCase() : `'${ type }'`;
+}
+
+// Used for sorting in messages (TODO: make it part of messages.js?)
+const token1sort = {
+  // 0: Identifier, Number, ...
+  // 1: separators:
+  ',': 1,
+  '.': 1,
+  ':': 1,
+  ';': 1,
+  // 2: parentheses:
+  '(': 2,
+  ')': 2,
+  '[': 2,
+  ']': 2,
+  '{': 2,
+  '}': 2,
+  // 3: special:
+  '!': 3,
+  '#': 3,
+  $: 3,
+  '?': 3,
+  '@': 3,
+  // 4: operators:
+  '*': 4,
+  '+': 4,
+  '-': 4,
+  '/': 4,
+  '<': 4,
+  '=': 4,
+  '>': 4,
+  '|': 4,
+  // 8: KEYWORD
+  // 9: <EOF>
+};
+
+function tokenPrecedence( name ) {
+  if (name.length < 2 || name === '<EOF>')
+    return `9${ name }`;
+  const prec = token1sort[name.charAt(1)];
+  if (prec)
+    return `${ prec }${ name }`;
+  return (name.charAt(1) < 'a' ? '8' : '0') + name;
+}
+
+module.exports = AstBuildingParser;