imprimatur 0.1.0-aarch64-linux-gnu → 0.2.0-aarch64-linux-gnu

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96b43fb07eaa3f15a32bc14ecfce9131ae1391369cec190e8b4458b56f40e14f
-  data.tar.gz: fd7e35e9d7d87c1523cb563acd16b189a3168e816daeac1495bd507e0e4d6235
+  metadata.gz: a1dcd8e194d2f7cf4096350af23ef9a629d8b9bb0e32ec88cd60edbebb0e190b
+  data.tar.gz: d5a960d8c7902c18b4be2b99553d50f95fdb1eb18bf8f674191de123a2f081b0
 SHA512:
-  metadata.gz: 5a5443f9a772157fea30caaa758cec11fdeaa42a262c7b0fe0f260d67d5cd0892ab96e02cb16bb69e5bd1316d7b5acf7f8aaebba01fcba8a40b5292f4f33f657
-  data.tar.gz: e02d379d59b7682b24f86f51408f3f1a932b2f49579b57959cd3e8cc8954f4141533f0d46727c8887bb6e832c1ad1d5f56d1af3b745e2435a73d6fa76c1c428b
+  metadata.gz: f27b7635c4c624b33adaedb532afd279d594117a2e596de2291d180158be82e90e34c5f19a1596c31a13b75c073f23331ec846f61751d8c70d48fcd9750bac5d
+  data.tar.gz: 9a3d3ae03b027bb7e3044779b63760cfb99889664d21acb08a78c065181282cf6e35f9d6cab6bb9af2cb19efa649304d34db2713adc913759ee32677765bb939

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [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

@@ -197,8 +197,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
@@ -215,8 +215,8 @@ 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
+  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,
@@ -224,6 +224,9 @@ end
 - **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 +240,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
 
@@ -270,6 +273,25 @@ Imprimatur.images("scan.pdf") do |image|
 end
 ```
 
+## 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/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,7 +14,7 @@ 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

data/lib/imprimatur/version.rb

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

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,7 @@ require_relative 'imprimatur/validation'
 require_relative 'imprimatur/xlsx'
 require_relative 'imprimatur/document'
 require_relative 'imprimatur/reader'
+require_relative 'imprimatur/zip'
 
 # Document authoring with a native core: XLSX workbooks, and PDF and DOCX from
 # one document model.
@@ -46,7 +47,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 +68,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, ...)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: imprimatur
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: aarch64-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: []
@@ -32,6 +33,7 @@ files:
 - 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 +61,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: []