imprimatur 0.1.0-x86_64-linux-gnu → 0.3.0-x86_64-linux-gnu

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 798102aec61182559eb546a4c521cb619b846d18aa1ea46e14de58f882527abc
-  data.tar.gz: 63d882d47e8f023fd9fda2442d2ce24542ab72b2e8c7a787ab9601e92cd620a2
+  metadata.gz: f23670009061b9f9bf1faf3d9c9400ef4c6a136561aefe2ab3d67c197d91fbe5
+  data.tar.gz: 2cd106d5795727dcc12188cef98a6d8ce9fe19374aa0611dedcaa1184b1a6028
 SHA512:
-  metadata.gz: ede8b20ea6972b6c7490e89d0d992374f235d70fab33d6f75c8cb936b98ff396272a2227bba13605c80b71f47496668ebf8c654a666985fead86e4e5e8d97a04
-  data.tar.gz: eee7e1d44a83c4b8ed38efad194d5ca301999362f306700a871323c0cd0fd9648c322ba64b817c0e60b2116c8cb2bf014c312212d85ef26ce940f49475ce2090
+  metadata.gz: 15c21dc23dacbbea052ab4115fca4a6a35385474af9136b1bada72b3c374b6fcedbd521cd6c6741dd392ccf92b5125f861159ec822d4c26a342e201b4b5e827f
+  data.tar.gz: 9a189350ce6ac19418097246554a94dcd0f0d994c26ab47f3632caca45ca2fc8045bd81bfea53da0f95c9d62cbe1656ec5feccccad91a414d731621c13d6c467

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## [0.3.0](https://github.com/seuros/imprimatur/compare/v0.2.0...v0.3.0) (2026-10-17)
+
+
+### Features
+
+* a spreadsheet's sheets give their comments, columns, validations and styles ([1797632](https://github.com/seuros/imprimatur/commit/1797632aad2948c1c0a493501de3684187062246))
+* draw PNG and JPEG pictures, on pages of any size ([419524a](https://github.com/seuros/imprimatur/commit/419524afe36bbb06e3ef0ecb48a4fab4f80fb989))
+* **font:** load static TrueType fonts and metrics ([fd85e3d](https://github.com/seuros/imprimatur/commit/fd85e3d78ece99506b2dde2c61bab6997cb20d21))
+* read column widths, data validations and cell styles ([2930964](https://github.com/seuros/imprimatur/commit/2930964cde82cc998113aa83336a547cda8bd9f8))
+* read whether a list validation shows its drop-down ([b75ef53](https://github.com/seuros/imprimatur/commit/b75ef530ef790876c58e40bb02dfc7257a48aab5))
+* read workbooks as typed rows with Imprimatur::Spreadsheet ([927033b](https://github.com/seuros/imprimatur/commit/927033bb5ef9725c38726bc0785bbd90be8f1dc8))
+* size columns to their cells, and give workbooks a font ([c88a058](https://github.com/seuros/imprimatur/commit/c88a0580a7ba052c4994faf4f53b42e75f48f587))
+* write right-to-left text in its own direction ([137206e](https://github.com/seuros/imprimatur/commit/137206e08622f33ae21b6e52013e3ec7b071bb6b))
+
+
+### Bug Fixes
+
+* build the gem with every feature of the crate ([7b48599](https://github.com/seuros/imprimatur/commit/7b485998abdb8b14b59e22a6ff97ca7dec143986))
+* **font:** put the TrueType loader behind a `fonts` feature ([f9d1915](https://github.com/seuros/imprimatur/commit/f9d1915f3c98c0c7351477c6e8f21799d01e02f9))
+* read right-to-left PDF text in its page's direction ([ca173ef](https://github.com/seuros/imprimatur/commit/ca173efd019513f25df004feafeda0e8551e64c0))
+* show numbers with their format's decimals and grouping ([d0089ee](https://github.com/seuros/imprimatur/commit/d0089ee2dcf364ac32c7f92dc6c3af9aa6a9e9cb))
+
+## [0.2.0](https://github.com/seuros/imprimatur/compare/v0.1.0...v0.2.0) (2026-10-16)
+
+
+### Features
+
+* read legacy XLS and ODS workbooks ([96b86fa](https://github.com/seuros/imprimatur/commit/96b86faab8eb04b80d33885c61b17ebad4f1f63a))
+* zip archive comments and entry listings ([a87f223](https://github.com/seuros/imprimatur/commit/a87f22330859ee4a583943ddbf107571cca9e841))
+* zip archives of any files ([d5ea579](https://github.com/seuros/imprimatur/commit/d5ea579ae1fc80a8ec6a1b213f442d490ededfba))
+
 ## 0.1.0 (2026-10-16)
 
 

data/README.md

@@ -102,6 +102,21 @@ columns past its end are left unstyled:
 sheet.row "", "", "", "Notes", style: [yellow] * 3
 ```
 
+The workbook can have a font of its own, for unstyled cells and for styles
+that name no font or size, and size its columns to their cells:
+
+```ruby
+Imprimatur.xlsx("export.xlsx", font: "Arial", size: 10, autofit: true) do |book|
+  book.sheet("Orders") { it.row "Supplier", "Amount", style: header }
+  book.sheet("Notes").autofit!(false)          # this one keeps Excel's widths
+end
+```
+
+`autofit` (or `sheet.autofit!`) sizes each column without a width of its own
+to its widest cell, estimated as `(characters + 3) × points / 10`,
+bold cells one and a half times wider, at most 255. A text counts its longest
+line, a date `yyyy-mm-dd`; formulas are left out, their results unknown.
+
 ## Validation and comments
 
 ```ruby
@@ -137,22 +152,23 @@ shown all the time with `visible: true`. The cell need not hold a value.
 ```ruby
 rtl = Imprimatur.style(direction: :rtl)
 
-book.sheet("مبيعات") do |sheet|                        # Arabic
-  sheet.right_to_left!                                 # column A on the right
-  sheet.row "المنطقة", "الشمال", style: rtl
+book.sheet("مبيعات") do |sheet|                        # Arabic: right to left
+  sheet.row "المنطقة", "الشمال", style: rtl              # column A on the right
 end
 
-book.sheet("מכירות") do |sheet|                        # Hebrew
-  sheet.right_to_left!
-  sheet.row "אזור", "צפון", style: rtl
+book.sheet("Suppliers") do |sheet|
+  sheet.right_to_left!                                 # told so: a Hebrew layout
+  sheet.row "אזור", "Region"
 end
 ```
 
 Text in any right-to-left language needs nothing special: Hebrew, Yiddish,
 Arabic, Persian, Urdu, Pashto, Sindhi, Kurdish (Sorani), Uyghur, Syriac,
-Dhivehi (Thaana), N'Ko, Adlam and the rest. `right_to_left!` lays the sheet
-out the way Excel does for them, and `direction: :rtl` fixes a cell's reading
-order instead of letting Excel infer it from its first letter.
+Dhivehi (Thaana), N'Ko, Adlam and the rest. A sheet whose letters (its name
+and text cells) are mostly right to left is laid out the way Excel does for
+them, column A on the right; `right_to_left!` and `right_to_left!(false)`
+decide instead. `direction: :rtl` fixes a cell's reading order instead of
+letting Excel infer it from its first letter.
 
 Not yet: merged cells, frozen panes, streaming for very large sheets.
 
@@ -171,6 +187,7 @@ doc.paragraph do |p|
 end
 doc.paragraph "Figures are unaudited.", italic: true, align: :center
 doc.table [["Region", "Q1"], ["North", 12_500.5]], header: true
+doc.image "chart.png", width: 300, align: :center
 doc.page_break
 doc.paragraph "Appendix."
 
@@ -178,15 +195,26 @@ doc.save_pdf("report.pdf")
 doc.save_docx("report.docx")
 
 Imprimatur.pdf("memo.pdf") { it.paragraph "Or in one go." }    # Imprimatur.docx alike
+Imprimatur.pdf(page_size: [200, 200], margin: 10) { it.image qr_png, width: 180 }
 ```
 
 - Headings 1 to 3 (real Word heading styles in DOCX), paragraphs of runs
   (bold, italic, underline, color), alignment, `\n` line breaks and tabs.
 - Tables: equal columns, borders, a shaded header row that repeats on every
   page; cells are converted with `to_s`.
-- Page breaks, A4 or Letter, `1 / N` page numbers.
-- `direction: :rtl` makes a right-to-left paragraph (right aligned, and
-  `w:bidi` in DOCX).
+- Pictures: PNG or JPEG (a path, the bytes or an IO), at `width:` or
+  `height:` points (the other follows), or else at 96 pixels an inch, never
+  larger than the page; `align:` like a paragraph. In PDF a JPEG and an
+  opaque PNG are stored as they are, a PNG with alpha gets a soft mask.
+  Interlaced PNGs are refused.
+- Page breaks; A4, Letter or `page_size: [width, height]` in points (36 to
+  1584); `margin:` in points (one inch unless set); `1 / N` page numbers.
+- Right to left without being told: a paragraph, heading or table cell
+  reads in the direction of its first letter (right aligned, and `w:bidi` in
+  DOCX), figures alone in their table's or document's, each run in its own;
+  a mostly right-to-left table has its first column on the right, and a
+  mostly right-to-left document its pages laid out right to left.
+  `direction: :rtl` or `:ltr` decides for a paragraph.
 
 **PDF text is Latin only for now.** PDFs use the standard Helvetica fonts,
 which carry Windows-1252: English and Western European text, curly quotes,
@@ -197,8 +225,8 @@ PDF, are the next step.
 
 ## Reading: documents as Markdown
 
-The other direction: a PDF, XLSX or DOCX printed as Markdown, for search
-indexes and language models.
+The other direction: a PDF, a workbook (XLSX, legacy XLS, ODS) or a DOCX
+printed as Markdown, for search indexes and language models.
 
 ```ruby
 Imprimatur.markdown("audit.pdf")              # a path
@@ -213,17 +241,28 @@ end
 ```
 
 - **PDF**: the text layer, placed glyph by glyph (fonts, encodings and
-  ToUnicode maps, forms, rotated pages), in reading order (right-to-left
-  lines too: Hebrew, Arabic, Persian, Urdu, Syriac, Dhivehi, N'Ko, Adlam,
-  their vowel marks kept on their letters), with headings by font size, hyphenated line breaks rejoined,
-  presentation forms (`fi`, Arabic contextual forms) as plain letters, and
-  running headers and footers left out. Pages after the first start with
-  `<!-- page N -->`. Encrypted PDFs open when the user password is empty, as
-  it is for documents that only restrict printing or copying (RC4, AES-128,
-  AES-256).
+  ToUnicode maps, forms, rotated pages), in reading order, with headings by
+  font size, hyphenated line breaks rejoined, presentation forms (`fi`,
+  Arabic contextual forms) as plain letters, and running headers and
+  footers left out. Pages after the first start with `<!-- page N -->`.
+  Encrypted PDFs open when the user password is empty, as it is for
+  documents that only restrict printing or copying (RC4, AES-128, AES-256).
+- **Right to left in PDFs** (Hebrew, Arabic, Persian, Urdu, Syriac,
+  Dhivehi, N'Ko, Adlam): a PDF records where glyphs go, not the order they
+  read in, so each line is put back in order the way the Unicode
+  bidirectional algorithm laid it out, with its page's direction for
+  context. An Arabic page's table rows read from the right, figures
+  included; an Arabic or Hebrew name in an English line reads forwards
+  inside that line; numbers stay whole (`2024-03-15`, `1,250.50`, `50%`,
+  `+98 21 5555 1234`, Arabic-Indic and Persian digits); vowel marks stay on
+  their letters. Not yet: pages set in several columns, whose lines run
+  together whatever their direction.
 - **XLSX**: each sheet as a table under its name, values as Excel shows them
   (dates as dates, percentages, 15 significant digits), formulas without a
   cached result as `=FORMULA`, then the sheet's comments.
+- **XLS** (Excel 97–2003, and Excel 5.0/95 in Western European code pages)
+  and **ODS** (LibreOffice, OpenOffice): the same, sheet by sheet; an ODS
+  number keeps the text it shows. Legacy `.xls` comments are left out.
 - **DOCX**: headings (from styles and outline levels), bulleted and numbered
   lists, bold, italic, links, tables, text boxes; deleted text and field
   codes left out.
@@ -237,7 +276,7 @@ Documents are untrusted input, so reads are bounded: `max_bytes:` (512 MiB),
 `Imprimatur::LimitExceeded`. Reading runs without the GVL: other threads and
 fibers keep running, and `Timeout` or `Thread#raise` cancels it.
 `Imprimatur::PasswordRequired` and `Imprimatur::UnsupportedDocument` (legacy
-`.xls` and `.doc`, `.xlsb`, presentations) are the other errors to expect.
+`.doc`, `.xlsb`, presentations) are the other errors to expect.
 
 ### Structure and images
 
@@ -258,6 +297,15 @@ Imprimatur.content("audit.pdf")[:pages].first[:blocks].first
 #     bounds: {left: 72.0, top: 61.4, right: 290.1, bottom: 85.0}}
 ```
 
+An `.xlsx` sheet also gives its `columns` widths and data `validations`, and
+with `styles: true` the look of each formatted cell, empty ones included:
+
+```ruby
+sheet = Imprimatur.content("template.xlsx", styles: true)[:sheets].first
+sheet[:validations].first  # => {range: "G2:G1000", type: "list", formula1: "\"Yes,No\"", ...}
+sheet[:styles].first       # => {cell: "A1", font: "Arial", size: 12.0, bold: true, fill: "FF808080", ...}
+```
+
 `Imprimatur.images` hands over every image as a file: a PDF's JPEG and JPEG
 2000 as stored, fax scans as TIFF, raw pixels as PNG (soft masks as alpha),
 with the page and place each is drawn at; a Word or Excel document's media,
@@ -270,6 +318,58 @@ Imprimatur.images("scan.pdf") do |image|
 end
 ```
 
+### Workbooks as rows
+
+For importing uploads, `Imprimatur.spreadsheet` reads an `.xlsx`, `.xls` or
+`.ods` into rows of Ruby values: Strings, Integers for whole numbers shown
+without a decimal point or a percent sign, Floats, `true`/`false`, Dates,
+DateTimes for a time of day, and `nil` for an empty cell or a formula never
+computed.
+
+```ruby
+book = Imprimatur.spreadsheet(upload.download)   # a path, the bytes or an IO
+book.names                                      # => ["Suppliers", "Countries"]
+book.sheet.rows.first                           # => ["Instructions: one a row"]
+
+book.sheet("Suppliers").parse(clean: true, name: "Company Name", since: "Since")
+# => [{ name: "Acme", since: #<Date: 2024-03-15> }, ...]
+```
+
+`parse` finds the header row among the first 100 (`header_rows:`), the first
+holding every header, and maps the rows under it. `clean: true` strips control
+characters and the whitespace at both ends of every String. Without such a row
+it raises `Imprimatur::HeaderRowNotFound`, whose `missing` lists the headers the
+closest row lacks.
+
+Each sheet also has its `comments`, its `columns` (runs of widths, and whether
+hidden) and its `validations`, as `Imprimatur.content` gives them. Opened with
+`styles: true`, it has every formatted cell's look too:
+
+```ruby
+sheet = Imprimatur.spreadsheet("template.xlsx", styles: true).sheet("BOM")
+sheet.validation("G2:G1000")   # => { range: "G2:G1000", type: "list", formula1: "Lists!$A$1:$A$9", ... }
+sheet.style("A1")              # => { cell: "A1", font: "Arial", bold: true, fill: "FFDDEEFF", ... }
+```
+
+## Zip archives
+
+Archives of any files, for what is not a document (an export of an order's
+files, a download to unpack). Entries keep their modification times and
+comments, files are streamed from disk, and archives past 4 GiB use ZIP64;
+reading is bounded per entry. Both run without the GVL.
+
+```ruby
+Imprimatur::Zip.write("export.zip") do |zip|
+  zip.add_file("contracts/0contract.pdf", "/tmp/contract.pdf", comment: "Contract")
+  zip.add("manifest.json", JSON.generate(manifest))
+end
+
+Imprimatur::Zip.open("geolite.zip") do |zip|
+  csv = zip.read(zip.glob("**/*-Locations-en.csv").first) # max_bytes: 1 GiB by default
+  zip.extract("README.txt", "/tmp/readme.txt")
+end
+```
+
 ## Command line
 
 The same reader as a static binary, for scripts and agents that would

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/error.rb

@@ -9,11 +9,12 @@ module Imprimatur
   # A PDF without a text layer: its pages are images (scans), which need OCR.
   class NoTextLayer < Error; end
 
-  # A PDF encrypted with a user password; only an empty one is tried.
+  # A PDF encrypted with a user password (only an empty one is tried), or
+  # an encrypted legacy +.xls+.
   class PasswordRequired < Error; end
 
-  # A format {Imprimatur.markdown} does not read: legacy +.xls+ and +.doc+,
-  # binary +.xlsb+, presentations, anything not a PDF, XLSX or DOCX.
+  # A format {Imprimatur.markdown} does not read: legacy +.doc+, binary
+  # +.xlsb+, presentations, anything not a PDF, XLSX, XLS, ODS or DOCX.
   class UnsupportedDocument < Error; end
 
   # The read hit one of its limits (size, decompressed size, nesting, time),

data/lib/imprimatur/reader.rb

@@ -14,15 +14,15 @@ module Imprimatur
   module Reader
     # File signatures a document's bytes start with; a String that starts
     # with neither is taken for a path.
-    SIGNATURES = ["%PDF-".b, "PK\x03\x04".b, "PK\x05\x06".b].freeze
+    SIGNATURES = ["%PDF-".b, "PK\x03\x04".b, "PK\x05\x06".b, "\xD0\xCF\x11\xE0\xA1\xB1\x1A\xE1".b].freeze
     private_constant :SIGNATURES
 
     # @see Imprimatur.markdown
     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.1.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/zip.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Imprimatur
+  # Zip archives of any files: entries written with their modification times
+  # and comments (ZIP64 when large), read one at a time within a size limit.
+  # Compressing and reading run without the GVL.
+  #
+  #   Imprimatur::Zip.write('export.zip') do |zip|
+  #     zip.add_file('contracts/0contract.pdf', '/tmp/contract.pdf', comment: 'Contract')
+  #     zip.add('manifest.json', JSON.generate(manifest))
+  #   end
+  #
+  #   Imprimatur::Zip.open('geolite.zip') do |zip|
+  #     zip.read(zip.glob('**/*-Locations-en.csv').first)
+  #   end
+  module Zip
+    # Bytes an entry may hold once decompressed by default: 1 GiB.
+    MAX_ENTRY_BYTES = 1024**3
+
+    # An entry added to an archive being written.
+    Added = Data.define(:name, :comment)
+
+    # An entry of an archive being read, as its directory states it.
+    Entry = Data.define(:name, :size, :compressed_size, :crc32, :comment)
+
+    # Writes an archive at +path+, the block adding its entries. On an
+    # error, the partial file is removed.
+    #
+    # @yieldparam zip [Writer]
+    # @return the path
+    def self.write(path)
+      writer = Writer.new(path)
+      yield writer
+      writer.finish
+      path
+    rescue Exception # any failure, an interrupt included: the partial file goes, then the error
+      FileUtils.rm_f(path.to_s) if writer
+      raise
+    end
+
+    # The archive at +path+.
+    #
+    # @yieldparam zip [Reader] when a block is given
+    # @return [Reader, Object] the reader, or what the block returns
+    # @raise [Errno::ENOENT] when there is no such file
+    # @raise [Error] when it is no zip
+    def self.open(path)
+      reader = Reader.new(path)
+      block_given? ? yield(reader) : reader
+    end
+
+    # Adds entries to an archive being written; see {Zip.write}.
+    class Writer
+      # @return [Array<Added>] the entries added so far, in order
+      attr_reader :entries
+
+      def initialize(path)
+        @native = Native::ZipWriter.new(path.to_s)
+        @entries = []
+      end
+
+      # Adds the file at +source+ as +name+, streamed from disk, with its
+      # modification time.
+      def add_file(name, source, comment: nil)
+        @native.add_file(name.to_s, source.to_s, comment&.to_s)
+        @entries << Added.new(name: name.to_s, comment: comment&.to_s)
+        self
+      end
+
+      # Adds +data+ as +name+, dated now.
+      def add(name, data, comment: nil)
+        @native.add(name.to_s, data.to_s.b, comment&.to_s)
+        @entries << Added.new(name: name.to_s, comment: comment&.to_s)
+        self
+      end
+
+      # The archive's own comment, shown by most zip tools.
+      def comment=(comment)
+        @native.comment = comment.to_s
+      end
+
+      # @api private
+      def finish = @native.finish
+    end
+
+    # An archive's entries, by name; see {Zip.open}.
+    class Reader
+      # @return [Array<String>] the entries' names, in the archive's order
+      attr_reader :names
+
+      def initialize(path)
+        raise Errno::ENOENT, path.to_s unless File.file?(path.to_s)
+
+        @native = Native::ZipReader.new(path.to_s)
+        @names = @native.names.freeze
+      end
+
+      # Each entry's name, sizes, CRC-32 and comment, nothing decompressed.
+      #
+      # @return [Array<Entry>]
+      def entries
+        @native.entries.map { |row| Entry.new(*row) }
+      end
+
+      # The names matching a shell pattern, +**/+ spanning folders.
+      def glob(pattern) = names.select { File.fnmatch?(pattern, it, File::FNM_PATHNAME | File::FNM_EXTGLOB) }
+
+      # The entry's bytes, binary.
+      #
+      # @raise [KeyError] for an entry the archive does not have
+      # @raise [LimitExceeded] when it holds more than +max_bytes+
+      def read(name, max_bytes: MAX_ENTRY_BYTES)
+        @native.read(name.to_s, Integer(max_bytes)) or raise KeyError, "no entry #{name} in the archive"
+      end
+
+      # Writes the entry to +path+, streamed; returns +path+.
+      #
+      # @raise (see #read)
+      def extract(name, path, max_bytes: MAX_ENTRY_BYTES)
+        @native.extract(name.to_s, path.to_s, Integer(max_bytes)) or raise KeyError, "no entry #{name} in the archive"
+        path
+      end
+    end
+  end
+end

data/lib/imprimatur.rb

@@ -9,6 +9,8 @@ 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
 # one document model.
@@ -24,7 +26,7 @@ require_relative 'imprimatur/reader'
 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]
@@ -46,7 +48,7 @@ module Imprimatur
     # As {.pdf}, rendered as DOCX.
     def docx(path = nil, **options, &) = Document.build(:docx, path, **options, &)
 
-    # A PDF, XLSX or DOCX as Markdown: a PDF's text layer (headings by font
+    # A PDF, workbook (XLSX, XLS, ODS) or DOCX as Markdown: a PDF's text layer (headings by font
     # size, running headers and footers left out, pages marked with
     # +<!-- page N -->+), each sheet of a workbook as a table, a Word
     # document's headings, lists, emphasis, links and tables. The format is
@@ -67,7 +69,7 @@ module Imprimatur
     # @return [String] Markdown, UTF-8
     # @raise [NoTextLayer] a PDF of scanned pages: run OCR instead
     # @raise [PasswordRequired] a PDF that needs a password to open
-    # @raise [UnsupportedDocument] not a PDF, XLSX or DOCX
+    # @raise [UnsupportedDocument] not a PDF, XLSX, XLS, ODS or DOCX
     # @raise [LimitExceeded] the document is too large, too deep or too slow
     # @raise [Error] a damaged document
     def markdown(document, ...) = Reader.markdown(document, ...)
@@ -77,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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: imprimatur
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: x86_64-linux-gnu
 authors:
 - Abdelkader Boudih
@@ -11,7 +11,8 @@ date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: 'A Ruby DSL over a native core that writes Excel workbooks, and PDF and
   Word documents from one model, with its own XML, zip and PDF writers: no third-party
-  format stack. Precompiled for Linux, macOS and FreeBSD; CRuby only.'
+  format stack. It reads PDF, XLSX, XLS, ODS and DOCX back: as Markdown, as typed
+  structure, and their images. Precompiled for Linux, macOS and FreeBSD; CRuby only.'
 email:
 - terminale@gmail.com
 executables: []
@@ -28,10 +29,12 @@ files:
 - lib/imprimatur/formula.rb
 - lib/imprimatur/native.rb
 - lib/imprimatur/reader.rb
+- lib/imprimatur/spreadsheet.rb
 - lib/imprimatur/style.rb
 - lib/imprimatur/validation.rb
 - lib/imprimatur/version.rb
 - lib/imprimatur/xlsx.rb
+- lib/imprimatur/zip.rb
 homepage: https://github.com/seuros/imprimatur
 licenses:
 - BSD-3-Clause
@@ -59,5 +62,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.20
 specification_version: 4
-summary: XLSX, PDF and DOCX authoring with a Ruby DSL. Let it be printed.
+summary: XLSX, PDF and DOCX authoring, and office documents read back. Let it be printed.
 test_files: []