@borgar/fx 3.1.0 → 4.0.0-rc.2

package/lib/rc.js

@@ -10,6 +10,8 @@ import { MAX_ROWS, MAX_COLS } from './constants.js';
 import { parseRef } from './parseRef.js';
 import { stringifyPrefix } from './stringifyPrefix.js';
 
+const clamp = (min, val, max) => Math.min(Math.max(val, min), max);
+
 function toCoord (value, isAbs) {
   if (isAbs) {
     return String(value + 1);
@@ -17,12 +19,33 @@ function toCoord (value, isAbs) {
   return value ? '[' + value + ']' : '';
 }
 
-export function toRC (range) {
-  const { r0, c0, r1, c1, $c0, $c1, $r0, $r1 } = range;
+/**
+ * Stringify a range object into R1C1 syntax.
+ *
+ * @private
+ * @see parseR1C1Ref
+ * @param {Object} range  A range object
+ * @return {string}  An R1C1-style string represenation of a range
+ */
+export function toR1C1 (range) {
+  let { r0, c0, r1, c1 } = range;
+  const { $c0, $c1, $r0, $r1 } = range;
   const nullR0 = r0 == null;
-  const nullR1 = r1 == null;
   const nullC0 = c0 == null;
-  const nullC1 = c1 == null;
+  let nullR1 = r1 == null;
+  let nullC1 = c1 == null;
+  r0 = clamp($r0 ? 0 : -MAX_ROWS, r0 | 0, MAX_ROWS);
+  c0 = clamp($c0 ? 0 : -MAX_COLS, c0 | 0, MAX_COLS);
+  if (!nullR0 && nullR1 && !nullC0 && nullC1) {
+    r1 = r0;
+    nullR1 = false;
+    c1 = c0;
+    nullC1 = false;
+  }
+  else {
+    r1 = clamp($r1 ? 0 : -MAX_ROWS, r1 | 0, MAX_ROWS);
+    c1 = clamp($c1 ? 0 : -MAX_COLS, c1 | 0, MAX_COLS);
+  }
   // C:C
   if ((r0 === 0 && r1 >= MAX_ROWS) || (nullR0 && nullR1)) {
     const a = toCoord(c0, $c0);
@@ -57,7 +80,7 @@ export function toRC (range) {
   return 'R' + s_r0 + 'C' + s_c0;
 }
 
-function parseRCPart (ref) {
+function parseR1C1Part (ref) {
   let r0 = null;
   let c0 = null;
   let $r0 = null;
@@ -103,14 +126,22 @@ function parseRCPart (ref) {
   return [ r0, c0, $r0, $c0 ];
 }
 
-export function fromRC (ref) {
+/**
+ * Parse a simple string reference to an R1C1 range into a range object.
+ *
+ * @private
+ * @see parseA1Ref
+ * @param {string} rangeString  A range string
+ * @return {(Object|null)} An object representing a valid reference or null if it is invalid.
+ */
+export function fromR1C1 (ref) {
   let final = null;
   const [ part1, part2 ] = ref.split(':', 2);
-  const range = parseRCPart(part1);
+  const range = parseR1C1Part(part1);
   if (range) {
     const [ r0, c0, $r0, $c0 ] = range;
     if (part2) {
-      const extendTo = parseRCPart(part2);
+      const extendTo = parseR1C1Part(part2);
       if (extendTo) {
         final = {};
         const [ r1, c1, $r1, $c1 ] = extendTo;
@@ -213,12 +244,38 @@ export function fromRC (ref) {
   return final;
 }
 
-export function parseRCRef (ref, { allowNamed = true, allowTernary = false } = {}) {
-  const d = parseRef(ref, { allowNamed, allowTernary, r1c1: true });
+/**
+ * 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
+ * //   }
+ * // }
+ * ```
+ *
+ * @param {string} refString An R1C1-style reference string
+ * @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.
+ * @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 });
   if (d && (d.r0 || d.name)) {
     const range = d.r1
-      ? fromRC(d.r0 + ':' + d.r1)
-      : fromRC(d.r0);
+      ? fromR1C1(d.r0 + ':' + d.r1)
+      : fromR1C1(d.r0);
     if (d.name || range) {
       d.range = range;
       delete d.r0;
@@ -232,15 +289,31 @@ export function parseRCRef (ref, { allowNamed = true, allowTernary = false } = {
   return null;
 }
 
-export function stringifyRCRef (ref) {
-  return stringifyPrefix(ref) + (
-    ref.name ? ref.name : toRC(ref.range)
+/**
+ * Get an R1C1-style string representation of a reference object.
+ *
+ * ```js
+ * stringifyR1C1Ref({
+ *   context: [ 'Sheet1' ],
+ *   range: {
+ *     r0: 9,
+ *     c0: 8,
+ *     r1: 9,
+ *     c1: 8,
+ *     $c0: true,
+ *     $c1: true
+ *     $r0: false,
+ *     $r1: false
+ *   }
+ * });
+ * // => 'Sheet1!R[9]C9:R[9]C9'
+ * ```
+ *
+ * @param {Object} refObject A reference object
+ * @return {Object} The reference in R1C1-style string format
+ */
+export function stringifyR1C1Ref (refObject) {
+  return stringifyPrefix(refObject) + (
+    refObject.name ? refObject.name : toR1C1(refObject.range)
   );
 }
-
-export default {
-  to: toRC,
-  from: fromRC,
-  parse: parseRCRef,
-  stringify: stringifyRCRef
-};

package/lib/rc.spec.js

@@ -1,7 +1,7 @@
 /* eslint-disable object-property-newline, object-curly-newline */
 import { test, Test } from 'tape';
 import { MAX_COLS, MAX_ROWS } from './constants.js';
-import { parseRCRef, stringifyRCRef, toRC } from './rc.js';
+import { parseR1C1Ref, stringifyR1C1Ref, toR1C1 } from './rc.js';
 
 Test.prototype.isRCEqual = function isTokens (expr, result, opts) {
   if (result) {
@@ -20,11 +20,11 @@ Test.prototype.isRCEqual = function isTokens (expr, result, opts) {
       };
     }
   }
-  this.deepEqual(parseRCRef(expr, opts), result, expr);
+  this.deepEqual(parseR1C1Ref(expr, opts), result, expr);
 };
 
 Test.prototype.isR1C1Rendered = function isTokens (range, expect, d) {
-  this.is(toRC(range, d), expect, expect);
+  this.is(toR1C1(range, d), expect, expect);
 };
 
 test('parse single R1C1 references', t => {
@@ -196,12 +196,23 @@ test('R1C1 serialization', t => {
   t.isR1C1Rendered({ r0: -6, c0: 15, r1: 3, $c0: true, $c1: true }, 'R[-6]C16:R[3]');
   t.isR1C1Rendered({ r0: 0, c0: 10, r1: 9, $r0: true, $r1: true }, 'R1C[10]:R10');
   t.isR1C1Rendered({ r0: 0, c0: 15, r1: 9, $r0: true, $c0: true, $r1: true, $c1: true }, 'R1C16:R10');
+  // allow skipping right/bottom for cells
+  t.isR1C1Rendered({ r0: -5, c0: -2 }, 'R[-5]C[-2]');
+  // clamp the range at min/max dimensions
+  const abs = { $r0: true, $c0: true, $r1: true, $c1: true };
+  t.isR1C1Rendered({ r0: 1, c0: -20000, r1: 1, c1: 20000, ...abs }, 'R2');
+  t.isR1C1Rendered({ r0: -15e5, c0: 1, r1: 15e5, c1: 1, ...abs }, 'C2');
+  t.isR1C1Rendered({ r0: -5, c0: -2, r1: -8, c1: -7, ...abs }, 'R1C1');
+  t.isR1C1Rendered({ r0: 0, c0: -20000, r1: 0, c1: 20000 }, 'RC[-16383]:RC[16383]');
+  t.isR1C1Rendered({ r0: -15e5, c0: 0, r1: 15e5, c1: 0 }, 'R[-1048575]C:R[1048575]C');
+  t.isR1C1Rendered({ r0: 0.5, c0: 0.5, r1: 0.5, c1: 0.5, ...abs }, 'R1C1');
+  t.isR1C1Rendered({ r0: 0.5, c0: 0.5, r1: 0.5, c1: 0.5 }, 'RC');
   t.end();
 });
 
-test('stringifyRCRef', t => {
+test('stringifyR1C1Ref', t => {
   const rangeA1 = { r0: 2, c0: 4, r1: 2, c1: 4 };
-  const testRef = (ref, expect) => t.is(stringifyRCRef(ref), expect, expect);
+  const testRef = (ref, expect) => t.is(stringifyR1C1Ref(ref), expect, expect);
   testRef({ range: rangeA1 }, 'R[2]C[4]');
   testRef({ context: [ 'Sheet1' ], range: rangeA1 }, 'Sheet1!R[2]C[4]');
   testRef({ context: [ 'Sheet 1' ], range: rangeA1 }, "'Sheet 1'!R[2]C[4]");

package/lib/sr.js

@@ -0,0 +1,277 @@
+import { parseRef } from './parseRef.js';
+import { stringifyPrefix } from './stringifyPrefix.js';
+
+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].trim());
+    }
+    // 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].trim());
+        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].trim());
+          }
+          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)
+  };
+}
+
+/**
+ * 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
+ * @return {(Object|null)} An object representing a valid reference or null if it is invalid.
+ */
+export function parseStructRef (ref, opts = {}) {
+  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 null;
+}
+
+function quoteColname (str) {
+  return str.replace(/([[\]#'@])/g, '\'$1');
+}
+
+function needsBraces (str) {
+  return !/^[a-zA-Z0-9\u00a1-\uffff]+$/.test(str);
+}
+
+function toSentenceCase (str) {
+  return str[0].toUpperCase() + str.slice(1).toLowerCase();
+}
+
+/**
+ * Get a string representation of a structured reference object.
+ *
+ * ```js
+ * stringifyStructRef({
+ *   context: [ 'workbook.xlsx' ],
+ *   sections: [ 'data' ],
+ *   columns: [ 'my column', '@foo' ],
+ *   table: 'tableName',
+ * });
+ * // => 'workbook.xlsx!tableName[[#Data],[Column1]:[Column2]]'
+ * ```
+ *
+ * @param {Object} refObject A structured reference object
+ * @return {Object} The structured reference in string format
+ */
+export function stringifyStructRef (ref) {
+  let s = stringifyPrefix(ref);
+  if (ref.table) {
+    s += ref.table;
+  }
+  const numColumns = ref.columns?.length ?? 0;
+  const numSections = ref.sections?.length ?? 0;
+  // single section
+  if (numSections === 1 && !numColumns) {
+    s += `[#${toSentenceCase(ref.sections[0])}]`;
+  }
+  // single column
+  else if (!numSections && numColumns === 1) {
+    s += `[${quoteColname(ref.columns[0])}]`;
+  }
+  else {
+    s += '[';
+    // single [#this row] sections get normalized to an @
+    const singleAt = numSections === 1 && ref.sections[0].toLowerCase() === 'this row';
+    if (singleAt) {
+      s += '@';
+    }
+    else if (numSections) {
+      s += ref.sections
+        .map(d => `[#${toSentenceCase(d)}]`)
+        .join(',');
+      if (numColumns) {
+        s += ',';
+      }
+    }
+    // a case of a single alphanumberic column with a [#this row] becomes [@col]
+    if (singleAt && ref.columns.length === 1 && !needsBraces(ref.columns[0])) {
+      s += quoteColname(ref.columns[0]);
+    }
+    else if (numColumns) {
+      s += ref.columns.slice(0, 2)
+        .map(d => (`[${quoteColname(d)}]`))
+        .join(':');
+    }
+    s += ']';
+  }
+  return s;
+}

package/lib/sr.spec.js

@@ -0,0 +1,179 @@
+/* eslint-disable object-property-newline, object-curly-newline */
+import { test, Test } from 'tape';
+import { parseStructRef, stringifyStructRef } from './sr.js';
+
+Test.prototype.isSREqual = function isSREqual (expr, expect, opts) {
+  if (expect) {
+    expect = {
+      context: [],
+      table: '',
+      columns: [],
+      sections: [],
+      ...expect
+    };
+  }
+  this.deepEqual(parseStructRef(expr, opts), expect, expr);
+};
+
+test('parse structured references', t => {
+  t.isSREqual('table[col]', {
+    table: 'table',
+    columns: [ 'col' ]
+  });
+
+  t.isSREqual('[#All]', {
+    sections: [ 'all' ]
+  });
+
+  t.isSREqual('[column name]', {
+    columns: [ 'column name' ]
+  });
+
+  t.isSREqual('[column name]!foo', null);
+  t.isSREqual('[foo]bar', null);
+
+  t.isSREqual('[[my column]]', {
+    columns: [ 'my column' ]
+  });
+
+  t.isSREqual('[ [my column]:otherColumn ]', {
+    columns: [ 'my column', 'otherColumn' ]
+  });
+
+  t.isSREqual('[ @[my column]:otherColumn ]', {
+    columns: [ 'my column', 'otherColumn' ],
+    sections: [ 'this row' ]
+  });
+
+  t.isSREqual('[ [#Data], [my column]:otherColumn ]', {
+    columns: [ 'my column', 'otherColumn' ],
+    sections: [ 'data' ]
+  });
+
+  t.isSREqual('[ [#Data], [my column]:[\'@foo] ]', {
+    columns: [ 'my column', '@foo' ],
+    sections: [ 'data' ]
+  });
+
+  t.isSREqual('workbook.xlsx!tableName[ [#Data], [my column]:[\'@foo] ]', {
+    columns: [ 'my column', '@foo' ],
+    sections: [ 'data' ],
+    table: 'tableName',
+    context: [ 'workbook.xlsx' ]
+  });
+
+  t.isSREqual('[[#Data],[#data],[#Data],[#Data],[#Totals],[#Totals],[#Totals],foo]', {
+    columns: [ 'foo' ],
+    sections: [ 'data', 'totals' ]
+  });
+
+  t.end();
+});
+
+test('serialize structured references', t => {
+  t.is(
+    stringifyStructRef({
+      columns: [ 'foo' ]
+    }),
+    '[foo]',
+    '[foo]'
+  );
+
+  t.is(
+    stringifyStructRef({
+      columns: [ 'foo' ],
+      table: 'tableName'
+    }),
+    'tableName[foo]',
+    'tableName[foo]'
+  );
+
+  t.is(
+    stringifyStructRef({
+      columns: [ 'lorem ipsum' ],
+      table: 'tableName'
+    }),
+    'tableName[lorem ipsum]',
+    'tableName[lorem ipsum]'
+  );
+
+  t.is(
+    stringifyStructRef({
+      columns: [ 'foo', 'sævör' ],
+      table: 'tableName'
+    }),
+    'tableName[[foo]:[sævör]]',
+    'tableName[[foo]:[sævör]]'
+  );
+
+  t.is(
+    stringifyStructRef({
+      sections: [ 'data' ],
+      table: 'tableName'
+    }),
+    'tableName[#Data]',
+    'tableName[#Data]'
+  );
+
+  t.is(
+    stringifyStructRef({
+      columns: [ 'lorem ipsum', 'sævör' ],
+      table: 'tableName'
+    }),
+    'tableName[[lorem ipsum]:[sævör]]',
+    'tableName[[lorem ipsum]:[sævör]]'
+  );
+
+  t.is(
+    stringifyStructRef({
+      columns: [ 'my column', 'fo@o' ],
+      sections: [ 'data' ],
+      table: 'tableName',
+      context: [ 'workbook.xlsx' ]
+    }),
+    'workbook.xlsx!tableName[[#Data],[my column]:[fo\'@o]]',
+    'workbook.xlsx!tableName[[#Data],[my column]:[fo\'@o]]'
+  );
+
+  t.is(
+    stringifyStructRef({
+      columns: [ 'bar' ],
+      sections: [ 'this row' ],
+      table: 'foo'
+    }),
+    'foo[@bar]',
+    'foo[@bar]'
+  );
+
+  t.is(
+    stringifyStructRef({
+      columns: [ 'bar', 'baz' ],
+      sections: [ 'this row' ],
+      table: 'foo'
+    }),
+    'foo[@[bar]:[baz]]',
+    'foo[@[bar]:[baz]]'
+  );
+
+  t.is(
+    stringifyStructRef({
+      columns: [ 'lorem ipsum', 'baz' ],
+      sections: [ 'this row' ],
+      table: 'foo'
+    }),
+    'foo[@[lorem ipsum]:[baz]]',
+    'foo[@[lorem ipsum]:[baz]]'
+  );
+
+  t.is(
+    stringifyStructRef({
+      sections: [ 'data', 'headers' ],
+      table: 'table'
+    }),
+    'table[[#Data],[#Headers]]',
+    'table[[#Data],[#Headers]]'
+  );
+
+  t.end();
+});
+