worksheet_formula library
A standalone formula engine for spreadsheet-like calculations.
This package provides:
- Excel/Google Sheets compatible formula parsing
- An extensible function registry with built-in functions
- Dependency tracking for efficient recalculation
- Type-safe formula values and error handling
Basic Usage
import 'package:worksheet_formula/worksheet_formula.dart';
// Create the engine
final engine = FormulaEngine();
// Parse a formula
final ast = engine.parse('=SUM(A1:A10) * 2');
// Implement EvaluationContext to connect your data source
final context = MyEvaluationContext(myData);
// Evaluate
final result = engine.evaluate(ast, context);
Classes
- BinaryOpNode
- Binary operation: A1 + B1, 2 * 3, "a" & "b"
- BooleanNode
- Boolean literal: TRUE, FALSE
- BooleanValue
- CellRefNode
- Cell reference: A1, $B$2, Sheet1!C3
- DependencyGraph
- Tracks cell dependencies for efficient recalculation.
- EmptyValue
- ErrorNode
- Error literal: #REF!, #VALUE!, etc.
- ErrorValue
- EvaluationContext
- Abstract context for formula evaluation.
- FormulaEngine
- Main entry point for the formula engine.
- FormulaFunction
- Base class for all formula functions.
- FormulaNode
- Base class for all formula AST nodes.
- FormulaParser
- Parser for spreadsheet formulas.
- FormulaValue
- Represents any value that can result from formula evaluation.
- FunctionCallNode
- Function call: SUM(A1:A10), IF(A1>0, "yes", "no")
- FunctionRegistry
- Registry of available formula functions.
- NumberNode
- Number literal: 42, 3.14, -17
- NumberValue
- ParenthesizedNode
- Parenthesized expression (preserves formatting in toFormulaString).
- RangeRefNode
- Range reference: A1:B10, Sheet1!A1:C3
- RangeValue
- TextNode
- String literal: "hello", "world"
- TextValue
- UnaryOpNode
- Unary operation: -A1, +5, 50%
Enums
- BinaryOperator
- Binary operators supported in formulas.
- FormulaError
- Excel-compatible formula errors.
- UnaryOperator
- Unary operators supported in formulas.
Exceptions / Errors
- FormulaParseException
- Exception thrown when formula parsing fails.