pdfrb 0.6.0 → 0.7.10

data/lib/pdfrb/layout/polygon_frame.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Layout
+    # Polygon-aware Frame: extends Frame to compute available area
+    # against an arbitrary polygon shape, not just a rectangle.
+    # Useful for L-shaped text regions, text-around-image, and
+    # irregular page layouts.
+    #
+    # The default Frame.find_available_area always returns the
+    # top-left rectangle; this subclass finds the largest inscribed
+    # rectangle of (width × height) inside the polygon, scanning
+    # row-by-row to find the leftmost x where the requested box fits
+    # at the requested height.
+    class PolygonFrame < Frame
+      DEFAULT_STEP = 1.0
+
+      attr_reader :polygon
+
+      # @param polygon [Array<Array<Numeric>>] array of [x, y] vertex
+      #   pairs. The polygon is implicitly closed.
+      # @param step [Numeric] scan resolution in PDF units; smaller
+      #   steps find tighter fits but take longer.
+      def initialize(left:, bottom:, width:, height:, polygon: nil, step: DEFAULT_STEP)
+        super(left: left, bottom: bottom, width: width, height: height)
+        @polygon = polygon || [[left, bottom], [left + width, bottom],
+                               [left + width, bottom + height],
+                               [left, bottom + height]]
+        @step = step.to_f
+      end
+
+      # Find the next available area inside the polygon that fits
+      # (width, height). Walks row by row from the top of the
+      # bounding box downward; at each row y, scans x from left
+      # toward the right edge, returning the first (x, y, w, h)
+      # position where all four corners of (x, y - h, w, h) are
+      # inside the polygon.
+      def find_available_area(width, height)
+        w = width.to_f
+        h = height.to_f
+        return nil unless w.positive? && h.positive?
+
+        bbox_top = bounding_box_top
+        bbox_bottom = bounding_box_bottom
+        bbox_left = bounding_box_left
+        bbox_right = bounding_box_right
+
+        y = bbox_top
+        while y - h >= bbox_bottom
+          x = bbox_left
+          while x + w <= bbox_right
+            return [x, y, w, h] if contains_rectangle?(x, y - h, w, h)
+
+            x += @step
+          end
+          y -= @step
+        end
+        nil
+      end
+
+      def bounding_box_top
+        @polygon.map { |_x, y| y }.max.to_f
+      end
+
+      def bounding_box_bottom
+        @polygon.map { |_x, y| y }.min.to_f
+      end
+
+      def bounding_box_left
+        @polygon.map { |x, _y| x }.min.to_f
+      end
+
+      def bounding_box_right
+        @polygon.map { |x, _y| x }.max.to_f
+      end
+
+      # Point-in-polygon test (ray casting).
+      def contains_point?(x, y)
+        inside = false
+        n = @polygon.length
+        i = 0
+        j = n - 1
+        while i < n
+          xi, yi = @polygon[i]
+          xj, yj = @polygon[j]
+          if ((yi > y) != (yj > y)) &&
+              (x < ((xj - xi) * (y - yi) / (yj - yi)) + xi)
+            inside = !inside
+          end
+          j = i
+          i += 1
+        end
+        inside
+      end
+
+      def contains_rectangle?(x, y, w, h)
+        [
+          [x, y],
+          [x + w, y],
+          [x, y + h],
+          [x + w, y + h],
+        ].all? { |px, py| contains_point?(px, py) }
+      end
+    end
+  end
+end

data/lib/pdfrb/layout/table_box.rb

@@ -1,47 +1,64 @@
-# frozen_string_literal: true
+# frozen_string literal: true
 
 module Pdfrb
   module Layout
     # A table of cells. Each cell holds a Box. Column widths are auto
     # unless specified; row heights computed from content.
+    #
+    # Cells may declare +colspan+ / +rowspan+ to occupy multiple
+    # columns or rows. Cell entries can be plain Boxes (treated as
+    # 1x1 cells) or +TableBox::Cell+ instances created via
+    # +TableBox.cell(box, colspan:, rowspan:+).
     class TableBox < Box
+      Cell = Struct.new(:box, :colspan, :rowspan, keyword_init: true) do
+        def initialize(box:, colspan: 1, rowspan: 1)
+          super
+        end
+
+        def fit?(*args); box.fit?(*args); end
+
+        def draw(*args); box.draw(*args); end
+
+        def height; box.height; end
+
+        def width; box.width; end
+      end
+
       attr_reader :rows, :column_widths
 
+      # Build a Cell wrapping +box+ with the given spans.
+      def self.cell(box, colspan: 1, rowspan: 1)
+        Cell.new(box: box, colspan: colspan, rowspan: rowspan)
+      end
+
       def initialize(rows:, column_widths: nil, **)
         super(**)
-        @rows = rows
+        @rows = rows.map { |row| row.map { |c| wrap_cell(c) } }
         @column_widths = column_widths
       end
 
       def fit?(available_width, available_height)
         compute_column_widths(available_width)
-        remaining = available_height
-        @rows.each do |row|
-          row_heights = []
-          row.each_with_index do |cell, col|
-            cell_w = @column_widths[col]
-            cell.fit?(cell_w, remaining) or return false
-            row_heights << cell.height
-          end
-          row_h = row_heights.max || 0
-          remaining -= row_h
-        end
-        @width = available_width
-        @height = available_height - remaining
-        true
+        layout_grid!
+        fit_rows!(available_height)
+        @height <= available_height
       end
 
       def draw_content(canvas, x, y)
         offset_y = y
-        @rows.each do |row|
-          max_h = 0
+        row_heights.each_with_index do |row_h, row_index|
           offset_x = x
-          row.each_with_index do |cell, col|
-            cell.draw(canvas, offset_x, offset_y)
-            offset_x += @column_widths[col]
-            max_h = cell.height if cell.height > max_h
+          @column_widths.each_with_index do |_w, col_index|
+            cell = cell_at(row_index, col_index)
+            if cell && origin?(row_index, col_index, cell)
+              span_w = spanned_width(col_index, cell.colspan)
+              span_h = spanned_height(row_index, cell.rowspan)
+              cell.box.fit?(span_w, span_h)
+              cell.draw(canvas, offset_x, offset_y)
+            end
+            offset_x += @column_widths[col_index]
           end
-          offset_y -= max_h
+          offset_y -= row_h
         end
       end
 
@@ -49,8 +66,23 @@ module Pdfrb
         @rows.empty?
       end
 
+      # Height of each row, indexed by row position. Populated by
+      # +fit?+.
+      def row_heights
+        @row_heights || []
+      end
+
       private
 
+      def wrap_cell(value)
+        return value if value.is_a?(Cell)
+
+        box = value.is_a?(::Hash) ? value[:box] : value
+        colspan = value.is_a?(::Hash) ? (value[:colspan] || 1) : 1
+        rowspan = value.is_a?(::Hash) ? (value[:rowspan] || 1) : 1
+        Cell.new(box: box, colspan: colspan, rowspan: rowspan)
+      end
+
       def compute_column_widths(available_width)
         return @column_widths = equal_widths(available_width) if @column_widths.nil?
 
@@ -61,6 +93,105 @@ module Pdfrb
         col_count = @rows.first&.size || 1
         Array.new(col_count, available_width / col_count)
       end
+
+      # Build a (row, col) -> Cell map accounting for spans, so any
+      # cell covered by a span from above or to the left resolves to
+      # the same Cell instance. @grid[r][c] = the originating Cell.
+      def layout_grid!
+        @grid = ::Array.new(@rows.size) { ::Array.new(column_count) }
+        @origins = {} # [r, c] -> true if this is the top-left of a Cell
+        @rows.each_with_index do |row, r|
+          c = 0
+          row.each do |cell|
+            c = next_free_column(r, c)
+            place_cell(cell, r, c)
+            @origins[[r, c]] = true
+            c += cell.colspan
+          end
+        end
+      end
+
+      def next_free_column(row, col)
+        col += 1 while @grid[row] && @grid[row][col]
+        col
+      end
+
+      def place_cell(cell, row, col)
+        cell.rowspan.times do |dr|
+          cell.colspan.times do |dc|
+            r = row + dr
+            c = col + dc
+            next unless @grid[r] && c < @grid[r].size
+
+            @grid[r][c] = cell
+          end
+        end
+      end
+
+      def column_count
+        @column_widths.length
+      end
+
+      def cell_at(row, col)
+        @grid[row]&.[](col)
+      end
+
+      def origin?(row, col, cell)
+        # The cell is the origin if the grid position matches the
+        # cell's top-left (i.e. the position above and to the left
+        # belongs to a different cell or none).
+        return true if row.zero? && col.zero?
+
+        above = row.positive? ? @grid[row - 1][col] : nil
+        left = col.positive? ? @grid[row][col - 1] : nil
+        above != cell && left != cell
+      end
+      alias is_origin? origin?
+
+      def spanned_width(start_col, colspan)
+        span = colspan
+        @column_widths[start_col, span].sum
+      end
+
+      def spanned_height(start_row, rowspan)
+        span = rowspan
+        @row_heights[start_row, span]&.sum || 0
+      end
+
+      def fit_rows!(available_height)
+        @row_heights = compute_row_heights(available_height)
+        @height = @row_heights.sum
+        @width = @column_widths.sum
+        self
+      end
+
+      # First pass: compute the natural height of each row by taking
+      # the max content height across cells in that row, ignoring
+      # rowspan contributions to non-origin rows.
+      def compute_row_heights(available_height)
+        heights = ::Array.new(@rows.size, 0)
+        @rows.each_with_index do |row, r|
+          row.each_with_index do |_cell, _c|
+            # Handled via grid below for span correctness.
+          end
+          # Use the grid to skip span-occupied cells.
+          column_count.times do |c|
+            cell = @grid[r][c]
+            next unless cell && origin?(r, c, cell)
+
+            span_w = spanned_width(c, cell.colspan)
+            cell.fit?(span_w, available_height)
+            cell_h = cell.height.to_f
+            # Distribute the height across the rows the cell spans.
+            distribute = [(cell_h / cell.rowspan).ceil, 1].max
+            cell.rowspan.times do |dr|
+              rr = r + dr
+              heights[rr] = [heights[rr], distribute].max if heights[rr]
+            end
+          end
+        end
+        heights
+      end
     end
   end
 end

data/lib/pdfrb/layout/text_shaper.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Layout
+    # Text shaping interface. Pure-Ruby shapers don't exist for the
+    # complexity of OpenType GSUB/GPOS — this module defines the
+    # contract that a real shaper (HarfBuzz, fribidi, etc.) must
+    # satisfy. Callers can plug in a shaper implementation via
+    # Pdfrb::Layout::TextShaper.implementation = MyShaper.
+    #
+    # The default implementation is grapheme-cluster-aware: it keeps
+    # each user-perceived character (a base + combining marks, a
+    # Hangul syllable, an emoji-ZWJ sequence, etc.) together as one
+    # cluster so the TextLayouter measures and breaks at cluster
+    # boundaries, never inside one.
+    module TextShaper
+      @implementation = nil
+
+      ShapedRun = Struct.new(:codepoints, :clusters, :advances,
+                             :cluster_starts, keyword_init: true)
+
+      class << self
+        attr_accessor :implementation
+
+        # Shape +text+ for +font+ at +size+. Returns a ShapedRun.
+        #
+        # When an +implementation+ is registered, delegates to it.
+        # Otherwise runs the default grapheme-cluster shaper.
+        def shape(text, font: nil, size: 12, direction: :ltr)
+          if implementation
+            return implementation.shape(text, font: font, size: size,
+                                              direction: direction)
+          end
+
+          default_shape(text, size, direction)
+        end
+
+        private
+
+        # Default shaper: one cluster per grapheme. Each cluster's
+        # advance is its base-codepoint width (combining marks add
+        # zero). Falls back to size/2 when font metrics aren't
+        # available.
+        def default_shape(text, size, _direction)
+          clusters = text.to_s.grapheme_clusters.to_a
+          codepoints = []
+          cluster_indices = []
+          advances = []
+          cluster_starts = []
+
+          clusters.each_with_index do |cluster, cluster_idx|
+            cluster_starts << codepoints.length
+            cps = cluster.codepoints.to_a
+            cps.each do |cp|
+              codepoints << cp
+              cluster_indices << cluster_idx
+              advances << advance_for(cp, size, cps)
+            end
+          end
+
+          ShapedRun.new(
+            codepoints: codepoints,
+            clusters: cluster_indices,
+            advances: advances,
+            cluster_starts: cluster_starts
+          )
+        end
+
+        # Per-codepoint advance. Combining marks (Unicode general
+        # category M*) contribute 0; everything else gets size/2
+        # as a heuristic unless real metrics are available.
+        def advance_for(codepoint, size, _cluster_cps)
+          return 0.0 if combining_mark?(codepoint)
+          return size * 0.6 if wide?(codepoint)
+
+          # Heuristic average advance for ASCII range.
+          size / 2.0
+        end
+
+        # Combining marks: Unicode general categories Mn, Mc, Me.
+        # Subset of common ranges; the full list is in
+        # UnicodeData.txt.
+        def combining_mark?(codepoint)
+          ranges = [
+            0x0300..0x036F,   # Combining Diacritical Marks
+            0x0483..0x0489,
+            0x0591..0x05BD,
+            0x05BF..0x05BF,
+            0x05C1..0x05C2, 0x05C4..0x05C5, 0x05C7..0x05C7,
+            0x0610..0x061A,
+            0x064B..0x065F,
+            0x0670..0x0670,
+            0x06D6..0x06DC,
+            0x06DF..0x06E4,
+            0x06E7..0x06E8,
+            0x06EA..0x06ED,
+            0x0711..0x0711,
+            0x0730..0x074A,
+            0x0900..0x0903,
+            0x093A..0x094F,
+            0x0951..0x0957,
+            0x20D0..0x20FF,   # Combining marks for symbols
+            0xFE00..0xFE0F    # Variation selectors
+          ]
+          ranges.any? { |r| r.cover?(codepoint) }
+        end
+
+        # Wide characters: CJK + emoji. These typically take 1em
+        # advance (double-width of a Latin letter).
+        def wide?(codepoint)
+          ranges = [
+            0x1100..0x115F,   # Hangul Jamo
+            0x2E80..0x303E,   # CJK Radicals
+            0x3040..0x33BF,   # Hiragana, Katakana, CJK
+            0x3400..0x4DBF,   # CJK Extension A
+            0x4E00..0x9FFF,   # CJK Unified Ideographs
+            0xA000..0xA4CF,   # Yi
+            0xAC00..0xD7A3,   # Hangul Syllables
+            0xF900..0xFAFF,   # CJK Compatibility Ideographs
+            0xFE30..0xFE4F,   # CJK Compatibility Forms
+            0x1F000..0x1FAFF, # Emoji + extensions
+            0x20000..0x2FFFF, # CJK Extension B+
+          ]
+          ranges.any? { |r| r.cover?(codepoint) }
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/layout.rb

@@ -15,6 +15,7 @@ module Pdfrb
     autoload :ImageBox, "pdfrb/layout/image_box"
     autoload :ListBox, "pdfrb/layout/list_box"
     autoload :TableBox, "pdfrb/layout/table_box"
+    autoload :MultiPageTableBox, "pdfrb/layout/multi_page_table_box"
     autoload :ColumnBox, "pdfrb/layout/column_box"
     autoload :InlineBox, "pdfrb/layout/inline_box"
     autoload :BoxFitter, "pdfrb/layout/box_fitter"
@@ -23,6 +24,12 @@ module Pdfrb
     autoload :TextFragment, "pdfrb/layout/text_fragment"
     autoload :Line, "pdfrb/layout/line"
     autoload :Bidi, "pdfrb/layout/bidi"
+    autoload :Hyphenation, "pdfrb/layout/hyphenation"
+    autoload :TextShaper, "pdfrb/layout/text_shaper"
+    autoload :PolygonFrame, "pdfrb/layout/polygon_frame"
+    autoload :FontFallback, "pdfrb/layout/font_fallback"
+    autoload :JustificationKashidas, "pdfrb/layout/justification_kashidas"
+    autoload :MultiCellTextLayout, "pdfrb/layout/multi_cell_text_layout"
     autoload :RomanNumeral, "pdfrb/layout/list_box"
   end
 end

data/lib/pdfrb/model/type/page_piece_info.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    module Type
+      # Page-piece dictionary (s14.5). Per-page metadata recording
+      # application-specific private data. The dictionary hangs off
+      # a page's /PieceInfo key and is keyed by application name;
+      # each value carries /LastModified, /Private, and (optionally)
+      # an /ASFStream reference for a stream-encoded private payload.
+      #
+      # Conforming readers MUST NOT interpret application-private
+      # data; it survives round-trips and incremental updates intact.
+      class PagePieceInfo < Pdfrb::Model::Cos::Dictionary
+        # The application-name key (e.g. :Adobe, :Pdfrb). Multiple
+        # applications may each have their own entry in the same
+        # /PieceInfo dict.
+        def application_name
+          value.key?(:Application) ? value[:Application] : nil
+        end
+
+        # /LastModified — PDF date string, parsed to a Time.
+        def last_modified
+          v = value[:LastModified]
+          return nil unless v.is_a?(::String)
+
+          Pdfrb::Model::Date.parse(v)
+        end
+
+        # /Private — application-private dict. Untyped on purpose:
+        # the contents are app-defined.
+        def private_data
+          value[:Private]
+        end
+
+        # Set the application's /LastModified to +time+. +time+ is
+        # converted to a PDF date string.
+        def last_modified=(time)
+          value[:LastModified] = Pdfrb::Model::Date.format(time)
+        end
+
+        # Merge +hash+ into /Private. If /Private is absent, it is
+        # created from the hash.
+        def merge_private!(hash)
+          existing = value[:Private]
+          if existing.is_a?(Pdfrb::Model::Cos::Dictionary)
+            existing.value.merge!(hash)
+          elsif existing.is_a?(::Hash)
+            existing.merge!(hash)
+          else
+            value[:Private] = hash
+          end
+          self
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/model/type.rb

@@ -353,6 +353,9 @@ module Pdfrb
       # Structure types (s14.7).
       autoload :StructureAttributes, "pdfrb/model/type/structure_attributes"
       autoload :StructureElementKid, "pdfrb/model/type/structure_element_kid"
+
+      # Page-piece dictionary (s14.5).
+      autoload :PagePieceInfo, "pdfrb/model/type/page_piece_info"
     end
   end
 end

data/lib/pdfrb/source/linearization_reader.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Source
+    # Reads the Linearization dictionary (Annex F) that lives on the
+    # first indirect object of a linearized PDF. Exposes the
+    # page-one fast-path offset (/O), end of first page (/E), number
+    # of pages (/N), and the hint stream offset (/T) so callers can
+    # resolve page 1 without parsing the rest of the file.
+    #
+    # A non-linearized PDF returns nil from .detect.
+    class LinearizationReader
+      LinearizationInfo = Struct.new(
+        :linearized,    # 1.0 marker
+        :file_length,   # /L
+        :first_page_obj_offset, # /O
+        :first_page_end_offset, # /E
+        :page_count, # /N
+        :hint_stream_offset, # /T
+        :primary_hint_offset, # /H [offset, length]
+        keyword_init: true
+      )
+
+      class << self
+        # Parse the first indirect object at offset 0 in +io+ and
+        # return a LinearizationInfo if it's a Linearization dict,
+        # nil otherwise.
+        def detect(io)
+          io.seek(0, IO::SEEK_SET)
+          header = io.read(1024).to_s
+          return nil unless header.start_with?("%PDF-")
+
+          # Skip the header line, then look for the first "N G obj"
+          # marker. The Linearization dict is on the first indirect
+          # object in a linearized file.
+          io.seek(0, IO::SEEK_SET)
+          tok = Pdfrb::Source::Tokenizer.new(io)
+          parser = Pdfrb::Source::Parser.new(tok, document: nil)
+          first_obj = begin
+            parser.parse_indirect_object
+          rescue StandardError
+            nil
+          end
+          return nil unless first_obj
+
+          dict = dictionary_value(first_obj)
+          return nil unless dict && dict[:Linearized]
+
+          build_info(dict)
+        end
+
+        private
+
+        def dictionary_value(obj)
+          return obj.value if obj.is_a?(Pdfrb::Model::Cos::Dictionary)
+          return obj.value if obj.is_a?(Pdfrb::Model::Cos::Stream)
+
+          obj if obj.is_a?(::Hash)
+        end
+
+        def build_info(dict)
+          hint = dict[:H]
+          LinearizationInfo.new(
+            linearized: dict[:Linearized].to_s,
+            file_length: dict[:L]&.to_i,
+            first_page_obj_offset: dict[:O]&.to_i,
+            first_page_end_offset: dict[:E]&.to_i,
+            page_count: dict[:N]&.to_i,
+            hint_stream_offset: dict[:T]&.to_i,
+            primary_hint_offset: hint.is_a?(::Array) ? hint : nil
+          )
+        end
+      end
+    end
+  end
+end