imprimatur 0.1.0

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