@borgar/fx 4.2.0 → 4.3.0

package/lib/a1.spec.js

@@ -15,12 +15,21 @@ import { MAX_COLS, MAX_ROWS } from './constants.js';
 
 Test.prototype.isA1Equal = function isA1Equal (expr, expect, opts) {
   if (expect) {
-    expect = {
-      context: [],
-      name: '',
-      range: null,
-      ...expect
-    };
+    expect = opts?.xlsx
+      ? {
+        workbookName: '',
+        sheetName: '',
+        name: '',
+        range: null,
+        ...expect
+      }
+      : {
+        context: [],
+        name: '',
+        range: null,
+        ...expect
+      };
+    Object.assign(expect, expect);
     if (expect.range && typeof expect.range === 'object') {
       // mix in some defaults so we don't have to write things out in full
       expect.range = {
@@ -156,6 +165,108 @@ test('parse A1 references', t => {
   t.end();
 });
 
+test('parse A1 ranges in XLSX mode', t => {
+  const opts = { xlsx: true };
+
+  t.isA1Equal('[1]!A1', {
+    workbookName: '1',
+    sheetName: '',
+    range: { top: 0, left: 0, bottom: 0, right: 0 }
+  }, opts);
+
+  t.isA1Equal('[Workbook.xlsx]!A1', {
+    workbookName: 'Workbook.xlsx',
+    sheetName: '',
+    range: { top: 0, left: 0, bottom: 0, right: 0 }
+  }, opts);
+
+  t.isA1Equal('[1]Sheet1!A1', {
+    workbookName: '1',
+    sheetName: 'Sheet1',
+    range: { top: 0, left: 0, bottom: 0, right: 0 }
+  }, opts);
+
+  t.isA1Equal('[Workbook.xlsx]Sheet1!A1', {
+    workbookName: 'Workbook.xlsx',
+    sheetName: 'Sheet1',
+    range: { top: 0, left: 0, bottom: 0, right: 0 }
+  }, opts);
+
+  t.isA1Equal('[4]!name', {
+    workbookName: '4',
+    sheetName: '',
+    name: 'name'
+  }, opts);
+
+  t.isA1Equal('[Workbook.xlsx]!name', {
+    workbookName: 'Workbook.xlsx',
+    sheetName: '',
+    name: 'name'
+  }, opts);
+
+  t.isA1Equal('[16]Sheet1!name', {
+    workbookName: '16',
+    sheetName: 'Sheet1',
+    name: 'name'
+  }, opts);
+
+  t.isA1Equal('[Workbook.xlsx]Sheet1!name', {
+    workbookName: 'Workbook.xlsx',
+    sheetName: 'Sheet1',
+    name: 'name'
+  }, opts);
+
+  t.isA1Equal("='[1]'!A1", {
+    workbookName: '1',
+    sheetName: '',
+    range: { top: 0, left: 0, bottom: 0, right: 0 }
+  }, opts);
+
+  t.isA1Equal("='[Workbook.xlsx]'!A1", {
+    workbookName: 'Workbook.xlsx',
+    sheetName: '',
+    range: { top: 0, left: 0, bottom: 0, right: 0 }
+  }, opts);
+
+  t.isA1Equal("'[1]Sheet1'!A1", {
+    workbookName: '1',
+    sheetName: 'Sheet1',
+    range: { top: 0, left: 0, bottom: 0, right: 0 }
+  }, opts);
+
+  t.isA1Equal("'[Workbook.xlsx]Sheet1'!A1", {
+    workbookName: 'Workbook.xlsx',
+    sheetName: 'Sheet1',
+    range: { top: 0, left: 0, bottom: 0, right: 0 }
+  }, opts);
+
+  t.isA1Equal("'[4]'!name", {
+    workbookName: '4',
+    sheetName: '',
+    name: 'name'
+  }, opts);
+
+  t.isA1Equal("'[Workbook.xlsx]'!name", {
+    workbookName: 'Workbook.xlsx',
+    sheetName: '',
+    name: 'name'
+  }, opts);
+
+  t.isA1Equal("'[16]Sheet1'!name", {
+    workbookName: '16',
+    sheetName: 'Sheet1',
+    name: 'name'
+  }, opts);
+
+  t.isA1Equal("'[Workbook.xlsx]Sheet1'!name", {
+    workbookName: 'Workbook.xlsx',
+    sheetName: 'Sheet1',
+    name: 'name'
+  }, opts);
+
+  t.end();
+});
+
 test('A1 partial ranges', t => {
   const opt = { allowTernary: true };
   // partials are not allowed by defult
@@ -252,6 +363,32 @@ test('stringifyA1Ref', t => {
   testRef({ context: [ 'My File.xlsx', 'Sheet1' ], name: 'foo' }, "'[My File.xlsx]Sheet1'!foo");
   testRef({ context: [ 'MyFile.xlsx' ], name: 'foo' }, 'MyFile.xlsx!foo');
   testRef({ context: [ 'My File.xlsx' ], name: 'foo' }, "'My File.xlsx'!foo");
+  // ignore .workbookName/.sheetName
+  testRef({ workbookName: 'MyFile.xlsx', sheetName: 'Sheet1', range: rangeA1 }, 'A1');
+  testRef({ workbookName: 'MyFile.xlsx', sheetName: 'Sheet1', name: 'foo' }, 'foo');
+  t.end();
+});
+
+test('stringifyA1Ref in XLSX mode', t => {
+  const rangeA1 = { top: 0, bottom: 0, left: 0, right: 0 };
+  const testRef = (ref, expect) => t.is(stringifyA1Ref(ref, { xlsx: true }), expect, expect);
+  testRef({ range: rangeA1 }, 'A1');
+  testRef({ sheetName: 'Sheet1', range: rangeA1 }, 'Sheet1!A1');
+  testRef({ sheetName: 'Sheet 1', range: rangeA1 }, "'Sheet 1'!A1");
+  testRef({ workbookName: 'MyFile.xlsx', sheetName: 'Sheet1', range: rangeA1 }, '[MyFile.xlsx]Sheet1!A1');
+  testRef({ workbookName: 'My File.xlsx', sheetName: 'Sheet1', range: rangeA1 }, "'[My File.xlsx]Sheet1'!A1");
+  testRef({ workbookName: 'MyFile.xlsx', range: rangeA1 }, '[MyFile.xlsx]!A1');
+  testRef({ workbookName: 'My File.xlsx', range: rangeA1 }, "'[My File.xlsx]'!A1");
+  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 }, 'A1');
+  testRef({ context: [ 'MyFile.xlsx', 'Sheet1' ], name: 'foo' }, 'foo');
   t.end();
 });
 
@@ -268,4 +405,3 @@ test('A1 utilities', t => {
   t.deepEqual(toRelative(absA1Range), relA1Range, 'toRelative');
   t.end();
 });
-

package/lib/fixRanges.js

@@ -4,14 +4,17 @@ import { parseStructRef, stringifyStructRef } from './sr.js';
 import { tokenize } from './lexer.js';
 import { REF_STRUCT } from './constants.js';
 
-// There is no R1C1 counerpart to this. This is because without an anchor cell
+// There is no R1C1 counterpart to this. This is because without an anchor cell
 // it is impossible to determine if a relative+absolute range (R[1]C[1]:R5C5)
 // needs to be flipped or not. The solution is to convert to A1 first:
 // translateToRC(fixRanges(translateToA1(...)))
 
 /**
- * Normalizes A1 style ranges in a formula or list of tokens so that the top and
- * left coordinates of the range are on the left-hand side of a colon operator:
+ * Normalizes A1 style ranges and structured references in a formula or list of
+ * tokens.
+ * 
+ * It ensures that that the top and left coordinates of an A1 range are on the
+ * left-hand side of a colon operator:
  *
  * `B2:A1` → `A1:B2`  
  * `1:A1` → `A1:1`  
@@ -31,13 +34,16 @@ import { REF_STRUCT } from './constants.js';
  * `B2:B` → `B2:1048576`  
  * `B2:2` → `B2:XFD2`  
  *
+ * Structured ranges are normalized cleaned up to have consistent order and
+ * capitalization of sections as well as removing redundant ones.
+ *
  * Returns the same formula with the ranges updated. If an array of tokens was
  * supplied, then a new array is returned.
  *
  * @param {(string | Array<Object>)} formula A string (an Excel formula) or a token list that should be adjusted.
  * @param {Object} [options={}]  Options
  * @param {boolean} [options.addBounds=false]  Fill in any undefined bounds of range objects. Top to 0, bottom to 1048575, left to 0, and right to 16383.
- * @param {boolean} [options.r1c1=false]  Ranges are expected to be in the R1C1 style format rather than the more popular A1 style.
+ * @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 fixRanges (tokens, options = { addBounds: false }) {
@@ -49,7 +55,7 @@ export function fixRanges (tokens, options = { addBounds: false }) {
   if (!Array.isArray(tokens)) {
     throw new Error('fixRanges expects an array of tokens');
   }
-  const { addBounds, r1c1 } = options;
+  const { addBounds, r1c1, xlsx } = options;
   if (r1c1) {
     throw new Error('fixRanges does not have an R1C1 mode');
   }
@@ -61,18 +67,19 @@ export function fixRanges (tokens, options = { addBounds: false }) {
     }
     let offsetDelta = 0;
     if (token.type === REF_STRUCT) {
-      const newValue = stringifyStructRef(parseStructRef(token.value));
+      const sref = parseStructRef(token.value, { xlsx });
+      const newValue = stringifyStructRef(sref, { xlsx });
       offsetDelta = newValue.length - token.value.length;
       token.value = newValue;
     }
     else if (isRange(token)) {
-      const ref = parseA1Ref(token.value, { allowTernary: true });
+      const ref = parseA1Ref(token.value, { xlsx, allowTernary: true });
       const range = ref.range;
       // fill missing dimensions?
       if (addBounds) {
         addA1RangeBounds(range);
       }
-      const newValue = stringifyA1Ref(ref);
+      const newValue = stringifyA1Ref(ref, { xlsx });
       offsetDelta = newValue.length - token.value.length;
       token.value = newValue;
     }

package/lib/fixRanges.spec.js

@@ -138,3 +138,22 @@ test('fixRanges structured references', t => {
   t.isFixed('[ @foo bar ]', '[@[foo bar]]');
   t.end();
 });
+
+test('fixRanges works with xlsx mode', t => {
+  // should not mess with invalid ranges in normal mode
+  t.isFixed("='[Workbook]'!Table[Column]", "='[Workbook]'!Table[Column]");
+  t.isFixed('=[Workbook]!Table[Column]', '=[Workbook]!Table[Column]');
+  t.isFixed("='[Foo]'!A1", "='[Foo]'!A1");
+  t.isFixed('=[Foo]!A1', '=[Foo]!A1');
+  // should fix things in xlsx mode
+  const opts = { xlsx: true };
+  t.isFixed("='[Workbook]'!Table[Column]", '=[Workbook]!Table[Column]', opts);
+  t.isFixed('=[Workbook]!Table[Column]', '=[Workbook]!Table[Column]', opts);
+  t.isFixed('=[Lorem Ipsum]!Table[Column]', "='[Lorem Ipsum]'!Table[Column]", opts);
+  t.isFixed("='[Foo]'!A1", '=[Foo]!A1', opts);
+  t.isFixed('=[Foo]Bar!A1', '=[Foo]Bar!A1', opts);
+  t.isFixed('=[Foo Bar]Baz!A1', "='[Foo Bar]Baz'!A1", opts);
+  t.isFixed('=[Foo]!A1', '=[Foo]!A1', opts);
+  t.isFixed('=[Lorem Ipsum]!A1', "='[Lorem Ipsum]'!A1", opts);
+  t.end();
+});

package/lib/lexer-srefs.spec.js

@@ -2,7 +2,7 @@ import { test, Test } from 'tape';
 import {
   FX_PREFIX, UNKNOWN,
   OPERATOR, WHITESPACE,
-  REF_NAMED, CONTEXT_QUOTE, REF_STRUCT
+  REF_NAMED, CONTEXT_QUOTE, REF_STRUCT, REF_RANGE
 } from './constants.js';
 import { tokenize } from './lexer.js';
 
@@ -166,6 +166,14 @@ test('tokenize structured references (merges on)', t => {
   t.isTokens('[[#Totals],col name:Foo]', [
     { type: REF_STRUCT, value: '[[#Totals],col name:Foo]' }
   ]);
+  t.isTokens('Table1[[#This Row],[a]]*[1]Sheet1!$A$1', [
+    { type: REF_STRUCT, value: 'Table1[[#This Row],[a]]' },
+    { type: OPERATOR, value: '*' },
+    { type: REF_RANGE, value: '[1]Sheet1!$A$1' }
+  ], { xlsx: true });
+  t.isTokens("Sheet1!Table1[foo '[bar']]", [
+    { type: REF_STRUCT, value: "Sheet1!Table1[foo '[bar']]" }
+  ]);
   t.end();
 });
 

package/lib/lexer.js

@@ -202,6 +202,7 @@ export function getTokens (fx, tokenHandlers, options = {}) {
  * @param {boolean} [options.r1c1=false]  Ranges are expected to be in the R1C1 style format rather than the more popular A1 style.
  * @param {boolean} [options.withLocation=true]  Nodes will include source position offsets to the tokens: `{ loc: [ start, end ] }`
  * @param {boolean} [options.mergeRefs=true]  Should ranges be returned as whole references (`Sheet1!A1:B2`) or as separate tokens for each part: (`Sheet1`,`!`,`A1`,`:`,`B2`). This is the same as calling [`mergeRefTokens`](#mergeRefTokens)
+ * @param {boolean} [options.xlsx=false]  Enables a `[1]Sheet1!A1` or `[1]!name` syntax form for external workbooks found only in XLSX files.
  * @return {Array<Object>} An AST of nodes
  */
 export function tokenize (formula, options = {}) {

package/lib/lexer.spec.js

@@ -1697,3 +1697,75 @@ test('tokenize partial ranges', t => {
 
   t.end();
 });
+
+test('tokenize external refs syntax from XLSX files', t => {
+  const opts = { xlsx: true };
+  // Excel XLS files only use positive integers as workbooks...
+  t.isTokens('=[1]!A1', [
+    { type: FX_PREFIX, value: '=' },
+    { type: REF_RANGE, value: '[1]!A1' }
+  ], opts);
+  t.isTokens('=[1]Sheet1!A1', [
+    { type: FX_PREFIX, value: '=' },
+    { type: REF_RANGE, value: '[1]Sheet1!A1' }
+  ], opts);
+  t.isTokens('=[4]!name', [
+    { type: FX_PREFIX, value: '=' },
+    { type: REF_NAMED, value: '[4]!name' }
+  ], opts);
+  t.isTokens('=[16]Sheet1!name', [
+    { type: FX_PREFIX, value: '=' },
+    { type: REF_NAMED, value: '[16]Sheet1!name' }
+  ], opts);
+  t.isTokens("='[1]'!A1", [
+    { type: FX_PREFIX, value: '=' },
+    { type: REF_RANGE, value: "'[1]'!A1" }
+  ], opts);
+  t.isTokens("='[1]Sheet1'!A1", [
+    { type: FX_PREFIX, value: '=' },
+    { type: REF_RANGE, value: "'[1]Sheet1'!A1" }
+  ], opts);
+  t.isTokens("='[4]'!name", [
+    { type: FX_PREFIX, value: '=' },
+    { type: REF_NAMED, value: "'[4]'!name" }
+  ], opts);
+  t.isTokens("='[16]Sheet1'!name", [
+    { type: FX_PREFIX, value: '=' },
+    { type: REF_NAMED, value: "'[16]Sheet1'!name" }
+  ], opts);
+  // ...fx additionally permits workbook names
+  t.isTokens('=[Workbook.xlsx]!A1', [
+    { type: FX_PREFIX, value: '=' },
+    { type: REF_RANGE, value: '[Workbook.xlsx]!A1' }
+  ], opts);
+  t.isTokens('=[Workbook.xlsx]Sheet1!A1', [
+    { type: FX_PREFIX, value: '=' },
+    { type: REF_RANGE, value: '[Workbook.xlsx]Sheet1!A1' }
+  ], opts);
+  t.isTokens('=[Workbook.xlsx]!name', [
+    { type: FX_PREFIX, value: '=' },
+    { type: REF_NAMED, value: '[Workbook.xlsx]!name' }
+  ], opts);
+  t.isTokens('=[Workbook.xlsx]Sheet1!name', [
+    { type: FX_PREFIX, value: '=' },
+    { type: REF_NAMED, value: '[Workbook.xlsx]Sheet1!name' }
+  ], opts);
+  t.isTokens("='[Workbook.xlsx]'!A1", [
+    { type: FX_PREFIX, value: '=' },
+    { type: REF_RANGE, value: "'[Workbook.xlsx]'!A1" }
+  ], opts);
+  t.isTokens("='[Workbook.xlsx]Sheet1'!A1", [
+    { type: FX_PREFIX, value: '=' },
+    { type: REF_RANGE, value: "'[Workbook.xlsx]Sheet1'!A1" }
+  ], opts);
+  t.isTokens("='[Workbook.xlsx]'!name", [
+    { type: FX_PREFIX, value: '=' },
+    { type: REF_NAMED, value: "'[Workbook.xlsx]'!name" }
+  ], opts);
+  t.isTokens("='[Workbook.xlsx]Sheet1'!name", [
+    { type: FX_PREFIX, value: '=' },
+    { type: REF_NAMED, value: "'[Workbook.xlsx]Sheet1'!name" }
+  ], opts);
+
+  t.end();
+});

package/lib/lexerParts.js

@@ -28,8 +28,7 @@ const re_NEWLINE = /^\n+/;
 const re_WHITESPACE = /^[ \f\r\t\v\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]+/;
 const re_STRING = /^"(?:""|[^"])*("|$)/;
 const re_NUMBER = /^(?:\d+(\.\d+)?(?:[eE][+-]?\d+)?|\d+)/;
-
-const re_CONTEXT = /^(\[(?:[^\]])+\])?([0-9A-Za-z._¡¤§¨ª\u00ad¯-\uffff]+)(?=!)/;
+const re_CONTEXT = /^(?!!)(\[(?:[^\]])+\])?([0-9A-Za-z._¡¤§¨ª\u00ad¯-\uffff]+)?(?=!)/;
 const re_CONTEXT_QUOTE = /^'(?:''|[^'])*('|$)(?=!)/;
 
 const rngPart = '\\$?[A-Z]{1,3}\\$?[1-9][0-9]{0,6}';
@@ -63,6 +62,36 @@ function makeHandler (type, re) {
   };
 }
 
+const re_QUOTED_VALUE = /^'(?:[^[\]]+?)?(?:\[(.+?)\])?(?:[^[\]]+?)'$/;
+const re_QUOTED_VALUE_XLSX = /^'\[(.+?)\]'$/;
+function lexContext (str, options) {
+  const mq = re_CONTEXT_QUOTE.exec(str);
+  if (mq) {
+    const value = mq[0];
+    const isValid = options.xlsx
+      ? re_QUOTED_VALUE_XLSX.test(value) || re_QUOTED_VALUE.test(value)
+      : re_QUOTED_VALUE.test(value);
+    if (isValid) {
+      return { type: CONTEXT_QUOTE, value: value };
+    }
+  }
+  // xlsx xml uses a variant of the syntax that has external references in
+  // bracets. Any of: [1]Sheet1!A1, '[1]Sheet one'!A1, [1]!named
+  // We're only concerned with the non quoted version here as the quoted version
+  // doesn't currently examine what is in the quotes.
+  const m = re_CONTEXT.exec(str);
+  if (m) {
+    const [ , a, b ] = m;
+    const valid = (
+      ((a && b) || b) || // "[a]b!" or "b!" forms
+      (a && !b && options.xlsx) // "[a]" form (allowed in xlsx mode)
+    );
+    if (valid) {
+      return { type: CONTEXT, value: m[0] };
+    }
+  }
+}
+
 function lexStructured (str) {
   const structData = parseSRange(str);
   if (structData) {
@@ -159,8 +188,7 @@ export const lexers = [
   makeHandler(NEWLINE, re_NEWLINE),
   makeHandler(WHITESPACE, re_WHITESPACE),
   makeHandler(STRING, re_STRING),
-  makeHandler(CONTEXT_QUOTE, re_CONTEXT_QUOTE),
-  makeHandler(CONTEXT, re_CONTEXT),
+  lexContext,
   lexRange,
   lexStructured,
   makeHandler(NUMBER, re_NUMBER),
@@ -169,8 +197,7 @@ export const lexers = [
 
 export const lexersRefs = [
   lexRefOp,
-  makeHandler(CONTEXT_QUOTE, re_CONTEXT_QUOTE),
-  makeHandler(CONTEXT, re_CONTEXT),
+  lexContext,
   lexRange,
   lexStructured,
   makeHandler(REF_NAMED, re_NAMED)

package/lib/parseRef.js

@@ -12,13 +12,61 @@ import {
 import { lexersRefs } from './lexerParts.js';
 import { getTokens } from './lexer.js';
 
+// Liberally split a context string up into parts.
+// Permits any combination of braced and unbraced items.
+export function splitPrefix (str, stringsOnly = false) {
+  let inBrace = false;
+  let currStr = '';
+  const parts = [];
+  const flush = () => {
+    if (currStr) {
+      parts.push(
+        stringsOnly
+          ? currStr
+          : { value: currStr, braced: inBrace }
+      );
+    }
+    currStr = '';
+  };
+  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;
+}
+
 function splitContext (contextString) {
-  const m = /(?:\[(.+?)\])?([^[\]]+?)$/.exec(contextString);
-  if (m) {
-    const [ , a, b ] = m;
-    const context = [ a, b ].filter(Boolean);
-    return { context };
+  return { context: splitPrefix(contextString, true) };
+}
+
+function splitContextXlsx (contextString) {
+  const context = {};
+  const ctx = splitPrefix(contextString);
+  if (ctx.length > 1) {
+    context.workbookName = ctx[ctx.length - 2].value;
+    context.sheetName = ctx[ctx.length - 1].value;
+  }
+  else if (ctx.length === 1) {
+    const item = ctx[0];
+    if (item.braced) {
+      context.workbookName = item.value;
+    }
+    else {
+      context.sheetName = item.value;
+    }
   }
+  return context;
 }
 
 const unquote = d => d.slice(1, -1).replace(/''/g, "'");
@@ -30,9 +78,14 @@ const pRange2 = t => t && t.type === REF_RANGE && { r1: t.value };
 const pBang = t => t && t.type === OPERATOR && t.value === '!' && {};
 const pBeam = t => t && t.type === REF_BEAM && { r0: t.value };
 const pStrucured = t => t && t.type === REF_STRUCT && { struct: t.value };
-const pContext = t => {
-  if (t && t.type === CONTEXT) { return splitContext(t.value); }
-  if (t && t.type === CONTEXT_QUOTE) { return splitContext(unquote(t.value)); }
+const pContext = (t, opts) => {
+  const splitter = opts.xlsx ? splitContextXlsx : splitContext;
+  if (t && t.type === CONTEXT) {
+    return splitter(t.value);
+  }
+  if (t && t.type === CONTEXT_QUOTE) {
+    return splitter(unquote(t.value));
+  }
 };
 const pNamed = t => t && t.type === REF_NAMED && { name: t.value };
 
@@ -62,15 +115,24 @@ export function parseRef (ref, opts) {
     allowTernary: false,
     allowNamed: true,
     r1c1: false,
+    xlsx: false,
     ...opts
   };
   const tokens = getTokens(ref, lexersRefs, options);
-  const refData = {
-    context: [],
-    r0: '',
-    r1: '',
-    name: ''
-  };
+  const refData = options.xlsx
+    ? {
+      workbookName: '',
+      sheetName: '',
+      r0: '',
+      r1: '',
+      name: ''
+    }
+    : {
+      context: [],
+      r0: '',
+      r1: '',
+      name: ''
+    };
   // discard the "="-prefix if it is there
   if (tokens.length && tokens[0].type === FX_PREFIX) {
     tokens.shift();
@@ -80,7 +142,7 @@ export function parseRef (ref, opts) {
     const data = { ...refData };
     if (runs[i].length === tokens.length) {
       const valid = runs[i].every((parse, j) => {
-        const d = parse(tokens[j]);
+        const d = parse(tokens[j], options);
         Object.assign(data, d);
         return d;
       });

package/lib/parseRef.spec.js

@@ -0,0 +1,60 @@
+import { test } from 'tape';
+import { splitPrefix } from './parseRef.js';
+
+test('splitPrefix', t => {
+  const testStr = (str, opt, expected) => {
+    t.deepEqual(splitPrefix(str, opt), expected, str);
+  };
+
+  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]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' ]);
+  testStr('[foo][bar]', true, [ 'foo', 'bar' ]);
+  testStr('[foo]', true, [ 'foo' ]);
+  testStr('foo', true, [ 'foo' ]);
+
+  testStr('[foo][bar][baz]', false, [
+    { value: 'foo', braced: true },
+    { value: 'bar', braced: true },
+    { value: 'baz', braced: true } ]);
+  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[baz]', false, [
+    { value: 'foo', braced: true },
+    { value: 'bar', braced: false },
+    { value: 'baz', braced: true } ]);
+  testStr('[foo]bar', false, [
+    { value: 'foo', braced: true },
+    { value: 'bar', braced: false } ]);
+  testStr('foo[bar]', false, [
+    { value: 'foo', braced: false },
+    { value: 'bar', braced: true } ]);
+  testStr('[foo][bar]', false, [
+    { value: 'foo', braced: true },
+    { value: 'bar', braced: true } ]);
+  testStr('[foo]', false, [
+    { value: 'foo', braced: true } ]);
+  testStr('foo', false, [
+    { value: 'foo', braced: false } ]);
+
+  t.end();
+});

package/lib/parser.js

@@ -475,7 +475,7 @@ prefix('{', function () {
  * because it does not recognize reference context tokens.
  *
  * The AST Abstract Syntax Tree's format is documented in
- * [AST_format.md][./AST_format.md]
+ * [AST_format.md](./AST_format.md)
  *
  * @see nodeTypes
  * @param {(string | Array<Object>)} formula An Excel formula string (an Excel expression) or an array of tokens.
@@ -486,7 +486,8 @@ prefix('{', function () {
  * @param {boolean} [options.permitArrayRanges=false]  Ranges are allowed as elements of arrays. This is a feature in Google Sheets while Excel does not allow it.
  * @param {boolean} [options.permitArrayCalls=false]  Function calls are allowed as elements of arrays. This is a feature in Google Sheets while Excel does not allow it.
  * @param {boolean} [options.r1c1=false]  Ranges are expected to be in the R1C1 style format rather than the more popular A1 style.
- * @param {boolean} [options.withLocation=true]  Nodes will include source position offsets to the tokens: `{ loc: [ start, end ] }`
+ * @param {boolean} [options.withLocation=false]  Nodes will include source position offsets to the tokens: `{ loc: [ start, end ] }`
+ * @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} An AST of nodes
  */
 export function parse (source, options) {

package/lib/parser.spec.js

@@ -828,3 +828,14 @@ test('does not tolerate unterminated tokens', t => {
     { permitArrayCalls: true });
   t.end();
 });
+
+test('parser can permit xlsx mode references', t => {
+  t.isInvalidExpr('=SUM([Workbook.xlsx]!A1+[Workbook.xlsx]!Table1[#Data])');
+  t.isParsed('=SUM([Workbook.xlsx]!A1+[Workbook.xlsx]!Table1[#Data])',
+    { type: 'CallExpression', callee: { type: 'Identifier', name: 'SUM' }, arguments: [
+      { type: 'BinaryExpression', operator: '+', arguments: [
+        { type: 'ReferenceIdentifier', value: '[Workbook.xlsx]!A1' },
+        { type: 'ReferenceIdentifier', value: '[Workbook.xlsx]!Table1[#Data]' } ] } ] },
+    { xlsx: true });
+  t.end();
+});