truecalc_core/
lib.rs

1//! Spreadsheet formula parser and evaluator for Google Sheets and Excel
2//! conformance.
3//!
4//! # Quick start
5//!
6//! ```rust
7//! use std::collections::HashMap;
8//! use truecalc_core::{Engine, Value};
9//!
10//! let engine = Engine::sheets();
11//!
12//! let mut vars = HashMap::new();
13//! vars.insert("A1".to_string(), Value::Number(10.0));
14//! vars.insert("A2".to_string(), Value::Number(20.0));
15//! vars.insert("A3".to_string(), Value::Number(30.0));
16//!
17//! let result = engine.evaluate("=SUM(A1,A2,A3)", &vars);
18//! assert_eq!(result, Value::Number(60.0));
19//! ```
20//!
21//! # Engine flavors
22//!
23//! The engine flavor is **required and immutable**: create one engine per
24//! evaluation context and reuse it.
25//!
26//! | Constructor | Target conformance |
27//! |---|---|
28//! | [`Engine::sheets()`] | Google Sheets |
29//! | [`Engine::excel()`] | Excel (parse/validate only; evaluation pending) |
30//!
31//! # Evaluation modes
32//!
33//! - **Variable map** — [`Engine::evaluate`]: references are looked up in a
34//!   `HashMap<String, Value>`. Suitable for ad-hoc formula evaluation outside a
35//!   workbook.
36//! - **Resolver** — [`Engine::evaluate_with_resolver`]: every cell, range, and
37//!   name reference is resolved through a [`Resolver`] implementation. This is
38//!   the workbook layer's entry point; see `truecalc-workbook`.
39//! - **Pinned clock** — [`Engine::evaluate_at`] / [`Engine::evaluate_with_resolver_at`]:
40//!   volatile functions (`NOW`, `TODAY`) are pinned to a fixed spreadsheet serial,
41//!   producing deterministic results.
42//!
43//! # Migration from 0.6.x
44//!
45//! The free `evaluate()` function and `Engine::google_sheets()` constructor were
46//! deprecated in 0.7.0. Update call sites as follows:
47//!
48//! ```rust
49//! // Before (0.6.x):
50//! // use truecalc_core::evaluate;
51//! // let result = evaluate("=SUM(A1,A2)", &vars);
52//!
53//! // After (0.7+):
54//! use std::collections::HashMap;
55//! use truecalc_core::{Engine, Value};
56//! let vars: HashMap<String, Value> = HashMap::new();
57//! let result = Engine::sheets().evaluate("=SUM(A1,A2)", &vars);
58//! ```
59//!
60//! See [`MIGRATION.md`](https://github.com/truecalc/core/blob/main/crates/core/MIGRATION.md)
61//! for the full migration guide.
62//!
63//! # Related crates
64//!
65//! - [`truecalc-workbook`](https://docs.rs/truecalc-workbook): full workbook
66//!   layer — engine-locked workbook, worksheet, cell mutation, and recalc.
67
68pub mod display;
69pub mod engine;
70pub mod eval;
71pub mod parser;
72pub mod types;
73
74pub use display::display_number;
75pub use engine::{Engine, EngineFlavor};
76#[allow(deprecated)]
77pub use parser::{parse, validate};
78pub use parser::Expr;
79pub use parser::{CellAddr, Ref};
80pub use types::{ErrorKind, ParseError, Value};
81
82pub use eval::functions::{FunctionMeta, Registry};
83pub use eval::{extract_refs, Resolver};
84
85use std::collections::HashMap;
86
87/// Evaluate a formula string with named variables, targeting Google Sheets conformance.
88///
89/// Returns `Value::Error(ErrorKind::Value)` on parse failure.
90#[deprecated(since = "0.7.0", note = "use Engine::sheets()/Engine::excel() and engine.evaluate() — engine flavor is required; see ADR 2026-04-27; removal target: 0.7.0 coordinated release")]
91pub fn evaluate(formula: &str, variables: &HashMap<String, Value>) -> Value {
92    Engine::sheets().evaluate(formula, variables)
93}
truecalc_core/lib.rs

truecalc_core/
lib.rs
