visi_core/lib.rs
1//! `visi-core`: an embeddable spreadsheet engine.
2//!
3//! Excel formula compilation and evaluation, dependency-tracked
4//! recalculation, and `.xlsx` import/export. Makes no CLI or filesystem
5//! assumptions -- everything is driven through byte buffers -- and uses
6//! `web-time` and `getrandom` rather than `std::time` so it can target wasm.
7//!
8//! # Getting started
9//!
10//! [`WorkbookManager`] is the entry point. It owns a workbook's sheets,
11//! charts, pivot tables and VBA project, and is the layer that makes
12//! cross-sheet formulas and pivot tables behave correctly -- see its
13//! documentation before reaching for [`core::engine::Sheet`] directly.
14//!
15//! ```no_run
16//! use visi_core::WorkbookManager;
17//!
18//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
19//! let bytes = std::fs::read("book.xlsx")?;
20//! let mut wb = WorkbookManager::load_bytes(&bytes)?;
21//!
22//! // 0-based (row, col); A1 notation is a boundary concern.
23//! wb.set_cell(0, 0, 0, "=SUM(Sheet2!A1:A10)".to_string());
24//! wb.evaluate()?;
25//!
26//! std::fs::write("out.xlsx", wb.save_bytes()?)?;
27//! # Ok(())
28//! # }
29//! ```
30//!
31//! # Errors
32//!
33//! Fallible calls return [`Error`], which implements [`std::error::Error`]
34//! and so composes with `anyhow`, `eyre`, or `Box<dyn Error>`. Failures that
35//! name a workbook object carry an [`ObjectKind`] rather than only a message,
36//! so callers can react without parsing text:
37//!
38//! ```no_run
39//! use visi_core::{Error, ObjectKind, WorkbookManager};
40//!
41//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
42//! # let mut wb = WorkbookManager::new_empty()?;
43//! match wb.rename_sheet("Sheet1", "Data") {
44//! Err(Error::NotFound { kind: ObjectKind::Sheet, name, .. }) => {
45//! eprintln!("no sheet called {name}");
46//! }
47//! other => other?,
48//! }
49//! # Ok(())
50//! # }
51//! ```
52//!
53//! # Stability
54//!
55//! Pre-1.0; the public API is still moving. Modules that exist to implement
56//! Excel's function library are crate-private -- what is re-exported here and
57//! from [`core`] is the intended surface.
58
59#![warn(missing_docs)]
60
61/// The engine's modules: sheets and cells, Excel Tables, pivot tables,
62/// charts, styling, VBA, and `.xlsx` I/O.
63///
64/// The curated re-exports at this module's root are the intended surface.
65/// Modules implementing Excel's function library are crate-private.
66pub mod core;
67mod error;
68
69pub use core::workbook::{SheetSummary, WorkbookManager, WorkbookSummary};
70pub use core::xlsx::{export_xlsx_data, import_xlsx_data};
71pub use error::{Error, ObjectKind, Result};