#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] //! Excel workbooks: `.xlsx`/`.xlsm` (SpreadsheetML, ECMA-376 Part 1, transitional and strict) and //! `.xlsb` (the same package with binary parts, [MS-XLSB]). Clean-room, from the specifications //! and observed files. //! //! This is the part layer: a [`Package`] opens the OPC container (`craft-opc`) and reads //! //! - the workbook part: sheets, the date system, defined names ([`Workbook`]); //! - shared strings with their rich-text runs and phonetic readings ([`StringItem`]); //! - the styles tables as the file has them ([`Styles`]): number formats, fonts, fills, borders, //! cell formats, named styles and differential formats, by index; //! - one worksheet at a time as a stream of [`Row`]s of [`Cell`]s, so a sheet of any length is //! read without holding it; what is left of the part (properties, columns, merged cells, //! validation, and so on) comes back as a tree ([`SheetPart`]). //! //! Parts are read with fixed prefixes ([`ns`]): the SpreadsheetML main namespace has none //! (`sheetData`), the others have theirs whatever the file used (`r:id`, `x14:sparklineGroups`, //! `mc:AlternateContent`), so a tree kept from a part can be written back with [`ns::declare`]. //! //! Nothing is interpreted beyond the format: a cell holds a shared-string index and a format //! index, a width is in the file's units, a formula is the file's text. Every other part //! (drawings, charts, pivot caches, macros) is reachable through [`Package::opc`], so a caller //! can read it or carry it through unchanged. //! //! A binary workbook gives the same [`Workbook`], [`StringItem`]s, [`Row`]s and merged cells: //! saved values only, since formulas there are token streams that are not decoded and styles are //! not read. //! //! Reading SpreadsheetML is lenient: a damaged optional part is skipped and named in //! [`Package::warnings`]; only an unreadable package or workbook part is an error. Reading a //! binary workbook is strict: a record that does not parse fails the read, because skipping it //! would lose data silently. Input is hostile: [`Limits`] bounds the package, the XML and the //! binary records, cells outside the grid are dropped, and nothing indexes by a number from the //! file. //! //! ``` //! # fn main() -> Result<(), craft_xlsx::Error> { //! # let bytes = craft_xlsx::testing::workbook(&[("Prices", r#"02.5"#)], &["Tea"]); //! let mut package = craft_xlsx::Package::open(&bytes, &craft_xlsx::Limits::default())?; //! let workbook = package.workbook()?; //! let strings = package.shared_strings()?; //! let mut values = Vec::new(); //! package.sheet(&workbook.sheets[0], |row| { //! values.extend(row.cells.iter().map(|c| c.value.resolve(&strings, workbook.date_1904))); //! Ok(()) //! })?; //! assert_eq!(values, [craft_xlsx::Value::text("Tea"), craft_xlsx::Value::Number(2.5)]); //! # Ok(()) //! # } //! ``` mod document; mod drawing; #[macro_use] mod features; pub mod ns; mod package; mod pivot; mod richdata; mod sheet; mod strings; mod styles; #[doc(hidden)] pub mod testing; mod workbook; mod write; mod xlsb; pub use craft_drawingml; pub use craft_sheet::{ BorderStyle, CellError, CellRef, DEFAULT_PALETTE, HAlign, MAX_COLS, MAX_ROWS, Pattern, Range, Script, Underline, VAlign, Value, Visibility, builtin_format, builtin_format_id, quote_sheet, sheet_needs_quotes, }; pub use document::{Document, DrawingPart, KeptPart, PivotCachePart, PivotTablePart, TablePart, Worksheet, XlsxKind}; pub use drawing::{Anchor, Drawing, Item, Marker, ObjectKind, Placement}; pub use features::{ Break, CfRule, Cfvo, ColorScale, Comment, Comments, ConditionalFormatting, DataBar, DataValidation, DataValidations, Features, HeaderFooter, Hyperlink, IconSet, NoteShape, PageMargins, PageSetup, Pane, Print, PrintOptions, Selection, SheetView, Table, TableColumn, TableStyleInfo, notes_vml, parse_sqref, range_ref, }; pub use package::{Package, is_xlsb}; pub use pivot::{ CacheField, CacheItem, CacheRecord, CacheSource, CacheValue, DataField, FieldGroup, Location, PageField, PivotCacheDefinition, PivotField, PivotItem, PivotTableDefinition, PivotTableStyleInfo, RangePr, SharedItems, WorksheetSource, records_xml, }; pub use richdata::{CellPicture, MAX_PICTURE, MAX_PICTURES_TOTAL, MAX_RECORDS}; pub use sheet::{Cell, CellFormula, CellValue, Column, FormulaKind, Row, SheetPart, iso_date_serial}; pub use strings::{PhoneticProps, PhoneticRun, StringItem, TextRun, decode_xstring, encode_xstring, rich_text, t_el}; pub use styles::{ Alignment, Border, BorderEdge, CellStyle, Color, ColorSource, Dxf, Fill, Font, FontScheme, GradientFill, PatternFill, Protection, Styles, Xf, }; pub use workbook::{DefinedName, PivotCacheEntry, SheetEntry, SheetKind, Workbook}; pub use write::num; /// Why a workbook could not be read. #[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] pub enum Error { /// The bytes are not a ZIP package, or an entry is damaged. #[error("the file is not a valid zip package: {0}")] Zip(String), /// A part that must be read holds XML that cannot be. #[error("the file contains invalid XML: {0}")] Xml(String), /// The package is not a workbook, or a binary part is damaged. #[error("the file is not a valid spreadsheet: {0}")] Invalid(String), /// More than [`Limits`] or a fixed cap allows. #[error("the file is too large: {0}")] TooLarge(String), } impl From for Error { fn from(e: craft_opc::Error) -> Self { match e { e if e.is_limit() => Error::TooLarge(e.to_string()), craft_opc::Error::Zip(m) => Error::Zip(m), craft_opc::Error::Xml { .. } => Error::Xml(e.to_string()), e => Error::Invalid(e.to_string()), } } } impl From for Error { fn from(e: craft_xml::Error) -> Self { if e.is_limit() { Error::TooLarge(e.to_string()) } else { Error::Xml(e.to_string()) } } } /// What a read refuses to exceed. The defaults suit a spreadsheet application; a caller that /// only wants a table of values can lower them. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub struct Limits { /// The ZIP package: entries, bytes per part and bytes in all. pub package: craft_opc::Limits, /// One XML part. Rows and shared strings are streamed, so `max_nodes` bounds one row or one /// string and what is left of a part, not a sheet's length. pub xml: craft_xml::Limits, /// Records read from a binary workbook, every part together. Records are skipped or decoded /// without being kept, so this bounds parse time, not memory. Excel writes four records per /// row besides the cells, and one per formatted empty cell, so a sheet needs many more /// records than cells. pub binary_records: usize, /// Cells with a value read from a binary workbook, over all its sheets; also the most /// shared-string items. pub binary_cells: usize, /// Bytes of decoded text (shared and inline strings) in a binary workbook, over all its parts. pub binary_text: usize, /// Bytes of decoded formula text in a binary workbook, over all its sheets. A cell formula /// may hold 16 KB of tokens, so without a total a million cells of long formulas would cost /// gigabytes; past it, formulas keep their saved results (the file still opens). pub binary_formula_text: usize, } impl Default for Limits { fn default() -> Self { Limits { package: craft_opc::Limits::new(200_000, 512 << 20, 1 << 30), xml: craft_xml::Limits { max_input: 512 << 20, ..craft_xml::Limits::DEFAULT }, // The limits of `craft-xls`. binary_records: 40_000_000, binary_cells: 4_000_000, binary_text: 256 << 20, binary_formula_text: 128 << 20, } } } /// What a read skipped or repaired, each distinct message once and at most 1000 of them. #[derive(Debug, Clone, Default, PartialEq, Eq)] pub(crate) struct Warnings(pub(crate) Vec); impl Warnings { pub(crate) fn warn(&mut self, m: impl Into) { let m = m.into(); if self.0.len() < 1000 && !self.0.contains(&m) { self.0.push(m); } } }