Skip to main content

sheet_engine/
lib.rs

1//! Spreadsheet calculation engine — dependency-driven incremental
2//! recalculation, Excel-compatible semantics, volatile function tracking.
3//!
4//! `sheet-engine` is the L2 composition layer of the estate's spreadsheet
5//! stack: it turns the parts into a working product.
6//!
7//! | Crate | Layer | Role in the engine |
8//! |---|---|---|
9//! | `formula_lang` | L0 | formula tokenizer, Pratt parser, AST, evaluator, Excel coercions |
10//! | `sheet_core` | L1 | sparse cell storage (`Sheet`), per-sheet dependency DAG (`DependencyGraph`) |
11//! | `sheet_xlsx` | L1 | XLSX codec — workbook, worksheets, shared strings, calc chain |
12//!
13//! # The workbook dimension
14//!
15//! `sheet-core` models **one worksheet**: its `DependencyGraph` keys cells
16//! by `(row, col)` within a single sheet, and its reference scanner records
17//! a qualified reference (`Sheet2!A1`) at its bare coordinates — both
18//! documented v0.1 simplifications that defer cross-sheet edges to a
19//! workbook-level graph. That workbook-level graph is *this crate*: the
20//! engine layers the sheet dimension on top —
21//!
22//! - **Local edges** (formula reads cells of its own sheet) are owned by a
23//!   per-sheet `sheet-core` `DependencyGraph`, exactly as designed.
24//! - **Cross-sheet edges** (`=Sheet2!A1`, `='Q4 Data'!B2:F9`) are owned by
25//!   the engine and merged with the local edges everywhere a graph question
26//!   is asked: topological order, dirty propagation, cycle detection.
27//!
28//! # Cross-sheet evaluation by stub rewriting
29//!
30//! `formula-lang`'s grammar has no sheet qualifier (`!` is not a token), so
31//! the engine cannot parse `=Sheet2!A1` directly — and its
32//! `CellResolver` has no sheet dimension either. Instead of re-implementing
33//! the evaluator, the engine **rewrites** each qualified reference to a
34//! *stub*: a plain in-grid cell reference that would collide with no real
35//! reference in the same formula (stub coordinates start above the highest
36//! linear coordinate the formula's local references reach). The rewrite is
37//! recorded per formula, and the engine's resolver translates stub reads
38//! back to their real `(sheet, row, col)` targets at evaluation time. The
39//! original formula text is preserved verbatim in the sheet, so XLSX
40//! round-trips are exact.
41//!
42//! # Calculation model
43//!
44//! The API is explicit-recalculation, like a file format rather than a UI:
45//! [`set_cell`](Engine::set_cell) parses the input, stores it, and marks
46//! the cell dirty; [`recalculate`](Engine::recalculate) evaluates every
47//! formula in topological order; `recalculate_incremental` evaluates only
48//! the dirty subgraph — the edited cells plus their transitive dependents,
49//! plus the volatile cells (`TODAY`, `NOW`, `OFFSET`), which re-evaluate on
50//! every calculation, Excel-style.
51//!
52//! Errors are values, not exceptions, exactly as spreadsheets behave:
53//! `=1/0` evaluates to `#DIV/0!`, and a formula reading an error cell
54//! propagates it (`=A1+1` over an errored `A1` is `#DIV/0!` too). Circular
55//! references are the one hard error: they are detected as explicit cycles
56//! and reported, never evaluated to a fixed point.
57//!
58//! # Coordinates
59//!
60//! The public API is **0-based** `(row, col)` — the same convention as
61//! `sheet-core` and `sheet-xlsx`. Cell `A1` is `(0, 0)`; the `A1` notation
62//! inside formulas stays 1-based as Excel users write it (`=A1` reads
63//! `(0, 0)`).
64//!
65//! # Example
66//!
67//! ```
68//! use sheet_engine::{Engine, Value};
69//!
70//! # fn main() -> Result<(), sheet_engine::EngineError> {
71//! let mut engine = Engine::new();
72//! engine.set_cell("Sheet1", 0, 0, "41")?;        // A1 = 41
73//! engine.set_cell("Sheet1", 0, 1, "=A1+1")?;     // B1 = A1 + 1
74//! engine.recalculate()?;
75//! assert_eq!(engine.get_value("Sheet1", 0, 1), Some(Value::Number(42.0)));
76//!
77//! // Edit A1; only the dependency chain re-evaluates.
78//! engine.set_cell("Sheet1", 0, 0, "100")?;
79//! engine.recalculate_incremental(&[("Sheet1".into(), 0, 0)])?;
80//! assert_eq!(engine.get_value("Sheet1", 0, 1), Some(Value::Number(101.0)));
81//! # Ok(())
82//! # }
83//! ```
84
85#![forbid(unsafe_code)]
86
87pub mod error;
88pub mod qualified;
89pub mod workbook;
90
91mod engine;
92mod resolver;
93mod xlsx_codec;
94
95pub use engine::Engine;
96pub use error::EngineError;
97pub use formula_lang::Value;
98
99/// A cell address in the workbook: `(sheet, row, col)` — the sheet's name
100/// and 0-based coordinates, the same tuple every engine API speaks.
101pub type CellId = (String, u32, u32);