@borgar/fx 4.13.0 → 5.0.0

package/lib/{parser.js → parse.ts}

@@ -16,7 +16,7 @@ import {
   isFxPrefix,
   isOperator,
   isError
-} from './isType.js';
+} from './isType.ts';
 import {
   UNARY,
   BINARY,
@@ -36,9 +36,10 @@ import {
   REF_NAMED,
   REF_STRUCT,
   REF_BEAM
-} from './constants.js';
+} from './constants.ts';
 
-import { tokenize } from './lexer.js';
+import type { Token } from './types.ts';
+import type { ArrayExpression, AstExpression, BinaryExpression, CallExpression, Identifier, LambdaExpression, LetDeclarator, LetExpression, UnaryExpression } from './astTypes.ts';
 
 const END = '(END)';
 const FUNCTION = '(FUNCTION)';
@@ -65,17 +66,17 @@ const refFunctions = [
 
 const symbolTable = {};
 let currentNode;
-let tokens;
-let tokenIndex;
+let tokens: Token[];
+let tokenIndex: number;
 let permitArrayRanges = false;
 let permitArrayCalls = false;
 let looseRefCalls = false;
 
-const isReferenceFunctionName = fnName => {
+const isReferenceFunctionName = (fnName: string) => {
   return looseRefCalls || refFunctions.includes(fnName.toUpperCase());
 };
 
-const isReferenceToken = (token, allowOperators = false) => {
+const isReferenceToken = (token: Token, allowOperators = false) => {
   const value = (token && token.value) + '';
   if (isReference(token)) {
     return true;
@@ -106,9 +107,11 @@ const isReferenceNode = node => {
   );
 };
 
-function halt (message, atIndex = null) {
+function halt (message: string, atIndex = null) {
   const err = new Error(message);
+  // @ts-ignore -- FIXME: use a dedicated error class
   err.source = tokens.map(d => d.value).join('');
+  // @ts-ignore
   err.sourceOffset = tokens
     .slice(0, atIndex ?? tokenIndex)
     .reduce((a, d) => a + d.value.length, 0);
@@ -116,9 +119,9 @@ function halt (message, atIndex = null) {
 }
 
 // A1 A1 | A1 (A1) | A1 ((A1)) | A1 ( (A1) ) | ...
-function refIsUpcoming (allowOperators = false) {
+function refIsUpcoming (allowOperators = false): boolean {
   let i = tokenIndex;
-  let next;
+  let next: Token;
   do {
     next = tokens[++i];
   }
@@ -193,7 +196,7 @@ function advance (expectNext = null, leftNode = null) {
   return currentNode;
 }
 
-function expression (rbp) {
+function expression (rbp: number) {
   let t = currentNode;
   advance(null, t);
   let left = t.nud();
@@ -213,7 +216,7 @@ const original_symbol = {
 };
 
 // bp = binding power
-function symbol (id, bp = 0) {
+function symbol (id: string, bp = 0) {
   let s = symbolTable[id];
   if (s) {
     if (bp >= s.lbp) {
@@ -230,10 +233,11 @@ function symbol (id, bp = 0) {
   return s;
 }
 
-function infix (id, bp, led) {
+function infix (id: string, bp: number, led?) {
   const s = symbol(id, bp);
-  s.led = led || function (left) {
+  s.led = led || function (this: BinaryExpression & { value?: string }, left) {
     this.type = BINARY;
+    // @ts-expect-error -- we know this is going to be a valid operator
     this.operator = this.value;
     delete this.value;
     const right = expression(bp);
@@ -246,11 +250,12 @@ function infix (id, bp, led) {
   return s;
 }
 
-function postfix (id, led) {
+function postfix (id: string, led?) {
   const s = symbol(id, 0);
   s.lbp = 70;
-  s.led = led || function (left) {
+  s.led = led || function (this: UnaryExpression & { value?: string }, left) {
     this.type = UNARY;
+    // @ts-expect-error -- we know this is going to be a valid operator
     this.operator = this.value;
     delete this.value;
     this.arguments = [ left ];
@@ -262,10 +267,11 @@ function postfix (id, led) {
   return s;
 }
 
-function prefix (id, nud) {
+function prefix (id, nud?) {
   const s = symbol(id);
-  s.nud = nud || function () {
+  s.nud = nud || function (this: UnaryExpression & { value?: string }) {
     this.type = UNARY;
+    // @ts-expect-error -- we know this is going to be a valid operator
     this.operator = this.value;
     delete this.value;
     const subexpr = expression(70);
@@ -279,15 +285,16 @@ function prefix (id, nud) {
 }
 
 function rangeInfix (id, bp) {
-  return infix(id, bp, function (left) {
+  return infix(id, bp, function (this: BinaryExpression & { id?: string, value?: string }, left) {
     if (!isReferenceNode(left)) {
       halt(`Unexpected ${id} operator`);
     }
     const right = expression(bp);
-    if (!isReferenceNode(right, true)) {
+    if (!isReferenceNode(right)) {
       halt(`Unexpected ${currentNode.type} following ${this.id}`);
     }
     this.type = BINARY;
+    // @ts-expect-error -- we know this is going to be a valid operator
     this.operator = this.value.trim() ? this.value : ' '; // hack around whitespace op
     delete this.value;
     this.arguments = [ left, right ];
@@ -307,7 +314,7 @@ rangeInfix(WHITESPACE, 80); // intersect: =B7:D7 C6:C8
 
 // Excel's grammar is ambiguous. This turns the , operator's left binding
 // power on/off which allows us to treat , as a symbol where we need.
-const unionRefs = enable => {
+const unionRefs = (enable?: boolean) => {
   const currState = comma.lbp > 0;
   if (enable != null) { comma.lbp = enable ? 80 : 0; }
   return currState;
@@ -315,7 +322,7 @@ const unionRefs = enable => {
 
 // arithmetic and string operations
 postfix('%'); // percent
-postfix('#', function (left) { // spilled range (_xlfn.ANCHORARRAY)
+postfix('#', function (this: Token, left) { // spilled range (_xlfn.ANCHORARRAY)
   if (!isReferenceNode(left)) {
     halt('# expects a reference');
   }
@@ -396,8 +403,8 @@ prefix('(', function () {
 symbol(FUNCTION).nud = function () {
   return this;
 };
-infix('(', 90, function (left) {
-  let callee = {
+infix('(', 90, function (this: CallExpression & { value?: string }, left) {
+  let callee: Identifier = {
     type: IDENTIFIER,
     name: left.value
   };
@@ -470,10 +477,10 @@ infix('(', 90, function (left) {
   return this;
 });
 
-function parseLambda (left) {
+function parseLambda (this: LambdaExpression & { value?: string }, left) {
   const args = [];
   const argNames = {};
-  let body;
+  let body: AstExpression | null;
   let done = false;
   const prevState = unionRefs(false);
   if (currentNode.id !== ')') {
@@ -492,7 +499,7 @@ function parseLambda (left) {
             halt('Duplicate name: ' + arg.value);
           }
           argNames[currName] = 1;
-          const a = { type: IDENTIFIER, name: arg.value };
+          const a: Identifier = { type: IDENTIFIER, name: arg.value };
           if (arg.loc) { a.loc = arg.loc; }
           args.push(a);
         }
@@ -520,13 +527,13 @@ function parseLambda (left) {
   return this;
 }
 
-function parseLet (left) {
+function parseLet (this: LetExpression & { value?: string }, left) {
   const args = [];
   const vals = [];
   const argNames = {};
-  let body;
+  let body: AstExpression | null;
   let argCounter = 0;
-  const addArgument = (arg, lastArg) => {
+  const addArgument = (arg, lastArg?) => {
     if (body) {
       halt('Unexpected argument following calculation');
     }
@@ -585,7 +592,6 @@ function parseLet (left) {
   if (lastWasComma) {
     addArgument(null, true);
   }
-  // eslint-disable-next-line no-undefined
   if (body === undefined) {
     halt('Unexpected end of arguments');
   }
@@ -597,7 +603,7 @@ function parseLet (left) {
     halt('Unexpected end of arguments');
   }
   for (let i = 0; i < args.length; i++) {
-    const s = {
+    const s: LetDeclarator = {
       type: LET_DECL,
       id: args[i],
       init: vals[i],
@@ -616,7 +622,7 @@ function parseLet (left) {
 // array literal
 symbol('}');
 symbol(';');
-prefix('{', function () {
+prefix('{', function (this: ArrayExpression & { value?: string }) {
   if (currentNode.id === '}') { // arrays must not be empty
     halt('Unexpected empty array');
   }
@@ -672,42 +678,53 @@ prefix('{', function () {
   return this;
 });
 
+/**
+ * Options for {@link parse}.
+ */
+export type OptsParse = {
+  /**
+   * Ranges are allowed as elements of arrays. This is a feature in Google Sheets while Excel
+   * does not allow it.
+   * @defaultValue false
+   */
+  permitArrayRanges?: boolean,
+  /**
+   * Function calls are allowed as elements of arrays. This is a feature in Google Sheets
+   * while Excel does not allow it.
+   * @defaultValue false
+   */
+  permitArrayCalls?: boolean,
+  /**
+   * Permits any function call where otherwise only functions that return references would
+   * be permitted.
+   * @defaultValue false
+   */
+  looseRefCalls?: boolean,
+};
+
 /**
  * Parses a string formula or list of tokens into an AST.
  *
- * The parser requires `mergeRefs` to have been `true` in tokenlist options,
- * because it does not recognize reference context tokens.
+ * The parser assumes `mergeRefs` and `negativeNumbers` were `true` when the tokens were generated.
+ * It does not yet recognize reference context tokens or know how to deal with unary minuses in
+ * arrays.
  *
  * The AST Abstract Syntax Tree's format is documented in
- * [AST_format.md](./AST_format.md)
+ * [AST_format.md](./AST_format.md).
  *
- * @see nodeTypes
- * @param {(string | Token[])} formula An Excel formula string (an Excel expression) or an array of tokens.
- * @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.
- * @param {boolean} [options.negativeNumbers=true]  Merges unary minuses with their immediately following number tokens (`-`,`1`) => `-1` (alternatively these will be unary operations in the tree).
- * @param {boolean} [options.permitArrayRanges=false]  Ranges are allowed as elements of arrays. This is a feature in Google Sheets while Excel does not allow it.
- * @param {boolean} [options.permitArrayCalls=false]  Function calls are allowed as elements of arrays. This is a feature in Google Sheets while Excel does not allow it.
- * @param {boolean} [options.looseRefCalls=false]  Permits any function call where otherwise only functions that return references would be permitted.
- * @param {boolean} [options.r1c1=false]  Ranges are expected to be in the R1C1 style format rather than the more popular A1 style.
- * @param {boolean} [options.withLocation=false]  Nodes will include source position offsets to the tokens: `{ loc: [ start, end ] }`
- * @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)
- * @returns {AstExpression} An AST of nodes
+ * @see {@link OptsParse}
+ * @see {@link nodeTypes}
+ * @see {@link tokenize}
+ * @param tokenlist An array of tokens.
+ * @param options Options for the parsers behavior.
+ * @returns An AST of nodes.
  */
-export function parse (formula, options) {
-  if (typeof formula === 'string') {
-    tokens = tokenize(formula, {
-      withLocation: false,
-      ...options,
-      mergeRefs: true
-    });
-  }
-  else if (Array.isArray(formula)) {
-    tokens = formula;
-  }
-  else {
-    throw new Error('Parse requires a string or array of tokens.');
+export function parse (
+  tokenlist: Token[],
+  options: OptsParse = {}
+): AstExpression {
+  if (!Array.isArray(tokenlist)) {
+    throw new Error('Parse requires an array of tokens.');
   }
   // allow ranges in array "literals"?
   permitArrayRanges = options?.permitArrayRanges;
@@ -715,7 +732,8 @@ export function parse (formula, options) {
   permitArrayCalls = options?.permitArrayCalls;
   // allow any function call in range operations?
   looseRefCalls = options?.looseRefCalls;
-  // set index to start
+  // assign the tokenlist and set index to start
+  tokens = tokenlist;
   tokenIndex = 0;
   // discard redundant whitespace and = prefix
   while (isWhitespace(tokens[tokenIndex]) || isFxPrefix(tokens[tokenIndex])) {

package/lib/parseA1Range.spec.ts

@@ -0,0 +1,233 @@
+/* eslint-disable @stylistic/object-property-newline */
+import { describe, test, expect } from 'vitest';
+import { fromRow, parseA1Range } from './parseA1Range.ts';
+
+describe('fromRow', () => {
+  test('fromRow converts row strings to zero-based indices', () => {
+    expect(fromRow('1')).toBe(0);
+    expect(fromRow('2')).toBe(1);
+    expect(fromRow('10')).toBe(9);
+    expect(fromRow('100')).toBe(99);
+    expect(fromRow('9999999')).toBe(9999998);
+  });
+});
+
+describe('parseA1Range', () => {
+  test('parseA1Range parses simple cell references', () => {
+    expect(parseA1Range('A1')).toEqual({
+      top: 0, left: 0, bottom: 0, right: 0,
+      $top: false, $left: false, $bottom: false, $right: false
+    });
+
+    expect(parseA1Range('B2')).toEqual({
+      top: 1, left: 1, bottom: 1, right: 1,
+      $top: false, $left: false, $bottom: false, $right: false
+    });
+
+    expect(parseA1Range('Z10')).toEqual({
+      top: 9, left: 25, bottom: 9, right: 25,
+      $top: false, $left: false, $bottom: false, $right: false
+    });
+
+    expect(parseA1Range('AA100')).toEqual({
+      top: 99, left: 26, bottom: 99, right: 26,
+      $top: false, $left: false, $bottom: false, $right: false
+    });
+  });
+});
+
+test('parseA1Range parses absolute cell references', () => {
+  expect(parseA1Range('$A$1')).toEqual({
+    top: 0, left: 0, bottom: 0, right: 0,
+    $top: true, $left: true, $bottom: true, $right: true
+  });
+
+  expect(parseA1Range('$A1')).toEqual({
+    top: 0, left: 0, bottom: 0, right: 0,
+    $top: false, $left: true, $bottom: false, $right: true
+  });
+
+  expect(parseA1Range('A$1')).toEqual({
+    top: 0, left: 0, bottom: 0, right: 0,
+    $top: true, $left: false, $bottom: true, $right: false
+  });
+});
+
+test('parseA1Range parses range references', () => {
+  expect(parseA1Range('A1:B2')).toEqual({
+    top: 0, left: 0, bottom: 1, right: 1,
+    $top: false, $left: false, $bottom: false, $right: false
+  });
+
+  expect(parseA1Range('A1:Z10')).toEqual({
+    top: 0, left: 0, bottom: 9, right: 25,
+    $top: false, $left: false, $bottom: false, $right: false
+  });
+
+  expect(parseA1Range('B2:D4')).toEqual({
+    top: 1, left: 1, bottom: 3, right: 3,
+    $top: false, $left: false, $bottom: false, $right: false
+  });
+});
+
+test('parseA1Range parses range references with mixed absolute/relative', () => {
+  expect(parseA1Range('$A$1:B2')).toEqual({
+    top: 0, left: 0, bottom: 1, right: 1,
+    $top: true, $left: true, $bottom: false, $right: false
+  });
+
+  expect(parseA1Range('A1:$B$2')).toEqual({
+    top: 0, left: 0, bottom: 1, right: 1,
+    $top: false, $left: false, $bottom: true, $right: true
+  });
+
+  expect(parseA1Range('$A1:B$2')).toEqual({
+    top: 0, left: 0, bottom: 1, right: 1,
+    $top: false, $left: true, $bottom: true, $right: false
+  });
+});
+
+test('parseA1Range normalizes reversed ranges', () => {
+  expect(parseA1Range('B2:A1')).toEqual({
+    top: 0, left: 0, bottom: 1, right: 1,
+    $top: false, $left: false, $bottom: false, $right: false
+  });
+
+  expect(parseA1Range('Z10:A1')).toEqual({
+    top: 0, left: 0, bottom: 9, right: 25,
+    $top: false, $left: false, $bottom: false, $right: false
+  });
+});
+
+test('parseA1Range parses column ranges', () => {
+  expect(parseA1Range('A:A')).toEqual({
+    top: null, left: 0, bottom: null, right: 0,
+    $top: false, $left: false, $bottom: false, $right: false
+  });
+
+  expect(parseA1Range('A:C')).toEqual({
+    top: null, left: 0, bottom: null, right: 2,
+    $top: false, $left: false, $bottom: false, $right: false
+  });
+
+  expect(parseA1Range('C:A')).toEqual({
+    top: null, left: 0, bottom: null, right: 2,
+    $top: false, $left: false, $bottom: false, $right: false
+  });
+
+  expect(parseA1Range('$A:C')).toEqual({
+    top: null, left: 0, bottom: null, right: 2,
+    $top: false, $left: true, $bottom: false, $right: false
+  });
+
+  expect(parseA1Range('A:$C')).toEqual({
+    top: null, left: 0, bottom: null, right: 2,
+    $top: false, $left: false, $bottom: false, $right: true
+  });
+});
+
+test('parseA1Range parses row ranges', () => {
+  expect(parseA1Range('1:1')).toEqual({
+    top: 0, left: null, bottom: 0, right: null,
+    $top: false, $left: false, $bottom: false, $right: false
+  });
+
+  expect(parseA1Range('1:3')).toEqual({
+    top: 0, left: null, bottom: 2, right: null,
+    $top: false, $left: false, $bottom: false, $right: false
+  });
+
+  expect(parseA1Range('3:1')).toEqual({
+    top: 0, left: null, bottom: 2, right: null,
+    $top: false, $left: false, $bottom: false, $right: false
+  });
+
+  expect(parseA1Range('$1:3')).toEqual({
+    top: 0, left: null, bottom: 2, right: null,
+    $top: true, $left: false, $bottom: false, $right: false
+  });
+
+  expect(parseA1Range('1:$3')).toEqual({
+    top: 0, left: null, bottom: 2, right: null,
+    $top: false, $left: false, $bottom: true, $right: false
+  });
+});
+
+test('parseA1Range parses trimmed ranges', () => {
+  expect(parseA1Range('A1.:B2')).toEqual({
+    top: 0, left: 0, bottom: 1, right: 1,
+    $top: false, $left: false, $bottom: false, $right: false,
+    trim: 'head'
+  });
+
+  expect(parseA1Range('A1:.B2')).toEqual({
+    top: 0, left: 0, bottom: 1, right: 1,
+    $top: false, $left: false, $bottom: false, $right: false,
+    trim: 'tail'
+  });
+
+  expect(parseA1Range('A1.:.B2')).toEqual({
+    top: 0, left: 0, bottom: 1, right: 1,
+    $top: false, $left: false, $bottom: false, $right: false,
+    trim: 'both'
+  });
+});
+
+test('parseA1Range handles partial column ranges', () => {
+  const range = {
+    top: 0, left: 0, bottom: null, right: 2,
+    $top: false, $left: false, $bottom: false, $right: false
+  };
+  expect(parseA1Range('A1:C')).toEqual(range);
+  expect(parseA1Range('C:A1')).toEqual(range);
+});
+
+test('parseA1Range handles partial row ranges', () => {
+  const range = {
+    top: 0, left: 0, bottom: 2, right: null,
+    $top: false, $left: false, $bottom: false, $right: false
+  };
+  expect(parseA1Range('A1:3')).toEqual(range);
+  expect(parseA1Range('3:A1')).toEqual(range);
+});
+
+test('parseA1Range returns null for invalid references', () => {
+  expect(parseA1Range('')).toBe(undefined);
+  expect(parseA1Range('A')).toBe(undefined);
+  expect(parseA1Range('1')).toBe(undefined);
+  expect(parseA1Range('$A')).toBe(undefined);
+  expect(parseA1Range('$1')).toBe(undefined);
+  expect(parseA1Range('AAAA1')).toBe(undefined);
+  expect(parseA1Range('A0')).toBe(undefined);
+  expect(parseA1Range('A10000000')).toBe(undefined);
+  expect(parseA1Range('123ABC')).toBe(undefined);
+  expect(parseA1Range('A1:B2:C3')).toBe(undefined);
+  expect(parseA1Range('A1::B2')).toBe(undefined);
+  expect(parseA1Range('A1B2')).toBe(undefined);
+  expect(parseA1Range('$$$A1')).toBe(undefined);
+});
+
+test('parseA1Range handles maximum valid values', () => {
+  expect(parseA1Range('XFD1048576')).toEqual({
+    top: 1048575, left: 16383, bottom: 1048575, right: 16383,
+    $top: false, $left: false, $bottom: false, $right: false
+  });
+  expect(parseA1Range('XFD1048577')).toBe(undefined);
+  expect(parseA1Range('XFE1048576')).toBe(undefined);
+});
+
+test('parseA1Range handles case insensitivity', () => {
+  const lower = parseA1Range('a1');
+  const upper = parseA1Range('A1');
+  const mixed = parseA1Range('aA1');
+
+  expect(lower).toEqual(upper);
+  expect(lower).toEqual({
+    top: 0, left: 0, bottom: 0, right: 0,
+    $top: false, $left: false, $bottom: false, $right: false
+  });
+  expect(mixed).toEqual({
+    top: 0, left: 26, bottom: 0, right: 26,
+    $top: false, $left: false, $bottom: false, $right: false
+  });
+});