@borgar/fx 4.10.2 → 4.11.0

package/lib/a1.js

@@ -1,66 +1,12 @@
 import { MAX_ROWS, MAX_COLS } from './constants.js';
 import { parseRef } from './parseRef.js';
+import { toCol } from './toCol.js';
+import { fromCol } from './fromCol.js';
 import { stringifyPrefix, stringifyPrefixAlt } from './stringifyPrefix.js';
 
 const clamp = (min, val, max) => Math.min(Math.max(val, min), max);
 const toColStr = (c, a) => (a ? '$' : '') + toCol(c);
 const toRowStr = (r, a) => (a ? '$' : '') + toRow(r);
-const charFrom = String.fromCharCode;
-
-/**
- * Convert a column string representation to a 0 based
- * offset number (`"C"` = `2`).
- *
- * The method expects a valid column identifier made up of _only_
- * A-Z letters, which may be either upper or lower case. Other input will
- * return garbage.
- *
- * @param {string} columnString  The column string identifier
- * @returns {number}  Zero based column index number
- */
-export function fromCol (columnString) {
-  const x = (columnString || '');
-  const l = x.length;
-  let n = 0;
-  if (l > 2) {
-    const c = x.charCodeAt(l - 3);
-    const a = c > 95 ? 32 : 0;
-    n += (1 + c - a - 65) * 676;
-  }
-  if (l > 1) {
-    const c = x.charCodeAt(l - 2);
-    const a = c > 95 ? 32 : 0;
-    n += (1 + c - a - 65) * 26;
-  }
-  if (l) {
-    const c = x.charCodeAt(l - 1);
-    const a = c > 95 ? 32 : 0;
-    n += (c - a) - 65;
-  }
-  return n;
-}
-
-/**
- * Convert a 0 based offset number to a column string
- * representation (`2` = `"C"`).
- *
- * The method expects a number between 0 and 16383. Other input will
- * return garbage.
- *
- * @param {number} columnIndex Zero based column index number
- * @returns {string} The column string identifier
- */
-export function toCol (columnIndex) {
-  return (
-    (columnIndex >= 702
-      ? charFrom(((((columnIndex - 702) / 676) - 0) % 26) + 65)
-      : '') +
-    (columnIndex >= 26
-      ? charFrom(((((columnIndex / 26) - 1) % 26) + 65))
-      : '') +
-    charFrom((columnIndex % 26) + 65)
-  );
-}
 
 export function fromRow (rowStr) {
   return +rowStr - 1;

package/lib/a1.spec.js

@@ -1,8 +1,6 @@
 /* eslint-disable object-property-newline, object-curly-newline */
 import { test, Test } from 'tape';
 import {
-  fromCol,
-  toCol,
   fromRow,
   toRow,
   toRelative,
@@ -33,15 +31,6 @@ Test.prototype.isA1Equal = function isA1Equal (expr, expect, opts) {
 
 // What happens when B2:A1 -> should work!
 test('convert to and from column and row ids', t => {
-  t.is(fromCol('a'), 0);
-  t.is(fromCol('A'), 0);
-  t.is(fromCol('AA'), 26);
-  t.is(fromCol('zz'), 701);
-  t.is(fromCol('ZZZ'), 18277);
-  t.is(toCol(0), 'A');
-  t.is(toCol(26), 'AA');
-  t.is(toCol(701), 'ZZ');
-  t.is(toCol(18277), 'ZZZ');
   t.is(fromRow('11'), 10);
   t.is(fromRow('1'), 0);
   t.is(toRow(12), '13');

package/lib/addTokenMeta.js

@@ -1,6 +1,6 @@
 import { REF_RANGE, REF_BEAM, REF_TERNARY, UNKNOWN, REF_STRUCT } from './constants.js';
 import { parseA1Ref } from './a1.js';
-import { parseStructRef } from './sr.js';
+import { parseStructRef } from './parseStructRef.js';
 
 function getIDer () {
   let i = 1;

package/lib/fixRanges.js

@@ -1,6 +1,7 @@
 import { isRange } from './isType.js';
 import { parseA1Ref, stringifyA1Ref, addA1RangeBounds } from './a1.js';
-import { parseStructRef, stringifyStructRef } from './sr.js';
+import { parseStructRef } from './parseStructRef.js';
+import { stringifyStructRef } from './stringifyStructRef.js';
 import { tokenize } from './lexer.js';
 import { REF_STRUCT } from './constants.js';
 

package/lib/fromCol.js

@@ -0,0 +1,32 @@
+/**
+ * Convert a column string representation to a 0 based
+ * offset number (`"C"` = `2`).
+ *
+ * The method expects a valid column identifier made up of _only_
+ * A-Z letters, which may be either upper or lower case. Other input will
+ * return garbage.
+ *
+ * @param {string} columnString  The column string identifier
+ * @returns {number}  Zero based column index number
+ */
+export function fromCol (columnString) {
+  const x = (columnString || '');
+  const l = x.length;
+  let n = 0;
+  if (l > 2) {
+    const c = x.charCodeAt(l - 3);
+    const a = c > 95 ? 32 : 0;
+    n += (1 + c - a - 65) * 676;
+  }
+  if (l > 1) {
+    const c = x.charCodeAt(l - 2);
+    const a = c > 95 ? 32 : 0;
+    n += (1 + c - a - 65) * 26;
+  }
+  if (l) {
+    const c = x.charCodeAt(l - 1);
+    const a = c > 95 ? 32 : 0;
+    n += (c - a) - 65;
+  }
+  return n;
+}

package/lib/fromCol.spec.js

@@ -0,0 +1,11 @@
+import { test } from 'tape';
+import { fromCol } from './fromCol.js';
+
+test('fromCol parses column id strings to numbers', t => {
+  t.is(fromCol('a'), 0);
+  t.is(fromCol('A'), 0);
+  t.is(fromCol('AA'), 26);
+  t.is(fromCol('zz'), 701);
+  t.is(fromCol('ZZZ'), 18277);
+  t.end();
+});

package/lib/index.js

@@ -16,9 +16,10 @@ export {
   isWhitespace
 } from './isType.js';
 
+export { fromCol } from './fromCol.js';
+export { toCol } from './toCol.js';
+
 export {
-  fromCol,
-  toCol,
   parseA1Ref,
   stringifyA1Ref,
   addA1RangeBounds
@@ -29,10 +30,8 @@ export {
   stringifyR1C1Ref
 } from './rc.js';
 
-export {
-  parseStructRef,
-  stringifyStructRef
-} from './sr.js';
+export { stringifyStructRef } from './stringifyStructRef.js';
+export { parseStructRef } from './parseStructRef.js';
 
 import {
   // token types

package/lib/isType.spec.js

@@ -0,0 +1,168 @@
+import { test } from 'tape';
+import {
+  REF_RANGE, REF_BEAM, REF_NAMED, REF_TERNARY, REF_STRUCT,
+  FX_PREFIX, WHITESPACE, NEWLINE,
+  FUNCTION, OPERATOR,
+  ERROR, STRING, NUMBER, BOOLEAN
+} from './constants.js';
+import { isRange, isReference, isLiteral, isError, isWhitespace, isFunction, isFxPrefix, isOperator } from './isType.js';
+
+test('isRange', t => {
+  t.is(isRange(null), false, 'null is not a range');
+  t.is(isRange({}), false, 'plain object is not a range');
+  t.is(isRange({ type: BOOLEAN }), false, 'BOOLEAN is not a range');
+  t.is(isRange({ type: ERROR }), false, 'ERROR is not a range');
+  t.is(isRange({ type: FUNCTION }), false, 'FUNCTION is not a range');
+  t.is(isRange({ type: FX_PREFIX }), false, 'FX_PREFIX is not a range');
+  t.is(isRange({ type: NEWLINE }), false, 'NEWLINE is not a range');
+  t.is(isRange({ type: NUMBER }), false, 'NUMBER is not a range');
+  t.is(isRange({ type: OPERATOR }), false, 'OPERATOR is not a range');
+  t.is(isRange({ type: REF_BEAM }), true, 'REF_BEAM is a range');
+  t.is(isRange({ type: REF_NAMED }), false, 'REF_NAMED is not a range');
+  t.is(isRange({ type: REF_RANGE }), true, 'REF_RANGE is a range');
+  t.is(isRange({ type: REF_STRUCT }), false, 'REF_STRUCT is not a range');
+  t.is(isRange({ type: REF_TERNARY }), true, 'REF_TERNARY is a range');
+  t.is(isRange({ type: STRING }), false, 'STRING is not a range');
+  t.is(isRange({ type: WHITESPACE }), false, 'WHITESPACE is not a range');
+  t.end();
+});
+
+test('isReference', t => {
+  t.is(isReference(null), false, 'null is not a reference');
+  t.is(isReference({}), false, 'plain object is not a reference');
+  t.is(isReference({ type: BOOLEAN }), false, 'BOOLEAN is not a reference');
+  t.is(isReference({ type: ERROR }), false, 'ERROR is not a reference');
+  t.is(isReference({ type: FUNCTION }), false, 'FUNCTION is not a reference');
+  t.is(isReference({ type: FX_PREFIX }), false, 'FX_PREFIX is not a reference');
+  t.is(isReference({ type: NEWLINE }), false, 'NEWLINE is not a reference');
+  t.is(isReference({ type: NUMBER }), false, 'NUMBER is not a reference');
+  t.is(isReference({ type: OPERATOR }), false, 'OPERATOR is not a reference');
+  t.is(isReference({ type: REF_BEAM }), true, 'REF_BEAM is a reference');
+  t.is(isReference({ type: REF_NAMED }), true, 'REF_NAMED is not a reference');
+  t.is(isReference({ type: REF_RANGE }), true, 'REF_RANGE is a reference');
+  t.is(isReference({ type: REF_STRUCT }), true, 'REF_STRUCT is not a reference');
+  t.is(isReference({ type: REF_TERNARY }), true, 'REF_TERNARY is a reference');
+  t.is(isReference({ type: STRING }), false, 'STRING is not a reference');
+  t.is(isReference({ type: WHITESPACE }), false, 'WHITESPACE is not a reference');
+  t.end();
+});
+
+test('isLiteral', t => {
+  t.is(isLiteral(null), false, 'null is not a literal');
+  t.is(isLiteral({}), false, 'plain object is not a literal');
+  t.is(isLiteral({ type: BOOLEAN }), true, 'BOOLEAN is not a literal');
+  t.is(isLiteral({ type: ERROR }), true, 'ERROR is not a literal');
+  t.is(isLiteral({ type: FUNCTION }), false, 'FUNCTION is not a literal');
+  t.is(isLiteral({ type: FX_PREFIX }), false, 'FX_PREFIX is not a literal');
+  t.is(isLiteral({ type: NEWLINE }), false, 'NEWLINE is not a literal');
+  t.is(isLiteral({ type: NUMBER }), true, 'NUMBER is not a literal');
+  t.is(isLiteral({ type: OPERATOR }), false, 'OPERATOR is not a literal');
+  t.is(isLiteral({ type: REF_BEAM }), false, 'REF_BEAM is a literal');
+  t.is(isLiteral({ type: REF_NAMED }), false, 'REF_NAMED is not a literal');
+  t.is(isLiteral({ type: REF_RANGE }), false, 'REF_RANGE is a literal');
+  t.is(isLiteral({ type: REF_STRUCT }), false, 'REF_STRUCT is not a literal');
+  t.is(isLiteral({ type: REF_TERNARY }), false, 'REF_TERNARY is a literal');
+  t.is(isLiteral({ type: STRING }), true, 'STRING is not a literal');
+  t.is(isLiteral({ type: WHITESPACE }), false, 'WHITESPACE is not a literal');
+  t.end();
+});
+
+test('isError', t => {
+  t.is(isError(null), false, 'null is not an error');
+  t.is(isError({}), false, 'plain object is not an error');
+  t.is(isError({ type: BOOLEAN }), false, 'BOOLEAN is not an error');
+  t.is(isError({ type: ERROR }), true, 'ERROR is not an error');
+  t.is(isError({ type: FUNCTION }), false, 'FUNCTION is not an error');
+  t.is(isError({ type: FX_PREFIX }), false, 'FX_PREFIX is not an error');
+  t.is(isError({ type: NEWLINE }), false, 'NEWLINE is not an error');
+  t.is(isError({ type: NUMBER }), false, 'NUMBER is not an error');
+  t.is(isError({ type: OPERATOR }), false, 'OPERATOR is not an error');
+  t.is(isError({ type: REF_BEAM }), false, 'REF_BEAM is an error');
+  t.is(isError({ type: REF_NAMED }), false, 'REF_NAMED is not an error');
+  t.is(isError({ type: REF_RANGE }), false, 'REF_RANGE is an error');
+  t.is(isError({ type: REF_STRUCT }), false, 'REF_STRUCT is not an error');
+  t.is(isError({ type: REF_TERNARY }), false, 'REF_TERNARY is an error');
+  t.is(isError({ type: STRING }), false, 'STRING is not an error');
+  t.is(isError({ type: WHITESPACE }), false, 'WHITESPACE is not an error');
+  t.end();
+});
+
+test('isWhitespace', t => {
+  t.is(isWhitespace(null), false, 'null is not a whitespace');
+  t.is(isWhitespace({}), false, 'plain object is not a whitespace');
+  t.is(isWhitespace({ type: BOOLEAN }), false, 'BOOLEAN is not a whitespace');
+  t.is(isWhitespace({ type: ERROR }), false, 'ERROR is not a whitespace');
+  t.is(isWhitespace({ type: FUNCTION }), false, 'FUNCTION is not a whitespace');
+  t.is(isWhitespace({ type: FX_PREFIX }), false, 'FX_PREFIX is not a whitespace');
+  t.is(isWhitespace({ type: NEWLINE }), true, 'NEWLINE is not a whitespace');
+  t.is(isWhitespace({ type: NUMBER }), false, 'NUMBER is not a whitespace');
+  t.is(isWhitespace({ type: OPERATOR }), false, 'OPERATOR is not a whitespace');
+  t.is(isWhitespace({ type: REF_BEAM }), false, 'REF_BEAM is a whitespace');
+  t.is(isWhitespace({ type: REF_NAMED }), false, 'REF_NAMED is not a whitespace');
+  t.is(isWhitespace({ type: REF_RANGE }), false, 'REF_RANGE is a whitespace');
+  t.is(isWhitespace({ type: REF_STRUCT }), false, 'REF_STRUCT is not a whitespace');
+  t.is(isWhitespace({ type: REF_TERNARY }), false, 'REF_TERNARY is a whitespace');
+  t.is(isWhitespace({ type: STRING }), false, 'STRING is not a whitespace');
+  t.is(isWhitespace({ type: WHITESPACE }), true, 'WHITESPACE is not a whitespace');
+  t.end();
+});
+
+test('isFunction', t => {
+  t.is(isFunction(null), false, 'null is not a function');
+  t.is(isFunction({}), false, 'plain object is not a function');
+  t.is(isFunction({ type: BOOLEAN }), false, 'BOOLEAN is not a function');
+  t.is(isFunction({ type: ERROR }), false, 'ERROR is not a function');
+  t.is(isFunction({ type: FUNCTION }), true, 'FUNCTION is not a function');
+  t.is(isFunction({ type: FX_PREFIX }), false, 'FX_PREFIX is not a function');
+  t.is(isFunction({ type: NEWLINE }), false, 'NEWLINE is not a function');
+  t.is(isFunction({ type: NUMBER }), false, 'NUMBER is not a function');
+  t.is(isFunction({ type: OPERATOR }), false, 'OPERATOR is not a function');
+  t.is(isFunction({ type: REF_BEAM }), false, 'REF_BEAM is a function');
+  t.is(isFunction({ type: REF_NAMED }), false, 'REF_NAMED is not a function');
+  t.is(isFunction({ type: REF_RANGE }), false, 'REF_RANGE is a function');
+  t.is(isFunction({ type: REF_STRUCT }), false, 'REF_STRUCT is not a function');
+  t.is(isFunction({ type: REF_TERNARY }), false, 'REF_TERNARY is a function');
+  t.is(isFunction({ type: STRING }), false, 'STRING is not a function');
+  t.is(isFunction({ type: WHITESPACE }), false, 'WHITESPACE is not a function');
+  t.end();
+});
+
+test('isFxPrefix', t => {
+  t.is(isFxPrefix(null), false, 'null is not a prefix');
+  t.is(isFxPrefix({}), false, 'plain object is not a prefix');
+  t.is(isFxPrefix({ type: BOOLEAN }), false, 'BOOLEAN is not a prefix');
+  t.is(isFxPrefix({ type: ERROR }), false, 'ERROR is not a prefix');
+  t.is(isFxPrefix({ type: FUNCTION }), false, 'FUNCTION is not a prefix');
+  t.is(isFxPrefix({ type: FX_PREFIX }), true, 'FX_PREFIX is not a prefix');
+  t.is(isFxPrefix({ type: NEWLINE }), false, 'NEWLINE is not a prefix');
+  t.is(isFxPrefix({ type: NUMBER }), false, 'NUMBER is not a prefix');
+  t.is(isFxPrefix({ type: OPERATOR }), false, 'OPERATOR is not a prefix');
+  t.is(isFxPrefix({ type: REF_BEAM }), false, 'REF_BEAM is a prefix');
+  t.is(isFxPrefix({ type: REF_NAMED }), false, 'REF_NAMED is not a prefix');
+  t.is(isFxPrefix({ type: REF_RANGE }), false, 'REF_RANGE is a prefix');
+  t.is(isFxPrefix({ type: REF_STRUCT }), false, 'REF_STRUCT is not a prefix');
+  t.is(isFxPrefix({ type: REF_TERNARY }), false, 'REF_TERNARY is a prefix');
+  t.is(isFxPrefix({ type: STRING }), false, 'STRING is not a prefix');
+  t.is(isFxPrefix({ type: WHITESPACE }), false, 'WHITESPACE is not a prefix');
+  t.end();
+});
+
+test('isOperator', t => {
+  t.is(isOperator(null), false, 'null is not a operator');
+  t.is(isOperator({}), false, 'plain object is not a operator');
+  t.is(isOperator({ type: BOOLEAN }), false, 'BOOLEAN is not a operator');
+  t.is(isOperator({ type: ERROR }), false, 'ERROR is not a operator');
+  t.is(isOperator({ type: FUNCTION }), false, 'FUNCTION is not a operator');
+  t.is(isOperator({ type: FX_PREFIX }), false, 'FX_PREFIX is not a operator');
+  t.is(isOperator({ type: NEWLINE }), false, 'NEWLINE is not a operator');
+  t.is(isOperator({ type: NUMBER }), false, 'NUMBER is not a operator');
+  t.is(isOperator({ type: OPERATOR }), true, 'OPERATOR is not a operator');
+  t.is(isOperator({ type: REF_BEAM }), false, 'REF_BEAM is a operator');
+  t.is(isOperator({ type: REF_NAMED }), false, 'REF_NAMED is not a operator');
+  t.is(isOperator({ type: REF_RANGE }), false, 'REF_RANGE is a operator');
+  t.is(isOperator({ type: REF_STRUCT }), false, 'REF_STRUCT is not a operator');
+  t.is(isOperator({ type: REF_TERNARY }), false, 'REF_TERNARY is a operator');
+  t.is(isOperator({ type: STRING }), false, 'STRING is not a operator');
+  t.is(isOperator({ type: WHITESPACE }), false, 'WHITESPACE is not a operator');
+  t.end();
+});

package/lib/lexerParts.js

@@ -18,8 +18,8 @@ import {
   MAX_ROWS,
   OPERATOR_TRIM
 } from './constants.js';
-import { fromCol } from './a1.js';
-import { parseSRange } from './sr.js';
+import { fromCol } from './fromCol.js';
+import { parseSRange } from './parseSRange.js';
 
 const re_ERROR = /^#(NAME\?|FIELD!|CALC!|VALUE!|REF!|DIV\/0!|NULL!|NUM!|N\/A|GETTING_DATA\b|SPILL!|UNKNOWN!|FIELD\b|CALC\b|SYNTAX\?|ERROR!|CONNECT!|BLOCKED!|EXTERNAL!)/i;
 const re_OPERATOR = /^(<=|>=|<>|[-+/*^%&<>=]|[{},;]|[()]|@|:|!|#)/;

package/lib/parseSRange.js

@@ -0,0 +1,165 @@
+const re_SRcolumnB = /^\[('['#@[\]]|[^'#@[\]])+\]/i;
+const re_SRcolumnN = /^([^#@[\]:]+)/i;
+
+const keyTerms = {
+  'headers': 1,
+  'data': 2,
+  'totals': 4,
+  'all': 8,
+  'this row': 16,
+  '@': 16
+};
+
+const fz = (...a) => Object.freeze(a);
+
+// only combinations allowed are: #data + (#headers | #totals | #data)
+const sectionMap = {
+  // no terms
+  0: fz(),
+  // single term
+  1: fz('headers'),
+  2: fz('data'),
+  4: fz('totals'),
+  8: fz('all'),
+  16: fz('this row'),
+  // headers+data
+  3: fz('headers', 'data'),
+  // totals+data
+  6: fz('data', 'totals')
+};
+
+const matchColumn = (s, allowUnbraced = true) => {
+  let m = re_SRcolumnB.exec(s);
+  if (m) {
+    const value = m[0].slice(1, -1).replace(/'(['#@[\]])/g, '$1');
+    return [ m[0], value ];
+  }
+  if (allowUnbraced) {
+    m = re_SRcolumnN.exec(s);
+    if (m) {
+      return [ m[0], m[0] ];
+    }
+  }
+  return null;
+};
+
+export function parseSRange (raw) {
+  const columns = [];
+  let pos = 0;
+  let s = raw;
+  let m;
+  let m1;
+  let terms = 0;
+
+  // start of structured ref?
+  if ((m = /^(\[\s*)/.exec(s))) {
+    // quickly determine if this is a simple keyword or column
+    // [#keyword]
+    if ((m1 = /^\[#([a-z ]+)\]/i.exec(s))) {
+      const k = m1[1].toLowerCase();
+      pos += m1[0].length;
+      if (keyTerms[k]) {
+        terms |= keyTerms[k];
+      }
+      else {
+        return null;
+      }
+    }
+    // [column]
+    else if ((m1 = matchColumn(s, false))) {
+      pos += m1[0].length;
+      columns.push(m1[1]);
+    }
+    // use the "normal" method
+    // [[#keyword]]
+    // [[column]]
+    // [@]
+    // [@column]
+    // [@[column]]
+    // [@column:column]
+    // [@column:[column]]
+    // [@[column]:column]
+    // [@[column]:[column]]
+    // [column:column]
+    // [column:[column]]
+    // [[column]:column]
+    // [[column]:[column]]
+    // [[#keyword],column]
+    // [[#keyword],column:column]
+    // [[#keyword],[#keyword],column:column]
+    // ...
+    else {
+      let expect_more = true;
+      s = s.slice(m[1].length);
+      pos += m[1].length;
+      // match keywords as we find them
+      while (
+        expect_more &&
+        (m = /^\[#([a-z ]+)\](\s*,\s*)?/i.exec(s))
+      ) {
+        const k = m[1].toLowerCase();
+        if (keyTerms[k]) {
+          terms |= keyTerms[k];
+          s = s.slice(m[0].length);
+          pos += m[0].length;
+          expect_more = !!m[2];
+        }
+        else {
+          return null;
+        }
+      }
+      // is there an @ specifier?
+      if (expect_more && (m = /^@/.exec(s))) {
+        terms |= keyTerms['@'];
+        s = s.slice(1);
+        pos += 1;
+        expect_more = s[0] !== ']';
+      }
+      // not all keyword terms may be combined
+      if (!(terms in sectionMap)) {
+        return null;
+      }
+      // column definitions
+      const leftCol = expect_more ? matchColumn(raw.slice(pos)) : null;
+      if (leftCol) {
+        pos += leftCol[0].length;
+        columns.push(leftCol[1]);
+        s = raw.slice(pos);
+        if (s[0] === ':') {
+          s = s.slice(1);
+          pos++;
+          const rightCol = matchColumn(s);
+          if (rightCol) {
+            pos += rightCol[0].length;
+            columns.push(rightCol[1]);
+          }
+          else {
+            return null;
+          }
+        }
+        expect_more = false;
+      }
+      // advance ws
+      while (raw[pos] === ' ') {
+        pos++;
+      }
+      // close the ref
+      if (expect_more || raw[pos] !== ']') {
+        return null;
+      }
+      // step over the closing ]
+      pos++;
+    }
+  }
+  else {
+    return null;
+  }
+
+  const sections = sectionMap[terms];
+  return {
+    columns,
+    sections: sections ? sections.concat() : sections,
+    length: pos,
+    token: raw.slice(0, pos)
+  };
+}

package/lib/parseStructRef.js

@@ -0,0 +1,48 @@
+import { parseRef } from './parseRef.js';
+import { parseSRange } from './parseSRange.js';
+
+/**
+ * Parse a structured reference string into an object representing it.
+ *
+ * ```js
+ * parseStructRef('workbook.xlsx!tableName[[#Data],[Column1]:[Column2]]');
+ * // => {
+ * //   context: [ 'workbook.xlsx' ],
+ * //   sections: [ 'data' ],
+ * //   columns: [ 'my column', '@foo' ],
+ * //   table: 'tableName',
+ * // }
+ * ```
+ *
+ * For A:A or A1:A style ranges, `null` will be used for any dimensions that the
+ * syntax does not specify:
+ *
+ * @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)
+ * @returns {(ReferenceStruct|null)} An object representing a valid reference or null if it is invalid.
+ */
+export function parseStructRef (ref, options = { xlsx: false }) {
+  const r = parseRef(ref, options);
+  if (r && r.struct) {
+    const structData = parseSRange(r.struct);
+    if (structData && structData.length === r.struct.length) {
+      return options.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;
+}