@borgar/fx 4.2.0 → 4.3.1

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.2.0",
+  "version": "4.3.1",
   "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": {