From e7914038f339325f9e51807b6f2cc7fae4585eff Mon Sep 17 00:00:00 2001 From: kiwi4boy Date: Sat, 14 Nov 2026 09:55:35 -0500 Subject: [PATCH 1/6] craft-xlsx: read the defined names of a binary workbook Each BrtName becomes a DefinedName as Excel writes it in .xlsx: built-in names as _xlnm.Print_Area, sheet scope as localSheetId, the formula decoded with relative references as offsets from A1, the comment, hidden, and a macro's function, vbProcedure or xlm, functionGroupId, shortcutKey, publishToServer and workbookParameter. The hidden names for newer functions and LET parameters are left out, as .xlsx does. Cell formulas using a name that was read now decode instead of keeping their saved results, PtgNameX through the workbook's own link is 'Other Sheet'!Local, and a deleted 3-D reference is Sheet2!#REF!, as in .xlsx. A name whose formula can't be read is left out with a warning, and formulas using it keep their saved results. Closes #1250. --- crates/xlsx/README.md | 9 +- crates/xlsx/src/xlsb.rs | 153 +++++++++++++++++++++++++++++--- crates/xlsx/src/xlsb/expr.rs | 3 + crates/xlsx/src/xlsb/formula.rs | 105 ++++++++++++++++------ crates/xlsx/tests/xlsb.rs | 135 +++++++++++++++++++++++++++- 5 files changed, 360 insertions(+), 45 deletions(-) diff --git a/crates/xlsx/README.md b/crates/xlsx/README.md index 1dc30574d..4e90ca830 100644 --- a/crates/xlsx/README.md +++ b/crates/xlsx/README.md @@ -84,12 +84,17 @@ The parts this crate writes use the transitional namespaces; a strict file's kep they were. A binary workbook is not written. A binary workbook gives the same `Workbook`, strings, rows and merged cells. Its styles are not -read (each cell keeps its format index). Its cell formulas are decoded from their tokens into the +read (each cell keeps its format index). Its defined names are those of `definedNames` in the +`.xlsx` Excel writes: built-in names as `_xlnm.Print_Area`, sheet-scoped names with their +`localSheetId`, relative references as the cell they reach from A1, macro names with their +`function`, `xlm`, `functionGroupId` and `shortcutKey`. Excel's hidden names for newer functions +and LET parameters are left out, as in `.xlsx`; so is a name whose formula can't be read, with a +warning. Its cell formulas are decoded from their tokens into the text an `.xlsx` file holds (`_xlfn.` and `_xlpm.` names as written, no implicit `@`), with `FormulaKind::Shared` or `FormulaKind::Array` and their ranges, and `BrtCellMeta` as the cell metadata index. Every cell of a shared formula gets its own text, decoded at the cell, since the file keeps the tokens once. A formula whose decoding needs something the reader does not read -keeps only its saved result, with a warning saying why: user defined names, table references, +keeps only its saved result, with a warning saying why: a defined name left out, table references, other workbooks, Python code stored outside the cell, data tables. The XLSB function table (`xlsb/ftab.rs`) and the expression printer are this crate's own, apart from `craft-xls`'s. diff --git a/crates/xlsx/src/xlsb.rs b/crates/xlsx/src/xlsb.rs index 2fdde59be..1941ea61e 100644 --- a/crates/xlsx/src/xlsb.rs +++ b/crates/xlsx/src/xlsb.rs @@ -1,5 +1,5 @@ -//! Binary workbooks ([MS-XLSB]): the workbook part, shared strings and worksheet cells, from -//! their records. Cell formulas are decoded from their tokens ([`formula`]) into the text an +//! Binary workbooks ([MS-XLSB]): the workbook part with its defined names, shared strings and +//! worksheet cells, from their records. Cell formulas are decoded from their tokens ([`formula`]) into the text an //! `.xlsx` file holds; one that can't be keeps only its saved result, with a warning saying why. //! Styles are not read. A record that does not parse fails the read. @@ -15,7 +15,7 @@ use craft_sheet::{CellError, CellRef, MAX_COLS, MAX_ROWS, Range, Visibility}; use crate::sheet::{Cell, CellFormula, CellValue, FormulaKind, Row, SheetPart}; use crate::strings::StringItem; -use crate::workbook::{SheetEntry, SheetKind, Workbook}; +use crate::workbook::{DefinedName, SheetEntry, SheetKind, Workbook}; use crate::{Error, Limits, Warnings}; pub(crate) use formula::Links; use formula::{Book, Mode, Name, Xti}; @@ -266,6 +266,9 @@ pub(crate) fn workbook( records.first(131, warnings)?; let mut wb = Workbook::default(); let mut links = Some(Links::default()); + let mut pending = vec![]; + // Each BrtBundleSh's place in `wb.sheets`, `None` for a skipped one. + let mut bundle_sheets: Vec> = vec![]; let mut bundle = false; let mut bundle_seen = false; while let Some((id, payload)) = records.next(warnings)? { @@ -279,14 +282,15 @@ pub(crate) fn workbook( if wb.sheets.is_empty() { return Err(invalid("no supported worksheets")); } - if links.is_none() { - warnings.warn("XLSB: the workbook's sheet links or names could not be read; formulas keep their saved results"); + match links.as_mut() { + Some(l) => wb.defined_names = defined_names(pending, &bundle_sheets, l, limits, budget, warnings), + None => warnings.warn("XLSB: the workbook's sheet links or names could not be read; formulas keep their saved results"), } return Ok((wb, links)); } 39 | 355 | 357 | 358 | 362 | 667 => { if let Some(l) = links.as_mut() - && link_record(id, payload, l).is_err() + && link_record(id, payload, l, &mut pending).is_err() { links = None; } @@ -341,6 +345,7 @@ pub(crate) fn workbook( if let Some(l) = links.as_mut() { l.sheets.push(None); } + bundle_sheets.push(None); continue; }; let rel = rels.by_id(&rel_id).ok_or_else(|| invalid("worksheet relationship is missing"))?; @@ -355,6 +360,7 @@ pub(crate) fn workbook( if let Some(l) = links.as_mut() { l.sheets.push((kind == SheetKind::Worksheet).then(|| name.clone())); } + bundle_sheets.push(u32::try_from(wb.sheets.len()).ok()); wb.sheets.push(SheetEntry { name, sheet_id, visibility, rel_id, kind, part: Some(rel.target.clone()) }); } _ => {} @@ -363,9 +369,110 @@ pub(crate) fn workbook( Err(invalid("missing workbook end record")) } +/// A `BrtName`'s parts that only its [`DefinedName`] needs, until the workbook part is read. +struct PendingName { + /// Its place in [`Links`]'s names. + index: usize, + flags: u32, + /// `chKey`: a macro's shortcut key. + key: u8, + rgce: Vec, + rgcb: Vec, + comment: Option, + menu: Option, + description: Option, +} + +/// The workbook's defined names, as `.xlsx` has them in `definedNames`: every `BrtName` but the +/// hidden ones for newer functions and LET parameters, which Excel doesn't write there. `sheets` +/// maps a name's `itab` (its sheet's place in `BrtBundleSh` order) to [`Workbook::sheets`]. +/// A name whose formula can't be read, or that belongs to a sheet the reader skips, is left out +/// with a warning, and a cell formula using it keeps its saved result. +fn defined_names( + pending: Vec, + sheets: &[Option], + links: &mut Links, + limits: &Limits, + budget: &Budget, + warnings: &mut Warnings, +) -> Vec { + let mut out = vec![]; + for p in pending { + let Some(name) = links.names.get(p.index) else { continue }; + if name.future || formula::is_param(&name.text) { + continue; + } + let local_sheet_id = match name.scope { + None => None, + Some(itab) => match usize::try_from(itab).ok().and_then(|i| sheets.get(i)) { + Some(Some(i)) => Some(*i), + _ => { + warnings.warn("XLSB: some defined names were left out (names of sheets the reader skips)"); + continue; + } + }, + }; + let formula = match formula::decode(&p.rgce, &p.rgcb, links, Mode::Name) { + Ok(e) => expr::print(&e), + Err(formula::Unsupported(why)) => { + warnings.warn(format!("XLSB: some defined names were left out ({why})")); + continue; + } + }; + if !budget.try_formula_text(formula.len(), limits) { + warnings.warn("XLSB: some defined names were left out (more formula text than the limits allow)"); + continue; + } + let mut attrs = vec![]; + let mut put = |k: &str, v: String| attrs.push((k.to_string(), v)); + // In `CT_DefinedName`'s order. + if let Some(m) = p.menu { + put("customMenu", m); + } + if let Some(d) = p.description { + put("description", d); + } + let (func, vba, proc) = (p.flags & 0x02 != 0, p.flags & 0x04 != 0, p.flags & 0x08 != 0); + if func { + put("function", "1".into()); + } + if vba { + put("vbProcedure", "1".into()); + } else if proc { + put("xlm", "1".into()); + } + let group = (p.flags >> 6) & 0x1FF; + if proc && group != 0 { + put("functionGroupId", group.to_string()); + } + if p.key != 0 { + put("shortcutKey", char::from(p.key).to_string()); + } + if p.flags & (1 << 15) != 0 { + put("publishToServer", "1".into()); + } + if p.flags & (1 << 16) != 0 { + put("workbookParameter", "1".into()); + } + out.push(DefinedName { + name: name.text.clone(), + local_sheet_id, + formula, + comment: p.comment.unwrap_or_default(), + hidden: p.flags & 1 != 0, + attrs, + }); + if let Some(n) = links.names.get_mut(p.index) { + n.read = true; + } + } + out +} + /// A supporting link (`BrtSupSelf`, `BrtSupSame`, `BrtSupAddin`, `BrtSupBookSrc`), the sheet links -/// (`BrtExternSheet`) or a defined name (`BrtName`), added to `links`. -fn link_record(id: u16, payload: &[u8], links: &mut Links) -> Result<(), Error> { +/// (`BrtExternSheet`) or a defined name (`BrtName`), added to `links`; a name's other parts go to +/// `pending`. +fn link_record(id: u16, payload: &[u8], links: &mut Links, pending: &mut Vec) -> Result<(), Error> { let mut b = Bytes::new(payload); match id { 357 | 358 | 667 => { @@ -391,15 +498,37 @@ fn link_record(id: u16, payload: &[u8], links: &mut Links) -> Result<(), Error> b.finish()?; } _ => { - // BrtName ([MS-XLSB] 2.4.718): flags, chKey, itab, then the name; the formula and the - // rest aren't needed to call a function or tell a name from one. + // BrtName ([MS-XLSB] 2.4.718). Its formula is decoded once the workbook part is read. if links.names.len() >= MAX_NAMES { return Err(invalid("too many defined names")); } let flags = b.u32()?; - b.take(5)?; + let key = b.u8()?; + let itab = b.u32()?; let text = b.text(255)?; - links.names.push(Name { text, future: flags & (1 << 17) != 0 }); + let cce = b.u32()? as usize; + let rgce = b.take(cce)?.to_vec(); + let cb = b.u32()? as usize; + let rgcb = b.take(cb)?.to_vec(); + let comment = b.string(255, true)?; + // A macro's name (fProc) has four more strings: one unused, its custom menu, its + // description and another unused. + let (menu, description) = if flags & 0x08 != 0 { + b.string(32767, true)?; + let menu = b.string(32767, true)?; + let description = b.string(32767, true)?; + b.string(32767, true)?; + (menu, description) + } else { + (None, None) + }; + b.finish()?; + let scope = (itab != u32::MAX).then_some(itab); + // A built-in name (fBuiltin) is stored bare; `.xlsx` spells it `_xlnm.Print_Area`, in + // `definedNames` and in formulas alike. + let text = if flags & 0x20 != 0 { format!("_xlnm.{text}") } else { text }; + pending.push(PendingName { index: links.names.len(), flags, key, rgce, rgcb, comment, menu, description }); + links.names.push(Name { text, future: flags & (1 << 17) != 0, scope, read: false }); } } Ok(()) diff --git a/crates/xlsx/src/xlsb/expr.rs b/crates/xlsx/src/xlsb/expr.rs index 3dd643a6a..17f5086ae 100644 --- a/crates/xlsx/src/xlsb/expr.rs +++ b/crates/xlsx/src/xlsb/expr.rs @@ -24,6 +24,8 @@ pub(crate) enum RefKind { Rows(u32, bool, u32, bool), /// Whole columns `A:C`. Cols(u32, bool, u32, bool), + /// A deleted cell or range on a named sheet: `Sheet2!#REF!`. + Deleted, } #[derive(Clone, Debug, PartialEq, Eq)] @@ -173,6 +175,7 @@ fn push_reference(s: &mut String, r: &Reference) { s.push_str(dollar(*a1)); push_col(s, *c1); } + RefKind::Deleted => s.push_str(CellError::Ref.as_str()), } } diff --git a/crates/xlsx/src/xlsb/formula.rs b/crates/xlsx/src/xlsb/formula.rs index 327ffcc25..2e7f7cc96 100644 --- a/crates/xlsx/src/xlsb/formula.rs +++ b/crates/xlsx/src/xlsb/formula.rs @@ -4,8 +4,9 @@ //! called through hidden names), so this is its own decoder, with its own function table //! ([`super::ftab`]) and its own copies of craft-xls's depth guards and limits. Anything outside the //! token set it knows is reported as unsupported, and the caller keeps the cell's cached value. -//! So is a formula that needs something the reader doesn't read: a user's defined name (XLSB -//! names are not read yet) or Python code stored outside the cell. +//! So is a formula that needs something the reader doesn't read: a defined name whose own +//! formula could not be read, or Python code stored outside the cell. Defined names' formulas +//! are decoded here too ([`Mode::Name`]). //! //! Names keep their file spelling (`_xlfn.CONCAT`, `_xlpm.x`), as `.xlsx` formula text has them. @@ -92,13 +93,26 @@ pub(super) struct Xti { pub last: i32, } -/// A `BrtName` as far as cell formulas need it. +/// A `BrtName` as far as formulas need it. #[derive(Clone, Debug)] pub(super) struct Name { - /// The name as written (`_xlfn.CONCAT`, `_xlpm.x`, `Rate`). + /// The name as `.xlsx` spells it (`_xlfn.CONCAT`, `_xlpm.x`, `_xlnm.Print_Area`, `Rate`). pub text: String, /// `fFutureFunction`: a hidden name standing for a function newer than the file format. pub future: bool, + /// `itab`: the sheet a sheet-scoped name belongs to, by its place in `BrtBundleSh` order. + pub scope: Option, + /// Its own formula was read, so it is one of the workbook's defined names. + pub read: bool, +} + +impl Name { + /// Whether a formula may use the name: one the formula text itself defines (a newer + /// function, a LET parameter), or a defined name the reader gives. A name's formula may use + /// any other name: its text is the same either way. + fn usable(&self, mode: Mode) -> bool { + self.future || is_param(&self.text) || self.read || mode == Mode::Name + } } /// Workbook-level tables formulas refer to. @@ -114,20 +128,37 @@ pub(crate) struct Links { } /// Whether a name stands for a LET parameter (`_xlpm.x`), which only the formula itself defines. -fn is_param(name: &str) -> bool { +pub(super) fn is_param(name: &str) -> bool { name.get(..6).is_some_and(|p| p.eq_ignore_ascii_case("_xlpm.")) } impl Links { - /// The sheets a 3-D reference names, or `None` for a deleted sheet (the reference is `#REF!`). - fn sheet_sel(&self, ixti: u16) -> Result, Unsupported> { + /// `PtgName`'s and `PtgNameX`'s name: a 1-based index into every `BrtName`. A cell formula + /// using a defined name the reader doesn't give would calculate to `#NAME?`, so it keeps its + /// saved result instead. + fn name(&self, index: u32, mode: Mode) -> Result<&Name, Unsupported> { + let i = usize::try_from(index).ok().and_then(|i| i.checked_sub(1)); + let name = i.and_then(|i| self.names.get(i)).ok_or(Unsupported("reference to a missing defined name"))?; + if !name.usable(mode) { + return Err(Unsupported("defined names whose formula could not be read")); + } + Ok(name) + } + + /// Sheet link `ixti`, which must be through this workbook's own supporting link. + fn this_book(&self, ixti: u16) -> Result<&Xti, Unsupported> { let x = self.xti.get(usize::from(ixti)).ok_or(Unsupported("reference to a missing sheet link"))?; match usize::try_from(x.book).ok().and_then(|b| self.books.get(b)) { - Some(Book::This) => {} - Some(Book::External) => return Err(Unsupported("references to other workbooks (external links)")), - Some(_) => return Err(Unsupported("references through add-in or same-sheet links")), - None => return Err(Unsupported("reference to a missing workbook link")), + Some(Book::This) => Ok(x), + Some(Book::External) => Err(Unsupported("references to other workbooks (external links)")), + Some(_) => Err(Unsupported("references through add-in or same-sheet links")), + None => Err(Unsupported("reference to a missing workbook link")), } + } + + /// The sheets a 3-D reference names, or `None` for a deleted sheet (the reference is `#REF!`). + fn sheet_sel(&self, ixti: u16) -> Result, Unsupported> { + let x = self.this_book(ixti)?; // -1: "the first sheet in the reference cannot be found" (a deleted sheet). if x.first == -1 || x.last == -1 { return Ok(None); @@ -194,10 +225,15 @@ const LAST_COL: u32 = MAX_COLS - 1; /// Where a formula lives: a cell formula's references hold coordinates; a shared formula's /// relative tokens (`PtgRefN`, `PtgAreaN`) hold offsets from the shared formula's first cell. +/// +/// A defined name's relative references are offsets from A1 that wrap around the grid +/// (`RgceLocRel`), in its 3-D references too: `.xlsx` spells them as the cell they reach from A1 +/// (one column left is `Data!XFD1`). #[derive(Clone, Copy, PartialEq)] pub(super) enum Mode { Cell, Shared(CellRef), + Name, } /// RgceLoc ([MS-XLSB] 2.5.98.91): a row and a `ColRelShort` (14-bit column, then the @@ -225,9 +261,15 @@ fn loc(row: u32, col: u16, mode: Mode) -> Result { match mode { Mode::Cell => anchor(row, col), Mode::Shared(base) => relative_anchor(row, col, base), + Mode::Name => relative_anchor(row, col, CellRef::new(0, 0)), } } +/// A 3-D reference's cell: a coordinate, except in a defined name. +fn loc3d(row: u32, col: u16, mode: Mode) -> Result { + if mode == Mode::Name { loc(row, col, mode) } else { anchor(row, col) } +} + /// RgceArea: a range spanning every row (or column) is a whole-column (row) reference. fn area(r0: u32, r1: u32, c0: u16, c1: u16) -> Result { area_of(anchor(r0, c0)?, anchor(r1, c1)?) @@ -380,14 +422,7 @@ pub(super) fn decode(rgce: &[u8], rgcb: &[u8], links: &Links, mode: Mode) -> Res } 0x23 => { // PtgName: a 1-based index into every BrtName, hidden ones included. - let i = usize::try_from(t.u32()?).ok().and_then(|i| i.checked_sub(1)); - let name = i.and_then(|i| links.names.get(i)).ok_or(Unsupported("reference to a missing defined name"))?; - // Defined names are not imported from XLSB yet: a cell using one would calculate - // to #NAME?, so it keeps its saved result. Newer functions and LET parameters are - // hidden names that the formula text itself defines. - if !name.future && !is_param(&name.text) { - return Err(Unsupported("defined names")); - } + let name = links.name(t.u32()?, mode)?; push(&mut stack, kids, Expr::Name(name.text.clone()))?; } 0x24 => { @@ -420,36 +455,52 @@ pub(super) fn decode(rgce: &[u8], rgcb: &[u8], links: &Links, mode: Mode) -> Res t.take(12)?; push(&mut stack, kids, Expr::Error(CellError::Ref))?; } - 0x39 => return Err(Unsupported("names in other workbooks or on other sheets")), + 0x39 => { + // PtgNameX: a name through a supporting link. Through this workbook's own link + // it is a sheet-scoped name used from another sheet, which `.xlsx` spells + // `'Other Sheet'!Local`: Excel's files show it, [MS-XLSB] doesn't say. + let ixti = t.u16()?; + let index = t.u32()?; + links.this_book(ixti)?; + let name = links.name(index, mode)?; + let sheet = name.scope.and_then(|s| links.sheets.get(usize::try_from(s).ok()?).cloned().flatten()); + let sheet = sheet.ok_or(Unsupported("names in other workbooks or on other sheets"))?; + push(&mut stack, kids, Expr::Name(format!("{sheet}!{}", name.text)))?; + } 0x3A => { let ixti = t.u16()?; let (r, c) = (t.u32()?, t.u16()?); - let kind = RefKind::Cell(anchor(r, c)?); + let kind = RefKind::Cell(loc3d(r, c, mode)?); push(&mut stack, kids, reference(links.sheet_sel(ixti)?, kind))?; } 0x3B => { let ixti = t.u16()?; let (r0, r1, c0, c1) = (t.u32()?, t.u32()?, t.u16()?, t.u16()?); - let kind = area(r0, r1, c0, c1)?; + let kind = area_of(loc3d(r0, c0, mode)?, loc3d(r1, c1, mode)?)?; push(&mut stack, kids, reference(links.sheet_sel(ixti)?, kind))?; } 0x3C | 0x3D => { + // PtgRefErr3d, PtgAreaErr3d: a deleted cell or range, which `.xlsx` spells + // `Sheet2!#REF!` (`#REF!` when the sheet is gone too). The sheet link must still + // be one the reader follows: an external #REF! stays cached. let ixti = t.u16()?; t.take(if id == 0x3C { 6 } else { 12 })?; - // The sheet link must still be one the reader follows: an external #REF! stays cached. - links.sheet_sel(ixti)?; - push(&mut stack, kids, Expr::Error(CellError::Ref))?; + push(&mut stack, kids, reference(links.sheet_sel(ixti)?, RefKind::Deleted))?; } 0x01 => return Err(Unsupported("the shared or array formula form")), 0x02 => return Err(Unsupported("what-if data tables")), 0x18 => return Err(Unsupported("structured table references")), 0x2C => { - let Mode::Shared(_) = mode else { return Err(Unsupported("relative references in a cell formula")) }; + if mode == Mode::Cell { + return Err(Unsupported("relative references in a cell formula")); + } let (r, c) = (t.u32()?, t.u16()?); push(&mut stack, kids, Expr::Ref(Reference { sheet: SheetSel::Current, kind: RefKind::Cell(loc(r, c, mode)?) }))?; } 0x2D => { - let Mode::Shared(_) = mode else { return Err(Unsupported("relative references in a cell formula")) }; + if mode == Mode::Cell { + return Err(Unsupported("relative references in a cell formula")); + } let (r0, r1, c0, c1) = (t.u32()?, t.u32()?, t.u16()?, t.u16()?); let kind = area_of(loc(r0, c0, mode)?, loc(r1, c1, mode)?)?; push(&mut stack, kids, Expr::Ref(Reference { sheet: SheetSel::Current, kind }))?; diff --git a/crates/xlsx/tests/xlsb.rs b/crates/xlsx/tests/xlsb.rs index ee9ac3afd..73bd23218 100644 --- a/crates/xlsx/tests/xlsb.rs +++ b/crates/xlsx/tests/xlsb.rs @@ -5,7 +5,7 @@ mod common; use common::{read, read_with}; use craft_xlsx::testing::zip; -use craft_xlsx::{CellError, CellRef, Error, FormulaKind, Limits, Range, SheetKind, Value, Visibility, is_xlsb}; +use craft_xlsx::{CellError, CellRef, Error, FormulaKind, Limits, Package, Range, SheetKind, Value, Visibility, is_xlsb}; const ROOT: &str = r#""#; const RELS: &str = r#""#; @@ -463,6 +463,9 @@ fn name(flags: u32, text: &str) -> Vec { data.extend(wide(text)); data.extend([2, 0, 0, 0, 0x1c, 0x1d, 0, 0, 0, 0]); // Formula `#NAME?`, no extra data. data.extend(u32::MAX.to_le_bytes()); // No comment. + if flags & 0x08 != 0 { + data.extend(u32::MAX.to_le_bytes().repeat(4)); // A macro's four strings, all null. + } record(39, &data) } @@ -543,8 +546,8 @@ fn cell_formulas_are_read_in_their_xlsx_spelling() { ), (9, ref3d(3, 0, 0), vec![]), (10, [&[0x25u8][..], &0u32.to_le_bytes(), &1u32.to_le_bytes(), &REL.to_le_bytes(), &REL.to_le_bytes(), &[0x41, 20, 0]].concat(), vec![]), - // Kept as their saved results: (11, vec![0x43, 4, 0, 0, 0, 0x1E, 2, 0, 0x05], vec![]), + // Kept as their saved results: (12, ref3d(4, 0, REL), vec![]), (13, vec![0x01, 0, 0, 0, 0], vec![0, 0, 0, 0]), // Part of a shared formula at A1 that isn't one. ]; @@ -572,7 +575,7 @@ fn cell_formulas_are_read_in_their_xlsx_spelling() { Some("_xlfn.LET(_xlpm.x,1,_xlpm.x+1)"), Some("#REF!"), Some("SQRT(A1:A2)"), - None, + Some("Rate*2"), None, None, // A BrtCellMeta before a cell gives it cell metadata, as `cm` does in .xlsx. @@ -584,7 +587,7 @@ fn cell_formulas_are_read_in_their_xlsx_spelling() { assert_eq!(sheet.cell_metadata.iter().collect::>(), [(&CellRef::new(0, 14), &1)]); // Every formula cell keeps its saved result as its value. assert!((1..=15).all(|c| sheet.value(CellRef::new(0, c)) == Value::Number(0.0))); - for why in ["defined names", "other workbooks", "missing from the file", "structured table references"] { + for why in ["other workbooks", "missing from the file", "structured table references"] { assert!(warned(&wb, why), "{why}: {:?}", wb.warnings); } } @@ -930,3 +933,127 @@ fn a_dynamic_array_kept_as_its_value_has_no_cell_metadata() { assert_eq!(sheet.cell_metadata.iter().collect::>(), [(&at("C1"), &1)]); assert!(warned(&wb, "missing from the file"), "{:?}", wb.warnings); } + +// Defined names ([MS-XLSB] 2.4.718): `BrtName` records, and the `definedNames` Excel writes for +// the same names when it saves the workbook as `.xlsx`. + +/// `BrtName`. A macro's name (`fProc`, 0x08) has four more strings, null here. +fn brt_name(flags: u32, key: u8, itab: u32, text: &str, rgce: &[u8], comment: Option<&str>) -> Vec { + let mut data = flags.to_le_bytes().to_vec(); + data.push(key); + data.extend(itab.to_le_bytes()); + data.extend(wide(text)); + data.extend((rgce.len() as u32).to_le_bytes()); + data.extend(rgce); + data.extend(0u32.to_le_bytes()); + data.extend(comment.map_or_else(|| u32::MAX.to_le_bytes().to_vec(), wide)); + if flags & 0x08 != 0 { + data.extend(u32::MAX.to_le_bytes().repeat(4)); + } + record(39, &data) +} +fn ref3d_name(ixti: u16, row: u32, col: u16) -> Vec { + [&[0x3Au8][..], &ixti.to_le_bytes(), &loc(row, col)].concat() +} +const WORKBOOK: u32 = u32::MAX; + +/// `book(false)` with the supporting links of `book_with_links` (sheet links Data, Hidden, +/// Data:Hidden, a deleted sheet, the other workbook, and this workbook as a whole, which +/// `PtgNameX` uses), and `names`. +fn book_with_names(names: &[Vec]) -> Vec { + let plain = book(false); + let end = record(132, &[]); + let mut xti = 6u32.to_le_bytes().to_vec(); + for (book, first, last) in [(0u32, 0i32, 0i32), (0, 1, 1), (0, 0, 1), (0, -1, -1), (1, 0, 0), (0, -2, -2)] { + xti.extend([book.to_le_bytes(), first.to_le_bytes(), last.to_le_bytes()].concat()); + } + let links = [record(353, &[]), record(357, &[]), record(355, &wide("rId9")), record(362, &xti), record(354, &[])]; + [&plain[..plain.len() - end.len()], &links.concat(), &names.concat(), &end].concat() +} + +/// The names below, in record order, as `PtgName` numbers them from 1. +fn names() -> Vec> { + vec![ + // 1: a newer function's hidden name: not a defined name in `.xlsx`. + brt_name(0x0002_000b, 0, WORKBOOK, "_xlfn.CONCAT", &[0x1C, 0x1D], None), + // 2: built-in and hidden, on Data. + brt_name(0x21, 0, 0, "_FilterDatabase", &[&[0x3Bu8, 0, 0][..], &0u32.to_le_bytes(), &9u32.to_le_bytes(), &[0, 0, 2, 0]].concat(), None), + // 3: refers to another workbook: left out. + brt_name(0, 0, WORKBOOK, "External", &ref3d_name(4, 0, 0), None), + // 4: a deleted cell. + brt_name(0, 0, WORKBOOK, "Gone", &[0x3C, 0, 0, 0, 0, 0, 0, 0, 0], None), + brt_name(1, 0, WORKBOOK, "Hid", &[0x1E, 42, 0], None), + // 6, 7: the same name on two sheets. + brt_name(0, 0, 0, "Local", &ref3d_name(0, 1, 1), None), + brt_name(0, 0, 1, "Local", &ref3d_name(1, 0, 1), None), + // 8: an XLM macro with a shortcut key, in the "User Defined" group (14). + brt_name(0x388, b'k', WORKBOOK, "MacroName", &ref3d_name(0, 0, 0), None), + // 9 + brt_name(0, 0, WORKBOOK, "Rate", &[&[0x1Fu8][..], &0.05f64.to_le_bytes()].concat(), Some("a note")), + // 10, 11: relative references are offsets from A1, wrapping around the grid. + brt_name(0, 0, WORKBOOK, "Rel", &ref3d_name(0, 0, 0xFFFF), None), + brt_name(0, 0, WORKBOOK, "RelN", &[&[0x2Cu8][..], &loc(u32::MAX, REL)].concat(), None), + // 12: on a sheet the workbook doesn't have: left out. + brt_name(0, 0, 5, "Skipped", &[0x1E, 1, 0], None), + // 13: a name of a name. + brt_name(0, 0, WORKBOOK, "Twice", &[0x23, 9, 0, 0, 0, 0x1E, 2, 0, 0x05], None), + ] +} + +const NAMES_XML: &str = r#"Data!#REF!Data!$B$2Hidden!$B$1Data!$A$10.05Data!XFD1A1048576Rate*2"#; + +fn xml_names(xml: &str) -> Vec { + let types = r#""#; + let root = r#""#; + let bytes = zip(&[("[Content_Types].xml", types.as_bytes()), ("_rels/.rels", root.as_bytes()), ("xl/workbook.xml", xml.as_bytes())]); + Package::open(&bytes, &Limits::default()).unwrap().workbook().unwrap().defined_names +} + +#[test] +fn defined_names_are_read_as_their_xlsx_spelling() { + let cells: Vec> = vec![ + vec![0x23, 9, 0, 0, 0, 0x1E, 100, 0, 0x05], + vec![0x23, 6, 0, 0, 0], + // PtgNameX through this workbook's own link: a sheet-scoped name used from another sheet. + vec![0x39, 5, 0, 7, 0, 0, 0], + vec![0x23, 2, 0, 0, 0], + vec![0x3C, 1, 0, 0, 0, 0, 0, 0, 0], + // Kept as their saved results: a name left out, a name in another workbook, and a + // workbook name through PtgNameX. + vec![0x23, 3, 0, 0, 0], + vec![0x39, 4, 0, 9, 0, 0, 0], + vec![0x39, 5, 0, 9, 0, 0, 0], + ]; + let mut data = row(0); + for (i, rgce) in cells.iter().enumerate() { + data.extend(formula_cell(i as u32 + 1, rgce, &[])); + } + let bytes = package(&book_with_names(&names()), &worksheet(&data, &[]), &sst(), ROOT, RELS, TYPES); + let wb = Package::open(&bytes, &Limits::default()).unwrap().workbook().unwrap(); + assert_eq!(wb.defined_names, xml_names(NAMES_XML)); + let book = read(&bytes).unwrap(); + let got: Vec<_> = (1..=8).map(|c| book.sheets[0].formula(CellRef::new(0, c))).collect(); + let want = [Some("Rate*100"), Some("Local"), Some("Hidden!Local"), Some("_xlnm._FilterDatabase"), Some("Hidden!#REF!"), None, None, None]; + assert_eq!(got, want); + for why in ["defined names whose formula could not be read", "other workbooks", "names in other workbooks or on other sheets"] { + assert!(warned(&book, why), "{why}: {:?}", book.warnings); + } + for why in ["(references to other workbooks (external links))", "(names of sheets the reader skips)"] { + assert!(book.warnings.iter().any(|w| w.contains("defined names were left out") && w.contains(why)), "{why}: {:?}", book.warnings); + } +} + +#[test] +fn a_damaged_name_leaves_names_and_formulas_as_values() { + // A truncated BrtName: the workbook opens with no names, and every formula keeps its value. + let mut list = names(); + let full = brt_name(0, 0, WORKBOOK, "Rate", &[0x1E, 1, 0], None); + list[8] = record(39, &full[2..full.len() - 2]); // The payload without its record header and last two bytes. + let data = [row(0), formula_cell(1, &[0x1E, 1, 0], &[])].concat(); + let bytes = package(&book_with_names(&list), &worksheet(&data, &[]), &sst(), ROOT, RELS, TYPES); + let wb = Package::open(&bytes, &Limits::default()).unwrap().workbook().unwrap(); + assert!(wb.defined_names.is_empty()); + let book = read(&bytes).unwrap(); + assert_eq!(book.sheets[0].formula(CellRef::new(0, 1)), None); + assert!(book.warnings.iter().any(|w| w.contains("names could not be read")), "{:?}", book.warnings); +} From 2a786e27a2826e9a67cfe0af167410409717b0d3 Mon Sep 17 00:00:00 2001 From: kiwi4boy Date: Sat, 14 Nov 2026 11:30:32 -0500 Subject: [PATCH 2/6] craft-xlsx: names on macro sheets, spans over chart sheets, formula-less built-ins A second Excel probe showed three cases where the .xlsb reader left out what .xlsx has: - Macro names point at an XLM macro sheet (Macro1!$A$1), which the sheet links treated as a sheet with no cells, so every such name was left out. Macro sheets have cells; references to them are now named. - A 3-D span over a chart sheet ('Data:After Sheet'!$A$1) was refused. A span is spelled by its ends; a sheet with no cells between them adds nothing, and .xlsx spells it the same. - Excel writes a workbook-level built-in with no formula (Database) beside a sheet's own. .xlsx leaves it out of definedNames, but formulas using it spell _xlnm.Database; they now do instead of keeping their saved results. --- crates/xlsx/README.md | 7 +++-- crates/xlsx/src/xlsb.rs | 13 ++++++++-- crates/xlsx/src/xlsb/formula.rs | 13 ++++------ crates/xlsx/tests/xlsb.rs | 46 +++++++++++++++++++++++++++++++++ 4 files changed, 67 insertions(+), 12 deletions(-) diff --git a/crates/xlsx/README.md b/crates/xlsx/README.md index 4e90ca830..3b636a2fa 100644 --- a/crates/xlsx/README.md +++ b/crates/xlsx/README.md @@ -88,8 +88,11 @@ read (each cell keeps its format index). Its defined names are those of `defined `.xlsx` Excel writes: built-in names as `_xlnm.Print_Area`, sheet-scoped names with their `localSheetId`, relative references as the cell they reach from A1, macro names with their `function`, `xlm`, `functionGroupId` and `shortcutKey`. Excel's hidden names for newer functions -and LET parameters are left out, as in `.xlsx`; so is a name whose formula can't be read, with a -warning. Its cell formulas are decoded from their tokens into the +and LET parameters are left out, as in `.xlsx`, and so is the formula-less workbook-level built-in +Excel writes beside a sheet's (`Database`), which formulas still spell `_xlnm.Database`; a name +whose formula can't be read is left out with a warning. A reference may name an XLM macro sheet +(`Macro1!$A$1`, where macro names point), and a 3-D span is spelled by its ends whatever chart +sheets lie between them. Its cell formulas are decoded from their tokens into the text an `.xlsx` file holds (`_xlfn.` and `_xlpm.` names as written, no implicit `@`), with `FormulaKind::Shared` or `FormulaKind::Array` and their ranges, and `BrtCellMeta` as the cell metadata index. Every cell of a shared formula gets its own text, decoded at the cell, since the diff --git a/crates/xlsx/src/xlsb.rs b/crates/xlsx/src/xlsb.rs index 1941ea61e..dd52a55b4 100644 --- a/crates/xlsx/src/xlsb.rs +++ b/crates/xlsx/src/xlsb.rs @@ -356,9 +356,10 @@ pub(crate) fn workbook( if let SheetKind::Other(_) = kind { return Err(invalid("unknown sheet relationship type")); } - // Only a worksheet has cells a formula can refer to. + // Only worksheets and macro sheets have cells a formula can refer to (a macro's + // name refers to its macro sheet: `Macro1!$A$1`). if let Some(l) = links.as_mut() { - l.sheets.push((kind == SheetKind::Worksheet).then(|| name.clone())); + l.sheets.push(matches!(kind, SheetKind::Worksheet | SheetKind::Macrosheet).then(|| name.clone())); } bundle_sheets.push(u32::try_from(wb.sheets.len()).ok()); wb.sheets.push(SheetEntry { name, sheet_id, visibility, rel_id, kind, part: Some(rel.target.clone()) }); @@ -412,6 +413,14 @@ fn defined_names( } }, }; + // Excel writes a workbook-level built-in with no formula (`Database`) beside a sheet's + // own; `.xlsx` leaves it out of `definedNames`, and formulas using it spell its name. + if p.rgce.is_empty() { + if let Some(n) = links.names.get_mut(p.index) { + n.read = true; + } + continue; + } let formula = match formula::decode(&p.rgce, &p.rgcb, links, Mode::Name) { Ok(e) => expr::print(&e), Err(formula::Unsupported(why)) => { diff --git a/crates/xlsx/src/xlsb/formula.rs b/crates/xlsx/src/xlsb/formula.rs index 2e7f7cc96..be6f47bfb 100644 --- a/crates/xlsx/src/xlsb/formula.rs +++ b/crates/xlsx/src/xlsb/formula.rs @@ -118,8 +118,8 @@ impl Name { /// Workbook-level tables formulas refer to. #[derive(Default)] pub(crate) struct Links { - /// Every sheet's name in `BrtBundleSh` order, `None` for sheets the reader skips or that hold - /// no cells (chart, dialog and macro sheets). + /// Every sheet's name in `BrtBundleSh` order, `None` for the sheets that hold no cells (chart, + /// dialog and module sheets). pub(super) sheets: Vec>, /// Every `BrtName`, in order: `PtgName` indexes them from 1. pub(super) names: Vec, @@ -167,14 +167,11 @@ impl Links { let (Ok(first), Ok(last)) = (usize::try_from(x.first), usize::try_from(x.last)) else { return Err(Unsupported("reference to a missing sheet")); }; - // A span takes every sheet between its ends, so a skipped one anywhere in it changes - // what the reference means. + // A span is spelled by its ends. A sheet between them with no cells (a chart sheet) adds + // nothing to it, and `.xlsx` spells the span the same; an end with no cells can't be named. let span = self.sheets.get(first..=last).filter(|s| !s.is_empty()).ok_or(Unsupported("reference to a missing sheet"))?; - if span.iter().any(Option::is_none) { - return Err(Unsupported("references to sheets the reader skips")); - } let (Some(Some(a)), Some(Some(b))) = (span.first(), span.last()) else { - return Err(Unsupported("reference to a missing sheet")); + return Err(Unsupported("references to sheets with no cells")); }; Ok(Some(if first == last { SheetSel::Named(a.clone()) } else { SheetSel::Span(a.clone(), b.clone()) })) } diff --git a/crates/xlsx/tests/xlsb.rs b/crates/xlsx/tests/xlsb.rs index 73bd23218..78e2d89b1 100644 --- a/crates/xlsx/tests/xlsb.rs +++ b/crates/xlsx/tests/xlsb.rs @@ -1057,3 +1057,49 @@ fn a_damaged_name_leaves_names_and_formulas_as_values() { assert_eq!(book.sheets[0].formula(CellRef::new(0, 1)), None); assert!(book.warnings.iter().any(|w| w.contains("names could not be read")), "{:?}", book.warnings); } + +#[test] +fn names_on_macro_sheets_spans_over_chart_sheets_and_empty_built_ins() { + // Sheets Data, a chart sheet, an XLM macro sheet, Hidden; sheet links Macro1, Data:Hidden + // (over both) and Data. + let mut book = record(131, &[]); + book.extend(record(153, &[[0u8; 8].as_slice(), &wide("")].concat())); + book.extend(record(143, &[])); + for (id, rel, name) in [(1u32, "one", "Data"), (3, "c", "Chart1"), (4, "m", "Macro1"), (2, "two", "Hidden")] { + book.extend(record(156, &[&0u32.to_le_bytes()[..], &id.to_le_bytes(), &wide(rel), &wide(name)].concat())); + } + book.extend(record(144, &[])); + let mut xti = 3u32.to_le_bytes().to_vec(); + for (first, last) in [(2i32, 2i32), (0, 3), (0, 0)] { + xti.extend([0u32.to_le_bytes(), first.to_le_bytes(), last.to_le_bytes()].concat()); + } + book.extend([record(353, &[]), record(357, &[]), record(362, &xti), record(354, &[])].concat()); + let area = [&[0x3Bu8][..], &2u16.to_le_bytes(), &0u32.to_le_bytes(), &1u32.to_le_bytes(), &0u16.to_le_bytes(), &1u16.to_le_bytes()].concat(); + // A sheet's built-in Database, then the workbook-level one Excel writes with no formula. + book.extend(brt_name(0x20, 0, 0, "Database", &area, None)); + book.extend(brt_name(0x20, 0, WORKBOOK, "Database", &[], None)); + book.extend(brt_name(0x388, b'k', WORKBOOK, "Cmd", &ref3d_name(0, 0, 0), None)); + book.extend(brt_name(0, 0, WORKBOOK, "Span", &ref3d_name(1, 0, 0), None)); + book.extend(record(132, &[])); + let rels = RELS.replace( + "", + r#""#, + ); + let ref3d_cell = |ixti: u16| [&[0x5Au8][..], &ixti.to_le_bytes(), &loc(0, 0)].concat(); + let data = [ + row(0), + formula_cell(1, &[0x23, 2, 0, 0, 0], &[]), + formula_cell(2, &[0x23, 4, 0, 0, 0], &[]), + formula_cell(3, &ref3d_cell(0), &[]), + formula_cell(4, &ref3d_cell(1), &[]), + ] + .concat(); + let bytes = package(&book, &worksheet(&data, &[]), &sst(), ROOT, &rels, TYPES); + let wb = Package::open(&bytes, &Limits::default()).unwrap().workbook().unwrap(); + let xml = r#"Data!$A$1:$B$2Macro1!$A$1Data:Hidden!$A$1"#; + assert_eq!(wb.defined_names, xml_names(xml)); + let read = read(&bytes).unwrap(); + let got: Vec<_> = (1..=4).map(|c| read.sheets[0].formula(CellRef::new(0, c))).collect(); + assert_eq!(got, [Some("_xlnm.Database"), Some("Span"), Some("Macro1!$A$1"), Some("Data:Hidden!$A$1")]); + assert!(read.warnings.iter().all(|w| !w.contains("left out") && !w.contains("saved results")), "{:?}", read.warnings); +} From b5eda42a33893ec17143532cef6fc1d97accb9d5 Mon Sep 17 00:00:00 2001 From: kiwi4boy Date: Sat, 14 Nov 2026 12:21:06 -0500 Subject: [PATCH 3/6] craft-xlsx: VBA function names and macro descriptions in binary workbooks An Excel probe with VBA enabled showed two things the names reader got wrong: - Excel writes a VBA function a cell calls as a BrtName with fFunc, fOB and fProc, no formula, and none of the four strings fProc names otherwise carry. The reader refused it, which dropped every name and left every formula as its saved result. Such a name now ends after its comment; it stays out of the names, as .xlsm lists none, and cells calling it spell it. - The two middle strings of a macro's name are its description and help topic, as .xlsm writes them (description="Function A" help="!0"), not the custom menu and description the specification's labels say. --- crates/xlsx/README.md | 39 ++++++++++++++++----------------- crates/xlsx/src/xlsb.rs | 23 +++++++++++--------- crates/xlsx/tests/xlsb.rs | 45 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 78 insertions(+), 29 deletions(-) diff --git a/crates/xlsx/README.md b/crates/xlsx/README.md index b873c87f6..e79fdbd55 100644 --- a/crates/xlsx/README.md +++ b/crates/xlsx/README.md @@ -83,25 +83,26 @@ for new pictures (`vm = i + 1`) and the `XLDAPR` dynamic-array metadata (`cm = 1 The parts this crate writes use the transitional namespaces; a strict file's kept parts stay as they were. A binary workbook is not written. -A binary workbook gives the same `Workbook`, strings, rows and merged cells. Its styles are not -read (each cell keeps its format index). Its defined names are those of `definedNames` in the -`.xlsx` Excel writes: built-in names as `_xlnm.Print_Area`, sheet-scoped names with their -`localSheetId`, relative references as the cell they reach from A1, macro names with their -`function`, `xlm`, `functionGroupId` and `shortcutKey`. Excel's hidden names for newer functions -and LET parameters are left out, as in `.xlsx`, and so is the formula-less workbook-level built-in -Excel writes beside a sheet's (`Database`), which formulas still spell `_xlnm.Database`; a name -whose formula can't be read is left out with a warning. A reference may name an XLM macro sheet -(`Macro1!$A$1`, where macro names point), and a 3-D span is spelled by its ends whatever chart -sheets lie between them. Its cell formulas are decoded from their tokens into the text an `.xlsx` -file holds (`_xlfn.` and `_xlpm.` names as written, apart from the four ISO/IEC 29500 functions -`.xlsx` names bare, no implicit `@`, the spaces and line breaks typed in the formula, numbers as -Excel spells them), with -`FormulaKind::Shared` or `FormulaKind::Array` and their ranges, and `BrtCellMeta` as the cell -metadata index. Every cell of a shared formula gets its own text, decoded at the cell, since the -file keeps the tokens once. A formula whose decoding needs something the reader does not read -keeps only its saved result, with a warning saying why: a defined name left out, table references, -other workbooks, Python code stored outside the cell, data tables. The XLSB function table -(`xlsb/ftab.rs`) and the expression printer are this crate's own, apart from `craft-xls`'s. +A binary workbook gives the same `Workbook`, strings, rows and merged cells. Its styles are not read +(each cell keeps its format index). Its defined names are those of `definedNames` in the `.xlsx` +Excel writes: built-in names as `_xlnm.Print_Area`, sheet-scoped names with their `localSheetId`, +relative references as the cell they reach from A1, macro names with their `function`, `xlm` or +`vbProcedure`, `functionGroupId`, `shortcutKey`, `description` and `help`. Excel's hidden names for +newer functions and LET parameters are left out, as in `.xlsx`, and so is the formula-less +workbook-level built-in Excel writes beside a sheet's (`Database`), which formulas still spell +`_xlnm.Database`, and the formula-less name of a VBA function a cell calls (`.xlsm` lists none; the +cell spells it); a name whose formula can't be read is left out with a warning. A reference may name +an XLM macro sheet (`Macro1!$A$1`, where macro names point), and a 3-D span is spelled by its ends +whatever chart sheets lie between them. Its cell formulas are decoded from their tokens into the +text an `.xlsx` file holds (`_xlfn.` and `_xlpm.` names as written, apart from the four ISO/IEC +29500 functions `.xlsx` names bare, no implicit `@`, the spaces and line breaks typed in the +formula, numbers as Excel spells them), with `FormulaKind::Shared` or `FormulaKind::Array` and their +ranges, and `BrtCellMeta` as the cell metadata index. Every cell of a shared formula gets its own +text, decoded at the cell, since the file keeps the tokens once. A formula whose decoding needs +something the reader does not read keeps only its saved result, with a warning saying why: a defined +name left out, table references, other workbooks, Python code stored outside the cell, data tables. +The XLSB function table (`xlsb/ftab.rs`) and the expression printer are this crate's own, apart from +`craft-xls`'s. ## Hostile input diff --git a/crates/xlsx/src/xlsb.rs b/crates/xlsx/src/xlsb.rs index dd52a55b4..e6246f4be 100644 --- a/crates/xlsx/src/xlsb.rs +++ b/crates/xlsx/src/xlsb.rs @@ -380,8 +380,8 @@ struct PendingName { rgce: Vec, rgcb: Vec, comment: Option, - menu: Option, description: Option, + help: Option, } /// The workbook's defined names, as `.xlsx` has them in `definedNames`: every `BrtName` but the @@ -435,12 +435,12 @@ fn defined_names( let mut attrs = vec![]; let mut put = |k: &str, v: String| attrs.push((k.to_string(), v)); // In `CT_DefinedName`'s order. - if let Some(m) = p.menu { - put("customMenu", m); - } if let Some(d) = p.description { put("description", d); } + if let Some(h) = p.help { + put("help", h); + } let (func, vba, proc) = (p.flags & 0x02 != 0, p.flags & 0x04 != 0, p.flags & 0x08 != 0); if func { put("function", "1".into()); @@ -520,14 +520,17 @@ fn link_record(id: u16, payload: &[u8], links: &mut Links, pending: &mut VecData!$A$1"#; + assert_eq!(wb.defined_names, xml_names(xml)); +} From 0f944f62d5330c58bfe2cfdeac3d74881ec67748 Mon Sep 17 00:00:00 2001 From: kiwi4boy Date: Sat, 14 Nov 2026 12:44:03 -0500 Subject: [PATCH 4/6] craft-xlsx: review fixes: names using a left-out name are left out; quoted sheet-scoped calls - A name whose formula uses a name that is left out (another workbook, a skipped sheet, an unreadable formula) was still published, so a cell using it decoded and would calculate to #NAME?. Each name's formula now records the names it uses, and every name reached from a left-out one is left out too, whatever their order: once each, so a long chain costs no more than its uses. A cell using one keeps its saved result. - A sheet-scoped name called as a function through PtgNameX prints its sheet quoted where needed ('My Sheet'!Fn(1)), as a sheet-qualified name does. --- crates/xlsx/README.md | 24 +++++++++---------- crates/xlsx/src/xlsb.rs | 42 +++++++++++++++++++++++++++++++-- crates/xlsx/src/xlsb/expr.rs | 24 ++++++++++++++++++- crates/xlsx/src/xlsb/formula.rs | 10 +++++++- crates/xlsx/tests/xlsb.rs | 22 +++++++++++++++++ 5 files changed, 106 insertions(+), 16 deletions(-) diff --git a/crates/xlsx/README.md b/crates/xlsx/README.md index 75dd8602a..6e6291934 100644 --- a/crates/xlsx/README.md +++ b/crates/xlsx/README.md @@ -91,18 +91,18 @@ relative references as the cell they reach from A1, macro names with their `func newer functions and LET parameters are left out, as in `.xlsx`, and so is the formula-less workbook-level built-in Excel writes beside a sheet's (`Database`), which formulas still spell `_xlnm.Database`, and the formula-less name of a VBA function a cell calls (`.xlsm` lists none; the -cell spells it); a name whose formula can't be read is left out with a warning. A reference may name -an XLM macro sheet (`Macro1!$A$1`, where macro names point), and a 3-D span is spelled by its ends -whatever chart sheets lie between them. Its cell formulas are decoded from their tokens into the -text an `.xlsx` file holds (`_xlfn.` and `_xlpm.` names as written, apart from the four ISO/IEC -29500 functions `.xlsx` names bare, no implicit `@`, the spaces and line breaks typed in the -formula, numbers as Excel spells them), with `FormulaKind::Shared` or `FormulaKind::Array` and their -ranges, and `BrtCellMeta` as the cell metadata index. Every cell of a shared formula gets its own -text, decoded at the cell, since the file keeps the tokens once. A formula whose decoding needs -something the reader does not read keeps only its saved result, with a warning saying why: a defined -name left out, table references, other workbooks, Python code stored outside the cell, data tables. -The XLSB function table (`xlsb/ftab.rs`) and the expression printer are this crate's own, apart from -`craft-xls`'s. +cell spells it); a name whose formula can't be read is left out with a warning, and so is every name +whose formula uses a left-out name. A reference may name an XLM macro sheet (`Macro1!$A$1`, where +macro names point), and a 3-D span is spelled by its ends whatever chart sheets lie between them. +Its cell formulas are decoded from their tokens into the text an `.xlsx` file holds (`_xlfn.` and +`_xlpm.` names as written, apart from the four ISO/IEC 29500 functions `.xlsx` names bare, no +implicit `@`, the spaces and line breaks typed in the formula, numbers as Excel spells them), with +`FormulaKind::Shared` or `FormulaKind::Array` and their ranges, and `BrtCellMeta` as the cell +metadata index. Every cell of a shared formula gets its own text, decoded at the cell, since the +file keeps the tokens once. A formula whose decoding needs something the reader does not read keeps +only its saved result, with a warning saying why: a defined name left out, table references, other +workbooks, Python code stored outside the cell, data tables. The XLSB function table +(`xlsb/ftab.rs`) and the expression printer are this crate's own, apart from `craft-xls`'s. ## Hostile input diff --git a/crates/xlsx/src/xlsb.rs b/crates/xlsx/src/xlsb.rs index 1eb7cddc1..22976d826 100644 --- a/crates/xlsx/src/xlsb.rs +++ b/crates/xlsx/src/xlsb.rs @@ -397,7 +397,10 @@ fn defined_names( budget: &Budget, warnings: &mut Warnings, ) -> Vec { - let mut out = vec![]; + // Each name's formula, and the names it uses. A name whose formula uses a name that is left + // out is left out too, whatever their order, so a cell using it keeps its saved result. + let mut omitted = vec![false; links.names.len()]; + let mut kept = vec![]; for p in pending { let Some(name) = links.names.get(p.index) else { continue }; if name.future || formula::is_param(&name.text) { @@ -409,6 +412,7 @@ fn defined_names( Some(Some(i)) => Some(*i), _ => { warnings.warn("XLSB: some defined names were left out (names of sheets the reader skips)"); + omit(&mut omitted, p.index); continue; } }, @@ -421,17 +425,46 @@ fn defined_names( } continue; } - let formula = match formula::decode(&p.rgce, &p.rgcb, links, Mode::Name) { + let mut used = vec![]; + let formula = match formula::decode_using(&p.rgce, &p.rgcb, links, Mode::Name, &mut used) { Ok(e) => expr::print(&e), Err(formula::Unsupported(why)) => { warnings.warn(format!("XLSB: some defined names were left out ({why})")); + omit(&mut omitted, p.index); continue; } }; if !budget.try_formula_text(formula.len(), limits) { warnings.warn("XLSB: some defined names were left out (more formula text than the limits allow)"); + omit(&mut omitted, p.index); continue; } + kept.push((p, local_sheet_id, formula, used)); + } + // Who uses each name, then every name reached from a left-out one: once each, so a chain + // of any length costs what its uses do. + let mut users: HashMap> = HashMap::new(); + for (k, (.., used)) in kept.iter().enumerate() { + for &u in used { + users.entry(u).or_default().push(k); + } + } + let mut queue: Vec = (0..omitted.len()).filter(|&i| omitted[i]).collect(); + while let Some(i) = queue.pop() { + for &k in users.get(&i).map_or(&[][..], Vec::as_slice) { + let Some((p, ..)) = kept.get(k) else { continue }; + if omit(&mut omitted, p.index) { + warnings.warn("XLSB: some defined names were left out (names using a name that was left out)"); + queue.push(p.index); + } + } + } + let mut out = vec![]; + for (p, local_sheet_id, formula, _) in kept { + if omitted.get(p.index).copied().unwrap_or(true) { + continue; + } + let Some(name) = links.names.get(p.index) else { continue }; let mut attrs = vec![]; let mut put = |k: &str, v: String| attrs.push((k.to_string(), v)); // In `CT_DefinedName`'s order. @@ -478,6 +511,11 @@ fn defined_names( out } +/// Marks name `i` left out; whether it wasn't already. +fn omit(omitted: &mut [bool], i: usize) -> bool { + omitted.get_mut(i).is_some_and(|o| !std::mem::replace(o, true)) +} + /// A supporting link (`BrtSupSelf`, `BrtSupSame`, `BrtSupAddin`, `BrtSupBookSrc`), the sheet links /// (`BrtExternSheet`) or a defined name (`BrtName`), added to `links`; a name's other parts go to /// `pending`. diff --git a/crates/xlsx/src/xlsb/expr.rs b/crates/xlsx/src/xlsb/expr.rs index eee43a557..4c5efe4f7 100644 --- a/crates/xlsx/src/xlsb/expr.rs +++ b/crates/xlsx/src/xlsb/expr.rs @@ -283,6 +283,20 @@ fn write_args(s: &mut String, args: &[Expr], sep: char) { } } +/// A function's name; a sheet-scoped one (`My Sheet!Fn`) is quoted as a sheet-qualified name is. +/// Kept out of [`write_expr`], whose frame every nesting level of a formula repeats. +#[inline(never)] +fn push_function_name(s: &mut String, name: &str) { + match sheet_split(name) { + Some((sheet, name)) => { + s.push_str("e_sheet(sheet)); + s.push('!'); + s.push_str(name); + } + None => s.push_str(name), + } +} + fn write_expr(s: &mut String, e: &Expr) { match e { Expr::Number(n) => s.push_str(&number(*n)), @@ -331,7 +345,7 @@ fn write_expr(s: &mut String, e: &Expr) { write_expr(s, b); } Expr::Call(name, args) => { - s.push_str(name); + push_function_name(s, name); s.push('('); write_args(s, args, ','); s.push(')'); @@ -377,4 +391,12 @@ mod tests { assert_eq!(number_to_text(1e100), "1E+100"); assert!(number(f64::MAX).parse::().is_ok_and(f64::is_finite)); } + + #[test] + fn a_sheet_scoped_function_name_is_quoted() { + let call = |name: &str| print(&Expr::Call(name.into(), vec![Expr::Number(1.0)])); + assert_eq!(call("My Sheet!Fn"), "'My Sheet'!Fn(1)"); + assert_eq!(call("Data!Fn"), "Data!Fn(1)"); + assert_eq!(call("SUM"), "SUM(1)"); + } } diff --git a/crates/xlsx/src/xlsb/formula.rs b/crates/xlsx/src/xlsb/formula.rs index 2c5712d33..46f7b5acd 100644 --- a/crates/xlsx/src/xlsb/formula.rs +++ b/crates/xlsx/src/xlsb/formula.rs @@ -338,6 +338,11 @@ fn reference(sheet: Option, kind: RefKind) -> Expr { /// represented. A shared formula's tokens are decoded once for each of its cells /// (`Mode::Shared` with that cell), whose relative references are offsets from it. pub(super) fn decode(rgce: &[u8], rgcb: &[u8], links: &Links, mode: Mode) -> Result { + decode_using(rgce, rgcb, links, mode, &mut Vec::new()) +} + +/// [`decode`], adding to `used` the 0-based index of every defined name the formula uses. +pub(super) fn decode_using(rgce: &[u8], rgcb: &[u8], links: &Links, mode: Mode, used: &mut Vec) -> Result { if rgce.len() > MAX_RGCE { return Err(Unsupported("formula too long")); } @@ -512,7 +517,9 @@ pub(super) fn decode(rgce: &[u8], rgcb: &[u8], links: &Links, mode: Mode) -> Res } 0x23 => { // PtgName: a 1-based index into every BrtName, hidden ones included. - let name = links.name(t.u32()?, mode)?; + let index = t.u32()?; + let name = links.name(index, mode)?; + used.extend(usize::try_from(index).ok().and_then(|i| i.checked_sub(1))); push(&mut stack, kids, Expr::Name(name.text.clone()))?; } 0x24 => { @@ -553,6 +560,7 @@ pub(super) fn decode(rgce: &[u8], rgcb: &[u8], links: &Links, mode: Mode) -> Res let index = t.u32()?; links.this_book(ixti)?; let name = links.name(index, mode)?; + used.extend(usize::try_from(index).ok().and_then(|i| i.checked_sub(1))); let sheet = name.scope.and_then(|s| links.sheets.get(usize::try_from(s).ok()?).cloned().flatten()); let sheet = sheet.ok_or(Unsupported("names in other workbooks or on other sheets"))?; push(&mut stack, kids, Expr::Name(format!("{sheet}!{}", name.text)))?; diff --git a/crates/xlsx/tests/xlsb.rs b/crates/xlsx/tests/xlsb.rs index 6502c1e5d..4d8f12d75 100644 --- a/crates/xlsx/tests/xlsb.rs +++ b/crates/xlsx/tests/xlsb.rs @@ -1280,3 +1280,25 @@ fn a_spent_formula_allowance_skips_decoding() { assert!(warned(&wb, "more formula text than the limits allow"), "{:?}", wb.warnings); assert!(!warned(&wb, "unknown formula token"), "{:?}", wb.warnings); } + +#[test] +fn a_name_using_a_left_out_name_is_left_out_too() { + // 14 Early = Later (a later name), 15 Alias = External (left out: another workbook), + // 16 Later = Alias, 17 Fine = Rate. Early, Alias and Later are left out whatever their order, + // and cells using them keep their saved results; Fine is read. + let mut list = names(); + for (text, index) in [("Early", 16u32), ("Alias", 3), ("Later", 15), ("Fine", 9)] { + list.push(brt_name(0, 0, WORKBOOK, text, &[&[0x23u8][..], &index.to_le_bytes()].concat(), None)); + } + let cell = |i: u32| [&[0x23u8][..], &i.to_le_bytes()].concat(); + let data = + [row(0), formula_cell(1, &cell(14), &[]), formula_cell(2, &cell(15), &[]), formula_cell(3, &cell(16), &[]), formula_cell(4, &cell(17), &[])] + .concat(); + let bytes = package(&book_with_names(&list), &worksheet(&data, &[]), &sst(), ROOT, RELS, TYPES); + let wb = Package::open(&bytes, &Limits::default()).unwrap().workbook().unwrap(); + let xml = NAMES_XML.replace("", r#"Rate"#); + assert_eq!(wb.defined_names, xml_names(&xml)); + let book = read(&bytes).unwrap(); + assert_eq!((1..=4).map(|c| book.sheets[0].formula(CellRef::new(0, c))).collect::>(), [None, None, None, Some("Fine")]); + assert!(book.warnings.iter().any(|w| w.contains("names using a name that was left out")), "{:?}", book.warnings); +} From b367c04c9deb2a1ac7dc391b270572ec4ab44b40 Mon Sep 17 00:00:00 2001 From: FredApps Date: Mon, 16 Nov 2026 12:25:17 +0100 Subject: [PATCH 5/6] Keep cached results for malformed empty XLSB names --- crates/xlsx/src/xlsb.rs | 16 ++++++++++++---- crates/xlsx/tests/xlsb.rs | 31 +++++++++++++++++++++++++++++++ 2 files changed, 43 insertions(+), 4 deletions(-) diff --git a/crates/xlsx/src/xlsb.rs b/crates/xlsx/src/xlsb.rs index c1a2f8962..ff54ffcaf 100644 --- a/crates/xlsx/src/xlsb.rs +++ b/crates/xlsx/src/xlsb.rs @@ -449,11 +449,19 @@ fn defined_names( } }, }; - // Excel writes a workbook-level built-in with no formula (`Database`) beside a sheet's - // own; `.xlsx` leaves it out of `definedNames`, and formulas using it spell its name. + // Excel omits the formula for a workbook-level Database built-in and a VBA function + // (fFunc, fOB, fProc). They remain usable by formulas without a definedNames entry. + // Other empty names are malformed: omitting them must also omit their dependants. if p.rgce.is_empty() { - if let Some(n) = links.names.get_mut(p.index) { - n.read = true; + let database = p.flags & 0x20 != 0 && name.scope.is_none() && name.text == "_xlnm.Database"; + let vba_function = p.flags & 0x0E == 0x0E; + if database || vba_function { + if let Some(n) = links.names.get_mut(p.index) { + n.read = true; + } + } else { + warnings.warn("XLSB: some defined names were left out (empty formula)"); + omit(&mut omitted, p.index); } continue; } diff --git a/crates/xlsx/tests/xlsb.rs b/crates/xlsx/tests/xlsb.rs index 27bcc18c1..6b403bfe8 100644 --- a/crates/xlsx/tests/xlsb.rs +++ b/crates/xlsx/tests/xlsb.rs @@ -1737,3 +1737,34 @@ fn module_sheets_and_supporting_links_are_bounded() { assert_eq!(wb.sheets[0].formula(CellRef::new(0, 0)), None); assert!(wb.warnings.iter().any(|w| w.contains("sheet links or names could not be read")), "{:?}", wb.warnings); } + +#[test] +fn empty_ordinary_names_and_their_dependants_keep_cached_values() { + // Forward and transitive references to an empty ordinary name must not become dangling + // formulas. An empty sheet-scoped Database or another built-in is not the observed + // workbook-level Database exception either. + let mut list = names(); + let cell = |i: u32| [&[0x23u8][..], &i.to_le_bytes()].concat(); + list.push(brt_name(0, 0, WORKBOOK, "Early", &cell(16), None)); // 14 + list.push(brt_name(0, 0, WORKBOOK, "Empty", &[], None)); // 15 + list.push(brt_name(0, 0, WORKBOOK, "Alias", &cell(15), None)); // 16 + list.push(brt_name(0x20, 0, 0, "Database", &[], None)); // 17 + list.push(brt_name(0x20, 0, WORKBOOK, "Print_Area", &[], None)); // 18 + list.push(brt_name(0, 0, WORKBOOK, "Fine", &cell(9), None)); // 19 + let mut data = row(0); + for i in 14..=19 { + data.extend(formula_cell(i - 13, &cell(i), &[])); + } + let bytes = package(&book_with_names(&list), &worksheet(&data, &[]), &sst(), ROOT, RELS, TYPES); + let wb = Package::open(&bytes, &Limits::default()).unwrap().workbook().unwrap(); + let xml = NAMES_XML.replace("", r#"Rate"#); + assert_eq!(wb.defined_names, xml_names(&xml)); + let book = read(&bytes).unwrap(); + for col in 1..=5 { + assert_eq!(book.sheets[0].formula(CellRef::new(0, col)), None); + assert_eq!(book.sheets[0].value(CellRef::new(0, col)), Value::Number(0.0)); + } + assert_eq!(book.sheets[0].formula(CellRef::new(0, 6)), Some("Fine")); + assert!(book.warnings.iter().any(|w| w.contains("empty formula")), "{:?}", book.warnings); + assert!(book.warnings.iter().any(|w| w.contains("names using a name that was left out")), "{:?}", book.warnings); +} From dd80bb5bc5f09afae4972bf4128d24647841e29e Mon Sep 17 00:00:00 2001 From: FredApps Date: Mon, 16 Nov 2026 13:21:01 +0100 Subject: [PATCH 6/6] Keep cached results for shadowed XLSB name references --- crates/xlsx/src/xlsb.rs | 22 ++++++++++++++++++++- crates/xlsx/tests/xlsb.rs | 41 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 62 insertions(+), 1 deletion(-) diff --git a/crates/xlsx/src/xlsb.rs b/crates/xlsx/src/xlsb.rs index ff54ffcaf..02087ed4a 100644 --- a/crates/xlsx/src/xlsb.rs +++ b/crates/xlsx/src/xlsb.rs @@ -10,7 +10,7 @@ mod formula; mod ftab; mod styles; -use std::collections::HashMap; +use std::collections::{HashMap, HashSet}; use std::sync::Arc; use craft_opc::{ContentTypes, Rels}; @@ -433,6 +433,14 @@ fn defined_names( // out is left out too, whatever their order, so a cell using it keeps its saved result. let mut omitted = vec![false; links.names.len()]; let mut kept = vec![]; + // PtgName identifies a record, but a bare workbook name in a sheet-scoped definition + // would instead bind to a same-spelled local name. Without a workbook qualifier, keep + // the cached results rather than silently changing that identity. Index once so hostile + // files with many names and references cannot turn this check into a quadratic scan. + // Ordinary shadows still count if their own formulas are omitted: do not infer a new + // binding from a partially emitted name environment. Synthetic names are not definitions. + let local_names: HashSet<_> = + links.names.iter().filter(|n| !n.future && !formula::is_param(&n.text)).filter_map(|n| n.scope.map(|s| (s, n.text.to_lowercase()))).collect(); for p in pending { let Some(name) = links.names.get(p.index) else { continue }; if name.future || formula::is_param(&name.text) { @@ -474,6 +482,18 @@ fn defined_names( continue; } }; + if name.scope.is_some_and(|scope| { + used.iter().filter_map(|&i| links.names.get(i)).any(|target| { + target.scope.is_none() + && !target.future + && !formula::is_param(&target.text) + && local_names.contains(&(scope, target.text.to_lowercase())) + }) + }) { + warnings.warn("XLSB: some defined names were left out (workbook names shadowed by local names)"); + omit(&mut omitted, p.index); + continue; + } if !budget.try_formula_text(formula.len(), limits) { warnings.warn("XLSB: some defined names were left out (more formula text than the limits allow)"); omit(&mut omitted, p.index); diff --git a/crates/xlsx/tests/xlsb.rs b/crates/xlsx/tests/xlsb.rs index 6b403bfe8..96c7cff5d 100644 --- a/crates/xlsx/tests/xlsb.rs +++ b/crates/xlsx/tests/xlsb.rs @@ -1768,3 +1768,44 @@ fn empty_ordinary_names_and_their_dependants_keep_cached_values() { assert!(book.warnings.iter().any(|w| w.contains("empty formula")), "{:?}", book.warnings); assert!(book.warnings.iter().any(|w| w.contains("names using a name that was left out")), "{:?}", book.warnings); } + +#[test] +fn scoped_names_do_not_rebind_shadowed_workbook_names() { + let token = |i: u32| [&[0x23u8][..], &i.to_le_bytes()].concat(); + let list = vec![ + brt_name(0, 0, WORKBOOK, "Rate", &[0x1E, 1, 0], None), // 1 + brt_name(0, 0, 1, "rAtE", &[0x1E, 2, 0], None), // 2: Hidden shadows Rate case-insensitively. + brt_name(0, 0, 1, "Alias", &token(1), None), // 3: must not become Hidden!rAtE. + brt_name(0, 0, 1, "Forward", &token(5), None), // 4 + brt_name(0, 0, 1, "Dependent", &token(3), None), // 5 + brt_name(0, 0, 0, "Fine", &token(1), None), // 6: no shadow on Data. + brt_name(0, 0, 1, "LocalAlias", &token(2), None), // 7: intentionally uses Hidden!rAtE. + brt_name(0, 0, WORKBOOK, "Other", &[0x1E, 3, 0], None), // 8 + brt_name(0, 0, 1, "Other", &[], None), // 9: malformed, but still an ordinary source shadow. + brt_name(0, 0, 1, "Conservative", &token(8), None), // 10 + brt_name(0, 0, WORKBOOK, "Synthetic", &[0x1E, 4, 0], None), // 11 + brt_name(0x0002_0000, 0, 1, "Synthetic", &[0x1C, 0x1D], None), // 12: future-function metadata. + brt_name(0, 0, 1, "SyntheticControl", &token(11), None), // 13: synthetic name is not a local definition. + ]; + let mut data = row(0); + for (col, index) in [3u32, 4, 5, 6, 10, 13].into_iter().enumerate() { + // PtgNameX qualifies these names on their own sheets. + let formula = [&[0x39u8, 0, 0][..], &index.to_le_bytes()].concat(); + data.extend(formula_cell(col as u32 + 1, &formula, &[])); + } + let bytes = package(&book_with_names(&list), &worksheet(&data, &[]), &sst(), ROOT, RELS, TYPES); + let wb = Package::open(&bytes, &Limits::default()).unwrap().workbook().unwrap(); + let xml = r#"12RaterAtE34Synthetic"#; + assert_eq!(wb.defined_names, xml_names(xml)); + let book = read(&bytes).unwrap(); + for col in 1..=3 { + assert_eq!(book.sheets[0].formula(CellRef::new(0, col)), None); + assert_eq!(book.sheets[0].value(CellRef::new(0, col)), Value::Number(0.0)); + } + assert_eq!(book.sheets[0].formula(CellRef::new(0, 4)), Some("Data!Fine")); + assert_eq!(book.sheets[0].formula(CellRef::new(0, 5)), None); + assert_eq!(book.sheets[0].value(CellRef::new(0, 5)), Value::Number(0.0)); + assert_eq!(book.sheets[0].formula(CellRef::new(0, 6)), Some("Hidden!SyntheticControl")); + assert!(book.warnings.iter().any(|w| w.contains("workbook names shadowed by local names")), "{:?}", book.warnings); + assert!(book.warnings.iter().any(|w| w.contains("names using a name that was left out")), "{:?}", book.warnings); +}