/**
 * xlsx FORMULAS — text → AST parser.
 *
 * OWNERSHIP: FORMULA agent (see ast.ts header).
 *
 * The grammar is Excel's formula language as stored in the XML `f`
 * element (which is already A1, en-US function names, ',' separators —
 * locale display variants are Excel-UI-only and out of scope):
 * literals, cell/range refs (incl. 3-D 'Sheet1:Sheet3'!A1, quoted
 * 'My Sheet'!A1, whole col/row A:C / 1:3), defined names, structured
 * table refs, operators with Excel precedence, function calls (with
 * `_xlfn.` / `_xlfn._xlws.` prefixes stripped into clean AST names),
 * array constants.
 *
 * Grammar decisions (documented, deliberate):
 * - Precedence, loosest to tightest: comparisons (= <> < <= > >=) < `&`
 *   < `+ -` < `* /` < `^` (left-associative, like Excel: 2^3^2 = 64) <
 *   postfix `%` < unary `- +` (so -2^2 parses as (-2)^2, and -2% as
 *   (-2)%) < reference operators (union `,` < intersection ' ' < range
 *   `:`) < primaries.
 * - Whitespace (space/tab/CR/LF) is insignificant everywhere EXCEPT
 *   between two reference-capable operands, where a run of it is the
 *   intersection operator (serialized back as exactly one space). A
 *   token that could start a reference (letter, `_`, `\`, `$`, `'`,
 *   `(`, `[`, digit, or any non-ASCII char) after whitespace triggers
 *   intersection; anything else (an operator, `"`, `{`, end) means the
 *   whitespace was insignificant.
 * - The union operator `,` exists only inside parentheses ((A1,B2));
 *   everywhere else `,` separates function arguments.
 * - `name(` with NO whitespace before `(` is a function call; with
 *   whitespace between, it is `name` intersected with a group (Excel's
 *   own resolution of the same ambiguity).
 * - A token that looks like a cell ref but lies beyond the sheet
 *   (XFE1, A1048577, A01 with a leading zero) parses as a defined name,
 *   exactly like Excel resolves it.
 * - Range corners are stored exactly as written (B2:A1 is NOT
 *   normalized to A1:B2) — text fidelity over normalization.
 * - `Sheet1!#REF!` (a broken sheet-qualified ref) parses as a NameRef
 *   named '#REF!' so it round-trips; a bare `#REF!` is an ErrorLiteral.
 * - R1C1 mode: `R2C5` absolute, `R[-1]C[2]` relative to the anchor,
 *   bare `R`/`C` axis = same row/col as the anchor; `R2`, `C[-1]`,
 *   `R1:R3` are whole-row/col refs. A relative ref that resolves
 *   outside the sheet throws. `$` is not part of the R1C1 grammar.
 */
import { type CellAddress } from '../internal.js';
import type { FormulaNode } from './ast.js';
/**
 * A formula syntax error: where it happened (0-based character offset
 * into the input string exactly as given, including any leading '='),
 * what the parser expected, and what it found instead.
 */
export declare class XlsxFormulaError extends Error {
    /** The full formula text that failed to parse, as given. */
    readonly formula: string;
    /** 0-based character offset into {@link formula}. */
    readonly position: number;
    /** Human-readable description of what was expected at {@link position}. */
    readonly expected: string;
    /** What was found instead (a quoted character, or 'end of formula'). */
    readonly found: string;
    constructor(formula: string, position: number, expected: string, found: string);
}
/** Options for {@link parseFormula}. */
export interface ParseFormulaOptions {
    /**
     * Reference style of the input text. Default 'A1'. With 'R1C1',
     * relative `R[1]C[-2]` offsets are resolved against `anchor`
     * (bare `R1C1` etc. are absolute).
     */
    readonly style?: 'A1' | 'R1C1';
    /**
     * The cell the formula belongs to — required to resolve relative R1C1
     * refs ('D2' or {row, col}). Default A1. Ignored for style 'A1'
     * (A1 coordinates are absolute positions regardless of `$`).
     */
    readonly anchor?: string | CellAddress;
}
/**
 * Parse formula text to a typed AST. A leading '=' is accepted and
 * ignored (users paste formulas both ways). Throws {@link XlsxFormulaError}
 * (an `Error` naming the character offset and what was expected) on any
 * syntax error; a relative R1C1 ref that resolves outside the sheet
 * (row < 1 etc.) also throws.
 *
 * ```ts
 * const ast = parseFormula('=SUM(Sheet1!A1:B2, TaxRate) * 1.1');
 * ast.kind  // → 'binary'
 * ```
 */
export declare function parseFormula(formula: string, options?: ParseFormulaOptions): FormulaNode;
//# sourceMappingURL=parser.d.ts.map