import type { FormulaSourceSpan } from "./formulaTypes.js";
/**
 * `reference` and `unknown` are produced ONLY under the matching
 * `TokenizeFormulaOptions` flag. The parser tokenizes with the defaults, so it
 * never sees either of them and its canonical grammar stays closed.
 */
export type FormulaTokenType = 'number' | 'string' | 'identifier' | 'operator' | 'punctuation' | 'reference' | 'unknown';
export interface FormulaToken {
  type: FormulaTokenType;
  /**
   * For `string` tokens this is the unescaped value (`""` -> `"`);
   * for every other type it is the raw source text.
   */
  value: string;
  span: FormulaSourceSpan;
  /**
   * Set on the `string` token a tolerant tokenization emits for a literal whose
   * closing quote is missing — the span then runs to the end of the input.
   */
  unterminated?: boolean;
}
export interface TokenizeFormulaOptions {
  /**
   * Recognizes the A1 editor dialect's references — `B5`, `$A$1`, the `A1:B2`
   * range and the `A:A` whole-column range — as single `reference` tokens, and
   * `:` as punctuation. Off by default: the canonical dialect the parser reads
   * has no A1 forms, and the same text must not tokenize two ways.
   * @default false
   */
  a1Notation?: boolean;
  /**
   * Never stops at a problem: an unexpected character becomes an `unknown`
   * token, an unterminated string an `unterminated` `string` token, and `error`
   * comes back `null`. For consumers that analyze half-typed text (autocomplete)
   * rather than parse it, where aborting would blind everything downstream of
   * the first stray character.
   * @default false
   */
  tolerant?: boolean;
}
export interface FormulaTokenizeError {
  message: string;
  span: FormulaSourceSpan;
}
export interface FormulaTokenizeResult {
  tokens: FormulaToken[];
  error: FormulaTokenizeError | null;
}
/**
 * Tokenizes a formula expression (the source without its leading `=`) in the
 * canonical dialect, stopping at the first problem: on error, `tokens` contains
 * everything tokenized up to the error position. `options` opens it up to the A1
 * dialect and to never stopping — see `TokenizeFormulaOptions`.
 */
export declare function tokenizeFormula(expression: string, options?: TokenizeFormulaOptions): FormulaTokenizeResult;