@borgar/fx 4.2.0 → 4.3.0

package/lib/rc.js

@@ -8,7 +8,7 @@
 */
 import { MAX_ROWS, MAX_COLS } from './constants.js';
 import { parseRef } from './parseRef.js';
-import { stringifyPrefix } from './stringifyPrefix.js';
+import { stringifyPrefix, stringifyPrefixAlt } from './stringifyPrefix.js';
 
 const clamp = (min, val, max) => Math.min(Math.max(val, min), max);
 
@@ -268,10 +268,11 @@ export function fromR1C1 (ref) {
  * @param {Object} [options={}]  Options
  * @param {boolean} [options.allowNamed=true]  Enable parsing names as well as ranges.
  * @param {boolean} [options.allowTernary=false]  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.
+ * @param {boolean} [options.xlsx=false]  Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md)
  * @return {(Object|null)} An object representing a valid reference or null if it is invalid.
  */
-export function parseR1C1Ref (refString, { allowNamed = true, allowTernary = false } = {}) {
-  const d = parseRef(refString, { allowNamed, allowTernary, r1c1: true });
+export function parseR1C1Ref (refString, { allowNamed = true, allowTernary = false, xlsx = false } = {}) {
+  const d = parseRef(refString, { allowNamed, allowTernary, xlsx, r1c1: true });
   if (d && (d.r0 || d.name)) {
     const range = d.r1
       ? fromR1C1(d.r0 + ':' + d.r1)
@@ -310,10 +311,15 @@ export function parseR1C1Ref (refString, { allowNamed = true, allowTernary = fal
  * ```
  *
  * @param {Object} refObject A reference object
+ * @param {Object} [options={}]  Options
+ * @param {boolean} [options.xlsx=false]  Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md)
  * @return {Object} The reference in R1C1-style string format
  */
-export function stringifyR1C1Ref (refObject) {
-  return stringifyPrefix(refObject) + (
+export function stringifyR1C1Ref (refObject, { xlsx = false } = {}) {
+  const prefix = xlsx
+    ? stringifyPrefixAlt(refObject)
+    : stringifyPrefix(refObject);
+  return prefix + (
     refObject.name ? refObject.name : toR1C1(refObject.range)
   );
 }

package/lib/rc.spec.js

@@ -3,24 +3,32 @@ import { test, Test } from 'tape';
 import { MAX_COLS, MAX_ROWS } from './constants.js';
 import { parseR1C1Ref, stringifyR1C1Ref, toR1C1 } from './rc.js';
 
-Test.prototype.isRCEqual = function isTokens (expr, result, opts) {
-  if (result) {
-    result = {
-      context: [],
-      name: '',
-      range: null,
-      ...result
-    };
-    if (result.range && typeof result.range === 'object') {
+Test.prototype.isRCEqual = function isTokens (expr, expect, opts) {
+  if (expect) {
+    expect = (opts?.xlsx)
+      ? {
+        workbookName: '',
+        sheetName: '',
+        name: '',
+        range: null,
+        ...expect
+      }
+      : {
+        context: [],
+        name: '',
+        range: null,
+        ...expect
+      };
+    if (expect.range && typeof expect.range === 'object') {
       // mix in some defaults so we don't have to write things out in full
-      result.range = {
+      expect.range = {
         r0: null, c0: null, r1: null, c1: null,
         $r0: false, $c0: false, $r1: false, $c1: false,
-        ...result.range
+        ...expect.range
       };
     }
   }
-  this.deepEqual(parseR1C1Ref(expr, opts), result, expr);
+  this.deepEqual(parseR1C1Ref(expr, opts), expect, expr);
 };
 
 Test.prototype.isR1C1Rendered = function isTokens (range, expect, d) {
@@ -151,6 +159,108 @@ test('parse joined R1C1 references', t => {
   t.end();
 });
 
+test('parse R1C1 ranges in XLSX mode', t => {
+  const opts = { xlsx: true };
+  const rcRange = { r0: 0, c0: 0, r1: 0, c1: 0 };
+  t.isRCEqual('[1]!RC', {
+    workbookName: '1',
+    sheetName: '',
+    range: rcRange
+  }, opts);
+
+  t.isRCEqual('[Workbook.xlsx]!RC', {
+    workbookName: 'Workbook.xlsx',
+    sheetName: '',
+    range: rcRange
+  }, opts);
+
+  t.isRCEqual('[1]Sheet1!RC', {
+    workbookName: '1',
+    sheetName: 'Sheet1',
+    range: rcRange
+  }, opts);
+
+  t.isRCEqual('[Workbook.xlsx]Sheet1!RC', {
+    workbookName: 'Workbook.xlsx',
+    sheetName: 'Sheet1',
+    range: rcRange
+  }, opts);
+
+  t.isRCEqual('[4]!name', {
+    workbookName: '4',
+    sheetName: '',
+    name: 'name'
+  }, opts);
+
+  t.isRCEqual('[Workbook.xlsx]!name', {
+    workbookName: 'Workbook.xlsx',
+    sheetName: '',
+    name: 'name'
+  }, opts);
+
+  t.isRCEqual('[16]Sheet1!name', {
+    workbookName: '16',
+    sheetName: 'Sheet1',
+    name: 'name'
+  }, opts);
+
+  t.isRCEqual('[Workbook.xlsx]Sheet1!name', {
+    workbookName: 'Workbook.xlsx',
+    sheetName: 'Sheet1',
+    name: 'name'
+  }, opts);
+
+  t.isRCEqual("='[1]'!RC", {
+    workbookName: '1',
+    sheetName: '',
+    range: rcRange
+  }, opts);
+
+  t.isRCEqual("='[Workbook.xlsx]'!RC", {
+    workbookName: 'Workbook.xlsx',
+    sheetName: '',
+    range: rcRange
+  }, opts);
+
+  t.isRCEqual("'[1]Sheet1'!RC", {
+    workbookName: '1',
+    sheetName: 'Sheet1',
+    range: rcRange
+  }, opts);
+
+  t.isRCEqual("'[Workbook.xlsx]Sheet1'!RC", {
+    workbookName: 'Workbook.xlsx',
+    sheetName: 'Sheet1',
+    range: rcRange
+  }, opts);
+
+  t.isRCEqual("'[4]'!name", {
+    workbookName: '4',
+    sheetName: '',
+    name: 'name'
+  }, opts);
+
+  t.isRCEqual("'[Workbook.xlsx]'!name", {
+    workbookName: 'Workbook.xlsx',
+    sheetName: '',
+    name: 'name'
+  }, opts);
+
+  t.isRCEqual("'[16]Sheet1'!name", {
+    workbookName: '16',
+    sheetName: 'Sheet1',
+    name: 'name'
+  }, opts);
+
+  t.isRCEqual("'[Workbook.xlsx]Sheet1'!name", {
+    workbookName: 'Workbook.xlsx',
+    sheetName: 'Sheet1',
+    name: 'name'
+  }, opts);
+
+  t.end();
+});
+
 test('R1C1 serialization', t => {
   // ray
   t.isR1C1Rendered({ r0: 0, c0: 0, r1: 0, c1: MAX_COLS }, 'R');
@@ -229,3 +339,26 @@ test('stringifyR1C1Ref', t => {
   testRef({ context: [ 'My File.xlsx' ], name: 'foo' }, "'My File.xlsx'!foo");
   t.end();
 });
+
+test('stringifyR1C1Ref in XLSX mode', t => {
+  const rangeA1 = { r0: 2, c0: 4, r1: 2, c1: 4 };
+  const testRef = (ref, expect) => t.is(stringifyR1C1Ref(ref, { xlsx: true }), expect, expect);
+  testRef({ range: rangeA1 }, 'R[2]C[4]');
+  testRef({ sheetName: 'Sheet1', range: rangeA1 }, 'Sheet1!R[2]C[4]');
+  testRef({ sheetName: 'Sheet 1', range: rangeA1 }, "'Sheet 1'!R[2]C[4]");
+  testRef({ workbookName: 'MyFile.xlsx', sheetName: 'Sheet1', range: rangeA1 }, '[MyFile.xlsx]Sheet1!R[2]C[4]');
+  testRef({ workbookName: 'My File.xlsx', sheetName: 'Sheet1', range: rangeA1 }, "'[My File.xlsx]Sheet1'!R[2]C[4]");
+  testRef({ workbookName: 'MyFile.xlsx', range: rangeA1 }, '[MyFile.xlsx]!R[2]C[4]');
+  testRef({ workbookName: 'My File.xlsx', range: rangeA1 }, "'[My File.xlsx]'!R[2]C[4]");
+  testRef({ name: 'foo' }, 'foo');
+  testRef({ sheetName: 'Sheet1', name: 'foo' }, 'Sheet1!foo');
+  testRef({ sheetName: 'Sheet 1', name: 'foo' }, "'Sheet 1'!foo");
+  testRef({ workbookName: 'MyFile.xlsx', sheetName: 'Sheet1', name: 'foo' }, '[MyFile.xlsx]Sheet1!foo');
+  testRef({ workbookName: 'My File.xlsx', sheetName: 'Sheet1', name: 'foo' }, "'[My File.xlsx]Sheet1'!foo");
+  testRef({ workbookName: 'MyFile.xlsx', name: 'foo' }, '[MyFile.xlsx]!foo');
+  testRef({ workbookName: 'My File.xlsx', name: 'foo' }, "'[My File.xlsx]'!foo");
+  // ignore .context
+  testRef({ context: [ 'MyFile.xlsx', 'Sheet1' ], range: rangeA1 }, 'R[2]C[4]');
+  testRef({ context: [ 'MyFile.xlsx', 'Sheet1' ], name: 'foo' }, 'foo');
+  t.end();
+});

package/lib/sr.js

@@ -1,5 +1,5 @@
 import { parseRef } from './parseRef.js';
-import { stringifyPrefix } from './stringifyPrefix.js';
+import { stringifyPrefix, stringifyPrefixAlt } from './stringifyPrefix.js';
 
 const re_SRcolumnB = /^\[('['#@[\]]|[^'#@[\]])+\]/i;
 const re_SRcolumnN = /^([^#@[\]:]+)/i;
@@ -186,19 +186,28 @@ export function parseSRange (raw) {
  * @tutorial References.md
  * @param {string} ref  A structured reference string
  * @param {Object} [options={}]  Options
+ * @param {boolean} [options.xlsx=false]  Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md)
  * @return {(Object|null)} An object representing a valid reference or null if it is invalid.
  */
-export function parseStructRef (ref, opts = {}) {
+export function parseStructRef (ref, opts = { xlsx: false }) {
   const r = parseRef(ref, opts);
   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
-      };
+      return opts.xlsx
+        ? {
+          workbookName: r.workbookName,
+          sheetName: r.sheetName,
+          table: r.name,
+          columns: structData.columns,
+          sections: structData.sections
+        }
+        : {
+          context: r.context,
+          table: r.name,
+          columns: structData.columns,
+          sections: structData.sections
+        };
     }
   }
   return null;
@@ -230,10 +239,15 @@ function toSentenceCase (str) {
  * ```
  *
  * @param {Object} refObject A structured reference object
+ * @param {Object} [options={}]  Options
+ * @param {boolean} [options.xlsx=false]  Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md)
  * @return {Object} The structured reference in string format
  */
-export function stringifyStructRef (ref) {
-  let s = stringifyPrefix(ref);
+export function stringifyStructRef (ref, { xlsx = false } = {}) {
+  let s = xlsx
+    ? stringifyPrefixAlt(ref)
+    : stringifyPrefix(ref);
+
   if (ref.table) {
     s += ref.table;
   }

package/lib/sr.spec.js

@@ -4,13 +4,22 @@ import { parseStructRef, stringifyStructRef } from './sr.js';
 
 Test.prototype.isSREqual = function isSREqual (expr, expect, opts) {
   if (expect) {
-    expect = {
-      context: [],
-      table: '',
-      columns: [],
-      sections: [],
-      ...expect
-    };
+    expect = opts?.xlsx
+      ? {
+        workbookName: '',
+        sheetName: '',
+        table: '',
+        columns: [],
+        sections: [],
+        ...expect
+      }
+      : {
+        context: [],
+        table: '',
+        columns: [],
+        sections: [],
+        ...expect
+      };
   }
   this.deepEqual(parseStructRef(expr, opts), expect, expr);
 };
@@ -67,6 +76,18 @@ test('parse structured references', t => {
     sections: [ 'data', 'totals' ]
   });
 
+  t.isSREqual("'Sheet'!Table[Column]", {
+    columns: [ 'Column' ],
+    table: 'Table',
+    context: [ 'Sheet' ]
+  });
+
+  t.isSREqual("Sheet1!Table1[foo '[bar']]", {
+    columns: [ 'foo [bar]' ],
+    table: 'Table1',
+    context: [ 'Sheet1' ]
+  });
+
   t.end();
 });
 
@@ -177,3 +198,68 @@ test('serialize structured references', t => {
   t.end();
 });
 
+test('structured references parse and serialize in xlsx mode', t => {
+  t.isSREqual('[Workbook.xlsx]!Table[#Data]', {
+    workbookName: 'Workbook.xlsx',
+    table: 'Table',
+    sections: [ 'data' ]
+  }, { xlsx: true });
+
+  t.isSREqual('[Workbook.xlsx]Sheet1!Table[#Data]', {
+    workbookName: 'Workbook.xlsx',
+    sheetName: 'Sheet1',
+    table: 'Table',
+    sections: [ 'data' ]
+  }, { xlsx: true });
+
+  t.isSREqual('Sheet1!Table[#Data]', {
+    sheetName: 'Sheet1',
+    table: 'Table',
+    sections: [ 'data' ]
+  }, { xlsx: true });
+
+  t.is(
+    stringifyStructRef({
+      context: [ 'Lorem', 'Ipsum' ],
+      columns: [ 'foo' ]
+    }, { xlsx: true }),
+    '[foo]',
+    'context prop is ignored in xlsx mode'
+  );
+  t.is(
+    stringifyStructRef({
+      workbookName: 'Lorem',
+      sheetName: 'Ipsum',
+      columns: [ 'foo' ]
+    }, { xlsx: false }),
+    '[foo]',
+    'workbookName+sheetName props are ignored in default mode'
+  );
+  t.is(
+    stringifyStructRef({
+      workbookName: 'Lorem',
+      sheetName: 'Ipsum',
+      columns: [ 'foo' ]
+    }, { xlsx: true }),
+    '[Lorem]Ipsum![foo]',
+    'workbookName+sheetName props are rendered correctly'
+  );
+  t.is(
+    stringifyStructRef({
+      workbookName: 'Lorem',
+      columns: [ 'foo' ]
+    }, { xlsx: true }),
+    '[Lorem]![foo]',
+    'workbookName prop is rendered correctly'
+  );
+  t.is(
+    stringifyStructRef({
+      sheetName: 'Ipsum',
+      columns: [ 'foo' ]
+    }, { xlsx: true }),
+    'Ipsum![foo]',
+    'sheetName prop is rendered correctly'
+  );
+  t.end();
+});
+

package/lib/stringifyPrefix.js

@@ -19,3 +19,21 @@ export function stringifyPrefix (ref) {
   }
   return pre ? pre + '!' : pre;
 }
+
+export function stringifyPrefixAlt (ref) {
+  let pre = '';
+  let quote = 0;
+  const { workbookName, sheetName } = ref;
+  if (workbookName) {
+    pre += '[' + workbookName + ']';
+    quote += reBannedChars.test(workbookName);
+  }
+  if (sheetName) {
+    pre += sheetName;
+    quote += reBannedChars.test(sheetName);
+  }
+  if (quote) {
+    pre = "'" + pre.replace(/'/g, "''") + "'";
+  }
+  return pre ? pre + '!' : pre;
+}

package/lib/translate-toA1.spec.js

@@ -2,10 +2,10 @@ import { test, Test } from 'tape';
 import { translateToA1 } from './translate.js';
 import { tokenize } from './lexer.js';
 import { addTokenMeta } from './addTokenMeta.js';
-import { ERROR, FUNCTION, FX_PREFIX, OPERATOR, REF_RANGE, REF_BEAM } from './constants.js';
+import { ERROR, FUNCTION, FX_PREFIX, OPERATOR, REF_RANGE, REF_BEAM, REF_STRUCT } from './constants.js';
 
-Test.prototype.isR2A = function isTokens (expr, anchor, result) {
-  this.is(translateToA1(expr, anchor), result, expr);
+Test.prototype.isR2A = function isTokens (expr, anchor, result, opts) {
+  this.is(translateToA1(expr, anchor, opts), result, expr);
 };
 
 test('translate absolute cells from RC to A1', t => {
@@ -175,3 +175,23 @@ test('translate works with merged ranges', t => {
   t.deepEqual(translateToA1(tokens, 'D10'), expected, expr);
   t.end();
 });
+
+test('translate works with xlsx mode references', t => {
+  const testExpr = (expr, anchor, expected) => {
+    const opts = { mergeRefs: true, xlsx: true, r1c1: true };
+    t.deepEqual(translateToA1(tokenize(expr, opts), anchor, opts), expected, expr);
+  };
+  testExpr("'[My Fancy Workbook.xlsx]'!R1C", 'B2', [
+    { type: REF_RANGE, value: "'[My Fancy Workbook.xlsx]'!B$1" }
+  ]);
+  testExpr('[Workbook.xlsx]!R1C', 'B2', [
+    { type: REF_RANGE, value: '[Workbook.xlsx]!B$1' }
+  ]);
+  testExpr('[Workbook.xlsx]Sheet1!R1C', 'B2', [
+    { type: REF_RANGE, value: '[Workbook.xlsx]Sheet1!B$1' }
+  ]);
+  testExpr('[Workbook.xlsx]!table[#data]', 'B2', [
+    { type: REF_STRUCT, value: '[Workbook.xlsx]!table[#data]' }
+  ]);
+  t.end();
+});

package/lib/translate-toRC.spec.js

@@ -2,7 +2,7 @@ import { test, Test } from 'tape';
 import { translateToR1C1 } from './translate.js';
 import { tokenize } from './lexer.js';
 import { addTokenMeta } from './addTokenMeta.js';
-import { FUNCTION, FX_PREFIX, OPERATOR, REF_RANGE, REF_BEAM } from './constants.js';
+import { FUNCTION, FX_PREFIX, OPERATOR, REF_RANGE, REF_BEAM, REF_STRUCT } from './constants.js';
 
 Test.prototype.isA2R = function isTokens (expr, anchor, result) {
   this.is(translateToR1C1(expr, anchor), result, expr);
@@ -115,9 +115,17 @@ test('translate mixed rel/abs coords from A1 to RC', t => {
   t.end();
 });
 
-test('translate involved formula from A1 to RC', t => {
+test('translate involved cases from A1 to RC', t => {
   t.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])');
+
+  // make sure we don't get confused by structured, or named refs
+  t.isA2R('=A1+Table1[#Data]', 'D10', '=R[-9]C[-3]+Table1[#Data]');
+  t.isA2R('=A1+foobar', 'D10', '=R[-9]C[-3]+foobar');
+
+  // This [123]Sheet!A1 variant of the syntax is used internally in xlsx files
+  t.isA2R('=[2]Sheet1!A1', 'D10', '=[2]Sheet1!R[-9]C[-3]');
+
   t.end();
 });
 
@@ -150,3 +158,24 @@ test('translate works with merged ranges', t => {
   t.deepEqual(translateToR1C1(tokens, 'D10'), expected, expr);
   t.end();
 });
+
+test('translate works with xlsx mode', t => {
+  const testExpr = (expr, anchor, expected) => {
+    const opts = { mergeRefs: true, xlsx: true, r1c1: false };
+    const tokens = tokenize(expr, opts);
+    t.deepEqual(translateToR1C1(tokens, anchor, opts), expected, expr);
+  };
+  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]' }
+  ]);
+  t.end();
+});

package/lib/translate.js

@@ -23,8 +23,7 @@ const settings = {
  * relative R1C1 syntax.
  *
  * Returns the same formula with the ranges translated. If an array of tokens
- * was supplied, then the same array is returned (be careful that `mergeRefs`
- * *must* be `false`).
+ * was supplied, then the same array is returned.
  *
  * ```js
  * translateToR1C1("=SUM(E10,$E$2,Sheet!$E$3)", "D10");
@@ -33,21 +32,24 @@ const settings = {
  *
  * @param {(string | Array<Object>)} formula A string (an Excel formula) or a token list that should be adjusted.
  * @param {string} anchorCell A simple string reference to an A1 cell ID (`AF123` or`$C$5`).
+ * @param {Object} [options={}] The options
+ * @param {boolean} [options.xlsx=false]  Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md)
  * @return {(string | Array<Object>)} A formula string or token list (depending on which was input)
  */
-export function translateToR1C1 (fx, anchorCell) {
+export function translateToR1C1 (fx, anchorCell, { xlsx = false } = {}) {
   const { top, left } = fromA1(anchorCell);
   const isString = typeof fx === 'string';
 
   const tokens = isString
-    ? tokenize(fx, settings)
+    ? tokenize(fx, { ...settings, xlsx })
     : fx;
 
   let offsetSkew = 0;
+  const refOpts = { xlsx, allowTernary: true };
   tokens.forEach(token => {
     if (isRange(token)) {
       const tokenValue = token.value;
-      const ref = parseA1Ref(tokenValue, { allowTernary: true });
+      const ref = parseA1Ref(tokenValue, refOpts);
       const d = ref.range;
       const range = {};
       range.r0 = calc(d.$top, d.top, top);
@@ -59,7 +61,7 @@ export function translateToR1C1 (fx, anchorCell) {
       range.$c0 = d.$left;
       range.$c1 = d.$right;
       ref.range = range;
-      token.value = stringifyR1C1Ref(ref);
+      token.value = stringifyR1C1Ref(ref, refOpts);
       // if token includes offsets, those offsets are now likely wrong!
       if (token.loc) {
         token.loc[0] += offsetSkew;
@@ -105,7 +107,8 @@ function toFixed (val, abs, base, max, wrapEdges = true) {
 
 const defaultOptions = {
   wrapEdges: true,
-  mergeRefs: true
+  mergeRefs: true,
+  xlsx: false
 };
 
 /**
@@ -113,8 +116,7 @@ const defaultOptions = {
  * absolute A1 syntax.
  *
  * Returns the same formula with the ranges translated. If an array of tokens
- * was supplied, then the same array is returned (be careful that `mergeRefs`
- * *must* be `false`).
+ * was supplied, then the same array is returned.
  *
  * ```js
  * translateToA1("=SUM(RC[1],R2C5,Sheet!R3C5)", "D10");
@@ -145,6 +147,7 @@ const defaultOptions = {
  * @param {Object} [options={}] The options
  * @param {boolean} [options.wrapEdges=true]  Wrap out-of-bounds ranges around sheet edges rather than turning them to #REF! errors
  * @param {boolean} [options.mergeRefs=true]   Should ranges be treated as whole references (`Sheet1!A1:B2`) or as separate tokens for each part: (`Sheet1`,`!`,`A1`,`:`,`B2`).
+ * @param {boolean} [options.xlsx=false]  Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md)
  * @return {(string | Array<Object>)} A formula string or token list (depending on which was input)
  */
 export function translateToA1 (formula, anchorCell, options = defaultOptions) {
@@ -156,16 +159,18 @@ export function translateToA1 (formula, anchorCell, options = defaultOptions) {
     ? tokenize(formula, {
       withLocation: false,
       mergeRefs: opts.mergeRefs,
+      xlsx: opts.xlsx,
       allowTernary: true,
       r1c1: true
     })
     : formula;
 
   let offsetSkew = 0;
+  const refOpts = { xlsx: opts.xlsx, allowTernary: true };
   tokens.forEach(token => {
     if (isRange(token)) {
       const tokenValue = token.value;
-      const ref = parseR1C1Ref(tokenValue, { allowTernary: true });
+      const ref = parseR1C1Ref(tokenValue, refOpts);
       const d = ref.range;
       const range = {};
       const r0 = toFixed(d.r0, d.$r0, anchor.top, MAX_ROWS, opts.wrapEdges);
@@ -204,7 +209,7 @@ export function translateToA1 (formula, anchorCell, options = defaultOptions) {
       }
       else {
         ref.range = range;
-        token.value = stringifyA1Ref(ref);
+        token.value = stringifyA1Ref(ref, refOpts);
       }
       // if token includes offsets, those offsets are now likely wrong!
       if (token.loc) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@borgar/fx",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "description": "Utilities for working with Excel formulas",
   "main": "dist/fx.js",
   "module": "lib/index.js",
@@ -15,7 +15,7 @@
     "version": "npm run build",
     "lint": "eslint lib/*.js",
     "test": "tape lib/*.spec.js | tap-min",
-    "build:docs": "echo '# _fx_ API\n'>docs/API.md; jsdoc -c .jsdoc/config.json -d console lib>>docs/API.md",
+    "build:docs": "echo '# _Fx_ API\n'>docs/API.md; jsdoc -c .jsdoc/config.json -d console lib>>docs/API.md",
     "build": "NODE_ENV=production rollup -c"
   },
   "repository": {