Skip to content

A fast, helpful, and open-source document parser

wip

Logan Markewichce96621cbf03
diff --git a/crates/liteparse-ooxml/src/docx/relationships.rs b/crates/liteparse-ooxml/src/docx/relationships.rs
index 0842e62..073f894 100644
--- a/crates/liteparse-ooxml/src/docx/relationships.rs
+++ b/crates/liteparse-ooxml/src/docx/relationships.rs
@@ -73,6 +73,21 @@ pub enum RelationshipType {
NotesMaster,
/// §13.3.3: the handout master (PresentationML).
HandoutMaster,
+ /// §12.3.24: a worksheet (SpreadsheetML).
+ Worksheet,
+ /// §12.3.4: a chartsheet — declared in `<sheets>` like a worksheet but
+ /// holding a chart instead of a cell grid.
+ ChartSheet,
+ /// §12.3.7: a dialog sheet, the same shape of exception as a chartsheet.
+ DialogSheet,
+ /// §12.3.15: the shared-string table (SpreadsheetML).
+ SharedStrings,
+ /// §12.3.20: a table part (`xl/tables/tableN.xml`).
+ Table,
+ /// §12.3.2: the calculation chain — cached formula ordering, never text.
+ CalcChain,
+ /// §12.3.11: a drawing part (also §13.3.1 in PresentationML).
+ Drawing,
/// Any relationship type not listed above.
Unknown(String),
}
@@ -138,6 +153,23 @@ impl RelationshipType {
Self::HandoutMaster
} else if uri.ends_with("/slide") {
Self::Slide
+ // SpreadsheetML (§12.3). As above, no type here is a `/`-suffix of
+ // another — `/pivotTable` does not end with `/table`, `/chartsheet`
+ // does not end with `/chart` — but longer names stay first anyway.
+ } else if uri.ends_with("/worksheet") {
+ Self::Worksheet
+ } else if uri.ends_with("/chartsheet") {
+ Self::ChartSheet
+ } else if uri.ends_with("/dialogsheet") {
+ Self::DialogSheet
+ } else if uri.ends_with("/sharedStrings") {
+ Self::SharedStrings
+ } else if uri.ends_with("/calcChain") {
+ Self::CalcChain
+ } else if uri.ends_with("/table") {
+ Self::Table
+ } else if uri.ends_with("/drawing") {
+ Self::Drawing
} else {
warn!("unknown relationship type: {}", uri);
Self::Unknown(uri.to_string())
diff --git a/crates/liteparse-ooxml/src/lib.rs b/crates/liteparse-ooxml/src/lib.rs
index 52d6a36..7e921b1 100644
--- a/crates/liteparse-ooxml/src/lib.rs
+++ b/crates/liteparse-ooxml/src/lib.rs
@@ -28,5 +28,6 @@ pub mod field;
pub mod model;
pub mod pptx;
pub mod render;
+pub mod xlsx;
pub use error::Error;
diff --git a/crates/liteparse-ooxml/src/xlsx/mod.rs b/crates/liteparse-ooxml/src/xlsx/mod.rs
new file mode 100644
index 0000000..eb1b9c4
--- /dev/null
+++ b/crates/liteparse-ooxml/src/xlsx/mod.rs
@@ -0,0 +1,337 @@
+//! Native SpreadsheetML (`.xlsx`) reader.
+//!
+//! Shares the OOXML packaging and relationships layers with [`crate::docx`] and
+//! [`crate::pptx`] — see `ATTRIBUTION.md` for what is vendored and what is ours.
+//! Unlike those two, nothing here is vendored: SpreadsheetML has no DOCX
+//! counterpart in dxpdf, so the whole reader is new code against ECMA-376 §18.
+//!
+//! # What this replaces
+//!
+//! Today an `.xlsx` goes through LibreOffice → PDF → grid projection, and the
+//! measured cost of that is not subtle. Across 218 real workbooks (63 research
+//! + 150 finance), that path emits **zero markdown table rows** and clips every
+//! cell at its rendered column width — `"Mosaic tree and shrub (>50%) …"`
+//! becomes `"Mosaic tr"`, destroyed before projection ever sees it, with a
+//! cell-text recall of 0.77 macro / 0.66–0.73 micro as the ceiling.
+//!
+//! A workbook states its grid explicitly. There is nothing to reverse-engineer.
+//!
+//! # Shape
+//!
+//! ```no_run
+//! let bytes = std::fs::read("report.xlsx")?;
+//! let wb = liteparse_ooxml::xlsx::read(&bytes)?;
+//! for sheet in &wb.sheets {
+//! for row in &sheet.rows {
+//! for cell in &row.cells {
+//! let text = wb.cell_text(cell);
+//! }
+//! }
+//! }
+//! # Ok::<(), liteparse_ooxml::Error>(())
+//! ```
+//!
+//! # What this layer does *not* do
+//!
+//! * **Number formatting.** A cell keeps its raw `f64` and its format code;
+//! turning `0.155` into `15.5%` is an interpreter, and the corpus says it is
+//! a real one — 665 distinct format codes, 50.0% of documents needing
+//! multi-section `pos;neg;zero;text` dispatch, 34.9% needing `_` skip-width
+//! padding. That is a vendored component (`ssf-rs` / `ironcalc`), landing
+//! separately, and [`Workbook::format_code`] is the seam it plugs into.
+//! * **Geometry.** Column widths stay in Excel's character unit and row
+//! heights in points; converting to a page needs the Normal font's digit
+//! width. That is the geometry pass.
+//! * **Emission.** No markdown, no `Block`s. That is `liteparse`'s job, and
+//! keeping it out of here is what lets this module be tested against a
+//! corpus with no renderer in the loop.
+
+pub mod package;
+pub mod refs;
+pub mod sheet;
+pub mod styles;
+pub mod text;
+mod xml;
+
+pub use package::{SheetEntry, WorkbookPackage, walk};
+pub use refs::{CellRef, RangeRef, column_label, parse_cell, parse_column, parse_range};
+pub use sheet::{Cell, CellValue, ColInfo, Hyperlink, Row, Sheet, SheetStats};
+pub use styles::{Alignment, CellXf, Font, HorizontalAlign, Styles};
+pub use text::{RichText, RunProps, TextRun, VertAlign, parse_shared_strings};
+
+use crate::docx::error::Result;
+
+/// A workbook read end to end.
+pub struct Workbook {
+ /// Sheets in tab order, including hidden ones (see [`Sheet::visible`]) and
+ /// excluding chartsheets, which carry no cell grid.
+ pub sheets: Vec<Sheet>,
+ /// The shared-string table, addressed by index from
+ /// [`CellValue::SharedString`]. Not folded into the cells: it exists so a
+ /// string used 40,000 times is stored once, and resolving eagerly would
+ /// undo that.
+ pub shared_strings: Vec<RichText>,
+ pub styles: Styles,
+ /// Serial dates count from 1904-01-01 rather than 1899-12-30.
+ pub date1904: bool,
+ /// Sheets named in `<sheets>` that hold no cell grid — chartsheets and
+ /// dialogsheets. Reported so a caller can tell an empty workbook from one
+ /// whose content this reader does not model.
+ pub non_worksheet_sheets: Vec<String>,
+}
+
+/// Read an `.xlsx` from raw bytes.
+///
+/// Fails only when the container is unreadable or the workbook part is absent.
+/// Everything below that degrades: an unparseable sheet is skipped with a
+/// warning, a missing styles part means every cell is `General`, and a missing
+/// shared-string table means string cells resolve to nothing. A workbook is
+/// almost never wholly broken, and refusing the whole file because one sheet is
+/// malformed is the fail-closed behaviour this vendor has already had to
+/// retire repeatedly.
+pub fn read(data: &[u8]) -> Result<Workbook> {
+ let pkg = walk(data)?;
+
+ let shared_strings = match pkg.shared_strings_xml.as_deref() {
+ Some(xml) => parse_shared_strings(xml).unwrap_or_else(|e| {
+ // Losing the table costs every `t="s"` cell its text, which is
+ // most of the workbook's words — but the numbers, the structure
+ // and the inline strings all survive.
+ log::warn!("unreadable shared-string table: {e}");
+ Vec::new()
+ }),
+ None => Vec::new(),
+ };
+ let styles = match pkg.styles_xml.as_deref() {
+ Some(xml) => Styles::parse(xml).unwrap_or_else(|e| {
+ log::warn!("unreadable styles part: {e}");
+ Styles::default()
+ }),
+ None => Styles::default(),
+ };
+
+ let mut sheets = Vec::new();
+ let mut non_worksheet_sheets = Vec::new();
+ for entry in &pkg.sheets {
+ if !entry.is_worksheet {
+ non_worksheet_sheets.push(entry.name.clone());
+ continue;
+ }
+ let Some(xml) = pkg.package.get_part(&entry.path) else {
+ continue;
+ };
+ match sheet::parse(&entry.name, entry.visible, xml) {
+ Ok(s) => sheets.push(s),
+ Err(e) => log::warn!("sheet {:?} failed to parse: {e}", entry.name),
+ }
+ }
+
+ Ok(Workbook {
+ sheets,
+ shared_strings,
+ styles,
+ date1904: pkg.date1904,
+ non_worksheet_sheets,
+ })
+}
+
+impl Workbook {
+ /// The text of a cell, resolving a shared-string index against the table.
+ ///
+ /// Returns `None` for a cell that holds no text — a number, a boolean, an
+ /// error — which is the caller's cue that the value needs formatting
+ /// rather than printing.
+ pub fn cell_text<'a>(&'a self, cell: &'a Cell) -> Option<&'a RichText> {
+ match &cell.value {
+ CellValue::Text(t) => Some(t),
+ CellValue::SharedString(i) => match self.shared_strings.get(*i as usize) {
+ Some(t) => Some(t),
+ None => {
+ // An index past the end of the table is corruption, and
+ // silently rendering an empty cell would hide it.
+ log::warn!(
+ "shared string {i} out of range ({} entries)",
+ self.shared_strings.len()
+ );
+ None
+ }
+ },
+ _ => None,
+ }
+ }
+
+ /// The number-format code governing a cell — the seam the number-format
+ /// interpreter plugs into.
+ pub fn format_code(&self, cell: &Cell) -> &str {
+ self.styles.format_code(cell.style)
+ }
+
+ /// Total cells carrying a value, across every sheet.
+ pub fn cell_count(&self) -> usize {
+ self.sheets.iter().map(|s| s.cell_count()).sum()
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use std::io::Write;
+
+ /// Build a minimal but real `.xlsx` container in memory. Written by hand
+ /// rather than fixtured so the test states exactly which parts the reader
+ /// is being asked to join.
+ fn build(parts: &[(&str, &str)]) -> Vec<u8> {
+ let mut buf = Vec::new();
+ {
+ let mut zip = zip::ZipWriter::new(std::io::Cursor::new(&mut buf));
+ let opts: zip::write::FileOptions<'_, ()> = zip::write::FileOptions::default()
+ .compression_method(zip::CompressionMethod::Deflated);
+ for (name, body) in parts {
+ zip.start_file(*name, opts).unwrap();
+ zip.write_all(body.as_bytes()).unwrap();
+ }
+ zip.finish().unwrap();
+ }
+ buf
+ }
+
+ const ROOT_RELS: &str = r#"<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+ <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="xl/workbook.xml"/>
+</Relationships>"#;
+
+ const WB_RELS: &str = r#"<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+ <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" Target="worksheets/sheet1.xml"/>
+ <Relationship Id="rId2" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/sharedStrings" Target="sharedStrings.xml"/>
+ <Relationship Id="rId3" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/>
+ <Relationship Id="rId4" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/chartsheet" Target="chartsheets/sheet1.xml"/>
+</Relationships>"#;
+
+ const WORKBOOK: &str = r#"<workbook xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">
+ <sheets>
+ <sheet name="Data" sheetId="1" r:id="rId1"/>
+ <sheet name="Chart" sheetId="2" r:id="rId4"/>
+ </sheets>
+</workbook>"#;
+
+ const SST: &str = r#"<sst count="2" uniqueCount="2">
+ <si><t>Total assets</t></si>
+ <si><r><rPr><b/></rPr><t>Q3</t></r></si>
+</sst>"#;
+
+ const STYLES: &str = r#"<styleSheet>
+ <numFmts><numFmt numFmtId="164" formatCode="0.0%"/></numFmts>
+ <cellXfs count="2"><xf numFmtId="0" fontId="0"/><xf numFmtId="164" fontId="0"/></cellXfs>
+</styleSheet>"#;
+
+ const SHEET1: &str = r#"<worksheet><sheetData>
+ <row r="1"><c r="A1" t="s"><v>0</v></c><c r="B1" t="s"><v>1</v></c></row>
+ <row r="2"><c r="A2"><v>1234.5</v></c><c r="B2" s="1"><v>0.155</v></c></row>
+</sheetData></worksheet>"#;
+
+ fn workbook() -> Workbook {
+ read(&build(&[
+ ("[Content_Types].xml", "<Types/>"),
+ ("_rels/.rels", ROOT_RELS),
+ ("xl/workbook.xml", WORKBOOK),
+ ("xl/_rels/workbook.xml.rels", WB_RELS),
+ ("xl/sharedStrings.xml", SST),
+ ("xl/styles.xml", STYLES),
+ ("xl/worksheets/sheet1.xml", SHEET1),
+ ("xl/chartsheets/sheet1.xml", "<chartsheet/>"),
+ ]))
+ .unwrap()
+ }
+
+ #[test]
+ fn a_workbook_joins_its_parts() {
+ let wb = workbook();
+ assert_eq!(wb.sheets.len(), 1);
+ assert_eq!(wb.sheets[0].name, "Data");
+ assert_eq!(wb.cell_count(), 4);
+ }
+
+ #[test]
+ fn shared_strings_resolve_through_the_workbook() {
+ let wb = workbook();
+ let cell = &wb.sheets[0].rows[0].cells[0];
+ assert_eq!(wb.cell_text(cell).unwrap().plain(), "Total assets");
+ // Rich formatting survives the round trip through the table.
+ let q3 = &wb.sheets[0].rows[0].cells[1];
+ assert!(wb.cell_text(q3).unwrap().runs[0].props.bold);
+ }
+
+ #[test]
+ fn numbers_carry_a_format_code_rather_than_a_rendered_string() {
+ let wb = workbook();
+ let plain = &wb.sheets[0].rows[1].cells[0];
+ let pct = &wb.sheets[0].rows[1].cells[1];
+ assert_eq!(plain.value, CellValue::Number(1234.5));
+ assert_eq!(wb.format_code(plain), styles::GENERAL);
+ // The seam: `0.155` plus `0.0%` is what the interpreter turns into
+ // `15.5%`. Neither half is discarded here.
+ assert_eq!(pct.value, CellValue::Number(0.155));
+ assert_eq!(wb.format_code(pct), "0.0%");
+ assert!(wb.cell_text(pct).is_none());
+ }
+
+ /// A chartsheet is declared in `<sheets>` exactly like a worksheet. Parsing
+ /// it as one would add an empty sheet to the output.
+ #[test]
+ fn chartsheets_are_reported_not_parsed_as_worksheets() {
+ let wb = workbook();
+ assert_eq!(wb.non_worksheet_sheets, vec!["Chart"]);
+ }
+
+ /// The failure the packaging layer exists to prevent: the part name is
+ /// conventional, so a workbook that puts its sheet somewhere else must
+ /// still resolve through relationships.
+ #[test]
+ fn sheets_resolve_through_rels_not_by_convention() {
+ let rels = WB_RELS.replace("worksheets/sheet1.xml", "sheets/data.xml");
+ let wb = read(&build(&[
+ ("[Content_Types].xml", "<Types/>"),
+ ("_rels/.rels", ROOT_RELS),
+ ("xl/workbook.xml", WORKBOOK),
+ ("xl/_rels/workbook.xml.rels", &rels),
+ ("xl/sheets/data.xml", SHEET1),
+ ]))
+ .unwrap();
+ assert_eq!(wb.cell_count(), 4);
+ }
+
+ #[test]
+ fn a_workbook_with_no_styles_or_strings_still_reads() {
+ let rels = r#"<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+ <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" Target="worksheets/sheet1.xml"/>
+</Relationships>"#;
+ let wb = read(&build(&[
+ ("[Content_Types].xml", "<Types/>"),
+ ("_rels/.rels", ROOT_RELS),
+ ("xl/workbook.xml", WORKBOOK),
+ ("xl/_rels/workbook.xml.rels", rels),
+ ("xl/worksheets/sheet1.xml", SHEET1),
+ ]))
+ .unwrap();
+ assert_eq!(wb.sheets.len(), 1);
+ // String cells have nothing to resolve against, but numbers survive.
+ assert!(wb.cell_text(&wb.sheets[0].rows[0].cells[0]).is_none());
+ assert_eq!(
+ wb.sheets[0].rows[1].cells[0].value,
+ CellValue::Number(1234.5)
+ );
+ }
+
+ #[test]
+ fn a_missing_workbook_part_is_the_one_fatal_error() {
+ let data = build(&[
+ ("[Content_Types].xml", "<Types/>"),
+ ("_rels/.rels", ROOT_RELS),
+ ]);
+ assert!(read(&data).is_err());
+ }
+
+ #[test]
+ fn a_non_zip_input_is_rejected() {
+ assert!(read(b"<html>not a workbook</html>").is_err());
+ }
+}
diff --git a/crates/liteparse-ooxml/src/xlsx/package.rs b/crates/liteparse-ooxml/src/xlsx/package.rs
new file mode 100644
index 0000000..257a281
--- /dev/null
+++ b/crates/liteparse-ooxml/src/xlsx/package.rs
@@ -0,0 +1,296 @@
+//! SpreadsheetML package walk: `xl/workbook.xml` → ordered worksheets, joined
+//! to the shared-string table and the style table they depend on.
+//!
+//! Deliberately byte-level, the same split `pptx::package` uses: this stage
+//! resolves the part graph and hands back raw XML, and nothing here understands
+//! a cell. Everything it stands on — [`PackageContents`], [`resolve_target`],
+//! [`rels_path_for`], [`Relationships`] — is the OOXML packaging layer vendored
+//! for DOCX, reused unchanged.
+//!
+//! **Sheets are reached through relationships, never by globbing
+//! `xl/worksheets/sheetN.xml`.** Two independent reasons, both real in the
+//! corpus: the part name is conventional rather than mandated, and the numeric
+//! suffix is not the tab order — `sheet10.xml` sorts before `sheet2.xml`, and a
+//! deleted sheet leaves a gap. Only `<sheets>` states the order the user sees.
+
+use crate::docx::error::{ParseError, Result};
+use crate::docx::relationships::{RelationshipType, Relationships};
+use crate::docx::zip::{PackageContents, part_directory, rels_path_for, resolve_target};
+use crate::xlsx::xml::{attr, local_name};
+
+/// A worksheet as the workbook part declares it, before its XML is parsed.
+#[derive(Clone, Debug)]
+pub struct SheetEntry {
+ pub name: String,
+ /// `state="hidden"` / `"veryHidden"`. A hidden sheet is usually scratch
+ /// data or a lookup table, so this is the emitter's decision to make, not
+ /// the reader's — it is reported rather than filtered here.
+ pub visible: bool,
+ /// Package-normalized path of the worksheet part.
+ pub path: String,
+ /// The worksheet's own relationships, for its hyperlinks and drawings.
+ /// `r:id` values are scoped to the part that uses them, so these cannot be
+ /// looked up in the workbook's set.
+ pub rels: Relationships,
+ /// True for `<chartsheet>` / `<dialogsheet>` parts, which appear in
+ /// `<sheets>` alongside worksheets but hold no cell grid.
+ pub is_worksheet: bool,
+}
+
+/// The workbook graph, walked but not yet understood.
+pub struct WorkbookPackage {
+ /// Sheets in **tab order** — `<sheets>`, not part order.
+ pub sheets: Vec<SheetEntry>,
+ pub shared_strings_xml: Option<Vec<u8>>,
+ pub styles_xml: Option<Vec<u8>>,
+ /// `<workbookPr date1904="1"/>`: the epoch serial dates count from. Excel
+ /// for Mac wrote 1904-based workbooks for years and 123 of the corpus's
+ /// 1,089 workbooks come from Mac Excel, so this is not a historical
+ /// curiosity — reading it wrong shifts every date by 1,462 days.
+ pub date1904: bool,
+ /// The raw container, kept for drawings and media the emitter may reach.
+ pub package: PackageContents,
+}
+
+/// Walk an `.xlsx` container into its part graph.
+pub fn walk(data: &[u8]) -> Result<WorkbookPackage> {
+ let package = PackageContents::from_bytes(data)?;
+
+ // The workbook part is reached through the package root rels rather than
+ // assumed to be `xl/workbook.xml` — the path is conventional, not
+ // mandated.
+ let root_rels = load_rels(&package, "");
+ let wb_path = root_rels
+ .find_by_type(&RelationshipType::OfficeDocument)
+ .map(|r| resolve_target("", &r.target))
+ .unwrap_or_else(|| "xl/workbook.xml".to_string());
+
+ let wb_xml = package
+ .get_part(&wb_path)
+ .ok_or_else(|| ParseError::MissingPart(wb_path.clone()))?
+ .to_vec();
+ let wb_rels = load_rels(&package, &wb_path);
+ let wb_dir = part_directory(&wb_path).to_string();
+
+ let parsed = parse_workbook(&wb_xml)?;
+
+ let mut sheets = Vec::new();
+ for entry in parsed.sheets {
+ let Some(rel) = entry
+ .rel_id
+ .as_deref()
+ .and_then(|id| wb_rels.find_by_id(id))
+ else {
+ // A sheet with no resolvable relationship has no part to read. It
+ // is skipped rather than fatal, and named in the log so a corpus
+ // run can tell "we dropped a sheet" from "the file had none".
+ log::warn!("sheet {:?} does not resolve to a part", entry.name);
+ continue;
+ };
+ let path = resolve_target(&wb_dir, &rel.target);
+ if package.get_part(&path).is_none() {
+ log::warn!("sheet {:?} points at a missing part {}", entry.name, path);
+ continue;
+ }
+ sheets.push(SheetEntry {
+ name: entry.name,
+ visible: entry.visible,
+ rels: load_rels(&package, &path),
+ // A chartsheet is declared in `<sheets>` exactly like a worksheet;
+ // the only distinguishing signal at this level is the relationship
+ // type, since both resolve to a real part.
+ is_worksheet: rel.rel_type == RelationshipType::Worksheet,
+ path,
+ });
+ }
+
+ let part_of_type = |ty: &RelationshipType| -> Option<Vec<u8>> {
+ let rel = wb_rels.find_by_type(ty)?;
+ let path = resolve_target(&wb_dir, &rel.target);
+ package.get_part(&path).map(|b| b.to_vec())
+ };
+ let shared_strings_xml = part_of_type(&RelationshipType::SharedStrings);
+ let styles_xml = part_of_type(&RelationshipType::Styles);
+
+ Ok(WorkbookPackage {
+ sheets,
+ shared_strings_xml,
+ styles_xml,
+ date1904: parsed.date1904,
+ package,
+ })
+}
+
+fn load_rels(package: &PackageContents, part_path: &str) -> Relationships {
+ let rels_path = if part_path.is_empty() {
+ "_rels/.rels".to_string()
+ } else {
+ rels_path_for(part_path)
+ };
+ package
+ .get_part(&rels_path)
+ .and_then(|b| match Relationships::parse(b) {
+ Ok(r) => Some(r),
+ Err(e) => {
+ // A malformed rels part costs hyperlink/drawing resolution for
+ // one sheet, not the workbook.
+ log::warn!("failed to parse {}: {}", rels_path, e);
+ None
+ }
+ })
+ .unwrap_or_default()
+}
+
+// ---------------------------------------------------------------------------
+// `xl/workbook.xml` is parsed by hand rather than with serde, for the reason
+// `pptx::package` documents at length: `<sheet name="X" sheetId="1"
+// r:id="rId1"/>` carries both `@sheetId` and `@r:id`, and quick-xml's serde
+// layer matches attributes on their local name with the prefix dropped. There
+// is no serde spelling that keeps `r:id` distinct, and the failure mode is
+// silent — binding the numeric id where the relationship id belongs resolves
+// nothing and yields an empty workbook.
+// ---------------------------------------------------------------------------
+
+#[derive(Default)]
+struct WorkbookXml {
+ sheets: Vec<DeclaredSheet>,
+ date1904: bool,
+}
+
+struct DeclaredSheet {
+ name: String,
+ visible: bool,
+ rel_id: Option<String>,
+}
+
+fn parse_workbook(data: &[u8]) -> Result<WorkbookXml> {
+ use quick_xml::Reader;
+ use quick_xml::events::Event;
+
+ let mut reader = Reader::from_reader(data);
+ let mut out = WorkbookXml::default();
+ let mut buf = Vec::new();
+ // `<sheet>` also appears inside `<externalReferences>`' cached sheet
+ // names, which are another workbook's tabs; counting those would invent
+ // sheets that have no part here.
+ let mut in_sheets = false;
+
+ loop {
+ let event = reader
+ .read_event_into(&mut buf)
+ .map_err(quick_xml::DeError::from)?;
+ match event {
+ Event::Eof => break,
+ Event::Start(ref e) | Event::Empty(ref e) => {
+ match local_name(e.name().as_ref()) {
+ b"sheets" => in_sheets = !matches!(event, Event::Empty(_)),
+ b"sheet" if in_sheets => out.sheets.push(DeclaredSheet {
+ name: attr(e, b"name").unwrap_or_default(),
+ visible: !matches!(
+ attr(e, b"state").as_deref(),
+ Some("hidden" | "veryHidden")
+ ),
+ rel_id: attr(e, b"r:id"),
+ }),
+ b"workbookPr" => {
+ out.date1904 =
+ matches!(attr(e, b"date1904").as_deref(), Some("1" | "true"))
+ || matches!(
+ // ECMA-376 Strict renamed the attribute.
+ attr(e, b"dateCompatibility").as_deref(),
+ Some("0" | "false")
+ );
+ }
+ _ => {}
+ }
+ }
+ Event::End(ref e) if local_name(e.name().as_ref()) == b"sheets" => in_sheets = false,
+ _ => {}
+ }
+ buf.clear();
+ }
+ Ok(out)
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ const WORKBOOK: &str = r#"<?xml version="1.0"?>
+<workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main"
+ xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">
+ <workbookPr date1904="1"/>
+ <sheets>
+ <sheet name="Summary" sheetId="3" r:id="rId4"/>
+ <sheet name="Scratch" sheetId="1" state="hidden" r:id="rId5"/>
+ </sheets>
+ <externalReferences><externalReference r:id="rId9"/></externalReferences>
+ <definedNames><definedName name="Range1">Summary!$A$1</definedName></definedNames>
+</workbook>"#;
+
+ /// The regression this module exists for, inherited from `pptx::package`:
+ /// `<sheet>` carries both `@sheetId` and `@r:id`, and binding the numeric
+ /// one resolves no part at all.
+ #[test]
+ fn sheets_read_the_rel_id_not_the_numeric_id() {
+ let wb = parse_workbook(WORKBOOK.as_bytes()).unwrap();
+ let ids: Vec<_> = wb.sheets.iter().map(|s| s.rel_id.clone()).collect();
+ assert_eq!(ids, vec![Some("rId4".into()), Some("rId5".into())]);
+ }
+
+ #[test]
+ fn tab_order_and_names_come_from_the_sheets_list() {
+ let wb = parse_workbook(WORKBOOK.as_bytes()).unwrap();
+ // sheetId 3 is written first, so it is the first tab. Sorting by
+ // sheetId — or by part name — would reorder the workbook.
+ assert_eq!(
+ wb.sheets
+ .iter()
+ .map(|s| s.name.as_str())
+ .collect::<Vec<_>>(),
+ vec!["Summary", "Scratch"]
+ );
+ }
+
+ #[test]
+ fn hidden_state_is_reported_not_filtered() {
+ let wb = parse_workbook(WORKBOOK.as_bytes()).unwrap();
+ assert!(wb.sheets[0].visible);
+ assert!(!wb.sheets[1].visible);
+ }
+
+ /// An external reference caches the *other* workbook's sheet names in
+ /// `<sheet>` elements. They have no part here, so counting them would
+ /// invent sheets that then fail to resolve.
+ #[test]
+ fn external_reference_sheets_are_not_counted() {
+ let xml = r#"<workbook xmlns:r="r">
+ <sheets><sheet name="Real" sheetId="1" r:id="rId1"/></sheets>
+ <externalReferences><externalBook><sheetNames>
+ <sheet val="Other"/><sheet val="Another"/>
+ </sheetNames></externalBook></externalReferences>
+ </workbook>"#;
+ assert_eq!(parse_workbook(xml.as_bytes()).unwrap().sheets.len(), 1);
+ }
+
+ /// 123 of the 1,089 corpus workbooks are Mac Excel; getting this wrong
+ /// shifts every date in them by 1,462 days.
+ #[test]
+ fn the_1904_epoch_flag_is_read() {
+ assert!(parse_workbook(WORKBOOK.as_bytes()).unwrap().date1904);
+ let xml = r#"<workbook><workbookPr/><sheets/></workbook>"#;
+ assert!(!parse_workbook(xml.as_bytes()).unwrap().date1904);
+ let xml = r#"<workbook><sheets/></workbook>"#;
+ assert!(!parse_workbook(xml.as_bytes()).unwrap().date1904);
+ }
+
+ #[test]
+ fn a_sheet_with_no_rel_id_is_kept_out_of_the_list_by_the_walk() {
+ // parse_workbook keeps it (it is what the file says); `walk` is what
+ // drops it, because it has no part.
+ let xml = r#"<workbook><sheets><sheet name="Orphan" sheetId="1"/></sheets></workbook>"#;
+ let wb = parse_workbook(xml.as_bytes()).unwrap();
+ assert_eq!(wb.sheets.len(), 1);
+ assert!(wb.sheets[0].rel_id.is_none());
+ }
+}
diff --git a/crates/liteparse-ooxml/src/xlsx/refs.rs b/crates/liteparse-ooxml/src/xlsx/refs.rs
new file mode 100644
index 0000000..41c3c67
--- /dev/null
+++ b/crates/liteparse-ooxml/src/xlsx/refs.rs
@@ -0,0 +1,208 @@
+//! A1-style cell references (§18.17.2.4) and the ranges built from them.
+//!
+//! Everything in a worksheet is addressed this way — `<c r="B7">`,
+//! `<mergeCell ref="A1:C3">`, `<dimension ref="A1:Z100">` — so this is the one
+//! piece the sheet reader cannot proceed without.
+//!
+//! Indices are **zero-based** throughout. XLSX rows are one-based in the file
+//! (`A1` is row 1) and columns are letters; both are converted at the boundary
+//! so no other module has to remember which convention it is holding.
+
+/// A single cell address, zero-based on both axes. `A1` is `(0, 0)`.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
+pub struct CellRef {
+ pub row: u32,
+ pub col: u32,
+}
+
+/// A rectangular range, inclusive on both ends.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct RangeRef {
+ pub start: CellRef,
+ pub end: CellRef,
+}
+
+impl RangeRef {
+ pub fn rows(&self) -> u32 {
+ self.end.row.saturating_sub(self.start.row) + 1
+ }
+
+ pub fn cols(&self) -> u32 {
+ self.end.col.saturating_sub(self.start.col) + 1
+ }
+
+ pub fn contains(&self, cell: CellRef) -> bool {
+ cell.row >= self.start.row
+ && cell.row <= self.end.row
+ && cell.col >= self.start.col
+ && cell.col <= self.end.col
+ }
+}
+
+/// Parse a column label (`A`, `Z`, `AA`, `XFD`) to a zero-based index.
+///
+/// Bijective base-26: there is no zero digit, so `AA` is 26 rather than 0.
+/// Returns `None` on an empty or non-alphabetic label, and on anything past
+/// Excel's `XFD` limit — a label that long is corruption, and accepting it
+/// would let a bad `r=` allocate an absurd column.
+pub fn parse_column(label: &str) -> Option<u32> {
+ if label.is_empty() || label.len() > 3 {
+ return None;
+ }
+ let mut n: u32 = 0;
+ for b in label.bytes() {
+ let digit = match b {
+ b'A'..=b'Z' => b - b'A',
+ b'a'..=b'z' => b - b'a',
+ _ => return None,
+ };
+ n = n * 26 + digit as u32 + 1;
+ }
+ Some(n - 1)
+}
+
+/// Render a zero-based column index back to its label. Inverse of
+/// [`parse_column`]; used by diagnostics and by the emitter when it has to
+/// name a cell a human will look up in Excel.
+pub fn column_label(mut col: u32) -> String {
+ let mut out = Vec::new();
+ loop {
+ out.push(b'A' + (col % 26) as u8);
+ match col / 26 {
+ 0 => break,
+ n => col = n - 1,
+ }
+ }
+ out.reverse();
+ String::from_utf8(out).expect("ASCII only")
+}
+
+/// Parse a single cell reference. Absolute markers (`$A$1`) are accepted and
+/// ignored — they are a formula concern, and a `ref=` attribute may still
+/// carry them.
+pub fn parse_cell(s: &str) -> Option<CellRef> {
+ let s = s.trim();
+ let mut letters = String::new();
+ let mut digits = String::new();
+ for ch in s.chars() {
+ match ch {
+ '$' => continue,
+ 'A'..='Z' | 'a'..='z' if digits.is_empty() => letters.push(ch),
+ '0'..='9' => digits.push(ch),
+ // A sheet-qualified ref (`Sheet1!A1`) or anything else is not a
+ // plain cell address; the caller decides what to do with `None`.
+ _ => return None,
+ }
+ }
+ let col = parse_column(&letters)?;
+ // One-based in the file. Row 0 does not exist, so it is malformed input
+ // rather than something to clamp.
+ let row: u32 = digits.parse().ok()?;
+ Some(CellRef {
+ row: row.checked_sub(1)?,
+ col,
+ })
+}
+
+/// Parse a range. A bare cell (`A1`) is a legal one-cell range — Excel writes
+/// `<dimension ref="A1"/>` for a single-cell sheet.
+///
+/// Ranges are normalized so `start` is the top-left corner: `C3:A1` and
+/// `A1:C3` are the same rectangle, and a reader that trusted the written order
+/// would compute a negative span.
+pub fn parse_range(s: &str) -> Option<RangeRef> {
+ let (a, b) = match s.split_once(':') {
+ Some((a, b)) => (a, b),
+ None => (s, s),
+ };
+ let a = parse_cell(a)?;
+ let b = parse_cell(b)?;
+ Some(RangeRef {
+ start: CellRef {
+ row: a.row.min(b.row),
+ col: a.col.min(b.col),
+ },
+ end: CellRef {
+ row: a.row.max(b.row),
+ col: a.col.max(b.col),
+ },
+ })
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn columns_are_bijective_base_26() {
+ assert_eq!(parse_column("A"), Some(0));
+ assert_eq!(parse_column("Z"), Some(25));
+ // The trap: base-26 with a zero digit would make this 0, not 26.
+ assert_eq!(parse_column("AA"), Some(26));
+ assert_eq!(parse_column("AB"), Some(27));
+ assert_eq!(parse_column("BA"), Some(52));
+ // Excel's last column.
+ assert_eq!(parse_column("XFD"), Some(16_383));
+ }
+
+ #[test]
+ fn column_label_round_trips() {
+ for col in [0u32, 25, 26, 27, 51, 52, 701, 702, 16_383] {
+ assert_eq!(parse_column(&column_label(col)), Some(col), "col {col}");
+ }
+ }
+
+ #[test]
+ fn oversized_or_empty_column_labels_are_rejected() {
+ assert_eq!(parse_column(""), None);
+ assert_eq!(parse_column("AAAA"), None);
+ assert_eq!(parse_column("A1"), None);
+ }
+
+ #[test]
+ fn cell_refs_are_zero_based() {
+ assert_eq!(parse_cell("A1"), Some(CellRef { row: 0, col: 0 }));
+ assert_eq!(parse_cell("B7"), Some(CellRef { row: 6, col: 1 }));
+ assert_eq!(parse_cell("AA100"), Some(CellRef { row: 99, col: 26 }));
+ }
+
+ #[test]
+ fn absolute_markers_are_ignored() {
+ assert_eq!(parse_cell("$B$7"), parse_cell("B7"));
+ assert_eq!(parse_cell("$B7"), parse_cell("B7"));
+ }
+
+ #[test]
+ fn malformed_cell_refs_return_none() {
+ assert_eq!(parse_cell("A0"), None, "row 0 does not exist");
+ assert_eq!(parse_cell("1A"), None);
+ assert_eq!(parse_cell("Sheet1!A1"), None);
+ assert_eq!(parse_cell(""), None);
+ }
+
+ #[test]
+ fn a_bare_cell_is_a_one_cell_range() {
+ let r = parse_range("A1").unwrap();
+ assert_eq!(r.rows(), 1);
+ assert_eq!(r.cols(), 1);
+ }
+
+ #[test]
+ fn ranges_are_normalized_to_top_left_first() {
+ // A reader that trusted the written order would compute a negative
+ // span here and silently drop the merge.
+ let written = parse_range("C3:A1").unwrap();
+ assert_eq!(written, parse_range("A1:C3").unwrap());
+ assert_eq!(written.rows(), 3);
+ assert_eq!(written.cols(), 3);
+ }
+
+ #[test]
+ fn range_containment_is_inclusive() {
+ let r = parse_range("B2:D4").unwrap();
+ assert!(r.contains(parse_cell("B2").unwrap()));
+ assert!(r.contains(parse_cell("D4").unwrap()));
+ assert!(!r.contains(parse_cell("A2").unwrap()));
+ assert!(!r.contains(parse_cell("E4").unwrap()));
+ }
+}
diff --git a/crates/liteparse-ooxml/src/xlsx/sheet.rs b/crates/liteparse-ooxml/src/xlsx/sheet.rs
new file mode 100644
index 0000000..ccbb3b8
--- /dev/null
+++ b/crates/liteparse-ooxml/src/xlsx/sheet.rs
@@ -0,0 +1,652 @@
+//! A worksheet part (`xl/worksheets/sheetN.xml`, §18.3): the cell grid, the
+//! row/column metrics the grid is drawn on, and the merges that break it.
+//!
+//! Streamed rather than deserialized. Sheets are the bulk of a workbook — 50.3M
+//! cells across the 1,089-workbook finance corpus, single sheets past 32 MB —
+//! and this is the one part where the reader's memory profile is decided.
+//!
+//! Two allocation decisions follow from that and are load-bearing:
+//!
+//! * **Shared strings are not resolved here.** A cell keeps its index into the
+//! shared-string table. The table exists precisely so a string used 40,000
+//! times is stored once; resolving eagerly would undo that. See
+//! [`crate::xlsx::Workbook::cell_text`].
+//! * **Value-less cells are dropped.** `<c r="A1" s="7"/>` carries a style and
+//! no content — usually a bordered-but-blank region, and in some producers
+//! an entire pre-formatted sheet. They are counted in [`SheetStats`] rather
+//! than stored, because a workbook can hold millions of them and none of
+//! them carries text.
+
+use quick_xml::Reader;
+use quick_xml::events::Event;
+
+use crate::docx::error::Result;
+use crate::xlsx::refs::{CellRef, RangeRef, parse_cell, parse_range};
+use crate::xlsx::text::{RichText, TextRun, read_rich_text};
+use crate::xlsx::xml::{
+ attr, attr_bool, attr_parse, decode_cdata, decode_general_ref, decode_text, local_name,
+};
+
+/// A cell's value, as the file states it.
+#[derive(Clone, Debug, PartialEq)]
+pub enum CellValue {
+ /// `t="n"` or, far more often, no `t=` at all — the default and the single
+ /// most common cell in any workbook. Dates live here too: Excel stores
+ /// them as serial numbers and only the format code says otherwise.
+ Number(f64),
+ /// `t="s"`: an index into the workbook's shared-string table.
+ SharedString(u32),
+ /// `t="inlineStr"` (`<is>`) or `t="str"` (a formula's cached string
+ /// result). Both carry their text in the cell.
+ Text(RichText),
+ /// `t="b"`, written as `0` / `1`.
+ Bool(bool),
+ /// `t="e"`: `#DIV/0!`, `#N/A`, `#REF!` and friends, kept verbatim because
+ /// the error text is what a reader of the sheet sees.
+ Error(String),
+ /// `t="d"`: an ISO 8601 date, written literally rather than as a serial.
+ /// Only ECMA-376 Strict and a few non-Excel producers emit this.
+ Date(String),
+}
+
+/// One cell that carries a value.
+#[derive(Clone, Debug)]
+pub struct Cell {
+ pub at: CellRef,
+ /// The `s=` index into `<cellXfs>`; `None` means style 0 / General.
+ pub style: Option<u32>,
+ pub value: CellValue,
+ /// The cell holds an `<f>`. The formula text itself is not kept — the
+ /// cached `<v>` is what renders, and 49.3% of corpus workbooks have
+ /// formulas, so storing their source would be pure weight.
+ pub has_formula: bool,
+}
+
+/// A row that exists in the file, with its own metrics.
+#[derive(Clone, Debug, Default)]
+pub struct Row {
+ /// Zero-based.
+ pub index: u32,
+ /// `ht=` in points, when the row states its own height.
+ pub height: Option<f64>,
+ pub hidden: bool,
+ /// Cells in written order, which is ascending column order in every
+ /// producer seen. Sparse: absent columns are absent.
+ pub cells: Vec<Cell>,
+}
+
+/// A `<col>` span's metrics. One entry covers columns `min..=max`, both
+/// zero-based here (the file writes them one-based).
+#[derive(Clone, Debug)]
+pub struct ColInfo {
+ pub min: u32,
+ pub max: u32,
+ /// Excel's column width unit: the count of `0` glyphs of the Normal font
+ /// that fit in the column. Converting it to points needs the font's digit
+ /// width, so it is kept raw here and converted by the geometry pass.
+ pub width: Option<f64>,
+ pub hidden: bool,
+ pub custom_width: bool,
+}
+
+#[derive(Clone, Debug)]
+pub struct Hyperlink {
+ pub at: RangeRef,
+ /// The `r:id` to resolve against the sheet's own relationships. Absent for
+ /// an in-workbook link, which carries only a `location`.
+ pub rel_id: Option<String>,
+ /// `location=`: a defined name or `Sheet2!A1` target within the workbook.
+ pub location: Option<String>,
+ pub tooltip: Option<String>,
+}
+
+/// Counts kept for the census and for the emitter's routing decisions —
+/// things that were seen and deliberately not stored.
+#[derive(Clone, Copy, Debug, Default)]
+pub struct SheetStats {
+ /// Cells with a style and no value. See the module docs for why they are
+ /// dropped.
+ pub empty_styled_cells: u32,
+ /// Cells whose `r=` was absent or unparseable and whose position was
+ /// inferred from document order. Non-zero means a producer that is not
+ /// Excel; worth knowing before trusting the geometry.
+ pub inferred_positions: u32,
+ /// `<c t="s">` whose `<v>` is not a usable index into the shared-string
+ /// table — unparseable here, out of range when resolved. Always a bug in
+ /// the producer or in this reader, never normal.
+ pub dangling_shared_strings: u32,
+}
+
+/// One parsed worksheet.
+#[derive(Clone, Debug, Default)]
+pub struct Sheet {
+ /// The tab name from `<sheet name=…>` in the workbook part, not from the
+ /// sheet itself — a worksheet part does not know what it is called.
+ pub name: String,
+ pub visible: bool,
+ /// `<dimension ref=…>`: the producer's claim about the used range. A
+ /// claim, not a guarantee — some producers write `A1` regardless — so it
+ /// is exposed for cross-checking rather than used to size anything.
+ pub dimension: Option<RangeRef>,
+ pub default_col_width: Option<f64>,
+ pub default_row_height: Option<f64>,
+ pub cols: Vec<ColInfo>,
+ pub rows: Vec<Row>,
+ /// Present in 80.7% of real workbooks, which is why they are read by the
+ /// first version of this reader rather than deferred.
+ pub merges: Vec<RangeRef>,
+ pub hyperlinks: Vec<Hyperlink>,
+ /// `<pane ySplit=… state="frozen">`: rows frozen at the top. A direct
+ /// statement that those rows are a header, which is otherwise the hardest
+ /// thing to infer about a spreadsheet.
+ pub frozen_rows: u32,
+ pub frozen_cols: u32,
+ /// `<autoFilter ref=…>`, the other explicit header signal.
+ pub auto_filter: Option<RangeRef>,
+ pub stats: SheetStats,
+}
+
+impl Sheet {
+ pub fn cell_count(&self) -> usize {
+ self.rows.iter().map(|r| r.cells.len()).sum()
+ }
+
+ /// The merge whose top-left corner is `at`, if any. The anchor is the only
+ /// cell of a merged region that carries a value; Excel writes the rest as
+ /// value-less cells, which this reader has already dropped.
+ pub fn merge_anchored_at(&self, at: CellRef) -> Option<&RangeRef> {
+ self.merges.iter().find(|m| m.start == at)
+ }
+
+ /// The merge covering `at`, anchor or not.
+ pub fn merge_covering(&self, at: CellRef) -> Option<&RangeRef> {
+ self.merges.iter().find(|m| m.contains(at))
+ }
+
+ /// The declared width of a column, walking the `<col>` spans.
+ pub fn col_width(&self, col: u32) -> Option<f64> {
+ self.cols
+ .iter()
+ .find(|c| col >= c.min && col <= c.max)
+ .and_then(|c| c.width)
+ .or(self.default_col_width)
+ }
+}
+
+/// Parse one worksheet part.
+pub fn parse(name: &str, visible: bool, data: &[u8]) -> Result<Sheet> {
+ let mut sheet = Sheet {
+ name: name.to_string(),
+ visible,
+ ..Sheet::default()
+ };
+ let mut reader = Reader::from_reader(data);
+ let mut buf = Vec::new();
+ // A separate buffer for nested reads: `buf` is borrowed by the event
+ // currently being matched, so `<is>` cannot recurse into it.
+ let mut nested_buf = Vec::new();
+
+ let mut row: Option<Row> = None;
+ let mut cell: Option<PendingCell> = None;
+ // The running position used when a producer omits `r=`. §18.3.1.4 makes
+ // the attribute optional, in which case position is document order.
+ let mut next_row: u32 = 0;
+ let mut next_col: u32 = 0;
+ let mut in_value = false;
+ let mut value = String::new();
+ // `<pane>` also appears under `<customSheetView>`, where it describes a
+ // saved view rather than the sheet as opened. Only the first `<sheetView>`
+ // one is the frozen-header signal.
+ let mut in_sheet_view = false;
+
+ loop {
+ let event = reader
+ .read_event_into(&mut buf)
+ .map_err(quick_xml::DeError::from)?;
+ match event {
+ Event::Eof => break,
+ Event::Start(ref e) | Event::Empty(ref e) => {
+ let empty = matches!(event, Event::Empty(_));
+ match local_name(e.name().as_ref()) {
+ b"dimension" => {
+ sheet.dimension = attr(e, b"ref").as_deref().and_then(parse_range);
+ }
+ b"sheetFormatPr" => {
+ sheet.default_col_width = attr_parse(e, b"defaultColWidth");
+ sheet.default_row_height = attr_parse(e, b"defaultRowHeight");
+ }
+ b"sheetView" => in_sheet_view = !empty,
+ b"pane" if in_sheet_view => {
+ // `state="split"` is a draggable divider, not a frozen
+ // header; only frozen panes state that rows above the
+ // split are repeated context.
+ if matches!(attr(e, b"state").as_deref(), Some("frozen" | "frozenSplit")) {
+ sheet.frozen_rows = attr_parse(e, b"ySplit").unwrap_or(0);
+ sheet.frozen_cols = attr_parse(e, b"xSplit").unwrap_or(0);
+ }
+ }
+ b"col" => {
+ // One-based and inclusive in the file.
+ let min: u32 = attr_parse(e, b"min").unwrap_or(1);
+ let max: u32 = attr_parse(e, b"max").unwrap_or(min);
+ sheet.cols.push(ColInfo {
+ min: min.saturating_sub(1),
+ max: max.saturating_sub(1),
+ width: attr_parse(e, b"width"),
+ hidden: attr_bool(e, b"hidden", false),
+ custom_width: attr_bool(e, b"customWidth", false),
+ });
+ }
+ b"row" => {
+ let index = match attr_parse::<u32>(e, b"r") {
+ Some(r) if r >= 1 => r - 1,
+ _ => next_row,
+ };
+ next_row = index + 1;
+ next_col = 0;
+ let started = Row {
+ index,
+ height: attr_parse(e, b"ht"),
+ hidden: attr_bool(e, b"hidden", false),
+ cells: Vec::new(),
+ };
+ // An empty `<row/>` still carries height and hidden
+ // state, which the geometry pass needs.
+ if empty {
+ sheet.rows.push(started);
+ } else {
+ row = Some(started);
+ }
+ }
+ b"c" => {
+ let at = match attr(e, b"r").as_deref().and_then(parse_cell) {
+ Some(at) => at,
+ None => {
+ sheet.stats.inferred_positions += 1;
+ CellRef {
+ row: row.as_ref().map_or(next_row, |r| r.index),
+ col: next_col,
+ }
+ }
+ };
+ next_col = at.col + 1;
+ let pending = PendingCell {
+ at,
+ style: attr_parse(e, b"s"),
+ kind: attr(e, b"t").unwrap_or_else(|| "n".to_string()),
+ has_formula: false,
+ text: None,
+ };
+ if empty {
+ // No children means no value: styled-but-blank.
+ sheet.stats.empty_styled_cells += 1;
+ } else {
+ cell = Some(pending);
+ }
+ }
+ b"v" if cell.is_some() => {
+ in_value = !empty;
+ value.clear();
+ }
+ b"f" if cell.is_some() => {
+ if let Some(c) = cell.as_mut() {
+ c.has_formula = true;
+ }
+ }
+ b"is" if cell.is_some() && !empty => {
+ let text = read_rich_text(&mut reader, &mut nested_buf, b"is")?;
+ if let Some(c) = cell.as_mut() {
+ c.text = Some(text);
+ }
+ }
+ b"mergeCell" => {
+ if let Some(r) = attr(e, b"ref").as_deref().and_then(parse_range) {
+ sheet.merges.push(r);
+ }
+ }
+ b"hyperlink" => {
+ if let Some(at) = attr(e, b"ref").as_deref().and_then(parse_range) {
+ sheet.hyperlinks.push(Hyperlink {
+ at,
+ rel_id: attr(e, b"r:id"),
+ location: attr(e, b"location"),
+ tooltip: attr(e, b"tooltip"),
+ });
+ }
+ }
+ b"autoFilter" => {
+ sheet.auto_filter = attr(e, b"ref").as_deref().and_then(parse_range);
+ }
+ _ => {}
+ }
+ }
+ Event::Text(ref t) if in_value => value.push_str(&decode_text(t)?),
+ Event::CData(ref c) if in_value => value.push_str(&decode_cdata(c)?),
+ // A `t="str"` cell's cached text arrives entity-split, same as a
+ // shared string; see `xml::decode_general_ref`.
+ Event::GeneralRef(ref r) if in_value => value.push_str(&decode_general_ref(r)?),
+ Event::End(ref e) => match local_name(e.name().as_ref()) {
+ b"sheetView" => in_sheet_view = false,
+ b"v" => in_value = false,
+ b"c" => {
+ if let Some(pending) = cell.take() {
+ finish_cell(pending, &value, &mut row, &mut sheet);
+ value.clear();
+ }
+ }
+ b"row" => {
+ if let Some(r) = row.take() {
+ sheet.rows.push(r);
+ }
+ }
+ _ => {}
+ },
+ _ => {}
+ }
+ buf.clear();
+ }
+
+ // A `</row>` or `</c>` lost to a truncated file still yields what was read.
+ if let Some(pending) = cell.take() {
+ finish_cell(pending, &value, &mut row, &mut sheet);
+ }
+ if let Some(r) = row.take() {
+ sheet.rows.push(r);
+ }
+ Ok(sheet)
+}
+
+struct PendingCell {
+ at: CellRef,
+ style: Option<u32>,
+ kind: String,
+ has_formula: bool,
+ text: Option<RichText>,
+}
+
+fn finish_cell(pending: PendingCell, raw: &str, row: &mut Option<Row>, sheet: &mut Sheet) {
+ let value = match pending.kind.as_str() {
+ "inlineStr" => pending.text.map(CellValue::Text),
+ // An empty body is a styled-but-blank cell that the producer happened
+ // to write as `<c …></c>` rather than `<c …/>`. Not corruption, and
+ // counting it as a dangling index would report 480 fake anomalies on
+ // one corpus workbook — which is exactly what it did before this
+ // distinction existed.
+ "s" if raw.trim().is_empty() => None,
+ "s" => match raw.trim().parse::<u32>() {
+ Ok(i) => Some(CellValue::SharedString(i)),
+ Err(_) => {
+ sheet.stats.dangling_shared_strings += 1;
+ None
+ }
+ },
+ // A formula's cached string result. Plain text with no runs — the
+ // `<is>` grammar does not apply here.
+ "str" => (!raw.is_empty()).then(|| {
+ CellValue::Text(RichText {
+ runs: vec![TextRun {
+ text: raw.to_string(),
+ props: Default::default(),
+ }],
+ })
+ }),
+ "b" => Some(CellValue::Bool(raw.trim() != "0")),
+ "e" => (!raw.is_empty()).then(|| CellValue::Error(raw.trim().to_string())),
+ "d" => (!raw.is_empty()).then(|| CellValue::Date(raw.trim().to_string())),
+ // "n" and anything unrecognised. A number that will not parse is not
+ // a number: dropping it is right, because emitting `NaN` would put a
+ // value in a cell the spreadsheet shows as blank.
+ _ => raw.trim().parse::<f64>().ok().map(CellValue::Number),
+ };
+
+ let Some(value) = value else {
+ sheet.stats.empty_styled_cells += 1;
+ return;
+ };
+ let cell = Cell {
+ at: pending.at,
+ style: pending.style,
+ value,
+ has_formula: pending.has_formula,
+ };
+ // A `<c>` outside any `<row>` is malformed but recoverable: give it a row
+ // of its own rather than losing the value.
+ match row.as_mut() {
+ Some(r) => r.cells.push(cell),
+ None => sheet.rows.push(Row {
+ index: cell.at.row,
+ cells: vec![cell],
+ ..Row::default()
+ }),
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ const SHEET: &str = r#"<?xml version="1.0"?>
+<worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main"
+ xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">
+ <dimension ref="A1:C4"/>
+ <sheetViews><sheetView><pane xSplit="1" ySplit="2" topLeftCell="B3" state="frozen"/></sheetView></sheetViews>
+ <sheetFormatPr defaultRowHeight="15" defaultColWidth="8.43"/>
+ <cols>
+ <col min="1" max="1" width="24.5" customWidth="1"/>
+ <col min="2" max="3" width="12" hidden="1"/>
+ </cols>
+ <sheetData>
+ <row r="1" ht="30" customHeight="1">
+ <c r="A1" t="s"><v>0</v></c>
+ <c r="B1" s="2"/>
+ </row>
+ <row r="2">
+ <c r="A2"><v>1234.5</v></c>
+ <c r="B2" t="b"><v>1</v></c>
+ <c r="C2" t="e"><v>#DIV/0!</v></c>
+ </row>
+ <row r="4" hidden="1">
+ <c r="A4" t="inlineStr"><is><r><rPr><b/></rPr><t>inline</t></r></is></c>
+ <c r="B4" t="str"><f>CONCAT(A1)</f><v>computed</v></c>
+ </row>
+ </sheetData>
+ <autoFilter ref="A1:C4"/>
+ <mergeCells count="1"><mergeCell ref="A1:C1"/></mergeCells>
+ <hyperlinks><hyperlink ref="A2" r:id="rId1" tooltip="go"/></hyperlinks>
+</worksheet>"#;
+
+ fn sheet() -> Sheet {
+ parse("Sheet1", true, SHEET.as_bytes()).unwrap()
+ }
+
+ #[test]
+ fn rows_keep_their_declared_index_not_their_position() {
+ let s = sheet();
+ // Row 3 is absent from the file; the fourth row must stay row 4
+ // (index 3), or every metric below it shifts up one.
+ assert_eq!(
+ s.rows.iter().map(|r| r.index).collect::<Vec<_>>(),
+ vec![0, 1, 3]
+ );
+ }
+
+ #[test]
+ fn cell_values_are_typed_by_their_t_attribute() {
+ let s = sheet();
+ assert_eq!(s.rows[0].cells[0].value, CellValue::SharedString(0));
+ assert_eq!(s.rows[1].cells[0].value, CellValue::Number(1234.5));
+ assert_eq!(s.rows[1].cells[1].value, CellValue::Bool(true));
+ assert_eq!(
+ s.rows[1].cells[2].value,
+ CellValue::Error("#DIV/0!".to_string())
+ );
+ }
+
+ #[test]
+ fn a_cell_with_no_t_attribute_is_a_number() {
+ // The single most common cell in any workbook carries no type marker.
+ assert_eq!(sheet().rows[1].cells[0].value, CellValue::Number(1234.5));
+ }
+
+ #[test]
+ fn inline_strings_keep_their_runs() {
+ let s = sheet();
+ let CellValue::Text(ref t) = s.rows[2].cells[0].value else {
+ panic!("expected inline text");
+ };
+ assert_eq!(t.plain(), "inline");
+ assert!(t.runs[0].props.bold);
+ }
+
+ /// `<is>` is consumed by a nested reader loop. If it did not resume
+ /// cleanly, the rest of the row — here the `t="str"` cell after it —
+ /// would be lost.
+ #[test]
+ fn parsing_resumes_after_an_inline_string() {
+ let s = sheet();
+ assert_eq!(s.rows[2].cells.len(), 2);
+ let CellValue::Text(ref t) = s.rows[2].cells[1].value else {
+ panic!("expected the formula's cached string");
+ };
+ assert_eq!(t.plain(), "computed");
+ assert!(s.rows[2].cells[1].has_formula);
+ }
+
+ #[test]
+ fn styled_but_valueless_cells_are_counted_not_stored() {
+ let s = sheet();
+ assert_eq!(s.rows[0].cells.len(), 1, "B1 has a style and no value");
+ assert_eq!(s.stats.empty_styled_cells, 1);
+ }
+
+ #[test]
+ fn merges_and_filters_and_frozen_panes_are_read() {
+ let s = sheet();
+ assert_eq!(s.merges.len(), 1);
+ assert_eq!(s.merges[0], parse_range("A1:C1").unwrap());
+ assert_eq!(s.auto_filter, Some(parse_range("A1:C4").unwrap()));
+ assert_eq!(s.frozen_rows, 2);
+ assert_eq!(s.frozen_cols, 1);
+ }
+
+ /// `state="split"` is a draggable divider, not a header declaration.
+ #[test]
+ fn split_panes_are_not_frozen_rows() {
+ let xml = r#"<worksheet><sheetViews><sheetView>
+ <pane xSplit="1" ySplit="2" state="split"/>
+ </sheetView></sheetViews><sheetData/></worksheet>"#;
+ let s = parse("s", true, xml.as_bytes()).unwrap();
+ assert_eq!(s.frozen_rows, 0);
+ }
+
+ #[test]
+ fn col_spans_are_zero_based_and_inclusive() {
+ let s = sheet();
+ assert_eq!(s.col_width(0), Some(24.5));
+ assert_eq!(s.col_width(1), Some(12.0));
+ assert_eq!(s.col_width(2), Some(12.0), "max is inclusive");
+ assert_eq!(s.col_width(3), Some(8.43), "falls back to the default");
+ assert!(s.cols[1].hidden);
+ }
+
+ #[test]
+ fn row_metrics_survive() {
+ let s = sheet();
+ assert_eq!(s.rows[0].height, Some(30.0));
+ assert!(!s.rows[0].hidden);
+ assert!(s.rows[2].hidden);
+ }
+
+ #[test]
+ fn hyperlinks_carry_their_rel_id() {
+ let s = sheet();
+ assert_eq!(s.hyperlinks[0].rel_id.as_deref(), Some("rId1"));
+ assert_eq!(s.hyperlinks[0].tooltip.as_deref(), Some("go"));
+ }
+
+ /// §18.3.1.4 makes `r=` optional on both `<row>` and `<c>`; a handful of
+ /// non-Excel producers omit it and position is then document order.
+ #[test]
+ fn positions_are_inferred_when_r_is_absent() {
+ let xml = r#"<worksheet><sheetData>
+ <row><c><v>1</v></c><c><v>2</v></c></row>
+ <row><c><v>3</v></c></row>
+ </sheetData></worksheet>"#;
+ let s = parse("s", true, xml.as_bytes()).unwrap();
+ assert_eq!(s.rows[0].cells[0].at, CellRef { row: 0, col: 0 });
+ assert_eq!(s.rows[0].cells[1].at, CellRef { row: 0, col: 1 });
+ assert_eq!(s.rows[1].cells[0].at, CellRef { row: 1, col: 0 });
+ assert_eq!(s.stats.inferred_positions, 3);
+ }
+
+ /// A partial `r=` run must not shift the cells that do declare one.
+ #[test]
+ fn an_explicit_ref_resets_the_running_column() {
+ let xml = r#"<worksheet><sheetData>
+ <row r="1"><c><v>1</v></c><c r="E1"><v>2</v></c><c><v>3</v></c></row>
+ </sheetData></worksheet>"#;
+ let s = parse("s", true, xml.as_bytes()).unwrap();
+ let cols: Vec<u32> = s.rows[0].cells.iter().map(|c| c.at.col).collect();
+ assert_eq!(cols, vec![0, 4, 5]);
+ }
+
+ /// `<c t="s"></c>` — a blank cell a producer wrote with an explicit close
+ /// tag instead of self-closing. It is styled-but-blank, not a broken
+ /// index; one corpus workbook has 480 of them.
+ #[test]
+ fn an_empty_shared_string_cell_is_blank_not_dangling() {
+ let xml = r#"<worksheet><sheetData><row r="1">
+ <c r="A1" s="3" t="s"></c><c r="B1" t="s"><v>0</v></c>
+ </row></sheetData></worksheet>"#;
+ let s = parse("s", true, xml.as_bytes()).unwrap();
+ assert_eq!(s.cell_count(), 1);
+ assert_eq!(s.stats.dangling_shared_strings, 0);
+ assert_eq!(s.stats.empty_styled_cells, 1);
+ }
+
+ /// A `t="s"` cell whose `<v>` is not an index *is* corruption, and must
+ /// stay visible in the stats rather than being folded into the blanks.
+ #[test]
+ fn an_unparseable_shared_string_index_is_reported() {
+ let xml = r#"<worksheet><sheetData><row r="1">
+ <c r="A1" t="s"><v>seven</v></c>
+ </row></sheetData></worksheet>"#;
+ let s = parse("s", true, xml.as_bytes()).unwrap();
+ assert_eq!(s.stats.dangling_shared_strings, 1);
+ }
+
+ #[test]
+ fn a_number_that_will_not_parse_is_dropped_not_nan() {
+ let xml = r#"<worksheet><sheetData><row r="1">
+ <c r="A1"><v>#N/A</v></c><c r="B1"><v>7</v></c>
+ </row></sheetData></worksheet>"#;
+ let s = parse("s", true, xml.as_bytes()).unwrap();
+ assert_eq!(s.rows[0].cells.len(), 1);
+ assert_eq!(s.rows[0].cells[0].value, CellValue::Number(7.0));
+ }
+
+ #[test]
+ fn a_truncated_sheet_yields_what_was_read() {
+ let xml = r#"<worksheet><sheetData><row r="1"><c r="A1"><v>5</v>"#;
+ let s = parse("s", true, xml.as_bytes()).unwrap();
+ assert_eq!(s.cell_count(), 1);
+ assert_eq!(s.rows[0].cells[0].value, CellValue::Number(5.0));
+ }
+
+ #[test]
+ fn merge_lookup_distinguishes_the_anchor_from_the_covered_cells() {
+ let s = sheet();
+ let a1 = parse_cell("A1").unwrap();
+ let b1 = parse_cell("B1").unwrap();
+ assert!(s.merge_anchored_at(a1).is_some());
+ assert!(s.merge_anchored_at(b1).is_none());
+ assert!(s.merge_covering(b1).is_some());
+ }
+
+ #[test]
+ fn an_empty_sheet_parses_to_nothing() {
+ let s = parse("s", true, b"<worksheet><sheetData/></worksheet>").unwrap();
+ assert_eq!(s.cell_count(), 0);
+ assert!(s.rows.is_empty());
+ }
+}
diff --git a/crates/liteparse-ooxml/src/xlsx/styles.rs b/crates/liteparse-ooxml/src/xlsx/styles.rs
new file mode 100644
index 0000000..fe00f65
--- /dev/null
+++ b/crates/liteparse-ooxml/src/xlsx/styles.rs
@@ -0,0 +1,445 @@
+//! `xl/styles.xml` (§18.8): the indirection from a cell's `s=` to the things a
+//! renderer needs — the number-format code, the font, the alignment.
+//!
+//! The chain is `<c s="7">` → `<cellXfs>` entry 7 → its `numFmtId` → either a
+//! builtin code (§18.8.30) or the workbook's own `<numFmt>`.
+//!
+//! **Two containers in this part hold identically-named children, and reading
+//! the wrong one fails silently rather than loudly**, which is why every
+//! collector below is gated on its enclosing element:
+//!
+//! * `<cellStyleXfs>` also holds `<xf>` elements. Only `<cellXfs>` is indexed
+//! by a cell's `s=`. Reading the other array yields plausible-looking
+//! formats attached to the wrong cells.
+//! * `<dxfs>` (differential formats, used by conditional formatting) also
+//! holds `<font>` elements. Appending those to the font list shifts every
+//! `fontId` above them.
+
+use std::collections::HashMap;
+
+use quick_xml::Reader;
+use quick_xml::events::Event;
+
+use crate::docx::error::Result;
+use crate::xlsx::xml::{attr, attr_bool, attr_parse, local_name};
+
+/// The format code applied when a cell names no style at all.
+pub const GENERAL: &str = "General";
+
+/// Custom format ids start here (§18.8.30); anything below with no builtin
+/// entry is reserved and Excel does not write it.
+pub const FIRST_CUSTOM_FORMAT_ID: u32 = 164;
+
+/// ECMA-376 §18.8.30 builtin number formats.
+///
+/// Ids 23–36 and 41–44 are absent on purpose: the spec reserves them or makes
+/// them locale-dependent, Excel does not write them, and a reader that invents
+/// codes for them is guessing at the user's locale.
+const BUILTIN_FORMATS: &[(u32, &str)] = &[
+ (0, "General"),
+ (1, "0"),
+ (2, "0.00"),
+ (3, "#,##0"),
+ (4, "#,##0.00"),
+ (9, "0%"),
+ (10, "0.00%"),
+ (11, "0.00E+00"),
+ (12, "# ?/?"),
+ (13, "# ??/??"),
+ (14, "mm-dd-yy"),
+ (15, "d-mmm-yy"),
+ (16, "d-mmm"),
+ (17, "mmm-yy"),
+ (18, "h:mm AM/PM"),
+ (19, "h:mm:ss AM/PM"),
+ (20, "h:mm"),
+ (21, "h:mm:ss"),
+ (22, "m/d/yy h:mm"),
+ (37, "#,##0 ;(#,##0)"),
+ (38, "#,##0 ;[Red](#,##0)"),
+ (39, "#,##0.00;(#,##0.00)"),
+ (40, "#,##0.00;[Red](#,##0.00)"),
+ (45, "mm:ss"),
+ (46, "[h]:mm:ss"),
+ (47, "mmss.0"),
+ (48, "##0.0E+0"),
+ (49, "@"),
+];
+
+/// Look up a builtin format code by id.
+pub fn builtin_format(id: u32) -> Option<&'static str> {
+ BUILTIN_FORMATS
+ .iter()
+ .find_map(|&(k, code)| (k == id).then_some(code))
+}
+
+/// Character formatting from `<fonts>`. Mirrors
+/// [`RunProps`](crate::xlsx::text::RunProps), which is the run-level version of
+/// the same properties — a cell takes this one, and a rich run overrides it.
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct Font {
+ pub bold: bool,
+ pub italic: bool,
+ pub strike: bool,
+ pub underline: bool,
+ pub size: Option<f32>,
+ pub name: Option<String>,
+}
+
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub enum HorizontalAlign {
+ /// §18.18.40: numbers right, text left. The default, and the reason a
+ /// spreadsheet reads as a table without any explicit alignment at all.
+ #[default]
+ General,
+ Left,
+ Center,
+ Right,
+ Fill,
+ Justify,
+ CenterContinuous,
+ Distributed,
+}
+
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct Alignment {
+ pub horizontal: HorizontalAlign,
+ pub wrap_text: bool,
+ /// Indent steps, each 3 spaces' worth in Excel's rendering. Load-bearing
+ /// for structure: indented labels are how spreadsheets express hierarchy.
+ pub indent: u32,
+ /// Degrees counter-clockwise, or 255 for stacked/vertical text (§18.8.1).
+ pub text_rotation: Option<u32>,
+}
+
+/// One `<cellXfs>` entry — the record a cell's `s=` points at.
+#[derive(Clone, Debug, Default)]
+pub struct CellXf {
+ pub num_fmt_id: u32,
+ pub font_id: u32,
+ pub alignment: Alignment,
+ /// `quotePrefix="1"`: the user typed a leading apostrophe to force text.
+ /// The apostrophe is not in the cell value, so it must not be emitted, but
+ /// it does mean the value is text no matter what it looks like.
+ pub quote_prefix: bool,
+}
+
+/// The parsed `xl/styles.xml`.
+#[derive(Clone, Debug, Default)]
+pub struct Styles {
+ /// Workbook-defined codes from `<numFmts>`, keyed by id.
+ ///
+ /// A custom id may legally redefine a builtin one, and may carry the code
+ /// `General`; both are in the corpus, so custom entries are consulted
+ /// first and never assumed to be "not General".
+ custom_formats: HashMap<u32, String>,
+ cell_xfs: Vec<CellXf>,
+ fonts: Vec<Font>,
+}
+
+impl Styles {
+ /// Parse `xl/styles.xml`.
+ pub fn parse(data: &[u8]) -> Result<Self> {
+ let mut out = Styles::default();
+ let mut reader = Reader::from_reader(data);
+ let mut buf = Vec::new();
+ // Which array we are inside. `<xf>` and `<font>` each appear under
+ // more than one parent; see the module docs.
+ let mut in_cell_xfs = false;
+ let mut in_fonts = false;
+ let mut current_xf: Option<CellXf> = None;
+ let mut current_font: Option<Font> = None;
+
+ loop {
+ let event = reader
+ .read_event_into(&mut buf)
+ .map_err(quick_xml::DeError::from)?;
+ let (start, empty) = match event {
+ Event::Eof => break,
+ Event::Start(ref e) => (Some(e), false),
+ Event::Empty(ref e) => (Some(e), true),
+ Event::End(ref e) => {
+ match local_name(e.name().as_ref()) {
+ b"cellXfs" => in_cell_xfs = false,
+ b"fonts" => in_fonts = false,
+ b"xf" => {
+ if let Some(xf) = current_xf.take() {
+ out.cell_xfs.push(xf);
+ }
+ }
+ b"font" => {
+ if let Some(font) = current_font.take() {
+ out.fonts.push(font);
+ }
+ }
+ _ => {}
+ }
+ buf.clear();
+ continue;
+ }
+ _ => {
+ buf.clear();
+ continue;
+ }
+ };
+ let Some(e) = start else { unreachable!() };
+
+ match local_name(e.name().as_ref()) {
+ b"cellXfs" => in_cell_xfs = !empty,
+ b"fonts" => in_fonts = !empty,
+ b"numFmt" => {
+ // `<numFmt>` appears both in the workbook-level `<numFmts>`
+ // and inside `<dxf>`. Collecting both is harmless — they
+ // share one id space and a dxf restates rather than
+ // redefines — so this one is not container-gated.
+ if let (Some(id), Some(code)) =
+ (attr_parse(e, b"numFmtId"), attr(e, b"formatCode"))
+ {
+ out.custom_formats.insert(id, code);
+ }
+ }
+ b"xf" if in_cell_xfs => {
+ let xf = CellXf {
+ num_fmt_id: attr_parse(e, b"numFmtId").unwrap_or(0),
+ font_id: attr_parse(e, b"fontId").unwrap_or(0),
+ alignment: Alignment::default(),
+ quote_prefix: attr_bool(e, b"quotePrefix", false),
+ };
+ if empty {
+ out.cell_xfs.push(xf);
+ } else {
+ // A non-empty `<xf>` still has an `<alignment>` child
+ // to read before it can be pushed.
+ current_xf = Some(xf);
+ }
+ }
+ b"alignment" => {
+ if let Some(xf) = current_xf.as_mut() {
+ xf.alignment = Alignment {
+ horizontal: match attr(e, b"horizontal").as_deref() {
+ Some("left") => HorizontalAlign::Left,
+ Some("center") => HorizontalAlign::Center,
+ Some("right") => HorizontalAlign::Right,
+ Some("fill") => HorizontalAlign::Fill,
+ Some("justify") => HorizontalAlign::Justify,
+ Some("centerContinuous") => HorizontalAlign::CenterContinuous,
+ Some("distributed") => HorizontalAlign::Distributed,
+ _ => HorizontalAlign::General,
+ },
+ wrap_text: attr_bool(e, b"wrapText", false),
+ indent: attr_parse(e, b"indent").unwrap_or(0),
+ text_rotation: attr_parse::<u32>(e, b"textRotation")
+ .filter(|&r| r != 0),
+ };
+ }
+ }
+ b"font" if in_fonts => {
+ let font = Font::default();
+ if empty {
+ out.fonts.push(font);
+ } else {
+ current_font = Some(font);
+ }
+ }
+ name if current_font.is_some() => {
+ let font = current_font.as_mut().expect("checked by the guard");
+ // Same CT_BooleanProperty rule as run properties: an
+ // explicit `val="0"` turns the property off.
+ let on = || !matches!(attr(e, b"val").as_deref(), Some("0" | "false"));
+ match name {
+ b"b" => font.bold = on(),
+ b"i" => font.italic = on(),
+ b"strike" => font.strike = on(),
+ b"u" => {
+ font.underline = !matches!(attr(e, b"val").as_deref(), Some("none"))
+ }
+ b"sz" => font.size = attr_parse(e, b"val"),
+ b"name" => font.name = attr(e, b"val"),
+ _ => {}
+ }
+ }
+ _ => {}
+ }
+ buf.clear();
+ }
+ Ok(out)
+ }
+
+ /// The number-format code for a cell's `s=` index.
+ ///
+ /// Absent `s=`, an out-of-range index, and an unmapped `numFmtId` all
+ /// resolve to `General` — the same answer Excel gives, and the reason most
+ /// cells in most workbooks need no lookup at all.
+ ///
+ /// `applyNumberFormat="0"` is deliberately ignored. In the spec it means
+ /// "take the format from the linked `<cellStyleXfs>` entry instead", but
+ /// every producer in the corpus writes the effective `numFmtId` on the
+ /// `<cellXfs>` entry regardless, and honouring the flag would replace a
+ /// correct answer with an inherited one.
+ pub fn format_code(&self, style_index: Option<u32>) -> &str {
+ let Some(xf) = self.cell_xf(style_index) else {
+ return GENERAL;
+ };
+ self.format_code_for_id(xf.num_fmt_id)
+ }
+
+ /// The code registered for a `numFmtId`, custom entries winning over
+ /// builtins.
+ pub fn format_code_for_id(&self, id: u32) -> &str {
+ if let Some(code) = self.custom_formats.get(&id) {
+ return code;
+ }
+ builtin_format(id).unwrap_or(GENERAL)
+ }
+
+ pub fn cell_xf(&self, style_index: Option<u32>) -> Option<&CellXf> {
+ self.cell_xfs.get(style_index.unwrap_or(0) as usize)
+ }
+
+ /// The font for a cell's `s=` index, or the default font when anything in
+ /// the chain is missing.
+ pub fn font(&self, style_index: Option<u32>) -> Font {
+ self.cell_xf(style_index)
+ .and_then(|xf| self.fonts.get(xf.font_id as usize))
+ .cloned()
+ .unwrap_or_default()
+ }
+
+ pub fn alignment(&self, style_index: Option<u32>) -> Alignment {
+ self.cell_xf(style_index)
+ .map(|xf| xf.alignment.clone())
+ .unwrap_or_default()
+ }
+
+ /// Every distinct format code the workbook can reach, for censuses.
+ pub fn custom_formats(&self) -> &HashMap<u32, String> {
+ &self.custom_formats
+ }
+
+ pub fn cell_xf_count(&self) -> usize {
+ self.cell_xfs.len()
+ }
+
+ pub fn font_count(&self) -> usize {
+ self.fonts.len()
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ const STYLES: &str = r#"<?xml version="1.0"?>
+<styleSheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">
+ <numFmts count="2">
+ <numFmt numFmtId="164" formatCode="&quot;$&quot;#,##0.00"/>
+ <numFmt numFmtId="165" formatCode="General"/>
+ </numFmts>
+ <fonts count="3">
+ <font><sz val="11"/><name val="Calibri"/></font>
+ <font><b/><sz val="14"/><name val="Arial"/></font>
+ <font><b val="0"/><i/></font>
+ </fonts>
+ <cellStyleXfs count="1">
+ <xf numFmtId="9" fontId="1"/>
+ </cellStyleXfs>
+ <cellXfs count="4">
+ <xf numFmtId="0" fontId="0"/>
+ <xf numFmtId="164" fontId="1" applyNumberFormat="1"/>
+ <xf numFmtId="3" fontId="2" quotePrefix="1"/>
+ <xf numFmtId="0" fontId="0"><alignment horizontal="center" wrapText="1" indent="2"/></xf>
+ </cellXfs>
+ <dxfs count="1"><dxf><font><b/></font></dxf></dxfs>
+</styleSheet>"#;
+
+ fn styles() -> Styles {
+ Styles::parse(STYLES.as_bytes()).unwrap()
+ }
+
+ /// The headline trap. `<cellStyleXfs>` holds an `<xf numFmtId="9">` (a
+ /// percent format) directly above `<cellXfs>`. If it leaked in, every
+ /// `s=` index would be shifted by one and cell styles would silently
+ /// resolve to their neighbours'.
+ #[test]
+ fn cell_style_xfs_do_not_leak_into_cell_xfs() {
+ let s = styles();
+ assert_eq!(s.cell_xf_count(), 4);
+ assert_eq!(s.format_code(Some(0)), "General");
+ assert_eq!(s.format_code(Some(1)), "\"$\"#,##0.00");
+ assert_eq!(s.format_code(Some(2)), "#,##0");
+ // The percent code from cellStyleXfs must appear nowhere.
+ assert!((0..4).all(|i| s.format_code(Some(i)) != "0%"));
+ }
+
+ /// `<dxfs>` holds `<font>` elements too; counting them shifts every
+ /// `fontId` above the insertion point.
+ #[test]
+ fn dxf_fonts_do_not_shift_the_font_ids() {
+ let s = styles();
+ assert_eq!(s.font_count(), 3);
+ assert_eq!(s.font(Some(1)).name.as_deref(), Some("Arial"));
+ assert!(s.font(Some(1)).bold);
+ }
+
+ #[test]
+ fn absent_and_out_of_range_style_indices_are_general() {
+ let s = styles();
+ assert_eq!(s.format_code(None), GENERAL);
+ assert_eq!(s.format_code(Some(999)), GENERAL);
+ assert_eq!(s.font(Some(999)), Font::default());
+ }
+
+ /// A custom id may carry the code `General` — a reader that assumed
+ /// "id >= 164 means non-General" would format these cells wrongly.
+ #[test]
+ fn a_custom_format_may_be_general() {
+ assert_eq!(styles().format_code_for_id(165), "General");
+ }
+
+ #[test]
+ fn format_code_attributes_are_unescaped() {
+ // `"$"#,##0.00` arrives as `&quot;$&quot;#,##0.00`; leaving the
+ // entities in would hand the formatter a code it cannot parse.
+ assert!(styles().format_code_for_id(164).starts_with('"'));
+ }
+
+ #[test]
+ fn font_boolean_off_switch_is_honoured() {
+ let f = styles().font(Some(2));
+ assert!(!f.bold, "b val=0 must turn bold off");
+ assert!(f.italic);
+ }
+
+ #[test]
+ fn alignment_is_read_from_the_xf_child() {
+ let a = styles().alignment(Some(3));
+ assert_eq!(a.horizontal, HorizontalAlign::Center);
+ assert!(a.wrap_text);
+ assert_eq!(a.indent, 2);
+ // An xf with no <alignment> child gets the default, not the previous
+ // xf's — the classic streaming-parser carry-over bug.
+ assert_eq!(styles().alignment(Some(0)), Alignment::default());
+ }
+
+ #[test]
+ fn quote_prefix_is_captured() {
+ assert!(styles().cell_xf(Some(2)).unwrap().quote_prefix);
+ assert!(!styles().cell_xf(Some(0)).unwrap().quote_prefix);
+ }
+
+ #[test]
+ fn a_workbook_with_no_styles_part_still_resolves() {
+ let s = Styles::default();
+ assert_eq!(s.format_code(Some(7)), GENERAL);
+ assert_eq!(s.font(Some(7)), Font::default());
+ }
+
+ #[test]
+ fn builtin_table_omits_reserved_ids() {
+ assert_eq!(builtin_format(14), Some("mm-dd-yy"));
+ assert_eq!(builtin_format(49), Some("@"));
+ // Reserved / locale-dependent: no code may be invented for these.
+ assert_eq!(builtin_format(23), None);
+ assert_eq!(builtin_format(42), None);
+ }
+}
diff --git a/crates/liteparse-ooxml/src/xlsx/text.rs b/crates/liteparse-ooxml/src/xlsx/text.rs
new file mode 100644
index 0000000..c7d46d6
--- /dev/null
+++ b/crates/liteparse-ooxml/src/xlsx/text.rs
@@ -0,0 +1,440 @@
+//! Rich text: the `<si>` / `<is>` grammar (§18.4.8, §18.4.12) shared by the
+//! shared-string table and by inline strings written straight into a sheet.
+//!
+//! Two things here are not obvious from the schema and both were measured on
+//! the corpus rather than assumed:
+//!
+//! * **`<rPh>` must be stripped.** An `<si>` may carry phonetic runs —
+//! *furigana*, the ruby Excel draws above a Japanese cell (§18.4.6). Their
+//! `<t>` elements sit at the same depth as the real ones, so a reader that
+//! concatenates every `<t>` emits `一般競争入札イッパンキョウソウニュウサツ`:
+//! the content immediately followed by its own pronunciation. This exact bug
+//! cost the XLSX baseline oracle 0.021 macro recall across a cohort of
+//! Japanese workbooks before it was found. 44.2% of real workbooks have rich
+//! text, so this path is not an edge case.
+//!
+//! * **Runs are kept, not flattened.** `calamine` concatenates `<r><t>` and
+//! discards every `<rPr>`; that is the single largest recall penalty the
+//! LibreOffice baseline measured (−0.067 on workbooks with rich text) and
+//! throwing the emphasis away here would give it up before the emitter ever
+//! sees it.
+
+use quick_xml::Reader;
+use quick_xml::events::{BytesStart, Event};
+use std::io::BufRead;
+
+use crate::docx::error::Result;
+use crate::xlsx::xml::{attr, decode_cdata, decode_general_ref, decode_text, local_name};
+
+/// Character formatting on one run (§18.8.7 `CT_RPrElt`).
+///
+/// Colour is deliberately absent: an `<rPr>` colour may be `rgb`, `indexed`
+/// (the legacy palette), `theme` + `tint`, or `auto`, and resolving those needs
+/// the workbook theme and the styles palette. Nothing downstream reads a run
+/// colour yet, so the honest move is to not half-resolve it here.
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct RunProps {
+ pub bold: bool,
+ pub italic: bool,
+ pub strike: bool,
+ pub underline: bool,
+ /// `<sz val="11"/>` in points, when stated.
+ pub size: Option<f32>,
+ /// `<rFont val="Calibri"/>`, when stated.
+ pub font: Option<String>,
+ pub vert_align: Option<VertAlign>,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum VertAlign {
+ Superscript,
+ Subscript,
+}
+
+/// One formatting run within a cell's text.
+#[derive(Clone, Debug, PartialEq)]
+pub struct TextRun {
+ pub text: String,
+ pub props: RunProps,
+}
+
+/// A cell's text as the file states it: an ordered list of runs.
+///
+/// A plain string is one run with default props, which keeps the common case
+/// from needing a separate variant.
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct RichText {
+ pub runs: Vec<TextRun>,
+}
+
+impl RichText {
+ /// The whole string with formatting dropped.
+ pub fn plain(&self) -> String {
+ match self.runs.as_slice() {
+ [] => String::new(),
+ [only] => only.text.clone(),
+ runs => runs.iter().map(|r| r.text.as_str()).collect(),
+ }
+ }
+
+ pub fn is_empty(&self) -> bool {
+ self.runs.iter().all(|r| r.text.is_empty())
+ }
+
+ /// True when the text carries more than one distinct formatting run — the
+ /// case an emitter has to render with inline emphasis rather than as a
+ /// plain string.
+ pub fn is_rich(&self) -> bool {
+ self.runs.len() > 1
+ || self
+ .runs
+ .first()
+ .is_some_and(|r| r.props != RunProps::default())
+ }
+}
+
+/// Parse `xl/sharedStrings.xml` (§18.4.9) into the table cells index into.
+///
+/// Order is the whole contract: `<c t="s"><v>7</v></c>` means the eighth
+/// `<si>`, so an `<si>` that fails to yield text must still occupy its slot.
+/// Every `<si>` therefore pushes, empty or not.
+pub fn parse_shared_strings(data: &[u8]) -> Result<Vec<RichText>> {
+ let mut reader = Reader::from_reader(data);
+ let mut buf = Vec::new();
+ let mut nested = Vec::new();
+ let mut out = Vec::new();
+ loop {
+ match reader
+ .read_event_into(&mut buf)
+ .map_err(quick_xml::DeError::from)?
+ {
+ Event::Eof => break,
+ Event::Start(ref e) if local_name(e.name().as_ref()) == b"si" => {
+ out.push(read_rich_text(&mut reader, &mut nested, b"si")?);
+ }
+ // `<si/>` is a legal empty string and still holds an index.
+ Event::Empty(ref e) if local_name(e.name().as_ref()) == b"si" => {
+ out.push(RichText::default());
+ }
+ _ => {}
+ }
+ buf.clear();
+ }
+ Ok(out)
+}
+
+/// Read the body of an `<si>` or `<is>` element, with the reader positioned
+/// just after its start tag. Stops on the matching end tag named `end`.
+pub(crate) fn read_rich_text<R: BufRead>(
+ reader: &mut Reader<R>,
+ buf: &mut Vec<u8>,
+ end: &[u8],
+) -> Result<RichText> {
+ let mut out = RichText::default();
+ // Text found directly under <si>, outside any <r>. The overwhelmingly
+ // common shape, and it never carries props.
+ let mut bare = String::new();
+ let mut run_text = String::new();
+ let mut props = RunProps::default();
+ let mut in_run = false;
+ // Phonetic runs are skipped wholesale; see the module docs.
+ let mut in_phonetic = false;
+ let mut in_text = false;
+
+ loop {
+ let event = reader
+ .read_event_into(buf)
+ .map_err(quick_xml::DeError::from)?;
+ match event {
+ Event::Eof => break,
+ Event::Start(ref e) => match local_name(e.name().as_ref()) {
+ b"rPh" => in_phonetic = true,
+ b"r" if !in_phonetic => {
+ in_run = true;
+ props = RunProps::default();
+ run_text.clear();
+ }
+ b"t" => in_text = true,
+ name if in_run && !in_phonetic => apply_run_prop(&mut props, name, e),
+ _ => {}
+ },
+ Event::Empty(ref e) => {
+ if in_run && !in_phonetic {
+ apply_run_prop(&mut props, local_name(e.name().as_ref()), e);
+ }
+ }
+ // CData is legal in a `<t>` and rare, but a producer that uses it
+ // would otherwise lose the whole cell.
+ // `GeneralRef` is not optional to handle: the raw reader emits
+ // every entity as its own event, so omitting it drops each `&`,
+ // `<`, `>` and numeric charref from the text. See
+ // `xml::decode_general_ref`.
+ Event::Text(_) | Event::CData(_) | Event::GeneralRef(_) if in_text && !in_phonetic => {
+ let text = match event {
+ // CData is *not* entity-escaped; unescaping it would turn a
+ // literal `&amp;` inside a CDATA block into `&`.
+ Event::CData(ref c) => decode_cdata(c)?,
+ Event::Text(ref t) => decode_text(t)?,
+ Event::GeneralRef(ref r) => decode_general_ref(r)?,
+ _ => unreachable!("guarded by the pattern above"),
+ };
+ if in_run {
+ run_text.push_str(&text);
+ } else {
+ bare.push_str(&text);
+ }
+ }
+ Event::End(ref e) => match local_name(e.name().as_ref()) {
+ b"rPh" => in_phonetic = false,
+ b"t" => in_text = false,
+ b"r" if in_run => {
+ in_run = false;
+ // An empty run carries no text and no position; dropping it
+ // keeps `is_rich` from firing on formatting-only noise that
+ // some producers emit around edits.
+ if !run_text.is_empty() {
+ out.runs.push(TextRun {
+ text: std::mem::take(&mut run_text),
+ props: props.clone(),
+ });
+ }
+ }
+ name if name == end => break,
+ _ => {}
+ },
+ _ => {}
+ }
+ buf.clear();
+ }
+
+ if !bare.is_empty() {
+ // Bare text and runs are mutually exclusive in the schema, but a
+ // malformed file can carry both; putting the bare text first preserves
+ // document order for the only ordering that could have produced it.
+ out.runs.insert(
+ 0,
+ TextRun {
+ text: bare,
+ props: RunProps::default(),
+ },
+ );
+ }
+ Ok(out)
+}
+
+fn apply_run_prop(props: &mut RunProps, name: &[u8], e: &BytesStart<'_>) {
+ // §18.8: these are CT_BooleanProperty, so `val="0"` turns the property
+ // *off*. An absent val means true. Treating the element's presence as
+ // "true" would render struck-through text that Excel shows normally.
+ let on = || match attr(e, b"val") {
+ Some(v) => !matches!(v.as_str(), "0" | "false"),
+ None => true,
+ };
+ match name {
+ b"b" => props.bold = on(),
+ b"i" => props.italic = on(),
+ b"strike" => props.strike = on(),
+ // `<u/>` is CT_UnderlineProperty, not a boolean: its val is a style
+ // name (`single`, `double`, `singleAccounting`), and `none` is the
+ // off switch.
+ b"u" => props.underline = !matches!(attr(e, b"val").as_deref(), Some("none")),
+ b"sz" => props.size = attr(e, b"val").and_then(|v| v.parse().ok()),
+ b"rFont" => props.font = attr(e, b"val"),
+ b"vertAlign" => {
+ props.vert_align = match attr(e, b"val").as_deref() {
+ Some("superscript") => Some(VertAlign::Superscript),
+ Some("subscript") => Some(VertAlign::Subscript),
+ _ => None,
+ }
+ }
+ _ => {}
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use crate::xlsx::xml::decode_control_escapes;
+
+ fn read(xml: &str, end: &[u8]) -> RichText {
+ let mut reader = Reader::from_reader(xml.as_bytes());
+ let mut buf = Vec::new();
+ // Advance past the opening tag so the reader is where the real caller
+ // leaves it.
+ loop {
+ match reader.read_event_into(&mut buf).unwrap() {
+ Event::Start(ref e) if local_name(e.name().as_ref()) == end => break,
+ Event::Eof => panic!("no opening tag"),
+ _ => {}
+ }
+ }
+ buf.clear();
+ read_rich_text(&mut reader, &mut buf, end).unwrap()
+ }
+
+ #[test]
+ fn plain_shared_string_is_one_run() {
+ let t = read("<si><t>Total assets</t></si>", b"si");
+ assert_eq!(t.plain(), "Total assets");
+ assert_eq!(t.runs.len(), 1);
+ assert!(!t.is_rich());
+ }
+
+ #[test]
+ fn runs_keep_their_formatting() {
+ let t = read(
+ r#"<si><r><rPr><b/></rPr><t>Q3</t></r><r><t> actual</t></r></si>"#,
+ b"si",
+ );
+ assert_eq!(t.plain(), "Q3 actual");
+ assert_eq!(t.runs.len(), 2);
+ assert!(t.runs[0].props.bold);
+ assert!(!t.runs[1].props.bold);
+ assert!(t.is_rich());
+ }
+
+ /// The furigana bug, as a test. Without the `<rPh>` guard this reads
+ /// "東京トウキョウ" — the word followed by its own pronunciation.
+ #[test]
+ fn phonetic_runs_are_stripped() {
+ let t = read(
+ r#"<si><t>東京</t><rPh sb="0" eb="2"><t>トウキョウ</t></rPh><phoneticPr fontId="1"/></si>"#,
+ b"si",
+ );
+ assert_eq!(t.plain(), "東京");
+ }
+
+ /// `<rPh>` also appears interleaved with real `<r>` runs, where a
+ /// depth-blind reader would attach the reading to the wrong run.
+ #[test]
+ fn phonetic_runs_between_real_runs_are_stripped() {
+ let t = read(
+ r#"<si><r><t>東京</t></r><rPh sb="0" eb="2"><t>トウキョウ</t></rPh><r><t>都</t></r></si>"#,
+ b"si",
+ );
+ assert_eq!(t.plain(), "東京都");
+ assert_eq!(t.runs.len(), 2);
+ }
+
+ #[test]
+ fn val_zero_turns_a_boolean_property_off() {
+ // Excel writes `<b val="0"/>` when a style turned bold on and the run
+ // turns it back off. Treating presence as true renders it bold.
+ let t = read(
+ r#"<si><r><rPr><b val="0"/><i/></rPr><t>x</t></r></si>"#,
+ b"si",
+ );
+ assert!(!t.runs[0].props.bold);
+ assert!(t.runs[0].props.italic);
+ }
+
+ #[test]
+ fn underline_none_is_off_but_double_is_on() {
+ let t = read(
+ r#"<si><r><rPr><u val="none"/></rPr><t>a</t></r><r><rPr><u val="double"/></rPr><t>b</t></r><r><rPr><u/></rPr><t>c</t></r></si>"#,
+ b"si",
+ );
+ assert!(!t.runs[0].props.underline);
+ assert!(t.runs[1].props.underline);
+ assert!(t.runs[2].props.underline);
+ }
+
+ #[test]
+ fn size_and_font_are_captured() {
+ let t = read(
+ r#"<si><r><rPr><sz val="14.5"/><rFont val="Calibri"/></rPr><t>x</t></r></si>"#,
+ b"si",
+ );
+ assert_eq!(t.runs[0].props.size, Some(14.5));
+ assert_eq!(t.runs[0].props.font.as_deref(), Some("Calibri"));
+ }
+
+ #[test]
+ fn inline_string_uses_the_same_grammar() {
+ let t = read(r#"<is><r><rPr><i/></rPr><t>note</t></r></is>"#, b"is");
+ assert_eq!(t.plain(), "note");
+ assert!(t.runs[0].props.italic);
+ }
+
+ #[test]
+ fn control_escapes_decode_to_the_character() {
+ let t = read("<si><t>line one_x000D__x000A_line two</t></si>", b"si");
+ assert_eq!(t.plain(), "line one\r\nline two");
+ }
+
+ #[test]
+ fn printable_escapes_are_left_literal() {
+ // `_x0041_` officially means "A", but Excel never writes it and real
+ // strings do contain runs like this. Decoding would corrupt them.
+ assert_eq!(decode_control_escapes("id_x0041_1"), "id_x0041_1");
+ }
+
+ #[test]
+ fn escaped_underscore_round_trips_a_literal_escape() {
+ assert_eq!(decode_control_escapes("_x005F_x000D_"), "_x000D_");
+ }
+
+ #[test]
+ fn text_with_no_escape_marker_is_passed_through() {
+ assert_eq!(decode_control_escapes("plain text"), "plain text");
+ assert_eq!(decode_control_escapes("a_b_c"), "a_b_c");
+ }
+
+ #[test]
+ fn multibyte_text_around_an_escape_is_not_split() {
+ // The decoder walks bytes; slicing on a non-boundary would panic.
+ assert_eq!(decode_control_escapes("東京_x000D_都"), "東京\r都");
+ }
+
+ #[test]
+ fn xml_entities_are_unescaped() {
+ let t = read("<si><t>R&amp;D &lt;2026&gt; &#3585;</t></si>", b"si");
+ assert_eq!(t.plain(), "R&D <2026> ก");
+ }
+
+ #[test]
+ fn empty_si_yields_empty_text() {
+ let t = read("<si><t/></si>", b"si");
+ assert!(t.is_empty());
+ assert_eq!(t.plain(), "");
+ }
+
+ /// The shared-string table is addressed by position, so an `<si>` that
+ /// carries nothing must still take its slot. Dropping it shifts every
+ /// string after it — the worst possible failure mode, because the output
+ /// stays plausible.
+ #[test]
+ fn empty_entries_keep_their_index() {
+ let sst = r#"<sst count="4" uniqueCount="4">
+ <si><t>alpha</t></si>
+ <si/>
+ <si><t/></si>
+ <si><t>delta</t></si>
+ </sst>"#;
+ let table = parse_shared_strings(sst.as_bytes()).unwrap();
+ assert_eq!(table.len(), 4);
+ assert_eq!(table[0].plain(), "alpha");
+ assert_eq!(table[3].plain(), "delta");
+ }
+
+ #[test]
+ fn shared_string_table_reads_runs_and_strips_phonetics() {
+ let sst = r#"<sst>
+ <si><r><rPr><b/></rPr><t>Q3</t></r><r><t> total</t></r></si>
+ <si><t>東京</t><rPh sb="0" eb="2"><t>トウキョウ</t></rPh></si>
+ </sst>"#;
+ let table = parse_shared_strings(sst.as_bytes()).unwrap();
+ assert_eq!(table[0].plain(), "Q3 total");
+ assert!(table[0].runs[0].props.bold);
+ assert_eq!(table[1].plain(), "東京");
+ }
+
+ #[test]
+ fn an_absent_table_is_an_empty_table() {
+ assert!(
+ parse_shared_strings(b"<sst count=\"0\"/>")
+ .unwrap()
+ .is_empty()
+ );
+ }
+}
diff --git a/crates/liteparse-ooxml/src/xlsx/xml.rs b/crates/liteparse-ooxml/src/xlsx/xml.rs
new file mode 100644
index 0000000..2ca80ed
--- /dev/null
+++ b/crates/liteparse-ooxml/src/xlsx/xml.rs
@@ -0,0 +1,235 @@
+//! Small helpers shared by the hand-rolled SpreadsheetML readers.
+//!
+//! Every part of the XLSX reader parses with `quick_xml::Reader` events rather
+//! than the serde layer the DOCX vendor uses, for two reasons that are specific
+//! to this format:
+//!
+//! * **Whitespace.** `PackageContents::from_bytes` runs
+//! [`substitute_whitespace_only_runs`](crate::docx::whitespace_workaround),
+//! which protects whitespace-only text from quick-xml's serde trimmer — but
+//! it is namespace-gated to WordprocessingML, so it deliberately no-ops on
+//! SpreadsheetML. A serde schema here would silently drop a cell whose whole
+//! value is `" "`. The event reader does not trim, so it never has the
+//! problem.
+//!
+//! * **Size.** Sheets are the bulk of a workbook — 50.3M cells across the
+//! 1,089-workbook finance corpus, with single sheets past 32 MB. serde
+//! materializes an intermediate `Vec` per element; streaming does not.
+
+use quick_xml::events::{BytesCData, BytesRef, BytesStart, BytesText};
+
+use crate::docx::error::Result;
+
+/// Strip a namespace prefix from a qualified name (`x:sheetData` →
+/// `sheetData`).
+///
+/// SpreadsheetML is usually written with the default namespace and no prefix,
+/// but Excel Online, WPS and XlsIO all appear in the corpus and prefixed
+/// output is legal, so no reader here may match on the qualified name.
+pub(crate) fn local_name(qname: &[u8]) -> &[u8] {
+ match qname.iter().position(|&b| b == b':') {
+ Some(i) => &qname[i + 1..],
+ None => qname,
+ }
+}
+
+/// Read an attribute by its **qualified** name, unescaped.
+///
+/// Qualified rather than local because `<sheet name="…" r:id="rId1"/>` is
+/// exactly the collision `pptx::package` documents: quick-xml's serde layer
+/// drops attribute prefixes, so `r:id` and a hypothetical `id` would be
+/// indistinguishable. Matching the written name keeps them apart.
+///
+/// A malformed attribute is skipped rather than fatal, matching the fail-open
+/// posture of `docx/parse/primitives/lenient.rs`.
+pub(crate) fn attr(e: &BytesStart<'_>, want: &[u8]) -> Option<String> {
+ e.attributes().flatten().find_map(|a| {
+ (a.key.as_ref() == want).then(|| match a.unescape_value() {
+ Ok(v) => v.into_owned(),
+ // An attribute with a broken entity keeps its raw form rather than
+ // vanishing; for `r=`/`ref=` the raw form still parses.
+ Err(_) => String::from_utf8_lossy(&a.value).into_owned(),
+ })
+ })
+}
+
+/// Read an attribute and parse it, treating both "absent" and "unparseable"
+/// as `None`.
+///
+/// Deliberately lossy: a `<row r="abc">` is corruption, and the reader's job
+/// is to keep reading the other 40,000 rows.
+pub(crate) fn attr_parse<T: std::str::FromStr>(e: &BytesStart<'_>, want: &[u8]) -> Option<T> {
+ attr(e, want)?.trim().parse().ok()
+}
+
+/// Read a boolean attribute with OOXML's four spellings (§22.9.2.7:
+/// `1`/`0`/`true`/`false`).
+pub(crate) fn attr_bool(e: &BytesStart<'_>, want: &[u8], default: bool) -> bool {
+ match attr(e, want).as_deref() {
+ Some("1" | "true" | "on") => true,
+ Some("0" | "false" | "off") => false,
+ _ => default,
+ }
+}
+
+/// quick-xml's leaf errors do not implement `Into<ParseError>` directly; they
+/// go through `quick_xml::Error` and then the crate's existing `DeError` arm.
+pub(crate) fn xml_err(e: impl Into<quick_xml::Error>) -> quick_xml::DeError {
+ quick_xml::DeError::from(e.into())
+}
+
+/// Decode a text event: encoding, then XML entities, then SpreadsheetML's own
+/// `_xHHHH_` escapes.
+pub(crate) fn decode_text(t: &BytesText<'_>) -> Result<String> {
+ let raw = t.xml10_content().map_err(xml_err)?;
+ let unescaped = match quick_xml::escape::unescape(&raw) {
+ Ok(unescaped) => unescaped,
+ // A malformed entity costs one cell's fidelity, not the workbook.
+ Err(e) => {
+ log::warn!("undecodable entity in SpreadsheetML text: {e}");
+ std::borrow::Cow::Borrowed(raw.as_ref())
+ }
+ };
+ Ok(decode_control_escapes(&unescaped))
+}
+
+/// Decode a CDATA section. **Not** entity-unescaped: a literal `&amp;` inside
+/// CDATA is five characters, not one.
+pub(crate) fn decode_cdata(c: &BytesCData<'_>) -> Result<String> {
+ Ok(decode_control_escapes(&c.decode().map_err(xml_err)?))
+}
+
+/// Resolve an entity reference to the text it stands for.
+///
+/// quick-xml's **raw event reader does not fold entities into `Text`** — it
+/// emits `&amp;` as a separate [`Event::GeneralRef`](quick_xml::events::Event)
+/// carrying the bare name, splitting the surrounding text in two. Any reader
+/// that matches only on `Text` therefore *drops* every `&`, `<`, `>` and every
+/// numeric character reference silently, and `R&amp;D &#3585;` arrives as
+/// `RD `. (The serde layer the DOCX vendor uses resolves them itself, which is
+/// why this only bites the hand-rolled readers here.)
+///
+/// SpreadsheetML declares no DTD, so only the five predefined entities and
+/// numeric refs are legal. An unknown name is kept in its written form rather
+/// than dropped — visible, and recoverable by a human, which silence is not.
+pub(crate) fn decode_general_ref(r: &BytesRef<'_>) -> Result<String> {
+ let name = r.decode().map_err(xml_err)?;
+ let written = format!("&{name};");
+ match quick_xml::escape::unescape(&written) {
+ Ok(resolved) => Ok(resolved.into_owned()),
+ Err(e) => {
+ log::warn!("unresolvable entity {written}: {e}");
+ Ok(written)
+ }
+ }
+}
+
+/// Decode `_xHHHH_` escapes for characters XML 1.0 cannot carry literally.
+///
+/// Excel writes an in-cell newline as `_x000D_` / `_x000A_`, because those
+/// bytes would be normalized away by any conformant XML parser. Left undecoded
+/// they surface as literal `_x000D_` in the middle of extracted text — visible
+/// garbage in every downstream consumer.
+///
+/// **Only control characters are decoded**, which is narrower than the spec.
+/// The escape is legal for any codepoint, so `_x0041_` officially means `A` —
+/// but Excel never writes that form, whereas real strings containing an
+/// underscore-and-hex run do exist (identifiers, file stems). Decoding those
+/// would corrupt data to satisfy a form nothing produces. The escape-the-escape
+/// sequence `_x005F_` is honoured so a literal `_x000D_` in the source round
+/// trips.
+pub(crate) fn decode_control_escapes(s: &str) -> String {
+ if !s.contains("_x") {
+ return s.to_string();
+ }
+ let bytes = s.as_bytes();
+ let mut out = String::with_capacity(s.len());
+ let mut i = 0;
+ while i < bytes.len() {
+ match escape_at(bytes, i) {
+ // `_x005F_` escapes the underscore of a following escape.
+ Some(0x5F) => {
+ out.push('_');
+ i += 7;
+ }
+ Some(c) if c < 0x20 || c == 0x7F => {
+ out.push(c as u8 as char);
+ i += 7;
+ }
+ _ => {
+ let ch = s[i..].chars().next().expect("index is a char boundary");
+ out.push(ch);
+ i += ch.len_utf8();
+ }
+ }
+ }
+ out
+}
+
+/// The codepoint of an `_xHHHH_` escape starting at `i`, if one is there.
+fn escape_at(bytes: &[u8], i: usize) -> Option<u32> {
+ let slice = bytes.get(i..i + 7)?;
+ if slice[0] != b'_' || slice[1] != b'x' || slice[6] != b'_' {
+ return None;
+ }
+ let hex = std::str::from_utf8(&slice[2..6]).ok()?;
+ u32::from_str_radix(hex, 16).ok()
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use quick_xml::Reader;
+ use quick_xml::events::Event;
+
+ fn start(xml: &str) -> BytesStart<'static> {
+ let mut reader = Reader::from_reader(xml.as_bytes());
+ let mut buf = Vec::new();
+ loop {
+ match reader.read_event_into(&mut buf).unwrap() {
+ Event::Start(e) | Event::Empty(e) => return e.into_owned(),
+ Event::Eof => panic!("no element"),
+ _ => {}
+ }
+ }
+ }
+
+ #[test]
+ fn local_name_strips_a_prefix_when_present() {
+ assert_eq!(local_name(b"sheetData"), b"sheetData");
+ assert_eq!(local_name(b"x:sheetData"), b"sheetData");
+ }
+
+ #[test]
+ fn qualified_attributes_stay_distinct() {
+ let e = start(r#"<sheet name="Q3" sheetId="1" r:id="rId7"/>"#);
+ assert_eq!(attr(&e, b"r:id").as_deref(), Some("rId7"));
+ assert_eq!(attr(&e, b"sheetId").as_deref(), Some("1"));
+ // `id` alone must not resolve to the relationship id.
+ assert_eq!(attr(&e, b"id"), None);
+ }
+
+ #[test]
+ fn attribute_values_are_unescaped() {
+ let e = start(r#"<sheet name="R&amp;D &lt;2026&gt;"/>"#);
+ assert_eq!(attr(&e, b"name").as_deref(), Some("R&D <2026>"));
+ }
+
+ #[test]
+ fn unparseable_numbers_are_none_not_zero() {
+ // Zero would be a valid row/column index; silently coercing corruption
+ // into cell A1 is the failure mode this guards.
+ let e = start(r#"<row r="abc"/>"#);
+ assert_eq!(attr_parse::<u32>(&e, b"r"), None);
+ assert_eq!(attr_parse::<u32>(&e, b"missing"), None);
+ }
+
+ #[test]
+ fn booleans_accept_both_spellings_and_fall_back_to_the_default() {
+ let e = start(r#"<col hidden="1" customWidth="false" bestFit="true"/>"#);
+ assert!(attr_bool(&e, b"hidden", false));
+ assert!(!attr_bool(&e, b"customWidth", true));
+ assert!(attr_bool(&e, b"bestFit", false));
+ assert!(attr_bool(&e, b"absent", true));
+ }
+}