@borgar/fx 4.7.0 → 4.8.0

package/docs/API.md

@@ -5,9 +5,7 @@
 - [addA1RangeBounds( range )](#addA1RangeBounds)
 - [addTokenMeta( tokenlist, _\[context\]_ )](#addTokenMeta)
 - [fixRanges( formula, _\[options\]_ )](#fixRanges)
-- [fromA1( rangeString )](#fromA1)
 - [fromCol( columnString )](#fromCol)
-- [fromR1C1( rangeString )](#fromR1C1)
 - [isError( token )](#isError)
 - [isFunction( token )](#isFunction)
 - [isFxPrefix( token )](#isFxPrefix)
@@ -24,9 +22,7 @@
 - [stringifyA1Ref( refObject, _\[options\]_ )](#stringifyA1Ref)
 - [stringifyR1C1Ref( refObject, _\[options\]_ )](#stringifyR1C1Ref)
 - [stringifyStructRef( refObject, _\[options\]_ )](#stringifyStructRef)
-- [toA1( range )](#toA1)
 - [toCol( columnIndex )](#toCol)
-- [toR1C1( range )](#toR1C1)
 - [tokenize( formula, _\[options\]_ )](#tokenize)
 - [translateToA1( formula, anchorCell, _\[options\]_ )](#translateToA1)
 - [translateToR1C1( formula, anchorCell, _\[options\]_ )](#translateToR1C1)
@@ -38,13 +34,26 @@
 
 **Types**
 
+- [AstExpression](#AstExpression)
+- [BinaryExpression](#BinaryExpression)
+- [CallExpression](#CallExpression)
+- [ErrorLiteral](#ErrorLiteral)
+- [Identifier](#Identifier)
+- [LambdaExpression](#LambdaExpression)
+- [LetDeclarator](#LetDeclarator)
+- [LetExpression](#LetExpression)
+- [Literal](#Literal)
+- [MatrixExpression](#MatrixExpression)
 - [RangeA1](#RangeA1)
 - [RangeR1C1](#RangeR1C1)
 - [ReferenceA1](#ReferenceA1)
+- [ReferenceIdentifier](#ReferenceIdentifier)
 - [ReferenceR1C1](#ReferenceR1C1)
 - [ReferenceStruct](#ReferenceStruct)
+- [SourceLocation](#SourceLocation)
 - [Token](#Token)
 - [TokenEnhanced](#TokenEnhanced)
+- [UnaryExpression](#UnaryExpression)
 
 ## Functions
 
@@ -177,24 +186,6 @@ Returns the same formula with the ranges updated. If an array of tokens was supp
 
 ---
 
-### <a id="fromA1" href="#fromA1">#</a> fromA1( rangeString ) ⇒ [`RangeA1`](#RangeA1) | `null`
-
-Parse a simple string reference to an A1 range into a range object. Will accept `A1`, `A2`, `A:A`, or `1:1`.
-
-**See also:** [parseA1Ref](#parseA1Ref).
-
-##### Parameters
-
-| Name        | Type     | Description    |
-| ----------- | -------- | -------------- |
-| rangeString | `string` | A range string |
-
-##### Returns
-
-[`RangeA1`](#RangeA1) | `null` – An object representing a valid range or null if it is invalid.
-
----
-
 ### <a id="fromCol" href="#fromCol">#</a> fromCol( columnString ) ⇒ `number`
 
 Convert a column string representation to a 0 based offset number (`"C"` = `2`).
@@ -213,24 +204,6 @@ The method expects a valid column identifier made up of _only_ A-Z letters, whic
 
 ---
 
-### <a id="fromR1C1" href="#fromR1C1">#</a> fromR1C1( rangeString ) ⇒ [`RangeR1C1`](#RangeR1C1) | `null`
-
-Parse a simple string reference to an R1C1 range into a range object.
-
-**See also:** [parseA1Ref](#parseA1Ref).
-
-##### Parameters
-
-| Name        | Type     | Description    |
-| ----------- | -------- | -------------- |
-| rangeString | `string` | A range string |
-
-##### Returns
-
-[`RangeR1C1`](#RangeR1C1) | `null` – An object representing a valid reference or null if it is invalid.
-
----
-
 ### <a id="isError" href="#isError">#</a> isError( token ) ⇒ `boolean`
 
 Determines whether the specified token is an error.
@@ -391,7 +364,7 @@ When given a tokenlist, this function returns a new list with ranges returned as
 
 ---
 
-### <a id="parse" href="#parse">#</a> parse( formula, _[options = `{}`]_ ) ⇒ `object`
+### <a id="parse" href="#parse">#</a> parse( formula, _[options = `{}`]_ ) ⇒ [`AstExpression`](#AstExpression)
 
 Parses a string formula or list of tokens into an AST.
 
@@ -399,7 +372,7 @@ The parser requires `mergeRefs` to have been `true` in tokenlist options, becaus
 
 The AST Abstract Syntax Tree's format is documented in [AST_format.md](./AST_format.md)
 
-**See also:** [nodeTypes](#nodeTypes).
+**See also:**  [nodeTypes](#nodeTypes).
 
 ##### Parameters
 
@@ -418,7 +391,7 @@ The AST Abstract Syntax Tree's format is documented in [AST_format.md](./AST_for
 
 ##### Returns
 
-`object` – An AST of nodes
+[`AstExpression`](#AstExpression) – An AST of nodes
 
 ---
 
@@ -626,24 +599,6 @@ stringifyStructRef({
 
 ---
 
-### <a id="toA1" href="#toA1">#</a> toA1( range ) ⇒ `string`
-
-Stringify a range object into A1 syntax.
-
-**See also:** [parseA1Ref](#parseA1Ref).
-
-##### Parameters
-
-| Name  | Type                  | Description    |
-| ----- | --------------------- | -------------- |
-| range | [`RangeA1`](#RangeA1) | A range object |
-
-##### Returns
-
-`string` – An A1-style string represenation of a range
-
----
-
 ### <a id="toCol" href="#toCol">#</a> toCol( columnIndex ) ⇒ `string`
 
 Convert a 0 based offset number to a column string representation (`2` = `"C"`).
@@ -662,24 +617,6 @@ The method expects a number between 0 and 16383. Other input will return garbage
 
 ---
 
-### <a id="toR1C1" href="#toR1C1">#</a> toR1C1( range ) ⇒ `string`
-
-Stringify a range object into R1C1 syntax.
-
-**See also:** [parseR1C1Ref](#parseR1C1Ref).
-
-##### Parameters
-
-| Name  | Type                      | Description    |
-| ----- | ------------------------- | -------------- |
-| range | [`RangeR1C1`](#RangeR1C1) | A range object |
-
-##### Returns
-
-`string` – An R1C1-style string represenation of a range
-
----
-
 ### <a id="tokenize" href="#tokenize">#</a> tokenize( formula, _[options = `{}`]_ ) ⇒ `Array<Token>`
 
 Breaks a string formula into a list of tokens.
@@ -707,7 +644,7 @@ To support syntax highlighting as you type, `STRING` tokens are allowed to be "u
 ]
 ```
 
-**See also:** [tokenTypes](#tokenTypes).
+**See also:**  [tokenTypes](#tokenTypes).
 
 ##### Parameters
 
@@ -802,7 +739,7 @@ translateToR1C1("=SUM(E10,$E$2,Sheet!$E$3)", "D10");
 
 A dictionary of the types used to identify AST node variants.
 
-**See also:** [parse](#parse).
+**See also:**  [parse](#parse).
 
 ##### Properties
 
@@ -823,7 +760,7 @@ A dictionary of the types used to identify AST node variants.
 
 A dictionary of the types used to identify token variants.
 
-**See also:** [tokenize](#tokenize).
+**See also:**  [tokenize](#tokenize).
 
 ##### Properties
 
@@ -851,6 +788,125 @@ A dictionary of the types used to identify token variants.
 
 ## Types
 
+### <a id="AstExpression" href="#AstExpression">#</a> AstExpression = [`ReferenceIdentifier`](#ReferenceIdentifier) | [`Literal`](#Literal) | [`ErrorLiteral`](#ErrorLiteral) | [`UnaryExpression`](#UnaryExpression) | [`BinaryExpression`](#BinaryExpression) | [`CallExpression`](#CallExpression) | [`MatrixExpression`](#MatrixExpression) | [`LambdaExpression`](#LambdaExpression) | [`LetExpression`](#LetExpression)
+
+---
+
+### <a id="BinaryExpression" href="#BinaryExpression">#</a> BinaryExpression = `Node`
+
+##### Properties
+
+| Name      | Type                                                                                                                                   |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| arguments | `Array<AstExpression>`                                                                                                                 |
+| [loc]     | [`SourceLocation`](#SourceLocation)                                                                                                    |
+| operator  | `"="` \| `"<"` \| `">"` \| `"<="` \| `">="` \| `"<>"` \| `"-"` \| `"+"` \| `"*"` \| `"/"` \| `"^"` \| `":"` \| `" "` \| `","` \| `"&"` |
+| type      | `"BinaryExpression"`                                                                                                                   |
+
+---
+
+### <a id="CallExpression" href="#CallExpression">#</a> CallExpression = `Node`
+
+##### Properties
+
+| Name      | Type                                |
+| --------- | ----------------------------------- |
+| arguments | `Array<AstExpression>`              |
+| callee    | [`Identifier`](#Identifier)         |
+| [loc]     | [`SourceLocation`](#SourceLocation) |
+| type      | `"CallExpression"`                  |
+
+---
+
+### <a id="ErrorLiteral" href="#ErrorLiteral">#</a> ErrorLiteral = `Node`
+
+##### Properties
+
+| Name  | Type                                |
+| ----- | ----------------------------------- |
+| [loc] | [`SourceLocation`](#SourceLocation) |
+| raw   | `string`                            |
+| type  | `"ErrorLiteral"`                    |
+| value | `string`                            |
+
+---
+
+### <a id="Identifier" href="#Identifier">#</a> Identifier = `Node`
+
+##### Properties
+
+| Name  | Type                                |
+| ----- | ----------------------------------- |
+| [loc] | [`SourceLocation`](#SourceLocation) |
+| name  | `string`                            |
+| type  | `"Identifier"`                      |
+
+---
+
+### <a id="LambdaExpression" href="#LambdaExpression">#</a> LambdaExpression = `Node`
+
+##### Properties
+
+| Name   | Type                                        |
+| ------ | ------------------------------------------- |
+| body   | `null` \| [`AstExpression`](#AstExpression) |
+| [loc]  | [`SourceLocation`](#SourceLocation)         |
+| params | `Array<Identifier>`                         |
+| type   | `"LambdaExpression"`                        |
+
+---
+
+### <a id="LetDeclarator" href="#LetDeclarator">#</a> LetDeclarator = `Node`
+
+##### Properties
+
+| Name  | Type                                        |
+| ----- | ------------------------------------------- |
+| id    | [`Identifier`](#Identifier)                 |
+| init  | `null` \| [`AstExpression`](#AstExpression) |
+| [loc] | [`SourceLocation`](#SourceLocation)         |
+| type  | `"LetDeclarator"`                           |
+
+---
+
+### <a id="LetExpression" href="#LetExpression">#</a> LetExpression = `Node`
+
+##### Properties
+
+| Name         | Type                                        |
+| ------------ | ------------------------------------------- |
+| body         | `null` \| [`AstExpression`](#AstExpression) |
+| declarations | `Array<LetDeclarator>`                      |
+| [loc]        | [`SourceLocation`](#SourceLocation)         |
+| type         | `"LetExpression"`                           |
+
+---
+
+### <a id="Literal" href="#Literal">#</a> Literal = `Node`
+
+##### Properties
+
+| Name  | Type                                |
+| ----- | ----------------------------------- |
+| [loc] | [`SourceLocation`](#SourceLocation) |
+| raw   | `string`                            |
+| type  | `"Literal"`                         |
+| value | `string` \| `number` \| `boolean`   |
+
+---
+
+### <a id="MatrixExpression" href="#MatrixExpression">#</a> MatrixExpression = `Node`
+
+##### Properties
+
+| Name      | Type                                                                            |
+| --------- | ------------------------------------------------------------------------------- |
+| arguments | `Array<Array<(ReferenceIdentifier | Literal | ErrorLiteral | CallExpression)>>` |
+| [loc]     | [`SourceLocation`](#SourceLocation)                                             |
+| type      | `"ArrayExpression"`                                                             |
+
+---
+
 ### <a id="RangeA1" href="#RangeA1">#</a> RangeA1
 
 A range in A1 style coordinates.
@@ -904,6 +960,19 @@ A reference containing an A1 style range. See [Prefixes.md] for   documentation
 
 ---
 
+### <a id="ReferenceIdentifier" href="#ReferenceIdentifier">#</a> ReferenceIdentifier = `Node`
+
+##### Properties
+
+| Name  | Type                                           |
+| ----- | ---------------------------------------------- |
+| kind  | `"name"` \| `"range"` \| `"beam"` \| `"table"` |
+| [loc] | [`SourceLocation`](#SourceLocation)            |
+| type  | `"ReferenceIdentifier"`                        |
+| value | `string`                                       |
+
+---
+
 ### <a id="ReferenceR1C1" href="#ReferenceR1C1">#</a> ReferenceR1C1
 
 A reference containing a R1C1 style range. See [Prefixes.md] for   documentation on how scopes work in Fx.
@@ -936,6 +1005,10 @@ A reference containing a table slice definition. See [Prefixes.md] for   documen
 
 ---
 
+### <a id="SourceLocation" href="#SourceLocation">#</a> SourceLocation = `Array<number>`
+
+---
+
 ### <a id="Token" href="#Token">#</a> Token extends `Record<string, any>`
 
 A formula language token.
@@ -966,4 +1039,17 @@ A token with extra meta data.
 
 ---
 
+### <a id="UnaryExpression" href="#UnaryExpression">#</a> UnaryExpression = `Node`
+
+##### Properties
+
+| Name      | Type                                      |
+| --------- | ----------------------------------------- |
+| arguments | `Array<AstExpression>`                    |
+| [loc]     | [`SourceLocation`](#SourceLocation)       |
+| operator  | `"+"` \| `"-"` \| `"%"` \| `"#"` \| `"@"` |
+| type      | `"UnaryExpression"`                       |
+
+---
+
 

package/docs/AST_format.md

@@ -6,7 +6,7 @@ This document specifies the core AST node types that support the Excel grammar.
 
 All AST nodes are represented by `Node` objects. They may have any prototype inheritance but implement the following basic interface:
 
-```
+```ts
 interface Node {
   type: string;
   loc?: Location | null;
@@ -17,7 +17,7 @@ The `type` field is a string representing the AST variant type. Each subtype of
 
 The `loc` field represents the source location information of the node. If the node contains no information about the source location, the field is `null`; otherwise it is an array consisting of a two numbers: A start offset (the position of the first character of the parsed source region) and an end offset (the position of the first character after the parsed source region):
 
-```
+```ts
 interface Location extends Array<number> {
   0: number;
   1: number;
@@ -26,30 +26,31 @@ interface Location extends Array<number> {
 
 ## Identifier
 
-```
+```ts
 interface Identifier extends Node {
   type: "Identifier";
   name: string;
 }
 ```
 
-An identifier. These only appear on `CallExpression` and will always be a static string representing the name of a function call.
+An identifier. These appear on `CallExpression`, `LambdaExpression`, and `LetExpression` and will always be a static string representing the name of a function call or parameter.
 
 ## ReferenceIdentifier
 
-```
+```ts
 interface ReferenceIdentifier extends Node {
   type: "ReferenceIdentifier";
   value: string;
+  kind: "name" | "range" | "beam" | "table";
 }
 ```
 
-A range identifier.
+An identifier for a range or a named. The 
 
 
 ## Literal
 
-```
+```ts
 interface Literal extends Node {
   type: "Literal";
   raw: string;
@@ -61,7 +62,7 @@ A literal token. Captures numbers, strings, and booleans. Literal errors have th
 
 ## ErrorLiteral
 
-```
+```ts
 interface ErrorLiteral extends Node {
   type: "ErrorLiteral";
   raw: string;
@@ -73,7 +74,7 @@ An Error expression.
 
 ## UnaryExpression
 
-```
+```ts
 interface UnaryExpression extends Node {
   type: "UnaryExpression";
   operator: UnaryOperator;
@@ -85,7 +86,7 @@ A unary operator expression.
 
 ### UnaryOperator 
 
-```
+```ts
 type UnaryOperator = (
   "+" | "-" | "%" | "#" | "@"
 )
@@ -95,7 +96,7 @@ A unary operator token.
 
 ## BinaryExpression
 
-```
+```ts
 interface BinaryExpression extends Node {
   type: "BinaryExpression";
   operator: BinaryOperator; 
@@ -107,7 +108,7 @@ A binary operator expression.
 
 ### BinaryOperator 
 
-```
+```ts
 type BinaryOperator = (
   "=" | "<" | ">" | "<=" | ">=" |  "<>" |
   "-" | "+" | "*" | "/" | "^" |
@@ -120,7 +121,7 @@ A binary operator token. Note that Excels union operator is whitespace so a pars
 
 ## CallExpression
 
-```
+```ts
 interface CallExpression extends Node {
   type: "CallExpression";
   callee: Identifier;
@@ -132,13 +133,42 @@ A function call expression.
 
 ## ArrayExpression
 
-```
+```ts
 interface ArrayExpression extends Node {
   type: "ArrayExpression";
-  elements: Array<Array<Literal | Error | ReferenceIdentifier>>;
+  elements: Array<Array<ReferenceIdentifier | Literal | ErrorLiteral | CallExpression>>;
 }
 ```
 
 An array expression. Excel does not have empty or sparse arrays and restricts array elements to literals. Google Sheets allows `ReferenceIdentifier`s as elements of arrays, the fx parser as an option for this but it is off by default.
 
+## LambdaExpression
+
+```ts
+interface LambdaExpression extends Node {
+  type: "LambdaExpression";
+  params: Array<Identifier>;
+  body: null | Node;
+}
+```
+
+## LetExpression
+
+```ts
+interface LetExpression extends Node {
+  type: "LetExpression";
+  declarations: Array<LetDeclarator>;
+  body: null | Node;
+}
+```
+
+## LetDeclarator
+
+```ts
+interface LetDeclarator extends Node {
+  type: "LetDeclarator";
+  id: Identifier;
+  init: null | Node;
+}
+```
 

package/docs/Prefixes.md

@@ -63,7 +63,7 @@ When Excel saves a workbook to one of its XML formats (most commonly as .xlsx) i
 * `[a]!`
 * `[a]b!`
 
-Since the XML files only ever emitted with positive integer indexes instead of workbook names, whether the syntax allows anything else is open. _Fx_ chooses to be permissive in handling this variant and allows `[Workbook.xlsx]!A1` forms as well as `[1]!A1`.
+Since the XML files only ever emitted with positive integer indexes instead of workbook names, whether the syntax allows anything else is speculative. _Fx_ chooses to be permissive in handling this variant and allows `[Workbook.xlsx]!A1` forms as well as `[1]!A1`.
 
 Why the formula language does not use this unambiguous and somewhat more intuitive variant rather than the above form is a question for Excel historians, likely this later form was introduced with the XML format to eliminate the ambiguity?
 

package/lib/a1.js

@@ -84,6 +84,7 @@ export function toAbsolute (range) {
  * Stringify a range object into A1 syntax.
  *
  * @private
+ * @ignore
  * @see parseA1Ref
  * @param {RangeA1} range  A range object
  * @returns {string}  An A1-style string represenation of a range
@@ -161,6 +162,7 @@ function splitA1 (str) {
  * Will accept `A1`, `A2`, `A:A`, or `1:1`.
  *
  * @private
+ * @ignore
  * @see parseA1Ref
  * @param {string} rangeString  A range string
  * @returns {(RangeA1|null)} An object representing a valid range or null if it is invalid.

package/lib/astTypes.js

@@ -0,0 +1,96 @@
+/* eslint-disable jsdoc/require-property-description */
+
+/**
+ * @typedef {number[]} SourceLocation
+ */
+
+/**
+ * @typedef {Node} Identifier
+ * @property {"Identifier"} type
+ * @property {SourceLocation} [loc]
+ * @property {string} name
+ */
+
+/**
+ * @typedef {Node} ReferenceIdentifier
+ * @property {"ReferenceIdentifier"} type
+ * @property {SourceLocation} [loc]
+ * @property {string} value
+ * @property {"name" | "range" | "beam" | "table"} kind
+ */
+
+/**
+ * @typedef {Node} Literal
+ * @property {"Literal"} type
+ * @property {SourceLocation} [loc]
+ * @property {string} raw
+ * @property {string | number | boolean} value
+ */
+
+/**
+ * @typedef {Node} ErrorLiteral
+ * @property {"ErrorLiteral"} type
+ * @property {SourceLocation} [loc]
+ * @property {string} raw
+ * @property {string} value
+ */
+
+/**
+ * @typedef {Node} UnaryExpression
+ * @property {"UnaryExpression"} type
+ * @property {SourceLocation} [loc]
+ * @property {"+" | "-" | "%" | "#" | "@"} operator
+ * @property {AstExpression[]} arguments
+ */
+
+/**
+ * @typedef {Node} BinaryExpression
+ * @property {"BinaryExpression"} type
+ * @property {SourceLocation} [loc]
+ * @property {"=" | "<" | ">" | "<=" | ">=" | "<>" | "-" | "+" | "*" | "/" | "^" | ":" | " " | "," | "&"} operator
+ * @property {AstExpression[]} arguments
+ */
+
+/**
+ * @typedef {Node} CallExpression
+ * @property {"CallExpression"} type
+ * @property {SourceLocation} [loc]
+ * @property {Identifier} callee
+ * @property {AstExpression[]} arguments
+ */
+
+// FIXME: the awkward naming is because tooling fails, fix tooling :)
+/**
+ * @typedef {Node} MatrixExpression
+ * @property {"ArrayExpression"} type
+ * @property {SourceLocation} [loc]
+ * @property {Array<Array<ReferenceIdentifier | Literal | ErrorLiteral | CallExpression>>} arguments
+ */
+
+/**
+ * @typedef {Node} LambdaExpression
+ * @property {"LambdaExpression"} type
+ * @property {SourceLocation} [loc]
+ * @property {Identifier[]} params
+ * @property {null | AstExpression} body
+ */
+
+/**
+ * @typedef {Node} LetExpression
+ * @property {"LetExpression"} type
+ * @property {SourceLocation} [loc]
+ * @property {LetDeclarator[]} declarations
+ * @property {null | AstExpression} body
+ */
+
+/**
+ * @typedef {Node} LetDeclarator
+ * @property {"LetDeclarator"} type
+ * @property {SourceLocation} [loc]
+ * @property {Identifier} id
+ * @property {null | AstExpression} init
+ */
+
+/**
+ * @typedef {ReferenceIdentifier | Literal | ErrorLiteral | UnaryExpression | BinaryExpression | CallExpression | MatrixExpression | LambdaExpression | LetExpression} AstExpression
+ */

package/lib/constants.js

@@ -22,8 +22,11 @@ export const REFERENCE = 'ReferenceIdentifier';
 export const LITERAL = 'Literal';
 export const ERROR_LITERAL = 'ErrorLiteral';
 export const CALL = 'CallExpression';
+export const LAMBDA = 'LambdaExpression';
+export const LET = 'LetExpression';
 export const ARRAY = 'ArrayExpression';
 export const IDENTIFIER = 'Identifier';
+export const LET_DECL = 'LetDeclarator';
 
 export const MAX_COLS = (2 ** 14) - 1; // 16383
 export const MAX_ROWS = (2 ** 20) - 1; // 1048575