prawnx 0.1.1

data/lib/prawnx/measurements.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module PrawnX
+  # Conversions between metric and imperial units and PDF points (1/72 inch).
+  module Measurements
+    def cm2mm(cm)
+      cm * 10
+    end
+
+    def dm2mm(dm)
+      dm * 100
+    end
+
+    def m2mm(m)
+      m * 1000
+    end
+
+    def ft2in(ft)
+      ft * 12
+    end
+
+    def yd2in(yd)
+      yd * 36
+    end
+
+    def pt2pt(pt)
+      pt
+    end
+
+    def in2pt(inch)
+      inch * 72
+    end
+
+    def ft2pt(ft)
+      in2pt(ft2in(ft))
+    end
+
+    def yd2pt(yd)
+      in2pt(yd2in(yd))
+    end
+
+    def mm2pt(mm)
+      mm * (72 / 25.4)
+    end
+
+    def cm2pt(cm)
+      mm2pt(cm2mm(cm))
+    end
+
+    def dm2pt(dm)
+      mm2pt(dm2mm(dm))
+    end
+
+    def m2pt(m)
+      mm2pt(m2mm(m))
+    end
+
+    def pt2mm(pt)
+      pt * 1 / mm2pt(1)
+    end
+  end
+end

data/lib/prawnx/outline.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module PrawnX
+  class Document
+    def outline
+      @outline ||= Outline.new(self)
+    end
+  end
+
+  # The document outline (bookmarks): sections holding pages and subsections, each pointing at a page.
+  class Outline
+    attr_accessor :parent, :prev, :document, :items
+
+    def initialize(document)
+      @document = document
+      @parent = root
+      @prev = nil
+      @items = {}
+    end
+
+    def page_number
+      @document.page_number
+    end
+
+    def define(&block)
+      instance_eval(&block) if block
+    end
+    alias update define
+
+    def add_subsection_to(title, position = :last, &)
+      @parent = items[title] || raise(Errors::UnknownOutlineTitle, "\n No outline item with title: '#{title}' exists in the outline tree")
+      @prev = position == :first ? nil : @parent.data.last
+      insert_section(position == :first ? @parent.data.first : nil, &)
+    end
+
+    def insert_section_after(title, &)
+      @prev = items[title] || raise(Errors::UnknownOutlineTitle, "\n No outline item with title: '#{title}' exists in the outline tree")
+      @parent = @prev.data.parent
+      insert_section(@prev.data.next, &)
+    end
+
+    def section(title, options = {}, &)
+      add_outline_item(title, options, &)
+    end
+
+    def page(options = {})
+      raise Errors::RequiredOption, "\nTitle is a required option for page" unless options[:title]
+
+      add_outline_item(options[:title], options)
+    end
+
+    private
+
+    def root
+      document.outlines_reference
+    end
+
+    def add_outline_item(title, options, &block)
+      outline_item = create_outline_item(title, options)
+      prev.data.next = outline_item if prev
+      parent.data.first = outline_item unless prev
+      parent.data.last = outline_item
+      increase_count
+      self.prev = block ? nil : outline_item
+      self.parent = outline_item if block
+      yield if block
+      return unless parent == outline_item
+
+      self.prev = outline_item
+      self.parent = outline_item.data.parent
+    end
+
+    def create_outline_item(title, options)
+      outline_item = PDF::OutlineItem.new(title, parent, options)
+      case options[:destination]
+      when Integer then outline_item.dest = [document.pages[options[:destination] - 1].dictionary, :Fit]
+      when Array then outline_item.dest = options[:destination]
+      end
+      outline_item.prev = prev if @prev
+      items[title] = document.ref!(outline_item)
+    end
+
+    def increase_count
+      counting_parent = parent
+      while counting_parent
+        counting_parent.data.count += 1
+        counting_parent = counting_parent == root ? nil : counting_parent.data.parent
+      end
+    end
+
+    def insert_section(next_item)
+      last = @parent.data.last
+      yield if block_given?
+      if next_item
+        next_item.data.prev = @prev
+        @prev.data.next = next_item
+        @parent.data.last = last
+      end
+      @parent = root
+      @prev = root.data.last
+    end
+  end
+
+  module Destinations
+    def dests
+      names.data[:Dests] ||= ref!(PDF::NameTree.new)
+    end
+
+    def add_dest(name, reference)
+      reference = ref!(reference) unless reference.is_a?(PDF::Reference)
+      dests.data.add(name, reference)
+    end
+
+    def dest_xyz(left, top, zoom = nil, dest_page = page)
+      [dest_page.dictionary, :XYZ, left, top, zoom]
+    end
+
+    def dest_fit(dest_page = page)
+      [dest_page.dictionary, :Fit]
+    end
+
+    def dest_fit_horizontally(top, dest_page = page)
+      [dest_page.dictionary, :FitH, top]
+    end
+
+    def dest_fit_vertically(left, dest_page = page)
+      [dest_page.dictionary, :FitV, left]
+    end
+
+    def dest_fit_rect(left, bottom, right, top, dest_page = page)
+      [dest_page.dictionary, :FitR, left, bottom, right, top]
+    end
+
+    def dest_fit_bounds(dest_page = page)
+      [dest_page.dictionary, :FitB]
+    end
+
+    def dest_fit_bounds_horizontally(top, dest_page = page)
+      [dest_page.dictionary, :FitBH, top]
+    end
+
+    def dest_fit_bounds_vertically(left, dest_page = page)
+      [dest_page.dictionary, :FitBV, left]
+    end
+  end
+end

data/lib/prawnx/page.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module PrawnX
+  # One page: its geometry, the content stream being written, its resources and the stack of graphic states.
+  class Page
+    DEFAULT_MARGINS = {left: 36, right: 36, top: 36, bottom: 36}.freeze
+    NO_INDENTS = {left: 0, bottom: 0, right: 0, top: 0}.freeze
+
+    attr_accessor :margins, :crops, :bleeds, :trims, :art_indents, :stack
+    attr_reader :document, :content
+
+    def initialize(document, options = {})
+      @document = document
+      @margins = options[:margins] || DEFAULT_MARGINS.dup
+      @crops = options[:crops] || NO_INDENTS
+      @bleeds = options[:bleeds] || NO_INDENTS
+      @trims = options[:trims] || NO_INDENTS
+      @art_indents = options[:art_indents] || NO_INDENTS
+      @stack = [GraphicState.new(options[:graphic_state])]
+      @size = options[:size] || "LETTER"
+      @layout = options[:layout] || :portrait
+      @content = document.ref!({}, (+"q\n").b)
+      @dictionary = document.ref!(Type: :Page, Parent: document.pages_reference, MediaBox: dimensions, Contents: @content)
+      @stamp_stream = nil
+      @stamp_dictionary = nil
+    end
+
+    def graphic_state
+      stack.last
+    end
+
+    def size
+      @size || dimensions[2, 2]
+    end
+
+    def layout
+      @layout || (dimensions[3] > dimensions[2] ? :portrait : :landscape)
+    end
+
+    def content_stream
+      @stamp_stream || content.stream
+    end
+
+    def dictionary
+      @stamp_dictionary || @dictionary
+    end
+
+    # Writes what the block draws into a form XObject instead of the page, starting from a copy of the current
+    # graphic settings.
+    def stamp_stream(reference)
+      @stamp_dictionary = reference
+      @stamp_stream = reference.stream
+      depth = stack.size
+      document.save_graphics_state
+      document.__send__(:freeze_stamp_graphics)
+      yield if block_given?
+      document.restore_graphics_state until stack.size == depth
+      @stamp_stream = nil
+      @stamp_dictionary = nil
+    end
+
+    def in_stamp_stream?
+      !@stamp_stream.nil?
+    end
+
+    def resources
+      dictionary.data[:Resources] ||= {}
+    end
+
+    def fonts
+      resources[:Font] ||= {}
+    end
+
+    def xobjects
+      resources[:XObject] ||= {}
+    end
+
+    def ext_gstates
+      resources[:ExtGState] ||= {}
+    end
+
+    def dimensions
+      sides = PageGeometry::SIZES[@size] || @size
+      sides =
+        case @layout
+        when :portrait then sides
+        when :landscape then sides.reverse
+        else raise Errors::InvalidPageLayout, "Layout must be either :portrait or :landscape"
+        end
+      [0, 0, *sides]
+    end
+
+    def crop_box
+      boxed(crops)
+    end
+
+    def bleed_box
+      boxed(bleeds)
+    end
+
+    def trim_box
+      boxed(trims)
+    end
+
+    def art_box
+      boxed(art_indents)
+    end
+
+    # Resources are required even when empty; every box defaults to the media box, so only those that differ are
+    # written.
+    def finalize
+      resources
+      {CropBox: crop_box, BleedBox: bleed_box, TrimBox: trim_box, ArtBox: art_box}.each do |name, box|
+        dictionary.data[name] = box unless box == dimensions
+      end
+    end
+
+    private
+
+    def boxed(indents)
+      left, bottom, right, top = dimensions
+      [left + indents[:left], bottom + indents[:bottom], right - indents[:right], top - indents[:top]]
+    end
+  end
+end

data/lib/prawnx/page_geometry.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module PrawnX
+  module PageGeometry
+    POINTS_PER_INCH = 72.0
+    MILLIMETERS_PER_INCH = 25.4
+
+    # ISO 216 (A, B), ISO 217 (RA, SRA) and ISO 269 (C) sizes in millimeters, then North American sizes in inches.
+    MILLIMETERS_BY_SIZE = {
+      "4A0" => [1682, 2378], "2A0" => [1189, 1682],
+      "A0" => [841, 1189], "A1" => [594, 841], "A2" => [420, 594], "A3" => [297, 420], "A4" => [210, 297],
+      "A5" => [148, 210], "A6" => [105, 148], "A7" => [74, 105], "A8" => [52, 74], "A9" => [37, 52], "A10" => [26, 37],
+      "B0" => [1000, 1414], "B1" => [707, 1000], "B2" => [500, 707], "B3" => [353, 500], "B4" => [250, 353],
+      "B5" => [176, 250], "B6" => [125, 176], "B7" => [88, 125], "B8" => [62, 88], "B9" => [44, 62], "B10" => [31, 44],
+      "C0" => [917, 1297], "C1" => [648, 917], "C2" => [458, 648], "C3" => [324, 458], "C4" => [229, 324],
+      "C5" => [162, 229], "C6" => [114, 162], "C7" => [81, 114], "C8" => [57, 81], "C9" => [40, 57], "C10" => [28, 40],
+      "RA0" => [860, 1220], "RA1" => [610, 860], "RA2" => [430, 610], "RA3" => [305, 430], "RA4" => [215, 305],
+      "SRA0" => [900, 1280], "SRA1" => [640, 900], "SRA2" => [450, 640], "SRA3" => [320, 450], "SRA4" => [225, 320],
+      "EXECUTIVE" => [184.1, 266.7],
+    }.freeze
+    INCHES_BY_SIZE = {"FOLIO" => [8.5, 13], "LEGAL" => [8.5, 14], "LETTER" => [8.5, 11], "TABLOID" => [11, 17]}.freeze
+
+    SIZES = MILLIMETERS_BY_SIZE.transform_values { |sides| sides.map { (it * POINTS_PER_INCH / MILLIMETERS_PER_INCH).round(2) } }
+      .merge(INCHES_BY_SIZE.transform_values { |sides| sides.map { it * POINTS_PER_INCH } })
+      .freeze
+  end
+end

data/lib/prawnx/pdf/outline_node.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module PrawnX
+  module PDF
+    class OutlineRoot
+      include Serializable
+
+      attr_accessor :count, :first, :last
+
+      def initialize
+        @count = 0
+      end
+
+      def to_hash
+        {Type: :Outlines, Count: count, First: first, Last: last}
+      end
+    end
+
+    class OutlineItem
+      include Serializable
+
+      attr_accessor :count, :first, :last, :next, :prev, :parent, :title, :dest, :closed
+
+      def initialize(title, parent, options)
+        @closed = options[:closed]
+        @title = title
+        @parent = parent
+        @count = 0
+      end
+
+      def to_hash
+        {Title: title, Parent: parent, Count: closed ? -count : count, First: first, Last: last, Next: @next, Prev: prev, Dest: dest}.compact
+      end
+    end
+
+    # A name tree kept as a single sorted leaf: valid at any size (ISO 32000-1 §7.9.6).
+    class NameTree
+      include Serializable
+
+      def initialize
+        @value_by_name = {}
+      end
+
+      def add(name, value)
+        @value_by_name[name] = value
+      end
+
+      def to_hash
+        {Names: @value_by_name.sort_by { |name, _| name.to_s }.flat_map { |name, value| [LiteralString.new(name.to_s), value] }}
+      end
+    end
+  end
+end

data/lib/prawnx/pdf/reference.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module PrawnX
+  module PDF
+    # An indirect object: a number, its value and, for a stream, its bytes.
+    class Reference
+      attr_reader :identifier
+      attr_accessor :data, :uncompressed
+      attr_writer :stream
+
+      def initialize(identifier, data, stream = nil)
+        @identifier = identifier
+        @data = data
+        @stream = stream
+      end
+
+      def to_s
+        "#{identifier} 0 R"
+      end
+
+      # A reference becomes a stream once bytes are written to it: prawn-svg appends to ref!({}).stream.
+      def stream
+        @stream ||= +"".b
+      end
+
+      def stream?
+        !@stream.nil? && !@stream.empty?
+      end
+    end
+  end
+end

data/lib/prawnx/pdf/writer.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "digest/md5"
+require "zlib"
+
+module PrawnX
+  module PDF
+    # Writes a PDF 1.5 file: streams compressed, every other object packed into one compressed object stream, and
+    # a compressed cross-reference stream instead of the xref table (ISO 32000-1 §7.5.7, §7.5.8).
+    class Writer
+      MINIMUM_VERSION = 1.5
+      BINARY_MARKER = "%\xE2\xE3\xCF\xD3\n".b
+
+      def self.call(...)
+        new(...).call
+      end
+
+      def initialize(objects:, root:, info:, version:, trailer: {}, encryption: nil, identified: false)
+        @objects = objects
+        @root = root
+        @info = info
+        @version = [version, MINIMUM_VERSION].max
+        @trailer = trailer
+        return unless encryption || identified
+
+        file_identifier = PDF::ByteString.new(document_digest)
+        @trailer = trailer.merge(ID: [file_identifier, file_identifier])
+        return unless encryption
+
+        @encryption_key = encryption.key(file_identifier)
+        @trailer[:Encrypt] = encryption.dictionary(file_identifier)
+      end
+
+      def call
+        output = (+"%PDF-#{version}\n").b << BINARY_MARKER
+        location_by_identifier = {}
+
+        stream_objects, packed_objects = objects.partition(&:stream?)
+        stream_objects.each do |reference|
+          location_by_identifier[reference.identifier] = [1, output.bytesize]
+          output << indirect_stream(reference.identifier, reference.data, reference.stream, compressed: !reference.uncompressed)
+        end
+
+        object_stream_identifier = objects.size + 1
+        unless packed_objects.empty?
+          location_by_identifier[object_stream_identifier] = [1, output.bytesize]
+          output << object_stream(object_stream_identifier, packed_objects, location_by_identifier)
+        end
+
+        cross_reference_identifier = object_stream_identifier + 1
+        location_by_identifier[cross_reference_identifier] = [1, output.bytesize]
+        output << cross_reference_stream(cross_reference_identifier, location_by_identifier)
+      end
+
+      private
+
+      attr_reader :objects, :root, :info, :version, :trailer
+
+      # A file identifier derived from the document's content, so the same document always gets the same one.
+      def document_digest
+        digest = Digest::MD5.new
+        objects.each do |reference|
+          digest << PDF.serialize(reference.data)
+          digest << reference.stream if reference.stream?
+        end
+        digest.digest
+      end
+
+      # Streams are encrypted once compressed; the cross-reference stream never is (ISO 32000-1 §7.5.8.4).
+      def indirect_stream(identifier, dictionary, bytes, encrypted: true, compressed: true)
+        compressed &&= dictionary[:Filter].nil?
+        bytes = Zlib::Deflate.deflate(bytes) if compressed
+        bytes = Document::Arcfour.new(Document::Security.object_key(@encryption_key, identifier, 0)).encrypt(bytes) if @encryption_key && encrypted
+        dictionary = dictionary.merge(Length: bytes.bytesize)
+        dictionary[:Filter] = :FlateDecode if compressed
+        "#{identifier} 0 obj\n#{PDF.serialize(dictionary)}\nstream\n".b << bytes.b << "\nendstream\nendobj\n"
+      end
+
+      def object_stream(identifier, references, location_by_identifier)
+        offsets = +""
+        body = +""
+        references.each_with_index do |reference, index|
+          location_by_identifier[reference.identifier] = [2, identifier, index]
+          offsets << "#{reference.identifier} #{body.bytesize} "
+          body << PDF.serialize(reference.data) << "\n"
+        end
+        dictionary = {Type: :ObjStm, N: references.size, First: offsets.bytesize}
+        indirect_stream(identifier, dictionary, offsets << body)
+      end
+
+      # Each row is one byte of type, then the offset or the object stream, then the generation or the index.
+      def cross_reference_stream(identifier, location_by_identifier)
+        size = identifier + 1
+        offset_width = [(location_by_identifier.values.map { it[1] }.max.bit_length + 7) / 8, 1].max
+        rows = (+"\x00".b) << ("\x00" * offset_width).b << "\xFF\xFF".b
+        (1...size).each do |object_identifier|
+          type, field, generation_or_index = location_by_identifier.fetch(object_identifier)
+          rows << type.chr << [field].pack("Q>").byteslice(8 - offset_width, offset_width) << [generation_or_index.to_i].pack("n")
+        end
+        dictionary = {Type: :XRef, Size: size, W: [1, offset_width, 2], Root: root, Info: info}.merge(trailer)
+        indirect_stream(identifier, dictionary, rows, encrypted: false) << "startxref\n#{location_by_identifier.fetch(identifier)[1]}\n%%EOF\n"
+      end
+    end
+  end
+end

data/lib/prawnx/pdf.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module PrawnX
+  # PDF syntax: numbers, names, strings, arrays and dictionaries, as ISO 32000-1 §7.3 writes them.
+  module PDF
+    Name = Data.define(:value)
+
+    # Objects that build their dictionary when the document is written, once every reference they hold is known.
+    module Serializable
+    end
+    LiteralString = Class.new(String)
+    ByteString = Class.new(String)
+
+    DELIMITER_OR_IRREGULAR_BYTES = ((0..32).to_a + [35, 37, 40, 41, 47, 60, 62, 91, 93, 123, 125] + (127..255).to_a).freeze
+    LITERAL_STRING_ESCAPES = {"(" => "\\(", ")" => "\\)", "\\" => "\\\\", "\r" => "\\r"}.freeze
+    NAME_BY_SYMBOL = Hash.new do |cache, symbol|
+      cache[symbol] = (+"/").concat(*symbol.to_s.b.each_byte.map { DELIMITER_OR_IRREGULAR_BYTES.include?(it) ? format("#%02X", it) : it.chr }).freeze
+    end
+
+    module_function
+
+    # Five decimals, trailing zeros dropped but one: 1 is "1.0", 0.5 is "0.5", 1/3 is "0.33333".
+    def real(number)
+      digits = format("%.5f", number)
+      last = digits.bytesize - 1
+      last -= 1 while digits.getbyte(last) == 48 && digits.getbyte(last - 1) != 46
+      digits.byteslice(0, last + 1)
+    end
+
+    def real_params(numbers)
+      numbers.map { real(it) }.join(" ")
+    end
+
+    # Integers as integers, other numbers to five decimals without a trailing ".0".
+    def number(value)
+      return value.to_s if value.is_a?(Integer)
+
+      digits = real(value)
+      digits.end_with?(".0") ? digits.delete_suffix(".0") : digits
+    end
+
+    def serialize(value, in_content_stream = false)
+      case value
+      when nil then "null"
+      when true then "true"
+      when false then "false"
+      when Numeric then number(value)
+      when Symbol then NAME_BY_SYMBOL[value]
+      when Name then NAME_BY_SYMBOL[value.value.to_sym]
+      when LiteralString then "(#{value.gsub(/[\\\r()]/, LITERAL_STRING_ESCAPES)})"
+      when ByteString then "<#{value.unpack1("H*")}>"
+      when Time then "(#{value.strftime("D:%Y%m%d%H%M%S%z").chop.chop}'00')"
+      when String then "<#{(in_content_stream ? value : utf16be(value)).unpack1("H*")}>"
+      when Array then "[#{value.map { serialize(it, in_content_stream) }.join(" ")}]"
+      when Hash then "<<#{value.map { |key, entry| "#{serialize(key.to_sym)} #{serialize(entry, in_content_stream)}" }.join("\n")}>>"
+      when Reference then value.to_s
+      when Serializable then serialize(value.to_hash, in_content_stream)
+      else raise Errors::FailedObjectConversion, "This object cannot be serialized to PDF (#{value.inspect})"
+      end
+    end
+
+    def utf16be(string)
+      "\xFE\xFF".b + string.encode(::Encoding::UTF_16BE).b
+    end
+  end
+end

data/lib/prawnx/pdf_a/srgb_profile.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module PrawnX
+  module PdfA
+    # An ICC version 2 display profile for sRGB (IEC 61966-2.1), built from the standard's primaries adapted to D50
+    # (ICC.1:2001-04): PDF/A needs one as output intent, and building it avoids shipping a third-party file.
+    module SrgbProfile
+      DESCRIPTION = "sRGB IEC61966-2.1"
+      D50_WHITE = [0.9642, 1.0, 0.8249].freeze
+      # sRGB primaries, Bradford-adapted from D65 to D50.
+      RED = [0.4361, 0.2225, 0.0139].freeze
+      GREEN = [0.3851, 0.7169, 0.0971].freeze
+      BLUE = [0.1431, 0.0606, 0.7141].freeze
+      # The sRGB tone curve, approximated by a 2.2 gamma, as u8Fixed8Number.
+      GAMMA = 0x0233
+
+      module_function
+
+      def bytes
+        @bytes ||= begin
+          curve = "curv".b + "\x00" * 4 + [1, GAMMA].pack("Nn") + "\x00\x00".b
+          tags = [
+            ["desc", text_description(DESCRIPTION)],
+            ["cprt", "text".b + ("\x00" * 4) + "No copyright, use freely\x00".b],
+            ["wtpt", xyz(D50_WHITE)],
+            ["rXYZ", xyz(RED)], ["gXYZ", xyz(GREEN)], ["bXYZ", xyz(BLUE)],
+            ["rTRC", curve], ["gTRC", curve], ["bTRC", curve],
+          ]
+          table_size = 4 + (tags.size * 12)
+          offset = 128 + table_size
+          directory = [tags.size].pack("N")
+          data = +"".b
+          tags.each do |signature, tag|
+            directory << [signature, offset + data.bytesize, tag.bytesize].pack("a4N2")
+            data << tag << ("\x00" * ((4 - (tag.bytesize % 4)) % 4))
+          end
+          body = directory + data
+          header(128 + body.bytesize) + body
+        end
+      end
+
+      def header(size)
+        [size, "", 0x02100000, "mntr", "RGB ", "XYZ ", 2026, 1, 1, 0, 0, 0, "acsp", "APPL", 0, "", "", 0, 0,
+          *D50_WHITE.map { s15_fixed16(it) }, ""].pack("N a4 N a4 a4 a4 n6 a4 a4 N a4 a4 Q> N N3 a4") + ("\x00" * 44)
+      end
+
+      def xyz(values)
+        "XYZ ".b + ("\x00" * 4) + values.map { s15_fixed16(it) }.pack("N3")
+      end
+
+      def s15_fixed16(value)
+        (value * 65_536).round & 0xFFFFFFFF
+      end
+
+      def text_description(text)
+        ascii = "#{text}\x00".b
+        "desc".b + ("\x00" * 4) + [ascii.bytesize].pack("N") + ascii + [0, 0, 0].pack("N2n") + ("\x00" * 67)
+      end
+    end
+  end
+end