gamba 2.0.0

data/lib/gamba/images/png_decoder.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Prawn
+  module Images
+    # Undoes PNG's per-row filters (PNG specification §9), giving back raw samples: needed to split an alpha
+    # channel or a palette's transparency into a separate soft mask.
+    module PngDecoder
+      NONE = 0
+      SUB = 1
+      UP = 2
+      AVERAGE = 3
+      PAETH = 4
+
+      module_function
+
+      # Rows of unfiltered bytes, from the inflated data of a non-interlaced image.
+      def unfilter(data, row_bytes, bytes_per_pixel)
+        previous = ("\x00" * row_bytes).b
+        row_count = data.bytesize / (row_bytes + 1)
+        Array.new(row_count) do |row_index|
+          start = row_index * (row_bytes + 1)
+          filter = data.getbyte(start)
+          row = data.byteslice(start + 1, row_bytes).b
+          unfilter_row!(row, previous, filter, bytes_per_pixel)
+          previous = row
+        end
+      end
+
+      def unfilter_row!(row, previous, filter, bytes_per_pixel)
+        case filter
+        when NONE then nil
+        when SUB
+          (bytes_per_pixel...row.bytesize).each { |index| row.setbyte(index, (row.getbyte(index) + row.getbyte(index - bytes_per_pixel)) & 0xFF) }
+        when UP
+          row.bytesize.times { |index| row.setbyte(index, (row.getbyte(index) + previous.getbyte(index)) & 0xFF) }
+        when AVERAGE
+          row.bytesize.times do |index|
+            left = (index >= bytes_per_pixel) ? row.getbyte(index - bytes_per_pixel) : 0
+            row.setbyte(index, (row.getbyte(index) + ((left + previous.getbyte(index)) >> 1)) & 0xFF)
+          end
+        when PAETH
+          row.bytesize.times do |index|
+            left = (index >= bytes_per_pixel) ? row.getbyte(index - bytes_per_pixel) : 0
+            up = previous.getbyte(index)
+            up_left = (index >= bytes_per_pixel) ? previous.getbyte(index - bytes_per_pixel) : 0
+            row.setbyte(index, (row.getbyte(index) + paeth(left, up, up_left)) & 0xFF)
+          end
+        else raise Errors::UnsupportedImageType, "PNG uses an unknown filter type #{filter}"
+        end
+        row
+      end
+
+      def paeth(left, up, up_left)
+        estimate = left + up - up_left
+        distance_left = (estimate - left).abs
+        distance_up = (estimate - up).abs
+        distance_up_left = (estimate - up_left).abs
+        if distance_left <= distance_up && distance_left <= distance_up_left then left
+        elsif distance_up <= distance_up_left then up
+        else up_left
+        end
+      end
+    end
+  end
+end

data/lib/gamba/images.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "digest/sha1"
+require "pathname"
+
+module Prawn
+  def self.image_handler
+    @image_handler ||= ImageHandler.new
+  end
+
+  # The image formats Gamba knows, tried in order on an image's first bytes.
+  class ImageHandler
+    def initialize
+      @handlers = []
+    end
+
+    def register(handler)
+      @handlers.delete(handler)
+      @handlers.push(handler)
+    end
+
+    def register!(handler)
+      @handlers.delete(handler)
+      @handlers.unshift(handler)
+    end
+
+    def unregister(handler)
+      @handlers.delete(handler)
+    end
+
+    def find(image_blob)
+      @handlers.find { _1.can_render?(image_blob) } || raise(Errors::UnsupportedImageType, "image file is an unrecognised format")
+    end
+  end
+
+  module Images
+    def image(file, options = {})
+      Prawn.verify_options(%i[at position vposition height width scale fit], options)
+      pdf_object, info = build_image_object(file)
+      embed_image(pdf_object, info, options)
+      info
+    end
+
+    # The same image bytes are embedded once per document, however many times they are placed.
+    def build_image_object(file)
+      image_content = verify_and_read_image(file)
+      entry = image_registry[Digest::SHA1.hexdigest(image_content)] ||= begin
+        info = Prawn.image_handler.find(image_content).new(image_content)
+        min_version(info.min_pdf_version) if info.respond_to?(:min_pdf_version)
+        {obj: info.build_pdf_object(self), info:}
+      end
+      [entry[:obj], entry[:info]]
+    end
+
+    def embed_image(pdf_object, info, options)
+      width, height = info.calc_image_dimensions(options)
+      if options[:at]
+        x, y = map_to_absolute(options[:at])
+      else
+        x, y = image_position(width, height, options)
+        move_text_position(height)
+      end
+      label = "I#{@image_counter = (@image_counter || 0) + 1}"
+      page.xobjects[label] = pdf_object
+      add_content("\nq\n#{PDF::Core.real_params([width, 0, 0, height, x, y - height])} cm\n/#{label} Do\nQ")
+    end
+
+    private
+
+    def verify_and_read_image(io_or_path)
+      if io_or_path.respond_to?(:rewind)
+        io_or_path.rewind
+        io_or_path.binmode if io_or_path.respond_to?(:binmode)
+        return io_or_path.read
+      end
+      path = Pathname.new(io_or_path)
+      raise ArgumentError, "#{path} not found" unless path.file?
+
+      path.binread
+    end
+
+    def image_position(width, height, options)
+      options[:position] ||= :left
+      y =
+        case options[:vposition]
+        when :top then bounds.absolute_top
+        when :center then bounds.absolute_top - ((bounds.height - height) / 2.0)
+        when :bottom then bounds.absolute_bottom + height
+        when Numeric then bounds.absolute_top - options[:vposition]
+        else determine_y_with_page_flow(height)
+        end
+      x =
+        case options[:position]
+        when :left then bounds.left_side
+        when :center then bounds.left_side + ((bounds.width - width) / 2.0)
+        when :right then bounds.right_side - width
+        when Numeric then options[:position] + bounds.left_side
+        end
+      [x, y]
+    end
+
+    def determine_y_with_page_flow(height)
+      bounds.move_past_bottom if overruns_page?(height)
+      y
+    end
+
+    def overruns_page?(height)
+      (y - height) < reference_bounds.absolute_bottom
+    end
+
+    def image_registry
+      @image_registry ||= {}
+    end
+  end
+end

data/lib/gamba/measurement_extensions.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "measurements"
+
+# 10.mm, 2.cm, 1.in…: lengths in PDF points.
+class Numeric
+  include Prawn::Measurements
+
+  def mm
+    mm2pt(self)
+  end
+
+  def cm
+    cm2pt(self)
+  end
+
+  def dm
+    dm2pt(self)
+  end
+
+  def m
+    m2pt(self)
+  end
+
+  def in
+    in2pt(self)
+  end
+
+  def yd
+    yd2pt(self)
+  end
+
+  def ft
+    ft2pt(self)
+  end
+
+  def pt
+    pt2pt(self)
+  end
+end

data/lib/gamba/measurements.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Prawn
+  # 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/gamba/outline.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Prawn
+  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_method :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::Core::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
+end
+
+module PDF::Core
+  module Destinations
+    def dests
+      names.data[:Dests] ||= ref!(PDF::Core::NameTree.new)
+    end
+
+    def add_dest(name, reference)
+      reference = ref!(reference) unless reference.is_a?(PDF::Core::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/gamba/page.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module PDF::Core
+  # 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 Prawn::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/gamba/page_geometry.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module PDF::Core
+  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 { |millimeters| (millimeters * POINTS_PER_INCH / MILLIMETERS_PER_INCH).round(2) } }
+      .merge(INCHES_BY_SIZE.transform_values { |sides| sides.map { |inches| inches * POINTS_PER_INCH } })
+      .freeze
+  end
+end