@borgar/fx 3.1.0 → 4.0.0-rc.2

package/lib/translate-toA1.spec.js

@@ -1,8 +1,8 @@
 import { test, Test } from 'tape';
 import { translateToA1 } from './translate.js';
 import { tokenize } from './lexer.js';
-import { addMeta } from './addMeta.js';
-import { FUNCTION, FX_PREFIX, OPERATOR, RANGE, RANGE_BEAM } from './constants.js';
+import { addTokenMeta } from './addTokenMeta.js';
+import { ERROR, FUNCTION, FX_PREFIX, OPERATOR, REF_RANGE, REF_BEAM } from './constants.js';
 
 Test.prototype.isR2A = function isTokens (expr, anchor, result) {
   this.is(translateToA1(expr, anchor), result, expr);
@@ -109,6 +109,24 @@ test('translate out of bounds coords from RC to A1', t => {
   t.isR2A('=R[-2]', 'A1', '=1048575:1048575');
   t.isR2A('=R[1048575]C', 'A2', '=A1');
   t.isR2A('=R[1048575]C', 'A3', '=A2');
+
+  const f1 = '=R[-1]C[-1]';
+  t.is(translateToA1(f1, 'A1', { wrapEdges: false }), '=#REF!', f1);
+
+  const tokens = addTokenMeta(tokenize('SUM(Sheet1!R[-1]C[-1])', { r1c1: true, withLocation: true }));
+  t.deepEqual(translateToA1(tokens, 'A1', { wrapEdges: false }), [
+    { type: FUNCTION, value: 'SUM', loc: [ 0, 3 ], index: 0, depth: 0 },
+    { type: OPERATOR, value: '(', loc: [ 3, 4 ], index: 1, depth: 1, groupId: 'fxg1' },
+    { type: ERROR, value: '#REF!', loc: [ 4, 9 ], index: 2, depth: 1 },
+    { type: OPERATOR, value: ')', loc: [ 9, 10 ], index: 3, depth: 1, groupId: 'fxg1' }
+  ], 'tokens with meta');
+
+  const f2 = '=Sheet4!R[-2]C[-2]:R[-1]C[-1]';
+  t.is(translateToA1(f2, 'B2', { wrapEdges: false }), '=#REF!', f2);
+
+  const f3 = '=Sheet4!R[-2]C[-2]:R[-1]C[-1]';
+  t.is(translateToA1(f3, 'B2', { wrapEdges: false, mergeRefs: false }), '=Sheet4!#REF!:A1', f3);
+
   t.end();
 });
 
@@ -133,26 +151,26 @@ test('translate works with merged ranges', t => {
   // - 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 addMeta are preserved
+  // - Properties added by addTokenMeta are preserved
   const expr = '=SUM(IF(RC[1],R2C5,R3C5),Sheet1!R2*Sheet2!C[-2])';
-  const tokens = addMeta(tokenize(expr, { emitRanges: true, r1c1: true }));
+  const tokens = addTokenMeta(tokenize(expr, { withLocation: true, r1c1: true }));
   const expected = [
-    { type: FX_PREFIX, value: '=', range: [ 0, 1 ], index: 0, depth: 0 },
-    { type: FUNCTION, value: 'SUM', range: [ 1, 4 ], index: 1, depth: 0 },
-    { type: OPERATOR, value: '(', range: [ 4, 5 ], index: 2, depth: 1, groupId: 'fxg3' },
-    { type: FUNCTION, value: 'IF', range: [ 5, 7 ], index: 3, depth: 1 },
-    { type: OPERATOR, value: '(', range: [ 7, 8 ], index: 4, depth: 2, groupId: 'fxg1' },
-    { type: RANGE, value: 'E10', range: [ 8, 11 ], index: 5, depth: 2 },
-    { type: OPERATOR, value: ',', range: [ 11, 12 ], index: 6, depth: 2 },
-    { type: RANGE, value: '$E$2', range: [ 12, 16 ], index: 7, depth: 2 },
-    { type: OPERATOR, value: ',', range: [ 16, 17 ], index: 8, depth: 2 },
-    { type: RANGE, value: '$E$3', range: [ 17, 21 ], index: 9, depth: 2 },
-    { type: OPERATOR, value: ')', range: [ 21, 22 ], index: 10, depth: 2, groupId: 'fxg1' },
-    { type: OPERATOR, value: ',', range: [ 22, 23 ], index: 11, depth: 1 },
-    { type: RANGE_BEAM, value: 'Sheet1!$2:$2', range: [ 23, 35 ], index: 12, depth: 1, groupId: 'fxg2' },
-    { type: OPERATOR, value: '*', range: [ 35, 36 ], index: 13, depth: 1 },
-    { type: RANGE_BEAM, value: 'Sheet2!B:B', range: [ 36, 46 ], index: 14, depth: 1 },
-    { type: OPERATOR, value: ')', range: [ 46, 47 ], index: 15, depth: 1, groupId: 'fxg3' }
+    { 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: 'fxg3' },
+    { type: FUNCTION, value: 'IF', loc: [ 5, 7 ], index: 3, depth: 1 },
+    { type: OPERATOR, value: '(', loc: [ 7, 8 ], index: 4, depth: 2, groupId: 'fxg1' },
+    { type: REF_RANGE, value: 'E10', loc: [ 8, 11 ], index: 5, depth: 2 },
+    { type: OPERATOR, value: ',', loc: [ 11, 12 ], index: 6, depth: 2 },
+    { type: REF_RANGE, value: '$E$2', loc: [ 12, 16 ], index: 7, depth: 2 },
+    { type: OPERATOR, value: ',', loc: [ 16, 17 ], index: 8, depth: 2 },
+    { type: REF_RANGE, value: '$E$3', loc: [ 17, 21 ], index: 9, depth: 2 },
+    { type: OPERATOR, value: ')', loc: [ 21, 22 ], index: 10, depth: 2, groupId: 'fxg1' },
+    { type: OPERATOR, value: ',', loc: [ 22, 23 ], index: 11, depth: 1 },
+    { type: REF_BEAM, value: 'Sheet1!$2:$2', loc: [ 23, 35 ], index: 12, depth: 1, groupId: 'fxg2' },
+    { type: OPERATOR, value: '*', loc: [ 35, 36 ], index: 13, depth: 1 },
+    { type: REF_BEAM, value: 'Sheet2!B:B', loc: [ 36, 46 ], index: 14, depth: 1 },
+    { type: OPERATOR, value: ')', loc: [ 46, 47 ], index: 15, depth: 1, groupId: 'fxg3' }
   ];
   t.deepEqual(translateToA1(tokens, 'D10'), expected, expr);
   t.end();

package/lib/translate-toRC.spec.js

@@ -1,11 +1,11 @@
 import { test, Test } from 'tape';
-import { translateToRC } from './translate.js';
+import { translateToR1C1 } from './translate.js';
 import { tokenize } from './lexer.js';
-import { addMeta } from './addMeta.js';
-import { FUNCTION, FX_PREFIX, OPERATOR, RANGE, RANGE_BEAM } from './constants.js';
+import { addTokenMeta } from './addTokenMeta.js';
+import { FUNCTION, FX_PREFIX, OPERATOR, REF_RANGE, REF_BEAM } from './constants.js';
 
 Test.prototype.isA2R = function isTokens (expr, anchor, result) {
-  this.is(translateToRC(expr, anchor), result, expr);
+  this.is(translateToR1C1(expr, anchor), result, expr);
 };
 
 test('translate absolute cells from A1 to RC', t => {
@@ -126,27 +126,27 @@ test('translate works with merged ranges', t => {
   // - 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 addMeta are preserved
+  // - Properties added by addTokenMeta are preserved
   const expr = '=SUM(IF(E10,$E$2,$E$3),Sheet1!$2:$2*Sheet2!B:B)';
-  const tokens = addMeta(tokenize(expr, { emitRanges: true }));
+  const tokens = addTokenMeta(tokenize(expr, { withLocation: true }));
   const expected = [
-    { type: FX_PREFIX, value: '=', range: [ 0, 1 ], index: 0, depth: 0 },
-    { type: FUNCTION, value: 'SUM', range: [ 1, 4 ], index: 1, depth: 0 },
-    { type: OPERATOR, value: '(', range: [ 4, 5 ], index: 2, depth: 1, groupId: 'fxg7' },
-    { type: FUNCTION, value: 'IF', range: [ 5, 7 ], index: 3, depth: 1 },
-    { type: OPERATOR, value: '(', range: [ 7, 8 ], index: 4, depth: 2, groupId: 'fxg4' },
-    { type: RANGE, value: 'RC[1]', range: [ 8, 13 ], index: 5, depth: 2, groupId: 'fxg1' },
-    { type: OPERATOR, value: ',', range: [ 13, 14 ], index: 6, depth: 2 },
-    { type: RANGE, value: 'R2C5', range: [ 14, 18 ], index: 7, depth: 2, groupId: 'fxg2' },
-    { type: OPERATOR, value: ',', range: [ 18, 19 ], index: 8, depth: 2 },
-    { type: RANGE, value: 'R3C5', range: [ 19, 23 ], index: 9, depth: 2, groupId: 'fxg3' },
-    { type: OPERATOR, value: ')', range: [ 23, 24 ], index: 10, depth: 2, groupId: 'fxg4' },
-    { type: OPERATOR, value: ',', range: [ 24, 25 ], index: 11, depth: 1 },
-    { type: RANGE_BEAM, value: 'Sheet1!R2', range: [ 25, 34 ], index: 12, depth: 1, groupId: 'fxg5' },
-    { type: OPERATOR, value: '*', range: [ 34, 35 ], index: 13, depth: 1 },
-    { type: RANGE_BEAM, value: 'Sheet2!C[-2]', range: [ 35, 47 ], index: 14, depth: 1, groupId: 'fxg6' },
-    { type: OPERATOR, value: ')', range: [ 47, 48 ], index: 15, depth: 1, groupId: 'fxg7' }
+    { 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' }
   ];
-  t.deepEqual(translateToRC(tokens, 'D10'), expected, expr);
+  t.deepEqual(translateToR1C1(tokens, 'D10'), expected, expr);
   t.end();
 });

package/lib/translate.js

@@ -1,6 +1,6 @@
-import { MAX_ROWS, MAX_COLS } from './constants.js';
+import { MAX_ROWS, MAX_COLS, ERROR } from './constants.js';
 import { fromA1, parseA1Ref, stringifyA1Ref } from './a1.js';
-import { parseRCRef, stringifyRCRef } from './rc.js';
+import { parseR1C1Ref, stringifyR1C1Ref } from './rc.js';
 import { tokenize } from './lexer.js';
 import { isRange } from './isType.js';
 
@@ -12,13 +12,30 @@ const calc = (abs, vX, aX) => {
 };
 
 const settings = {
-  emitRanges: false,
-  mergeRanges: false,
+  withLocation: false,
+  mergeRefs: false,
   allowTernary: true,
   r1c1: false
 };
 
-export function translateToRC (fx, anchorCell) {
+/**
+ * Translates ranges in a formula or list of tokens from absolute A1 syntax to
+ * 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`).
+ *
+ * ```js
+ * translateToR1C1("=SUM(E10,$E$2,Sheet!$E$3)", "D10");
+ * // => "=SUM(RC[1],R2C5,Sheet!R3C5)");
+ * ```
+ *
+ * @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`).
+ * @return {(string | Array<Object>)} A formula string or token list (depending on which was input)
+ */
+export function translateToR1C1 (fx, anchorCell) {
   const { top, left } = fromA1(anchorCell);
   const isString = typeof fx === 'string';
 
@@ -42,17 +59,17 @@ export function translateToRC (fx, anchorCell) {
       range.$c0 = d.$left;
       range.$c1 = d.$right;
       ref.range = range;
-      token.value = stringifyRCRef(ref);
+      token.value = stringifyR1C1Ref(ref);
       // if token includes offsets, those offsets are now likely wrong!
-      if (token.range) {
-        token.range[0] += offsetSkew;
+      if (token.loc) {
+        token.loc[0] += offsetSkew;
         offsetSkew += token.value.length - tokenValue.length;
-        token.range[1] += offsetSkew;
+        token.loc[1] += offsetSkew;
       }
     }
-    else if (offsetSkew && token.range) {
-      token.range[0] += offsetSkew;
-      token.range[1] += offsetSkew;
+    else if (offsetSkew && token.loc) {
+      token.loc[0] += offsetSkew;
+      token.loc[1] += offsetSkew;
     }
   });
 
@@ -61,7 +78,7 @@ export function translateToRC (fx, anchorCell) {
     : tokens;
 }
 
-function toFixed (val, abs, base, max) {
+function toFixed (val, abs, base, max, wrapEdges = true) {
   let v = val;
   if (v != null && !abs) {
     v = base + val;
@@ -70,33 +87,89 @@ function toFixed (val, abs, base, max) {
     // 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;
 }
 
-export function translateToA1 (fx, anchorCell) {
+const defaultOptions = {
+  wrapEdges: true,
+  mergeRefs: true
+};
+
+/**
+ * Translates ranges in a formula or list of tokens from relative R1C1 syntax to
+ * 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`).
+ *
+ * ```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.
+ *
+ * @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.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`).
+ * @return {(string | Array<Object>)} A formula string or token list (depending on which was input)
+ */
+export function translateToA1 (formula, anchorCell, options = defaultOptions) {
   const anchor = fromA1(anchorCell);
-  const isString = typeof fx === 'string';
+  const isString = typeof formula === 'string';
+  const opts = { ...defaultOptions, ...options };
 
   const tokens = isString
-    ? tokenize(fx, { emitRanges: false, mergeRanges: false, allowTernary: true, r1c1: true })
-    : fx;
+    ? tokenize(formula, {
+      withLocation: false,
+      mergeRefs: opts.mergeRefs,
+      allowTernary: true,
+      r1c1: true
+    })
+    : formula;
 
   let offsetSkew = 0;
   tokens.forEach(token => {
     if (isRange(token)) {
       const tokenValue = token.value;
-      const ref = parseRCRef(tokenValue, { allowTernary: true });
+      const ref = parseR1C1Ref(tokenValue, { allowTernary: true });
       const d = ref.range;
       const range = {};
-      const r0 = toFixed(d.r0, d.$r0, anchor.top, MAX_ROWS);
-      const r1 = toFixed(d.r1, d.$r1, anchor.top, MAX_ROWS);
+      const r0 = toFixed(d.r0, d.$r0, anchor.top, MAX_ROWS, opts.wrapEdges);
+      const r1 = toFixed(d.r1, d.$r1, anchor.top, MAX_ROWS, opts.wrapEdges);
       if (r0 > r1) {
         range.top = r1;
         range.$top = d.$r1;
@@ -109,8 +182,8 @@ export function translateToA1 (fx, anchorCell) {
         range.bottom = r1;
         range.$bottom = d.$r1;
       }
-      const c0 = toFixed(d.c0, d.$c0, anchor.left, MAX_COLS);
-      const c1 = toFixed(d.c1, d.$c1, anchor.left, MAX_COLS);
+      const c0 = toFixed(d.c0, d.$c0, anchor.left, MAX_COLS, opts.wrapEdges);
+      const c1 = toFixed(d.c1, d.$c1, anchor.left, MAX_COLS, opts.wrapEdges);
       if (c0 > c1) {
         range.left = c1;
         range.$left = d.$c1;
@@ -123,18 +196,26 @@ export function translateToA1 (fx, anchorCell) {
         range.right = c1;
         range.$right = d.$c1;
       }
-      ref.range = range;
-      token.value = stringifyA1Ref(ref);
+      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;
+        token.value = stringifyA1Ref(ref);
+      }
       // if token includes offsets, those offsets are now likely wrong!
-      if (token.range) {
-        token.range[0] += offsetSkew;
+      if (token.loc) {
+        token.loc[0] += offsetSkew;
         offsetSkew += token.value.length - tokenValue.length;
-        token.range[1] += offsetSkew;
+        token.loc[1] += offsetSkew;
       }
     }
-    else if (offsetSkew && token.range) {
-      token.range[0] += offsetSkew;
-      token.range[1] += offsetSkew;
+    else if (offsetSkew && token.loc) {
+      token.loc[0] += offsetSkew;
+      token.loc[1] += offsetSkew;
     }
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@borgar/fx",
-  "version": "3.1.0",
+  "version": "4.0.0-rc.2",
   "description": "Utilities for working with Excel formulas",
   "main": "dist/fx.js",
   "module": "lib/index.js",
@@ -15,6 +15,7 @@
     "version": "npm run build",
     "lint": "eslint lib/*.js",
     "test": "tape lib/*.spec.js | tap-min",
+    "build:docs": "echo '# @borgar/fx API\n'>docs/API.md; jsdoc -c .jsdoc/config.json -d console lib>>docs/API.md",
     "build": "NODE_ENV=production rollup -c"
   },
   "repository": {
@@ -45,6 +46,7 @@
     "@rollup/plugin-babel": "~6.0.3",
     "babel-eslint": "~10.1.0",
     "eslint": "~8.34.0",
+    "jsdoc": "~4.0.2",
     "rollup": "~3.17.2",
     "rollup-plugin-minification": "~0.2.0",
     "tap-min": "~2.0.0",

package/References.md

@@ -1,39 +0,0 @@
-# References and Ranges
-
-In Excels spreadsheet formula language terminology, a reference is similar to what is in most programming is called a variable. Spreadsheets do not have variables though, they have cells. The cells can be referenced in formulas, either directly (such as `=SUM(A1)`), or through aliases (such as `=SUM(someName)`).
-
-A range is when a cell, or a set of cells, is referenced directly. Ranges in formulas can come in one of two syntax styles: The commonly known A1 style, as well as R1C1 style where both axes are numerical. Only one style can be used at a time in a formula.
-
-This tokenizer considers there to be three "types" of ranges:
-
-## Ranges (`RANGE`)
-
-The basic type of range will be referencing either:
-
-* A single cell, like `A1` or `AF31`.
-* A bounded rectangle of cells, like `A1:B2` or `AF17:AF31`.
-
-
-## Range ternary (`RANGE_TERNARY`)
-
-Ternary ranges are rectangles of cells defined by only three of the four possible sides. They are are unbounded in either bottom or right dimension:
-
-* A rectangle of cells that is unbounded to the bottom, like `A1:A` or `C3:D`.
-* A rectangle of cells that is unbounded to the right, like `A1:1` or `F2:5`.
-
-This type of range is not supported in Excel, so it is an opt-in for the tokenizer (see README.md).
-
-
-## Range beams (`RANGE_BEAM`)
-
-Range beams are rectangles of cells that are unbounded in either left and right, or top and bottom dimensions.
-
-* A rectangle of cells that is unbounded to the top and bottom, like `A:A` or `C:D`.
-* A rectangle of cells that is unbounded to the left and right, like `1:1` or `2:5`.
-
----
-
-Spreadsheet applications will normalize all of these types when you enter a formula, flipping the left/right and top/bottom coordinates as needed to keep the range top to bottom and left to right.
-
-The library has tools to both normalize the ranges, as well as filling in the missing boundaries  (see README.md).
-