imprimatur 0.1.0

data/ext/imprimatur_native/cli/src/cli.rs

@@ -0,0 +1,71 @@
+//! The command line: the root, its global flag, and the commands.
+
+mod completion;
+mod grep;
+mod images;
+mod limits;
+mod markdown;
+#[cfg(test)]
+mod tests;
+
+use usage_rs::{Cli, Subcommands};
+
+pub use completion::Completion;
+pub use grep::Grep;
+pub use images::Images;
+pub use markdown::Markdown;
+
+/// The exit statuses, for `--help`; `exit_code` below declares them for the
+/// spec, and `app::Failure` returns them.
+pub const EXIT_STATUS: &str = "Exit status:
+0: every document was read
+1: a document is damaged, or a file could not be read or written
+2: the command line is wrong
+3: a PDF has no text layer: its pages are scans, which need OCR
+4: a PDF is encrypted with a password
+5: not a PDF, XLSX or DOCX (legacy .xls and .doc, .xlsb, presentations)
+6: a limit was hit: size, decompressed size, nesting or time";
+
+/// Read PDF, XLSX and DOCX documents: as Markdown or JSON, searched, or their images
+///
+/// The format is told by a document's content, not its name. Documents are
+/// untrusted input: reading is bounded in size, decompressed size, nesting
+/// and time, so a hostile file fails fast instead of hanging.
+///
+/// `grep` exits as grep does: 0 when a line matched, 1 when none did, 2 on
+/// trouble. The other commands exit as listed below.
+#[derive(Cli, Debug)]
+#[usage(
+    bin = "imprimatur",
+    version,
+    completion,
+    unknown_flags = "error",
+    args_override_self = false,
+    exit_code(0, "every document was read"),
+    exit_code(1, "a document is damaged, or a file could not be read or written"),
+    exit_code(2, "the command line is wrong"),
+    exit_code(3, "a PDF has no text layer: its pages are scans, which need OCR"),
+    exit_code(4, "a PDF is encrypted with a password"),
+    exit_code(5, "not a PDF, XLSX or DOCX: legacy .xls and .doc, .xlsb, presentations"),
+    exit_code(6, "a limit was hit: size, decompressed size, nesting or time"),
+    after_long_help = EXIT_STATUS
+)]
+pub struct Imprimatur {
+    /// One JSON object per document, each on its own line
+    #[usage(long, global)]
+    pub json: bool,
+
+    #[usage(subcommand)]
+    pub command: Commands,
+}
+
+#[derive(Subcommands, Debug)]
+#[usage(run_with)]
+pub enum Commands {
+    #[usage(alias = "md")]
+    Markdown(Markdown),
+    Grep(Grep),
+    Images(Images),
+    #[usage(no_ctx)]
+    Completion(Completion),
+}

data/ext/imprimatur_native/cli/src/main.rs

@@ -0,0 +1,15 @@
+//! `imprimatur`: documents in, Markdown out. Reads PDF, XLSX and DOCX with
+//! the imprimatur crate; see `imprimatur --help`.
+
+mod app;
+mod cli;
+
+use std::process::ExitCode;
+
+use usage_rs::RunWith;
+
+fn main() -> ExitCode {
+    let cli = cli::Imprimatur::parse();
+    let app = app::App { json: cli.json };
+    cli.command.run_with(&app)
+}

data/ext/imprimatur_native/core/Cargo.toml

@@ -0,0 +1,33 @@
+[package]
+name = "imprimatur"
+version = "0.1.0"
+description = "XLSX, PDF and DOCX authoring with its own XML, zip and PDF writers."
+keywords = ["xlsx", "excel", "pdf", "docx", "spreadsheet"]
+categories = ["encoding", "text-processing"]
+readme = "README.md"
+edition.workspace = true
+rust-version.workspace = true
+authors.workspace = true
+license.workspace = true
+repository.workspace = true
+include = ["src/**/*.rs", "src/**/*.txt", "src/**/tests/*.pdf", "src/**/tests/*.xml", "src/**/tests/*.rels", "README.md", "LICENSE*"]
+
+[lints]
+workspace = true
+
+[dependencies]
+aes = "0.9.3"
+crc32fast = "1.5.2"
+md-5 = "0.11.0"
+miniz_oxide = "0.9.1"
+serde_json = { version = "1.0.154", optional = true }
+sha2 = "0.11.1"
+thiserror = "2.0.21"
+
+[features]
+# `read::json`: content and images as JSON, the schema the command line and
+# the Ruby binding share.
+json = ["dep:serde_json"]
+
+[dev-dependencies]
+zip = { version = "9.0.3", default-features = false, features = ["deflate-flate2-zlib-rs"] }

data/ext/imprimatur_native/core/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Abdelkader Boudih
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/ext/imprimatur_native/core/README.md

@@ -0,0 +1,105 @@
+# imprimatur
+
+Document authoring with no third-party format stack: the XML and the zip
+container are written here, on `miniz_oxide` (deflate) and `crc32fast`.
+XLSX workbooks, and PDF and DOCX from one document model.
+Output is deterministic: the same document always gives the same bytes.
+
+```rust
+use imprimatur::xlsx::{Cell, Color, DateTime, Format, Workbook};
+
+let header = Format::new().bold().fill(Color::from_hex("#1F4E79")?).font_color(Color::WHITE);
+let mut book = Workbook::new();
+let sheet = book.add_sheet("Budget")?;
+sheet.append_row_with_format(["Line item", "Promised", "Delivered"], &header)?;
+sheet.append_row([Cell::from("High-speed rail"), 1_000_000_000.into(), 0.into()])?;
+sheet.append_row([Cell::from("Total"), Cell::formula("SUM(B2:B2)"), Cell::formula("SUM(C2:C2)")])?;
+sheet.write(5, 0, "written at A6")?; // zero-based row and column
+sheet.write(6, 0, DateTime::date(2026, 10, 15)?)?; // shows as yyyy-mm-dd
+sheet.set_column_width(0, 24.0)?.set_right_to_left(false);
+
+book.save("budget.xlsx")?;          // or to_bytes(), or write_to(impl Write)
+# std::fs::remove_file("budget.xlsx")?;
+# Ok::<(), Box<dyn std::error::Error>>(())
+```
+
+```rust
+use imprimatur::doc::{Document, Paragraph, Run, Table};
+
+let mut doc = Document::new();
+doc.set_page_numbers(true);
+doc.heading(1, "Quarterly report")?;
+doc.push_paragraph(Paragraph::new().text("Revenue was ").run(Run::new("up 12%").bold()))?;
+doc.table(Table::new([["Region", "Q1"], ["North", "12.5"]]).header())?;
+let pdf = doc.to_pdf()?; // Helvetica, Windows-1252 text
+let docx = doc.to_docx()?; // any script
+# Ok::<(), imprimatur::Error>(())
+```
+
+```rust
+use imprimatur::xlsx::{Alert, Comment, Format, Validation, VerticalAlign, Workbook};
+
+let header = Format::new().font_name("Arial")?.font_size(12.0)?.bold().valign(VerticalAlign::Center);
+let mut book = Workbook::new();
+let sheet = book.add_sheet("Items")?;
+sheet.append_row_with_format(["Name", "Unit"], &header)?;
+sheet.set_comment(0, 0, Comment::new("Required.")?.author("Instructions"))?;
+sheet.add_validation("B2:B1000".parse()?, Validation::list(["g", "kg", "ea"])?)?;
+let short = Validation::custom("LEN(A2)<=100")?.alert(Alert::Warning).prompt("Name", "Short")?;
+sheet.add_validation("A2:A1000".parse()?, short)?;
+# Ok::<(), imprimatur::Error>(())
+```
+
+Everything Excel would refuse is an `Error` before a byte is written: invalid
+or duplicate sheet names, positions beyond 1,048,576 rows or 16,384 columns,
+text over 32,767 characters, formulas over 8,192, NaN and infinity, font
+sizes Excel cannot set, inline validation lists over 255 characters, and
+validations whose ranges overlap. A rejected row writes nothing.
+
+Reading goes the other way, any PDF, XLSX or DOCX to Markdown, within
+limits (input size, decompressed size, nesting, time, a cancel flag):
+
+```rust
+use imprimatur::read::{Limits, markdown};
+
+# let mut book = imprimatur::xlsx::Workbook::new();
+# book.add_sheet("Notes")?.append_row(["Hello"])?;
+# let document = book.to_bytes()?;
+let text = markdown(&document, &Limits::default())?;
+assert!(text.starts_with("## Notes"));
+# Ok::<(), imprimatur::Error>(())
+```
+
+Markdown is one rendering of what a read finds. `content` gives the
+structure itself: a PDF's pages of headings and paragraphs with their
+position on the page, a workbook's sheets of typed cells (number, date,
+bool, text, error, formula) and comments, a Word document's blocks with
+their bold, italic and linked stretches. `images` hands over every image,
+as a file: JPEG and JPEG 2000 as stored, fax scans as TIFF, raw pixels as
+PNG, an Office document's media as they are.
+
+```rust
+use imprimatur::read::{Content, Limits, Value, content, images};
+
+# let mut book = imprimatur::xlsx::Workbook::new();
+# book.add_sheet("Notes")?.append_row([imprimatur::xlsx::Cell::from(12.5)])?;
+# let document = book.to_bytes()?;
+let Content::Xlsx(sheets) = content(&document, &Limits::default())? else { panic!() };
+let cell = &sheets[0].cells.cells()[0];
+assert_eq!((cell.reference(), cell.value), ("A1".to_owned(), Value::Number(12.5)));
+
+let mut found = Vec::new();
+images(&document, &Limits::default(), |image| {
+    found.push((image.format.extension(), image.data));
+    Ok(())
+})?;
+assert!(found.is_empty(), "no pictures in this one");
+# Ok::<(), imprimatur::Error>(())
+```
+
+Dependencies: `miniz_oxide`, `crc32fast` and `thiserror`; reading encrypted
+PDFs adds `md-5`, `sha2` and `aes`.
+
+## License
+
+BSD 3-Clause

data/ext/imprimatur_native/core/src/doc/paragraph.rs

@@ -0,0 +1,112 @@
+use crate::style::{Align, Color, TextDirection};
+
+/// A stretch of text with one look.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Run {
+    pub(crate) text: String,
+    pub(crate) bold: bool,
+    pub(crate) italic: bool,
+    pub(crate) underline: bool,
+    pub(crate) color: Option<Color>,
+}
+
+impl Run {
+    #[must_use]
+    pub fn new(text: impl Into<String>) -> Self {
+        Self { text: text.into(), bold: false, italic: false, underline: false, color: None }
+    }
+
+    #[must_use]
+    pub const fn bold(mut self) -> Self {
+        self.bold = true;
+        self
+    }
+
+    #[must_use]
+    pub const fn italic(mut self) -> Self {
+        self.italic = true;
+        self
+    }
+
+    #[must_use]
+    pub const fn underline(mut self) -> Self {
+        self.underline = true;
+        self
+    }
+
+    #[must_use]
+    pub const fn color(mut self, color: Color) -> Self {
+        self.color = Some(color);
+        self
+    }
+
+    #[must_use]
+    pub fn text(&self) -> &str {
+        &self.text
+    }
+}
+
+/// Runs of text laid out together. Left aligned unless told otherwise, or
+/// right aligned when right to left.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct Paragraph {
+    pub(crate) runs: Vec<Run>,
+    pub(crate) align: Option<Align>,
+    pub(crate) direction: Option<TextDirection>,
+}
+
+impl Paragraph {
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Appends plain text.
+    #[must_use]
+    pub fn text(self, text: impl Into<String>) -> Self {
+        self.run(Run::new(text))
+    }
+
+    /// Appends bold text.
+    #[must_use]
+    pub fn bold(self, text: impl Into<String>) -> Self {
+        self.run(Run::new(text).bold())
+    }
+
+    /// Appends italic text.
+    #[must_use]
+    pub fn italic(self, text: impl Into<String>) -> Self {
+        self.run(Run::new(text).italic())
+    }
+
+    #[must_use]
+    pub fn run(mut self, run: Run) -> Self {
+        self.runs.push(run);
+        self
+    }
+
+    #[must_use]
+    pub const fn align(mut self, align: Align) -> Self {
+        self.align = Some(align);
+        self
+    }
+
+    #[must_use]
+    pub const fn direction(mut self, direction: TextDirection) -> Self {
+        self.direction = Some(direction);
+        self
+    }
+
+    #[must_use]
+    pub fn runs(&self) -> &[Run] {
+        &self.runs
+    }
+
+    /// The alignment the paragraph is laid out with.
+    pub(crate) fn effective_align(&self) -> Align {
+        self.align.unwrap_or(match self.direction {
+            Some(TextDirection::RightToLeft) => Align::Right,
+            _ => Align::Left,
+        })
+    }
+}

data/ext/imprimatur_native/core/src/doc/table.rs

@@ -0,0 +1,41 @@
+/// A grid of text cells; columns share the page width equally. Short rows
+/// are padded with empty cells.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Table {
+    pub(crate) rows: Vec<Vec<String>>,
+    pub(crate) header: bool,
+}
+
+impl Table {
+    pub fn new<R, C>(rows: impl IntoIterator<Item = R>) -> Self
+    where
+        R: IntoIterator<Item = C>,
+        C: Into<String>,
+    {
+        let rows = rows.into_iter().map(|row| row.into_iter().map(Into::into).collect()).collect();
+        Self { rows, header: false }
+    }
+
+    /// Makes the first row a header: bold, shaded, and repeated on every
+    /// page the table spans.
+    #[must_use]
+    pub const fn header(mut self) -> Self {
+        self.header = true;
+        self
+    }
+
+    #[must_use]
+    pub fn rows(&self) -> &[Vec<String>] {
+        &self.rows
+    }
+
+    /// The widest row's cell count.
+    #[must_use]
+    pub fn columns(&self) -> usize {
+        self.rows.iter().map(Vec::len).max().unwrap_or(0)
+    }
+
+    pub(crate) const fn has_header(&self) -> bool {
+        self.header
+    }
+}

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

@@ -0,0 +1,210 @@
+//! A flowing document (headings, paragraphs, tables, page breaks) that
+//! renders to PDF and DOCX from the same content.
+//!
+//! ```
+//! use imprimatur::doc::{Document, Paragraph, Run, Table};
+//! use imprimatur::style::{Align, Color};
+//!
+//! let mut doc = Document::new();
+//! doc.heading(1, "Quarterly report")?;
+//! doc.push_paragraph(
+//!     Paragraph::new()
+//!         .text("Revenue was ")
+//!         .run(Run::new("up 12%").bold().color(Color::rgb(0x1F_7A_1F)))
+//!         .text(" this quarter.")
+//!         .align(Align::Left),
+//! )?;
+//! doc.table(Table::new([["Region", "Q1"], ["North", "12.5"]]).header())?;
+//! let pdf = doc.to_pdf()?;
+//! let docx = doc.to_docx()?;
+//! assert!(pdf.starts_with(b"%PDF-") && docx.starts_with(b"PK"));
+//! # Ok::<(), imprimatur::Error>(())
+//! ```
+
+mod paragraph;
+mod table;
+#[cfg(test)]
+mod tests;
+
+use std::fs::File;
+use std::io::{BufWriter, Write};
+use std::path::Path;
+
+pub use paragraph::{Paragraph, Run};
+pub use table::Table;
+
+use crate::{Error, Result};
+
+/// Paper size; pages are portrait.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub enum PageSize {
+    #[default]
+    A4,
+    Letter,
+}
+
+impl PageSize {
+    /// Width and height in PDF points (1/72 inch).
+    pub(crate) const fn points(self) -> (f64, f64) {
+        match self {
+            Self::A4 => (595.276, 841.89),
+            Self::Letter => (612.0, 792.0),
+        }
+    }
+
+    /// Width and height in twentieths of a point, as Word measures pages.
+    pub(crate) const fn twips(self) -> (u32, u32) {
+        match self {
+            Self::A4 => (11_906, 16_838),
+            Self::Letter => (12_240, 15_840),
+        }
+    }
+}
+
+/// One piece of a document, in reading order.
+#[derive(Debug, Clone, PartialEq)]
+#[non_exhaustive]
+pub enum Block {
+    Heading { level: u8, text: String },
+    Paragraph(Paragraph),
+    Table(Table),
+    PageBreak,
+}
+
+/// Content and page setup; render it with [`to_pdf`](Self::to_pdf) or
+/// [`to_docx`](Self::to_docx).
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct Document {
+    blocks: Vec<Block>,
+    page_size: PageSize,
+    page_numbers: bool,
+}
+
+impl Document {
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    pub const fn set_page_size(&mut self, size: PageSize) -> &mut Self {
+        self.page_size = size;
+        self
+    }
+
+    /// Numbers pages `1 / 3` at the bottom of each one.
+    pub const fn set_page_numbers(&mut self, enabled: bool) -> &mut Self {
+        self.page_numbers = enabled;
+        self
+    }
+
+    /// A heading, level 1 (the title) to 3.
+    ///
+    /// # Errors
+    /// [`Error::InvalidHeadingLevel`], or [`Error::ControlCharacter`] in the text.
+    pub fn heading(&mut self, level: u8, text: impl Into<String>) -> Result<&mut Self> {
+        (1..=3).contains(&level).ok_or(Error::InvalidHeadingLevel(level))?;
+        let text = text.into();
+        validate_text(&text)?;
+        self.blocks.push(Block::Heading { level, text });
+        Ok(self)
+    }
+
+    /// A paragraph of plain text. `\n` breaks the line, `\t` is a tab.
+    ///
+    /// # Errors
+    /// [`Error::ControlCharacter`] for any other control character.
+    pub fn paragraph(&mut self, text: impl Into<String>) -> Result<&mut Self> {
+        self.push_paragraph(Paragraph::new().text(text))
+    }
+
+    /// # Errors
+    /// [`Error::ControlCharacter`] in any run.
+    pub fn push_paragraph(&mut self, paragraph: Paragraph) -> Result<&mut Self> {
+        for run in &paragraph.runs {
+            validate_text(&run.text)?;
+        }
+        self.blocks.push(Block::Paragraph(paragraph));
+        Ok(self)
+    }
+
+    /// # Errors
+    /// [`Error::EmptyTable`] without a row or a column, and
+    /// [`Error::ControlCharacter`] in any cell.
+    pub fn table(&mut self, table: Table) -> Result<&mut Self> {
+        (table.columns() > 0).ok_or(Error::EmptyTable)?;
+        for cell in table.rows.iter().flatten() {
+            validate_text(cell)?;
+        }
+        self.blocks.push(Block::Table(table));
+        Ok(self)
+    }
+
+    pub fn page_break(&mut self) -> &mut Self {
+        self.blocks.push(Block::PageBreak);
+        self
+    }
+
+    #[must_use]
+    pub fn blocks(&self) -> &[Block] {
+        &self.blocks
+    }
+
+    #[must_use]
+    pub const fn page_size(&self) -> PageSize {
+        self.page_size
+    }
+
+    #[must_use]
+    pub const fn has_page_numbers(&self) -> bool {
+        self.page_numbers
+    }
+
+    /// # Errors
+    /// [`Error::UnsupportedCharacter`] for text the PDF standard fonts cannot
+    /// encode, [`Error::RowTooTall`], or [`Error::Io`] when `out` fails.
+    pub fn write_pdf<W: Write>(&self, out: W) -> Result<W> {
+        crate::pdf::write(self, out)
+    }
+
+    /// # Errors
+    /// As [`write_pdf`](Self::write_pdf).
+    pub fn to_pdf(&self) -> Result<Vec<u8>> {
+        self.write_pdf(Vec::new())
+    }
+
+    /// # Errors
+    /// As [`write_pdf`](Self::write_pdf).
+    pub fn save_pdf(&self, path: impl AsRef<Path>) -> Result<()> {
+        self.write_pdf(BufWriter::new(File::create(path)?))?;
+        Ok(())
+    }
+
+    /// # Errors
+    /// [`Error::Io`] when `out` fails.
+    pub fn write_docx<W: Write>(&self, out: W) -> Result<W> {
+        crate::docx::write(self, out)
+    }
+
+    /// # Errors
+    /// As [`write_docx`](Self::write_docx).
+    pub fn to_docx(&self) -> Result<Vec<u8>> {
+        self.write_docx(Vec::new())
+    }
+
+    /// # Errors
+    /// As [`write_docx`](Self::write_docx).
+    pub fn save_docx(&self, path: impl AsRef<Path>) -> Result<()> {
+        self.write_docx(BufWriter::new(File::create(path)?))?;
+        Ok(())
+    }
+}
+
+/// Newlines and tabs mean something in every format; other control
+/// characters mean nothing in any of them.
+fn validate_text(text: &str) -> Result<()> {
+    let invalid =
+        |ch: char| (ch.is_control() && ch != '\n' && ch != '\t') || crate::xml::is_forbidden(ch);
+    text.chars()
+        .find(|&ch| invalid(ch))
+        .map_or(Ok(()), |ch| Err(Error::ControlCharacter(u32::from(ch))))
+}