@borgar/fx 4.3.1 → 4.5.0

package/dist/fx.d.ts

@@ -0,0 +1,653 @@
+/**
+ * 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({
+ *   context: [ 'Sheet1' ],
+ *   range: {
+ *     top: 0,
+ *     left: 0,
+ *     bottom: 1,
+ *     $top: true,
+ *     $left: false,
+ *     $bottom: false,
+ *   }
+ * });
+ * // => {
+ * //   context: [ 'Sheet1' ],
+ * //   range: {
+ * //     top: 0,
+ * //     left: 0,
+ * //     bottom: 1,
+ * //     right: 16383,
+ * //     $top: true,
+ * //     $left: false,
+ * //     $bottom: false,
+ * //     $right: false
+ * //   }
+ * // }
+ * ```
+ *
+ * @param range The range part of a reference object.
+ * @returns same range with missing bounds filled in.
+ */
+export declare function addA1RangeBounds(range: object): object;
+
+/**
+ * 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`).
+ *
+ * @param tokenlist An array of tokens (from `tokenize()`)
+ * @param [context={}] A contest used to match `A1` to `Sheet1!A1`.
+ * @param [context.sheetName=''] An implied sheet name ('Sheet1')
+ * @param [context.workbookName=''] An implied workbook name ('report.xlsx')
+ * @returns The input array with the enchanced tokens
+ */
+export declare function addTokenMeta(tokenlist: Array<object>, context?: {
+    /** An implied sheet name ('Sheet1') */
+    sheetName?: string;
+    /** An implied workbook name ('report.xlsx') */
+    workbookName?: string;
+}): Array<object>;
+
+/**
+ * Normalizes A1 style ranges and structured references in a formula or 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: true }` is passed as an option, the missing bounds are
+ * also added. This can be done to ensure Excel compatible ranges. The fixes
+ * then additionally include:
+ * `1:A1` → `A1:1` → `1:1`  
+ * `A:A1` → `A1:A` → `A:A`  
+ * `A1:A` → `A:A`  
+ * `A1:1` → `A:1`  
+ * `B2:B` → `B2:1048576`  
+ * `B2:2` → `B2:XFD2`  
+ * Structured ranges are normalized cleaned up to have consistent order and
+ * capitalization of sections as well as removing redundant ones.
+ * Returns the same formula with the ranges updated. If an array of tokens was
+ * supplied, then a new array is returned.
+ *
+ * @param formula A string (an Excel formula) or a token list that should be adjusted.
+ * @param [options={}] Options
+ * @param [options.addBounds=false] Fill in any undefined bounds of range objects. Top to 0, bottom to 1048575, left to 0, and right to 16383.
+ * @param [options.xlsx=false] Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md)
+ * @returns A formula string or token list (depending on which was input)
+ */
+export declare function fixRanges(formula: (string | Array<object>), options?: {
+    /** Fill in any undefined bounds of range objects. Top to 0, bottom to 1048575, left to 0, and right to 16383. */
+    addBounds?: boolean;
+    /** Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md) */
+    xlsx?: boolean;
+}): (string | Array<object>);
+
+/**
+ * Parse a simple string reference to an A1 range into a range object.
+ * Will accept `A1`, `A2`, `A:A`, or `1:1`.
+ *
+ * @param rangeString A range string
+ * @returns An object representing a valid reference or null if it is invalid.
+ */
+declare function fromA1(rangeString: string): (object | null);
+
+/**
+ * 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.
+ *
+ * @param columnString The column string identifier
+ * @returns Zero based column index number
+ */
+export declare function fromCol(columnString: string): number;
+
+/**
+ * Parse a simple string reference to an R1C1 range into a range object.
+ *
+ * @param rangeString A range string
+ * @returns An object representing a valid reference or null if it is invalid.
+ */
+declare function fromR1C1(rangeString: string): (object | null);
+
+/**
+ * Determines whether the specified token is an error.
+ * Returns `true` if the input is a token of type ERROR (`#VALUE!`). In all
+ * other cases `false` is returned.
+ *
+ * @param token The token
+ * @returns True if the specified token is error, False otherwise.
+ */
+export declare function isError(token: object): 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.
+ *
+ * @param token The token
+ * @returns True if the specified token is function, False otherwise.
+ */
+export declare function isFunction(token: object): boolean;
+
+/**
+ * Returns `true` if the input is a token of type FX_PREFIX (leading `=` in
+ * formula). In all other cases `false` is returned.
+ *
+ * @param token The token
+ * @returns True if the specified token is effects prefix, False otherwise.
+ */
+export declare function isFxPrefix(token: object): 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.
+ *
+ * @param token The token
+ * @returns True if the specified token is literal, False otherwise.
+ */
+export declare function isLiteral(token: object): 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.
+ *
+ * @param token The token
+ * @returns True if the specified token is operator, False otherwise.
+ */
+export declare function isOperator(token: object): 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.
+ *
+ * @param token A token
+ * @returns True if the specified token is range, False otherwise.
+ */
+export declare function isRange(token: object): 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.
+ *
+ * @param token The token
+ * @returns True if the specified token is reference, False otherwise.
+ */
+export declare function isReference(token: object): 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.
+ *
+ * @param token The token
+ * @returns True if the specified token is whitespace, False otherwise.
+ */
+export declare function isWhitespace(token: object): boolean;
+
+/**
+ * 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`).
+ *
+ * @param tokenlist An array of tokens (from `tokenize()`)
+ * @returns A new list of tokens with range parts merged.
+ */
+export declare function mergeRefTokens(tokenlist: Array<object>): Array<any>;
+
+/**
+ * Parses a string formula or list of tokens into an AST.
+ * The parser requires `mergeRefs` to have been `true` in tokenlist options,
+ * because it does not recognize reference context tokens.
+ * The AST Abstract Syntax Tree's format is documented in
+ * [AST_format.md](./AST_format.md)
+ *
+ * @param formula An Excel formula string (an Excel expression) or an array of tokens.
+ * @param [options={}] Options
+ * @param [options.allowNamed=true] Enable parsing names as well as ranges.
+ * @param [options.allowTernary=false] Enables the recognition of ternary ranges in the style of `A1:A` or `A1:1`. These are supported by Google Sheets but not Excel. See: References.md.
+ * @param [options.negativeNumbers=true] Merges unary minuses with their immediately following number tokens (`-`,`1`) => `-1` (alternatively these will be unary operations in the tree).
+ * @param [options.permitArrayCalls=false] Function calls are allowed as elements of arrays. This is a feature in Google Sheets while Excel does not allow it.
+ * @param [options.permitArrayRanges=false] Ranges are allowed as elements of arrays. This is a feature in Google Sheets while Excel does not allow it.
+ * @param [options.r1c1=false] Ranges are expected to be in the R1C1 style format rather than the more popular A1 style.
+ * @param [options.withLocation=false] Nodes will include source position offsets to the tokens: `{ loc: [ start, end ] }`
+ * @param [options.xlsx=false] Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md)
+ * @returns An AST of nodes
+ */
+export declare function parse(formula: (string | Array<object>), options?: {
+    /** Enable parsing names as well as ranges. */
+    allowNamed?: boolean;
+    /** 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. */
+    allowTernary?: boolean;
+    /** Merges unary minuses with their immediately following number tokens (`-`,`1`) => `-1` (alternatively these will be unary operations in the tree). */
+    negativeNumbers?: boolean;
+    /** Function calls are allowed as elements of arrays. This is a feature in Google Sheets while Excel does not allow it. */
+    permitArrayCalls?: boolean;
+    /** Ranges are allowed as elements of arrays. This is a feature in Google Sheets while Excel does not allow it. */
+    permitArrayRanges?: boolean;
+    /** Ranges are expected to be in the R1C1 style format rather than the more popular A1 style. */
+    r1c1?: boolean;
+    /** Nodes will include source position offsets to the tokens: `{ loc: [ start, end ] }` */
+    withLocation?: boolean;
+    /** Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md) */
+    xlsx?: boolean;
+}): object;
+
+/**
+ * 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:
+ *
+ * @param refString An A1-style reference string
+ * @param [options={}] Options
+ * @param [options.allowNamed=true] Enable parsing names as well as ranges.
+ * @param [options.allowTernary=false] Enables the recognition of ternary ranges in the style of `A1:A` or `A1:1`. These are supported by Google Sheets but not Excel. See: References.md.
+ * @param [options.xlsx=false] Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md)
+ * @returns An object representing a valid reference or null if it is invalid.
+ */
+export declare function parseA1Ref(refString: string, options?: {
+    /** Enable parsing names as well as ranges. */
+    allowNamed?: boolean;
+    /** 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. */
+    allowTernary?: boolean;
+    /** Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md) */
+    xlsx?: boolean;
+}): (object | null);
+
+/**
+ * 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
+ * //   }
+ * // }
+ * ```
+ *
+ * @param refString An R1C1-style reference string
+ * @param [options={}] Options
+ * @param [options.allowNamed=true] Enable parsing names as well as ranges.
+ * @param [options.allowTernary=false] Enables the recognition of ternary ranges in the style of `A1:A` or `A1:1`. These are supported by Google Sheets but not Excel. See: References.md.
+ * @param [options.xlsx=false] Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md)
+ * @returns An object representing a valid reference or null if it is invalid.
+ */
+export declare function parseR1C1Ref(refString: string, options?: {
+    /** Enable parsing names as well as ranges. */
+    allowNamed?: boolean;
+    /** 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. */
+    allowTernary?: boolean;
+    /** Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md) */
+    xlsx?: boolean;
+}): (object | null);
+
+/**
+ * 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:
+ *
+ * @param ref A structured reference string
+ * @param [options={}] Options
+ * @param [options.xlsx=false] Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md)
+ * @returns An object representing a valid reference or null if it is invalid.
+ */
+export declare function parseStructRef(ref: string, options?: {
+    /** Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md) */
+    xlsx?: boolean;
+}): (object | null);
+
+/**
+ * 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'
+ * ```
+ *
+ * @param refObject A reference object
+ * @param [options={}] Options
+ * @param [options.xlsx=false] Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md)
+ * @returns The reference in A1-style string format
+ */
+export declare function stringifyA1Ref(refObject: object, options?: {
+    /** Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md) */
+    xlsx?: boolean;
+}): object;
+
+/**
+ * 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'
+ * ```
+ *
+ * @param refObject A reference object
+ * @param [options={}] Options
+ * @param [options.xlsx=false] Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md)
+ * @returns The reference in R1C1-style string format
+ */
+export declare function stringifyR1C1Ref(refObject: object, options?: {
+    /** Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md) */
+    xlsx?: boolean;
+}): object;
+
+/**
+ * Get 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]]'
+ * ```
+ *
+ * @param refObject A structured reference object
+ * @param [options={}] Options
+ * @param [options.xlsx=false] Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md)
+ * @returns The structured reference in string format
+ */
+export declare function stringifyStructRef(refObject: object, options?: {
+    /** Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md) */
+    xlsx?: boolean;
+}): object;
+
+/**
+ * Stringify a range object into A1 syntax.
+ *
+ * @param range A range object
+ * @returns An A1-style string represenation of a range
+ */
+declare function toA1(range: object): string;
+
+/**
+ * Convert a 0 based offset number to a column string
+ * representation (`2` = `"C"`).
+ * The method expects a number between 0 and 16383. Other input will
+ * return garbage.
+ *
+ * @param columnIndex Zero based column index number
+ * @returns The column string identifier
+ */
+export declare function toCol(columnIndex: number): string;
+
+/**
+ * Stringify a range object into R1C1 syntax.
+ *
+ * @param range A range object
+ * @returns An R1C1-style string represenation of a range
+ */
+declare function toR1C1(range: object): string;
+
+/**
+ * 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: ')' }
+ * ]
+ * ```
+ * Token types may be found as an Object as the
+ * [`tokenTypes` export]{@link tokenTypes} on the package
+ * (`import {tokenTypes} from '@borgar/fx';`).
+ * 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 },
+ * ]
+ * ```
+ *
+ * @param formula An Excel formula string (an Excel expression) or an array of tokens.
+ * @param [options={}] Options
+ * @param [options.allowTernary=false] Enables the recognition of ternary ranges in the style of `A1:A` or `A1:1`. These are supported by Google Sheets but not Excel. See: References.md.
+ * @param [options.mergeRefs=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)
+ * @param [options.negativeNumbers=true] Merges unary minuses with their immediately following number tokens (`-`,`1`) => `-1` (alternatively these will be unary operations in the tree).
+ * @param [options.r1c1=false] Ranges are expected to be in the R1C1 style format rather than the more popular A1 style.
+ * @param [options.withLocation=true] Nodes will include source position offsets to the tokens: `{ loc: [ start, end ] }`
+ * @param [options.xlsx=false] Enables a `[1]Sheet1!A1` or `[1]!name` syntax form for external workbooks found only in XLSX files.
+ * @returns An AST of nodes
+ */
+export declare function tokenize(formula: string, options?: {
+    /** 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. */
+    allowTernary?: boolean;
+    /** 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) */
+    mergeRefs?: boolean;
+    /** Merges unary minuses with their immediately following number tokens (`-`,`1`) => `-1` (alternatively these will be unary operations in the tree). */
+    negativeNumbers?: boolean;
+    /** Ranges are expected to be in the R1C1 style format rather than the more popular A1 style. */
+    r1c1?: boolean;
+    /** Nodes will include source position offsets to the tokens: `{ loc: [ start, end ] }` */
+    withLocation?: boolean;
+    /** Enables a `[1]Sheet1!A1` or `[1]!name` syntax form for external workbooks found only in XLSX files. */
+    xlsx?: boolean;
+}): Array<object>;
+
+/**
+ * Translates ranges in a formula or list of tokens from relative R1C1 syntax to
+ * absolute A1 syntax.
+ * Returns the same formula with the ranges translated. If an array of tokens
+ * was supplied, then the same array is returned.
+ * ```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.
+ *
+ * @param formula A string (an Excel formula) or a token list that should be adjusted.
+ * @param anchorCell A simple string reference to an A1 cell ID (`AF123` or`$C$5`).
+ * @param [options={}] The options
+ * @param [options.allowTernary=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.
+ * @param [options.mergeRefs=true] Should ranges be treated as whole references (`Sheet1!A1:B2`) or as separate tokens for each part: (`Sheet1`,`!`,`A1`,`:`,`B2`).
+ * @param [options.wrapEdges=true] Wrap out-of-bounds ranges around sheet edges rather than turning them to #REF! errors
+ * @param [options.xlsx=false] Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md)
+ * @returns A formula string or token list (depending on which was input)
+ */
+export declare function translateToA1(formula: (string | Array<object>), anchorCell: string, options?: {
+    /** 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. */
+    allowTernary?: boolean;
+    /** Should ranges be treated as whole references (`Sheet1!A1:B2`) or as separate tokens for each part: (`Sheet1`,`!`,`A1`,`:`,`B2`). */
+    mergeRefs?: boolean;
+    /** Wrap out-of-bounds ranges around sheet edges rather than turning them to #REF! errors */
+    wrapEdges?: boolean;
+    /** Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md) */
+    xlsx?: boolean;
+}): (string | Array<object>);
+
+/**
+ * Translates ranges in a formula or list of tokens from absolute A1 syntax to
+ * relative R1C1 syntax.
+ * Returns the same formula with the ranges translated. If an array of tokens
+ * was supplied, then the same array is returned.
+ * ```js
+ * translateToR1C1("=SUM(E10,$E$2,Sheet!$E$3)", "D10");
+ * // => "=SUM(RC[1],R2C5,Sheet!R3C5)");
+ * ```
+ *
+ * @param formula A string (an Excel formula) or a token list that should be adjusted.
+ * @param anchorCell A simple string reference to an A1 cell ID (`AF123` or`$C$5`).
+ * @param [options={}] The options
+ * @param [options.allowTernary=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.
+ * @param [options.xlsx=false] Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md)
+ * @returns A formula string or token list (depending on which was input)
+ */
+export declare function translateToR1C1(formula: (string | Array<object>), anchorCell: string, options?: {
+    /** 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. */
+    allowTernary?: boolean;
+    /** Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md) */
+    xlsx?: boolean;
+}): (string | Array<object>);
+
+/** A dictionary of the types used to identify AST node variants. */
+export declare const nodeTypes: Readonly<{
+    /** An array expression (`{1,2;3,4}`) */
+    ARRAY: string;
+    /** A binary operation (`10+10`) */
+    BINARY: string;
+    /** A function call expression (`SUM(1,2)`) */
+    CALL: string;
+    /** An error literal (`#VALUE!`) */
+    ERROR: string;
+    /** A function name identifier (`SUM`) */
+    IDENTIFIER: string;
+    /** A literal (number, string, or boolean) (`123`, `"foo"`, `false`) */
+    LITERAL: string;
+    /** A range identifier (`A1`) */
+    REFERENCE: string;
+    /** A unary operation (`10%`) */
+    UNARY: string;
+}>;
+
+/** A dictionary of the types used to identify token variants. */
+export declare const tokenTypes: Readonly<{
+    /** Boolean literal (`TRUE`) */
+    BOOLEAN: string;
+    /** Reference context ([Workbook.xlsx]Sheet1) */
+    CONTEXT: string;
+    /** Quoted reference context (`'[My workbook.xlsx]Sheet1'`) */
+    CONTEXT_QUOTE: string;
+    /** Error literal (`#VALUE!`) */
+    ERROR: string;
+    /** Function name (`SUM`) */
+    FUNCTION: string;
+    /** A leading equals sign at the start of a formula (`=`) */
+    FX_PREFIX: string;
+    /** Newline character (`\n`) */
+    NEWLINE: string;
+    /** Number literal (`123.4`, `-1.5e+2`) */
+    NUMBER: string;
+    /** Newline (`\n`) */
+    OPERATOR: string;
+    /** A range "beam" identifier (`A:A` or `1:1`) */
+    REF_BEAM: string;
+    /** A name / named range identifier (`income`) */
+    REF_NAMED: string;
+    /** A range identifier (`A1`) */
+    REF_RANGE: string;
+    /** A structured reference identifier (`table[[Column1]:[Column2]]`) */
+    REF_STRUCT: string;
+    /** A ternary range identifier (`B2:B`) */
+    REF_TERNARY: string;
+    /** String literal (`"Lorem ipsum"`) */
+    STRING: string;
+    /** Any unidentifiable range of characters. */
+    UNKNOWN: string;
+    /** Whitespace character sequence (` `) */
+    WHITESPACE: string;
+}>;
+