imprimatur 0.1.0

data/ext/imprimatur_native/core/src/test_support.rs

@@ -0,0 +1,163 @@
+//! Helpers shared by the unit tests.
+
+use std::io::{Cursor, Read};
+
+/// Every entry of a zip archive as `(name, bytes)`, read with the `zip`
+/// crate: an implementation independent of ours, which verifies each CRC.
+pub fn read_zip(bytes: Vec<u8>) -> Vec<(String, Vec<u8>)> {
+    let mut archive = ::zip::ZipArchive::new(Cursor::new(bytes)).unwrap();
+    (0..archive.len())
+        .map(|index| {
+            let mut file = archive.by_index(index).unwrap();
+            let mut data = Vec::new();
+            file.read_to_end(&mut data).unwrap();
+            (file.name().unwrap().into_owned(), data)
+        })
+        .collect()
+}
+
+/// Every entry of a zip archive as text, by name, read as [`read_zip`] does.
+pub fn text_parts(bytes: Vec<u8>) -> Vec<(String, String)> {
+    read_zip(bytes)
+        .into_iter()
+        .map(|(name, data)| (name, String::from_utf8(data).unwrap()))
+        .collect()
+}
+
+/// The text of the part `name` among `parts`.
+pub fn part<'a>(parts: &'a [(String, String)], name: &str) -> &'a str {
+    parts
+        .iter()
+        .find(|(part, _)| part == name)
+        .map_or_else(|| panic!("no part {name}"), |(_, xml)| xml)
+}
+
+/// A zip of `(name, text)` parts, written with our own writer.
+pub fn zip_of(parts: &[(&str, &str)]) -> Vec<u8> {
+    let mut zip = crate::zip::ZipWriter::new(Vec::new());
+    for (name, text) in parts {
+        zip.add(name, text.as_bytes()).unwrap();
+    }
+    zip.finish().unwrap()
+}
+
+/// A PDF of `objects`, numbered from 1 (the first is the catalog), with a
+/// classic cross-reference table.
+pub fn pdf_of(objects: &[Vec<u8>]) -> Vec<u8> {
+    use std::io::Write as _;
+    let mut out = b"%PDF-1.7\n%\xE2\xE3\xCF\xD3\n".to_vec();
+    let mut offsets = Vec::new();
+    for (number, body) in (1..).zip(objects) {
+        offsets.push(out.len());
+        writeln!(out, "{number} 0 obj").unwrap();
+        out.extend_from_slice(body);
+        out.extend_from_slice(b"\nendobj\n");
+    }
+    let xref = out.len();
+    write!(out, "xref\n0 {}\n0000000000 65535 f \n", objects.len() + 1).unwrap();
+    for offset in offsets {
+        writeln!(out, "{offset:010} 00000 n ").unwrap();
+    }
+    write!(
+        out,
+        "trailer\n<< /Size {} /Root 1 0 R >>\nstartxref\n{xref}\n%%EOF\n",
+        objects.len() + 1
+    )
+    .unwrap();
+    out
+}
+
+/// A stream object: `dict` holds the entries besides `/Length`.
+pub fn stream_object(dict: &str, data: &[u8]) -> Vec<u8> {
+    let mut out = format!("<< /Length {} {dict} >>\nstream\n", data.len()).into_bytes();
+    out.extend_from_slice(data);
+    out.extend_from_slice(b"\nendstream");
+    out
+}
+
+/// One page of `content` with Helvetica as `/F1` and a 612 by 792 page.
+pub fn page_pdf(content: &str, page_extra: &str) -> Vec<u8> {
+    pdf_of(&[
+        b"<< /Type /Catalog /Pages 2 0 R >>".to_vec(),
+        b"<< /Type /Pages /Kids [3 0 R] /Count 1 >>".to_vec(),
+        format!(
+            "<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] \
+             /Resources << /Font << /F1 4 0 R >> >> /Contents 5 0 R {page_extra} >>"
+        )
+        .into_bytes(),
+        b"<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica /Encoding /WinAnsiEncoding >>"
+            .to_vec(),
+        stream_object("", content.as_bytes()),
+    ])
+}
+
+/// A PNG as `read::image::png` writes it, read back.
+#[derive(Debug)]
+pub struct Png {
+    pub width: u32,
+    pub height: u32,
+    pub bits: u8,
+    pub color: u8,
+    pub palette: Option<Vec<u8>>,
+    /// The rows, their filter bytes (always 0, none) taken out.
+    pub rows: Vec<u8>,
+}
+
+/// Reads a PNG, checking each chunk's CRC and that every row is unfiltered.
+pub fn png_of(data: &[u8]) -> Png {
+    let be = |at: usize| u32::from_be_bytes(data[at..at + 4].try_into().unwrap());
+    assert!(data.starts_with(b"\x89PNG\r\n\x1a\n"), "{data:?}");
+    let (mut header, mut palette, mut compressed) = (Vec::new(), None, Vec::new());
+    let mut at = 8;
+    while at < data.len() {
+        let length = be(at) as usize;
+        let (kind, body) = (&data[at + 4..at + 8], &data[at + 8..at + 8 + length]);
+        assert_eq!(
+            be(at + 8 + length),
+            crc32fast::hash(&data[at + 4..at + 8 + length]),
+            "{kind:?}"
+        );
+        match kind {
+            b"IHDR" => header = body.to_vec(),
+            b"PLTE" => palette = Some(body.to_vec()),
+            b"IDAT" => compressed.extend_from_slice(body),
+            _ => {}
+        }
+        at += 12 + length;
+    }
+    let (width, height) = (be(16), be(20));
+    let (bits, color) = (header[8], header[9]);
+    let channels = match color {
+        0 | 3 => 1,
+        4 => 2,
+        2 => 3,
+        _ => 4,
+    };
+    let stride = (width as usize * channels * usize::from(bits)).div_ceil(8);
+    let filtered = miniz_oxide::inflate::decompress_to_vec_zlib(&compressed).unwrap();
+    assert_eq!(filtered.len(), (stride + 1) * height as usize);
+    let mut rows = Vec::new();
+    for row in filtered.chunks(stride + 1) {
+        assert_eq!(row[0], 0, "filter type");
+        rows.extend_from_slice(&row[1..]);
+    }
+    Png { width, height, bits, color, palette, rows }
+}
+
+/// A one-strip little-endian TIFF's tags, by number, and its strip.
+pub fn tiff_of(data: &[u8]) -> (std::collections::BTreeMap<u16, u32>, &[u8]) {
+    let le16 = |at: usize| u16::from_le_bytes(data[at..at + 2].try_into().unwrap());
+    let le32 = |at: usize| u32::from_le_bytes(data[at..at + 4].try_into().unwrap());
+    assert!(data.starts_with(b"II*\0"));
+    let directory = le32(4) as usize;
+    let tags: std::collections::BTreeMap<u16, u32> = (0..usize::from(le16(directory)))
+        .map(|index| {
+            let entry = directory + 2 + index * 12;
+            let value =
+                if le16(entry + 2) == 3 { u32::from(le16(entry + 8)) } else { le32(entry + 8) };
+            (le16(entry), value)
+        })
+        .collect();
+    let (offset, length) = (tags[&273] as usize, tags[&279] as usize);
+    (tags, &data[offset..offset + length])
+}

data/ext/imprimatur_native/core/src/xlsx/cell.rs

@@ -0,0 +1,112 @@
+#[cfg(test)]
+mod tests;
+
+use std::fmt::Write as _;
+
+use super::DateTime;
+
+/// A cell value.
+#[derive(Debug, Clone, PartialEq)]
+#[non_exhaustive]
+pub enum Cell {
+    Text(String),
+    Number(f64),
+    Bool(bool),
+    /// A formula without its leading `=`, such as `SUM(A1:A3)`. Excel
+    /// computes it when the workbook opens.
+    Formula(String),
+    /// A date, stored as its serial number. Without a number format of its
+    /// own the cell gets `yyyy-mm-dd`, or `yyyy-mm-dd hh:mm:ss` with a time.
+    DateTime(DateTime),
+}
+
+impl Cell {
+    /// A formula cell. A leading `=` is accepted and dropped.
+    pub fn formula(expression: impl Into<String>) -> Self {
+        let mut expression = expression.into();
+        if expression.starts_with('=') {
+            expression.remove(0);
+        }
+        Self::Formula(expression)
+    }
+}
+
+impl From<&str> for Cell {
+    fn from(text: &str) -> Self {
+        Self::Text(text.to_owned())
+    }
+}
+
+impl From<String> for Cell {
+    fn from(text: String) -> Self {
+        Self::Text(text)
+    }
+}
+
+impl From<bool> for Cell {
+    fn from(value: bool) -> Self {
+        Self::Bool(value)
+    }
+}
+
+impl From<DateTime> for Cell {
+    fn from(value: DateTime) -> Self {
+        Self::DateTime(value)
+    }
+}
+
+impl From<f64> for Cell {
+    fn from(value: f64) -> Self {
+        Self::Number(value)
+    }
+}
+
+/// Integers that convert to `f64` without loss; Excel stores every number as one.
+macro_rules! lossless_numbers {
+    ($($int:ty),*) => {$(
+        impl From<$int> for Cell {
+            fn from(value: $int) -> Self {
+                Self::Number(f64::from(value))
+            }
+        }
+    )*};
+}
+lossless_numbers!(f32, i8, i16, i32, u8, u16, u32);
+
+/// The column's letters: 0 is `A`, 25 is `Z`, 26 is `AA`.
+#[must_use]
+pub fn column_name(column: u16) -> String {
+    let mut name = String::with_capacity(3);
+    push_column_name(&mut name, column);
+    name
+}
+
+/// A1-style reference for a zero-based row and column.
+#[must_use]
+pub fn cell_reference(row: u32, column: u16) -> String {
+    let mut reference = String::with_capacity(10);
+    push_cell_reference(&mut reference, row, column);
+    reference
+}
+
+/// Appends the column's letters to `out`, without allocating.
+pub fn push_column_name(out: &mut String, column: u16) {
+    const ALPHABET: &[u8; 26] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+    // XFD, the last column, is three letters.
+    let mut letters = [0_u8; 3];
+    let mut length = 0;
+    let mut rest = usize::from(column) + 1;
+    while rest > 0 && length < letters.len() {
+        letters[length] = ALPHABET[(rest - 1) % 26];
+        length += 1;
+        rest = (rest - 1) / 26;
+    }
+    out.extend(letters[..length].iter().rev().map(|&letter| char::from(letter)));
+}
+
+/// Appends an A1-style reference to `out`, without allocating.
+pub fn push_cell_reference(out: &mut String, row: u32, column: u16) {
+    push_column_name(out, column);
+    // Writing to a String cannot fail.
+    let _ = write!(out, "{}", u64::from(row) + 1);
+}

data/ext/imprimatur_native/core/src/xlsx/comment.rs

@@ -0,0 +1,256 @@
+//! Cell comments (Excel's notes). The text lives in `xl/commentsN.xml`; the
+//! box Excel draws for each one is a legacy VML shape in
+//! `xl/drawings/vmlDrawingN.vml`, which Excel still requires to show them.
+
+#[cfg(test)]
+mod tests;
+
+use std::collections::{BTreeMap, HashMap};
+
+use super::cell::push_cell_reference;
+use super::package::MAIN_NS;
+use super::text::{check_length, escape, needs_preserve};
+use super::worksheet::{MAX_COLUMNS, MAX_ROWS};
+use crate::Result;
+use crate::xml::XmlWriter;
+
+/// VML shape ids come in blocks of 1024 per `o:idmap` entry.
+pub const SHAPES_PER_BLOCK: u32 = 1024;
+/// Excel's default note: 128 by 74 pixels, 15 to the right of the next
+/// column and 10 below the row above, on a grid of 64 by 20 pixel cells.
+const NOTE_SIZE: (u32, u32) = (128, 74);
+const DEFAULT_COLUMN_PIXELS: u32 = 64;
+const ROW_PIXELS: u32 = 20;
+/// Calibri 11, the default font: its widest digit and the cell padding.
+const DIGIT_PIXELS: f64 = 7.0;
+const PADDING_PIXELS: f64 = 5.0;
+
+/// A note on a cell, set with
+/// [`Worksheet::set_comment`](super::Worksheet::set_comment). Hidden until
+/// the pointer rests on the cell, unless made visible.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Comment {
+    text: String,
+    author: Option<String>,
+    visible: bool,
+}
+
+impl Comment {
+    /// # Errors
+    /// [`Error::TextTooLong`](crate::Error::TextTooLong) over 32,767 characters.
+    pub fn new(text: impl Into<String>) -> Result<Self> {
+        let text = text.into();
+        check_length(&text)?;
+        Ok(Self { text, author: None, visible: false })
+    }
+
+    #[must_use]
+    pub fn author(mut self, author: impl Into<String>) -> Self {
+        self.author = Some(author.into()).filter(|author| !author.is_empty());
+        self
+    }
+
+    /// Shows the note all the time, not only on hover.
+    #[must_use]
+    pub const fn visible(mut self, visible: bool) -> Self {
+        self.visible = visible;
+        self
+    }
+
+    #[must_use]
+    pub fn text(&self) -> &str {
+        &self.text
+    }
+}
+
+/// `xl/commentsN.xml`: the authors, then each comment in row-major order.
+/// A comment without an author refers to an empty one.
+pub fn comments_xml(comments: &BTreeMap<(u32, u16), Comment>) -> String {
+    let mut authors: Vec<&str> = Vec::new();
+    let mut author_ids: HashMap<&str, usize> = HashMap::new();
+    let ids: Vec<usize> = comments
+        .values()
+        .map(|comment| {
+            let author = comment.author.as_deref().unwrap_or("");
+            *author_ids.entry(author).or_insert_with(|| {
+                authors.push(author);
+                authors.len() - 1
+            })
+        })
+        .collect();
+
+    let mut xml = XmlWriter::new();
+    xml.open("comments", &[("xmlns", MAIN_NS)]);
+    xml.open("authors", &[]);
+    for author in &authors {
+        xml.element("author", &[], &escape(author));
+    }
+    xml.close("authors");
+    xml.open("commentList", &[]);
+    let mut reference = String::new();
+    for ((&(row, column), comment), author) in comments.iter().zip(ids) {
+        reference.clear();
+        push_cell_reference(&mut reference, row, column);
+        xml.open("comment", &[("ref", &reference), ("authorId", &author.to_string())]);
+        xml.open("text", &[]);
+        let preserve: &[(&str, &str)] =
+            if needs_preserve(&comment.text) { &[("xml:space", "preserve")] } else { &[] };
+        xml.element("t", preserve, &escape(&comment.text));
+        xml.close("text");
+        xml.close("comment");
+    }
+    xml.close("commentList");
+    xml.close("comments");
+    xml.finish()
+}
+
+/// How many shape id blocks a drawing of `count` notes takes: ids run from
+/// `block * 1024 + 1`, so the last of a full block spills into the next.
+pub fn blocks_for(count: usize) -> u32 {
+    u32::try_from(count).map_or(u32::MAX, |count| count / SHAPES_PER_BLOCK + 1)
+}
+
+/// `xl/drawings/vmlDrawingN.vml`: one note shape per comment, with ids
+/// from `first_block`, which no other drawing in the workbook uses.
+pub fn vml(
+    comments: &BTreeMap<(u32, u16), Comment>,
+    widths: &BTreeMap<u16, f64>,
+    first_block: u32,
+) -> String {
+    let mut xml = XmlWriter::bare();
+    xml.open(
+        "xml",
+        &[
+            ("xmlns:v", "urn:schemas-microsoft-com:vml"),
+            ("xmlns:o", "urn:schemas-microsoft-com:office:office"),
+            ("xmlns:x", "urn:schemas-microsoft-com:office:excel"),
+        ],
+    );
+    xml.open("o:shapelayout", &[("v:ext", "edit")]);
+    let blocks: Vec<String> =
+        (first_block..first_block + blocks_for(comments.len())).map(|b| b.to_string()).collect();
+    xml.empty("o:idmap", &[("v:ext", "edit"), ("data", &blocks.join(","))]);
+    xml.close("o:shapelayout");
+    xml.open(
+        "v:shapetype",
+        &[
+            ("id", "_x0000_t202"),
+            ("coordsize", "21600,21600"),
+            ("o:spt", "202"),
+            ("path", "m,l,21600r21600,l21600,xe"),
+        ],
+    );
+    xml.empty("v:stroke", &[("joinstyle", "miter")]);
+    xml.empty("v:path", &[("gradientshapeok", "t"), ("o:connecttype", "rect")]);
+    xml.close("v:shapetype");
+    let first_id = first_block * SHAPES_PER_BLOCK + 1;
+    for (index, (&(row, column), comment)) in (0..).zip(comments) {
+        write_shape(&mut xml, first_id + index, index + 1, (row, column, comment.visible), widths);
+    }
+    xml.close("xml");
+    xml.finish()
+}
+
+fn write_shape(
+    xml: &mut XmlWriter,
+    id: u32,
+    z_index: u32,
+    (row, column, visible): (u32, u16, bool),
+    widths: &BTreeMap<u16, f64>,
+) {
+    let anchor = Anchor::new(row, column, widths);
+    let points = |pixels: u32| f64::from(pixels) * 0.75;
+    let style = format!(
+        "position:absolute;margin-left:{}pt;margin-top:{}pt;width:{}pt;height:{}pt;\
+         z-index:{z_index};visibility:{}",
+        points(anchor.left),
+        points(anchor.top),
+        points(NOTE_SIZE.0),
+        points(NOTE_SIZE.1),
+        if visible { "visible" } else { "hidden" },
+    );
+    let shape_id = format!("_x0000_s{id}");
+    xml.open(
+        "v:shape",
+        &[
+            ("id", &shape_id),
+            ("type", "#_x0000_t202"),
+            ("style", &style),
+            ("fillcolor", "#ffffe1"),
+            ("o:insetmode", "auto"),
+        ],
+    );
+    xml.empty("v:fill", &[("color2", "#ffffe1")]);
+    xml.empty("v:shadow", &[("on", "t"), ("color", "black"), ("obscured", "t")]);
+    xml.empty("v:path", &[("o:connecttype", "none")]);
+    xml.open("v:textbox", &[("style", "mso-direction-alt:auto")]);
+    xml.element("div", &[("style", "text-align:left")], "");
+    xml.close("v:textbox");
+    xml.open("x:ClientData", &[("ObjectType", "Note")]);
+    xml.empty("x:MoveWithCells", &[]);
+    xml.empty("x:SizeWithCells", &[]);
+    xml.element("x:Anchor", &[], &anchor.cells);
+    xml.element("x:AutoFill", &[], "False");
+    xml.element("x:Row", &[], &row.to_string());
+    xml.element("x:Column", &[], &column.to_string());
+    if visible {
+        xml.empty("x:Visible", &[]);
+    }
+    xml.close("x:ClientData");
+    xml.close("v:shape");
+}
+
+/// Where a note's box sits: `x:Anchor` in cells and pixel offsets, and its
+/// top-left corner in pixels from the sheet's.
+struct Anchor {
+    cells: String,
+    left: u32,
+    top: u32,
+}
+
+impl Anchor {
+    /// Beside the cell, from the next column and the row above, as Excel
+    /// places a new note; held inside the sheet at its right and bottom edges.
+    fn new(row: u32, column: u16, widths: &BTreeMap<u16, f64>) -> Self {
+        let width = |column: u16| widths.get(&column).map_or(DEFAULT_COLUMN_PIXELS, |&w| pixels(w));
+        // Past the columns an offset spans, as Excel counts them: narrower
+        // columns are skipped.
+        let walk = |mut column: u16, mut offset: u32| {
+            while offset >= width(column) && column < MAX_COLUMNS - 1 {
+                offset -= width(column);
+                column += 1;
+            }
+            (column, offset)
+        };
+        let (first_column, x1) = walk((column + 1).min(MAX_COLUMNS - 4), 15);
+        let (last_column, x2) = walk(first_column, x1 + NOTE_SIZE.0);
+        let (first_row, y1) =
+            if row == 0 { (0, 2) } else { ((row - 1).min(MAX_ROWS - 6), ROW_PIXELS / 2) };
+        let height = y1 + NOTE_SIZE.1;
+        let (last_row, y2) = (first_row + height / ROW_PIXELS, height % ROW_PIXELS);
+
+        let custom: i64 = widths
+            .range(..first_column)
+            .map(|(_, &w)| i64::from(pixels(w)) - i64::from(DEFAULT_COLUMN_PIXELS))
+            .sum();
+        let left = i64::from(first_column) * i64::from(DEFAULT_COLUMN_PIXELS) + custom;
+        let left = u32::try_from(left).unwrap_or(0) + x1;
+        let top = first_row.saturating_mul(ROW_PIXELS).saturating_add(y1);
+        let cells = format!(
+            "{first_column}, {x1}, {first_row}, {y1}, {last_column}, {x2}, {last_row}, {y2}"
+        );
+        Self { cells, left, top }
+    }
+}
+
+/// A column width in characters as Excel draws it, in pixels.
+#[expect(clippy::cast_possible_truncation, reason = "widths are 0 to 255: at most 1791")]
+#[expect(clippy::cast_sign_loss, reason = "widths are never negative")]
+fn pixels(width: f64) -> u32 {
+    let pixels = if width < 1.0 {
+        width.mul_add(DIGIT_PIXELS + PADDING_PIXELS, 0.5)
+    } else {
+        width.mul_add(DIGIT_PIXELS, 0.5) + PADDING_PIXELS
+    };
+    pixels.floor() as u32
+}