@borgar/fx 4.12.0 → 5.0.0

package/lib/parseRef.spec.ts

@@ -0,0 +1,90 @@
+import { describe, test, expect } from 'vitest';
+import { splitPrefix } from './parseRef.ts';
+
+function testStr (str: string, opt: boolean, expected: any) {
+  expect(splitPrefix(str, opt)).toEqual(expected);
+}
+
+describe('splitPrefix', () => {
+  describe('with simple mode (opt = true)', () => {
+    test('fully bracketed references', () => {
+      testStr('[foo][bar][baz]', true, [ 'foo', 'bar', 'baz' ]);
+      testStr('[foo][bar]', true, [ 'foo', 'bar' ]);
+      testStr('[foo]', true, [ 'foo' ]);
+    });
+
+    test('mixed bracketed and unbracketed references', () => {
+      testStr('foo[bar][baz]', true, [ 'foo', 'bar', 'baz' ]);
+      testStr('[foo]bar[baz]', true, [ 'foo', 'bar', 'baz' ]);
+      testStr('[foo][bar]baz', true, [ 'foo', 'bar', 'baz' ]);
+      testStr('foo[bar]baz', true, [ 'foo', 'bar', 'baz' ]);
+      testStr('[foo]bar', true, [ 'foo', 'bar' ]);
+      testStr('foo[bar]', true, [ 'foo', 'bar' ]);
+    });
+
+    test('unbracketed references', () => {
+      testStr('foo', true, [ 'foo' ]);
+    });
+  });
+
+  describe('with detailed mode (opt = false)', () => {
+    test('fully bracketed references', () => {
+      testStr('[foo][bar][baz]', false, [
+        { value: 'foo', braced: true },
+        { value: 'bar', braced: true },
+        { value: 'baz', braced: true }
+      ]);
+
+      testStr('[foo][bar]', false, [
+        { value: 'foo', braced: true },
+        { value: 'bar', braced: true }
+      ]);
+
+      testStr('[foo]', false, [
+        { value: 'foo', braced: true }
+      ]);
+    });
+
+    test('mixed bracketed and unbracketed references', () => {
+      testStr('foo[bar][baz]', false, [
+        { value: 'foo', braced: false },
+        { value: 'bar', braced: true },
+        { value: 'baz', braced: true }
+      ]);
+
+      testStr('[foo]bar[baz]', false, [
+        { value: 'foo', braced: true },
+        { value: 'bar', braced: false },
+        { value: 'baz', braced: true }
+      ]);
+
+      testStr('[foo][bar]baz', false, [
+        { value: 'foo', braced: true },
+        { value: 'bar', braced: true },
+        { value: 'baz', braced: false }
+      ]);
+
+      testStr('foo[bar]baz', false, [
+        { value: 'foo', braced: false },
+        { value: 'bar', braced: true },
+        { value: 'baz', braced: false }
+      ]);
+
+      testStr('[foo]bar', false, [
+        { value: 'foo', braced: true },
+        { value: 'bar', braced: false }
+      ]);
+
+      testStr('foo[bar]', false, [
+        { value: 'foo', braced: false },
+        { value: 'bar', braced: true }
+      ]);
+    });
+
+    test('unbracketed references', () => {
+      testStr('foo', false, [
+        { value: 'foo', braced: false }
+      ]);
+    });
+  });
+});

package/lib/parseRef.ts

@@ -0,0 +1,240 @@
+import {
+  FX_PREFIX,
+  CONTEXT,
+  CONTEXT_QUOTE,
+  REF_RANGE,
+  REF_TERNARY,
+  REF_NAMED,
+  REF_BEAM,
+  REF_STRUCT,
+  OPERATOR
+} from './constants.ts';
+import { lexersRefs } from './lexers/sets.ts';
+import { getTokens } from './tokenize.ts';
+import type { Token } from './types.ts';
+
+// Liberally split a context string up into parts.
+// Permits any combination of braced and unbraced items.
+export function splitPrefix (str: string, stringsOnly = false) {
+  let inBrace = false;
+  let currStr = '';
+  const parts = [];
+  const flush = () => {
+    if (currStr) {
+      parts.push(
+        stringsOnly
+          ? currStr
+          : { value: currStr, braced: inBrace }
+      );
+    }
+    currStr = '';
+  };
+  // eslint-disable-next-line @typescript-eslint/prefer-for-of
+  for (let i = 0; i < str.length; i++) {
+    const char = str[i];
+    if (char === '[') {
+      flush();
+      inBrace = true;
+    }
+    else if (char === ']') {
+      flush();
+      inBrace = false;
+    }
+    else {
+      currStr += char;
+    }
+  }
+  flush();
+  return parts;
+}
+
+export function splitContext (contextString, data, xlsx) {
+  const ctx = splitPrefix(contextString, !xlsx);
+  if (xlsx) {
+    if (ctx.length > 1) {
+      data.workbookName = ctx[ctx.length - 2].value;
+      data.sheetName = ctx[ctx.length - 1].value;
+    }
+    else if (ctx.length === 1) {
+      const item = ctx[0];
+      if (item.braced) {
+        data.workbookName = item.value;
+      }
+      else {
+        data.sheetName = item.value;
+      }
+    }
+  }
+  else {
+    data.context = ctx;
+  }
+}
+
+type RefParseData = {
+  operator: string,
+  r0: string,
+  r1: string,
+  name: string,
+  struct: string,
+};
+type RefParserPart = (t: Token | undefined, data: Partial<RefParseData>, xlsx?: boolean) => 1 | undefined;
+
+const unquote = d => d.slice(1, -1).replace(/''/g, "'");
+
+const pRangeOp: RefParserPart = (t, data) => {
+  const value = t?.value;
+  if (value === ':' || value === '.:' || value === ':.' || value === '.:.') {
+    data.operator = value;
+    return 1;
+  }
+};
+const pRange: RefParserPart = (t, data) => {
+  if (t?.type === REF_RANGE) {
+    data.r0 = t.value;
+    return 1;
+  }
+};
+const pPartial: RefParserPart = (t, data) => {
+  if (t?.type === REF_TERNARY) {
+    data.r0 = t.value;
+    return 1;
+  }
+};
+const pRange2: RefParserPart = (t, data) => {
+  if (t?.type === REF_RANGE) {
+    data.r1 = t.value;
+    return 1;
+  }
+};
+const pBang: RefParserPart = t => {
+  if (t?.type === OPERATOR && t.value === '!') {
+    return 1;
+  }
+};
+const pBeam: RefParserPart = (t, data) => {
+  if (t?.type === REF_BEAM) {
+    data.r0 = t.value;
+    return 1;
+  }
+};
+const pStrucured: RefParserPart = (t, data) => {
+  if (t.type === REF_STRUCT) {
+    data.struct = t.value;
+    return 1;
+  }
+};
+const pContext: RefParserPart = (t, data, xlsx) => {
+  const type = t?.type;
+  if (type === CONTEXT) {
+    splitContext(t.value, data, xlsx);
+    return 1;
+  }
+  if (type === CONTEXT_QUOTE) {
+    splitContext(unquote(t.value), data, xlsx);
+    return 1;
+  }
+};
+const pNamed: RefParserPart = (t, data) => {
+  if (t?.type === REF_NAMED) {
+    data.name = t.value;
+    return 1;
+  }
+};
+
+const validRuns = [
+  [ pPartial ],
+  [ pRange, pRangeOp, pRange2 ],
+  [ pRange ],
+  [ pBeam ],
+  [ pContext, pBang, pPartial ],
+  [ pContext, pBang, pRange, pRangeOp, pRange2 ],
+  [ pContext, pBang, pRange ],
+  [ pContext, pBang, pBeam ]
+];
+
+const validRunsNamed = validRuns.concat([
+  [ pNamed ],
+  [ pContext, pBang, pNamed ],
+  [ pStrucured ],
+  [ pNamed, pStrucured ],
+  [ pContext, pBang, pNamed, pStrucured ]
+]);
+
+type ParseRefOptions = {
+  withLocation?: boolean,
+  mergeRefs?: boolean,
+  allowTernary?: boolean,
+  allowNamed?: boolean,
+  r1c1?: boolean,
+};
+export type RefParseDataXls = RefParseData & { workbookName: string, sheetName: string };
+export type RefParseDataCtx = RefParseData & { context: string[] };
+
+export function parseRefCtx (ref: string, opts: ParseRefOptions = {}): RefParseDataCtx | null {
+  const options = {
+    withLocation: opts.withLocation ?? false,
+    mergeRefs: opts.mergeRefs ?? false,
+    allowTernary: opts.allowTernary ?? false,
+    allowNamed: opts.allowNamed ?? true,
+    r1c1: opts.r1c1 ?? false
+  };
+  const tokens = getTokens(ref, lexersRefs, options);
+
+  // discard the "="-prefix if it is there
+  if (tokens.length && tokens[0].type === FX_PREFIX) {
+    tokens.shift();
+  }
+  const runs = options.allowNamed ? validRunsNamed : validRuns;
+  for (const run of runs) {
+    // const len = run.length;
+    if (run.length === tokens.length) {
+      const data: RefParseDataCtx = {
+        context: [],
+        r0: '',
+        r1: '',
+        name: '',
+        struct: '',
+        operator: ''
+      };
+      const valid = run.every((parse, i) => parse(tokens[i], data, false));
+      if (valid) {
+        return data;
+      }
+    }
+  }
+}
+
+export function parseRefXlsx (ref: string, opts: ParseRefOptions = {}): RefParseDataXls | null {
+  const options = {
+    withLocation: opts.withLocation ?? false,
+    mergeRefs: opts.mergeRefs ?? false,
+    allowTernary: opts.allowTernary ?? false,
+    allowNamed: opts.allowNamed ?? true,
+    r1c1: opts.r1c1 ?? false,
+    xlsx: true
+  };
+  const tokens = getTokens(ref, lexersRefs, options);
+
+  // discard the "="-prefix if it is there
+  if (tokens.length && tokens[0].type === FX_PREFIX) {
+    tokens.shift();
+  }
+  const runs = options.allowNamed ? validRunsNamed : validRuns;
+  for (const run of runs) {
+    if (run.length === tokens.length) {
+      const data: RefParseDataXls = {
+        workbookName: '',
+        sheetName: '',
+        r0: '',
+        r1: '',
+        name: '',
+        struct: '',
+        operator: ''
+      };
+      const valid = run.every((parse, i) => parse(tokens[i], data, true));
+      if (valid) {
+        return data as any;
+      }
+    }
+  }
+}

package/lib/parseSRange.ts

@@ -0,0 +1,240 @@
+import { isWS } from './lexers/lexWhitespace.ts';
+
+const AT = 64; // @
+const BR_CLOSE = 93; // ]
+const BR_OPEN = 91; // [
+const COLON = 58; // :
+const COMMA = 44; // ,
+const HASH = 35; // #
+const QUOT_SINGLE = 39; // '
+
+const keyTerms = {
+  'headers': 1,
+  'data': 2,
+  'totals': 4,
+  'all': 8,
+  'this row': 16,
+  '@': 16
+};
+
+// only combinations allowed are: #data + (#headers | #totals | #data)
+const fz = (...a: string[]) => Object.freeze(a);
+const sectionMap = {
+  // no terms
+  0: fz(),
+  // single term
+  1: fz('headers'),
+  2: fz('data'),
+  4: fz('totals'),
+  8: fz('all'),
+  16: fz('this row'),
+  // headers+data
+  3: fz('headers', 'data'),
+  // totals+data
+  6: fz('data', 'totals')
+};
+
+function matchKeyword (str: string, pos: number): number {
+  let p = pos;
+  if (str.charCodeAt(p++) !== BR_OPEN) {
+    return;
+  }
+  if (str.charCodeAt(p++) !== HASH) {
+    return;
+  }
+  do {
+    const c = str.charCodeAt(p);
+    if (
+      (c >= 65 && c <= 90) || // A-Z
+      (c >= 97 && c <= 122) || // a-z
+      (c === 32) // space
+    ) {
+      p++;
+    }
+    else {
+      break;
+    }
+  }
+  while (p < pos + 11); // max length: '[#this row'
+  if (str.charCodeAt(p++) !== BR_CLOSE) {
+    return;
+  }
+  return p - pos;
+}
+
+function skipWhitespace (str: string, pos: number): number {
+  let p = pos;
+  while (isWS(str.charCodeAt(p))) { p++; }
+  return p - pos;
+}
+
+function matchColumn (str: string, pos: number, allowUnbraced = true): [ string, string ] {
+  let p = pos;
+  let column = '';
+  if (str.charCodeAt(p) === BR_OPEN) {
+    p++;
+    let c;
+    do {
+      c = str.charCodeAt(p);
+      if (c === QUOT_SINGLE) {
+        p++;
+        c = str.charCodeAt(p);
+        // Allowed set: '#@[]
+        if (c === QUOT_SINGLE || c === HASH || c === AT || c === BR_OPEN || c === BR_CLOSE) {
+          column += String.fromCharCode(c);
+          p++;
+        }
+        else {
+          return;
+        }
+      }
+      // Allowed set is all chars BUT: '#@[]
+      else if (c === QUOT_SINGLE || c === HASH || c === AT || c === BR_OPEN) {
+        return;
+      }
+      else if (c === BR_CLOSE) {
+        p++;
+        return [ str.slice(pos, p), column ];
+      }
+      else {
+        column += String.fromCharCode(c);
+        p++;
+      }
+    }
+    while (p < str.length);
+  }
+  else if (allowUnbraced) {
+    let c;
+    do {
+      c = str.charCodeAt(p);
+      // Allowed set is all chars BUT: '#@[]:
+      if (c === QUOT_SINGLE || c === HASH || c === AT || c === BR_OPEN || c === BR_CLOSE || c === COLON) {
+        break;
+      }
+      else {
+        column += String.fromCharCode(c);
+        p++;
+      }
+    }
+    while (p < str.length);
+    if (p !== pos) {
+      return [ column, column ];
+    }
+  }
+}
+
+export type SRange = {
+  columns: string[],
+  sections: string[],
+  length: number,
+  token: string
+};
+
+export function parseSRange (str: string, pos: number = 0): SRange {
+  const columns: string[] = [];
+  const start = pos;
+  let m;
+  let terms = 0;
+
+  // structured refs start with a [
+  if (str.charCodeAt(pos) !== BR_OPEN) {
+    return;
+  }
+
+  // simple keyword: [#keyword]
+  if ((m = matchKeyword(str, pos))) {
+    const k = str.slice(pos + 2, pos + m - 1);
+    pos += m;
+    const term = keyTerms[k.toLowerCase()];
+    if (!term) { return; }
+    terms |= term;
+  }
+  // simple column: [column]
+  else if ((m = matchColumn(str, pos, false))) {
+    pos += m[0].length;
+    if (m[1]) {
+      columns.push(m[1]);
+    }
+  }
+  // use the "normal" method
+  // [[#keyword]]
+  // [[column]]
+  // [@]
+  // [@column]
+  // [@[column]]
+  // [@column:column]
+  // [@column:[column]]
+  // [@[column]:column]
+  // [@[column]:[column]]
+  // [column:column]
+  // [column:[column]]
+  // [[column]:column]
+  // [[column]:[column]]
+  // [[#keyword],column]
+  // [[#keyword],column:column]
+  // [[#keyword],[#keyword],column:column]
+  // ...
+  else {
+    let expect_more = true;
+    pos++; // skip open brace
+    pos += skipWhitespace(str, pos);
+    // match keywords as we find them
+    while (expect_more && (m = matchKeyword(str, pos))) {
+      const k = str.slice(pos + 2, pos + m - 1);
+      const term = keyTerms[k.toLowerCase()];
+      if (!term) { return; }
+      terms |= term;
+      pos += m;
+      pos += skipWhitespace(str, pos);
+      expect_more = str.charCodeAt(pos) === COMMA;
+      if (expect_more) {
+        pos++;
+        pos += skipWhitespace(str, pos);
+      }
+    }
+    // is there an @ specifier?
+    if (expect_more && (str.charCodeAt(pos) === AT)) {
+      terms |= keyTerms['@'];
+      pos += 1;
+      expect_more = str.charCodeAt(pos) !== BR_CLOSE;
+    }
+    // not all keyword terms may be combined
+    if (!sectionMap[terms]) {
+      return;
+    }
+    // column definitions
+    const leftCol = expect_more && matchColumn(str, pos, true);
+    if (leftCol) {
+      pos += leftCol[0].length;
+      columns.push(leftCol[1]);
+      if (str.charCodeAt(pos) === COLON) {
+        pos++;
+        const rightCol = matchColumn(str, pos, true);
+        if (rightCol) {
+          pos += rightCol[0].length;
+          columns.push(rightCol[1]);
+        }
+        else {
+          return;
+        }
+      }
+      expect_more = false;
+    }
+    // advance ws
+    pos += skipWhitespace(str, pos);
+    // close the ref
+    if (expect_more || str.charCodeAt(pos) !== BR_CLOSE) {
+      return;
+    }
+    // step over the closing ]
+    pos++;
+  }
+
+  const sections: string[] = sectionMap[terms];
+  return {
+    columns,
+    sections: sections ? sections.concat() : sections,
+    length: pos - start,
+    token: str.slice(start, pos)
+  };
+}