API.md

@borgar/fx

Modules

• fx
• fx/xlsx

fx

A tokenizer, parser, and other utilities to work with Excel formula code.

The base entry-point methods expect and return the variant of references that uses contexts. If you are using xlsx files or otherwise want to work with the xlsx-file variant of references you should use the fx/xlsx variant methods.

See Prefixes.md for documentation on how scopes work in Fx.

Type Aliases

• ArrayExpression
• AstExpression
• BinaryExpression
• BinaryOperator
• CallExpression
• ErrorLiteral
• Identifier
• LambdaExpression
• LetDeclarator
• LetExpression
• Literal
• Node
• OptsFixRanges
• OptsParse
• OptsParseA1Ref
• OptsParseR1C1Ref
• OptsStringifyStructRef
• OptsTokenize
• OptsTranslateFormulaToA1
• OptsTranslateTokensToA1
• OptsTranslateToR1C1
• RangeA1
• RangeR1C1
• ReferenceA1
• ReferenceA1Xlsx
• ReferenceIdentifier
• ReferenceName
• ReferenceNameXlsx
• ReferenceR1C1
• ReferenceR1C1Xlsx
• ReferenceStruct
• ReferenceStructXlsx
• SourceLocation
• Token
• TokenEnhanced
• UnaryExpression
• UnaryOperator

Variables

• MAX_COLS
• MAX_ROWS
• nodeTypes
• tokenTypes

Functions

• addA1RangeBounds
• fixFormulaRanges
• fixTokenRanges
• fromCol
• isArrayNode
• isBinaryNode
• isCallNode
• isError
• isErrorNode
• isExpressionNode
• isFunction
• isFxPrefix
• isIdentifierNode
• isLambdaNode
• isLetDeclaratorNode
• isLetNode
• isLiteral
• isLiteralNode
• isOperator
• isRange
• isReference
• isReferenceNode
• isUnaryNode
• isWhitespace
• mergeRefTokens
• parse
• parseA1Range
• parseA1Ref
• parseR1C1Range
• parseR1C1Ref
• parseStructRef
• stringifyA1Ref
• stringifyR1C1Ref
• stringifyStructRef
• stringifyTokens
• toCol
• tokenize
• translateFormulaToA1
• translateFormulaToR1C1
• translateTokensToA1
• translateTokensToR1C1

addA1RangeBounds()

functionaddA1RangeBounds(range: RangeA1): RangeA1;

Fill the any missing bounds in range objects. Top will be set to 0, bottom to 1048575, left to 0, and right to 16383, if they are null or undefined.

addA1RangeBounds({top: 0,left: 0,bottom: 1,$top: true,$left: false,$bottom: false,});// => {// top: 0,// left: 0,// bottom: 1,// right: 16383, // ← Added// $top: true,// $left: false,// $bottom: false,// $right: false // ← Added// }

Parameters

Parameter	Type	Description
range	RangeA1	The range part of a reference object.

Returns

RangeA1

The same range with missing bounds filled in.

fixFormulaRanges()

functionfixFormulaRanges(formula: string,options?: OptsFixRanges&OptsTokenize): string;

Normalizes A1 style ranges and structured references in a formula.

Internally it uses fixTokenRanges so see it's documentation for details.

Returns the same formula with the ranges updated. If an array of tokens was supplied, then a new array is returned.

Parameters

Parameter	Type	Description
formula	string	A string (an Excel formula) or a token list that should be adjusted.
options?	OptsFixRanges & OptsTokenize	Options

Returns

string

A formula string with ranges adjusted

See

OptsFixRanges & OptsTokenize

fixTokenRanges()

functionfixTokenRanges(tokens: Token[],options?: OptsFixRanges): Token[];

Normalizes A1 style ranges and structured references in a list of tokens.

It ensures that that the top and left coordinates of an A1 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 } option is set to true, 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

Structured ranges are normalized to have consistent order and capitalization of sections as well as removing redundant ones.

Returns a new array of tokens with values and position data updated.

Parameters

Parameter	Type	Description
tokens	Token[]	A list of tokens to be adjusted.
options?	OptsFixRanges	Options.

Returns

Token[]

A token list with ranges adjusted.

See

OptsFixRanges

fromCol()

functionfromCol(columnString: string): number;

Convert a column string representation to a 0 based offset number ("C" = 2).

The method expects a valid column identifier made up of only A-Z letters, which may be either upper or lower case. Other input will return garbage.

Parameters

Parameter	Type	Description
columnString	string	The column string identifier

Returns

number

Zero based column index number

isArrayNode()

functionisArrayNode(node?: Node): node is ArrayExpression;

Determines whether the specified node is a ArrayExpression.

Parameters

Parameter	Type	Description
node?	Node	An AST node.

Returns

node is ArrayExpression

True if the specified token is a ArrayExpression, False otherwise.

isBinaryNode()

functionisBinaryNode(node?: Node): node is BinaryExpression;

Determines whether the specified node is a BinaryExpression.

Parameters

Parameter	Type	Description
node?	Node	An AST node.

Returns

node is BinaryExpression

True if the specified token is a BinaryExpression, False otherwise.

isCallNode()

functionisCallNode(node?: Node): node is CallExpression;

Determines whether the specified node is a CallExpression.

Parameters

Parameter	Type	Description
node?	Node	An AST node.

Returns

node is CallExpression

True if the specified token is a CallExpression, False otherwise.

isError()

functionisError(token?: Pick<Token,"type">): boolean;

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.

Parameters

Parameter	Type	Description
token?	Pick<Token, "type">	The token

Returns

boolean

True if the specified token is error, False otherwise.

isErrorNode()

functionisErrorNode(node?: Node): node is ErrorLiteral;

Determines whether the specified node is an ErrorLiteral.

Parameters

Parameter	Type	Description
node?	Node	An AST node.

Returns

node is ErrorLiteral

True if the specified token is an ErrorLiteral, False otherwise.

isExpressionNode()

functionisExpressionNode(node?: Node): node is AstExpression;

Determines whether the specified node is a AstExpression.

Parameters

Parameter	Type	Description
node?	Node	An AST node.

Returns

node is AstExpression

True if the specified token is a AstExpression, False otherwise.

isFunction()

functionisFunction(token?: Pick<Token,"type">): boolean;

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.

Parameters

Parameter	Type	Description
token?	Pick<Token, "type">	The token

Returns

boolean

True if the specified token is function, False otherwise.

isFxPrefix()

functionisFxPrefix(token?: Pick<Token,"type">): boolean;

Returns true if the input is a token of type FX_PREFIX (leading = in formula). In all other cases false is returned.

Parameters

Parameter	Type	Description
token?	Pick<Token, "type">	The token

Returns

boolean

True if the specified token is effects prefix, False otherwise.

isIdentifierNode()

functionisIdentifierNode(node?: Node): node is Identifier;

Determines whether the specified node is an Identifier.

Parameters

Parameter	Type	Description
node?	Node	An AST node.

Returns

node is Identifier

True if the specified token is an Identifier, False otherwise.

isLambdaNode()

functionisLambdaNode(node?: Node): node is LambdaExpression;

Determines whether the specified node is a LambdaExpression.

Parameters

Parameter	Type	Description
node?	Node	An AST node.

Returns

node is LambdaExpression

True if the specified token is a LambdaExpression, False otherwise.

isLetDeclaratorNode()

functionisLetDeclaratorNode(node?: Node): node is LetDeclarator;

Determines whether the specified node is a LetDeclarator.

Parameters

Parameter	Type	Description
node?	Node	An AST node.

Returns

node is LetDeclarator

True if the specified token is a LetDeclarator, False otherwise.

isLetNode()

functionisLetNode(node?: Node): node is LetExpression;

Determines whether the specified node is a LetExpression.

Parameters

Parameter	Type	Description
node?	Node	An AST node.

Returns

node is LetExpression

True if the specified token is a LetExpression, False otherwise.

isLiteral()

functionisLiteral(token?: Pick<Token,"type">): boolean;

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.

Parameters

Parameter	Type	Description
token?	Pick<Token, "type">	The token

Returns

boolean

True if the specified token is literal, False otherwise.

isLiteralNode()

functionisLiteralNode(node?: Node): node is Literal;

Determines whether the specified node is a Literal.

Parameters

Parameter	Type	Description
node?	Node	An AST node.

Returns

node is Literal

True if the specified token is a Literal, False otherwise.

isOperator()

functionisOperator(token?: Pick<Token,"type">): boolean;

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.

Parameters

Parameter	Type	Description
token?	Pick<Token, "type">	The token

Returns

boolean

True if the specified token is operator, False otherwise.

isRange()

functionisRange(token?: Pick<Token,"type">): boolean;

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.

Parameters

Parameter	Type	Description
token?	Pick<Token, "type">	A token

Returns

boolean

True if the specified token is range, False otherwise.

isReference()

functionisReference(token?: Pick<Token,"type">): boolean;

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.

Parameters

Parameter	Type	Description
token?	Pick<Token, "type">	The token

Returns

boolean

True if the specified token is reference, False otherwise.

isReferenceNode()

functionisReferenceNode(node?: Node): node is ReferenceIdentifier;

Determines whether the specified node is a ReferenceIdentifier.

Parameters

Parameter	Type	Description
node?	Node	An AST node.

Returns

node is ReferenceIdentifier

True if the specified token is a ReferenceIdentifier, False otherwise.

isUnaryNode()

functionisUnaryNode(node?: Node): node is UnaryExpression;

Determines whether the specified node is a UnaryExpression.

Parameters

Parameter	Type	Description
node?	Node	An AST node.

Returns

node is UnaryExpression

True if the specified token is a UnaryExpression, False otherwise.

isWhitespace()

functionisWhitespace(token?: Pick<Token,"type">): boolean;

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.

Parameters

Parameter	Type	Description
token?	Pick<Token, "type">	The token

Returns

boolean

True if the specified token is whitespace, False otherwise.

mergeRefTokens()

functionmergeRefTokens(tokenlist: Token[]): Token[];

Merges context with reference tokens as possible in a list of tokens.

When given a tokenlist, this function returns a new list with ranges returned as whole references (Sheet1!A1:B2) rather than separate tokens for each part: (Sheet1,!,A1,:,B2).

Parameters

Parameter	Type	Description
tokenlist	Token[]	An array of tokens.

Returns

Token[]

A new list of tokens with range parts merged.

parse()

functionparse(tokenlist: Token[],options?: OptsParse): AstExpression;

Parses a string formula or list of tokens into an AST.

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.

Parameters

Parameter	Type	Description
tokenlist	Token[]	An array of tokens.
options	OptsParse	Options for the parsers behavior.

Returns

AstExpression

An AST of nodes.

See

• OptsParse
• nodeTypes
• tokenize

parseA1Range()

functionparseA1Range(rangeString: string,allowTernary?: boolean): RangeA1;

Parse A1-style range string into a RangeA1 object.

Parameters

Parameter	Type	Default value	Description
rangeString	string	undefined	A1-style range string.
allowTernary?	boolean	true	Permit ternary ranges like A2:A or B2:2.

Returns

RangeA1

A reference object.

parseA1Ref()

functionparseA1Ref(refString: string,options?: OptsParseA1Ref): |ReferenceA1|ReferenceName;

Parse a string reference into an object representing it.

parseA1Ref('Sheet1!A$1:$B2');// => {// context: [ 'Sheet1' ],// range: {// top: 0,// left: 0,// bottom: 1,// right: 1// $top: true,// $left: false,// $bottom: false,// $right: true// }// }

For A:A or A1:A style ranges, null will be used for any dimensions that the syntax does not specify.

Parameters

Parameter	Type	Description
refString	string	An A1-style reference string.
options	OptsParseA1Ref	Options.

Returns

| ReferenceA1 | ReferenceName

An object representing a valid reference or undefined if it is invalid.

See

OptsParseA1Ref

parseR1C1Range()

functionparseR1C1Range(rangeString: string): RangeR1C1;

Parse R1C1-style range string into a RangeR1C1 object.

Parameters

Parameter	Type	Description
rangeString	string	R1C1-style range string.

Returns

RangeR1C1

A reference object.

parseR1C1Ref()

functionparseR1C1Ref(refString: string,options?: OptsParseR1C1Ref): |ReferenceName|ReferenceR1C1;

Parse a string reference into an object representing it.

parseR1C1Ref('Sheet1!R[9]C9:R[9]C9');// => {// context: [ 'Sheet1' ],// range: {// r0: 9,// c0: 8,// r1: 9,// c1: 8,// $c0: true,// $c1: true// $r0: false,// $r1: false// }// }

Parameters

Parameter	Type	Description
refString	string	An R1C1-style reference string.
options?	OptsParseR1C1Ref	Options.

Returns

| ReferenceName | ReferenceR1C1

An object representing a valid reference or undefined if it is invalid.

See

OptsParseR1C1Ref

parseStructRef()

functionparseStructRef(ref: string): ReferenceStruct;

Parse a structured reference string into an object representing it.

parseStructRef('workbook.xlsx!tableName[[#Data],[Column1]:[Column2]]');// => {// context: [ 'workbook.xlsx' ],// sections: [ 'data' ],// columns: [ 'my column', '@foo' ],// table: 'tableName',// }

For A:A or A1:A style ranges, null will be used for any dimensions that the syntax does not specify:

See References.md.

Parameters

Parameter	Type	Description
ref	string	A structured reference string

Returns

ReferenceStruct

An object representing a valid reference or undefined if it is invalid.

stringifyA1Ref()

functionstringifyA1Ref(refObject: |ReferenceA1|ReferenceName): string;

Get an A1-style string representation of a reference object.

stringifyA1Ref({context: ['Sheet1'],range: {top: 0,left: 0,bottom: 1,right: 1,$top: true,$left: false,$bottom: false,$right: true}});// => 'Sheet1!A$1:$B2'

Parameters

Parameter	Type	Description
refObject	| ReferenceA1 | ReferenceName	A reference object.

Returns

string

The reference in A1-style string format.

stringifyR1C1Ref()

functionstringifyR1C1Ref(refObject: |ReferenceName|ReferenceR1C1): string;

Get an R1C1-style string representation of a reference object.

stringifyR1C1Ref({context: ['Sheet1'],range: {r0: 9,c0: 8,r1: 9,c1: 8,$c0: true,$c1: true$r0: false,$r1: false}});// => 'Sheet1!R[9]C9:R[9]C9'

Parameters

Parameter	Type	Description
refObject	| ReferenceName | ReferenceR1C1	A reference object.

Returns

string

The reference in R1C1-style string format.

stringifyStructRef()

functionstringifyStructRef(refObject: ReferenceStruct,options?: OptsStringifyStructRef): string;

Returns a string representation of a structured reference object.

stringifyStructRef({context: ['workbook.xlsx'],sections: ['data'],columns: ['my column','@foo'],table: 'tableName',});// => 'workbook.xlsx!tableName[[#Data],[Column1]:[Column2]]'

Parameters

Parameter	Type	Description
refObject	ReferenceStruct	A structured reference object.
options?	OptsStringifyStructRef	Options.

Returns

string

The given structured reference in string format.

See

OptsStringifyStructRef

stringifyTokens()

functionstringifyTokens(tokens: Token[]): string;

Collapses a list of tokens into a formula string.

Parameters

Parameter	Type	Description
tokens	Token[]	A list of tokens.

Returns

string

A formula string.

toCol()

functiontoCol(columnIndex: number): string;

Convert a 0 based offset number to a column string representation (0 = "A", 2 = "C").

The method expects a number between 0 and 16383. Other input will return garbage.

Parameters

Parameter	Type	Description
columnIndex	number	Zero based column index number

Returns

string

The column string identifier

tokenize()

functiontokenize(formula: string,options?: OptsTokenize): Token[];

Breaks a string formula into a list of tokens.

The returned output will be an array of objects representing the tokens:

[{type: FX_PREFIX,value: '='},{type: FUNCTION,value: 'SUM'},{type: OPERATOR,value: '('},{type: REF_RANGE,value: 'A1:B2'},{type: OPERATOR,value: ')'}]

A collection of token types may be found as an object as the tokenTypes export on the package.

Warning: To support syntax highlighting as you type, STRING tokens are allowed to be "unterminated". For example, the incomplete formula ="Hello world would be tokenized as:

[{type: FX_PREFIX,value: '='},{type: STRING,value: '"Hello world',unterminated: true},]

Parsers will need to handle this.

Parameters

Parameter	Type	Description
formula	string	An Excel formula string (an Excel expression).
options?	OptsTokenize	Options

Returns

Token[]

An array of Tokens

See

• OptsTokenize
• tokenTypes

translateFormulaToA1()

functiontranslateFormulaToA1(formula: string,anchorCell: string,options?: OptsTranslateFormulaToA1): string;

Translates ranges in a formula from relative R1C1 syntax to absolute A1 syntax.

translateToA1("=SUM(RC[1],R2C5,Sheet!R3C5)","D10");// => "=SUM(E10,$E$2,Sheet!$E$3)");

If an input range is -1,-1 relative rows/columns and the anchor is A1, the resulting range will (by default) wrap around to the bottom of the sheet resulting in the range XFD1048576. This may not be what you want so you can set { wrapEdges } to false which will instead turn the range into a #REF! error.

translateToA1("=R[-1]C[-1]","A1");// => "=XFD1048576");translateToA1("=R[-1]C[-1]","A1",{wrapEdges: false});// => "=#REF!");

Parameters

Parameter	Type	Description
formula	string	An Excel formula string that should be adjusted.
anchorCell	string	A simple string reference to an A1 cell ID (AF123 or$C$5).
options	OptsTranslateFormulaToA1	Translation options.

Returns

string

A formula string.

See

OptsTranslateFormulaToA1

translateFormulaToR1C1()

functiontranslateFormulaToR1C1(formula: string,anchorCell: string,options?: OptsTranslateToR1C1): string;

Translates ranges in a formula from absolute A1 syntax to relative R1C1 syntax.

translateFormulaToR1C1("=SUM(E10,$E$2,Sheet!$E$3)","D10");// => "=SUM(RC[1],R2C5,Sheet!R3C5)");

Parameters

Parameter	Type	Description
formula	string	An Excel formula that should be adjusted.
anchorCell	string	A simple string reference to an A1 cell ID (AF123 or$C$5).
options?	OptsTranslateToR1C1	The options

Returns

string

A formula string.

See

OptsTranslateToR1C1

translateTokensToA1()

functiontranslateTokensToA1(tokens: Token[],anchorCell: string,options?: OptsTranslateTokensToA1): Token[];

Translates ranges in a list of tokens from relative R1C1 syntax to absolute A1 syntax.

translateToA1("=SUM(RC[1],R2C5,Sheet!R3C5)","D10");// => "=SUM(E10,$E$2,Sheet!$E$3)");

If an input range is -1,-1 relative rows/columns and the anchor is A1, the resulting range will (by default) wrap around to the bottom of the sheet resulting in the range XFD1048576. This may not be what you want so may set { wrapEdges } to false which will instead turn the range into a #REF! error.

translateToA1("=R[-1]C[-1]","A1");// => "=XFD1048576");translateToA1("=R[-1]C[-1]","A1",{wrapEdges: false});// => "=#REF!");

Note that if you are passing in a list of tokens that was not created using mergeRefs and you disable edge wrapping (or you simply set both options to false), you can end up with a formula such as =#REF!:B2 or =Sheet3!#REF!:F3. These are valid formulas in the Excel formula language and Excel will accept them, but they are not supported in Google Sheets.

Parameters

Parameter	Type	Description
tokens	Token[]	A token list that should be adjusted.
anchorCell	string	A simple string reference to an A1 cell ID (AF123 or$C$5).
options	OptsTranslateTokensToA1	Translation options.

Returns

Token[]

A token list.

See

OptsTranslateTokensToA1

translateTokensToR1C1()

functiontranslateTokensToR1C1(tokens: Token[],anchorCell: string): Token[];

Translates ranges in a list of tokens from absolute A1 syntax to relative R1C1 syntax.

translateFormulaToR1C1("=SUM(E10,$E$2,Sheet!$E$3)","D10");// => "=SUM(RC[1],R2C5,Sheet!R3C5)");

Parameters

Parameter	Type	Description
tokens	Token[]	A token list that should be adjusted.
anchorCell	string	A simple string reference to an A1 cell ID (AF123 or$C$5).

Returns

Token[]

A token list.

ArrayExpression

typeArrayExpression={elements: (|ReferenceIdentifier|Literal|ErrorLiteral|CallExpression)[][];loc?: SourceLocation;type: "ArrayExpression";}&Node;

An array expression. Excel does not have empty or sparse arrays and restricts array elements to literals. Google Sheets allows ReferenceIdentifiers and CallExpressions as elements of arrays, the fx parser has options for this but they are off by default.

Type Declaration

Name	Type	Description
elements	( | ReferenceIdentifier | Literal | ErrorLiteral | CallExpression)[][]	The elements of the array.
loc?	SourceLocation	The original source position of the node.
type	"ArrayExpression"	The type of this AST node.

AstExpression

typeAstExpression=|ReferenceIdentifier|Literal|ErrorLiteral|UnaryExpression|BinaryExpression|CallExpression|ArrayExpression|LambdaExpression|LetExpression;

Represents an evaluate-able expression.

BinaryExpression

typeBinaryExpression={arguments: AstExpression[];loc?: SourceLocation;operator: BinaryOperator;type: "BinaryExpression";}&Node;

A binary operator expression.

Type Declaration

Name	Type	Description
arguments	AstExpression[]	The arguments for the operator.
loc?	SourceLocation	The original source position of the node.
operator	BinaryOperator	The expression's operator.
type	"BinaryExpression"	The type of this AST node.

BinaryOperator

typeBinaryOperator=|"="|"<"|">"|"<="|">="|"<>"|"-"|"+"|"*"|"/"|"^"|":"|" "|","|"&";

A binary operator token.

Note that Excels union operator is whitespace so a parser must take care to normalize this to a single space.

CallExpression

typeCallExpression={arguments: AstExpression[];callee: Identifier;loc?: SourceLocation;type: "CallExpression";}&Node;

A function call expression.

Type Declaration

Name	Type	Description
arguments	AstExpression[]	The arguments for the function.
callee	Identifier	The function being called.
loc?	SourceLocation	The original source position of the node.
type	"CallExpression"	The type of this AST node.

ErrorLiteral

typeErrorLiteral={loc?: SourceLocation;raw: string;type: "ErrorLiteral";value: string;}&Node;

An Error expression.

Type Declaration

Name	Type	Description
loc?	SourceLocation	The original source position of the node.
raw	string	The untouched literal source.
type	"ErrorLiteral"	The type of this AST node.
value	string	The value of the error.

Identifier

typeIdentifier={loc?: SourceLocation;name: string;type: "Identifier";}&Node;

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.

Type Declaration

Name	Type	Description
loc?	SourceLocation	The original source position of the node.
name	string	The identifying name.
type	"Identifier"	The type of this AST node.

LambdaExpression

typeLambdaExpression={body: AstExpression|null;loc?: SourceLocation;params: Identifier[];type: "LambdaExpression";}&Node;

A LAMBDA expression.

Type Declaration

Name	Type	Description
body	AstExpression | null	The LAMBDA's expression.
loc?	SourceLocation	The original source position of the node.
params	Identifier[]	The LAMBDA's parameters.
type	"LambdaExpression"	The type of this AST node.

LetDeclarator

typeLetDeclarator={id: Identifier;init: AstExpression|null;loc?: SourceLocation;type: "LetDeclarator";}&Node;

A LET parameter declaration.

Type Declaration

Name	Type	Description
id	Identifier	The name of the variable.
init	AstExpression | null	The variable's initializing expression.
loc?	SourceLocation	The original source position of the node.
type	"LetDeclarator"	The type of this AST node.

LetExpression

typeLetExpression={body: AstExpression|null;declarations: LetDeclarator[];loc?: SourceLocation;type: "LetExpression";}&Node;

A LET expression.

Type Declaration

Name	Type	Description
body	AstExpression | null	The LET's scoped expression.
declarations	LetDeclarator[]	The LET's variable declarations.
loc?	SourceLocation	The original source position of the node.
type	"LetExpression"	The type of this AST node.

Literal

typeLiteral={loc?: SourceLocation;raw: string;type: "Literal";value: string|number|boolean;}&Node;

A literal token. Captures numbers, strings, and booleans. Literal errors have their own variant type.

Type Declaration

Name	Type	Description
loc?	SourceLocation	The original source position of the node.
raw	string	The untouched literal source.
type	"Literal"	The type of this AST node.
value	string | number | boolean	The value of the literal.

Node

typeNode={loc?: SourceLocation;type: string;};

All AST nodes are represented by Node objects. They may have any prototype inheritance but implement the same basic interface.

The type field is a string representing the AST variant type. Each subtype of Node is documented below with the specific string of its type field. You can use this field to determine which interface a node implements.

Properties

Property	Type	Description
loc?	SourceLocation	The original source position of the node.
type	string	The type of this AST node.

OptsFixRanges

typeOptsFixRanges={addBounds?: boolean;thisRow?: boolean;};

Options for fixTokenRanges and fixFormulaRanges.

Properties

Property	Type	Default value	Description
addBounds?	boolean	false	Fill in any undefined bounds of range objects. Top to 0, bottom to 1048575, left to 0, and right to 16383.
thisRow?	boolean	false	Enforces using the [#This Row] instead of the @ shorthand when serializing structured ranges.

OptsParse

typeOptsParse={looseRefCalls?: boolean;permitArrayCalls?: boolean;permitArrayRanges?: boolean;};

Options for parse.

Properties

Property	Type	Default value	Description
looseRefCalls?	boolean	false	Permits any function call where otherwise only functions that return references would be permitted.
permitArrayCalls?	boolean	false	Function calls are allowed as elements of arrays. This is a feature in Google Sheets while Excel does not allow it.
permitArrayRanges?	boolean	false	Ranges are allowed as elements of arrays. This is a feature in Google Sheets while Excel does not allow it.

OptsParseA1Ref

typeOptsParseA1Ref={allowNamed?: boolean;allowTernary?: boolean;};

Options for parseA1Ref.

Properties

Property	Type	Default value	Description
allowNamed?	boolean	true	Enable parsing names as well as ranges.
allowTernary?	boolean	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.

OptsParseR1C1Ref

typeOptsParseR1C1Ref={allowNamed?: boolean;allowTernary?: boolean;};

Options for parseR1C1Ref.

Properties

Property	Type	Default value	Description
allowNamed?	boolean	true	Enable parsing names as well as ranges.
allowTernary?	boolean	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.

OptsStringifyStructRef

typeOptsStringifyStructRef={thisRow?: boolean;};

Options for stringifyStructRef

Properties

Property	Type	Default value	Description
thisRow?	boolean	false	Enforces using the [#This Row] instead of the @ shorthand when serializing structured ranges.

OptsTokenize

typeOptsTokenize={allowTernary?: boolean;mergeRefs?: boolean;negativeNumbers?: boolean;r1c1?: boolean;withLocation?: boolean;};

Options for tokenize.

Properties

Property	Type	Default value	Description
allowTernary?	boolean	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.
mergeRefs?	boolean	true	Should ranges be returned as whole references (Sheet1!A1:B2) or as separate tokens for each part: (Sheet1,!,A1,:,B2). This is the same as calling mergeRefTokens
negativeNumbers?	boolean	true	Merges unary minuses with their immediately following number tokens (-,1) => -1 (alternatively these will be unary operations in the tree).
r1c1?	boolean	false	Ranges are expected to be in the R1C1 style format rather than the more popular A1 style.
withLocation?	boolean	true	Nodes will include source position offsets to the tokens: { loc: [ start, end ] }

OptsTranslateFormulaToA1

typeOptsTranslateFormulaToA1={allowTernary?: boolean;mergeRefs?: boolean;wrapEdges?: boolean;};

Options for translateFormulaToA1.

Properties

Property	Type	Default value	Description
allowTernary?	boolean	true	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.
mergeRefs?	boolean	true	Should ranges be treated as whole references (Sheet1!A1:B2) or as separate tokens for each part: (Sheet1,!,A1,:,B2).
wrapEdges?	boolean	true	Wrap out-of-bounds ranges around sheet edges rather than turning them to #REF! errors.

OptsTranslateToR1C1

typeOptsTranslateToR1C1={allowTernary?: boolean;};

Options for translateFormulaToR1C1.

Properties

Property	Type	Default value	Description
allowTernary?	boolean	true	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.

OptsTranslateTokensToA1

typeOptsTranslateTokensToA1={wrapEdges?: boolean;};

Options for translateTokensToA1

Properties

Property	Type	Default value	Description
wrapEdges?	boolean	true	Wrap out-of-bounds ranges around sheet edges rather than turning them to #REF! errors.

RangeA1

typeRangeA1={$bottom?: boolean|null;$left?: boolean|null;$right?: boolean|null;$top?: boolean|null;bottom?: number|null;left: number|null;right?: number|null;top: number|null;trim?: "head"|"tail"|"both"|null;};

A range in A1 style coordinates.

Properties

Property	Type	Description
$bottom?	boolean | null	Signifies that bottom is a "locked" value
$left?	boolean | null	Signifies that left is a "locked" value
$right?	boolean | null	Signifies that right is a "locked" value
$top?	boolean | null	Signifies that top is a "locked" value
bottom?	number | null	Bottom row of the range
left	number | null	Left column of the range
right?	number | null	Right column of the range
top	number | null	Top row of the range
trim?	"head" | "tail" | "both" | null	Should empty rows and columns at the top/left or bottom/right be discarded when range is read?

RangeR1C1

typeRangeR1C1={$c0?: boolean|null;$c1?: boolean|null;$r0?: boolean|null;$r1?: boolean|null;c0?: number|null;c1?: number|null;r0?: number|null;r1?: number|null;trim?: "head"|"tail"|"both"|null;};

A range in R1C1 style coordinates.

Properties

Property	Type	Description
$c0?	boolean | null	Signifies that c0 is an absolute value
$c1?	boolean | null	Signifies that c1 is an absolute value
$r0?	boolean | null	Signifies that r0 is an absolute value
$r1?	boolean | null	Signifies that r1 is an absolute value
c0?	number | null	Left column of the range
c1?	number | null	Right column of the range
r0?	number | null	Top row of the range
r1?	number | null	Bottom row of the range
trim?	"head" | "tail" | "both" | null	Should empty rows and columns at the top/left or bottom/right be discarded when range is read?

ReferenceA1

typeReferenceA1={context?: string[];range: RangeA1;};

A reference containing an A1 style range. See Prefixes.md for documentation on how scopes work in Fx.

Properties

Property	Type	Description
context?	string[]	A collection of scopes for the reference
range	RangeA1	The reference's range

ReferenceA1Xlsx

typeReferenceA1Xlsx={range: RangeA1;sheetName?: string;workbookName?: string;};

A reference containing an A1 style range. See [Prefixes.md] for documentation on how scopes work in Fx.

Properties

Property	Type	Description
range	RangeA1	The reference's range
sheetName?	string	A context sheet scope
workbookName?	string	A context workbook scope

ReferenceIdentifier

typeReferenceIdentifier={kind: "name"|"range"|"beam"|"table";loc?: SourceLocation;type: "ReferenceIdentifier";value: string;}&Node;

An identifier for a range or a name.

Type Declaration

Name	Type	Description
kind	"name" | "range" | "beam" | "table"	The kind of reference the value holds.
loc?	SourceLocation	The original source position of the node.
type	"ReferenceIdentifier"	The type of this AST node.
value	string	The untouched reference value.

ReferenceName

typeReferenceName={context?: string[];name: string;};

A reference containing a name. See [Prefixes.md] for documentation on how scopes work in Fx.

Properties

Property	Type	Description
context?	string[]	A collection of scopes for the reference
name	string	The reference's name

ReferenceNameXlsx

typeReferenceNameXlsx={name: string;sheetName?: string;workbookName?: string;};

A reference containing a name. See [Prefixes.md] for documentation on how scopes work in Fx.

Properties

Property	Type	Description
name	string	The reference's name
sheetName?	string	A context sheet scope
workbookName?	string	A context workbook scope

ReferenceR1C1

typeReferenceR1C1={context?: string[];range: RangeR1C1;};

A reference containing a R1C1 style range. See [Prefixes.md] for documentation on how scopes work in Fx.

Properties

Property	Type	Description
context?	string[]	A collection of scopes for the reference
range	RangeR1C1	The reference's range

ReferenceR1C1Xlsx

typeReferenceR1C1Xlsx={range: RangeR1C1;sheetName?: string;workbookName?: string;};

A reference containing a R1C1 style range. See [Prefixes.md] for documentation on how scopes work in Fx.

Properties

Property	Type	Description
range	RangeR1C1	The reference's range
sheetName?	string	A context sheet scope
workbookName?	string	A context workbook scope

ReferenceStruct

typeReferenceStruct={columns?: string[];context?: string[];sections?: string[];table?: string;};

A reference containing a table slice definition. See [Prefixes.md] for documentation on how scopes work in Fx.

Properties

Property	Type	Description
columns?	string[]	The sections this reference targets
context?	string[]	A collection of scopes for the reference
sections?	string[]	The sections this reference targets
table?	string	The table this reference targets

ReferenceStructXlsx

typeReferenceStructXlsx={columns?: string[];sections?: string[];sheetName?: string;table?: string;workbookName?: string;};

A reference containing a table slice definition. See [Prefixes.md] for documentation on how scopes work in Fx.

Properties

Property	Type	Description
columns?	string[]	The sections this reference targets
sections?	string[]	The sections this reference targets
sheetName?	string	A context sheet scope
table?	string	The table this reference targets
workbookName?	string	A context workbook scope

SourceLocation

typeSourceLocation=number[];

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).

Token

typeToken=Record<string,unknown>&{loc?: number[];type: string;unterminated?: boolean;value: string;};

A formula language token.

Type Declaration

Name	Type	Description
loc?	number[]	Source position offsets to the token
type	string	The type of the token
unterminated?	boolean	Signifies an unterminated string token
value	string	The value of the token

TokenEnhanced

typeTokenEnhanced=Token&{depth?: number;error?: boolean;groupId?: string;index: number;};

A token with extra meta data.

Type Declaration

Name	Type	Description
depth?	number	This token's level of nesting inside parentheses
error?	boolean	Token is of unknown type or a paren without a match
groupId?	string	The ID of a group which this token belongs (e.g. matching parens)
index	number	A zero based position in a token list

UnaryExpression

typeUnaryExpression={arguments: AstExpression[];loc?: SourceLocation;operator: UnaryOperator;type: "UnaryExpression";}&Node;

A unary operator expression.

Type Declaration

Name	Type	Description
arguments	AstExpression[]	The arguments for the operator.
loc?	SourceLocation	The original source position of the node.
operator	UnaryOperator	The expression's operator.
type	"UnaryExpression"	The type of this AST node.

UnaryOperator

typeUnaryOperator="+"|"-"|"%"|"#"|"@";

A unary operator token.

MAX_COLS

constMAX_COLS: number;

The maximum number of columns a spreadsheet reference may hold (16383).

MAX_ROWS

constMAX_ROWS: number;

The maximum number of rows a spreadsheet reference may hold (1048575).

nodeTypes

constnodeTypes: Readonly<{ARRAY: "ArrayExpression";BINARY: "BinaryExpression";CALL: "CallExpression";ERROR: "ErrorLiteral";IDENTIFIER: "Identifier";LAMBDA: "LambdaExpression";LET: "LetExpression";LET_DECL: "LetDeclarator";LITERAL: "Literal";REFERENCE: "ReferenceIdentifier";UNARY: "UnaryExpression";}>;

A dictionary of the types used to identify AST node variants.

tokenTypes

consttokenTypes: Readonly<{BOOLEAN: "bool";CONTEXT: "context";CONTEXT_QUOTE: "context_quote";ERROR: "error";FUNCTION: "func";FX_PREFIX: "fx_prefix";NEWLINE: "newline";NUMBER: "number";OPERATOR: "operator";REF_BEAM: "range_beam";REF_NAMED: "range_named";REF_RANGE: "range";REF_STRUCT: "structured";REF_TERNARY: "range_ternary";STRING: "string";UNKNOWN: "unknown";WHITESPACE: "whitespace";}>;

A dictionary of the types used to identify token variants.

fx/xlsx

A tokenizer, parser, and other utilities to work with Excel formula code.

The xslx entry-point methods expect and return the variant of references that uses properties. If you are not using xlsx files you should use the fx variant methods.

See Prefixes.md for documentation on how scopes work in Fx.

Functions

• addTokenMeta
• fixFormulaRanges
• fixTokenRanges
• mergeRefTokens
• parseA1Ref
• parseR1C1Ref
• parseStructRef
• stringifyA1Ref
• stringifyR1C1Ref
• stringifyStructRef
• tokenize

References

addA1RangeBounds

Re-exports addA1RangeBounds

---

ArrayExpression

Re-exports ArrayExpression

---

AstExpression

Re-exports AstExpression

---

BinaryExpression

Re-exports BinaryExpression

---

BinaryOperator

Re-exports BinaryOperator

---

CallExpression

Re-exports CallExpression

---

ErrorLiteral

Re-exports ErrorLiteral

---

fromCol

Re-exports fromCol

---

Identifier

Re-exports Identifier

---

isArrayNode

Re-exports isArrayNode

---

isBinaryNode

Re-exports isBinaryNode

---

isCallNode

Re-exports isCallNode

---

isError

Re-exports isError

---

isErrorNode

Re-exports isErrorNode

---

isExpressionNode

Re-exports isExpressionNode

---

isFunction

Re-exports isFunction

---

isFxPrefix

Re-exports isFxPrefix

---

isIdentifierNode

Re-exports isIdentifierNode

---

isLambdaNode

Re-exports isLambdaNode

---

isLetDeclaratorNode

Re-exports isLetDeclaratorNode

---

isLetNode

Re-exports isLetNode

---

isLiteral

Re-exports isLiteral

---

isLiteralNode

Re-exports isLiteralNode

---

isOperator

Re-exports isOperator

---

isRange

Re-exports isRange

---

isReference

Re-exports isReference

---

isReferenceNode

Re-exports isReferenceNode

---

isUnaryNode

Re-exports isUnaryNode

---

isWhitespace

Re-exports isWhitespace

---

LambdaExpression

Re-exports LambdaExpression

---

LetDeclarator

Re-exports LetDeclarator

---

LetExpression

Re-exports LetExpression

---

Literal

Re-exports Literal

---

MAX_COLS

Re-exports MAX_COLS

---

MAX_ROWS

Re-exports MAX_ROWS

---

Node

Re-exports Node

---

nodeTypes

Re-exports nodeTypes

---

OptsFixRanges

Re-exports OptsFixRanges

---

OptsParse

Re-exports OptsParse

---

OptsParseA1Ref

Re-exports OptsParseA1Ref

---

OptsParseR1C1Ref

Re-exports OptsParseR1C1Ref

---

OptsStringifyStructRef

Re-exports OptsStringifyStructRef

---

OptsTokenize

Re-exports OptsTokenize

---

OptsTranslateFormulaToA1

Re-exports OptsTranslateFormulaToA1

---

OptsTranslateTokensToA1

Re-exports OptsTranslateTokensToA1

---

OptsTranslateToR1C1

Re-exports OptsTranslateToR1C1

---

parse

Re-exports parse

---

parseA1Range

Re-exports parseA1Range

---

parseR1C1Range

Re-exports parseR1C1Range

---

RangeA1

Re-exports RangeA1

---

RangeR1C1

Re-exports RangeR1C1

---

ReferenceA1

Re-exports ReferenceA1

---

ReferenceA1Xlsx

Re-exports ReferenceA1Xlsx

---

ReferenceIdentifier

Re-exports ReferenceIdentifier

---

ReferenceName

Re-exports ReferenceName

---

ReferenceNameXlsx

Re-exports ReferenceNameXlsx

---

ReferenceR1C1

Re-exports ReferenceR1C1

---

ReferenceR1C1Xlsx

Re-exports ReferenceR1C1Xlsx

---

ReferenceStruct

Re-exports ReferenceStruct

---

ReferenceStructXlsx

Re-exports ReferenceStructXlsx

---

SourceLocation

Re-exports SourceLocation

---

stringifyTokens

Re-exports stringifyTokens

---

toCol

Re-exports toCol

---

Token

Re-exports Token

---

TokenEnhanced

Re-exports TokenEnhanced

---

tokenTypes

Re-exports tokenTypes

---

translateFormulaToA1

Re-exports translateFormulaToA1

---

translateFormulaToR1C1

Re-exports translateFormulaToR1C1

---

translateTokensToA1

Re-exports translateTokensToA1

---

translateTokensToR1C1

Re-exports translateTokensToR1C1

---

UnaryExpression

Re-exports UnaryExpression

---

UnaryOperator

Re-exports UnaryOperator

addTokenMeta()

functionaddTokenMeta(tokenlist: Token[],context?: {sheetName?: string;workbookName?: string;}): TokenEnhanced[];

Runs through a list of tokens and adds extra attributes such as matching parens and ranges.

The context parameter defines default reference attributes: { workbookName: 'report.xlsx', sheetName: 'Sheet1' }. If supplied, these are used to match A1 to Sheet1!A1.

All tokens will be tagged with a .depth number value to indicating the level of nesting in parentheses as well as an .index number indicating their zero based position in the list.

The returned output will be the same array of tokens but the following properties will added to tokens (as applicable):

Parentheses ( )

Matching parens will be tagged with .groupId string identifier as well as a .depth number value (indicating the level of nesting).

Closing parens without a counterpart will be tagged with .error (boolean true).

Curly brackets { }

Matching curly brackets will be tagged with .groupId string identifier. These may not be nested in Excel.

Closing curly brackets without a counterpart will be tagged with .error (boolean true).

Ranges (REF_RANGE or REF_BEAM type tokens)

All ranges will be tagged with .groupId string identifier regardless of the number of times they occur.

Tokens of type UNKNOWN

All will be tagged with .error (boolean true).

Parameters

Parameter	Type	Description
tokenlist	Token[]	An array of tokens (from tokenize())
context?	{ sheetName?: string; workbookName?: string; }	A context used to match A1 to Sheet1!A1.
context.sheetName?	string	An implied sheet name ('Sheet1')
context.workbookName?	string	An implied workbook name ('report.xlsx')

Returns

TokenEnhanced[]

The input array with the enchanced tokens

fixFormulaRanges()

functionfixFormulaRanges(formula: string,options?: OptsFixRanges&OptsTokenize): string;

Normalizes A1 style ranges and structured references in a formula.

Internally it uses fixTokenRanges so see it's documentation for details.

Returns the same formula with the ranges updated. If an array of tokens was supplied, then a new array is returned.

Parameters

Parameter	Type	Description
formula	string	A string (an Excel formula) or a token list that should be adjusted.
options?	OptsFixRanges & OptsTokenize	Options

Returns

string

A formula string with ranges adjusted

See

OptsFixRanges & OptsTokenize

fixTokenRanges()

functionfixTokenRanges(tokens: Token[],options?: OptsFixRanges): Token[];

Normalizes A1 style ranges and structured references in a list of tokens and returns a new array of tokens with values and position-data updated.

It ensures that that the top and left coordinates of an A1 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 } option is set to true, 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

Structured ranges are normalized to have consistent order and capitalization of sections as well as removing redundant ones.

Unlike Excel, fx does not normalize sheet or workbook names of references.

Parameters

Parameter	Type	Description
tokens	Token[]	A list of tokens to be adjusted.
options?	OptsFixRanges	Options.

Returns

Token[]

A token list with ranges adjusted.

See

OptsFixRanges

mergeRefTokens()

functionmergeRefTokens(tokenlist: Token[]): Token[];

Merges context with reference tokens as possible in a list of tokens.

When given a tokenlist, this function returns a new list with ranges returned as whole references (Sheet1!A1:B2) rather than separate tokens for each part: (Sheet1,!,A1,:,B2).

Parameters

Parameter	Type	Description
tokenlist	Token[]	An array of tokens.

Returns

Token[]

A new list of tokens with range parts merged.

parseA1Ref()

functionparseA1Ref(refString: string,options?: OptsParseA1Ref): |ReferenceA1Xlsx|ReferenceNameXlsx;

Parse a string reference into an object representing it.

parseA1Ref('Sheet1!A$1:$B2');// => {// workbookName: '',// sheetName: 'Sheet1',// range: {// top: 0,// left: 0,// bottom: 1,// right: 1// $top: true,// $left: false,// $bottom: false,// $right: true// }// }

For A:A or A1:A style ranges, null will be used for any dimensions that the syntax does not specify.

Parameters

Parameter	Type	Description
refString	string	An A1-style reference string.
options	OptsParseA1Ref	Options.

Returns

| ReferenceA1Xlsx | ReferenceNameXlsx

An object representing a valid reference or undefined if it is invalid.

See

OptsParseA1Ref

parseR1C1Ref()

functionparseR1C1Ref(refString: string,options?: OptsParseR1C1Ref): |ReferenceNameXlsx|ReferenceR1C1Xlsx;

Parse a string reference into an object representing it.

parseR1C1Ref('Sheet1!R[9]C9:R[9]C9');// => {// context: [ 'Sheet1' ],// range: {// r0: 9,// c0: 8,// r1: 9,// c1: 8,// $c0: true,// $c1: true// $r0: false,// $r1: false// }// }

Parameters

Parameter	Type	Description
refString	string	An R1C1-style reference string.
options?	OptsParseR1C1Ref	Options.

Returns

| ReferenceNameXlsx | ReferenceR1C1Xlsx

An object representing a valid reference or undefined if it is invalid.

See

OptsParseR1C1Ref

parseStructRef()

functionparseStructRef(ref: string): ReferenceStructXlsx;

Parse a structured reference string into an object representing it.

parseStructRef('[workbook.xlsx]!tableName[[#Data],[Column1]:[Column2]]');// => {// workbookName: 'workbook.xlsx',// sections: [ 'data' ],// columns: [ 'my column', '@foo' ],// table: 'tableName',// }

For A:A or A1:A style ranges, null will be used for any dimensions that the syntax does not specify:

See References.md.

Parameters

Parameter	Type	Description
ref	string	A structured reference string

Returns

ReferenceStructXlsx

An object representing a valid reference or null if it is invalid.

stringifyA1Ref()

functionstringifyA1Ref(refObject: |ReferenceA1Xlsx|ReferenceNameXlsx): string;

Get an A1-style string representation of a reference object.

stringifyA1Ref({sheetName: 'Sheet1',range: {top: 0,left: 0,bottom: 1,right: 1,$top: true,$left: false,$bottom: false,$right: true}});// => 'Sheet1!A$1:$B2'

Parameters

Parameter	Type	Description
refObject	| ReferenceA1Xlsx | ReferenceNameXlsx	A reference object.

Returns

string

The reference in A1-style string format.

stringifyR1C1Ref()

functionstringifyR1C1Ref(refObject: |ReferenceNameXlsx|ReferenceR1C1Xlsx): string;

Get an R1C1-style string representation of a reference object.

stringifyR1C1Ref({sheetName: 'Sheet1',range: {r0: 9,c0: 8,r1: 9,c1: 8,$c0: true,$c1: true$r0: false,$r1: false}});// => 'Sheet1!R[9]C9:R[9]C9'

Parameters

Parameter	Type	Description
refObject	| ReferenceNameXlsx | ReferenceR1C1Xlsx	A reference object.

Returns

string

The reference in R1C1-style string format.

stringifyStructRef()

functionstringifyStructRef(refObject: ReferenceStructXlsx,options?: OptsStringifyStructRef): string;

Returns a string representation of a structured reference object.

stringifyStructRef({workbookName: 'workbook.xlsx',sheetName: '',sections: ['data'],columns: ['my column','@foo'],table: 'tableName',});// => 'workbook.xlsx!tableName[[#Data],[Column1]:[Column2]]'

Parameters

Parameter	Type	Description
refObject	ReferenceStructXlsx	A structured reference object.
options?	OptsStringifyStructRef	Options.

Returns

string

The given structured reference in string format.

tokenize()

functiontokenize(formula: string,options?: OptsTokenize): Token[];

Breaks a string formula into a list of tokens.

The returned output will be an array of objects representing the tokens:

[{type: FX_PREFIX,value: '='},{type: FUNCTION,value: 'SUM'},{type: OPERATOR,value: '('},{type: REF_RANGE,value: 'A1:B2'},{type: OPERATOR,value: ')'}]

A collection of token types may be found as an object as the tokenTypes export on the package.

Warning: To support syntax highlighting as you type, STRING tokens are allowed to be "unterminated". For example, the incomplete formula ="Hello world would be tokenized as:

[{type: FX_PREFIX,value: '='},{type: STRING,value: '"Hello world',unterminated: true},]

Parameters

Parameter	Type	Description
formula	string	An Excel formula string (an Excel expression).
options?	OptsTokenize	Options

Returns

Token[]

An array of Tokens

See

• OptsTokenize
• tokenTypes