@borgar/fx 3.0.0 → 4.0.0-rc.1

package/lib/fixRanges.js

@@ -1,12 +1,45 @@
 import { isRange } from './isType.js';
-import { parseA1Ref, stringifyA1Ref, addRangeBounds } from './a1.js';
+import { parseA1Ref, stringifyA1Ref, addA1RangeBounds } from './a1.js';
+import { parseStructRef, stringifyStructRef } from './sr.js';
 import { tokenize } from './lexer.js';
+import { REF_STRUCT } from './constants.js';
 
 // There is no R1C1 counerpart to this. This is because without an anchor cell
 // it is impossible to determine if a relative+absolute range (R[1]C[1]:R5C5)
 // needs to be flipped or not. The solution is to convert to A1 first:
 // translateToRC(fixRanges(translateToA1(...)))
 
+/**
+ * Normalizes A1 style ranges in a formula or list of tokens so that the top and
+ * left coordinates of the range are on the left-hand side of a colon operator:
+ *
+ * `B2:A1` → `A1:B2`  
+ * `1:A1` → `A1:1`  
+ * `A:A1` → `A1:A`  
+ * `B:A` → `A:B`  
+ * `2:1` → `1:2`  
+ * `A1:A1` → `A1`  
+ *
+ * When `{ addBounds: true }` is passed as an option, the missing bounds are
+ * also added. This can be done to ensure Excel compatible ranges. The fixes
+ * then additionally include:
+ *
+ * `1:A1` → `A1:1` → `1:1`  
+ * `A:A1` → `A1:A` → `A:A`  
+ * `A1:A` → `A:A`  
+ * `A1:1` → `A:1`  
+ * `B2:B` → `B2:1048576`  
+ * `B2:2` → `B2:XFD2`  
+ *
+ * Returns the same formula with the ranges updated. If an array of tokens was
+ * supplied, then a new array is returned.
+ *
+ * @param {(string | Array<Object>)} formula A string (an Excel formula) or a token list that should be adjusted.
+ * @param {Object} [options={}]  Options
+ * @param {boolean} [options.addBounds=false]  Fill in any undefined bounds of range objects. Top to 0, bottom to 1048575, left to 0, and right to 16383.
+ * @param {boolean} [options.r1c1=false]  Ranges are expected to be in the R1C1 style format rather than the more popular A1 style.
+ * @return {(string | Array<Object>)} A formula string or token list (depending on which was input)
+ */
 export function fixRanges (tokens, options = { addBounds: false }) {
   if (typeof tokens === 'string') {
     return fixRanges(tokenize(tokens, options), options)
@@ -20,20 +53,41 @@ export function fixRanges (tokens, options = { addBounds: false }) {
   if (r1c1) {
     throw new Error('fixRanges does not have an R1C1 mode');
   }
-  return tokens.map(token => {
-    if (isRange(token)) {
-      const ref = parseA1Ref(token.value, options);
+  let offsetSkew = 0;
+  return tokens.map(t => {
+    const token = { ...t };
+    if (t.loc) {
+      token.loc = [ ...t.loc ];
+    }
+    let offsetDelta = 0;
+    if (token.type === REF_STRUCT) {
+      const newValue = stringifyStructRef(parseStructRef(token.value));
+      offsetDelta = newValue.length - token.value.length;
+      token.value = newValue;
+    }
+    else if (isRange(token)) {
+      const ref = parseA1Ref(token.value, { allowTernary: true });
       const range = ref.range;
       // fill missing dimensions?
       if (addBounds) {
-        addRangeBounds(range);
+        addA1RangeBounds(range);
       }
-      const ret = { ...token };
-      ret.value = stringifyA1Ref(ref);
-      if (ret.range) {
-        ret.range = range;
+      const newValue = stringifyA1Ref(ref);
+      offsetDelta = newValue.length - token.value.length;
+      token.value = newValue;
+    }
+    // ensure that positioning is still correct
+    if (offsetSkew || offsetDelta) {
+      if (token.loc) {
+        token.loc[0] += offsetSkew;
       }
-      return ret;
+      offsetSkew += offsetDelta;
+      if (token.loc) {
+        token.loc[1] += offsetSkew;
+      }
+    }
+    else {
+      offsetSkew += offsetDelta;
     }
     return token;
   });

package/lib/fixRanges.spec.js

@@ -1,8 +1,8 @@
 import { test, Test } from 'tape';
 import { tokenize } from './lexer.js';
-import { addMeta } from './addMeta.js';
+import { addTokenMeta } from './addTokenMeta.js';
 import { fixRanges } from './fixRanges.js';
-import { RANGE } from './constants.js';
+import { FUNCTION, FX_PREFIX, OPERATOR, REF_RANGE, REF_STRUCT, REF_TERNARY } from './constants.js';
 
 Test.prototype.isFixed = function (expr, expected, options = {}) {
   const result = fixRanges(expr, options);
@@ -13,13 +13,13 @@ test('fixRanges basics', t => {
   const fx = '=SUM([wb]Sheet1!B2:A1)';
   t.throws(() => fixRanges(123), 'throws on non arrays (number)');
   t.throws(() => fixRanges(null), 'throws on non arrays (null)');
-  const tokens = addMeta(tokenize(fx, { mergeRanges: true }));
+  const tokens = addTokenMeta(tokenize(fx, { mergeRefs: true }));
   tokens[3].foo = 'bar';
   const fixedTokens = fixRanges(tokens, { debug: 0 });
   t.ok(tokens !== fixedTokens, 'emits a new array instance');
   t.ok(tokens[3] !== fixedTokens[3], 'does not mutate existing range tokens');
   t.deepEqual(tokens[3], {
-    type: RANGE,
+    type: REF_RANGE,
     value: '[wb]Sheet1!B2:A1',
     index: 3,
     depth: 1,
@@ -27,14 +27,26 @@ test('fixRanges basics', t => {
     foo: 'bar'
   }, 'keeps meta (pre-fix range token)');
   t.deepEqual(fixedTokens[3], {
-    type: RANGE,
+    type: REF_RANGE,
     value: '[wb]Sheet1!A1:B2',
     index: 3,
     depth: 1,
     groupId: 'fxg1',
     foo: 'bar'
   }, 'keeps meta (post-fix range token)');
-  // fixes all range meta
+  const tokensWithRanges = tokenize(
+    '=SUM(B2:A,table[[#This Row],[Foo]])',
+    { withLocation: true, mergeRefs: true, allowTernary: true }
+  );
+  t.deepEqual(fixRanges(tokensWithRanges, { addBounds: true }), [
+    { type: FX_PREFIX, value: '=', loc: [ 0, 1 ] },
+    { type: FUNCTION, value: 'SUM', loc: [ 1, 4 ] },
+    { type: OPERATOR, value: '(', loc: [ 4, 5 ] },
+    { type: REF_TERNARY, value: 'A2:B1048576', loc: [ 5, 16 ] },
+    { type: OPERATOR, value: ',', loc: [ 16, 17 ] },
+    { type: REF_STRUCT, value: 'table[@Foo]', loc: [ 17, 28 ] },
+    { type: OPERATOR, value: ')', loc: [ 28, 29 ] }
+  ], 'updates token source location information');
   t.end();
 });
 
@@ -109,3 +121,20 @@ test('fixRanges A1 addBounds', t => {
   t.isFixed('=2:B20', '=B2:XFD20', opt);
   t.end();
 });
+
+test('fixRanges structured references', t => {
+  t.isFixed('=Table1[[#This Row],[Foo]]', '=Table1[@Foo]');
+  t.isFixed('=[[#This Row],[s:s]]', '=[@[s:s]]');
+  t.isFixed('=Table1[[#Totals],col name:Foo]', '=Table1[[#Totals],[col name]:[Foo]]');
+  t.isFixed('[[#data],[#headers]]', '[[#Headers],[#Data]]');
+  t.isFixed('[[#headers],[#data]]', '[[#Headers],[#Data]]');
+  t.isFixed('[[#totals],[#data]]', '[[#Data],[#Totals]]');
+  t.isFixed('[ [#totals], [#data] ]', '[[#Data],[#Totals]]');
+  t.isFixed('[[#data],[#totals]]', '[[#Data],[#Totals]]');
+  t.isFixed('[[#all],foo:bar]', '[[#All],[foo]:[bar]]');
+  t.isFixed('[[#all],[#all],[#all],[#all],[ColumnName]]', '[[#All],[ColumnName]]');
+  t.isFixed('[@[foo]:bar]', '[@[foo]:[bar]]');
+  t.isFixed('[@foo bar]', '[@[foo bar]]');
+  t.isFixed('[ @foo bar ]', '[@[foo bar]]');
+  t.end();
+});

package/lib/index.js

@@ -1,14 +1,32 @@
 export { tokenize } from './lexer.js';
-export { addMeta } from './addMeta.js';
-export { translateToRC, translateToA1 } from './translate.js';
-export { default as a1 } from './a1.js';
-export { default as rc } from './rc.js';
+export { parse } from './parser.js';
+export { addTokenMeta } from './addTokenMeta.js';
+export { translateToR1C1, translateToA1 } from './translate.js';
 export { MAX_COLS, MAX_ROWS } from './constants.js';
 export { isReference, isRange } from './isType.js';
-export { mergeRefTokens as mergeRanges } from './mergeRefTokens.js';
+export { mergeRefTokens } from './mergeRefTokens.js';
 export { fixRanges } from './fixRanges.js';
 
+export {
+  fromCol,
+  toCol,
+  parseA1Ref,
+  stringifyA1Ref,
+  addA1RangeBounds
+} from './a1.js';
+
+export {
+  parseR1C1Ref,
+  stringifyR1C1Ref
+} from './rc.js';
+
+export {
+  parseStructRef,
+  stringifyStructRef
+} from './sr.js';
+
 import {
+  // token types
   OPERATOR,
   BOOLEAN,
   ERROR,
@@ -19,15 +37,49 @@ import {
   STRING,
   CONTEXT,
   CONTEXT_QUOTE,
-  RANGE,
-  RANGE_BEAM,
-  RANGE_TERNARY,
-  RANGE_NAMED,
+  REF_RANGE,
+  REF_BEAM,
+  REF_TERNARY,
+  REF_NAMED,
+  REF_STRUCT,
   FX_PREFIX,
-  UNKNOWN
+  UNKNOWN,
+  // AST types
+  UNARY,
+  BINARY,
+  REFERENCE,
+  LITERAL,
+  ERROR_LITERAL,
+  CALL,
+  ARRAY,
+  IDENTIFIER
 } from './constants.js';
 
-export const tokenTypes = {
+/**
+ * A dictionary of the types used to identify token variants.
+ *
+ * @readonly
+ * @constant {Object<string>} tokenTypes
+ * @property {string} OPERATOR - Newline (`\n`)
+ * @property {string} BOOLEAN - Boolean literal (`TRUE`)
+ * @property {string} ERROR - Error literal (`#VALUE!`)
+ * @property {string} NUMBER - Number literal (`123.4`, `-1.5e+2`)
+ * @property {string} FUNCTION - Function name (`SUM`)
+ * @property {string} NEWLINE - Newline character (`\n`)
+ * @property {string} WHITESPACE - Whitespace character sequence (` `)
+ * @property {string} STRING - String literal (`"Lorem ipsum"`)
+ * @property {string} CONTEXT - Reference context ([Workbook.xlsx]Sheet1)
+ * @property {string} CONTEXT_QUOTE - Quoted reference context (`'[My workbook.xlsx]Sheet1'`)
+ * @property {string} REF_RANGE - A range identifier (`A1`)
+ * @property {string} REF_BEAM - A range "beam" identifier (`A:A` or `1:1`)
+ * @property {string} REF_TERNARY - A ternary range identifier (`B2:B`)
+ * @property {string} REF_NAMED - A name / named range identifier (`income`)
+ * @property {string} REF_STRUCT - A structured reference identifier (`table[[Column1]:[Column2]]`)
+ * @property {string} FX_PREFIX - A leading equals sign at the start of a formula (`=`)
+ * @property {string} UNKNOWN - Any unidentifiable range of characters.
+ * @see tokenize
+ */
+export const tokenTypes = Object.freeze({
   OPERATOR,
   BOOLEAN,
   ERROR,
@@ -38,10 +90,37 @@ export const tokenTypes = {
   STRING,
   CONTEXT,
   CONTEXT_QUOTE,
-  RANGE,
-  RANGE_BEAM,
-  RANGE_TERNARY,
-  RANGE_NAMED,
+  REF_RANGE,
+  REF_BEAM,
+  REF_TERNARY,
+  REF_NAMED,
+  REF_STRUCT,
   FX_PREFIX,
   UNKNOWN
-};
+});
+
+/**
+ * A dictionary of the types used to identify AST node variants.
+ *
+ * @readonly
+ * @constant {Object<string>} nodeTypes
+ * @property {string} UNARY - A unary operation (`10%`)
+ * @property {string} BINARY - A binary operation (`10+10`)
+ * @property {string} REFERENCE - A range identifier (`A1`)
+ * @property {string} LITERAL - A literal (number, string, or boolean) (`123`, `"foo"`, `false`)
+ * @property {string} ERROR - An error literal (`#VALUE!`)
+ * @property {string} CALL - A function call expression (`SUM(1,2)`)
+ * @property {string} ARRAY - An array expression (`{1,2;3,4}`)
+ * @property {string} IDENTIFIER - A function name identifier (`SUM`)
+ * @see parse
+ */
+export const nodeTypes = Object.freeze({
+  UNARY,
+  BINARY,
+  REFERENCE,
+  LITERAL,
+  ERROR: ERROR_LITERAL,
+  CALL,
+  ARRAY,
+  IDENTIFIER
+});

package/lib/isType.js

@@ -1,18 +1,129 @@
-import { RANGE, RANGE_BEAM, RANGE_NAMED, RANGE_TERNARY } from './constants.js';
+import {
+  REF_RANGE, REF_BEAM, REF_NAMED, REF_TERNARY, REF_STRUCT,
+  FX_PREFIX, WHITESPACE, NEWLINE,
+  FUNCTION, OPERATOR,
+  ERROR, STRING, NUMBER, BOOLEAN
+} from './constants.js';
 
+/**
+ * Determines whether the specified token is a range.
+ *
+ * Returns `true` if the input is a token that has a type of either REF_RANGE
+ * (`A1` or `A1:B2`), REF_TERNARY (`A1:A`, `A1:1`, `1:A1`, or `A:A1`), or
+ * REF_BEAM (`A:A` or `1:1`). In all other cases `false` is returned.
+ *
+ * @param {Object} token A token
+ * @return {boolean} True if the specified token is range, False otherwise.
+ */
 export function isRange (token) {
   return !!token && (
-    token.type === RANGE ||
-    token.type === RANGE_BEAM ||
-    token.type === RANGE_TERNARY
+    token.type === REF_RANGE ||
+    token.type === REF_BEAM ||
+    token.type === REF_TERNARY
   );
 }
 
+/**
+ * Determines whether the specified token is a reference.
+ *
+ * Returns `true` if the input is a token of type REF_RANGE (`A1` or `A1:B2`),
+ * REF_TERNARY (`A1:A`, `A1:1`, `1:A1`, or `A:A1`), REF_BEAM (`A:A` or `1:1`),
+ * or REF_NAMED (`myrange`). In all other cases `false` is returned.
+ *
+ * @param {Object} token The token
+ * @return {boolean} True if the specified token is reference, False otherwise.
+ */
 export function isReference (token) {
   return !!token && (
-    token.type === RANGE ||
-    token.type === RANGE_BEAM ||
-    token.type === RANGE_TERNARY ||
-    token.type === RANGE_NAMED
+    token.type === REF_RANGE ||
+    token.type === REF_BEAM ||
+    token.type === REF_TERNARY ||
+    token.type === REF_STRUCT ||
+    token.type === REF_NAMED
   );
 }
+
+/**
+ * Determines whether the specified token is a literal.
+ *
+ * Returns `true` if the input is a token of type BOOLEAN (`TRUE` or `FALSE`),
+ * ERROR (`#VALUE!`), NUMBER (123.4), or STRING (`"lorem ipsum"`). In all other
+ * cases `false` is returned.
+ *
+ * @param {Object} token The token
+ * @return {boolean} True if the specified token is literal, False otherwise.
+ */
+export function isLiteral (token) {
+  return !!token && (
+    token.type === BOOLEAN ||
+    token.type === ERROR ||
+    token.type === NUMBER ||
+    token.type === STRING
+  );
+}
+
+/**
+ * Determines whether the specified token is an error.
+ *
+ * Returns `true` if the input is a token of type ERROR (`#VALUE!`). In all
+ * other cases `false` is returned.
+ *
+ * @param {Object} token The token
+ * @return {boolean} True if the specified token is error, False otherwise.
+ */
+export function isError (token) {
+  return !!token && token.type === ERROR;
+}
+
+/**
+ * Determines whether the specified token is whitespace.
+ *
+ * Returns `true` if the input is a token of type WHITESPACE (` `) or
+ * NEWLINE (`\n`). In all other cases `false` is returned.
+ *
+ * @param {Object} token The token
+ * @return {boolean} True if the specified token is whitespace, False otherwise.
+ */
+export function isWhitespace (token) {
+  return !!token && (
+    token.type === WHITESPACE ||
+    token.type === NEWLINE
+  );
+}
+
+/**
+ * Determines whether the specified token is a function.
+ *
+ * Returns `true` if the input is a token of type FUNCTION.
+ * In all other cases `false` is returned.
+ *
+ * @param {Object} token The token
+ * @return {boolean} True if the specified token is function, False otherwise.
+ */
+export function isFunction (token) {
+  return !!token && token.type === FUNCTION;
+}
+
+/**
+ * Returns `true` if the input is a token of type FX_PREFIX (leading `=` in
+ * formula). In all other cases `false` is returned.
+ *
+ * @param {Object} token The token
+ * @return {boolean} True if the specified token is effects prefix, False otherwise.
+ */
+export function isFxPrefix (token) {
+  return !!token && token.type === FX_PREFIX;
+}
+
+/**
+ * Determines whether the specified token is an operator.
+ *
+ * Returns `true` if the input is a token of type OPERATOR (`+` or `:`). In all
+ * other cases `false` is returned.
+ *
+ * @param {Object} token The token
+ * @return {boolean} True if the specified token is operator, False otherwise.
+ */
+export function isOperator (token) {
+  return !!token && token.type === OPERATOR;
+}