@borgar/fx 4.1.0 → 4.3.0

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.1.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": {