imprimatur 0.1.0

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

@@ -0,0 +1,161 @@
+//! A write-only zip archive: enough for the Open Packaging Conventions
+//! container that XLSX and DOCX are. Entries are deflated (`miniz_oxide`), or
+//! stored when deflate would not make them smaller.
+//!
+//! Output is deterministic: every entry carries the zip epoch (1980-01-01
+//! 00:00) as its timestamp, and deflate runs at a fixed level, so the same
+//! document always gives the same bytes.
+
+pub mod reader;
+#[cfg(test)]
+mod tests;
+
+use std::io::Write;
+
+use crate::{Error, Result};
+
+const LOCAL_HEADER: u32 = 0x0403_4b50;
+const CENTRAL_HEADER: u32 = 0x0201_4b50;
+const END_OF_CENTRAL_DIRECTORY: u32 = 0x0605_4b50;
+/// 2.0: the version that introduced folders, which every reader handles.
+const VERSION: u16 = 20;
+const METHOD_STORED: u16 = 0;
+const METHOD_DEFLATED: u16 = 8;
+/// zlib's default trade-off between size and speed.
+const DEFLATE_LEVEL: u8 = 6;
+/// 00:00:00 in MS-DOS time.
+const DOS_TIME: u16 = 0;
+/// 1980-01-01 in MS-DOS date: day 1, month 1, year 0 (1980).
+const DOS_DATE: u16 = (1 << 5) | 1;
+
+struct Entry {
+    name: String,
+    name_len: u16,
+    method: u16,
+    crc: u32,
+    compressed_size: u32,
+    size: u32,
+    offset: u32,
+}
+
+/// Streams entries into `out`, then the central directory on [`finish`](Self::finish).
+pub struct ZipWriter<W: Write> {
+    out: W,
+    entries: Vec<Entry>,
+    written: u64,
+}
+
+impl<W: Write> ZipWriter<W> {
+    pub const fn new(out: W) -> Self {
+        Self { out, entries: Vec::new(), written: 0 }
+    }
+
+    /// Writes one entry. Names are ASCII part names such as
+    /// `xl/workbook.xml`, so the UTF-8 name flag is never needed.
+    pub fn add(&mut self, name: &str, data: &[u8]) -> Result<()> {
+        debug_assert!(name.is_ascii(), "OPC part names are ASCII: {name:?}");
+        let offset = self.offset()?;
+        let too_large = |_| Error::ArchiveTooLarge("entry over 4 GiB");
+        let size = u32::try_from(data.len()).map_err(too_large)?;
+        let name_len =
+            u16::try_from(name.len()).map_err(|_| Error::ArchiveTooLarge("entry name"))?;
+        let crc = crc32fast::hash(data);
+
+        let deflated = miniz_oxide::deflate::compress_to_vec(data, DEFLATE_LEVEL);
+        let (method, body) = if deflated.len() < data.len() {
+            (METHOD_DEFLATED, deflated.as_slice())
+        } else {
+            (METHOD_STORED, data)
+        };
+        let compressed_size = u32::try_from(body.len()).map_err(too_large)?;
+
+        let mut header = Vec::with_capacity(30 + name.len());
+        put32(&mut header, LOCAL_HEADER);
+        put16(&mut header, VERSION);
+        put16(&mut header, 0); // flags
+        put16(&mut header, method);
+        put16(&mut header, DOS_TIME);
+        put16(&mut header, DOS_DATE);
+        put32(&mut header, crc);
+        put32(&mut header, compressed_size);
+        put32(&mut header, size);
+        put16(&mut header, name_len);
+        put16(&mut header, 0); // extra field
+        header.extend_from_slice(name.as_bytes());
+
+        self.write(&header)?;
+        self.write(body)?;
+        self.entries.push(Entry {
+            name: name.to_owned(),
+            name_len,
+            method,
+            crc,
+            compressed_size,
+            size,
+            offset,
+        });
+        Ok(())
+    }
+
+    /// Writes the central directory and returns the underlying writer.
+    pub fn finish(mut self) -> Result<W> {
+        let directory_offset = self.offset()?;
+        let count = u16::try_from(self.entries.len())
+            .map_err(|_| Error::ArchiveTooLarge("more than 65535 entries"))?;
+
+        let mut directory = Vec::new();
+        for entry in &self.entries {
+            put32(&mut directory, CENTRAL_HEADER);
+            put16(&mut directory, VERSION); // made by: MS-DOS, 2.0
+            put16(&mut directory, VERSION); // needed to extract
+            put16(&mut directory, 0); // flags
+            put16(&mut directory, entry.method);
+            put16(&mut directory, DOS_TIME);
+            put16(&mut directory, DOS_DATE);
+            put32(&mut directory, entry.crc);
+            put32(&mut directory, entry.compressed_size);
+            put32(&mut directory, entry.size);
+            put16(&mut directory, entry.name_len);
+            put16(&mut directory, 0); // extra field
+            put16(&mut directory, 0); // comment
+            put16(&mut directory, 0); // disk number
+            put16(&mut directory, 0); // internal attributes
+            put32(&mut directory, 0); // external attributes
+            put32(&mut directory, entry.offset);
+            directory.extend_from_slice(entry.name.as_bytes());
+        }
+        let directory_size = u32::try_from(directory.len())
+            .map_err(|_| Error::ArchiveTooLarge("central directory over 4 GiB"))?;
+
+        put32(&mut directory, END_OF_CENTRAL_DIRECTORY);
+        put16(&mut directory, 0); // this disk
+        put16(&mut directory, 0); // disk with the directory
+        put16(&mut directory, count); // entries on this disk
+        put16(&mut directory, count); // entries in total
+        put32(&mut directory, directory_size);
+        put32(&mut directory, directory_offset);
+        put16(&mut directory, 0); // comment
+
+        self.write(&directory)?;
+        self.out.flush()?;
+        Ok(self.out)
+    }
+
+    fn offset(&self) -> Result<u32> {
+        u32::try_from(self.written).map_err(|_| Error::ArchiveTooLarge("archive over 4 GiB"))
+    }
+
+    fn write(&mut self, bytes: &[u8]) -> Result<()> {
+        self.out.write_all(bytes)?;
+        self.written += bytes.len() as u64;
+        Ok(())
+    }
+}
+
+fn put16(buf: &mut Vec<u8>, value: u16) {
+    buf.extend_from_slice(&value.to_le_bytes());
+}
+
+fn put32(buf: &mut Vec<u8>, value: u32) {
+    buf.extend_from_slice(&value.to_le_bytes());
+}

data/ext/imprimatur_native/extconf.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# imprimatur is native only: without the extension there is no gem, so every
+# missing prerequisite stops the install with what to do about it.
+def fail_build(reason)
+  abort "imprimatur: #{reason}"
+end
+
+def command?(command) = system(command, out: File::NULL, err: File::NULL)
+
+# rb_sys writes a GNU Makefile; RubyGems runs the system make (BSD make here).
+BSD = RUBY_PLATFORM.include?('bsd')
+
+fail_build("#{RUBY_ENGINE} is not supported; imprimatur needs CRuby") unless RUBY_ENGINE == 'ruby'
+fail_build('Cargo not found; install Rust (https://rustup.rs) or use a platform gem') unless command?('cargo --version')
+fail_build('GNU make not found (pkg install gmake)') if BSD && !command?('gmake --version')
+
+require 'mkmf'
+require 'rb_sys/mkmf'
+
+create_rust_makefile('imprimatur/imprimatur_native') do |r|
+  r.ext_dir = 'ffi'
+  r.profile = ENV.fetch('RB_SYS_CARGO_PROFILE', :release).to_sym
+end
+
+# BSD make reads BSDmakefile first (GNU make ignores it): delegate to gmake.
+if BSD
+  File.write('BSDmakefile', <<~MAKE)
+    GMAKE_VARS =
+    .for var in DESTDIR sitearchdir sitelibdir
+    .if defined(${var})
+    GMAKE_VARS += ${var}="${${var}}"
+    .endif
+    .endfor
+
+    # BSD make exports its own job flags (-J) in MAKEFLAGS; gmake rejects them.
+    GMAKE = env -u MAKEFLAGS -u MFLAGS gmake -f Makefile
+
+    all:
+    \t${GMAKE} ${GMAKE_VARS}
+
+    .DEFAULT:
+    \t${GMAKE} ${GMAKE_VARS} $@
+  MAKE
+end

data/ext/imprimatur_native/ffi/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "imprimatur_native"
+version = "0.1.0"
+description = "Ruby bindings for the imprimatur crate"
+publish = false
+edition.workspace = true
+rust-version.workspace = true
+authors.workspace = true
+license.workspace = true
+
+[lib]
+crate-type = ["cdylib"]
+
+[lints]
+workspace = true
+
+[dependencies]
+imprimatur = { workspace = true, features = ["json"] }
+serde_json.workspace = true
+magnus.workspace = true
+rb-sys.workspace = true

data/ext/imprimatur_native/ffi/src/convert.rs

@@ -0,0 +1,132 @@
+//! Ruby values to cells.
+
+use imprimatur::xlsx::{Cell, DateTime};
+use magnus::prelude::*;
+use magnus::{Error, Float, Integer, RClass, RString, Ruby, Value};
+
+use crate::{OrRaise, domain_error};
+
+/// The largest integer every `f64` neighbour of which is also an integer:
+/// beyond it, Excel would silently store a different number.
+const MAX_EXACT_INTEGER: u64 = 1 << 53;
+
+/// Ruby classes looked up once per call, not once per cell.
+pub struct Classes {
+    formula: RClass,
+    date: Option<RClass>,
+}
+
+impl Classes {
+    pub fn load(ruby: &Ruby) -> Result<Self, Error> {
+        let imprimatur: magnus::RModule = ruby.class_object().const_get("Imprimatur")?;
+        // Date is only there once something has required 'date'.
+        let date_defined: bool = ruby.class_object().funcall("const_defined?", ("Date",))?;
+        let date = if date_defined { Some(ruby.class_object().const_get("Date")?) } else { None };
+        Ok(Self { formula: imprimatur.const_get("Formula")?, date })
+    }
+}
+
+/// `nil` is no cell.
+pub fn to_cell(ruby: &Ruby, value: Value, classes: &Classes) -> Result<Option<Cell>, Error> {
+    if value.is_nil() {
+        return Ok(None);
+    }
+    if let Some(text) = RString::from_value(value) {
+        return Ok(Some(Cell::Text(text.to_string()?)));
+    }
+    if let Some(float) = Float::from_value(value) {
+        return Ok(Some(Cell::Number(float.to_f64())));
+    }
+    if let Some(integer) = Integer::from_value(value) {
+        return integer_cell(ruby, integer).map(Some);
+    }
+    if value.is_kind_of(ruby.class_true_class()) {
+        return Ok(Some(Cell::Bool(true)));
+    }
+    if value.is_kind_of(ruby.class_false_class()) {
+        return Ok(Some(Cell::Bool(false)));
+    }
+    if value.is_kind_of(classes.formula) {
+        let expression: String = value.funcall("expression", ())?;
+        return Ok(Some(Cell::formula(expression)));
+    }
+    if value.is_kind_of(ruby.class_time()) {
+        return time_cell(ruby, value).map(Some);
+    }
+    if let Some(date) = classes.date
+        && value.is_kind_of(date)
+    {
+        // DateTime is a Date with a time of day; a plain Date has none.
+        if value.respond_to("hour", false)? {
+            let fraction: Value = value.funcall("sec_fraction", ())?;
+            let nanosecond: u32 =
+                fraction.funcall::<_, _, Value>("*", (1_000_000_000,))?.funcall("to_i", ())?;
+            return date_cell(ruby, value, ["hour", "minute", "second"], nanosecond).map(Some);
+        }
+        return date_cell(ruby, value, [], 0).map(Some);
+    }
+    // BigDecimal, Rational: Excel keeps every number as a double anyway.
+    if value.is_kind_of(ruby.class_numeric()) {
+        let number: f64 = value.funcall("to_f", ())?;
+        return Ok(Some(Cell::Number(number)));
+    }
+    // ActiveSupport::TimeWithZone is a Time only to Ruby's own is_a?; its
+    // fields are the wall clock of its zone.
+    if value.respond_to("is_a?", false)?
+        && value.funcall::<_, _, bool>("is_a?", (ruby.class_time(),))?
+    {
+        return time_cell(ruby, value).map(Some);
+    }
+    Err(Error::new(
+        ruby.exception_type_error(),
+        format!("unsupported cell value {} ({})", value.inspect(), value.class().inspect()),
+    ))
+}
+
+fn time_cell(ruby: &Ruby, value: Value) -> Result<Cell, Error> {
+    let nanosecond: u32 = value.funcall("nsec", ())?;
+    date_cell(ruby, value, ["hour", "min", "sec"], nanosecond)
+}
+
+/// The wall-clock fields of a `Time`, `Date` or `DateTime`, named by `time`.
+fn date_cell<const N: usize>(
+    ruby: &Ruby,
+    value: Value,
+    time: [&str; N],
+    nanosecond: u32,
+) -> Result<Cell, Error> {
+    let year: i64 = value.funcall("year", ())?;
+    let month: u8 = value.funcall("month", ())?;
+    let day: u8 = value.funcall("day", ())?;
+    let mut clock = [0_u8; 3];
+    for (field, method) in clock.iter_mut().zip(time) {
+        *field = value.funcall(method, ())?;
+    }
+    let out_of_range = || {
+        let error = imprimatur::Error::DateOutOfRange(value.inspect());
+        domain_error(ruby, &error)
+    };
+    let year = u16::try_from(year).map_err(|_| out_of_range())?;
+    let date = DateTime::date(year, month, day).or_raise(ruby)?;
+    let [hour, minute, second] = clock;
+    let date = date.at(hour, minute, second, nanosecond).or_raise(ruby)?;
+    Ok(Cell::DateTime(date))
+}
+
+/// Integers become numbers only when the `f64` holds them exactly.
+fn integer_cell(ruby: &Ruby, integer: Integer) -> Result<Cell, Error> {
+    let out_of_range = || {
+        Error::new(
+            ruby.exception_range_error(),
+            format!(
+                "{integer} cannot be stored exactly; Excel keeps numbers as doubles (up to 2**53)"
+            ),
+        )
+    };
+    let value = integer.to_i64().map_err(|_| out_of_range())?;
+    if value.unsigned_abs() > MAX_EXACT_INTEGER {
+        return Err(out_of_range());
+    }
+    #[expect(clippy::cast_precision_loss, reason = "|value| <= 2**53, so the cast is exact")]
+    Ok(Cell::Number(value as f64))
+}

data/ext/imprimatur_native/ffi/src/document.rs

@@ -0,0 +1,138 @@
+//! `Imprimatur::Native::Document`: the document model, rendered to PDF or DOCX.
+
+use std::cell::RefCell;
+
+use imprimatur::doc::{Document, PageSize, Paragraph, Run, Table};
+use imprimatur::style::Color;
+use magnus::{Error, RModule, RString, Ruby, function, method, prelude::*};
+
+use crate::{ALIGNS, DIRECTIONS, OrRaise, RubyBytes, borrow, keyword};
+
+/// `[text, bold, italic, underline, color]`, as `Imprimatur::Paragraph` collects it.
+type RunSpec = (String, bool, bool, bool, Option<String>);
+
+#[magnus::wrap(class = "Imprimatur::Native::Document", free_immediately, size)]
+struct NativeDocument(RefCell<Document>);
+
+#[derive(Clone, Copy)]
+enum Output {
+    Pdf,
+    Docx,
+}
+
+const OUTPUTS: [(&str, Output); 2] = [("pdf", Output::Pdf), ("docx", Output::Docx)];
+
+#[expect(clippy::needless_pass_by_value, reason = "magnus passes Ruby arguments as owned values")]
+impl NativeDocument {
+    fn new() -> Self {
+        Self(RefCell::new(Document::new()))
+    }
+
+    fn set_page(
+        ruby: &Ruby,
+        rb_self: &Self,
+        size: String,
+        page_numbers: bool,
+    ) -> Result<(), Error> {
+        let size = keyword(
+            ruby,
+            "page_size",
+            &size,
+            &[("a4", PageSize::A4), ("letter", PageSize::Letter)],
+        )?;
+        borrow(ruby, &rb_self.0, "document")?.set_page_size(size).set_page_numbers(page_numbers);
+        Ok(())
+    }
+
+    fn heading(ruby: &Ruby, rb_self: &Self, level: u8, text: String) -> Result<(), Error> {
+        borrow(ruby, &rb_self.0, "document")?.heading(level, text).or_raise(ruby)?;
+        Ok(())
+    }
+
+    fn paragraph(
+        ruby: &Ruby,
+        rb_self: &Self,
+        runs: Vec<RunSpec>,
+        align: Option<String>,
+        direction: Option<String>,
+    ) -> Result<(), Error> {
+        let mut paragraph = Paragraph::new();
+        for (text, bold, italic, underline, color) in runs {
+            let mut run = Run::new(text);
+            if bold {
+                run = run.bold();
+            }
+            if italic {
+                run = run.italic();
+            }
+            if underline {
+                run = run.underline();
+            }
+            if let Some(color) = color {
+                run = run.color(Color::from_hex(&color).or_raise(ruby)?);
+            }
+            paragraph = paragraph.run(run);
+        }
+        if let Some(align) = align {
+            paragraph = paragraph.align(keyword(ruby, "align", &align, &ALIGNS)?);
+        }
+        if let Some(direction) = direction {
+            paragraph = paragraph.direction(keyword(ruby, "direction", &direction, &DIRECTIONS)?);
+        }
+        borrow(ruby, &rb_self.0, "document")?.push_paragraph(paragraph).or_raise(ruby)?;
+        Ok(())
+    }
+
+    fn table(
+        ruby: &Ruby,
+        rb_self: &Self,
+        rows: Vec<Vec<String>>,
+        header: bool,
+    ) -> Result<(), Error> {
+        let mut table = Table::new(rows);
+        if header {
+            table = table.header();
+        }
+        borrow(ruby, &rb_self.0, "document")?.table(table).or_raise(ruby)?;
+        Ok(())
+    }
+
+    fn page_break(ruby: &Ruby, rb_self: &Self) -> Result<(), Error> {
+        borrow(ruby, &rb_self.0, "document")?.page_break();
+        Ok(())
+    }
+
+    /// `:pdf` or `:docx` as a binary String.
+    fn render(ruby: &Ruby, rb_self: &Self, format: String) -> Result<RString, Error> {
+        let document = borrow(ruby, &rb_self.0, "document")?;
+        let out = RubyBytes(ruby.str_buf_new(0));
+        let written = match keyword(ruby, "format", &format, &OUTPUTS)? {
+            Output::Pdf => document.write_pdf(out),
+            Output::Docx => document.write_docx(out),
+        };
+        Ok(written.or_raise(ruby)?.0)
+    }
+
+    /// Writes `:pdf` or `:docx` straight to `path`.
+    fn save(ruby: &Ruby, rb_self: &Self, format: String, path: String) -> Result<(), Error> {
+        let document = borrow(ruby, &rb_self.0, "document")?;
+        let saved = match keyword(ruby, "format", &format, &OUTPUTS)? {
+            Output::Pdf => document.save_pdf(path),
+            Output::Docx => document.save_docx(path),
+        };
+        saved.or_raise(ruby)
+    }
+}
+
+pub fn define(ruby: &Ruby, native: RModule) -> Result<(), Error> {
+    let class = native.define_class("Document", ruby.class_object())?;
+    class.define_singleton_method("new", function!(NativeDocument::new, 0))?;
+    class.define_method("set_page", method!(NativeDocument::set_page, 2))?;
+    class.define_method("heading", method!(NativeDocument::heading, 2))?;
+    class.define_method("paragraph", method!(NativeDocument::paragraph, 3))?;
+    class.define_method("table", method!(NativeDocument::table, 2))?;
+    class.define_method("page_break", method!(NativeDocument::page_break, 0))?;
+    class.define_method("render", method!(NativeDocument::render, 1))?;
+    class.define_method("save", method!(NativeDocument::save, 2))?;
+    Ok(())
+}