@borgar/fx/docs/API.md

Utilities for working with Excel formulas

<a name="readmemd"></a>

# @borgar/fx

## Modules

- [fx](#fxreadmemd)
- [fx/xlsx](#fxxlsxreadmemd)


<a name="fxreadmemd"></a>

# 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](#fxxlsxreadmemd) variant methods.

See [Prefixes.md](./Prefixes.md) for documentation on how scopes work in Fx.

## Type Aliases

- [ArrayExpression](#fxtype-aliasesarrayexpressionmd)
- [AstExpression](#fxtype-aliasesastexpressionmd)
- [BinaryExpression](#fxtype-aliasesbinaryexpressionmd)
- [BinaryOperator](#fxtype-aliasesbinaryoperatormd)
- [CallExpression](#fxtype-aliasescallexpressionmd)
- [ErrorLiteral](#fxtype-aliaseserrorliteralmd)
- [Identifier](#fxtype-aliasesidentifiermd)
- [LambdaExpression](#fxtype-aliaseslambdaexpressionmd)
- [LetDeclarator](#fxtype-aliasesletdeclaratormd)
- [LetExpression](#fxtype-aliasesletexpressionmd)
- [Literal](#fxtype-aliasesliteralmd)
- [Node](#fxtype-aliasesnodemd)
- [OptsFixRanges](#fxtype-aliasesoptsfixrangesmd)
- [OptsParse](#fxtype-aliasesoptsparsemd)
- [OptsParseA1Ref](#fxtype-aliasesoptsparsea1refmd)
- [OptsParseR1C1Ref](#fxtype-aliasesoptsparser1c1refmd)
- [OptsStringifyStructRef](#fxtype-aliasesoptsstringifystructrefmd)
- [OptsTokenize](#fxtype-aliasesoptstokenizemd)
- [OptsTranslateFormulaToA1](#fxtype-aliasesoptstranslateformulatoa1md)
- [OptsTranslateTokensToA1](#fxtype-aliasesoptstranslatetokenstoa1md)
- [OptsTranslateToR1C1](#fxtype-aliasesoptstranslatetor1c1md)
- [RangeA1](#fxtype-aliasesrangea1md)
- [RangeR1C1](#fxtype-aliasesranger1c1md)
- [ReferenceA1](#fxtype-aliasesreferencea1md)
- [ReferenceA1Xlsx](#fxtype-aliasesreferencea1xlsxmd)
- [ReferenceIdentifier](#fxtype-aliasesreferenceidentifiermd)
- [ReferenceName](#fxtype-aliasesreferencenamemd)
- [ReferenceNameXlsx](#fxtype-aliasesreferencenamexlsxmd)
- [ReferenceR1C1](#fxtype-aliasesreferencer1c1md)
- [ReferenceR1C1Xlsx](#fxtype-aliasesreferencer1c1xlsxmd)
- [ReferenceStruct](#fxtype-aliasesreferencestructmd)
- [ReferenceStructXlsx](#fxtype-aliasesreferencestructxlsxmd)
- [SourceLocation](#fxtype-aliasessourcelocationmd)
- [Token](#fxtype-aliasestokenmd)
- [TokenEnhanced](#fxtype-aliasestokenenhancedmd)
- [UnaryExpression](#fxtype-aliasesunaryexpressionmd)
- [UnaryOperator](#fxtype-aliasesunaryoperatormd)

## Variables

- [MAX\_COLS](#fxvariablesmax_colsmd)
- [MAX\_ROWS](#fxvariablesmax_rowsmd)
- [nodeTypes](#fxvariablesnodetypesmd)
- [tokenTypes](#fxvariablestokentypesmd)

## Functions

- [addA1RangeBounds](#fxfunctionsadda1rangeboundsmd)
- [fixFormulaRanges](#fxfunctionsfixformularangesmd)
- [fixTokenRanges](#fxfunctionsfixtokenrangesmd)
- [fromCol](#fxfunctionsfromcolmd)
- [isArrayNode](#fxfunctionsisarraynodemd)
- [isBinaryNode](#fxfunctionsisbinarynodemd)
- [isCallNode](#fxfunctionsiscallnodemd)
- [isError](#fxfunctionsiserrormd)
- [isErrorNode](#fxfunctionsiserrornodemd)
- [isExpressionNode](#fxfunctionsisexpressionnodemd)
- [isFunction](#fxfunctionsisfunctionmd)
- [isFxPrefix](#fxfunctionsisfxprefixmd)
- [isIdentifierNode](#fxfunctionsisidentifiernodemd)
- [isLambdaNode](#fxfunctionsislambdanodemd)
- [isLetDeclaratorNode](#fxfunctionsisletdeclaratornodemd)
- [isLetNode](#fxfunctionsisletnodemd)
- [isLiteral](#fxfunctionsisliteralmd)
- [isLiteralNode](#fxfunctionsisliteralnodemd)
- [isOperator](#fxfunctionsisoperatormd)
- [isRange](#fxfunctionsisrangemd)
- [isReference](#fxfunctionsisreferencemd)
- [isReferenceNode](#fxfunctionsisreferencenodemd)
- [isUnaryNode](#fxfunctionsisunarynodemd)
- [isWhitespace](#fxfunctionsiswhitespacemd)
- [mergeRefTokens](#fxfunctionsmergereftokensmd)
- [parse](#fxfunctionsparsemd)
- [parseA1Range](#fxfunctionsparsea1rangemd)
- [parseA1Ref](#fxfunctionsparsea1refmd)
- [parseR1C1Range](#fxfunctionsparser1c1rangemd)
- [parseR1C1Ref](#fxfunctionsparser1c1refmd)
- [parseStructRef](#fxfunctionsparsestructrefmd)
- [stringifyA1Ref](#fxfunctionsstringifya1refmd)
- [stringifyR1C1Ref](#fxfunctionsstringifyr1c1refmd)
- [stringifyStructRef](#fxfunctionsstringifystructrefmd)
- [stringifyTokens](#fxfunctionsstringifytokensmd)
- [toCol](#fxfunctionstocolmd)
- [tokenize](#fxfunctionstokenizemd)
- [translateFormulaToA1](#fxfunctionstranslateformulatoa1md)
- [translateFormulaToR1C1](#fxfunctionstranslateformulator1c1md)
- [translateTokensToA1](#fxfunctionstranslatetokenstoa1md)
- [translateTokensToR1C1](#fxfunctionstranslatetokenstor1c1md)


<a name="fxfunctionsadda1rangeboundsmd"></a>

# addA1RangeBounds()

```ts
function addA1RangeBounds(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`.

```js
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`](#fxtype-aliasesrangea1md) | The range part of a reference object. |

## Returns

[`RangeA1`](#fxtype-aliasesrangea1md)

The same range with missing bounds filled in.


<a name="fxfunctionsfixformularangesmd"></a>

# fixFormulaRanges()

```ts
function fixFormulaRanges(formula: string, options?: OptsFixRanges & OptsTokenize): string;
```

Normalizes A1 style ranges and structured references in a formula.

Internally it uses [fixTokenRanges](#fxfunctionsfixtokenrangesmd) 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`](#fxtype-aliasesoptsfixrangesmd) & [`OptsTokenize`](#fxtype-aliasesoptstokenizemd) | Options |

## Returns

`string`

A formula string with ranges adjusted

## See

[OptsFixRanges](#fxtype-aliasesoptsfixrangesmd) & [OptsTokenize](#fxtype-aliasesoptstokenizemd)


<a name="fxfunctionsfixtokenrangesmd"></a>

# fixTokenRanges()

```ts
function fixTokenRanges(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`](#fxtype-aliasestokenmd)[] | A list of tokens to be adjusted. |
| `options?` | [`OptsFixRanges`](#fxtype-aliasesoptsfixrangesmd) | Options. |

## Returns

[`Token`](#fxtype-aliasestokenmd)[]

A token list with ranges adjusted.

## See

[OptsFixRanges](#fxtype-aliasesoptsfixrangesmd)


<a name="fxfunctionsfromcolmd"></a>

# fromCol()

```ts
function fromCol(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


<a name="fxfunctionsisarraynodemd"></a>

# isArrayNode()

```ts
function isArrayNode(node?: Node): node is ArrayExpression;
```

Determines whether the specified node is a ArrayExpression.

## Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `node?` | [`Node`](#fxtype-aliasesnodemd) | An AST node. |

## Returns

`node is ArrayExpression`

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


<a name="fxfunctionsisbinarynodemd"></a>

# isBinaryNode()

```ts
function isBinaryNode(node?: Node): node is BinaryExpression;
```

Determines whether the specified node is a BinaryExpression.

## Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `node?` | [`Node`](#fxtype-aliasesnodemd) | An AST node. |

## Returns

`node is BinaryExpression`

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


<a name="fxfunctionsiscallnodemd"></a>

# isCallNode()

```ts
function isCallNode(node?: Node): node is CallExpression;
```

Determines whether the specified node is a CallExpression.

## Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `node?` | [`Node`](#fxtype-aliasesnodemd) | An AST node. |

## Returns

`node is CallExpression`

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


<a name="fxfunctionsiserrormd"></a>

# isError()

```ts
function isError(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`](#fxtype-aliasestokenmd), `"type"`\> | The token |

## Returns

`boolean`

True if the specified token is error, False otherwise.


<a name="fxfunctionsiserrornodemd"></a>

# isErrorNode()

```ts
function isErrorNode(node?: Node): node is ErrorLiteral;
```

Determines whether the specified node is an ErrorLiteral.

## Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `node?` | [`Node`](#fxtype-aliasesnodemd) | An AST node. |

## Returns

`node is ErrorLiteral`

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


<a name="fxfunctionsisexpressionnodemd"></a>

# isExpressionNode()

```ts
function isExpressionNode(node?: Node): node is AstExpression;
```

Determines whether the specified node is a AstExpression.

## Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `node?` | [`Node`](#fxtype-aliasesnodemd) | An AST node. |

## Returns

`node is AstExpression`

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


<a name="fxfunctionsisfunctionmd"></a>

# isFunction()

```ts
function isFunction(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`](#fxtype-aliasestokenmd), `"type"`\> | The token |

## Returns

`boolean`

True if the specified token is function, False otherwise.


<a name="fxfunctionsisfxprefixmd"></a>

# isFxPrefix()

```ts
function isFxPrefix(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`](#fxtype-aliasestokenmd), `"type"`\> | The token |

## Returns

`boolean`

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


<a name="fxfunctionsisidentifiernodemd"></a>

# isIdentifierNode()

```ts
function isIdentifierNode(node?: Node): node is Identifier;
```

Determines whether the specified node is an Identifier.

## Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `node?` | [`Node`](#fxtype-aliasesnodemd) | An AST node. |

## Returns

`node is Identifier`

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


<a name="fxfunctionsislambdanodemd"></a>

# isLambdaNode()

```ts
function isLambdaNode(node?: Node): node is LambdaExpression;
```

Determines whether the specified node is a LambdaExpression.

## Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `node?` | [`Node`](#fxtype-aliasesnodemd) | An AST node. |

## Returns

`node is LambdaExpression`

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


<a name="fxfunctionsisletdeclaratornodemd"></a>

# isLetDeclaratorNode()

```ts
function isLetDeclaratorNode(node?: Node): node is LetDeclarator;
```

Determines whether the specified node is a LetDeclarator.

## Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `node?` | [`Node`](#fxtype-aliasesnodemd) | An AST node. |

## Returns

`node is LetDeclarator`

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


<a name="fxfunctionsisletnodemd"></a>

# isLetNode()

```ts
function isLetNode(node?: Node): node is LetExpression;
```

Determines whether the specified node is a LetExpression.

## Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `node?` | [`Node`](#fxtype-aliasesnodemd) | An AST node. |

## Returns

`node is LetExpression`

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


<a name="fxfunctionsisliteralmd"></a>

# isLiteral()

```ts
function isLiteral(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`](#fxtype-aliasestokenmd), `"type"`\> | The token |

## Returns

`boolean`

True if the specified token is literal, False otherwise.


<a name="fxfunctionsisliteralnodemd"></a>

# isLiteralNode()

```ts
function isLiteralNode(node?: Node): node is Literal;
```

Determines whether the specified node is a Literal.

## Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `node?` | [`Node`](#fxtype-aliasesnodemd) | An AST node. |

## Returns

`node is Literal`

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


<a name="fxfunctionsisoperatormd"></a>

# isOperator()

```ts
function isOperator(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`](#fxtype-aliasestokenmd), `"type"`\> | The token |

## Returns

`boolean`

True if the specified token is operator, False otherwise.


<a name="fxfunctionsisrangemd"></a>

# isRange()

```ts
function isRange(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`](#fxtype-aliasestokenmd), `"type"`\> | A token |

## Returns

`boolean`

True if the specified token is range, False otherwise.


<a name="fxfunctionsisreferencemd"></a>

# isReference()

```ts
function isReference(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`](#fxtype-aliasestokenmd), `"type"`\> | The token |

## Returns

`boolean`

True if the specified token is reference, False otherwise.


<a name="fxfunctionsisreferencenodemd"></a>

# isReferenceNode()

```ts
function isReferenceNode(node?: Node): node is ReferenceIdentifier;
```

Determines whether the specified node is a ReferenceIdentifier.

## Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `node?` | [`Node`](#fxtype-aliasesnodemd) | An AST node. |

## Returns

`node is ReferenceIdentifier`

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


<a name="fxfunctionsisunarynodemd"></a>

# isUnaryNode()

```ts
function isUnaryNode(node?: Node): node is UnaryExpression;
```

Determines whether the specified node is a UnaryExpression.

## Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `node?` | [`Node`](#fxtype-aliasesnodemd) | An AST node. |

## Returns

`node is UnaryExpression`

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


<a name="fxfunctionsiswhitespacemd"></a>

# isWhitespace()

```ts
function isWhitespace(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`](#fxtype-aliasestokenmd), `"type"`\> | The token |

## Returns

`boolean`

True if the specified token is whitespace, False otherwise.


<a name="fxfunctionsmergereftokensmd"></a>

# mergeRefTokens()

```ts
function mergeRefTokens(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`](#fxtype-aliasestokenmd)[] | An array of tokens. |

## Returns

[`Token`](#fxtype-aliasestokenmd)[]

A new list of tokens with range parts merged.


<a name="fxfunctionsparsemd"></a>

# parse()

```ts
function parse(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](./AST_format.md).

## Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `tokenlist` | [`Token`](#fxtype-aliasestokenmd)[] | An array of tokens. |
| `options` | [`OptsParse`](#fxtype-aliasesoptsparsemd) | Options for the parsers behavior. |

## Returns

[`AstExpression`](#fxtype-aliasesastexpressionmd)

An AST of nodes.

## See

 - [OptsParse](#fxtype-aliasesoptsparsemd)
 - [nodeTypes](#fxvariablesnodetypesmd)
 - [tokenize](#fxfunctionstokenizemd)


<a name="fxfunctionsparsea1rangemd"></a>

# parseA1Range()

```ts
function parseA1Range(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`](#fxtype-aliasesrangea1md)

A reference object.


<a name="fxfunctionsparsea1refmd"></a>

# parseA1Ref()

```ts
function parseA1Ref(refString: string, options?: OptsParseA1Ref): 
  | ReferenceA1
  | ReferenceName;
```

Parse a string reference into an object representing it.

```js
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`](#fxtype-aliasesoptsparsea1refmd) | Options. |

## Returns

  \| [`ReferenceA1`](#fxtype-aliasesreferencea1md)
  \| [`ReferenceName`](#fxtype-aliasesreferencenamemd)

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

## See

[OptsParseA1Ref](#fxtype-aliasesoptsparsea1refmd)


<a name="fxfunctionsparser1c1rangemd"></a>

# parseR1C1Range()

```ts
function parseR1C1Range(rangeString: string): RangeR1C1;
```

Parse R1C1-style range string into a RangeR1C1 object.

## Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `rangeString` | `string` | R1C1-style range string. |

## Returns

[`RangeR1C1`](#fxtype-aliasesranger1c1md)

A reference object.


<a name="fxfunctionsparser1c1refmd"></a>

# parseR1C1Ref()

```ts
function parseR1C1Ref(refString: string, options?: OptsParseR1C1Ref): 
  | ReferenceName
  | ReferenceR1C1;
```

Parse a string reference into an object representing it.

```js
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`](#fxtype-aliasesoptsparser1c1refmd) | Options. |

## Returns

  \| [`ReferenceName`](#fxtype-aliasesreferencenamemd)
  \| [`ReferenceR1C1`](#fxtype-aliasesreferencer1c1md)

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

## See

[OptsParseR1C1Ref](#fxtype-aliasesoptsparser1c1refmd)


<a name="fxfunctionsparsestructrefmd"></a>

# parseStructRef()

```ts
function parseStructRef(ref: string): ReferenceStruct;
```

Parse a structured reference string into an object representing it.

```js
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](./References.md).

## Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `ref` | `string` | A structured reference string |

## Returns

[`ReferenceStruct`](#fxtype-aliasesreferencestructmd)

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


<a name="fxfunctionsstringifya1refmd"></a>

# stringifyA1Ref()

```ts
function stringifyA1Ref(refObject: 
  | ReferenceA1
  | ReferenceName): string;
```

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

```js
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`](#fxtype-aliasesreferencea1md) \| [`ReferenceName`](#fxtype-aliasesreferencenamemd) | A reference object. |

## Returns

`string`

The reference in A1-style string format.


<a name="fxfunctionsstringifyr1c1refmd"></a>

# stringifyR1C1Ref()

```ts
function stringifyR1C1Ref(refObject: 
  | ReferenceName
  | ReferenceR1C1): string;
```

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

```js
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`](#fxtype-aliasesreferencenamemd) \| [`ReferenceR1C1`](#fxtype-aliasesreferencer1c1md) | A reference object. |

## Returns

`string`

The reference in R1C1-style string format.


<a name="fxfunctionsstringifystructrefmd"></a>

# stringifyStructRef()

```ts
function stringifyStructRef(refObject: ReferenceStruct, options?: OptsStringifyStructRef): string;
```

Returns a string representation of a structured reference object.

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

## Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `refObject` | [`ReferenceStruct`](#fxtype-aliasesreferencestructmd) | A structured reference object. |
| `options?` | [`OptsStringifyStructRef`](#fxtype-aliasesoptsstringifystructrefmd) | Options. |

## Returns

`string`

The given structured reference in string format.

## See

[OptsStringifyStructRef](#fxtype-aliasesoptsstringifystructrefmd)


<a name="fxfunctionsstringifytokensmd"></a>

# stringifyTokens()

```ts
function stringifyTokens(tokens: Token[]): string;
```

Collapses a list of tokens into a formula string.

## Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `tokens` | [`Token`](#fxtype-aliasestokenmd)[] | A list of tokens. |

## Returns

`string`

A formula string.


<a name="fxfunctionstocolmd"></a>

# toCol()

```ts
function toCol(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


<a name="fxfunctionstokenizemd"></a>

# tokenize()

```ts
function tokenize(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:

```js
[
  { 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](#fxvariablestokentypesmd)
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:

```js
[
  { 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`](#fxtype-aliasesoptstokenizemd) | Options |

## Returns

[`Token`](#fxtype-aliasestokenmd)[]

An array of Tokens

## See

 - [OptsTokenize](#fxtype-aliasesoptstokenizemd)
 - [tokenTypes](#fxvariablestokentypesmd)


<a name="fxfunctionstranslateformulatoa1md"></a>

# translateFormulaToA1()

```ts
function translateFormulaToA1(
   formula: string, 
   anchorCell: string, 
   options?: OptsTranslateFormulaToA1): string;
```

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

```js
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.

```js
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`](#fxtype-aliasesoptstranslateformulatoa1md) | Translation options. |

## Returns

`string`

A formula string.

## See

[OptsTranslateFormulaToA1](#fxtype-aliasesoptstranslateformulatoa1md)


<a name="fxfunctionstranslateformulator1c1md"></a>

# translateFormulaToR1C1()

```ts
function translateFormulaToR1C1(
   formula: string, 
   anchorCell: string, 
   options?: OptsTranslateToR1C1): string;
```

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

```js
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`](#fxtype-aliasesoptstranslatetor1c1md) | The options |

## Returns

`string`

A formula string.

## See

[OptsTranslateToR1C1](#fxtype-aliasesoptstranslatetor1c1md)


<a name="fxfunctionstranslatetokenstoa1md"></a>

# translateTokensToA1()

```ts
function translateTokensToA1(
   tokens: Token[], 
   anchorCell: string, 
   options?: OptsTranslateTokensToA1): Token[];
```

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

```js
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.

```js
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`](#fxtype-aliasestokenmd)[] | A token list that should be adjusted. |
| `anchorCell` | `string` | A simple string reference to an A1 cell ID (`AF123` or`$C$5`). |
| `options` | [`OptsTranslateTokensToA1`](#fxtype-aliasesoptstranslatetokenstoa1md) | Translation options. |

## Returns

[`Token`](#fxtype-aliasestokenmd)[]

A token list.

## See

[OptsTranslateTokensToA1](#fxtype-aliasesoptstranslatetokenstoa1md)


<a name="fxfunctionstranslatetokenstor1c1md"></a>

# translateTokensToR1C1()

```ts
function translateTokensToR1C1(tokens: Token[], anchorCell: string): Token[];
```

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

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

## Parameters

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

## Returns

[`Token`](#fxtype-aliasestokenmd)[]

A token list.


<a name="fxtype-aliasesarrayexpressionmd"></a>

# ArrayExpression

```ts
type ArrayExpression = {
  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 `ReferenceIdentifier`s and `CallExpression`s as elements of
arrays, the fx parser has options for this but they are off by default.

## Type Declaration

| Name | Type | Description |
| ------ | ------ | ------ |
| `elements` | ( \| [`ReferenceIdentifier`](#fxtype-aliasesreferenceidentifiermd) \| [`Literal`](#fxtype-aliasesliteralmd) \| [`ErrorLiteral`](#fxtype-aliaseserrorliteralmd) \| [`CallExpression`](#fxtype-aliasescallexpressionmd))[][] | The elements of the array. |
| `loc?` | [`SourceLocation`](#fxtype-aliasessourcelocationmd) | The original source position of the node. |
| `type` | `"ArrayExpression"` | The type of this AST node. |


<a name="fxtype-aliasesastexpressionmd"></a>

# AstExpression

```ts
type AstExpression = 
  | ReferenceIdentifier
  | Literal
  | ErrorLiteral
  | UnaryExpression
  | BinaryExpression
  | CallExpression
  | ArrayExpression
  | LambdaExpression
  | LetExpression;
```

Represents an evaluate-able expression.


<a name="fxtype-aliasesbinaryexpressionmd"></a>

# BinaryExpression

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

A binary operator expression.

## Type Declaration

| Name | Type | Description |
| ------ | ------ | ------ |
| `arguments` | [`AstExpression`](#fxtype-aliasesastexpressionmd)[] | The arguments for the operator. |
| `loc?` | [`SourceLocation`](#fxtype-aliasessourcelocationmd) | The original source position of the node. |
| `operator` | [`BinaryOperator`](#fxtype-aliasesbinaryoperatormd) | The expression's operator. |
| `type` | `"BinaryExpression"` | The type of this AST node. |


<a name="fxtype-aliasesbinaryoperatormd"></a>

# BinaryOperator

```ts
type BinaryOperator = 
  | "="
  | "<"
  | ">"
  | "<="
  | ">="
  | "<>"
  | "-"
  | "+"
  | "*"
  | "/"
  | "^"
  | ":"
  | " "
  | ","
  | "&";
```

A binary operator token.

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


<a name="fxtype-aliasescallexpressionmd"></a>

# CallExpression

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

A function call expression.

## Type Declaration

| Name | Type | Description |
| ------ | ------ | ------ |
| `arguments` | [`AstExpression`](#fxtype-aliasesastexpressionmd)[] | The arguments for the function. |
| `callee` | [`Identifier`](#fxtype-aliasesidentifiermd) | The function being called. |
| `loc?` | [`SourceLocation`](#fxtype-aliasessourcelocationmd) | The original source position of the node. |
| `type` | `"CallExpression"` | The type of this AST node. |


<a name="fxtype-aliaseserrorliteralmd"></a>

# ErrorLiteral

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

An Error expression.

## Type Declaration

| Name | Type | Description |
| ------ | ------ | ------ |
| `loc?` | [`SourceLocation`](#fxtype-aliasessourcelocationmd) | 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. |


<a name="fxtype-aliasesidentifiermd"></a>

# Identifier

```ts
type Identifier = {
  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`](#fxtype-aliasessourcelocationmd) | The original source position of the node. |
| `name` | `string` | The identifying name. |
| `type` | `"Identifier"` | The type of this AST node. |


<a name="fxtype-aliaseslambdaexpressionmd"></a>

# LambdaExpression

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

A LAMBDA expression.

## Type Declaration

| Name | Type | Description |
| ------ | ------ | ------ |
| `body` | [`AstExpression`](#fxtype-aliasesastexpressionmd) \| `null` | The LAMBDA's expression. |
| `loc?` | [`SourceLocation`](#fxtype-aliasessourcelocationmd) | The original source position of the node. |
| `params` | [`Identifier`](#fxtype-aliasesidentifiermd)[] | The LAMBDA's parameters. |
| `type` | `"LambdaExpression"` | The type of this AST node. |


<a name="fxtype-aliasesletdeclaratormd"></a>

# LetDeclarator

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

A LET parameter declaration.

## Type Declaration

| Name | Type | Description |
| ------ | ------ | ------ |
| `id` | [`Identifier`](#fxtype-aliasesidentifiermd) | The name of the variable. |
| `init` | [`AstExpression`](#fxtype-aliasesastexpressionmd) \| `null` | The variable's initializing expression. |
| `loc?` | [`SourceLocation`](#fxtype-aliasessourcelocationmd) | The original source position of the node. |
| `type` | `"LetDeclarator"` | The type of this AST node. |


<a name="fxtype-aliasesletexpressionmd"></a>

# LetExpression

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

A LET expression.

## Type Declaration

| Name | Type | Description |
| ------ | ------ | ------ |
| `body` | [`AstExpression`](#fxtype-aliasesastexpressionmd) \| `null` | The LET's scoped expression. |
| `declarations` | [`LetDeclarator`](#fxtype-aliasesletdeclaratormd)[] | The LET's variable declarations. |
| `loc?` | [`SourceLocation`](#fxtype-aliasessourcelocationmd) | The original source position of the node. |
| `type` | `"LetExpression"` | The type of this AST node. |


<a name="fxtype-aliasesliteralmd"></a>

# Literal

```ts
type Literal = {
  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`](#fxtype-aliasessourcelocationmd) | 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. |


<a name="fxtype-aliasesnodemd"></a>

# Node

```ts
type Node = {
  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 |
| ------ | ------ | ------ |
| <a id="property-loc"></a> `loc?` | [`SourceLocation`](#fxtype-aliasessourcelocationmd) | The original source position of the node. |
| <a id="property-type"></a> `type` | `string` | The type of this AST node. |


<a name="fxtype-aliasesoptsfixrangesmd"></a>

# OptsFixRanges

```ts
type OptsFixRanges = {
  addBounds?: boolean;
  thisRow?: boolean;
};
```

Options for [fixTokenRanges](#fxfunctionsfixtokenrangesmd) and [fixFormulaRanges](#fxfunctionsfixformularangesmd).

## Properties

| Property | Type | Default value | Description |
| ------ | ------ | ------ | ------ |
| <a id="property-addbounds"></a> `addBounds?` | `boolean` | `false` | Fill in any undefined bounds of range objects. Top to 0, bottom to 1048575, left to 0, and right to 16383. |
| <a id="property-thisrow"></a> `thisRow?` | `boolean` | `false` | Enforces using the `[#This Row]` instead of the `@` shorthand when serializing structured ranges. |


<a name="fxtype-aliasesoptsparsemd"></a>

# OptsParse

```ts
type OptsParse = {
  looseRefCalls?: boolean;
  permitArrayCalls?: boolean;
  permitArrayRanges?: boolean;
};
```

Options for [parse](#fxfunctionsparsemd).

## Properties

| Property | Type | Default value | Description |
| ------ | ------ | ------ | ------ |
| <a id="property-looserefcalls"></a> `looseRefCalls?` | `boolean` | `false` | Permits any function call where otherwise only functions that return references would be permitted. |
| <a id="property-permitarraycalls"></a> `permitArrayCalls?` | `boolean` | `false` | Function calls are allowed as elements of arrays. This is a feature in Google Sheets while Excel does not allow it. |
| <a id="property-permitarrayranges"></a> `permitArrayRanges?` | `boolean` | `false` | Ranges are allowed as elements of arrays. This is a feature in Google Sheets while Excel does not allow it. |


<a name="fxtype-aliasesoptsparsea1refmd"></a>

# OptsParseA1Ref

```ts
type OptsParseA1Ref = {
  allowNamed?: boolean;
  allowTernary?: boolean;
};
```

Options for [parseA1Ref](#fxfunctionsparsea1refmd).

## Properties

| Property | Type | Default value | Description |
| ------ | ------ | ------ | ------ |
| <a id="property-allownamed"></a> `allowNamed?` | `boolean` | `true` | Enable parsing names as well as ranges. |
| <a id="property-allowternary"></a> `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](./References.md). |


<a name="fxtype-aliasesoptsparser1c1refmd"></a>

# OptsParseR1C1Ref

```ts
type OptsParseR1C1Ref = {
  allowNamed?: boolean;
  allowTernary?: boolean;
};
```

Options for [parseR1C1Ref](#fxfunctionsparser1c1refmd).

## Properties

| Property | Type | Default value | Description |
| ------ | ------ | ------ | ------ |
| <a id="property-allownamed"></a> `allowNamed?` | `boolean` | `true` | Enable parsing names as well as ranges. |
| <a id="property-allowternary"></a> `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](./References.md). |


<a name="fxtype-aliasesoptsstringifystructrefmd"></a>

# OptsStringifyStructRef

```ts
type OptsStringifyStructRef = {
  thisRow?: boolean;
};
```

Options for [stringifyStructRef](#fxfunctionsstringifystructrefmd)

## Properties

| Property | Type | Default value | Description |
| ------ | ------ | ------ | ------ |
| <a id="property-thisrow"></a> `thisRow?` | `boolean` | `false` | Enforces using the `[#This Row]` instead of the `@` shorthand when serializing structured ranges. |


<a name="fxtype-aliasesoptstokenizemd"></a>

# OptsTokenize

```ts
type OptsTokenize = {
  allowTernary?: boolean;
  mergeRefs?: boolean;
  negativeNumbers?: boolean;
  r1c1?: boolean;
  withLocation?: boolean;
};
```

Options for [tokenize](#fxfunctionstokenizemd).

## Properties

| Property | Type | Default value | Description |
| ------ | ------ | ------ | ------ |
| <a id="property-allowternary"></a> `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](./References.md). |
| <a id="property-mergerefs"></a> `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`](#mergeRefTokens) |
| <a id="property-negativenumbers"></a> `negativeNumbers?` | `boolean` | `true` | Merges unary minuses with their immediately following number tokens (`-`,`1`) => `-1` (alternatively these will be unary operations in the tree). |
| <a id="property-r1c1"></a> `r1c1?` | `boolean` | `false` | Ranges are expected to be in the R1C1 style format rather than the more popular A1 style. |
| <a id="property-withlocation"></a> `withLocation?` | `boolean` | `true` | Nodes will include source position offsets to the tokens: `{ loc: [ start, end ] }` |


<a name="fxtype-aliasesoptstranslateformulatoa1md"></a>

# OptsTranslateFormulaToA1

```ts
type OptsTranslateFormulaToA1 = {
  allowTernary?: boolean;
  mergeRefs?: boolean;
  wrapEdges?: boolean;
};
```

Options for [translateFormulaToA1](#fxfunctionstranslateformulatoa1md).

## Properties

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


<a name="fxtype-aliasesoptstranslatetor1c1md"></a>

# OptsTranslateToR1C1

```ts
type OptsTranslateToR1C1 = {
  allowTernary?: boolean;
};
```

Options for [translateFormulaToR1C1](#fxfunctionstranslateformulator1c1md).

## Properties

| Property | Type | Default value | Description |
| ------ | ------ | ------ | ------ |
| <a id="property-allowternary"></a> `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](./References.md). |


<a name="fxtype-aliasesoptstranslatetokenstoa1md"></a>

# OptsTranslateTokensToA1

```ts
type OptsTranslateTokensToA1 = {
  wrapEdges?: boolean;
};
```

Options for [translateTokensToA1](#fxfunctionstranslatetokenstoa1md)

## Properties

| Property | Type | Default value | Description |
| ------ | ------ | ------ | ------ |
| <a id="property-wrapedges"></a> `wrapEdges?` | `boolean` | `true` | Wrap out-of-bounds ranges around sheet edges rather than turning them to #REF! errors. |


<a name="fxtype-aliasesrangea1md"></a>

# RangeA1

```ts
type RangeA1 = {
  $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 |
| ------ | ------ | ------ |
| <a id="property-bottom"></a> `$bottom?` | `boolean` \| `null` | Signifies that bottom is a "locked" value |
| <a id="property-left"></a> `$left?` | `boolean` \| `null` | Signifies that left is a "locked" value |
| <a id="property-right"></a> `$right?` | `boolean` \| `null` | Signifies that right is a "locked" value |
| <a id="property-top"></a> `$top?` | `boolean` \| `null` | Signifies that top is a "locked" value |
| <a id="property-bottom-1"></a> `bottom?` | `number` \| `null` | Bottom row of the range |
| <a id="property-left-1"></a> `left` | `number` \| `null` | Left column of the range |
| <a id="property-right-1"></a> `right?` | `number` \| `null` | Right column of the range |
| <a id="property-top-1"></a> `top` | `number` \| `null` | Top row of the range |
| <a id="property-trim"></a> `trim?` | `"head"` \| `"tail"` \| `"both"` \| `null` | Should empty rows and columns at the top/left or bottom/right be discarded when range is read? |


<a name="fxtype-aliasesranger1c1md"></a>

# RangeR1C1

```ts
type RangeR1C1 = {
  $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 |
| ------ | ------ | ------ |
| <a id="property-c0"></a> `$c0?` | `boolean` \| `null` | Signifies that c0 is an absolute value |
| <a id="property-c1"></a> `$c1?` | `boolean` \| `null` | Signifies that c1 is an absolute value |
| <a id="property-r0"></a> `$r0?` | `boolean` \| `null` | Signifies that r0 is an absolute value |
| <a id="property-r1"></a> `$r1?` | `boolean` \| `null` | Signifies that r1 is an absolute value |
| <a id="property-c0-1"></a> `c0?` | `number` \| `null` | Left column of the range |
| <a id="property-c1-1"></a> `c1?` | `number` \| `null` | Right column of the range |
| <a id="property-r0-1"></a> `r0?` | `number` \| `null` | Top row of the range |
| <a id="property-r1-1"></a> `r1?` | `number` \| `null` | Bottom row of the range |
| <a id="property-trim"></a> `trim?` | `"head"` \| `"tail"` \| `"both"` \| `null` | Should empty rows and columns at the top/left or bottom/right be discarded when range is read? |


<a name="fxtype-aliasesreferencea1md"></a>

# ReferenceA1

```ts
type ReferenceA1 = {
  context?: string[];
  range: RangeA1;
};
```

A reference containing an A1 style r