imprimatur 0.2.0 → 0.4.0

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

@@ -4,10 +4,12 @@
 //! drives them; sheets cross as indices.
 
 mod archive;
+mod barcode;
 mod blocking;
 mod convert;
 mod document;
 mod read;
+mod sheets;
 mod style;
 mod validation;
 
@@ -131,6 +133,31 @@ impl NativeWorkbook {
         Ok(())
     }
 
+    /// The workbook's own font, and whether the sheets it adds autofit.
+    fn configure(
+        ruby: &Ruby,
+        rb_self: &Self,
+        font: Option<String>,
+        size: Option<f64>,
+        autofit: bool,
+    ) -> Result<(), Error> {
+        let mut book = borrow(ruby, &rb_self.0, "workbook")?;
+        if let Some(font) = font {
+            book.set_font_name(font).or_raise(ruby)?;
+        }
+        if let Some(size) = size {
+            book.set_font_size(size).or_raise(ruby)?;
+        }
+        book.set_autofit(autofit);
+        Ok(())
+    }
+
+    fn set_autofit(ruby: &Ruby, rb_self: &Self, sheet: usize, autofit: bool) -> Result<(), Error> {
+        let mut book = borrow(ruby, &rb_self.0, "workbook")?;
+        sheet_mut(ruby, &mut book, sheet)?.set_autofit(autofit);
+        Ok(())
+    }
+
     fn set_right_to_left(
         ruby: &Ruby,
         rb_self: &Self,
@@ -176,6 +203,14 @@ impl std::io::Write for RubyBytes {
     }
 }
 
+/// A Ruby String's bytes, copied out.
+fn bytes(string: RString) -> Vec<u8> {
+    #[allow(unsafe_code)]
+    // SAFETY: the bytes are copied out at once, while the GVL is held and
+    // before any Ruby code can run and move or free the string.
+    unsafe { string.as_slice() }.to_vec()
+}
+
 /// Mutable access to a wrapped value; Ruby code that calls back into the
 /// same object mid-call gets a `RuntimeError`, not a panic.
 fn borrow<'a, T>(ruby: &Ruby, cell: &'a RefCell<T>, what: &str) -> Result<RefMut<'a, T>, Error> {
@@ -281,11 +316,13 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     style.define_singleton_method("__build", function!(Style::build, 13))?;
     let validation = imprimatur.define_class("Validation", ruby.class_object())?;
     validation.define_singleton_method("__build", function!(Validation::build, 8))?;
+    barcode::define(ruby, imprimatur)?;
 
     let native = imprimatur.define_module("Native")?;
     native.define_singleton_method("markdown", function!(read::markdown_native, 4))?;
-    native.define_singleton_method("content", function!(read::content_native, 4))?;
+    native.define_singleton_method("content", function!(read::content_native, 5))?;
     native.define_singleton_method("images", function!(read::images_native, 4))?;
+    native.define_singleton_method("sheets", function!(sheets::sheets_native, 5))?;
     let zip_writer = native.define_class("ZipWriter", ruby.class_object())?;
     zip_writer.define_singleton_method("new", function!(archive::ZipWriter::new, 1))?;
     zip_writer.define_method("add_file", method!(archive::ZipWriter::add_file, 3))?;
@@ -307,6 +344,8 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     workbook.define_method("set_column_width", method!(NativeWorkbook::set_column_width, 3))?;
     workbook.define_method("add_validation", method!(NativeWorkbook::add_validation, 3))?;
     workbook.define_method("set_comment", method!(NativeWorkbook::set_comment, 4))?;
+    workbook.define_method("configure", method!(NativeWorkbook::configure, 3))?;
+    workbook.define_method("set_autofit", method!(NativeWorkbook::set_autofit, 2))?;
     workbook.define_method("set_right_to_left", method!(NativeWorkbook::set_right_to_left, 2))?;
     workbook.define_method("next_row", method!(NativeWorkbook::next_row, 1))?;
     workbook.define_method("render", method!(NativeWorkbook::render, 0))?;

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

@@ -17,7 +17,7 @@ use crate::blocking::MAX_ATTEMPTS;
 use crate::{argument_error, domain_error};
 
 /// A read of a document's bytes within limits, run without the GVL.
-type Job<T> = fn(&[u8], &Limits) -> imprimatur::Result<T>;
+pub type Job<T> = fn(&[u8], &Limits) -> imprimatur::Result<T>;
 
 /// What crosses into the thread without the GVL, and comes back.
 struct Read<T> {
@@ -41,18 +41,18 @@ pub fn markdown_native(
 }
 
 /// Called by `Imprimatur.content`: the structure as JSON, the schema the
-/// command line prints, serialized before the GVL is taken back.
+/// command line prints, with each formatted cell's look when `styles`.
 pub fn content_native(
     ruby: &Ruby,
     document: RString,
     max_input: Option<usize>,
     max_inflated: Option<u64>,
     timeout: Option<f64>,
+    styles: bool,
 ) -> Result<RString, Error> {
-    let text = without_gvl(ruby, document, (max_input, max_inflated, timeout), |bytes, limits| {
-        content(bytes, limits).map(|content| Json::Object(json::content(&content)).to_string())
-    })?;
-    Ok(ruby.str_new(&text))
+    let read = without_gvl(ruby, document, (max_input, max_inflated, timeout), content)?;
+    let options = json::Options { styles };
+    Ok(ruby.str_new(&Json::Object(json::content_with(&read, options)).to_string()))
 }
 
 /// Called by `Imprimatur.images`: `[data, description]` pairs, the data
@@ -107,16 +107,13 @@ fn limits(
 }
 
 /// Runs `job` on the document's bytes on this thread, the GVL released.
-fn without_gvl<T>(
+pub fn without_gvl<T>(
     ruby: &Ruby,
     document: RString,
     keywords: (Option<usize>, Option<u64>, Option<f64>),
     job: Job<T>,
 ) -> Result<T, Error> {
-    // SAFETY: the bytes are copied out at once, while the GVL is held and
-    // before any Ruby code can run and move or free the string.
-    #[allow(unsafe_code)]
-    let document = unsafe { document.as_slice() }.to_vec();
+    let document = crate::bytes(document);
     let cancel = Arc::new(AtomicBool::new(false));
     let limits = limits(ruby, &cancel, keywords)?;
     let mut read = Read { document, limits, job, result: None };

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

@@ -0,0 +1,114 @@
+//! `Imprimatur::Native.sheets`: a workbook's sheets as rows of Ruby values,
+//! built from the cells directly instead of a hash per cell.
+
+use imprimatur::read::{Cell, Content, Grid, Sheet, Value, content, json};
+use imprimatur::xlsx::DateTime;
+use magnus::prelude::*;
+use magnus::{Error, IntoValue, RArray, RClass, RString, Ruby, Value as RubyValue};
+
+use crate::domain_error;
+use crate::read::without_gvl;
+
+/// The largest whole `f64` an Integer can come from exactly.
+const MAX_EXACT_INTEGER: f64 = 9_007_199_254_740_992.0;
+
+/// Called by `Imprimatur::Spreadsheet.open`: `[name, hidden, rows, details]`
+/// per sheet. The rows run from the first to the last with a value, each an
+/// Array of values by column, `nil` where a cell is empty; the details are
+/// the sheet's comments, columns, validations and, when `styles`, styles,
+/// as JSON.
+pub fn sheets_native(
+    ruby: &Ruby,
+    document: RString,
+    max_input: Option<usize>,
+    max_inflated: Option<u64>,
+    timeout: Option<f64>,
+    styles: bool,
+) -> Result<RArray, Error> {
+    let read = without_gvl(ruby, document, (max_input, max_inflated, timeout), content)?;
+    let Some(sheets) = read.sheets() else {
+        let kind = if matches!(read, Content::Pdf(_)) { "a PDF" } else { "a Word document" };
+        let error = imprimatur::Error::UnsupportedDocument(format!("{kind} is no spreadsheet"));
+        return Err(domain_error(ruby, &error));
+    };
+    let dates = Dates::load(ruby)?;
+    let out = ruby.ary_new_capa(sheets.len());
+    for sheet in sheets {
+        let details = json::sheet_details(sheet, json::Options { styles });
+        let entry = [
+            ruby.str_new(&sheet.name).into_value_with(ruby),
+            sheet.hidden.into_value_with(ruby),
+            rows(ruby, sheet, &dates)?.into_value_with(ruby),
+            ruby.str_new(&serde_json::Value::Object(details).to_string()).into_value_with(ruby),
+        ];
+        out.push(ruby.ary_new_from_values(&entry))?;
+    }
+    Ok(out)
+}
+
+fn rows(ruby: &Ruby, sheet: &Sheet, dates: &Dates) -> Result<RArray, Error> {
+    let grid = &sheet.cells;
+    let count = grid.cells().last().map_or(0, |cell| cell.row + 1);
+    let rows = ruby.ary_new_capa(usize::try_from(count).unwrap_or_default());
+    let mut filled = grid.rows().peekable();
+    for row in 0..count {
+        let values = ruby.ary_new();
+        if let Some(cells) =
+            filled.next_if(|cells| cells.first().is_some_and(|cell| cell.row == row))
+        {
+            for cell in cells {
+                let column = isize::try_from(cell.column).unwrap_or(isize::MAX);
+                values.store(column, value(ruby, grid, cell, dates)?)?;
+            }
+        }
+        rows.push(values)?;
+    }
+    Ok(rows)
+}
+
+/// A cell's value as Ruby has it. A formula with no computed result is nil.
+fn value(ruby: &Ruby, grid: &Grid, cell: &Cell, dates: &Dates) -> Result<RubyValue, Error> {
+    let text = grid.text(cell);
+    Ok(match cell.value {
+        Value::Number(number) => number_value(ruby, number, text),
+        Value::Bool(on) => on.into_value_with(ruby),
+        Value::Date(date) => dates.value(date)?,
+        Value::Formula => ruby.qnil().as_value(),
+        _ => ruby.str_new(text).as_value(),
+    })
+}
+
+/// A whole number shown without a decimal point or a percent sign is an
+/// Integer (`2`, `1,250`); any other a Float (`2.00`, `50%` as 0.5).
+fn number_value(ruby: &Ruby, number: f64, shown: &str) -> RubyValue {
+    let whole = number.fract() == 0.0 && number.abs() <= MAX_EXACT_INTEGER;
+    if whole && !shown.contains(['.', '%']) {
+        #[expect(clippy::cast_possible_truncation, reason = "a whole number within 2**53")]
+        ruby.integer_from_i64(number as i64).as_value()
+    } else {
+        ruby.float_from_f64(number).as_value()
+    }
+}
+
+/// `Date` and `DateTime`, looked up once per call.
+struct Dates {
+    date: RClass,
+    date_time: RClass,
+}
+
+impl Dates {
+    fn load(ruby: &Ruby) -> Result<Self, Error> {
+        let object = ruby.class_object();
+        Ok(Self { date: object.const_get("Date")?, date_time: object.const_get("DateTime")? })
+    }
+
+    /// A `Date`, or a `DateTime` when there is a time of day.
+    fn value(&self, date: DateTime) -> Result<RubyValue, Error> {
+        let (year, month, day) = date.year_month_day();
+        if !date.has_time() {
+            return self.date.funcall("new", (year, month, day));
+        }
+        let (hour, minute, second) = date.time_of_day();
+        self.date_time.funcall("new", (year, month, day, hour, minute, second))
+    }
+}

data/lib/imprimatur/barcode.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Imprimatur
+  # A barcode: QR Code, Data Matrix, EAN-13, EAN-8, UPC-A or Code 128, and the
+  # GS1 forms of QR Code, Data Matrix and Code 128 (GS1-128). Built with
+  # {Imprimatur.barcode}; draw it with {#svg} or {#png}, or place it in a
+  # {Document} with {Document#barcode}. The class itself is native.
+  #
+  #   qr = Imprimatur.barcode(:qr, 'https://id.gs1.org/01/09506000134352')
+  #   File.write('qr.svg', qr.svg(module_size: 4))
+  #
+  #   label = Imprimatur.barcode(:code128, '(00)106141412345678908', gs1: true)
+  #   File.binwrite('label.png', label.png(module_size: 3))
+  #
+  #   Imprimatur.barcode(:ean13, '950600013435').text # => "9506000134352"
+  class Barcode
+    SYMBOLOGIES = %i[qr datamatrix ean13 ean8 upca code128].freeze
+
+    # @param symbology [:qr, :datamatrix, :ean13, :ean8, :upca, :code128]
+    # @param data [String] text; a GTIN's digits for EAN and UPC, the check
+    #   digit added when left out; with +gs1: true+, a GS1 element string
+    #   such as "(01)09506000134352(17)251231(10)AB12"
+    # @param gs1 [Boolean] a GS1 QR Code, GS1 DataMatrix or GS1-128
+    # @param level [:l, :m, :q, :h, nil] a QR Code's error correction, :m unless set
+    # @return [Barcode]
+    # @raise [Imprimatur::Error] data the symbology cannot hold, an invalid
+    #   element string, or a wrong check digit
+    # @raise [ArgumentError] an unknown symbology or level, or one that does not apply
+    def self.encode(symbology, data, gs1: false, level: nil)
+      __encode(symbology.to_s, String(data), gs1 ? true : false, level&.to_s)
+    end
+
+    private_class_method :__encode
+
+    # @param module_size [Numeric] user units (pixels) a module, 0.01 to 1000
+    # @param color [String] the bars, "#RRGGBB"
+    # @param background [String, nil] "#RRGGBB", or nil for none
+    # @param quiet_zone [Boolean] keep the blank margin scanners need
+    # @param bar_height [Integer, nil] a linear code's bar height in modules;
+    #   the symbology's nominal height unless set
+    # @return [String] SVG markup
+    # @raise [Imprimatur::Error] a module size or color out of range
+    def svg(module_size: 4, color: '#000000', background: '#FFFFFF', quiet_zone: true, bar_height: nil)
+      __svg(Float(module_size), look(color, background, quiet_zone, bar_height))
+    end
+
+    # @param module_size [Integer] pixels a module
+    # @param (see #svg)
+    # @return [String] the PNG bytes (binary): one bit a pixel, the background
+    #   transparent when nil
+    # @raise [Imprimatur::Error] a size of 0, an image above 65 536 pixels a side,
+    #   or an invalid color
+    def png(module_size: 4, color: '#000000', background: '#FFFFFF', quiet_zone: true, bar_height: nil)
+      __png(Integer(module_size), look(color, background, quiet_zone, bar_height))
+    end
+
+    # @!method symbology
+    #   @return [Symbol] one of {SYMBOLOGIES}
+    # @!method text
+    #   @return [String] what it encodes: the data given, or a GTIN with its check digit
+    # @!method gs1?
+    #   @return [Boolean] whether it carries a GS1 element string
+    # @!method width
+    #   @return [Integer] modules across, without the quiet zone
+    # @!method height
+    #   @return [Integer] modules down; 1 for a linear code
+    # @!method modules
+    #   @return [Array<Array<Boolean>>] rows of modules, true for dark
+
+    def inspect = "#<#{self.class} #{symbology}#{' gs1' if gs1?} #{text.inspect}>"
+
+    private
+
+    def look(color, background, quiet_zone, bar_height)
+      [color.to_s, background&.to_s, quiet_zone ? true : false, bar_height && Integer(bar_height)]
+    end
+  end
+end

data/lib/imprimatur/document.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module Imprimatur
-  # A flowing document (headings, paragraphs, tables, page breaks) that
-  # renders to PDF and DOCX from the same content.
+  # A flowing document (headings, paragraphs, tables, pictures, barcodes, page breaks)
+  # that renders to PDF and DOCX from the same content.
   #
   #   doc = Imprimatur::Document.new(page_numbers: true)
   #   doc.heading 'Quarterly report'
@@ -18,12 +18,51 @@ module Imprimatur
   # PDF uses the standard Helvetica fonts for now: Windows-1252 (Latin) text
   # only, anything else raises {Imprimatur::Error}. DOCX carries any script.
   class Document
-    # @param page_size [:a4, :letter]
+    # @param page_size [:a4, :letter, Array(Numeric, Numeric)] or its width
+    #   and height in points, 36 to 1584 a side
+    # @param margin [Numeric, nil] points on every side, one inch (72) unless set
     # @param page_numbers [Boolean] number pages "1 / N" in the footer
     # @raise [ArgumentError] an unknown page size
-    def initialize(page_size: :a4, page_numbers: false)
+    # @raise [Imprimatur::Error] a page size or margin out of range
+    def initialize(page_size: :a4, margin: nil, page_numbers: false)
       @native = Native::Document.new
-      @native.set_page(page_size.to_s, page_numbers ? true : false)
+      numbers = page_numbers ? true : false
+      if page_size.is_a?(Array)
+        width, height = page_size
+        @native.set_page_points(Float(width), Float(height), numbers)
+      else
+        @native.set_page(page_size.to_s, numbers)
+      end
+      @native.set_margin(Float(margin)) if margin
+    end
+
+    # A PNG or JPEG in the flow, at +width+ or +height+ points (the other
+    # follows its proportions), or else at 96 pixels an inch; never larger
+    # than the page leaves room for.
+    #
+    # @param source [String, Pathname, #read] a path, the bytes or an IO
+    # @param align [:left, :center, :right, nil]
+    # @return [self]
+    # @raise [Imprimatur::Error] no PNG or JPEG, or one it cannot draw
+    def image(source, width: nil, height: nil, align: nil)
+      @native.picture(Reader.read(source), width && Float(width), height && Float(height), align&.to_s)
+      self
+    end
+
+    # A barcode in the flow: vector shapes in a PDF, a 300 dpi picture in DOCX.
+    # Drawn at +width+ or +height+ points (a QR Code or Data Matrix keeps
+    # square modules; a linear code's height is its bars'), or else at its
+    # symbology's usual module size; never larger than the page leaves room for.
+    # Its quiet zone is part of its size.
+    #
+    # @param barcode [Barcode] from {Imprimatur.barcode}
+    # @param align [:left, :center, :right, nil]
+    # @param color [String, nil] the bars, "#RRGGBB"; black unless set
+    # @return [self]
+    # @raise [Imprimatur::Error] a size out of range, or an invalid color
+    def barcode(barcode, width: nil, height: nil, align: nil, color: nil)
+      @native.barcode(barcode, [width && Float(width), height && Float(height)], align&.to_s, color&.to_s)
+      self
     end
 
     # @param text [String]
@@ -40,7 +79,8 @@ module Imprimatur
     #
     # @param text [String, nil] plain text, styled by the keywords below
     # @param align [:left, :center, :right, nil]
-    # @param direction [:ltr, :rtl, nil] right to left aligns right unless told otherwise
+    # @param direction [:ltr, :rtl, nil] nil takes the direction of the first letter;
+    #   right to left aligns right unless told otherwise
     # @yieldparam paragraph [Paragraph] add runs with {Paragraph#text}
     # @return [self]
     def paragraph(text = nil, align: nil, direction: nil, **look)

data/lib/imprimatur/reader.rb

@@ -21,8 +21,8 @@ module Imprimatur
     def self.markdown(document, **) = Native.markdown(read(document), *limits(**))
 
     # @see Imprimatur.content
-    def self.content(document, **)
-      JSON.parse(Native.content(read(document), *limits(**)), symbolize_names: true)
+    def self.content(document, styles: false, **)
+      JSON.parse(Native.content(read(document), *limits(**), styles ? true : false), symbolize_names: true)
     end
 
     # @see Imprimatur.images

data/lib/imprimatur/spreadsheet.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'json'
+
+module Imprimatur
+  # No row among the first ones of a sheet holds every header
+  # {Spreadsheet::Sheet#parse} looks for.
+  class HeaderRowNotFound < Error
+    # @return [Array<String>] the headers missing from the row that holds the most of them
+    attr_reader :missing
+
+    def initialize(missing)
+      @missing = missing.freeze
+      super("no header row has #{missing.join(', ')}")
+    end
+  end
+
+  # A workbook read for its values: +.xlsx+, +.xls+ (Excel 97-2003, and
+  # Excel 5.0/95) or +.ods+. Values come as Ruby has them: Strings,
+  # Integers for whole numbers shown without a decimal point or a percent
+  # sign, Floats, true and false, Dates, and DateTimes for a time of day;
+  # a formula without a computed result is nil.
+  #
+  #   book = Imprimatur::Spreadsheet.open('suppliers.xlsx')
+  #   book.names                    # => ["Suppliers", "Countries"]
+  #   book.sheet.rows.first         # => ["Name", "Country", "Since"]
+  #   book.sheet.parse(name: 'Name', since: 'Since')
+  #   # => [{ name: "Acme", since: #<Date: 2024-03-15> }, ...]
+  class Spreadsheet
+    # One sheet's values.
+    class Sheet
+      # How many rows from the top {#parse} searches for the header row.
+      HEADER_ROWS = 100
+
+      # @return [String]
+      attr_reader :name
+
+      # @return [Array<Array>] every row from the first to the last with a
+      #   value, each an Array of values by column, nil where a cell is
+      #   empty; a row without a value is an empty Array
+      attr_reader :rows
+
+      # @api private
+      def initialize(name, hidden, rows, details)
+        @name = name
+        @hidden = hidden
+        @rows = rows
+        @details = details
+      end
+
+      def hidden? = @hidden
+
+      # @return [Array<Hash>] +{cell:, author:, text:}+
+      def comments = details[:comments]
+
+      # @return [Array<Hash>] runs of +{first:, last:, width:, hidden:}+ columns, by letter
+      def columns = details[:columns]
+
+      # @return [Array<Hash>] +{range:, type:, formula1:, ...}+, as {Imprimatur.content} gives them
+      def validations = details[:validations]
+
+      # @return [Array<Hash>] each formatted cell's +{cell:, font:, size:, bold:, fill:, ...}+;
+      #   empty unless the workbook was opened with +styles: true+
+      def styles = details.fetch(:styles, [])
+
+      # @return [Hash, nil] the validation over exactly +range+ (+"G2:G1000"+)
+      def validation(range) = validations.find { it[:range] == range }
+
+      # @return [Hash, nil] the look of the cell at +reference+ (+"A1"+)
+      def style(reference) = styles.find { it[:cell] == reference }
+
+      # The rows under the header row, as Hashes of +headers+' keys to the
+      # values in the columns their headers name. The header row is the
+      # first, among the first +header_rows+, to hold every header.
+      #
+      #   sheet.parse(clean: true, name: 'Company Name', country: 'Country')
+      #   # => [{ name: "Acme", country: "PL" }, ...]
+      #
+      # @param clean [Boolean] strips control characters, and whitespace at
+      #   both ends, from every String, headers included
+      # @param header_rows [Integer]
+      # @param headers [Hash{Symbol => String}]
+      # @return [Array<Hash>]
+      # @raise [HeaderRowNotFound] no row holds every header
+      def parse(clean: false, header_rows: HEADER_ROWS, **headers)
+        rows = clean ? @rows.map { |row| row.map { clean(it) } } : @rows
+        header, columns = header_row(rows.first(header_rows), headers.values)
+        rows.drop(header + 1).map do |row|
+          headers.keys.zip(columns).to_h { |key, column| [key, row[column]] }
+        end
+      end
+
+      private
+
+      # The index of the first row holding every header, and their columns.
+      def header_row(rows, headers)
+        closest = []
+        rows.each_with_index do |row, index|
+          found = headers.filter_map { row.index(it) }
+          return [index, found] if found.size == headers.size
+
+          closest = headers.select { row.include?(it) } if found.size > closest.size
+        end
+        raise HeaderRowNotFound, headers - closest
+      end
+
+      def clean(value)
+        value.is_a?(String) ? value.gsub(/[[:cntrl:]]|\A[[:space:]]+|[[:space:]]+\z/, '') : value
+      end
+
+      def details
+        @details = JSON.parse(@details, symbolize_names: true) if @details.is_a?(String)
+        @details
+      end
+    end
+
+    # @param document [String, Pathname, #read] a path, the bytes or an IO
+    # @param styles [Boolean] each sheet's {Sheet#styles} too
+    # @param limits [Hash] +max_bytes:+, +max_inflated:+ and +timeout:+, as
+    #   {Imprimatur.content} takes them
+    # @return [Spreadsheet]
+    # @raise [UnsupportedDocument] a PDF, a Word document or another format
+    # @raise [Imprimatur::Error] a damaged workbook, or past a limit
+    def self.open(document, styles: false, **limits)
+      new(Native.sheets(Reader.read(document), *Reader.limits(**limits), styles ? true : false))
+    end
+
+    # @return [Array<Sheet>] in the workbook's order, hidden ones included
+    attr_reader :sheets
+
+    # @api private
+    def initialize(sheets)
+      @sheets = sheets.map { |name, hidden, rows, details| Sheet.new(name, hidden, rows, details) }.freeze
+    end
+
+    # @return [Array<String>]
+    def names = sheets.map(&:name)
+
+    # The sheet named +name+, or the first one.
+    #
+    # @return [Sheet]
+    # @raise [KeyError] the workbook has no sheet of that name
+    def sheet(name = nil)
+      return sheets.first unless name
+
+      sheets.find { it.name == name } or
+        raise KeyError.new("no sheet named #{name.inspect}, only #{names.inspect}", receiver: self, key: name)
+    end
+  end
+end

data/lib/imprimatur/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Imprimatur
-  VERSION = '0.2.0'
+  VERSION = '0.4.0'
 end

data/lib/imprimatur/xlsx.rb

@@ -22,10 +22,11 @@ module Imprimatur
     # Builds a workbook. With a path, saves it there and returns the path;
     # without, returns the +.xlsx+ bytes as a binary String.
     #
+    # @param options [Hash] +font:+, +size:+ and +autofit:+, as {Workbook#initialize} takes them
     # @yieldparam book [Workbook]
     # @raise [Imprimatur::Error] the workbook has no sheets, or the file cannot be written
-    def self.build(path = nil)
-      book = Workbook.new
+    def self.build(path = nil, **options)
+      book = Workbook.new(**options)
       yield book
       return book.render unless path
 
@@ -35,8 +36,15 @@ module Imprimatur
 
     # An ordered set of uniquely named sheets.
     class Workbook
-      def initialize
+      # @param font [String, nil] the font of unstyled cells and of styles that
+      #   name none; Calibri without one
+      # @param size [Numeric, nil] its size in points; 11 without one
+      # @param autofit [Boolean] every sheet sizes its columns to its cells, as
+      #   {Sheet#autofit!} does
+      # @raise [Imprimatur::Error] a font name or size Excel rejects
+      def initialize(font: nil, size: nil, autofit: false)
         @native = Native::Workbook.new
+        @native.configure(font&.to_s, size && Float(size), autofit ? true : false)
         @sheets = []
       end
 
@@ -166,9 +174,22 @@ module Imprimatur
         self
       end
 
+      # Sizes the columns without a width of their own to their widest cell
+      # when the workbook is written, estimated as +(characters + 3) x points
+      # / 10+, bold cells one and a half times wider, at most 255.
+      # Formulas are left out.
+      #
+      # @return [self]
+      def autofit!(enabled = true)
+        @native.set_autofit(@index, enabled ? true : false)
+        self
+      end
+
       # Lays the sheet out right to left, column A on the right, as Excel
       # shows sheets in right-to-left languages: Hebrew, Arabic, Persian,
-      # Urdu and the rest.
+      # Urdu and the rest; +false+ keeps it left to right. Without a call, a
+      # sheet is right to left when most of the letters of its name and text
+      # cells are.
       #
       # @return [self]
       def right_to_left!(enabled = true)