@borgar/fx 4.13.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.js → parseSRange.ts}

@@ -1,6 +1,4 @@
-/* eslint-disable no-multi-spaces */
-/* eslint-disable no-undefined */
-import { isWS } from './lexers/lexWhitespace.js';
+import { isWS } from './lexers/lexWhitespace.ts';
 
 const AT = 64; // @
 const BR_CLOSE = 93; // ]
@@ -20,7 +18,7 @@ const keyTerms = {
 };
 
 // only combinations allowed are: #data + (#headers | #totals | #data)
-const fz = (...a) => Object.freeze(a);
+const fz = (...a: string[]) => Object.freeze(a);
 const sectionMap = {
   // no terms
   0: fz(),
@@ -36,7 +34,7 @@ const sectionMap = {
   6: fz('data', 'totals')
 };
 
-function matchKeyword (str, pos) {
+function matchKeyword (str: string, pos: number): number {
   let p = pos;
   if (str.charCodeAt(p++) !== BR_OPEN) {
     return;
@@ -64,13 +62,13 @@ function matchKeyword (str, pos) {
   return p - pos;
 }
 
-function skipWhitespace (str, pos) {
+function skipWhitespace (str: string, pos: number): number {
   let p = pos;
   while (isWS(str.charCodeAt(p))) { p++; }
   return p - pos;
 }
 
-function matchColumn (str, pos, allowUnbraced = true) {
+function matchColumn (str: string, pos: number, allowUnbraced = true): [ string, string ] {
   let p = pos;
   let column = '';
   if (str.charCodeAt(p) === BR_OPEN) {
@@ -125,8 +123,15 @@ function matchColumn (str, pos, allowUnbraced = true) {
   }
 }
 
-export function parseSRange (str, pos = 0) {
-  const columns = [];
+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;
@@ -225,7 +230,7 @@ export function parseSRange (str, pos = 0) {
     pos++;
   }
 
-  const sections = sectionMap[terms];
+  const sections: string[] = sectionMap[terms];
   return {
     columns,
     sections: sections ? sections.concat() : sections,

package/lib/parseStructRef.spec.ts

@@ -0,0 +1,168 @@
+import { describe, test, expect } from 'vitest';
+import { parseStructRef, parseStructRefXlsx } from './parseStructRef.ts';
+
+function isSREqual (expr: string, expected: any, opts?: any) {
+  if (expected) {
+    expected = opts?.xlsx
+      ? {
+        workbookName: '',
+        sheetName: '',
+        table: '',
+        columns: [],
+        sections: [],
+        ...expected
+      }
+      : {
+        context: [],
+        table: '',
+        columns: [],
+        sections: [],
+        ...expected
+      };
+  }
+  expect(opts?.xlsx ? parseStructRefXlsx(expr) : parseStructRef(expr)).toEqual(expected);
+}
+
+describe('parse structured references', () => {
+  test('basic table and column references', () => {
+    isSREqual('table[col]', {
+      table: 'table',
+      columns: [ 'col' ]
+    });
+
+    isSREqual('table[]', {
+      table: 'table'
+    });
+  });
+
+  test('section references', () => {
+    isSREqual('[#All]', {
+      sections: [ 'all' ]
+    });
+  });
+
+  test('column name references', () => {
+    isSREqual('[column name]', {
+      columns: [ 'column name' ]
+    });
+
+    isSREqual('[[my column]]', {
+      columns: [ 'my column' ]
+    });
+  });
+
+  test('invalid references', () => {
+    isSREqual('[column name]!foo', undefined);
+    isSREqual('[foo]bar', undefined);
+  });
+
+  test('column range references', () => {
+    isSREqual('[[my column]:otherColumn]', {
+      columns: [ 'my column', 'otherColumn' ]
+    });
+
+    isSREqual('[ [my column]:otherColumn ]', {
+      columns: [ 'my column', 'otherColumn ' ]
+    });
+
+    isSREqual('[ [my column]: otherColumn ]', {
+      columns: [ 'my column', ' otherColumn ' ]
+    });
+  });
+
+  test('this row references', () => {
+    isSREqual('[ @[ my column ]: otherColumn ]', {
+      columns: [ ' my column ', ' otherColumn ' ],
+      sections: [ 'this row' ]
+    });
+  });
+
+  test('section and column combinations', () => {
+    isSREqual('[[#Data], [my column]:otherColumn]', {
+      columns: [ 'my column', 'otherColumn' ],
+      sections: [ 'data' ]
+    });
+
+    isSREqual('[ [#Data], [my column]:[\'@foo] ]', {
+      columns: [ 'my column', '@foo' ],
+      sections: [ 'data' ]
+    });
+  });
+
+  test('context-qualified references', () => {
+    isSREqual('workbook.xlsx!tableName[ [#Data], [my column]:[\'@foo] ]', {
+      columns: [ 'my column', '@foo' ],
+      sections: [ 'data' ],
+      table: 'tableName',
+      context: [ 'workbook.xlsx' ]
+    });
+
+    isSREqual("'Sheet'!Table[Column]", {
+      columns: [ 'Column' ],
+      table: 'Table',
+      context: [ 'Sheet' ]
+    });
+
+    isSREqual("Sheet1!Table1[foo '[bar']]", {
+      columns: [ 'foo [bar]' ],
+      table: 'Table1',
+      context: [ 'Sheet1' ]
+    });
+
+    isSREqual('[myworkbook.xlsx]Sheet1!TMP8w0habhr[#All]', {
+      columns: [],
+      table: 'TMP8w0habhr',
+      context: [ 'myworkbook.xlsx', 'Sheet1' ],
+      sections: [ 'all' ]
+    });
+  });
+
+  test('duplicate section handling', () => {
+    isSREqual('[[#Data],[#data],[#Data],[#Data],[#Totals],[#Totals],[#Totals],foo]', {
+      columns: [ 'foo' ],
+      sections: [ 'data', 'totals' ]
+    });
+  });
+});
+
+describe('structured references parse in xlsx mode', () => {
+  test('workbook-only references', () => {
+    isSREqual('[Workbook.xlsx]!Table[#Data]', {
+      workbookName: 'Workbook.xlsx',
+      table: 'Table',
+      sections: [ 'data' ]
+    }, { xlsx: true });
+  });
+
+  test('workbook and sheet references', () => {
+    isSREqual('[Workbook.xlsx]Sheet1!Table[#Data]', {
+      workbookName: 'Workbook.xlsx',
+      sheetName: 'Sheet1',
+      table: 'Table',
+      sections: [ 'data' ]
+    }, { xlsx: true });
+  });
+
+  test('sheet-only references', () => {
+    isSREqual('Sheet1!Table[#Data]', {
+      sheetName: 'Sheet1',
+      table: 'Table',
+      sections: [ 'data' ]
+    }, { xlsx: true });
+  });
+});
+
+describe('longform parse (in xlsx mode)', () => {
+  test('thisRow option should have no effect when parsing', () => {
+    const expectedResult = {
+      table: 'Table2',
+      columns: [ 'col1' ],
+      sections: [ 'this row' ]
+    };
+
+    isSREqual('Table2[[#This Row],[col1]]', expectedResult, { xlsx: true, thisRow: true });
+    isSREqual('Table2[[#This Row],[col1]]', expectedResult, { xlsx: true, thisRow: false });
+    isSREqual('Table2[[#This Row],[col1]]', expectedResult, { xlsx: false, thisRow: true });
+    isSREqual('Table2[[#This Row],[col1]]', expectedResult, { xlsx: false, thisRow: false });
+  });
+});

package/lib/parseStructRef.ts

@@ -0,0 +1,76 @@
+import type { ReferenceStruct, ReferenceStructXlsx } from './types.ts';
+import { parseRefCtx, parseRefXlsx } from './parseRef.ts';
+import { parseSRange } from './parseSRange.ts';
+
+/**
+ * Parse a structured reference string into an object representing it.
+ *
+ * ```js
+ * parseStructRef('workbook.xlsx!tableName[[#Data],[Column1]:[Column2]]');
+ * // => {
+ * //   context: [ 'workbook.xlsx' ],
+ * //   sections: [ 'data' ],
+ * //   columns: [ 'my column', '@foo' ],
+ * //   table: 'tableName',
+ * // }
+ * ```
+ *
+ * For A:A or A1:A style ranges, `null` will be used for any dimensions that the
+ * syntax does not specify:
+ *
+ * See [References.md](./References.md).
+ *
+ * @param ref A structured reference string
+ * @returns An object representing a valid reference or `undefined` if it is invalid.
+ */
+export function parseStructRef (ref: string): ReferenceStruct | undefined {
+  const r = parseRefCtx(ref);
+  if (r && r.struct) {
+    const structData = parseSRange(r.struct);
+    if (structData && structData.length === r.struct.length) {
+      return {
+        context: r.context,
+        table: r.name,
+        columns: structData.columns,
+        sections: structData.sections
+      };
+    }
+  }
+}
+
+/**
+ * Parse a structured reference string into an object representing it.
+ *
+ * ```js
+ * parseStructRef('[workbook.xlsx]!tableName[[#Data],[Column1]:[Column2]]');
+ * // => {
+ * //   workbookName: 'workbook.xlsx',
+ * //   sections: [ 'data' ],
+ * //   columns: [ 'my column', '@foo' ],
+ * //   table: 'tableName',
+ * // }
+ * ```
+ *
+ * For A:A or A1:A style ranges, `null` will be used for any dimensions that the
+ * syntax does not specify:
+ *
+ * See [References.md](./References.md).
+ *
+ * @param ref A structured reference string
+ * @returns An object representing a valid reference or null if it is invalid.
+ */
+export function parseStructRefXlsx (ref: string): ReferenceStructXlsx | undefined {
+  const r = parseRefXlsx(ref);
+  if (r && r.struct) {
+    const structData = parseSRange(r.struct);
+    if (structData && structData.length === r.struct.length) {
+      return {
+        workbookName: r.workbookName,
+        sheetName: r.sheetName,
+        table: r.name,
+        columns: structData.columns,
+        sections: structData.sections
+      };
+    }
+  }
+}