roo-calamine 0.0.1

data/ext/roo_calamine/src/reader.rs

@@ -0,0 +1,1182 @@
+//! Streaming reader for worksheet XML that yields the raw cell records roo
+//! builds its cells from.
+//!
+//! roo reads a worksheet in two ways, and each one selects rows and cells
+//! differently:
+//!
+//! * [`Mode::Document`] mirrors `Roo::Excelx::SheetDoc#extract_cells`: the
+//!   XPath `/worksheet/sheetData/row` and then `c` children, on a document
+//!   whose namespaces were removed, so names compare by local name.
+//! * [`Mode::Stream`] mirrors `Roo::Utils.each_element(path, "row")` plus
+//!   `SheetDoc#each_cell`: every element whose qualified name is `row`, at any
+//!   depth, and every element child of that row.
+//!
+//! Inside a cell both modes follow `SheetDoc#cell_from_xml`: the first `v`
+//! child, or the first `is` child with non-empty text, decides the value, and
+//! an `f` child seen before it is the formula.
+
+use std::fmt;
+use std::fs::File;
+use std::io::{BufRead, BufReader};
+use std::ops::Range;
+use std::path::Path;
+
+use quick_xml::events::{BytesRef, BytesStart, Event};
+use quick_xml::XmlVersion;
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Mode {
+    Document,
+    Stream,
+}
+
+/// The `r` attribute.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum Reference {
+    Missing,
+    /// What `Roo::Utils.extract_coordinate` returns for it.
+    At {
+        row: i64,
+        column: i64,
+    },
+    /// A value `Roo::Utils.extract_coordinate` raises for.
+    Invalid(String),
+}
+
+/// The `s` attribute.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum Style {
+    /// Absent (index 0) or plain decimal digits.
+    Index(i64),
+    /// Anything else, for Ruby's `String#to_i` to read.
+    Other(String),
+}
+
+/// The `t` attribute, as far as `SheetDoc#cell_value_type` tells types apart.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Kind {
+    /// Absent or any other value: the style's number format decides.
+    ByFormat,
+    Shared,
+    Boolean,
+    Str,
+    InlineStr,
+}
+
+/// A byte range of [`RawRow::text`].
+pub type Span = Range<usize>;
+
+/// The value-bearing part of a cell, as `cell_from_xml` sees it.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum Body {
+    /// No `v` child and no `is` child with text.
+    Empty,
+    /// Text of every `t` element inside the first non-empty `is` child.
+    Inline(Span),
+    /// Text content of the first `v` child.
+    Value(Span),
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct RawCell {
+    pub reference: Reference,
+    pub style: Style,
+    pub kind: Kind,
+    pub formula: Option<Span>,
+    pub body: Body,
+}
+
+/// A row's cells. Their text lives in one buffer, so a row costs a few
+/// allocations rather than a few per cell.
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct RawRow {
+    pub text: String,
+    pub cells: Vec<RawCell>,
+}
+
+impl RawRow {
+    pub fn text(&self, span: &Span) -> &str {
+        &self.text[span.clone()]
+    }
+}
+
+/// The input uses XML that this reader does not reproduce exactly the way
+/// Nokogiri does, so the caller falls back to roo's own parser.
+#[derive(Debug, PartialEq, Eq)]
+pub struct Unsupported(pub String);
+
+impl fmt::Display for Unsupported {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(&self.0)
+    }
+}
+
+impl std::error::Error for Unsupported {}
+
+impl From<quick_xml::Error> for Unsupported {
+    fn from(error: quick_xml::Error) -> Self {
+        Unsupported(error.to_string())
+    }
+}
+
+impl From<quick_xml::events::attributes::AttrError> for Unsupported {
+    fn from(error: quick_xml::events::attributes::AttrError) -> Self {
+        Unsupported(error.to_string())
+    }
+}
+
+type Result<T> = std::result::Result<T, Unsupported>;
+
+/// `Roo::Utils.extract_coordinate` for well-formed references. `None` means
+/// roo raises.
+pub fn parse_reference(reference: &str) -> Option<(i64, i64)> {
+    let (mut column, mut row) = (0i64, 0i64);
+    let mut digits = false;
+    for byte in reference.bytes() {
+        match byte {
+            b'A'..=b'Z' | b'a'..=b'z' if !digits => {
+                column = column
+                    .checked_mul(26)?
+                    .checked_add(i64::from(byte & 0x1f))?;
+            }
+            b'0'..=b'9' => {
+                digits = true;
+                row = row.checked_mul(10)?.checked_add(i64::from(byte - b'0'))?;
+            }
+            _ => return None,
+        }
+    }
+    (column != 0 && digits).then_some((row, column))
+}
+
+/// `String#to_i` for plain decimal digits; `None` leaves it to Ruby.
+pub fn parse_index(text: &str) -> Option<usize> {
+    if text.is_empty() || text.len() > 18 || !text.bytes().all(|b| b.is_ascii_digit()) {
+        return None;
+    }
+    text.parse().ok()
+}
+
+pub struct SheetReader<R: BufRead> {
+    xml: quick_xml::Reader<R>,
+    mode: Mode,
+    buf: Vec<u8>,
+    depth: usize,
+    /// Document mode: depth of the open `sheetData` element under the
+    /// `worksheet` root, if any.
+    sheet_data_depth: Option<usize>,
+    root_is_worksheet: bool,
+    done: bool,
+    /// Whether any event was read yet; an XML declaration must come first.
+    started: bool,
+    seen_root: bool,
+    /// Depth of the open elements, for namespace scopes.
+    open_elements: usize,
+    /// Namespace prefixes declared on open elements, with the depth they were
+    /// declared at.
+    prefixes: Vec<(usize, String)>,
+    /// `xml:space` values on open elements (`true` for `preserve`), with the
+    /// depth they were set at.
+    space: Vec<(usize, bool)>,
+    /// Stream mode: whether a row is being read.
+    in_row: bool,
+    /// An error met after some rows of a batch, returned by the next call.
+    pending_error: Option<Unsupported>,
+}
+
+impl SheetReader<BufReader<File>> {
+    pub fn open(path: &Path, mode: Mode) -> Result<Self> {
+        let file = File::open(path).map_err(|e| Unsupported(e.to_string()))?;
+        Ok(Self::new(BufReader::with_capacity(64 * 1024, file), mode))
+    }
+}
+
+#[derive(Clone, Copy)]
+enum Child {
+    Is,
+    F,
+    V,
+    Other,
+}
+
+fn child(e: &BytesStart<'_>) -> Child {
+    match e.local_name().as_ref() {
+        "is" => Child::Is,
+        "f" => Child::F,
+        "v" => Child::V,
+        _ => Child::Other,
+    }
+}
+
+impl<R: BufRead> SheetReader<R> {
+    pub fn new(input: R, mode: Mode) -> Self {
+        let mut xml = quick_xml::Reader::from_reader(input);
+        let config = xml.config_mut();
+        config.check_end_names = true;
+        config.check_comments = true;
+        Self {
+            xml,
+            mode,
+            buf: Vec::with_capacity(16 * 1024),
+            depth: 0,
+            sheet_data_depth: None,
+            root_is_worksheet: false,
+            done: false,
+            started: false,
+            seen_root: false,
+            open_elements: 0,
+            prefixes: Vec::new(),
+            space: Vec::new(),
+            in_row: false,
+            pending_error: None,
+        }
+    }
+
+    /// Reads rows until they hold about `cells` cells (an empty row counts as
+    /// one). An empty vector means the sheet is done. When an error stops a
+    /// batch, the rows before it are returned first and the error on the next
+    /// call.
+    pub fn next_rows(&mut self, cells: usize) -> Result<Vec<RawRow>> {
+        if let Some(error) = self.pending_error.take() {
+            return Err(error);
+        }
+        let mut rows = Vec::new();
+        let mut read = 0;
+        while read < cells {
+            match self.next_row() {
+                Ok(Some(row)) => {
+                    read += row.cells.len().max(1);
+                    rows.push(row);
+                }
+                Ok(None) => break,
+                Err(error) if rows.is_empty() => return Err(error),
+                Err(error) => {
+                    self.pending_error = Some(error);
+                    break;
+                }
+            }
+        }
+        Ok(rows)
+    }
+
+    pub fn next_row(&mut self) -> Result<Option<RawRow>> {
+        let mut buf = std::mem::take(&mut self.buf);
+        let row = self.find_row(&mut buf);
+        self.buf = buf;
+        row
+    }
+
+    fn find_row(&mut self, buf: &mut Vec<u8>) -> Result<Option<RawRow>> {
+        if self.done {
+            return Ok(None);
+        }
+        loop {
+            buf.clear();
+            let event = self.read_event(buf)?;
+            if self.depth == 0 {
+                self.check_top_level(&event)?;
+            }
+            match event {
+                Event::Start(e) => {
+                    self.depth += 1;
+                    if self.is_row(&e) {
+                        self.in_row = true;
+                        let row = self.read_row(buf);
+                        self.in_row = false;
+                        self.depth -= 1;
+                        return row.map(Some);
+                    }
+                    self.enter(&e);
+                }
+                Event::Empty(e) => {
+                    self.depth += 1;
+                    let is_row = self.is_row(&e);
+                    self.depth -= 1;
+                    if is_row {
+                        return Ok(Some(RawRow::default()));
+                    }
+                }
+                Event::End(_) => {
+                    if self.sheet_data_depth == Some(self.depth) {
+                        self.sheet_data_depth = None;
+                    }
+                    self.depth -= 1;
+                }
+                Event::Decl(decl) => check_encoding(&decl)?,
+                Event::Eof if self.depth != 0 => {
+                    return Err(Unsupported("unexpected end of the sheet".into()));
+                }
+                Event::Eof => {
+                    self.done = true;
+                    return Ok(None);
+                }
+                _ => {}
+            }
+        }
+    }
+
+    /// An element name and its attributes, as far as quick-xml leaves them
+    /// unchecked: names and their namespace prefixes, whitespace between
+    /// attributes, `<` in values, and the references in values.
+    fn check_start(&mut self, e: &BytesStart<'_>) -> Result<()> {
+        let name = e.name();
+        check_name(name.as_ref())?;
+        let raw = e.attributes_raw();
+        check_chars(raw)?;
+        let mut quote = None;
+        let mut after_value = false;
+        let mut name_start = true;
+        for &b in raw.as_bytes() {
+            match quote {
+                Some(q) if b == q => {
+                    quote = None;
+                    after_value = true;
+                }
+                Some(_) if b == b'<' => {
+                    return Err(Unsupported("`<` in an attribute value".into()))
+                }
+                Some(_) => {}
+                None if b.is_ascii_whitespace() => {
+                    after_value = false;
+                    name_start = true;
+                }
+                None if after_value && b != b'/' => {
+                    return Err(Unsupported(
+                        "attributes without whitespace between them".into(),
+                    ));
+                }
+                None => match b {
+                    b'"' | b'\'' => quote = Some(b),
+                    b'=' | b'/' => name_start = true,
+                    b if b.is_ascii_alphabetic() || b == b'_' || b == b':' => name_start = false,
+                    b'0'..=b'9' | b'-' | b'.' if !name_start => {}
+                    _ => return Err(Unsupported("an invalid attribute name".into())),
+                },
+            }
+        }
+        if self.mode == Mode::Stream && self.in_row {
+            // roo's streaming reader yields a nested `row` as a row of its own,
+            // and matches prefixed names in a row by namespace.
+            if name.as_ref() == "row" || name.as_ref().contains(':') {
+                return Err(Unsupported(format!(
+                    "<{}> inside a streamed row",
+                    name.as_ref()
+                )));
+            }
+        }
+        let depth = self.open_elements + 1;
+        // quick-xml reports duplicated attributes only while iterating.
+        for attribute in e.attributes() {
+            let attribute = attribute?;
+            let key = attribute.key.as_ref();
+            if key.contains(':') {
+                check_name(key)?;
+            }
+            if attribute.value.contains('&') {
+                check_chars(&attribute.normalized_value(XmlVersion::Implicit1_0)?)?;
+            }
+            if let Some(prefix) = key.strip_prefix("xmlns:") {
+                if attribute.value.is_empty() {
+                    return Err(Unsupported(format!("an empty namespace for {prefix}")));
+                }
+                self.prefixes.push((depth, prefix.to_owned()));
+            }
+            if key == "xml:space" {
+                self.space
+                    .push((depth, attribute.value.as_ref() == "preserve"));
+            }
+        }
+        if raw.contains(':') {
+            for attribute in e.attributes() {
+                let key = attribute?.key;
+                self.check_prefix(key.as_ref())?;
+            }
+        }
+        self.check_prefix(name.as_ref())
+    }
+
+    /// Ends the namespace and `xml:space` scopes of an element at `depth`.
+    fn leave(&mut self, depth: usize) {
+        self.prefixes.retain(|(declared, _)| *declared != depth);
+        self.space.retain(|(declared, _)| *declared != depth);
+    }
+
+    fn preserves_space(&self) -> bool {
+        self.space.last().is_some_and(|(_, preserve)| *preserve)
+    }
+
+    /// libxml2 keeps an undeclared prefix as part of the name, so roo would
+    /// not see `x:row` as `row`.
+    fn check_prefix(&self, name: &str) -> Result<()> {
+        match name.split_once(':') {
+            Some(("xml" | "xmlns", _)) | None => Ok(()),
+            Some((prefix, _)) if self.prefixes.iter().any(|(_, declared)| declared == prefix) => {
+                Ok(())
+            }
+            Some(_) => Err(Unsupported(format!("the undeclared prefix in {name}"))),
+        }
+    }
+
+    /// Outside the root element, XML allows only one root, whitespace,
+    /// comments, and processing instructions.
+    fn check_top_level(&mut self, event: &Event<'_>) -> Result<()> {
+        match event {
+            Event::Start(_) | Event::Empty(_) if self.seen_root => {
+                Err(Unsupported("a second root element".into()))
+            }
+            Event::Start(_) | Event::Empty(_) => {
+                self.seen_root = true;
+                Ok(())
+            }
+            Event::Text(t) if !t.trim_ascii().is_empty() => {
+                Err(Unsupported("text outside the root element".into()))
+            }
+            Event::CData(_) | Event::GeneralRef(_) => {
+                Err(Unsupported("text outside the root element".into()))
+            }
+            Event::Eof if !self.seen_root => Err(Unsupported("no root element".into())),
+            _ => Ok(()),
+        }
+    }
+
+    /// The next event, rejecting characters XML does not allow, which
+    /// Nokogiri does not accept and quick-xml does not check.
+    fn read_event<'b>(&mut self, buf: &'b mut Vec<u8>) -> Result<Event<'b>> {
+        let event = self.xml.read_event_into(buf)?;
+        let first = !std::mem::replace(&mut self.started, true);
+        match &event {
+            Event::Start(e) => {
+                self.check_start(e)?;
+                self.open_elements += 1;
+            }
+            Event::Empty(e) => {
+                self.check_start(e)?;
+                self.leave(self.open_elements + 1);
+            }
+            Event::End(_) => {
+                self.leave(self.open_elements);
+                self.open_elements = self.open_elements.saturating_sub(1);
+            }
+            Event::Text(t) if t.contains("]]>") => {
+                return Err(Unsupported("`]]>` in text".into()));
+            }
+            Event::Text(t) | Event::Comment(t) => check_chars(t)?,
+            Event::CData(t) => check_chars(&t.xml10_content())?,
+            Event::PI(pi) => {
+                check_name(pi.target())?;
+                check_chars(pi)?;
+            }
+            Event::GeneralRef(r) => match r.resolve_char_ref()? {
+                Some(c) => check_chars(c.encode_utf8(&mut [0; 4]))?,
+                None => {
+                    if !matches!(
+                        r.xml10_content().as_ref(),
+                        "lt" | "gt" | "amp" | "apos" | "quot"
+                    ) {
+                        return Err(Unsupported(
+                            "an entity reference XML does not define".into(),
+                        ));
+                    }
+                }
+            },
+            Event::Decl(_) if !first => {
+                return Err(Unsupported("an XML declaration after the start".into()));
+            }
+            // A DTD can define entities and attribute defaults, which Nokogiri
+            // applies and this reader does not.
+            Event::DocType(_) => return Err(Unsupported("a document type declaration".into())),
+            _ => {}
+        }
+        Ok(event)
+    }
+
+    /// Tracks the `/worksheet/sheetData` path for document mode. `self.depth`
+    /// is already the depth of `e`.
+    fn enter(&mut self, e: &BytesStart<'_>) {
+        if self.mode != Mode::Document {
+            return;
+        }
+        let name = e.local_name();
+        if self.depth == 1 {
+            self.root_is_worksheet = name.as_ref() == "worksheet";
+        } else if self.depth == 2 && self.root_is_worksheet && name.as_ref() == "sheetData" {
+            self.sheet_data_depth = Some(2);
+        }
+    }
+
+    /// `self.depth` is already the depth of `e`.
+    fn is_row(&self, e: &BytesStart<'_>) -> bool {
+        match self.mode {
+            Mode::Document => {
+                self.sheet_data_depth == Some(self.depth - 1) && e.local_name().as_ref() == "row"
+            }
+            Mode::Stream => e.name().as_ref() == "row",
+        }
+    }
+
+    fn is_cell(&self, e: &BytesStart<'_>) -> bool {
+        match self.mode {
+            Mode::Document => e.local_name().as_ref() == "c",
+            Mode::Stream => true,
+        }
+    }
+
+    /// Reads the children of an open `row` up to its end tag.
+    fn read_row(&mut self, buf: &mut Vec<u8>) -> Result<RawRow> {
+        let mut row = RawRow::default();
+        loop {
+            buf.clear();
+            match self.read_event(buf)? {
+                Event::Start(e) => {
+                    if self.is_cell(&e) {
+                        let cell = cell_attributes(&e, self.mode)?;
+                        self.read_cell(buf, &mut row, cell)?;
+                    } else {
+                        self.skip(buf)?;
+                    }
+                }
+                Event::Empty(e) => {
+                    if self.is_cell(&e) {
+                        row.cells.push(cell_attributes(&e, self.mode)?);
+                    }
+                }
+                Event::End(_) => return Ok(row),
+                Event::Eof => return Err(Unsupported("unexpected end of row".into())),
+                // roo's streaming takes every child node of a row as a cell and
+                // fails on one that is not an element.
+                Event::Text(t)
+                    if self.mode == Mode::Stream
+                        && (self.preserves_space() || !t.trim_ascii().is_empty()) =>
+                {
+                    return Err(Unsupported("text in a streamed row".into()));
+                }
+                Event::Comment(_) | Event::PI(_) | Event::CData(_) | Event::GeneralRef(_)
+                    if self.mode == Mode::Stream =>
+                {
+                    return Err(Unsupported("a non-element child of a streamed row".into()));
+                }
+                _ => {}
+            }
+        }
+    }
+
+    /// Reads the children of an open cell up to its end tag.
+    fn read_cell(&mut self, buf: &mut Vec<u8>, row: &mut RawRow, mut cell: RawCell) -> Result<()> {
+        let mut decided = false;
+        loop {
+            buf.clear();
+            let (child, empty) = match self.read_event(buf)? {
+                Event::Start(e) => (child(&e), false),
+                Event::Empty(e) => (child(&e), true),
+                Event::End(_) => break,
+                Event::Eof => return Err(Unsupported("unexpected end of cell".into())),
+                _ => continue,
+            };
+            if decided {
+                if !empty {
+                    self.skip(buf)?;
+                }
+                continue;
+            }
+            let start = row.text.len();
+            match (child, empty) {
+                (Child::Is, false) => {
+                    self.text_of_t_descendants(buf, &mut row.text)?;
+                    if row.text.len() > start {
+                        cell.body = Body::Inline(start..row.text.len());
+                        decided = true;
+                    }
+                }
+                (Child::F, false) => {
+                    self.text_content(buf, &mut row.text)?;
+                    cell.formula = Some(start..row.text.len());
+                }
+                (Child::F, true) => cell.formula = Some(start..start),
+                (Child::V, false) => {
+                    self.text_content(buf, &mut row.text)?;
+                    cell.body = Body::Value(start..row.text.len());
+                    decided = true;
+                }
+                (Child::V, true) => {
+                    cell.body = Body::Value(start..start);
+                    decided = true;
+                }
+                (_, false) => self.skip(buf)?,
+                (_, true) => {}
+            }
+        }
+        if !decided {
+            cell.formula = None;
+        }
+        row.cells.push(cell);
+        Ok(())
+    }
+
+    /// Nokogiri's `Node#content` of an open element: every text and CDATA
+    /// descendant, with references resolved.
+    fn text_content(&mut self, buf: &mut Vec<u8>, out: &mut String) -> Result<()> {
+        let mut depth = 0usize;
+        loop {
+            buf.clear();
+            match self.read_event(buf)? {
+                Event::Start(_) => depth += 1,
+                Event::End(_) if depth == 0 => return Ok(()),
+                Event::End(_) => depth -= 1,
+                Event::Text(t) => out.push_str(&t.xml10_content()),
+                Event::CData(t) => out.push_str(&t.xml10_content()),
+                Event::GeneralRef(r) => push_reference(out, &r)?,
+                Event::Eof => return Err(Unsupported("unexpected end of element".into())),
+                _ => {}
+            }
+        }
+    }
+
+    /// `is_element.search("t").map(&:content).join` for an open `is`.
+    fn text_of_t_descendants(&mut self, buf: &mut Vec<u8>, out: &mut String) -> Result<()> {
+        let mut depth = 0usize;
+        let mut t_depth: Option<usize> = None;
+        loop {
+            buf.clear();
+            match self.read_event(buf)? {
+                Event::Start(e) => {
+                    depth += 1;
+                    if e.local_name().as_ref() == "t" {
+                        if t_depth.is_some() {
+                            // roo joins the text of every `t`, the nested one twice.
+                            return Err(Unsupported("a `t` inside a `t`".into()));
+                        }
+                        t_depth = Some(depth);
+                    }
+                }
+                Event::End(_) if depth == 0 => return Ok(()),
+                Event::End(_) => {
+                    if t_depth == Some(depth) {
+                        t_depth = None;
+                    }
+                    depth -= 1;
+                }
+                Event::Text(t) if t_depth.is_some() => out.push_str(&t.xml10_content()),
+                Event::CData(t) if t_depth.is_some() => out.push_str(&t.xml10_content()),
+                Event::GeneralRef(r) if t_depth.is_some() => push_reference(out, &r)?,
+                Event::Eof => return Err(Unsupported("unexpected end of element".into())),
+                _ => {}
+            }
+        }
+    }
+
+    /// Skips the rest of an open element.
+    fn skip(&mut self, buf: &mut Vec<u8>) -> Result<()> {
+        let mut depth = 0usize;
+        loop {
+            buf.clear();
+            match self.read_event(buf)? {
+                Event::Start(_) => depth += 1,
+                Event::End(_) if depth == 0 => return Ok(()),
+                Event::End(_) => depth -= 1,
+                Event::Eof => return Err(Unsupported("unexpected end of element".into())),
+                _ => {}
+            }
+        }
+    }
+}
+
+fn cell_attributes(e: &BytesStart<'_>, mode: Mode) -> Result<RawCell> {
+    let mut cell = RawCell {
+        reference: Reference::Missing,
+        style: Style::Index(0),
+        kind: Kind::ByFormat,
+        formula: None,
+        body: Body::Empty,
+    };
+    for attribute in e.attributes() {
+        let attribute = attribute?;
+        let value = || attribute.normalized_value(XmlVersion::Implicit1_0);
+        match attribute.key.as_ref() {
+            "r" => {
+                let value = value()?;
+                cell.reference = match parse_reference(&value) {
+                    Some((row, column)) => Reference::At { row, column },
+                    None => Reference::Invalid(value.into_owned()),
+                };
+            }
+            "s" => {
+                let value = value()?;
+                cell.style = match parse_index(&value).filter(|i| *i < 1 << 30) {
+                    Some(index) => Style::Index(index as i64),
+                    None => Style::Other(value.into_owned()),
+                };
+            }
+            "t" => {
+                cell.kind = match value()?.as_ref() {
+                    "s" => Kind::Shared,
+                    "b" => Kind::Boolean,
+                    "str" => Kind::Str,
+                    "inlineStr" => Kind::InlineStr,
+                    _ => Kind::ByFormat,
+                };
+            }
+            // roo's document read removes namespaces first, so `x:t` would
+            // count as `t` there.
+            key if mode == Mode::Document
+                && key.split_once(':').is_some_and(|(prefix, local)| {
+                    prefix != "xmlns" && matches!(local, "r" | "s" | "t")
+                }) =>
+            {
+                return Err(Unsupported(format!("the attribute {key} on a cell")));
+            }
+            _ => {}
+        }
+    }
+    Ok(cell)
+}
+
+/// XML 1.0 `Char`: tab, line feed, carriage return, and U+0020 up, except
+/// U+FFFE and U+FFFF (Rust strings hold no surrogates).
+fn check_chars(text: &str) -> Result<()> {
+    let control = text
+        .bytes()
+        .any(|b| b < 0x20 && !matches!(b, b'\t' | b'\n' | b'\r'));
+    if control || text.contains(['\u{FFFE}', '\u{FFFF}']) {
+        return Err(Unsupported("a character XML does not allow".into()));
+    }
+    Ok(())
+}
+
+/// An ASCII XML name: a letter or `_` first, then those, digits, `-`, and
+/// `.`, with at most one `:` between two non-empty parts. Non-ASCII names are
+/// valid XML but never appear in worksheets, so they are left to roo rather
+/// than checked character by character.
+fn check_name(name: &str) -> Result<()> {
+    let part = |part: &str| {
+        part.bytes().enumerate().all(|(i, b)| {
+            b.is_ascii_alphabetic()
+                || b == b'_'
+                || (i > 0 && (b.is_ascii_digit() || b == b'-' || b == b'.'))
+        }) && !part.is_empty()
+    };
+    let valid = match name.split_once(':') {
+        Some((prefix, local)) => part(prefix) && part(local),
+        None => part(name),
+    };
+    if valid {
+        Ok(())
+    } else {
+        Err(Unsupported(format!("the name {name:?}")))
+    }
+}
+
+fn push_reference(text: &mut String, reference: &BytesRef<'_>) -> Result<()> {
+    if reference.is_char_ref() {
+        match reference.resolve_char_ref()? {
+            Some(c) => text.push(c),
+            None => return Err(Unsupported("invalid character reference".into())),
+        }
+        return Ok(());
+    }
+    let resolved = match reference.xml10_content().as_ref() {
+        "lt" => '<',
+        "gt" => '>',
+        "amp" => '&',
+        "apos" => '\'',
+        "quot" => '"',
+        other => return Err(Unsupported(format!("entity reference &{other};"))),
+    };
+    text.push(resolved);
+    Ok(())
+}
+
+fn check_encoding(decl: &quick_xml::events::BytesDecl<'_>) -> Result<()> {
+    if let Some(encoding) = decl.encoding() {
+        let encoding = encoding?;
+        if !encoding.eq_ignore_ascii_case("utf-8") {
+            return Err(Unsupported(format!("XML encoding {encoding}")));
+        }
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const NS: &str = r#"xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main""#;
+
+    fn rows(xml: &str, mode: Mode) -> Vec<RawRow> {
+        let mut reader = SheetReader::new(xml.as_bytes(), mode);
+        let mut out = Vec::new();
+        while let Some(row) = reader.next_row().unwrap() {
+            out.push(row);
+        }
+        out
+    }
+
+    /// `(reference, formula, body)` of every cell, with text resolved.
+    fn texts(row: &RawRow) -> Vec<(Reference, Option<&str>, Option<&str>)> {
+        row.cells
+            .iter()
+            .map(|c| {
+                let body = match &c.body {
+                    Body::Empty => None,
+                    Body::Inline(s) | Body::Value(s) => Some(row.text(s)),
+                };
+                (
+                    c.reference.clone(),
+                    c.formula.as_ref().map(|s| row.text(s)),
+                    body,
+                )
+            })
+            .collect()
+    }
+
+    fn at(row: i64, column: i64) -> Reference {
+        Reference::At { row, column }
+    }
+
+    #[test]
+    fn reads_values_formulas_and_inline_strings() {
+        let xml = format!(
+            r#"<?xml version="1.0" encoding="UTF-8"?><worksheet {NS}><sheetData>
+            <row r="1"><c r="A1" s="2" t="n"><f>B1+1</f><v>1.0</v></c><c r="B1" t="inlineStr"><is><r><t>a</t></r><rPh><t>b</t></rPh></is></c></row>
+            </sheetData></worksheet>"#
+        );
+        let got = rows(&xml, Mode::Document);
+        assert_eq!(got.len(), 1);
+        assert_eq!(got[0].cells[0].style, Style::Index(2));
+        assert_eq!(got[0].cells[0].kind, Kind::ByFormat);
+        assert_eq!(got[0].cells[1].kind, Kind::InlineStr);
+        assert!(matches!(got[0].cells[1].body, Body::Inline(_)));
+        assert_eq!(
+            texts(&got[0]),
+            vec![
+                (at(1, 1), Some("B1+1"), Some("1.0")),
+                (at(1, 2), None, Some("ab"))
+            ]
+        );
+    }
+
+    #[test]
+    fn keeps_attributes_ruby_has_to_read() {
+        let xml = format!(
+            r#"<worksheet {NS}><sheetData><row><c r="1A" s=" 3" t="e"/><c/></row></sheetData></worksheet>"#
+        );
+        let got = rows(&xml, Mode::Document);
+        let cells = &got[0].cells;
+        assert_eq!(cells[0].reference, Reference::Invalid("1A".into()));
+        assert_eq!(cells[0].style, Style::Other(" 3".into()));
+        assert_eq!(cells[0].kind, Kind::ByFormat);
+        assert_eq!(cells[1].reference, Reference::Missing);
+        assert_eq!(cells[1].style, Style::Index(0));
+    }
+
+    #[test]
+    fn resolves_references_and_normalizes_line_ends() {
+        let xml = format!(
+            "<worksheet {NS}><sheetData><row><c r=\"A1\" t=\"str\"><v>a&amp;b&#13;\r\nc<![CDATA[<d>]]></v></c></row></sheetData></worksheet>"
+        );
+        let got = rows(&xml, Mode::Document);
+        assert_eq!(texts(&got[0])[0].2, Some("a&b\r\nc<d>"));
+    }
+
+    #[test]
+    fn first_value_wins_and_formula_after_it_is_ignored() {
+        let xml = format!(
+            "<worksheet {NS}><sheetData><row><c r=\"A1\"><v>1</v><f>X</f><v>2</v></c><c r=\"B1\"><f>Y</f></c></row></sheetData></worksheet>"
+        );
+        let got = rows(&xml, Mode::Document);
+        assert_eq!(
+            texts(&got[0]),
+            vec![(at(1, 1), None, Some("1")), (at(1, 2), None, None)]
+        );
+    }
+
+    #[test]
+    fn empty_inline_string_does_not_decide_the_value() {
+        let xml = format!(
+            "<worksheet {NS}><sheetData><row><c r=\"A1\" t=\"inlineStr\"><is><t></t></is><v>7</v></c></row></sheetData></worksheet>"
+        );
+        let got = rows(&xml, Mode::Document);
+        assert!(matches!(got[0].cells[0].body, Body::Value(_)));
+        assert_eq!(texts(&got[0])[0].2, Some("7"));
+    }
+
+    #[test]
+    fn document_mode_reads_only_sheet_data_rows_and_c_children() {
+        let xml = format!(
+            "<worksheet {NS}><sheetPr><row/></sheetPr><sheetData><row r=\"1\"/><row r=\"2\"><x>1</x><c r=\"A2\"/></row></sheetData></worksheet>"
+        );
+        let got = rows(&xml, Mode::Document);
+        assert_eq!(got.len(), 2);
+        assert!(got[0].cells.is_empty());
+        assert_eq!(texts(&got[1]), vec![(at(2, 1), None, None)]);
+    }
+
+    #[test]
+    fn document_mode_matches_prefixed_names_by_local_name() {
+        let xml = r#"<x:worksheet xmlns:x="urn:x"><x:sheetData><x:row><x:c r="A1"><x:v>3</x:v></x:c></x:row></x:sheetData></x:worksheet>"#;
+        let got = rows(xml, Mode::Document);
+        assert_eq!(texts(&got[0])[0].2, Some("3"));
+    }
+
+    #[test]
+    fn stream_mode_needs_an_unprefixed_row_and_takes_every_child_element() {
+        let prefixed = r#"<x:worksheet xmlns:x="urn:x"><x:sheetData><x:row><x:c r="A1"/></x:row></x:sheetData></x:worksheet>"#;
+        assert!(rows(prefixed, Mode::Stream).is_empty());
+
+        let xml = format!(
+            "<worksheet {NS}><sheetData><row><c r=\"A1\"/><extra r=\"B1\"><v>1</v></extra></row></sheetData></worksheet>"
+        );
+        let got = rows(&xml, Mode::Stream);
+        assert_eq!(
+            texts(&got[0]),
+            vec![(at(1, 1), None, None), (at(1, 2), None, Some("1"))]
+        );
+    }
+
+    #[test]
+    fn rejects_inputs_it_cannot_reproduce() {
+        let latin1 = r#"<?xml version="1.0" encoding="ISO-8859-1"?><worksheet/>"#;
+        assert!(SheetReader::new(latin1.as_bytes(), Mode::Document)
+            .next_row()
+            .is_err());
+        for body in [
+            "<v>&custom;</v>",
+            "<v>a&#1;b</v>",
+            "<v>a\u{1}b</v>",
+            "<v>\u{FFFE}</v>",
+        ] {
+            let xml = format!(
+                "<worksheet {NS}><sheetData><row><c>{body}</c></row></sheetData></worksheet>"
+            );
+            assert!(
+                SheetReader::new(xml.as_bytes(), Mode::Document)
+                    .next_row()
+                    .is_err(),
+                "{body:?}"
+            );
+        }
+        let attribute = format!(
+            r#"<worksheet {NS}><sheetData><row><c r="A&#2;1"/></row></sheetData></worksheet>"#
+        );
+        assert!(SheetReader::new(attribute.as_bytes(), Mode::Document)
+            .next_row()
+            .is_err());
+        let truncated = format!("<worksheet {NS}><sheetData><row><c><v>1</v></c></row>");
+        let mut reader = SheetReader::new(truncated.as_bytes(), Mode::Document);
+        assert!(reader.next_row().unwrap().is_some());
+        assert!(
+            reader.next_row().is_err(),
+            "a sheet that ends with open elements"
+        );
+    }
+
+    #[test]
+    fn rejects_xml_that_is_not_well_formed() {
+        let rows = r#"<sheetData><row r="1"><c r="A1"><v>1</v></c></row></sheetData>"#;
+        for (label, xml) in [
+            (
+                "unquoted value",
+                "<worksheet><sheetData><row r=1/></sheetData></worksheet>".to_string(),
+            ),
+            (
+                "no space between attributes",
+                r#"<worksheet><sheetData><row r="1"s="2"/></sheetData></worksheet>"#.to_string(),
+            ),
+            (
+                "`<` in a value",
+                format!(r#"<worksheet x="a<b">{rows}</worksheet>"#),
+            ),
+            (
+                "unknown entity in a value",
+                format!(r#"<worksheet x="&bogus;">{rows}</worksheet>"#),
+            ),
+            (
+                "bare `&` in a value",
+                format!(r#"<worksheet x="a & b">{rows}</worksheet>"#),
+            ),
+            (
+                "`]]>` in text",
+                format!("<worksheet>{rows}a ]]> b</worksheet>"),
+            ),
+            (
+                "second root",
+                format!("<worksheet>{rows}</worksheet><worksheet/>"),
+            ),
+            (
+                "text before the root",
+                format!("x<worksheet>{rows}</worksheet>"),
+            ),
+            (
+                "doctype",
+                format!("<!DOCTYPE worksheet><worksheet>{rows}</worksheet>"),
+            ),
+            (
+                "illegal character in a PI",
+                format!("<?pi \u{1}?><worksheet>{rows}</worksheet>"),
+            ),
+            (
+                "`--` in a comment",
+                format!("<!-- a -- b --><worksheet>{rows}</worksheet>"),
+            ),
+            (
+                "invalid name",
+                format!("<worksheet><1x/>{rows}</worksheet>"),
+            ),
+            (
+                "late declaration",
+                format!(r#"<!-- c --><?xml version="1.0"?><worksheet>{rows}</worksheet>"#),
+            ),
+            ("empty document", String::new()),
+            ("PI in a value", "<worksheet><sheetData><row><c><v>1<? x?></v></c></row></sheetData></worksheet>".to_string()),
+            ("non-ASCII attribute name", "<worksheet><sheetData><row><c \u{d7}=\"1\"/></row></sheetData></worksheet>".to_string()),
+            ("non-ASCII element name", "<worksheet><sheetData><row><c><v>1<\u{d7}/>2</v></c></row></sheetData></worksheet>".to_string()),
+            ("undeclared element prefix", format!("<worksheet><sheetData><x:row>{rows}</x:row></sheetData></worksheet>")),
+            ("empty prefix", "<worksheet><sheetData><:row/></sheetData></worksheet>".to_string()),
+            ("undeclared value prefix", "<worksheet><sheetData><row><c><x:v>1</x:v><v>9</v></c></row></sheetData></worksheet>".to_string()),
+        ] {
+            for mode in [Mode::Document, Mode::Stream] {
+                let mut reader = SheetReader::new(xml.as_bytes(), mode);
+                let read: Result<Vec<RawRow>> =
+                    std::iter::from_fn(|| reader.next_row().transpose()).collect();
+                assert!(read.is_err(), "{label} ({mode:?})");
+            }
+        }
+        for (label, xml) in [
+            (
+                "prefixed r",
+                r#"<worksheet xmlns:x="urn:x"><sheetData><row><c x:r="B9" r="A1"><v>1</v></c></row></sheetData></worksheet>"#,
+            ),
+            (
+                "prefixed t",
+                r#"<worksheet xmlns:x="urn:x"><sheetData><row><c r="A1" x:t="str"><v>1</v></c></row></sheetData></worksheet>"#,
+            ),
+        ] {
+            assert!(
+                SheetReader::new(xml.as_bytes(), Mode::Document)
+                    .next_rows(9)
+                    .is_err(),
+                "{label}"
+            );
+            assert!(
+                SheetReader::new(xml.as_bytes(), Mode::Stream)
+                    .next_rows(9)
+                    .is_ok(),
+                "{label} streams"
+            );
+        }
+        for (label, xml) in [
+            (
+                "comment in a row",
+                "<worksheet><sheetData><row><!-- c --><c r=\"A1\"/></row></sheetData></worksheet>",
+            ),
+            (
+                "text in a row",
+                "<worksheet><sheetData><row>x<c r=\"A1\"/></row></sheetData></worksheet>",
+            ),
+        ] {
+            assert!(
+                SheetReader::new(xml.as_bytes(), Mode::Stream)
+                    .next_rows(9)
+                    .is_err(),
+                "{label}"
+            );
+            assert!(
+                SheetReader::new(xml.as_bytes(), Mode::Document)
+                    .next_rows(9)
+                    .is_ok(),
+                "{label} in a document"
+            );
+        }
+        for (label, xml) in [
+            ("nested t", "<worksheet><sheetData><row><c t=\"inlineStr\"><is><t>a<t>b</t>c</t></is></c></row></sheetData></worksheet>"),
+            ("empty prefix namespace", "<worksheet><sheetData><row r=\"1\" xmlns:x=\"\"><x:c r=\"A1\"><v>1</v></x:c></row></sheetData></worksheet>"),
+            ("duplicated attribute", "<worksheet><sheetData><row r=\"1\" r=\"2\"><c r=\"A1\"><v>1</v></c></row></sheetData></worksheet>"),
+            ("unknown entity in skipped content", "<worksheet><sheetData><row><c r=\"A1\"><v>1</v></c></row></sheetData><ext>&bogus;</ext></worksheet>"),
+        ] {
+            for mode in [Mode::Document, Mode::Stream] {
+                let mut reader = SheetReader::new(xml.as_bytes(), mode);
+                let read: Result<Vec<RawRow>> = std::iter::from_fn(|| reader.next_row().transpose()).collect();
+                assert!(read.is_err(), "{label} ({mode:?})");
+            }
+        }
+        for (label, xml) in [
+            ("nested row", "<worksheet><sheetData><row r=\"1\"><c r=\"A1\"><ext><row r=\"2\"/></ext></c></row></sheetData></worksheet>"),
+            ("prefixed t in a streamed row", "<worksheet><sheetData><row><c t=\"inlineStr\"><is><x:t xmlns:x=\"urn:other\">hi</x:t></is></c></row></sheetData></worksheet>"),
+            ("preserved whitespace in a row", "<worksheet><sheetData><row r=\"1\" xml:space=\"preserve\"> <c r=\"A1\"/> </row></sheetData></worksheet>"),
+        ] {
+            assert!(SheetReader::new(xml.as_bytes(), Mode::Stream).next_rows(9).is_err(), "{label}");
+            assert!(SheetReader::new(xml.as_bytes(), Mode::Document).next_rows(9).is_ok(), "{label} in a document");
+        }
+        let declared = r#"<x:worksheet xmlns:x="urn:x"><x:sheetData><x:row><x:c r="A1"><x:v>3</x:v></x:c></x:row></x:sheetData></x:worksheet>"#;
+        assert_eq!(
+            SheetReader::new(declared.as_bytes(), Mode::Document)
+                .next_rows(9)
+                .unwrap()
+                .len(),
+            1
+        );
+        let scoped =
+            r#"<worksheet><a xmlns:x="urn:x"/><sheetData><x:row/></sheetData></worksheet>"#;
+        assert!(
+            SheetReader::new(scoped.as_bytes(), Mode::Document)
+                .next_rows(9)
+                .is_err(),
+            "a prefix out of scope"
+        );
+        let fine = format!(
+            r#"<?xml version="1.0"?>
+<!-- c --><?pi ok?><worksheet x="a &amp; b" y='1'>{rows}</worksheet>
+"#
+        );
+        let mut reader = SheetReader::new(fine.as_bytes(), Mode::Document);
+        assert_eq!(reader.next_rows(10).unwrap().len(), 1);
+    }
+
+    #[test]
+    fn returns_the_rows_before_an_error_first() {
+        let xml = format!(
+            "<worksheet {NS}><sheetData><row/><row><c><v>&x;</v></c></row></sheetData></worksheet>"
+        );
+        let mut reader = SheetReader::new(xml.as_bytes(), Mode::Document);
+        assert_eq!(reader.next_rows(5).unwrap().len(), 1);
+        assert!(reader.next_rows(5).is_err());
+    }
+
+    #[test]
+    fn batches_rows() {
+        let xml = format!("<worksheet {NS}><sheetData><row/><row/><row/></sheetData></worksheet>");
+        let mut reader = SheetReader::new(xml.as_bytes(), Mode::Document);
+        assert_eq!(reader.next_rows(2).unwrap().len(), 2);
+        assert_eq!(reader.next_rows(2).unwrap().len(), 1);
+        assert!(reader.next_rows(2).unwrap().is_empty());
+
+        let xml = format!(
+            "<worksheet {NS}><sheetData><row><c/><c/><c/></row><row><c/></row></sheetData></worksheet>"
+        );
+        let mut reader = SheetReader::new(xml.as_bytes(), Mode::Document);
+        assert_eq!(
+            reader.next_rows(2).unwrap().len(),
+            1,
+            "a batch ends once it holds enough cells"
+        );
+    }
+
+    #[test]
+    fn parses_references_like_roo() {
+        assert_eq!(parse_reference("A1"), Some((1, 1)));
+        assert_eq!(parse_reference("aa10"), Some((10, 27)));
+        assert_eq!(parse_reference("XFD1048576"), Some((1048576, 16384)));
+        assert_eq!(parse_reference("1A"), None);
+        assert_eq!(parse_reference("A"), None);
+        assert_eq!(parse_reference("A1B"), None);
+        assert_eq!(parse_reference("$A$1"), None);
+    }
+
+    #[test]
+    fn parses_only_plain_indexes() {
+        assert_eq!(parse_index("12"), Some(12));
+        assert_eq!(parse_index("007"), Some(7));
+        assert_eq!(parse_index(""), None);
+        assert_eq!(parse_index("+1"), None);
+        assert_eq!(parse_index(" 1"), None);
+    }
+}