@borgar/fx 4.12.0 → 5.0.0

package/lib/parseR1C1Range.ts

@@ -0,0 +1,191 @@
+/*
+** RC notation works differently from A1 in that we can't merge static
+** references joined by `:`. Merging can only work between references
+** that are relative/absolute on the same axes, so:
+** - R1C1:R2C2 will work,
+** - R[1]C1:R[2]C2 will also work, but
+** - R[1]C[1]:R2C2 doesn't have a direct rectangle represention without context.
+*/
+import type { RangeR1C1 } from './types.ts';
+
+function trimDirection (head: boolean, tail: boolean): 'both' | 'head' | 'tail' | undefined {
+  if (head && tail) {
+    return 'both';
+  }
+  if (head) {
+    return 'head';
+  }
+  if (tail) {
+    return 'tail';
+  }
+}
+
+function parseR1C1Part (ref: string): [number, number, boolean, boolean] {
+  let r0 = null;
+  let c0 = null;
+  let $r0 = null;
+  let $c0 = null;
+  // R part
+  const rm = /^R(?:\[([+-]?\d+)\]|(\d+))?/.exec(ref);
+  if (rm) {
+    if (rm[1]) {
+      r0 = parseInt(rm[1], 10);
+      $r0 = false;
+    }
+    else if (rm[2]) {
+      r0 = parseInt(rm[2], 10) - 1;
+      $r0 = true;
+    }
+    else {
+      r0 = 0;
+      $r0 = false;
+    }
+    ref = ref.slice(rm[0].length);
+  }
+  // C part
+  const cm = /^C(?:\[([+-]?\d+)\]|(\d+))?/.exec(ref);
+  if (cm) {
+    if (cm[1]) {
+      c0 = parseInt(cm[1], 10);
+      $c0 = false;
+    }
+    else if (cm[2]) {
+      c0 = parseInt(cm[2], 10) - 1;
+      $c0 = true;
+    }
+    else {
+      c0 = 0;
+      $c0 = false;
+    }
+    ref = ref.slice(cm[0].length);
+  }
+  // must have at least one part (and nothing more)
+  if ((!rm && !cm) || ref.length) {
+    return null;
+  }
+  return [ r0, c0, $r0, $c0 ];
+}
+
+/**
+ * Parse R1C1-style range string into a RangeR1C1 object.
+ *
+ * @param rangeString R1C1-style range string.
+ * @return A reference object.
+ */
+export function parseR1C1Range (rangeString: string): RangeR1C1 | null {
+  let final: RangeR1C1 | null = undefined;
+  const [ part1, op, part2, overflow ] = rangeString.split(/(\.?:\.?)/);
+  if (overflow) {
+    return null;
+  }
+  const range = parseR1C1Part(part1);
+  // eslint-disable-next-line @typescript-eslint/prefer-string-starts-ends-with
+  const trim = trimDirection(!!op && op[0] === '.', !!op && op[op.length - 1] === '.');
+  if (range) {
+    const [ r0, c0, $r0, $c0 ] = range;
+    if (part2) {
+      const extendTo = parseR1C1Part(part2);
+      if (extendTo) {
+        final = {};
+        const [ r1, c1, $r1, $c1 ] = extendTo;
+        // rows
+        if (r0 != null && r1 != null) {
+          final.r0 = $r0 === $r1 ? Math.min(r0, r1) : r0;
+          final.$r0 = $r0;
+          final.r1 = $r0 === $r1 ? Math.max(r0, r1) : r1;
+          final.$r1 = $r1;
+        }
+        else if (r0 != null && r1 == null) {
+          // partial RC:C
+          final.r0 = r0;
+          final.$r0 = $r0;
+          final.r1 = null;
+          final.$r1 = $r0;
+        }
+        else if (r0 == null && r1 != null) {
+          // partial C:RC
+          final.r0 = r1;
+          final.$r0 = $r1;
+          final.r1 = null;
+          final.$r1 = $r1;
+        }
+        else if (r0 == null && r1 == null) {
+          // C:C
+          final.r0 = null;
+          final.$r0 = false;
+          final.r1 = null;
+          final.$r1 = false;
+        }
+        // columns
+        if (c0 != null && c1 != null) {
+          final.c0 = $c0 === $c1 ? Math.min(c0, c1) : c0;
+          final.$c0 = $c0;
+          final.c1 = $c0 === $c1 ? Math.max(c0, c1) : c1;
+          final.$c1 = $c1;
+        }
+        else if (c0 != null && c1 == null) {
+          final.c0 = c0;
+          final.$c0 = $c0;
+          final.c1 = null;
+          final.$c1 = $c0;
+        }
+        else if (c0 == null && c1 != null) {
+          final.c0 = c1;
+          final.$c0 = $c1;
+          final.c1 = null;
+          final.$c1 = $c1;
+        }
+        else if (c0 == null && c1 == null) {
+          final.c0 = null;
+          final.$c0 = false;
+          final.c1 = null;
+          final.$c1 = false;
+        }
+      }
+      else {
+        return null;
+      }
+    }
+    // range only - no second part
+    else if (r0 != null && c0 == null) {
+      final = {
+        r0: r0,
+        c0: null,
+        r1: r0,
+        c1: null,
+        $r0: $r0,
+        $c0: false,
+        $r1: $r0,
+        $c1: false
+      };
+    }
+    else if (r0 == null && c0 != null) {
+      final = {
+        r0: null,
+        c0: c0,
+        r1: null,
+        c1: c0,
+        $r0: false,
+        $c0: $c0,
+        $r1: false,
+        $c1: $c0
+      };
+    }
+    else {
+      final = {
+        r0: r0 || 0,
+        c0: c0 || 0,
+        r1: r0 || 0,
+        c1: c0 || 0,
+        $r0: $r0 || false,
+        $c0: $c0 || false,
+        $r1: $r0 || false,
+        $c1: $c0 || false
+      };
+    }
+  }
+  if (final && trim) {
+    final.trim = trim;
+  }
+  return final;
+}

package/lib/parseR1C1Ref.spec.ts

@@ -0,0 +1,323 @@
+/* eslint-disable @stylistic/object-property-newline */
+import { describe, test, expect } from 'vitest';
+import { parseR1C1Ref, parseR1C1RefXlsx } from './parseR1C1Ref.ts';
+
+type OptsIsRCEqual = {
+  allowNamed?: boolean;
+  allowTernary?: boolean;
+  xlsx?: boolean;
+};
+
+function isRCEqual (expr: string, expected: any, opts?: OptsIsRCEqual) {
+  const xlsx = !!opts?.xlsx;
+  if (expected) {
+    expected = xlsx
+      ? { workbookName: '', sheetName: '', ...expected }
+      : { context: [], ...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 = {
+        r0: null, c0: null, r1: null, c1: null,
+        $r0: false, $c0: false, $r1: false, $c1: false,
+        ...expected.range
+      };
+    }
+  }
+  expect(xlsx ? parseR1C1RefXlsx(expr, opts) : parseR1C1Ref(expr, opts)).toEqual(expected);
+}
+
+describe('parse single R1C1 references', () => {
+  test('current row references', () => {
+    isRCEqual('R', { range: { r0: 0, r1: 0 } });
+    isRCEqual('R[0]', { range: { r0: 0, r1: 0 } });
+  });
+
+  test('fixed row references', () => {
+    isRCEqual('R0', { name: 'R0' });
+    isRCEqual('R1', { range: { r0: 0, r1: 0, $r0: true, $r1: true } });
+    isRCEqual('R10', { range: { r0: 9, r1: 9, $r0: true, $r1: true } });
+  });
+
+  test('relative row references', () => {
+    isRCEqual('R[1]', { range: { r0: 1, r1: 1 } });
+    isRCEqual('R[-1]', { range: { r0: -1, r1: -1 } });
+  });
+
+  test('current column references', () => {
+    isRCEqual('C', { range: { c0: 0, c1: 0 } });
+    isRCEqual('C[0]', { range: { c0: 0, c1: 0 } });
+  });
+
+  test('fixed column references', () => {
+    isRCEqual('C0', { name: 'C0' });
+    isRCEqual('C1', { range: { c0: 0, c1: 0, $c0: true, $c1: true } });
+    isRCEqual('C10', { range: { c0: 9, c1: 9, $c0: true, $c1: true } });
+  });
+
+  test('relative column references', () => {
+    isRCEqual('C[1]', { range: { c0: 1, c1: 1 } });
+    isRCEqual('C[-1]', { range: { c0: -1, c1: -1 } });
+  });
+
+  test('cell references', () => {
+    isRCEqual('RC', { range: { r0: 0, c0: 0, r1: 0, c1: 0 } });
+    isRCEqual('R0C0', { name: 'R0C0' });
+    isRCEqual('R1C1', { range: { r0: 0, c0: 0, r1: 0, c1: 0, $c0: true, $c1: true, $r0: true, $r1: true } });
+    isRCEqual('R10C8', { range: { r0: 9, c0: 7, r1: 9, c1: 7, $c0: true, $c1: true, $r0: true, $r1: true } });
+    isRCEqual('R-10C-8', undefined);
+  });
+
+  test('relative cell parts', () => {
+    isRCEqual('R[2]C', { range: { r0: 2, c0: 0, r1: 2, c1: 0 } });
+    isRCEqual('R[-2]C', { range: { r0: -2, c0: 0, r1: -2, c1: 0 } });
+    isRCEqual('RC[3]', { range: { r0: 0, c0: 3, r1: 0, c1: 3 } });
+    isRCEqual('RC[-3]', { range: { r0: 0, c0: -3, r1: 0, c1: -3 } });
+    isRCEqual('R[2]C[4]', { range: { r0: 2, c0: 4, r1: 2, c1: 4 } });
+    isRCEqual('R[-2]C[-4]', { range: { r0: -2, c0: -4, r1: -2, c1: -4 } });
+  });
+
+  test('mixed fixed and relative references', () => {
+    isRCEqual('R[9]C9', { range: { r0: 9, c0: 8, r1: 9, c1: 8, $c0: true, $c1: true } });
+    isRCEqual('R9C[9]', { range: { r0: 8, c0: 9, r1: 8, c1: 9, $r0: true, $r1: true } });
+  });
+
+  test('out of bounds references', () => {
+    isRCEqual('R1048577', { name: 'R1048577' });
+    isRCEqual('R[1048576]', undefined);
+    isRCEqual('C16385', { name: 'C16385' });
+    isRCEqual('C[16384]', undefined);
+  });
+});
+
+describe('R1C1 partial ranges', () => {
+  const opts = { allowTernary: true };
+
+  test('partials are not allowed by default', () => {
+    isRCEqual('R[-5]C[-2]:C[-2]', undefined);
+    isRCEqual('R1:R1C1', undefined);
+  });
+
+  test('beam type partials', () => {
+    isRCEqual('R[-5]C[-2]:C[-2]', { range: { r0: -5, c0: -2, c1: -2 } }, opts);
+    isRCEqual('C[-2]:R[-5]C[-2]', { range: { r0: -5, c0: -2, c1: -2 } }, opts);
+    isRCEqual('R[-5]C[-3]:R[-5]', { range: { r0: -5, c0: -3, r1: -5 } }, opts);
+    isRCEqual('R[-5]:R[-5]C[-3]', { range: { r0: -5, c0: -3, r1: -5 } }, opts);
+    isRCEqual('R[-6]C1:C1', { range: { r0: -6, c0: 0, c1: 0, $c0: true, $c1: true } }, opts);
+    isRCEqual('C1:R[-6]C1', { range: { r0: -6, c0: 0, c1: 0, $c0: true, $c1: true } }, opts);
+    isRCEqual('R[-6]C1:R[-6]', { range: { r0: -6, c0: 0, r1: -6, $c0: true, $c1: true } }, opts);
+    isRCEqual('R[-6]:R[-6]C1', { range: { r0: -6, c0: 0, r1: -6, $c0: true, $c1: true } }, opts);
+    isRCEqual('R1C[-2]:C[-2]', { range: { r0: 0, c0: -2, c1: -2, $r0: true, $c0: false, $r1: true, $c1: false } }, opts);
+    isRCEqual('C[-2]:R1C[-2]', { range: { r0: 0, c0: -2, c1: -2, $r0: true, $c0: false, $r1: true, $c1: false } }, opts);
+    isRCEqual('R1C[-3]:R1', { range: { r0: 0, c0: -3, r1: 0, $r0: true, $c0: false, $r1: true, $c1: false } }, opts);
+    isRCEqual('R1:R1C[-3]', { range: { r0: 0, c0: -3, r1: 0, $r0: true, $c0: false, $r1: true, $c1: false } }, opts);
+    isRCEqual('R1C1:C1', { range: { r0: 0, c0: 0, c1: 0, $r0: true, $c0: true, $r1: true, $c1: true } }, opts);
+    isRCEqual('C1:R1C1', { range: { r0: 0, c0: 0, c1: 0, $r0: true, $c0: true, $r1: true, $c1: true } }, opts);
+    isRCEqual('R1C1:R1', { range: { r0: 0, c0: 0, r1: 0, $r0: true, $c0: true, $r1: true, $c1: true } }, opts);
+    isRCEqual('R1:R1C1', { range: { r0: 0, c0: 0, r1: 0, $r0: true, $c0: true, $r1: true, $c1: true } }, opts);
+  });
+
+  test('range type partials', () => {
+    isRCEqual('R[-5]C[10]:R[4]', { range: { r0: -5, c0: 10, r1: 4 } }, opts);
+    isRCEqual('R[4]:R[-5]C[10]', { range: { r0: -5, c0: 10, r1: 4 } }, opts);
+    isRCEqual('R[-6]C16:R[3]', { range: { r0: -6, c0: 15, r1: 3, $c0: true, $c1: true } }, opts);
+    isRCEqual('R[3]:R[-6]C16', { range: { r0: -6, c0: 15, r1: 3, $c0: true, $c1: true } }, opts);
+    isRCEqual('R1C[10]:R10', { range: { r0: 0, c0: 10, r1: 9, $r0: true, $c0: false, $r1: true, $c1: false } }, opts);
+    isRCEqual('R10:R1C[10]', { range: { r0: 0, c0: 10, r1: 9, $r0: true, $c0: false, $r1: true, $c1: false } }, opts);
+    isRCEqual('R1C16:R10', { range: { r0: 0, c0: 15, r1: 9, $r0: true, $c0: true, $r1: true, $c1: true } }, opts);
+    isRCEqual('R10:R1C16', { range: { r0: 0, c0: 15, r1: 9, $r0: true, $c0: true, $r1: true, $c1: true } }, opts);
+  });
+});
+
+describe('parse joined R1C1 references', () => {
+  test('equivalent mirrored references', () => {
+    isRCEqual('R:R', { range: { r0: 0, r1: 0 } });
+    isRCEqual('R[0]:R[0]', { range: { r0: 0, r1: 0 } });
+    isRCEqual('R1:R1', { range: { r0: 0, r1: 0, $r0: true, $r1: true } });
+    isRCEqual('R10:R10', { range: { r0: 9, r1: 9, $r0: true, $r1: true } });
+    isRCEqual('R[1]:R[1]', { range: { r0: 1, r1: 1 } });
+    isRCEqual('R[-1]:R[-1]', { range: { r0: -1, r1: -1 } });
+
+    isRCEqual('C:C', { range: { c0: 0, c1: 0 } });
+    isRCEqual('C[0]:C[0]', { range: { c0: 0, c1: 0 } });
+    isRCEqual('C1:C1', { range: { c0: 0, c1: 0, $c0: true, $c1: true } });
+    isRCEqual('C10:C10', { range: { c0: 9, c1: 9, $c0: true, $c1: true } });
+    isRCEqual('C[1]:C[1]', { range: { c0: 1, c1: 1 } });
+    isRCEqual('C[-1]:C[-1]', { range: { c0: -1, c1: -1 } });
+  });
+
+  test('invalid range combinations', () => {
+    isRCEqual('R0:R0', undefined);
+    isRCEqual('C0:C0', undefined);
+  });
+
+  test('complex range references', () => {
+    isRCEqual('R[9]C9:R[9]C9', { range: { r0: 9, c0: 8, r1: 9, c1: 8, $c0: true, $c1: true } });
+    isRCEqual('R9C[9]:R9C[9]', { range: { r0: 8, c0: 9, r1: 8, c1: 9, $r0: true, $r1: true } });
+    isRCEqual('R[1]C[1]:R1C1', { range: { r0: 1, c0: 1, r1: 0, c1: 0, $c1: true, $r1: true } });
+    isRCEqual('R1C1:R2C2', { range: { r0: 0, c0: 0, r1: 1, c1: 1, $c0: true, $c1: true, $r0: true, $r1: true } });
+    isRCEqual('R2C2:R1C1', { range: { r0: 0, c0: 0, r1: 1, c1: 1, $c0: true, $c1: true, $r0: true, $r1: true } });
+  });
+
+  test('single dimension ranges', () => {
+    isRCEqual('C1:C3', { range: { c0: 0, c1: 2, $c0: true, $c1: true } });
+    isRCEqual('R[1]:R3', { range: { r0: 1, r1: 2, $r1: true } });
+    isRCEqual('R[1]C1:R1C[-1]', { range: { r0: 1, c0: 0, r1: 0, c1: -1, $c0: true, $r1: true, $c1: false } });
+  });
+
+  test('invalid mixed references', () => {
+    isRCEqual('R:C', undefined);
+    isRCEqual('R:RC', undefined);
+    isRCEqual('RC:R', undefined);
+    isRCEqual('RC:C', undefined);
+    isRCEqual('C:R', undefined);
+    isRCEqual('C:RC', undefined);
+  });
+});
+
+describe('parse R1C1 ranges in XLSX mode', () => {
+  const opts = { xlsx: true };
+  const rcRange = { r0: 0, c0: 0, r1: 0, c1: 0 };
+
+  test('workbook-only references', () => {
+    isRCEqual('[1]!RC', {
+      workbookName: '1',
+      sheetName: '',
+      range: rcRange
+    }, opts);
+
+    isRCEqual('[Workbook.xlsx]!RC', {
+      workbookName: 'Workbook.xlsx',
+      sheetName: '',
+      range: rcRange
+    }, opts);
+  });
+
+  test('workbook and sheet references', () => {
+    isRCEqual('[1]Sheet1!RC', {
+      workbookName: '1',
+      sheetName: 'Sheet1',
+      range: rcRange
+    }, opts);
+
+    isRCEqual('[Workbook.xlsx]Sheet1!RC', {
+      workbookName: 'Workbook.xlsx',
+      sheetName: 'Sheet1',
+      range: rcRange
+    }, opts);
+  });
+
+  test('named references', () => {
+    isRCEqual('[4]!name', {
+      workbookName: '4',
+      sheetName: '',
+      name: 'name'
+    }, opts);
+
+    isRCEqual('[Workbook.xlsx]!name', {
+      workbookName: 'Workbook.xlsx',
+      sheetName: '',
+      name: 'name'
+    }, opts);
+
+    isRCEqual('[16]Sheet1!name', {
+      workbookName: '16',
+      sheetName: 'Sheet1',
+      name: 'name'
+    }, opts);
+
+    isRCEqual('[Workbook.xlsx]Sheet1!name', {
+      workbookName: 'Workbook.xlsx',
+      sheetName: 'Sheet1',
+      name: 'name'
+    }, opts);
+  });
+
+  test('quoted references', () => {
+    isRCEqual("='[1]'!RC", {
+      workbookName: '1',
+      sheetName: '',
+      range: rcRange
+    }, opts);
+
+    isRCEqual("='[Workbook.xlsx]'!RC", {
+      workbookName: 'Workbook.xlsx',
+      sheetName: '',
+      range: rcRange
+    }, opts);
+
+    isRCEqual("'[1]Sheet1'!RC", {
+      workbookName: '1',
+      sheetName: 'Sheet1',
+      range: rcRange
+    }, opts);
+
+    isRCEqual("'[Workbook.xlsx]Sheet1'!RC", {
+      workbookName: 'Workbook.xlsx',
+      sheetName: 'Sheet1',
+      range: rcRange
+    }, opts);
+
+    isRCEqual("'[4]'!name", {
+      workbookName: '4',
+      sheetName: '',
+      name: 'name'
+    }, opts);
+
+    isRCEqual("'[Workbook.xlsx]'!name", {
+      workbookName: 'Workbook.xlsx',
+      sheetName: '',
+      name: 'name'
+    }, opts);
+
+    isRCEqual("'[16]Sheet1'!name", {
+      workbookName: '16',
+      sheetName: 'Sheet1',
+      name: 'name'
+    }, opts);
+
+    isRCEqual("'[Workbook.xlsx]Sheet1'!name", {
+      workbookName: 'Workbook.xlsx',
+      sheetName: 'Sheet1',
+      name: 'name'
+    }, opts);
+  });
+});
+
+describe('R1C1 trimmed ranges', () => {
+  const locks = { $r0: true, $r1: true, $c0: true, $c1: true };
+  const opts = [ {}, { xlsx: true } ];
+
+  for (const opt of opts) {
+    test(`trimmed ranges with ${opt.xlsx ? 'XLSX' : 'default'} options`, () => {
+      isRCEqual('R[1]C[1]:R[2]C[2]', { range: { r0: 1, r1: 2, c0: 1, c1: 2 } }, opt);
+      isRCEqual('R[1]C[1].:R[2]C[2]', { range: { r0: 1, r1: 2, c0: 1, c1: 2, trim: 'head' } }, opt);
+      isRCEqual('R[1]C[1]:.R[2]C[2]', { range: { r0: 1, r1: 2, c0: 1, c1: 2, trim: 'tail' } }, opt);
+      isRCEqual('R[1]C[1].:.R[2]C[2]', { range: { r0: 1, r1: 2, c0: 1, c1: 2, trim: 'both' } }, opt);
+
+      isRCEqual('R2C2:R3C3', { range: { r0: 1, r1: 2, c0: 1, c1: 2, ...locks } }, opt);
+      isRCEqual('R2C2.:R3C3', { range: { r0: 1, r1: 2, c0: 1, c1: 2, trim: 'head', ...locks } }, opt);
+      isRCEqual('R2C2:.R3C3', { range: { r0: 1, r1: 2, c0: 1, c1: 2, trim: 'tail', ...locks } }, opt);
+      isRCEqual('R2C2.:.R3C3', { range: { r0: 1, r1: 2, c0: 1, c1: 2, trim: 'both', ...locks } }, opt);
+
+      isRCEqual('C[1]:C[2]', { range: { c0: 1, c1: 2 } }, opt);
+      isRCEqual('C[1].:C[2]', { range: { c0: 1, c1: 2, trim: 'head' } }, opt);
+      isRCEqual('C[1]:.C[2]', { range: { c0: 1, c1: 2, trim: 'tail' } }, opt);
+      isRCEqual('C[1].:.C[2]', { range: { c0: 1, c1: 2, trim: 'both' } }, opt);
+
+      isRCEqual('R[10]:R[10]', { range: { r0: 10, r1: 10 } }, opt);
+      isRCEqual('R[10].:R[10]', { range: { r0: 10, r1: 10, trim: 'head' } }, opt);
+      isRCEqual('R[10]:.R[10]', { range: { r0: 10, r1: 10, trim: 'tail' } }, opt);
+      isRCEqual('R[10].:.R[10]', { range: { r0: 10, r1: 10, trim: 'both' } }, opt);
+
+      isRCEqual('R[2]C[2]:R[4]', undefined, { ...opt });
+      isRCEqual('R[2]C[2]:C[4]', undefined, { ...opt });
+      isRCEqual('R[2]C[2].:.R[4]', undefined, { ...opt });
+      isRCEqual('R[2]C[2].:.C[4]', undefined, { ...opt });
+
+      isRCEqual('R[2]C[2]:R[4]', { range: { r0: 2, r1: 4, c0: 2 } }, { allowTernary: true, ...opt });
+      isRCEqual('R[2]C[2]:C[4]', { range: { r0: 2, c0: 2, c1: 4 } }, { allowTernary: true, ...opt });
+      isRCEqual('R[2]C[2].:.R[4]', { range: { r0: 2, r1: 4, c0: 2, trim: 'both' } }, { allowTernary: true, ...opt });
+      isRCEqual('R[2]C[2].:.C[4]', { range: { r0: 2, c0: 2, c1: 4, trim: 'both' } }, { allowTernary: true, ...opt });
+    });
+  }
+});

package/lib/parseR1C1Ref.ts

@@ -0,0 +1,127 @@
+/*
+** RC notation works differently from A1 in that we can't merge static
+** references joined by `:`. Merging can only work between references
+** that are relative/absolute on the same axes, so:
+** - R1C1:R2C2 will work,
+** - R[1]C1:R[2]C2 will also work, but
+** - R[1]C[1]:R2C2 doesn't have a direct rectangle represention without context.
+*/
+import type { ReferenceName, ReferenceNameXlsx, ReferenceR1C1, ReferenceR1C1Xlsx } from './types.ts';
+import { parseR1C1Range } from './parseR1C1Range.ts';
+import { parseRefCtx, parseRefXlsx } from './parseRef.ts';
+
+/**
+ * Options for {@link parseR1C1Ref}.
+ */
+export type OptsParseR1C1Ref = {
+  /**
+   * 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
+ * parseR1C1Ref('Sheet1!R[9]C9:R[9]C9');
+ * // => {
+ * //   context: [ 'Sheet1' ],
+ * //   range: {
+ * //     r0: 9,
+ * //     c0: 8,
+ * //     r1: 9,
+ * //     c1: 8,
+ * //     $c0: true,
+ * //     $c1: true
+ * //     $r0: false,
+ * //     $r1: false
+ * //   }
+ * // }
+ * ```
+ *
+ * @see {@link OptsParseR1C1Ref}
+ * @param refString An R1C1-style reference string.
+ * @param [options] Options.
+ * @returns An object representing a valid reference or `undefined` if it is invalid.
+ */
+export function parseR1C1Ref (
+  refString: string,
+  options: OptsParseR1C1Ref = {}
+): ReferenceR1C1 | ReferenceName | undefined {
+  const {
+    allowNamed = true,
+    allowTernary = false
+  } = options;
+  const d = parseRefCtx(refString, { allowNamed, allowTernary, r1c1: true });
+  if (d) {
+    if (d.name) {
+      return { context: d.context, name: d.name } as ReferenceName;
+    }
+    else if (d.r0) {
+      const range = d.r1
+        ? parseR1C1Range(d.r0 + d.operator + d.r1)
+        : parseR1C1Range(d.r0);
+      if (range) {
+        return { context: d.context, range } as ReferenceR1C1;
+      }
+    }
+  }
+}
+
+/**
+ * Parse a string reference into an object representing it.
+ *
+ * ```js
+ * parseR1C1Ref('Sheet1!R[9]C9:R[9]C9');
+ * // => {
+ * //   context: [ 'Sheet1' ],
+ * //   range: {
+ * //     r0: 9,
+ * //     c0: 8,
+ * //     r1: 9,
+ * //     c1: 8,
+ * //     $c0: true,
+ * //     $c1: true
+ * //     $r0: false,
+ * //     $r1: false
+ * //   }
+ * // }
+ * ```
+ *
+ * @see {@link OptsParseR1C1Ref}
+ * @param refString An R1C1-style reference string.
+ * @param [options] Options.
+ * @returns An object representing a valid reference or `undefined` if it is invalid.
+ */
+export function parseR1C1RefXlsx (
+  refString: string,
+  options: OptsParseR1C1Ref = {}
+): ReferenceR1C1Xlsx | ReferenceNameXlsx | undefined {
+  const {
+    allowNamed = true,
+    allowTernary = false
+  } = options;
+  const d = parseRefXlsx(refString, { allowNamed, allowTernary, r1c1: true });
+  if (d) {
+    if (d.name && allowNamed) {
+      return { workbookName: d.workbookName, sheetName: d.sheetName, name: d.name } as ReferenceNameXlsx;
+    }
+    else if (d.r0) {
+      const range = d.r1
+        ? parseR1C1Range(d.r0 + d.operator + d.r1)
+        : parseR1C1Range(d.r0);
+      if (range) {
+        return { workbookName: (d).workbookName, sheetName: (d).sheetName, range } as ReferenceR1C1Xlsx;
+      }
+    }
+  }
+}