imprimatur 0.2.0 → 0.3.0

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

@@ -2,7 +2,7 @@
 
 use std::cell::RefCell;
 
-use imprimatur::doc::{Document, PageSize, Paragraph, Run, Table};
+use imprimatur::doc::{Document, PageSize, Paragraph, Picture, Run, Table};
 use imprimatur::style::Color;
 use magnus::{Error, RModule, RString, Ruby, function, method, prelude::*};
 
@@ -40,10 +40,54 @@ impl NativeDocument {
             &size,
             &[("a4", PageSize::A4), ("letter", PageSize::Letter)],
         )?;
+        Self::page(ruby, rb_self, size, page_numbers)
+    }
+
+    /// A page `width` by `height` points.
+    fn set_page_points(
+        ruby: &Ruby,
+        rb_self: &Self,
+        width: f64,
+        height: f64,
+        page_numbers: bool,
+    ) -> Result<(), Error> {
+        let size = PageSize::custom(width, height).or_raise(ruby)?;
+        Self::page(ruby, rb_self, size, page_numbers)
+    }
+
+    fn page(ruby: &Ruby, rb_self: &Self, size: PageSize, page_numbers: bool) -> Result<(), Error> {
         borrow(ruby, &rb_self.0, "document")?.set_page_size(size).set_page_numbers(page_numbers);
         Ok(())
     }
 
+    fn set_margin(ruby: &Ruby, rb_self: &Self, points: f64) -> Result<(), Error> {
+        borrow(ruby, &rb_self.0, "document")?.set_margin(points).or_raise(ruby)?;
+        Ok(())
+    }
+
+    /// A PNG or JPEG from its bytes, `width` and `height` in points.
+    fn picture(
+        ruby: &Ruby,
+        rb_self: &Self,
+        data: RString,
+        width: Option<f64>,
+        height: Option<f64>,
+        align: Option<String>,
+    ) -> Result<(), Error> {
+        let mut picture = Picture::new(crate::bytes(data)).or_raise(ruby)?;
+        if let Some(width) = width {
+            picture = picture.width(width).or_raise(ruby)?;
+        }
+        if let Some(height) = height {
+            picture = picture.height(height).or_raise(ruby)?;
+        }
+        if let Some(align) = align {
+            picture = picture.align(keyword(ruby, "align", &align, &ALIGNS)?);
+        }
+        borrow(ruby, &rb_self.0, "document")?.picture(picture);
+        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(())
@@ -128,6 +172,9 @@ 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("set_page_points", method!(NativeDocument::set_page_points, 3))?;
+    class.define_method("set_margin", method!(NativeDocument::set_margin, 1))?;
+    class.define_method("picture", method!(NativeDocument::picture, 4))?;
     class.define_method("heading", method!(NativeDocument::heading, 2))?;
     class.define_method("paragraph", method!(NativeDocument::paragraph, 3))?;
     class.define_method("table", method!(NativeDocument::table, 2))?;

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

@@ -8,6 +8,7 @@ mod blocking;
 mod convert;
 mod document;
 mod read;
+mod sheets;
 mod style;
 mod validation;
 
@@ -131,6 +132,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,
@@ -178,6 +204,14 @@ impl std::io::Write for RubyBytes {
 
 /// Mutable access to a wrapped value; Ruby code that calls back into the
 /// same object mid-call gets a `RuntimeError`, not a panic.
+/// A Ruby String's bytes, copied out.
+fn bytes(string: RString) -> Vec<u8> {
+    // 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)]
+    unsafe { string.as_slice() }.to_vec()
+}
+
 fn borrow<'a, T>(ruby: &Ruby, cell: &'a RefCell<T>, what: &str) -> Result<RefMut<'a, T>, Error> {
     cell.try_borrow_mut().map_err(|_| {
         Error::new(
@@ -284,8 +318,9 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
 
     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 +342,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/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, 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,35 @@ 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
 
     # @param text [String]
@@ -40,7 +63,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.3.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)

data/lib/imprimatur.rb

@@ -9,6 +9,7 @@ require_relative 'imprimatur/validation'
 require_relative 'imprimatur/xlsx'
 require_relative 'imprimatur/document'
 require_relative 'imprimatur/reader'
+require_relative 'imprimatur/spreadsheet'
 require_relative 'imprimatur/zip'
 
 # Document authoring with a native core: XLSX workbooks, and PDF and DOCX from
@@ -25,7 +26,7 @@ require_relative 'imprimatur/zip'
 module Imprimatur
   class << self
     # @see Xlsx.build
-    def xlsx(path = nil, &) = Xlsx.build(path, &)
+    def xlsx(path = nil, **, &) = Xlsx.build(path, **, &)
 
     # @param expression [String] such as +"SUM(A1:A3)"+ or +"=A1*2"+
     # @return [Formula]
@@ -78,18 +79,29 @@ module Imprimatur
     # (+heading+, +paragraph+) with their +:bounds+ in points from the
     # page's top-left corner; a workbook's +:sheets+ of +:rows+ of typed
     # +:cells+ (+number+, +date+, +bool+, +text+, +error+, +formula+) and
-    # +:comments+; a Word document's +:blocks+ (+heading+, +paragraph+,
+    # +:comments+, and from an +.xlsx+ its +:columns+ widths and data
+    # +:validations+; a Word document's +:blocks+ (+heading+, +paragraph+,
     # +list_item+, +table+), their bold, italic and linked +:marks+ as byte
     # ranges. Dates are ISO 8601 strings: Excel's have no time zone.
     #
     #   sheet = Imprimatur.content('sales.xlsx')[:sheets].first
     #   sheet[:rows][1][:cells]  # => [{cell: "A2", type: "text", value: "North"}, ...]
     #
-    # Takes the arguments of {.markdown}, and raises as it does.
+    # Takes the arguments of {.markdown}, and raises as it does. With
+    # +styles: true+ each sheet also lists its formatted cells' +:styles+:
+    # font, size, bold, italic, underline, ARGB color and fill, alignment,
+    # wrap, border and number format.
     #
     # @return [Hash] with symbol keys; +:format+ is +"pdf"+, +"xlsx"+ or +"docx"+
     def content(document, ...) = Reader.content(document, ...)
 
+    # A workbook's sheets and their values, read from the same documents
+    # {.markdown} takes (+.xlsx+, +.xls+, +.ods+); see {Spreadsheet}.
+    #
+    # @return [Spreadsheet]
+    # @raise [UnsupportedDocument] a PDF, a Word document or another format
+    def spreadsheet(document, ...) = Spreadsheet.open(document, ...)
+
     # A document's images, as files: a PDF's, once each, from the first page
     # that draws them (JPEG and JPEG 2000 as stored, fax scans as TIFF, raw
     # pixels as PNG); a Word or Excel document's media. A scanned PDF gives