imprimatur 0.1.0-aarch64-linux-gnu

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 96b43fb07eaa3f15a32bc14ecfce9131ae1391369cec190e8b4458b56f40e14f
+  data.tar.gz: fd7e35e9d7d87c1523cb563acd16b189a3168e816daeac1495bd507e0e4d6235
+SHA512:
+  metadata.gz: 5a5443f9a772157fea30caaa758cec11fdeaa42a262c7b0fe0f260d67d5cd0892ab96e02cb16bb69e5bd1316d7b5acf7f8aaebba01fcba8a40b5292f4f33f657
+  data.tar.gz: e02d379d59b7682b24f86f51408f3f1a932b2f49579b57959cd3e8cc8954f4141533f0d46727c8887bb6e832c1ad1d5f56d1af3b745e2435a73d6fa76c1c428b

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0 (2026-10-16)
+
+
+### Features
+
+* extract from forgejo ([d6c0937](https://github.com/seuros/imprimatur/commit/d6c0937b8cbdda8f6770f43e0423ef6aa4c8c646))

data/LICENSE.txt

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Abdelkader Boudih
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,314 @@
+# imprimatur
+
+*Imprimatur*: "let it be printed", the stamp a censor put on a book before it
+could go to press. This one stamps spreadsheets, PDFs and Word documents. No heresy reaches the printer: an invalid sheet name, a NaN or
+a 40,000-character cell is refused at the door, not discovered by Excel's
+"We found a problem with some content".
+
+- **A Ruby DSL over a native core.** The core is also published on its own,
+  as `imprimatur` on crates.io; the gem wraps it.
+- **No third-party format stack.** The XML writer and the zip container are
+  written here, from ECMA-376 and the zip specification; only deflate
+  (`miniz_oxide`) and CRC-32 (`crc32fast`) come from crates.
+- **Deterministic.** The same document always gives the same bytes.
+- **Native only.** CRuby 4.0+. No pure Ruby fallback, no JRuby, no TruffleRuby.
+
+```ruby
+require "imprimatur"
+
+Imprimatur.xlsx("budget.xlsx") do |book|
+  book.sheet("Budget") do |sheet|
+    sheet.row "Line item", "Promised", "Delivered"
+    sheet.row "High-speed rail", 1_000_000_000, 0
+    sheet.row "Bridge to nowhere", 398_000_000, 398_000_000
+    sheet.row "Total", Imprimatur.formula("SUM(B2:B3)"), Imprimatur.formula("SUM(C2:C3)")
+  end
+end
+```
+
+## Installation
+
+```ruby
+gem "imprimatur"
+```
+
+Precompiled gems ship for Linux (x86_64 and aarch64, glibc 2.34+ and musl),
+macOS 13+ (arm64, x86_64) and FreeBSD 15.1 (amd64): nothing to compile.
+Anywhere else, the source gem compiles the extension on install, with the
+toolchain from [rustup.rs](https://rustup.rs) (1.99+).
+
+## Workbooks
+
+```ruby
+bytes = Imprimatur.xlsx do |book|       # no path: returns the .xlsx bytes
+  sheet = book.sheet("Sales")
+  sheet.row "Region", "Q1", "On target"
+  sheet.row "North", 12.5, true
+  sheet << ["South", nil, false]         # nil leaves a cell empty
+  sheet.write(9, 2, "C10")               # zero-based row and column
+  sheet.next_row                         # => 10
+end
+
+send_data bytes, filename: "sales.xlsx", type: :xlsx
+```
+
+| Ruby value | Cell |
+|---|---|
+| `String` | text, up to 32,767 characters |
+| `Integer` | number, up to 2\*\*53 (beyond, Excel would store a different number: `RangeError`) |
+| `Float` | number; NaN and infinity are refused |
+| `BigDecimal`, `Rational` | number, as its `to_f`: Excel keeps every number as a double |
+| `true`, `false` | boolean |
+| `Imprimatur.formula("SUM(A1:A3)")` | formula, computed when the workbook opens |
+| `Date`, `Time`, `DateTime` | date; its wall-clock fields, no time zone (1900-01-01 to 9999-12-31) |
+| `ActiveSupport::TimeWithZone` | as `Time`, the wall clock of its zone |
+| `nil` | nothing |
+
+Dates without a number format of their own show as `yyyy-mm-dd`, or
+`yyyy-mm-dd hh:mm:ss` with a time of day.
+
+Anything else raises `TypeError`. Excel's own limits raise `Imprimatur::Error`:
+sheet names (31 characters, no `[ ] : * ? / \`, unique ignoring case, not
+`History`), 1,048,576 rows, 16,384 columns. A rejected row writes nothing.
+
+## Styles
+
+```ruby
+header = Imprimatur.style(bold: true, color: "#FFFFFF", fill: "#1F4E79", align: :center, border: :thin)
+money  = Imprimatur.style(number_format: "#,##0.00")
+
+Imprimatur.xlsx("report.xlsx") do |book|
+  book.sheet("Report") do |sheet|
+    sheet.column_widths 24, 14                 # characters; nil skips a column
+    sheet.row "Line item", "Amount", style: header
+    sheet.row "Consulting", nil
+    sheet.write(1, 1, 98_000, style: money)
+  end
+end
+```
+
+`Imprimatur.style` takes `number_format:`, `bold:`, `italic:`, `underline:`,
+`color:` and `fill:` (`"#RRGGBB"`), `font:` (`"Arial"`; Calibri by default),
+`size:` (points, in steps of 0.5; 11 by default), `align:` (`:left`,
+`:center`, `:right`), `valign:` (`:top`, `:center`, `:bottom`), `direction:`
+(`:ltr`, `:rtl`), `wrap:` and `border:` (`:thin`, `:medium`, `:thick`). A
+style is checked once, when it is built, and every cell using it shares one
+entry in the workbook.
+
+`style:` also takes an Array, one style (or `nil`) per column from A; the
+columns past its end are left unstyled:
+
+```ruby
+sheet.row "", "", "", "Notes", style: [yellow] * 3
+```
+
+## Validation and comments
+
+```ruby
+yes_no = Imprimatur.validation(list: %w[Yes No])     # built once, shared
+
+book.sheet("Items") do |sheet|
+  sheet.row "Name", "Unit", "Supplier", "Raw material"
+  sheet.comment "A1", "Required. Up to 100 characters.", author: "Instructions"
+  sheet.validate "A2:A1000", formula: "LEN(A2)<=100", alert: :warning, prompt: "Up to 100 characters"
+  sheet.validate "B2:B1000", list: %w[g kg m l ea]
+  sheet.validate "C2:C1000", list: "Suppliers!$A$2:$A$500",
+                             error_title: "Unknown supplier", error: "Pick one from the list."
+  sheet.validate "D2:D1000", yes_no
+end
+```
+
+`list:` is the drop-down's values, or a range holding them (another sheet's
+too). Values typed into the rule stay under Excel's 255 characters, commas
+between them included, and cannot contain a comma; longer lists belong in a
+range. `formula:` accepts a value when it is true, its references relative to
+the range's top-left cell. `alert:` decides what an invalid value meets:
+`:stop` (refused, the default), `:warning`, `:information`, or `:off` (accepted;
+a list still offers its drop-down). `prompt:` and `prompt_title:` show while a
+cell is selected, `error:` and `error_title:` in the alert. Ranges are A1 text;
+one overlapping a range already validated is refused, since Excel applies a
+single rule per cell.
+
+A comment is an Excel note: hidden until the pointer rests on its cell, or
+shown all the time with `visible: true`. The cell need not hold a value.
+
+## Right to left
+
+```ruby
+rtl = Imprimatur.style(direction: :rtl)
+
+book.sheet("مبيعات") do |sheet|                        # Arabic
+  sheet.right_to_left!                                 # column A on the right
+  sheet.row "المنطقة", "الشمال", style: rtl
+end
+
+book.sheet("מכירות") do |sheet|                        # Hebrew
+  sheet.right_to_left!
+  sheet.row "אזור", "צפון", style: rtl
+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.
+
+Not yet: merged cells, frozen panes, streaming for very large sheets.
+
+## Documents: PDF and DOCX
+
+One document, two formats:
+
+```ruby
+doc = Imprimatur::Document.new(page_size: :a4, page_numbers: true)
+doc.heading "Quarterly report"
+doc.heading "Sales", level: 2
+doc.paragraph do |p|
+  p.text "Revenue was "
+  p.text "up 12%", bold: true, color: "#1F7A1F"
+  p.text " this quarter."
+end
+doc.paragraph "Figures are unaudited.", italic: true, align: :center
+doc.table [["Region", "Q1"], ["North", 12_500.5]], header: true
+doc.page_break
+doc.paragraph "Appendix."
+
+doc.save_pdf("report.pdf")
+doc.save_docx("report.docx")
+
+Imprimatur.pdf("memo.pdf") { it.paragraph "Or in one go." }    # Imprimatur.docx alike
+```
+
+- 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).
+
+**PDF text is Latin only for now.** PDFs use the standard Helvetica fonts,
+which carry Windows-1252: English and Western European text, curly quotes,
+dashes, the euro sign. Anything else (Arabic, Hebrew, Greek, CJK, emoji) raises
+`Imprimatur::Error` naming the character, never a `?`. DOCX carries any
+script. Embedded TrueType fonts, and with them every script and proper RTL in
+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.
+
+```ruby
+Imprimatur.markdown("audit.pdf")              # a path
+Imprimatur.markdown(upload.download)          # bytes: the format is in the content
+Imprimatur.markdown(File.open("sales.xlsx"))  # an IO
+
+begin
+  Imprimatur.markdown(scan)
+rescue Imprimatur::NoTextLayer
+  # scanned pages: images, which need OCR
+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).
+- **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.
+- **DOCX**: headings (from styles and outline levels), bulleted and numbered
+  lists, bold, italic, links, tables, text boxes; deleted text and field
+  codes left out.
+
+Escaping is minimal: only what would break a table (`|`, line breaks). The
+text is meant to be searched and read, and `snake\_case` would be noise.
+
+Documents are untrusted input, so reads are bounded: `max_bytes:` (512 MiB),
+`max_inflated:` (1 GiB of decompressed data, zip bombs included) and
+`timeout:` (60 seconds), plus a nesting limit; past one,
+`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.
+
+### Structure and images
+
+Markdown is one rendering of what a read finds. `Imprimatur.content` gives
+the structure itself, the same as `imprimatur --json md` prints: a PDF's
+pages of headings and paragraphs with their position, a workbook's typed
+cells and comments, a Word document's blocks with their bold, italic and
+linked stretches.
+
+```ruby
+sheet = Imprimatur.content("sales.xlsx")[:sheets].first
+sheet[:rows][1][:cells]
+# => [{cell: "A2", type: "text", value: "North"},
+#     {cell: "B2", type: "number", value: 12.5, text: "12.5"}]
+
+Imprimatur.content("audit.pdf")[:pages].first[:blocks].first
+# => {type: "heading", level: 1, text: "Audit report",
+#     bounds: {left: 72.0, top: 61.4, right: 290.1, bottom: 85.0}}
+```
+
+`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,
+with the sheet that shows each. A scanned PDF gives its pages, ready for
+OCR.
+
+```ruby
+Imprimatur.images("scan.pdf") do |image|
+  File.binwrite("page-#{image.page}.#{image.format}", image.data)
+end
+```
+
+## Command line
+
+The same reader as a static binary, for scripts and agents that would
+otherwise reach for Python to read a PDF:
+
+```sh
+cargo install imprimatur-cli
+imprimatur md audit.pdf sales.xlsx         # Markdown on stdout
+imprimatur --json md sales.xlsx            # the structure: typed cells, blocks, positions
+imprimatur grep -i 'gots' certs/*.pdf      # matches by page, cell or section
+imprimatur images -o figures/ report.pdf   # every image, as a file
+```
+
+See [`ext/imprimatur_native/cli`](ext/imprimatur_native/cli/README.md).
+
+## Core library
+
+The core works without Ruby too; see
+[`ext/imprimatur_native/core`](ext/imprimatur_native/core/README.md).
+
+## Development
+
+```sh
+bundle install
+rake test:all        # cargo test, then the Ruby suite on the compiled extension
+rake lint            # dictator, cargo fmt --check, clippy
+rake gems:native     # the precompiled gem for this machine, in pkg/
+```
+
+Releases come from release-please: merging its release PR tags `vX.Y.Z`,
+bumps the gem and the crates together, and the release workflow attaches the
+source gem and every platform gem to the GitHub release. Publishing is local:
+
+```sh
+rake gems:pull_all   # the release's gems into pkg/, every platform checked
+rake gems:push_all   # to rubygems.org, skipping platforms already published
+```
+
+## License
+
+BSD 3-Clause. The PDF font metrics in `pdf/metrics.rs` are derived from Adobe's Core 14
+AFM files, under the notice reproduced in that file.

data/lib/imprimatur/document.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Imprimatur
+  # A flowing document (headings, paragraphs, tables, page breaks) that
+  # renders to PDF and DOCX from the same content.
+  #
+  #   doc = Imprimatur::Document.new(page_numbers: true)
+  #   doc.heading 'Quarterly report'
+  #   doc.paragraph do |p|
+  #     p.text 'Revenue was '
+  #     p.text 'up 12%', bold: true, color: '#1F7A1F'
+  #     p.text ' this quarter.'
+  #   end
+  #   doc.table [%w[Region Q1], ['North', 12.5]], header: true
+  #   doc.save_pdf('report.pdf')
+  #   doc.save_docx('report.docx')
+  #
+  # 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_numbers [Boolean] number pages "1 / N" in the footer
+    # @raise [ArgumentError] an unknown page size
+    def initialize(page_size: :a4, page_numbers: false)
+      @native = Native::Document.new
+      @native.set_page(page_size.to_s, page_numbers ? true : false)
+    end
+
+    # @param text [String]
+    # @param level [Integer] 1 (the title) to 3
+    # @return [self]
+    # @raise [Imprimatur::Error] a level out of range, or a control character
+    def heading(text, level: 1)
+      @native.heading(level, String(text))
+      self
+    end
+
+    # A paragraph, from plain text or a block of runs. +\n+ breaks the line,
+    # +\t+ is a tab.
+    #
+    # @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
+    # @yieldparam paragraph [Paragraph] add runs with {Paragraph#text}
+    # @return [self]
+    def paragraph(text = nil, align: nil, direction: nil, **look)
+      paragraph = Paragraph.new
+      paragraph.text(text, **look) if text
+      yield paragraph if block_given?
+      @native.paragraph(paragraph.runs, align&.to_s, direction&.to_s)
+      self
+    end
+
+    # @param rows [Array<Array>] cells are converted with +to_s+; nil is empty
+    # @param header [Boolean] the first row is a header: bold, shaded, repeated on every page
+    # @return [self]
+    # @raise [Imprimatur::Error] no rows or no columns
+    def table(rows, header: false)
+      @native.table(rows.map { |row| row.map { it.nil? ? '' : it.to_s } }, header ? true : false)
+      self
+    end
+
+    # @return [self]
+    def page_break
+      @native.page_break
+      self
+    end
+
+    # @return [String] the PDF bytes (binary)
+    # @raise [Imprimatur::Error] text the standard fonts cannot encode, or a table row taller than a page
+    def to_pdf = @native.render('pdf')
+
+    # @return [String] the DOCX bytes (binary)
+    def to_docx = @native.render('docx')
+
+    # @param path [String, Pathname]
+    # @return [self]
+    def save_pdf(path)
+      @native.save('pdf', File.expand_path(path))
+      self
+    end
+
+    # @param path [String, Pathname]
+    # @return [self]
+    def save_docx(path)
+      @native.save('docx', File.expand_path(path))
+      self
+    end
+
+    # @api private
+    def self.build(format, path, **options)
+      document = new(**options)
+      yield document
+      return document.public_send(:"to_#{format}") unless path
+
+      document.public_send(:"save_#{format}", path)
+      path
+    end
+  end
+
+  # Runs of text that make up one {Document#paragraph}.
+  class Paragraph
+    # @api private
+    attr_reader :runs
+
+    def initialize
+      @runs = []
+    end
+
+    # @param text [String]
+    # @param bold [Boolean]
+    # @param italic [Boolean]
+    # @param underline [Boolean]
+    # @param color [String, nil] "#RRGGBB"
+    # @return [self]
+    def text(text, bold: false, italic: false, underline: false, color: nil)
+      @runs << [String(text), bold ? true : false, italic ? true : false, underline ? true : false, color&.to_s]
+      self
+    end
+
+    # @return [self]
+    def bold(text) = text(text, bold: true)
+
+    # @return [self]
+    def italic(text) = text(text, italic: true)
+  end
+end

data/lib/imprimatur/error.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Imprimatur
+  # A document Excel (or Word, or a PDF reader) would reject: an invalid or
+  # duplicate sheet name, a cell out of range, text over a limit, NaN. Also
+  # a document {Imprimatur.markdown} cannot read. Raised by the native core.
+  class Error < StandardError; end
+
+  # 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.
+  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.
+  class UnsupportedDocument < Error; end
+
+  # The read hit one of its limits (size, decompressed size, nesting, time),
+  # or was cancelled.
+  class LimitExceeded < Error; end
+end

data/lib/imprimatur/formula.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Imprimatur
+  # A cell formula such as +SUM(B2:B9)+, with or without the leading +=+.
+  # Excel computes it when the workbook opens.
+  Formula = Data.define(:expression) do
+    def initialize(expression:)
+      raise TypeError, "formula expression must be a String, got #{expression.class}" unless expression.is_a?(String)
+
+      super
+    end
+  end
+end

data/lib/imprimatur/native.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# imprimatur is native only: there is no pure Ruby engine to fall back to.
+#
+# Platform gems ship the binary under the Ruby ABI version; a dev build (rake
+# compile) or a source install leaves it next to this file.
+shipped = File.join(__dir__, RUBY_VERSION[/\A\d+\.\d+/], "imprimatur_native.#{RbConfig::CONFIG['DLEXT']}")
+begin
+  if File.exist?(shipped)
+    require shipped
+  else
+    require 'imprimatur/imprimatur_native'
+  end
+rescue LoadError => e
+  raise LoadError, "imprimatur: the native extension did not load (#{e.message}). " \
+                   'Install a platform gem, or build it with `rake compile` (toolchain: https://rustup.rs).'
+end

data/lib/imprimatur/reader.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Imprimatur
+  # An image found in a document, as a file: {#data} is what a file of
+  # {#format} holds. On a PDF page, {#page} and {#bounds} (points from the
+  # page's top-left corner) say where; in a Word or Excel package, {#part}
+  # names the medium, and {#sheet} the sheet that shows it.
+  Image = Data.define(:data, :format, :width, :height, :page, :bounds, :part, :sheet)
+
+  # Documents in: Markdown, their structure, their images. See
+  # {Imprimatur.markdown}, {Imprimatur.content} and {Imprimatur.images}.
+  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
+    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)
+    end
+
+    # @see Imprimatur.images
+    def self.images(document, **)
+      Native.images(read(document), *limits(**)).map do |data, description|
+        found = JSON.parse(description, symbolize_names: true)
+        Image.new(data:, **Image.members.drop(1).to_h { [it, found[it]] })
+      end
+    end
+
+    # @api private
+    def self.limits(timeout: 60, max_bytes: nil, max_inflated: nil)
+      [max_bytes, max_inflated, timeout && Float(timeout)]
+    end
+
+    # @api private
+    def self.read(document)
+      case document
+      when Pathname then File.binread(document)
+      when String then bytes?(document) ? document : File.binread(document)
+      else
+        raise TypeError, "expected a path, bytes or an IO, not #{document.class}" unless document.respond_to?(:read)
+
+        document.read.to_s.b
+      end
+    end
+
+    # @api private
+    def self.bytes?(string)
+      head = string.byteslice(0, 1024).b
+      SIGNATURES.any? { head.start_with?(it) } || head.include?("%PDF-") || head.include?("\0")
+    end
+  end
+end

data/lib/imprimatur/style.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Imprimatur
+  # How a cell looks. Built once with {Imprimatur.style}, validated then, and
+  # shared by every cell that uses it. The class itself is native.
+  class Style
+    # @param number_format [String, nil] an Excel format code: "0.00", "#,##0", "0%", "yyyy-mm-dd"
+    # @param bold [Boolean]
+    # @param italic [Boolean]
+    # @param underline [Boolean]
+    # @param color [String, nil] font color, "#RRGGBB"
+    # @param fill [String, nil] background color, "#RRGGBB"
+    # @param align [:left, :center, :right, nil]
+    # @param direction [:ltr, :rtl, nil] reading order; without one Excel infers it from the text
+    # @param wrap [Boolean] wrap text within the column width
+    # @param border [:thin, :medium, :thick, nil] on all four sides
+    # @param font [String, nil] typeface, Calibri by default: "Arial"
+    # @param size [Numeric, nil] in points, 1 to 409 in steps of 0.5; 11 by default
+    # @param valign [:top, :center, :bottom, nil] vertical alignment; Excel's default is the bottom
+    # @return [Style]
+    # @raise [Imprimatur::Error] an invalid number format, color, font or size
+    # @raise [ArgumentError] an unknown align, direction, border or valign
+    def self.build(number_format: nil, bold: false, italic: false, underline: false, color: nil, fill: nil,
+                   align: nil, direction: nil, wrap: false, border: nil, font: nil, size: nil, valign: nil)
+      __build(number_format&.to_s, bold, italic, underline, color&.to_s, fill&.to_s,
+              align&.to_s, direction&.to_s, wrap, border&.to_s, font&.to_s, size && Float(size), valign&.to_s)
+    end
+
+    private_class_method :__build
+  end
+end

data/lib/imprimatur/validation.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Imprimatur
+  # A data validation rule: a drop-down list, or a formula a value must
+  # satisfy. Built once with {Imprimatur.validation}, validated then, and
+  # applied to any number of ranges with {Xlsx::Sheet#validate}. The class
+  # itself is native.
+  class Validation
+    # @param list [Array<#to_s>, String, nil] the drop-down's values, or the
+    #   range holding them: "Units!$A$2:$A$20"
+    # @param formula [String, nil] true for a valid value; references are
+    #   relative to the top-left cell of the range: "LEN(B2)<=100"
+    # @param allow_blank [Boolean] whether an empty cell passes
+    # @param dropdown [Boolean] whether a list shows its in-cell arrow
+    # @param alert [:stop, :warning, :information, :off] what an invalid
+    #   value meets: refused, confirmed, accepted with a note, or accepted
+    # @param prompt [String, nil] shown while a cell of the range is selected
+    # @param prompt_title [String, nil] up to 32 characters
+    # @param error [String, nil] the alert's message, up to 255 characters
+    # @param error_title [String, nil] up to 32 characters
+    # @return [Validation]
+    # @raise [ArgumentError] not exactly one of +list:+ and +formula:+, or an unknown alert
+    # @raise [Imprimatur::Error] a rule or text Excel would refuse
+    def self.build(list: nil, formula: nil, allow_blank: true, dropdown: true, alert: :stop,
+                   prompt: nil, prompt_title: nil, error: nil, error_title: nil)
+      raise ArgumentError, 'a validation takes one of list: or formula:' unless list.nil? ^ formula.nil?
+
+      values, source = list.is_a?(Array) ? [list.map(&:to_s), nil] : [nil, list&.to_s]
+      __build(values, source, formula&.to_s, allow_blank ? true : false, dropdown ? true : false,
+              alert&.to_s, [prompt_title.to_s, prompt.to_s], [error_title.to_s, error.to_s])
+    end
+
+    private_class_method :__build
+  end
+end

data/lib/imprimatur/version.rb

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

data/lib/imprimatur/xlsx.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Imprimatur
+  # Excel workbooks (+.xlsx+).
+  #
+  #   header = Imprimatur.style(bold: true, fill: '#1F4E79', color: '#FFFFFF')
+  #   money = Imprimatur.style(number_format: '#,##0.00')
+  #
+  #   Imprimatur.xlsx('report.xlsx') do |book|
+  #     book.sheet('Sales') do |sheet|
+  #       sheet.row 'Region', 'Closed', 'Amount', style: header
+  #       sheet.row 'North', Date.today, 12.5
+  #       sheet.write(2, 2, Imprimatur.formula('SUM(C2:C2)'), style: money)
+  #       sheet.column_widths 18, 12, 14
+  #     end
+  #   end
+  #
+  # Cells take String, Integer (up to 2**53), Float, true, false, {Formula},
+  # Time, Date and DateTime (their wall-clock fields; no time zone); +nil+
+  # leaves a cell empty.
+  module Xlsx
+    # Builds a workbook. With a path, saves it there and returns the path;
+    # without, returns the +.xlsx+ bytes as a binary String.
+    #
+    # @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
+      yield book
+      return book.render unless path
+
+      book.save(path)
+      path
+    end
+
+    # An ordered set of uniquely named sheets.
+    class Workbook
+      def initialize
+        @native = Native::Workbook.new
+        @sheets = []
+      end
+
+      # @return [Array<Sheet>]
+      attr_reader :sheets
+
+      # Adds a sheet after the existing ones.
+      #
+      # @param name [String] up to 31 characters, unique ignoring case
+      # @yieldparam sheet [Sheet]
+      # @return [Sheet]
+      # @raise [Imprimatur::Error] the name is invalid or taken
+      def sheet(name)
+        sheet = Sheet.new(@native, @native.add_sheet(String(name)), name)
+        @sheets << sheet
+        yield sheet if block_given?
+        sheet
+      end
+
+      # @return [String] the +.xlsx+ bytes (binary)
+      def render = @native.render
+
+      # Writes the workbook to +path+, replacing any file there.
+      #
+      # @param path [String, Pathname]
+      def save(path)
+        @native.save(File.expand_path(path))
+        self
+      end
+    end
+
+    # One worksheet. Rows and columns are zero-based.
+    class Sheet
+      # @return [String]
+      attr_reader :name
+
+      # @api private
+      def initialize(native, index, name)
+        @native = native
+        @index = index
+        @name = name
+      end
+
+      # Appends a row below the last row written, from column A.
+      #
+      # @param cells [Array] values; +nil+ leaves a cell empty
+      # @param style [Style, Array<Style, nil>, nil] applied to every cell
+      #   written, or one per column from A; columns past the Array's end
+      #   are left unstyled
+      # @return [self]
+      # @raise [TypeError] a value of an unsupported type
+      # @raise [RangeError] an Integer beyond 2**53
+      # @raise [ArgumentError] more styles than cells
+      # @raise [Imprimatur::Error] the row is invalid; nothing is written
+      def row(*cells, style: nil)
+        @native.append_row(@index, cells, style)
+        self
+      end
+
+      # Appends an Array as a row: +sheet << ['North', 12.5]+.
+      #
+      # @param cells [Array]
+      # @return [self]
+      def <<(cells) = row(*cells)
+
+      # Sets one cell, replacing what was there.
+      #
+      # @param row [Integer] zero-based
+      # @param column [Integer] zero-based
+      # @param style [Style, nil]
+      # @return [self]
+      def write(row, column, value, style: nil)
+        @native.write([@index, row, column], value, style)
+        self
+      end
+
+      # Sets one column's width, in characters of the default font (0 to 255).
+      #
+      # @param column [Integer] zero-based
+      # @param width [Numeric]
+      # @return [self]
+      def column_width(column, width)
+        @native.set_column_width(@index, column, Float(width))
+        self
+      end
+
+      # Sets widths from column A on; +nil+ skips a column.
+      #
+      # @param widths [Array<Numeric, nil>]
+      # @return [self]
+      def column_widths(*widths)
+        widths.each_with_index { |width, column| column_width(column, width) if width }
+        self
+      end
+
+      # Applies a data validation to every cell of a range, written or not:
+      #
+      #   sheet.validate 'G2:G1000', list: %w[Yes No]
+      #   sheet.validate 'F2:F1000', list: 'Connections!$A$2:$A$1000', error: 'Pick a connection.'
+      #   sheet.validate 'B2:B1000', units  # a Validation built once, shared
+      #
+      # @param range [String] an A1 range, "B2:B100", or a cell, "B2"
+      # @param validation [Validation, nil] a rule built with {Imprimatur.validation}
+      # @param options [Hash] or the options to build one, see {Validation.build}
+      # @return [self]
+      # @raise [Imprimatur::Error] an invalid range, or one overlapping a range
+      #   already validated (Excel applies a single rule per cell)
+      def validate(range, validation = nil, **options)
+        raise ArgumentError, 'pass a Validation or its options, not both' if validation && options.any?
+
+        validation ||= Validation.build(**options)
+        @native.add_validation(@index, String(range), validation)
+        self
+      end
+
+      # Attaches a comment (an Excel note) to a cell, replacing any it had.
+      # The cell need not hold a value.
+      #
+      # @param reference [String] an A1 reference: "C1"
+      # @param text [String] up to 32,767 characters; newlines are kept
+      # @param author [String, nil]
+      # @param visible [Boolean] shown all the time, not only on hover
+      # @return [self]
+      # @raise [Imprimatur::Error] an invalid reference or text too long
+      def comment(reference, text, author: nil, visible: false)
+        @native.set_comment([@index, String(reference)], String(text), author&.to_s, visible ? 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.
+      #
+      # @return [self]
+      def right_to_left!(enabled = true)
+        @native.set_right_to_left(@index, enabled ? true : false)
+        self
+      end
+
+      # @return [Integer] the zero-based row the next {#row} writes
+      def next_row = @native.next_row(@index)
+    end
+  end
+end

data/lib/imprimatur.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require_relative 'imprimatur/version'
+require_relative 'imprimatur/error'
+require_relative 'imprimatur/formula'
+require_relative 'imprimatur/native'
+require_relative 'imprimatur/style'
+require_relative 'imprimatur/validation'
+require_relative 'imprimatur/xlsx'
+require_relative 'imprimatur/document'
+require_relative 'imprimatur/reader'
+
+# Document authoring with a native core: XLSX workbooks, and PDF and DOCX from
+# one document model.
+#
+#   Imprimatur.xlsx('report.xlsx') do |book|
+#     book.sheet('Sales') { it.row 'Region', 'Q1' }
+#   end
+#
+#   Imprimatur.pdf('report.pdf', page_numbers: true) do |doc|
+#     doc.heading 'Report'
+#     doc.paragraph 'It was printed.'
+#   end
+module Imprimatur
+  class << self
+    # @see Xlsx.build
+    def xlsx(path = nil, &) = Xlsx.build(path, &)
+
+    # @param expression [String] such as +"SUM(A1:A3)"+ or +"=A1*2"+
+    # @return [Formula]
+    def formula(expression) = Formula.new(expression:)
+
+    # @see Style.build
+    def style(**) = Style.build(**)
+
+    # @see Validation.build
+    def validation(**) = Validation.build(**)
+
+    # Builds a {Document} and renders it as PDF. With a path, saves it there
+    # and returns the path; without, returns the bytes.
+    #
+    # @param options [Hash] +page_size:+ and +page_numbers:+, see {Document#initialize}
+    # @yieldparam document [Document]
+    def pdf(path = nil, **options, &) = Document.build(:pdf, path, **options, &)
+
+    # 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
+    # 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
+    # told by the content, not the name.
+    #
+    # Reading runs without the GVL: other threads keep running, and
+    # +Thread#raise+ or +Timeout+ cancels it.
+    #
+    #   Imprimatur.markdown('audit.pdf')
+    #   Imprimatur.markdown(upload.download)        # bytes
+    #   Imprimatur.markdown(File.open('sales.xlsx'))
+    #
+    # @param document [String, Pathname, #read] a path, the document's bytes
+    #   (told apart by their signature), or an IO
+    # @param timeout [Numeric, nil] seconds the read may take (60), +nil+ for none
+    # @param max_bytes [Integer, nil] the largest document accepted (512 MiB)
+    # @param max_inflated [Integer, nil] decompressed bytes allowed in all (1 GiB)
+    # @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 [LimitExceeded] the document is too large, too deep or too slow
+    # @raise [Error] a damaged document
+    def markdown(document, ...) = Reader.markdown(document, ...)
+
+    # What {.markdown} renders, as data: the same structure as
+    # +imprimatur --json md+ prints. A PDF's +:pages+ of +:blocks+
+    # (+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+,
+    # +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.
+    #
+    # @return [Hash] with symbol keys; +:format+ is +"pdf"+, +"xlsx"+ or +"docx"+
+    def content(document, ...) = Reader.content(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
+    # its pages' images, ready for OCR, instead of raising {NoTextLayer}.
+    #
+    #   Imprimatur.images('report.pdf').each do |image|
+    #     File.binwrite("p#{image.page}.#{image.format}", image.data)
+    #   end
+    #
+    # Takes the arguments of {.markdown}, and raises as it does (but for
+    # {NoTextLayer}).
+    #
+    # @yieldparam image [Image] each image, when a block is given
+    # @return [Array<Image>]
+    def images(document, ...)
+      found = Reader.images(document, ...)
+      block_given? ? found.each { yield it } : found
+    end
+  end
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: imprimatur
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: aarch64-linux-gnu
+authors:
+- Abdelkader Boudih
+bindir: bin
+cert_chain: []
+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.'
+email:
+- terminale@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/imprimatur.rb
+- lib/imprimatur/4.0/imprimatur_native.so
+- lib/imprimatur/document.rb
+- lib/imprimatur/error.rb
+- lib/imprimatur/formula.rb
+- lib/imprimatur/native.rb
+- lib/imprimatur/reader.rb
+- lib/imprimatur/style.rb
+- lib/imprimatur/validation.rb
+- lib/imprimatur/version.rb
+- lib/imprimatur/xlsx.rb
+homepage: https://github.com/seuros/imprimatur
+licenses:
+- BSD-3-Clause
+metadata:
+  source_code_uri: https://github.com/seuros/imprimatur
+  bug_tracker_uri: https://github.com/seuros/imprimatur/issues
+  changelog_uri: https://github.com/seuros/imprimatur/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: XLSX, PDF and DOCX authoring with a Ruby DSL. Let it be printed.
+test_files: []