@borgar/fx 4.13.0 → 5.0.0

package/lib/parseA1Range.ts

@@ -0,0 +1,206 @@
+import { MAX_COLS, MAX_ROWS } from './constants.ts';
+import type { RangeA1 } from './types.ts';
+
+type TrimString = 'both' | 'head' | 'tail';
+
+export function fromRow (rowStr: string): number {
+  return +rowStr - 1;
+}
+
+const CHAR_DOLLAR = 36;
+const CHAR_PERIOD = 46;
+const CHAR_COLON = 58;
+const CHAR_A_LC = 97;
+const CHAR_A_UC = 65;
+const CHAR_Z_LC = 122;
+const CHAR_Z_UC = 90;
+const CHAR_0 = 48;
+const CHAR_1 = 49;
+const CHAR_9 = 57;
+
+function advRangeOp (str: string, pos: number): [ number, TrimString | '' ] {
+  const c0 = str.charCodeAt(pos);
+  if (c0 === CHAR_PERIOD) {
+    const c1 = str.charCodeAt(pos + 1);
+    if (c1 === CHAR_COLON) {
+      return str.charCodeAt(pos + 2) === CHAR_PERIOD
+        ? [ 3, 'both' ]
+        : [ 2, 'head' ];
+    }
+  }
+  else if (c0 === CHAR_COLON) {
+    const c1 = str.charCodeAt(pos + 1);
+    return c1 === CHAR_PERIOD
+      ? [ 2, 'tail' ]
+      : [ 1, '' ];
+  }
+  return [ 0, '' ];
+}
+
+function advA1Col (str: string, pos: number): [ number, number, boolean ] {
+  // [A-Z]{1,3}
+  const start = pos;
+  const lock = str.charCodeAt(pos) === CHAR_DOLLAR;
+  if (lock) { pos++; }
+  const stop = pos + 3;
+  let col = 0;
+  do {
+    const c = str.charCodeAt(pos);
+    if (c >= CHAR_A_UC && c <= CHAR_Z_UC) {
+      col = (26 * col) + c - (CHAR_A_UC - 1);
+      pos++;
+    }
+    else if (c >= CHAR_A_LC && c <= CHAR_Z_LC) {
+      col = (26 * col) + c - (CHAR_A_LC - 1);
+      pos++;
+    }
+    else {
+      break;
+    }
+  }
+  while (pos < stop && pos < str.length);
+  return (col && col <= MAX_COLS + 1)
+    ? [ pos - start, col - 1, lock ]
+    : [ 0, 0, false ];
+}
+
+function advA1Row (str: string, pos: number): [number, number, boolean] {
+  // [1-9][0-9]{0,6}
+  const start = pos;
+  const lock = str.charCodeAt(pos) === CHAR_DOLLAR;
+  if (lock) { pos++; }
+  const stop = pos + 7;
+  let row = 0;
+  let c = str.charCodeAt(pos);
+  if (c >= CHAR_1 && c <= CHAR_9) {
+    row = (row * 10) + c - CHAR_0;
+    pos++;
+    do {
+      c = str.charCodeAt(pos);
+      if (c >= CHAR_0 && c <= CHAR_9) {
+        row = (row * 10) + c - CHAR_0;
+        pos++;
+      }
+      else {
+        break;
+      }
+    }
+    while (pos < stop && pos < str.length);
+  }
+  return (row && row <= MAX_ROWS + 1)
+    ? [ pos - start, row - 1, lock ]
+    : [ 0, 0, false ];
+}
+
+function makeRange (
+  top: number | null,
+  $top: boolean | null,
+  left: number | null,
+  $left: boolean | null,
+  bottom: number | null,
+  $bottom: boolean | null,
+  right: number | null,
+  $right: boolean | null,
+  trim: TrimString | ''
+): RangeA1 {
+  // flip left/right and top/bottom as needed
+  // for partial ranges we perfer the coord on the left-side of the:
+  if (right != null && (left == null || (left != null && right < left))) {
+    [ left, right, $left, $right ] = [ right, left, $right, $left ];
+  }
+  if (bottom != null && (top == null || (top != null && bottom < top))) {
+    [ top, bottom, $top, $bottom ] = [ bottom, top, $bottom, $top ];
+  }
+  const range: RangeA1 = { top, left, bottom, right, $top, $left, $bottom, $right };
+  if (trim) {
+    range.trim = trim;
+  }
+  return range;
+}
+
+/**
+ * Parse A1-style range string into a RangeA1 object.
+ *
+ * @param rangeString A1-style range string.
+ * @param [allowTernary] Permit ternary ranges like A2:A or B2:2.
+ * @return A reference object.
+ */
+export function parseA1Range (rangeString: string, allowTernary = true): RangeA1 | undefined {
+  let p = 0;
+  const [ leftChars, left, $left ] = advA1Col(rangeString, p);
+  let right = 0;
+  let $right = false;
+  let bottom = 0;
+  let $bottom = false;
+  let rightChars: number;
+  let bottomChars: number;
+  if (leftChars) {
+    // TLBR: could be A1:A1
+    // TL R: could be A1:A (if allowTernary)
+    // TLB : could be A1:1 (if allowTernary)
+    //  LBR: could be A:A1 (if allowTernary)
+    //  L R: could be A:A
+    p += leftChars;
+    const [ topChars, top, $top ] = advA1Row(rangeString, p);
+    p += topChars;
+    const [ op, trim ] = advRangeOp(rangeString, p);
+    if (op) {
+      p += op;
+      [ rightChars, right, $right ] = advA1Col(rangeString, p);
+      p += rightChars;
+      [ bottomChars, bottom, $bottom ] = advA1Row(rangeString, p);
+      p += bottomChars;
+      if (topChars && bottomChars && rightChars) {
+        if (p === rangeString.length) {
+          return makeRange(top, $top, left, $left, bottom, $bottom, right, $right, trim);
+        }
+      }
+      else if (!topChars && !bottomChars) {
+        if (p === rangeString.length) {
+          return makeRange(null, false, left, $left, null, false, right, $right, trim);
+        }
+      }
+      else if (allowTernary && (bottomChars || rightChars) && p === rangeString.length) {
+        if (!topChars) {
+          return makeRange(null, false, left, $left, bottom, $bottom, right, $right, trim);
+        }
+        else if (!bottomChars) {
+          return makeRange(top, $top, left, $left, null, false, right, $right, trim);
+        }
+        else {
+          return makeRange(top, $top, left, $left, bottom, $bottom, null, false, trim);
+        }
+      }
+    }
+    // LT  : this is A1
+    if (topChars && p === rangeString.length) {
+      return makeRange(top, $top, left, $left, top, $top, left, $left, trim);
+    }
+  }
+  else {
+    // T B : could be 1:1
+    // T BR: could be 1:A1 (if allowTernary)
+    const [ topChars, top, $top ] = advA1Row(rangeString, p);
+    if (topChars) {
+      p += topChars;
+      const [ op, trim ] = advRangeOp(rangeString, p);
+      if (op) {
+        p += op;
+        [ rightChars, right, $right ] = advA1Col(rangeString, p);
+        p += rightChars;
+        [ bottomChars, bottom, $bottom ] = advA1Row(rangeString, p);
+        p += bottomChars;
+        if (rightChars && bottomChars && allowTernary) {
+          if (p === rangeString.length) {
+            return makeRange(top, $top, null, false, bottom, $bottom, right, $right, trim);
+          }
+        }
+        else if (!rightChars && bottomChars) {
+          if (p === rangeString.length) {
+            return makeRange(top, $top, null, false, bottom, $bottom, null, false, trim);
+          }
+        }
+      }
+    }
+  }
+}

package/lib/parseA1Ref.spec.ts

@@ -0,0 +1,337 @@
+/* eslint-disable @stylistic/object-property-newline */
+import { describe, test, expect } from 'vitest';
+import { parseA1Ref, parseA1RefXlsx, type OptsParseA1Ref } from './parseA1Ref.ts';
+
+type IsA1EqualOptions = OptsParseA1Ref & {
+  xlsx?: boolean,
+};
+
+function isA1Equal (expr: string, expected: any, opts?: IsA1EqualOptions) {
+  const xlsx = !!(opts?.xlsx);
+  if (expected) {
+    expected = xlsx
+      ? { workbookName: '', sheetName: '', ...expected }
+      : { context: [], ...expected };
+    Object.assign(expected, expected);
+    if (expected.range && typeof expected.range === 'object') {
+      // mix in some defaults so we don't have to write things out in full
+      expected.range = {
+        top: null, left: null, bottom: null, right: null,
+        $top: false, $left: false, $bottom: false, $right: false,
+        ...expected.range
+      };
+    }
+  }
+  expect(xlsx ? parseA1RefXlsx(expr, opts) : parseA1Ref(expr, opts)).toEqual(expected);
+}
+
+describe('parse A1 references', () => {
+  test('basic A1 references', () => {
+    isA1Equal('A1', { range: { top: 0, left: 0, bottom: 0, right: 0 } });
+    isA1Equal('A1:B2', { range: { top: 0, left: 0, bottom: 1, right: 1 } });
+
+    isA1Equal('$A1:B2', { range: { top: 0, left: 0, bottom: 1, right: 1, $left: true } });
+    isA1Equal('A$1:B2', { range: { top: 0, left: 0, bottom: 1, right: 1, $top: true } });
+    isA1Equal('A1:$B2', { range: { top: 0, left: 0, bottom: 1, right: 1, $right: true } });
+    isA1Equal('A1:B$2', { range: { top: 0, left: 0, bottom: 1, right: 1, $bottom: true } });
+  });
+
+  test('column and row ranges', () => {
+    isA1Equal('A:A', { range: { left: 0, right: 0 } });
+    isA1Equal('C:C', { range: { left: 2, right: 2 } });
+    isA1Equal('C:$C', { range: { left: 2, right: 2, $right: true } });
+    isA1Equal('$C:C', { range: { left: 2, right: 2, $left: true } });
+    isA1Equal('$C:$C', { range: { left: 2, right: 2, $left: true, $right: true } });
+
+    isA1Equal('1:1', { range: { top: 0, bottom: 0 } });
+    isA1Equal('10:10', { range: { top: 9, bottom: 9 } });
+    isA1Equal('10:$10', { range: { top: 9, bottom: 9, $bottom: true } });
+    isA1Equal('$10:10', { range: { top: 9, bottom: 9, $top: true } });
+    isA1Equal('$10:$10', { range: { top: 9, bottom: 9, $top: true, $bottom: true } });
+  });
+
+  test('maximum ranges', () => {
+    isA1Equal('XFD1048576', { range: { top: 1048575, left: 16383, bottom: 1048575, right: 16383 } });
+  });
+
+  test('sheet references', () => {
+    isA1Equal('Sheet1!A1', {
+      context: [ 'Sheet1' ],
+      range: { top: 0, left: 0, bottom: 0, right: 0 }
+    });
+
+    isA1Equal('\'Sheet1\'!A1', {
+      context: [ 'Sheet1' ],
+      range: { top: 0, left: 0, bottom: 0, right: 0 }
+    });
+
+    isA1Equal('\'Sheet1\'\'s\'!A1', {
+      context: [ 'Sheet1\'s' ],
+      range: { top: 0, left: 0, bottom: 0, right: 0 }
+    });
+  });
+
+  test('workbook references', () => {
+    isA1Equal('[Workbook.xlsx]Sheet1!A1', {
+      context: [ 'Workbook.xlsx', 'Sheet1' ],
+      range: { top: 0, left: 0, bottom: 0, right: 0 }
+    });
+
+    isA1Equal("'[Workbook.xlsx]Sheet1'!A1", {
+      context: [ 'Workbook.xlsx', 'Sheet1' ],
+      range: { top: 0, left: 0, bottom: 0, right: 0 }
+    });
+
+    isA1Equal("='[Workbook.xlsx]Sheet1'!A1", {
+      context: [ 'Workbook.xlsx', 'Sheet1' ],
+      range: { top: 0, left: 0, bottom: 0, right: 0 }
+    });
+
+    isA1Equal('[foo bar]Sheet1!A1', {
+      context: [ 'foo bar', 'Sheet1' ],
+      range: { top: 0, left: 0, bottom: 0, right: 0 }
+    });
+
+    isA1Equal('[a "b" c]d!A1', {
+      context: [ 'a "b" c', 'd' ],
+      range: { top: 0, left: 0, bottom: 0, right: 0 }
+    });
+  });
+
+  test('long context names', () => {
+    // unless we know the contexts available, we don't know that this is a sheet
+    // or a filename, so we can't reject it:
+    isA1Equal('0123456789abcdefghijklmnopqrstuvwxyz!A1', {
+      context: [ '0123456789abcdefghijklmnopqrstuvwxyz' ],
+      range: { top: 0, left: 0, bottom: 0, right: 0 }
+    });
+  });
+
+  test('invalid references', () => {
+    isA1Equal('[Workbook.xlsx]!A1', undefined);
+    isA1Equal('[Workbook.xlsx]!A1:B2', undefined);
+    isA1Equal('[Workbook.xlsx]!A:A', undefined);
+    isA1Equal('[Workbook.xlsx]!1:1', undefined);
+    isA1Equal('[]Sheet1!A1', undefined);
+  });
+
+  test('named ranges', () => {
+    isA1Equal('namedrange', { name: 'namedrange' });
+
+    isA1Equal('Workbook.xlsx!namedrange', {
+      context: [ 'Workbook.xlsx' ],
+      name: 'namedrange'
+    });
+
+    isA1Equal("'Workbook.xlsx'!namedrange", {
+      context: [ 'Workbook.xlsx' ],
+      name: 'namedrange'
+    });
+
+    isA1Equal('[Workbook.xlsx]!namedrange', undefined);
+    isA1Equal('pensioneligibilitypartner1', { name: 'pensioneligibilitypartner1' });
+    isA1Equal('XFE1048577', { name: 'XFE1048577' });
+  });
+
+  test('named ranges with allowNamed: false', () => {
+    isA1Equal('namedrange', undefined, { allowNamed: false });
+    isA1Equal('Workbook.xlsx!namedrange', undefined, { allowNamed: false });
+    isA1Equal('pensioneligibilitypartner1', undefined, { allowNamed: false });
+    isA1Equal('XFE1048577', undefined, { allowNamed: false });
+  });
+});
+
+describe('parse A1 ranges in XLSX mode', () => {
+  const opts = { xlsx: true };
+
+  test('workbook references', () => {
+    isA1Equal('[1]!A1', {
+      workbookName: '1',
+      sheetName: '',
+      range: { top: 0, left: 0, bottom: 0, right: 0 }
+    }, opts);
+
+    isA1Equal('[Workbook.xlsx]!A1', {
+      workbookName: 'Workbook.xlsx',
+      sheetName: '',
+      range: { top: 0, left: 0, bottom: 0, right: 0 }
+    }, opts);
+
+    isA1Equal('[1]Sheet1!A1', {
+      workbookName: '1',
+      sheetName: 'Sheet1',
+      range: { top: 0, left: 0, bottom: 0, right: 0 }
+    }, opts);
+
+    isA1Equal('[Workbook.xlsx]Sheet1!A1', {
+      workbookName: 'Workbook.xlsx',
+      sheetName: 'Sheet1',
+      range: { top: 0, left: 0, bottom: 0, right: 0 }
+    }, opts);
+  });
+
+  test('named ranges in workbooks', () => {
+    isA1Equal('[4]!name', {
+      workbookName: '4',
+      sheetName: '',
+      name: 'name'
+    }, opts);
+
+    isA1Equal('[Workbook.xlsx]!name', {
+      workbookName: 'Workbook.xlsx',
+      sheetName: '',
+      name: 'name'
+    }, opts);
+
+    isA1Equal('[16]Sheet1!name', {
+      workbookName: '16',
+      sheetName: 'Sheet1',
+      name: 'name'
+    }, opts);
+
+    isA1Equal('[Workbook.xlsx]Sheet1!name', {
+      workbookName: 'Workbook.xlsx',
+      sheetName: 'Sheet1',
+      name: 'name'
+    }, opts);
+  });
+
+  test('quoted references', () => {
+    isA1Equal("='[1]'!A1", {
+      workbookName: '1',
+      sheetName: '',
+      range: { top: 0, left: 0, bottom: 0, right: 0 }
+    }, opts);
+
+    isA1Equal("='[Workbook.xlsx]'!A1", {
+      workbookName: 'Workbook.xlsx',
+      sheetName: '',
+      range: { top: 0, left: 0, bottom: 0, right: 0 }
+    }, opts);
+
+    isA1Equal("'[1]Sheet1'!A1", {
+      workbookName: '1',
+      sheetName: 'Sheet1',
+      range: { top: 0, left: 0, bottom: 0, right: 0 }
+    }, opts);
+
+    isA1Equal("'[Workbook.xlsx]Sheet1'!A1", {
+      workbookName: 'Workbook.xlsx',
+      sheetName: 'Sheet1',
+      range: { top: 0, left: 0, bottom: 0, right: 0 }
+    }, opts);
+
+    isA1Equal("'[4]'!name", {
+      workbookName: '4',
+      sheetName: '',
+      name: 'name'
+    }, opts);
+
+    isA1Equal("'[Workbook.xlsx]'!name", {
+      workbookName: 'Workbook.xlsx',
+      sheetName: '',
+      name: 'name'
+    }, opts);
+
+    isA1Equal("'[16]Sheet1'!name", {
+      workbookName: '16',
+      sheetName: 'Sheet1',
+      name: 'name'
+    }, opts);
+
+    isA1Equal("'[Workbook.xlsx]Sheet1'!name", {
+      workbookName: 'Workbook.xlsx',
+      sheetName: 'Sheet1',
+      name: 'name'
+    }, opts);
+  });
+});
+
+describe('A1 partial ranges', () => {
+  const opt = { allowTernary: true };
+
+  test('partial ranges not allowed by default', () => {
+    isA1Equal('A10:A', undefined);
+    isA1Equal('B3:2', undefined);
+  });
+
+  test('unbounded bottom ranges', () => {
+    isA1Equal('A10:A', { range: { top: 9, left: 0, right: 0 } }, opt);
+    isA1Equal('A:A10', { range: { top: 9, left: 0, right: 0 } }, opt);
+    isA1Equal('A$5:A', { range: { top: 4, left: 0, right: 0, $top: true } }, opt);
+    isA1Equal('A:A$5', { range: { top: 4, left: 0, right: 0, $top: true } }, opt);
+    isA1Equal('A$5:A', { range: { top: 4, left: 0, right: 0, $top: true } }, opt);
+    isA1Equal('A:$B5', { range: { top: 4, left: 0, right: 1, $right: true } }, opt);
+    isA1Equal('$B:B3', { range: { top: 2, left: 1, right: 1, $left: true } }, opt);
+    isA1Equal('$B:C5', { range: { top: 4, left: 1, right: 2, $left: true } }, opt);
+    isA1Equal('C2:B', { range: { top: 1, left: 1, right: 2 } }, opt);
+    isA1Equal('C:B2', { range: { top: 1, left: 1, right: 2 } }, opt);
+  });
+
+  test('unbounded right ranges', () => {
+    isA1Equal('D1:1', { range: { top: 0, left: 3, bottom: 0 } }, opt);
+    isA1Equal('1:D2', { range: { top: 0, left: 3, bottom: 1 } }, opt);
+    isA1Equal('2:$D3', { range: { top: 1, left: 3, bottom: 2, $left: true } }, opt);
+    isA1Equal('$D2:3', { range: { top: 1, left: 3, bottom: 2, $left: true } }, opt);
+    isA1Equal('1:D$1', { range: { top: 0, left: 3, bottom: 0, $bottom: true } }, opt);
+    isA1Equal('$1:D1', { range: { top: 0, left: 3, bottom: 0, $top: true } }, opt);
+    isA1Equal('AA$3:4', { range: { top: 2, left: 26, bottom: 3, $top: true } }, opt);
+    isA1Equal('B3:2', { range: { top: 1, bottom: 2, left: 1 } }, opt);
+    isA1Equal('3:B2', { range: { top: 1, bottom: 2, left: 1 } }, opt);
+  });
+});
+
+describe('A1 trimmed ranges', () => {
+  const locks = { $top: true, $left: true, $bottom: true, $right: true };
+  const opts = [ {}, { xlsx: true } ];
+
+  for (const opt of opts) {
+    test(`trimmed ranges with ${opt.xlsx ? 'XLSX' : 'default'} options`, () => {
+      isA1Equal('A1:B2', { range: { top: 0, left: 0, bottom: 1, right: 1 } }, opt);
+      isA1Equal('A1.:B2', { range: { top: 0, left: 0, bottom: 1, right: 1, trim: 'head' } }, opt);
+      isA1Equal('A1:.B2', { range: { top: 0, left: 0, bottom: 1, right: 1, trim: 'tail' } }, opt);
+      isA1Equal('A1.:.B2', { range: { top: 0, left: 0, bottom: 1, right: 1, trim: 'both' } }, opt);
+
+      isA1Equal('$A$1:$B$2', { range: { top: 0, left: 0, bottom: 1, right: 1, ...locks } }, opt);
+      isA1Equal('$A$1.:$B$2', { range: { top: 0, left: 0, bottom: 1, right: 1, trim: 'head', ...locks } }, opt);
+      isA1Equal('$A$1:.$B$2', { range: { top: 0, left: 0, bottom: 1, right: 1, trim: 'tail', ...locks } }, opt);
+      isA1Equal('$A$1.:.$B$2', { range: { top: 0, left: 0, bottom: 1, right: 1, trim: 'both', ...locks } }, opt);
+
+      isA1Equal('J:J', { range: { top: null, left: 9, bottom: null, right: 9 } }, opt);
+      isA1Equal('J.:J', { range: { top: null, left: 9, bottom: null, right: 9, trim: 'head' } }, opt);
+      isA1Equal('J:.J', { range: { top: null, left: 9, bottom: null, right: 9, trim: 'tail' } }, opt);
+      isA1Equal('J.:.J', { range: { top: null, left: 9, bottom: null, right: 9, trim: 'both' } }, opt);
+
+      isA1Equal('10:10', { range: { top: 9, left: null, bottom: 9, right: null } }, opt);
+      isA1Equal('10.:10', { range: { top: 9, left: null, bottom: 9, right: null, trim: 'head' } }, opt);
+      isA1Equal('10:.10', { range: { top: 9, left: null, bottom: 9, right: null, trim: 'tail' } }, opt);
+      isA1Equal('10.:.10', { range: { top: 9, left: null, bottom: 9, right: null, trim: 'both' } }, opt);
+
+      isA1Equal('J10:J', undefined, { ...opt });
+      isA1Equal('J10:10', undefined, { ...opt });
+      isA1Equal('J10.:.J', undefined, { ...opt });
+      isA1Equal('J10.:.10', undefined, { ...opt });
+      isA1Equal('J10:J', { range: { top: 9, left: 9, bottom: null, right: 9 } }, { allowTernary: true, ...opt });
+      isA1Equal('J10:10', { range: { top: 9, left: 9, bottom: 9, right: null } }, { allowTernary: true, ...opt });
+      isA1Equal('J10.:.J', { range: { top: 9, left: 9, bottom: null, right: 9, trim: 'both' } }, { allowTernary: true, ...opt });
+      isA1Equal('J10.:.10', { range: { top: 9, left: 9, bottom: 9, right: null, trim: 'both' } }, { allowTernary: true, ...opt });
+    });
+  }
+});
+
+describe('A1 trimmed ranges vs named ranges', () => {
+  test('named ranges cannot be trimmed', () => {
+    isA1Equal('name1.:.name1', undefined);
+    isA1Equal('name1.:.foo', undefined);
+    isA1Equal('foo.:.name1', undefined);
+  });
+
+  test('trimmed column references', () => {
+    // prior to the intruduction of trimed ranges, the following would have
+    // been an expression: NAME:`foo.` OP:`:`, COLUMN:`bar`
+    isA1Equal('foo.:bar', { range: { left: 1395, right: 4460, trim: 'head' } });
+    // prior to the intruduction of trimed ranges, the following would have
+    // been an expression: NAME:`foo.` OP:`:`, CELL:`B2`
+    isA1Equal('foo.:B2', { range: { top: 1, left: 1, right: 4460, trim: 'head' } }, { allowTernary: true });
+  });
+});

package/lib/parseA1Ref.ts

@@ -0,0 +1,115 @@
+import { parseRefCtx, parseRefXlsx } from './parseRef.ts';
+import { parseA1Range } from './parseA1Range.ts';
+import type { ReferenceA1, ReferenceA1Xlsx, ReferenceName, ReferenceNameXlsx } from './types.ts';
+
+/**
+ * Options for {@link parseA1Ref}.
+ */
+export type OptsParseA1Ref = {
+  /**
+   * Enable parsing names as well as ranges.
+   * @defaultValue true
+   */
+  allowNamed?: boolean,
+  /**
+   * Enables the recognition of ternary ranges in the style of `A1:A` or `A1:1`.
+   * These are supported by Google Sheets but not Excel. See: [References.md](./References.md).
+   * @defaultValue false
+   */
+  allowTernary?: boolean,
+};
+
+/**
+ * Parse a string reference into an object representing it.
+ *
+ * ```js
+ * parseA1Ref('Sheet1!A$1:$B2');
+ * // => {
+ * //   context: [ 'Sheet1' ],
+ * //   range: {
+ * //     top: 0,
+ * //     left: 0,
+ * //     bottom: 1,
+ * //     right: 1
+ * //     $top: true,
+ * //     $left: false,
+ * //     $bottom: false,
+ * //     $right: true
+ * //   }
+ * // }
+ * ```
+ *
+ * For A:A or A1:A style ranges, `null` will be used for any dimensions that the
+ * syntax does not specify.
+ *
+ * @see {@link OptsParseA1Ref}
+ * @param refString An A1-style reference string.
+ * @param options Options.
+ * @returns An object representing a valid reference or `undefined` if it is invalid.
+ */
+export function parseA1Ref (
+  refString: string,
+  { allowNamed = true, allowTernary = false }: OptsParseA1Ref = {}
+): ReferenceA1 | ReferenceName | undefined {
+  const d = parseRefCtx(refString, { allowNamed, allowTernary, r1c1: false });
+  if (d) {
+    if (d.name) {
+      return { context: d.context, name: d.name };
+    }
+    else if (d.r0) {
+      const range = parseA1Range(d.r1 ? d.r0 + d.operator + d.r1 : d.r0);
+      if (range) {
+        return { context: d.context, range };
+      }
+    }
+  }
+}
+
+/**
+ * Parse a string reference into an object representing it.
+ *
+ * ```js
+ * parseA1Ref('Sheet1!A$1:$B2');
+ * // => {
+ * //   workbookName: '',
+ * //   sheetName: 'Sheet1',
+ * //   range: {
+ * //     top: 0,
+ * //     left: 0,
+ * //     bottom: 1,
+ * //     right: 1
+ * //     $top: true,
+ * //     $left: false,
+ * //     $bottom: false,
+ * //     $right: true
+ * //   }
+ * // }
+ * ```
+ *
+ * For A:A or A1:A style ranges, `null` will be used for any dimensions that the
+ * syntax does not specify.
+ *
+ * @see {@link OptsParseA1Ref}
+ * @param refString An A1-style reference string.
+ * @param options Options.
+ * @returns An object representing a valid reference or `undefined` if it is invalid.
+ */
+export function parseA1RefXlsx (
+  refString: string,
+  { allowNamed = true, allowTernary = false }: OptsParseA1Ref = {}
+): ReferenceA1Xlsx | ReferenceNameXlsx | undefined {
+  const d = parseRefXlsx(refString, { allowNamed, allowTernary, r1c1: false });
+  if (d) {
+    if (d.name) {
+      return { workbookName: d.workbookName, sheetName: d.sheetName, name: d.name };
+    }
+    else if (d.r0) {
+      if (d.r0) {
+        const range = parseA1Range(d.r1 ? d.r0 + d.operator + d.r1 : d.r0);
+        if (range) {
+          return { workbookName: d.workbookName, sheetName: d.sheetName, range };
+        }
+      }
+    }
+  }
+}