@borgar/fx 4.13.0 → 5.0.0

package/lib/translateToA1.ts

@@ -0,0 +1,231 @@
+import { MAX_ROWS, MAX_COLS, ERROR } from './constants.ts';
+import { stringifyA1RefXlsx } from './stringifyA1Ref.ts';
+import { parseR1C1RefXlsx } from './parseR1C1Ref.ts';
+import { tokenizeXlsx } from './tokenize.ts';
+import { isRange } from './isType.ts';
+import { parseA1Range } from './parseA1Range.ts';
+import type { RangeA1, ReferenceR1C1Xlsx, Token } from './types.ts';
+import { stringifyTokens } from './stringifyTokens.ts';
+import { cloneToken } from './cloneToken.ts';
+
+// Turn on the most permissive setting when parsing ranges so we don't have to think about
+// this option. We already know that range tokens are legal, so we're not going to encounter
+// ternary ranges who's validity we need to worry about.
+const REF_OPTS = { allowTernary: true };
+
+function toFixed (val: number, abs: boolean, base: number, max: number, wrapEdges = true) {
+  let v = val;
+  if (v != null && !abs) {
+    v = base + val;
+    // Excel "wraps around" when value goes out of lower bounds.
+    // It's a bit quirky on entry as Excel _really wants_ to re-rewite the
+    // references but the behaviour is consistent with INDIRECT:
+    // ... In A1: RC[-1] => R1C[16383].
+    if (v < 0) {
+      if (!wrapEdges) {
+        return NaN;
+      }
+      v = max + v + 1;
+    }
+    // ... In B1: =RC[16383] => =RC[-1]
+    if (v > max) {
+      if (!wrapEdges) {
+        return NaN;
+      }
+      v -= max + 1;
+    }
+  }
+  return v;
+}
+
+/**
+ * Options for {@link translateTokensToA1}
+ */
+export type OptsTranslateTokensToA1 = {
+  /**
+  * Wrap out-of-bounds ranges around sheet edges rather than turning them to #REF! errors.
+  * @defaultValue true
+  */
+  wrapEdges?: boolean,
+};
+
+/**
+ * Translates ranges in a list of tokens from relative R1C1 syntax to absolute A1 syntax.
+ *
+ * ```js
+ * translateToA1("=SUM(RC[1],R2C5,Sheet!R3C5)", "D10");
+ * // => "=SUM(E10,$E$2,Sheet!$E$3)");
+ * ```
+ *
+ * If an input range is -1,-1 relative rows/columns and the anchor is A1, the
+ * resulting range will (by default) wrap around to the bottom of the sheet
+ * resulting in the range XFD1048576. This may not be what you want so may set
+ * `{ wrapEdges }` to false which will instead turn the range into a `#REF!` error.
+ *
+ * ```js
+ * translateToA1("=R[-1]C[-1]", "A1");
+ * // => "=XFD1048576");
+ *
+ * translateToA1("=R[-1]C[-1]", "A1", { wrapEdges: false });
+ * // => "=#REF!");
+ * ```
+ *
+ * Note that if you are passing in a list of tokens that was not created using
+ * `mergeRefs` and you disable edge wrapping (or you simply set both options
+ * to false), you can end up with a formula such as `=#REF!:B2` or
+ * `=Sheet3!#REF!:F3`. These are valid formulas in the Excel formula language
+ * and Excel will accept them, but they are not supported in Google Sheets.
+ *
+ * @see {@link OptsTranslateTokensToA1}
+ * @param tokens A token list that should be adjusted.
+ * @param anchorCell A simple string reference to an A1 cell ID (`AF123` or`$C$5`).
+ * @param options Translation options.
+ * @returns A token list.
+ */
+export function translateTokensToA1 (
+  tokens: Token[],
+  anchorCell: string,
+  options: OptsTranslateTokensToA1 = {}
+): Token[] {
+  const anchorRange = parseA1Range(anchorCell);
+  if (!anchorRange) {
+    throw new Error('translateToR1C1 got an invalid anchorCell: ' + anchorCell);
+  }
+  const { top, left } = anchorRange;
+  const { wrapEdges = true } = options;
+
+  let offsetSkew = 0;
+  const outTokens = [];
+  for (let token of tokens) {
+    if (isRange(token)) {
+      token = cloneToken(token);
+      const tokenValue = token.value;
+      // We can get away with using the xlsx ref-parser here because it is more permissive
+      // and we will end up with the same prefix after serialization anyway:
+      const ref = parseR1C1RefXlsx(tokenValue, REF_OPTS) as ReferenceR1C1Xlsx;
+      const d = ref.range;
+      const range: RangeA1 = { top: 0, left: 0 };
+      const r0 = toFixed(d.r0, d.$r0, top, MAX_ROWS, wrapEdges);
+      const r1 = toFixed(d.r1, d.$r1, top, MAX_ROWS, wrapEdges);
+      if (r0 > r1) {
+        range.top = r1;
+        range.$top = d.$r1;
+        range.bottom = r0;
+        range.$bottom = d.$r0;
+      }
+      else {
+        range.top = r0;
+        range.$top = d.$r0;
+        range.bottom = r1;
+        range.$bottom = d.$r1;
+      }
+      const c0 = toFixed(d.c0, d.$c0, left, MAX_COLS, wrapEdges);
+      const c1 = toFixed(d.c1, d.$c1, left, MAX_COLS, wrapEdges);
+      if (c0 > c1) {
+        range.left = c1;
+        range.$left = d.$c1;
+        range.right = c0;
+        range.$right = d.$c0;
+      }
+      else {
+        range.left = c0;
+        range.$left = d.$c0;
+        range.right = c1;
+        range.$right = d.$c1;
+      }
+      if (d.trim) {
+        range.trim = d.trim;
+      }
+      if (isNaN(r0) || isNaN(r1) || isNaN(c0) || isNaN(c1)) {
+        // convert to ref error
+        token.type = ERROR;
+        token.value = '#REF!';
+        delete token.groupId;
+      }
+      else {
+        ref.range = range;
+        // @ts-expect-error -- reusing the object, switching it to A1 by swapping the range
+        token.value = stringifyA1RefXlsx(ref);
+      }
+      // if token includes offsets, those offsets are now likely wrong!
+      if (token.loc) {
+        token.loc[0] += offsetSkew;
+        offsetSkew += token.value.length - tokenValue.length;
+        token.loc[1] += offsetSkew;
+      }
+    }
+    else if (offsetSkew && token.loc) {
+      token = cloneToken(token);
+      token.loc[0] += offsetSkew;
+      token.loc[1] += offsetSkew;
+    }
+    outTokens[outTokens.length] = token;
+  }
+
+  return outTokens;
+}
+
+/**
+ * Options for {@link translateFormulaToA1}.
+ */
+export type OptsTranslateFormulaToA1 = {
+  /**
+  * Wrap out-of-bounds ranges around sheet edges rather than turning them to #REF! errors.
+  * @defaultValue true
+  */
+  wrapEdges?: boolean,
+  /**
+  * Should ranges be treated as whole references (`Sheet1!A1:B2`) or as separate tokens
+  * for each part: (`Sheet1`,`!`,`A1`,`:`,`B2`).
+  * @defaultValue true
+  */
+  mergeRefs?: 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.
+  * @defaultValue true
+  */
+  allowTernary?: boolean,
+};
+
+/**
+ * Translates ranges in a formula from relative R1C1 syntax to absolute A1 syntax.
+ *
+ * ```js
+ * translateToA1("=SUM(RC[1],R2C5,Sheet!R3C5)", "D10");
+ * // => "=SUM(E10,$E$2,Sheet!$E$3)");
+ * ```
+ *
+ * If an input range is -1,-1 relative rows/columns and the anchor is A1, the
+ * resulting range will (by default) wrap around to the bottom of the sheet
+ * resulting in the range XFD1048576. This may not be what you want so you can set
+ * `{ wrapEdges }` to false which will instead turn the range into a `#REF!` error.
+ *
+ * ```js
+ * translateToA1("=R[-1]C[-1]", "A1");
+ * // => "=XFD1048576");
+ *
+ * translateToA1("=R[-1]C[-1]", "A1", { wrapEdges: false });
+ * // => "=#REF!");
+ * ```
+ *
+ * @see {@link OptsTranslateFormulaToA1}
+ * @param formula An Excel formula string that should be adjusted.
+ * @param anchorCell A simple string reference to an A1 cell ID (`AF123` or`$C$5`).
+ * @param options Translation options.
+ * @returns A formula string.
+ */
+export function translateFormulaToA1 (
+  formula: string,
+  anchorCell: string,
+  options: OptsTranslateFormulaToA1 = {}
+): string {
+  if (typeof formula === 'string') {
+    return stringifyTokens(translateTokensToA1(tokenizeXlsx(formula, {
+      allowTernary: options.allowTernary ?? true,
+      mergeRefs: options.mergeRefs,
+      r1c1: true
+    }), anchorCell, options));
+  }
+  throw new Error('translateFormulaToA1 expects a formula string');
+}

package/lib/translateToR1C1.spec.ts

@@ -0,0 +1,227 @@
+import { describe, test, expect } from 'vitest';
+import { translateFormulaToR1C1, translateTokensToR1C1 } from './translateToR1C1.ts';
+import { tokenize } from './tokenize.ts';
+import { addTokenMeta } from './addTokenMeta.ts';
+import { FUNCTION, FX_PREFIX, OPERATOR, REF_RANGE, REF_BEAM, REF_STRUCT } from './constants.ts';
+
+function isA2R (expr: string, anchor: string, result: string) {
+  expect(translateFormulaToR1C1(expr, anchor)).toBe(result);
+}
+
+describe('translate absolute cells from A1 to RC', () => {
+  test('absolute cells with B2 anchor', () => {
+    isA2R('=$A$1', 'B2', '=R1C1');
+    isA2R('=$A$2', 'B2', '=R2C1');
+    isA2R('=$A$3', 'B2', '=R3C1');
+    isA2R('=$B$1', 'B2', '=R1C2');
+    isA2R('=$B$2', 'B2', '=R2C2');
+    isA2R('=$B$3', 'B2', '=R3C2');
+    isA2R('=$C$1', 'B2', '=R1C3');
+    isA2R('=$C$2', 'B2', '=R2C3');
+    isA2R('=$C$3', 'B2', '=R3C3');
+  });
+
+  test('absolute cells with Z19 anchor', () => {
+    // absolute cells, anchor has no real effect
+    isA2R('=$A$1', 'Z19', '=R1C1');
+    isA2R('=$A$2', 'Z19', '=R2C1');
+    isA2R('=$A$3', 'Z19', '=R3C1');
+    isA2R('=$B$1', 'Z19', '=R1C2');
+    isA2R('=$B$2', 'Z19', '=R2C2');
+    isA2R('=$B$3', 'Z19', '=R3C2');
+    isA2R('=$C$1', 'Z19', '=R1C3');
+    isA2R('=$C$2', 'Z19', '=R2C3');
+    isA2R('=$C$3', 'Z19', '=R3C3');
+  });
+});
+
+describe('translate relative cells from A1 to RC', () => {
+  test('relative cells with B2 anchor', () => {
+    isA2R('=A1', 'B2', '=R[-1]C[-1]');
+    isA2R('=A2', 'B2', '=RC[-1]');
+    isA2R('=A3', 'B2', '=R[1]C[-1]');
+    isA2R('=B1', 'B2', '=R[-1]C');
+    isA2R('=B2', 'B2', '=RC');
+    isA2R('=B3', 'B2', '=R[1]C');
+    isA2R('=C1', 'B2', '=R[-1]C[1]');
+    isA2R('=C2', 'B2', '=RC[1]');
+    isA2R('=C3', 'B2', '=R[1]C[1]');
+  });
+
+  test('relative cells with I12 anchor', () => {
+    // relative cells, but with [0] notation
+    isA2R('=H11', 'I12', '=R[-1]C[-1]');
+    isA2R('=H12', 'I12', '=RC[-1]');
+    isA2R('=H13', 'I12', '=R[1]C[-1]');
+    isA2R('=I11', 'I12', '=R[-1]C');
+    isA2R('=I12', 'I12', '=RC');
+    isA2R('=I13', 'I12', '=R[1]C');
+    isA2R('=J11', 'I12', '=R[-1]C[1]');
+    isA2R('=J12', 'I12', '=RC[1]');
+    isA2R('=J13', 'I12', '=R[1]C[1]');
+  });
+});
+
+describe('translate rows from A1 to RC', () => {
+  test('relative row references', () => {
+    isA2R('=2:2', 'B1', '=R[1]');
+    isA2R('=2:2', 'B2', '=R');
+    isA2R('=2:2', 'B3', '=R[-1]');
+    isA2R('=13:13', 'B13', '=R');
+  });
+
+  test('mixed row references', () => {
+    isA2R('=$2:$2', 'B2', '=R2');
+    isA2R('=2:$2', 'B2', '=R:R2');
+    isA2R('=11:9', 'Z10', '=R[-1]:R[1]');
+  });
+});
+
+describe('translate cols from A1 to RC', () => {
+  test('relative column references', () => {
+    isA2R('=B:B', 'A2', '=C[1]');
+    isA2R('=B:B', 'B2', '=C');
+    isA2R('=B:B', 'C2', '=C[-1]');
+    isA2R('=Z:Z', 'Z2', '=C');
+  });
+
+  test('mixed column references', () => {
+    isA2R('=$B:$B', 'B2', '=C2');
+    isA2R('=B:$B', 'B2', '=C:C2');
+    isA2R('=N:L', 'M10', '=C[-1]:C[1]');
+  });
+});
+
+describe('translate partials from A1 to RC', () => {
+  test('partial range references', () => {
+    isA2R('=A1:A', 'C6', '=R[-5]C[-2]:C[-2]');
+    isA2R('=A1:1', 'D6', '=R[-5]C[-3]:R[-5]');
+    isA2R('=$A1:$A', 'C7', '=R[-6]C1:C1');
+    isA2R('=$A:$A1', 'D7', '=R[-6]C1:C1');
+    isA2R('=$A1:1', 'C7', '=R[-6]C1:R[-6]');
+    isA2R('=1:$A1', 'C7', '=R[-6]C1:R[-6]');
+    isA2R('=A$1:A', 'C6', '=R1C[-2]:C[-2]');
+    isA2R('=A:A$1', 'C6', '=R1C[-2]:C[-2]');
+    isA2R('=A$1:$1', 'D6', '=R1C[-3]:R1');
+    isA2R('=$1:A$1', 'D6', '=R1C[-3]:R1');
+    isA2R('=$A$1:$A', 'D6', '=R1C1:C1');
+    isA2R('=$A:$A$1', 'D6', '=R1C1:C1');
+    isA2R('=$A$1:$1', 'D6', '=R1C1:R1');
+    isA2R('=$1:$A$1', 'D6', '=R1C1:R1');
+  });
+});
+
+describe('translate boundary coords from A1 to RC', () => {
+  test('boundary coordinate references', () => {
+    isA2R('=XFD:XFD', 'A1', '=C[16383]');
+    isA2R('=A1', 'B1', '=RC[-1]');
+    isA2R('=B1', 'C1', '=RC[-1]');
+    isA2R('=1048576:1048576', 'A1', '=R[1048575]');
+    isA2R('=$1:$1048576', 'A1', '=R1:R1048576');
+    isA2R('=$A:$XFD', 'A1', '=C1:C16384');
+    isA2R('=$A$1:$XFD$1048576', 'A1', '=R1C1:R1048576C16384');
+    isA2R('=A1', 'A2', '=R[-1]C');
+    isA2R('=A2', 'A3', '=R[-1]C');
+  });
+});
+
+describe('translate mixed rel/abs coords from A1 to RC', () => {
+  test('mixed relative/absolute references', () => {
+    isA2R('=B$1', 'B2', '=R1C');
+    isA2R('=$D8', 'B4', '=R[4]C4');
+    isA2R('=8:$10', 'B4', '=R[4]:R10');
+    isA2R('=$J:L', 'B4', '=C10:C[10]');
+    isA2R('=$A$1:$B$2', 'D4', '=R1C1:R2C2');
+    isA2R('=C3:F6', 'D4', '=R[-1]C[-1]:R[2]C[2]');
+  });
+});
+
+describe('translate involved cases from A1 to RC', () => {
+  test('complex function expressions', () => {
+    isA2R('=SUM(IF(E10,$E$2,$E$3),Sheet1!$2:$2*Sheet2!B:B)', 'D10',
+      '=SUM(IF(RC[1],R2C5,R3C5),Sheet1!R2*Sheet2!C[-2])');
+  });
+
+  test('expressions with structured and named references', () => {
+    // make sure we don't get confused by structured, or named refs
+    isA2R('=A1+Table1[#Data]', 'D10', '=R[-9]C[-3]+Table1[#Data]');
+    isA2R('=A1+foobar', 'D10', '=R[-9]C[-3]+foobar');
+  });
+
+  test('XLSX internal syntax', () => {
+    // This [123]Sheet!A1 variant of the syntax is used internally in xlsx files
+    isA2R('=[2]Sheet1!A1', 'D10', '=[2]Sheet1!R[-9]C[-3]');
+  });
+});
+
+describe('translate works with merged ranges', () => {
+  test('preserves token metadata and locations', () => {
+    // This tests that:
+    // - Translate works with ranges that have context attached
+    // - If input is a tokenlist, output is also a tokenlist
+    // - If tokens have ranges, those ranges are adjusted to new token lengths
+    // - Properties added by addTokenMeta are preserved
+    const expr = '=SUM(IF(E10,$E$2,$E$3),Sheet1!$2:$2*Sheet2!B:B)';
+    const tokens = addTokenMeta(tokenize(expr, { withLocation: true }));
+    const expected = [
+      { type: FX_PREFIX, value: '=', loc: [ 0, 1 ], index: 0, depth: 0 },
+      { type: FUNCTION, value: 'SUM', loc: [ 1, 4 ], index: 1, depth: 0 },
+      { type: OPERATOR, value: '(', loc: [ 4, 5 ], index: 2, depth: 1, groupId: 'fxg7' },
+      { type: FUNCTION, value: 'IF', loc: [ 5, 7 ], index: 3, depth: 1 },
+      { type: OPERATOR, value: '(', loc: [ 7, 8 ], index: 4, depth: 2, groupId: 'fxg4' },
+      { type: REF_RANGE, value: 'RC[1]', loc: [ 8, 13 ], index: 5, depth: 2, groupId: 'fxg1' },
+      { type: OPERATOR, value: ',', loc: [ 13, 14 ], index: 6, depth: 2 },
+      { type: REF_RANGE, value: 'R2C5', loc: [ 14, 18 ], index: 7, depth: 2, groupId: 'fxg2' },
+      { type: OPERATOR, value: ',', loc: [ 18, 19 ], index: 8, depth: 2 },
+      { type: REF_RANGE, value: 'R3C5', loc: [ 19, 23 ], index: 9, depth: 2, groupId: 'fxg3' },
+      { type: OPERATOR, value: ')', loc: [ 23, 24 ], index: 10, depth: 2, groupId: 'fxg4' },
+      { type: OPERATOR, value: ',', loc: [ 24, 25 ], index: 11, depth: 1 },
+      { type: REF_BEAM, value: 'Sheet1!R2', loc: [ 25, 34 ], index: 12, depth: 1, groupId: 'fxg5' },
+      { type: OPERATOR, value: '*', loc: [ 34, 35 ], index: 13, depth: 1 },
+      { type: REF_BEAM, value: 'Sheet2!C[-2]', loc: [ 35, 47 ], index: 14, depth: 1, groupId: 'fxg6' },
+      { type: OPERATOR, value: ')', loc: [ 47, 48 ], index: 15, depth: 1, groupId: 'fxg7' }
+    ];
+    expect(translateTokensToR1C1(tokens, 'D10')).toEqual(expected);
+  });
+});
+
+describe('translate works with xlsx mode', () => {
+  function testExpr (expr: string, anchor: string, expected: any[]) {
+    const opts = { mergeRefs: true, xlsx: true, r1c1: false };
+    const tokens = tokenize(expr, opts);
+    expect(translateTokensToR1C1(tokens, anchor)).toEqual(expected);
+  }
+
+  test('XLSX workbook references', () => {
+    testExpr("'[My Fancy Workbook.xlsx]'!B$1", 'B2', [
+      { type: REF_RANGE, value: "'[My Fancy Workbook.xlsx]'!R1C" }
+    ]);
+
+    testExpr('[Workbook.xlsx]!B$1', 'B2', [
+      { type: REF_RANGE, value: '[Workbook.xlsx]!R1C' }
+    ]);
+
+    testExpr('[Workbook.xlsx]Sheet1!B$1', 'B2', [
+      { type: REF_RANGE, value: '[Workbook.xlsx]Sheet1!R1C' }
+    ]);
+
+    testExpr('[Workbook.xlsx]!table[#data]', 'B2', [
+      { type: REF_STRUCT, value: '[Workbook.xlsx]!table[#data]' }
+    ]);
+  });
+});
+
+describe('translate works with trimmed ranges', () => {
+  function testExpr (expr: string, anchor: string, expected: any[]) {
+    const opts = { mergeRefs: true, xlsx: true, r1c1: false };
+    expect(translateTokensToR1C1(tokenize(expr, opts), anchor)).toEqual(expected);
+  }
+
+  test('trimmed range translation', () => {
+    testExpr('Sheet!A1.:.B2*Sheet2!AZ.:.ZZ', 'B2', [
+      { type: 'range', value: 'Sheet!R[-1]C[-1].:.RC' },
+      { type: 'operator', value: '*' },
+      { type: 'range_beam', value: 'Sheet2!C[50].:.C[700]' }
+    ]);
+  });
+});

package/lib/translateToR1C1.ts

@@ -0,0 +1,145 @@
+import { stringifyR1C1RefXlsx } from './stringifyR1C1Ref.ts';
+import { tokenizeXlsx } from './tokenize.ts';
+import { parseA1Range } from './parseA1Range.ts';
+import type { RangeR1C1, ReferenceA1Xlsx, Token } from './types.ts';
+import { stringifyTokens } from './stringifyTokens.ts';
+import { cloneToken } from './cloneToken.ts';
+import { REF_BEAM, REF_RANGE, REF_TERNARY } from './constants.ts';
+import { splitContext } from './parseRef.ts';
+
+const calc = (abs: boolean, vX: number, aX: number): number => {
+  if (vX == null) {
+    return null;
+  }
+  return abs ? vX : vX - aX;
+};
+
+// We already know here that we're holding a token value from
+// one of: REF_RANGE | REF_BEAM | REF_TERNARY
+// So we can quickly scan for ! shortcut a bunch of parsing:
+const unquote = d => d.slice(1, -1).replace(/''/g, "'");
+function quickParseA1 (ref: string): ReferenceA1Xlsx {
+  const split = ref.lastIndexOf('!');
+  const data: Partial<ReferenceA1Xlsx> = {};
+  if (split > -1) {
+    if (ref.startsWith('\'')) {
+      splitContext(unquote(ref.slice(0, split)), data, true);
+    }
+    else {
+      splitContext(ref.slice(0, split), data, true);
+    }
+    data.range = parseA1Range(ref.slice(split + 1));
+  }
+  else {
+    data.range = parseA1Range(ref);
+  }
+  return data as ReferenceA1Xlsx;
+}
+
+/**
+ * Options for {@link translateFormulaToR1C1}.
+ */
+export type OptsTranslateToR1C1 = {
+  /**
+   * 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 true
+   */
+  allowTernary?: boolean,
+};
+
+/**
+ * Translates ranges in a list of tokens from absolute A1 syntax to relative R1C1 syntax.
+ *
+ * ```js
+ * translateFormulaToR1C1("=SUM(E10,$E$2,Sheet!$E$3)", "D10");
+ * // => "=SUM(RC[1],R2C5,Sheet!R3C5)");
+ * ```
+ *
+ * @param tokens A token list that should be adjusted.
+ * @param anchorCell A simple string reference to an A1 cell ID (`AF123` or`$C$5`).
+ * @returns A token list.
+ */
+export function translateTokensToR1C1 (
+  tokens: Token[],
+  anchorCell: string
+): Token[] {
+  const anchorRange = parseA1Range(anchorCell);
+  if (!anchorRange) {
+    throw new Error('translateTokensToR1C1 got an invalid anchorCell: ' + anchorCell);
+  }
+  const { top, left } = anchorRange;
+
+  let offsetSkew = 0;
+  const outTokens = [];
+  for (let token of tokens) {
+    const tokenType = token?.type;
+    if (tokenType === REF_RANGE || tokenType === REF_BEAM || tokenType === REF_TERNARY) {
+      token = cloneToken(token);
+      const tokenValue = token.value;
+      // We can get away with using the xlsx ref-parser here because it is more permissive
+      // and we will end up with the same prefix after serialization anyway:
+      const ref = quickParseA1(tokenValue);
+      const d = ref.range;
+      const range: RangeR1C1 = {};
+      range.r0 = calc(d.$top, d.top, top);
+      range.r1 = calc(d.$bottom, d.bottom, top);
+      range.c0 = calc(d.$left, d.left, left);
+      range.c1 = calc(d.$right, d.right, left);
+      range.$r0 = d.$top;
+      range.$r1 = d.$bottom;
+      range.$c0 = d.$left;
+      range.$c1 = d.$right;
+      if (d.trim) {
+        range.trim = d.trim;
+      }
+      // @ts-expect-error -- reusing the object, switching it to R1C1 by swapping the range
+      ref.range = range;
+      token.value = stringifyR1C1RefXlsx(ref);
+      // if token includes offsets, those offsets are now likely wrong!
+      if (token.loc) {
+        token.loc[0] += offsetSkew;
+        offsetSkew += token.value.length - tokenValue.length;
+        token.loc[1] += offsetSkew;
+      }
+    }
+    else if (offsetSkew && token.loc) {
+      token = cloneToken(token);
+      token.loc[0] += offsetSkew;
+      token.loc[1] += offsetSkew;
+    }
+    outTokens[outTokens.length] = token;
+  }
+
+  return outTokens;
+}
+
+/**
+ * Translates ranges in a formula from absolute A1 syntax to relative R1C1 syntax.
+ *
+ * ```js
+ * translateFormulaToR1C1("=SUM(E10,$E$2,Sheet!$E$3)", "D10");
+ * // => "=SUM(RC[1],R2C5,Sheet!R3C5)");
+ * ```
+ *
+ * @see {@link OptsTranslateToR1C1}
+ * @param formula An Excel formula that should be adjusted.
+ * @param anchorCell A simple string reference to an A1 cell ID (`AF123` or`$C$5`).
+ * @param [options={}] The options
+ * @returns A formula string.
+ */
+export function translateFormulaToR1C1 (
+  formula: string,
+  anchorCell: string,
+  options: OptsTranslateToR1C1 = {}
+): string {
+  if (typeof formula === 'string') {
+    const tokens = tokenizeXlsx(formula, {
+      mergeRefs: false,
+      allowTernary: options.allowTernary ?? true
+    });
+    return stringifyTokens(translateTokensToR1C1(tokens, anchorCell));
+  }
+  throw new Error('translateFormulaToA1 expects a formula string');
+}