pdfrb 0.7.1 → 0.7.11

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/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

data/lib/pdfrb/source/recovery.rb

@@ -6,9 +6,23 @@ module Pdfrb
     # patterns and synthesise an XrefSection from the offsets found.
     # Triggered when the xref table is missing or points to a wrong
     # offset.
+    #
+    # Extended recovery capabilities:
+    #   * Cross-reference table reconstruction (the original mode).
+    #   * Trailer recovery: find /Root and /Encrypt by scanning for
+    #     the keys directly when the trailer is corrupt.
+    #   * Hybrid xref detection: read both xref table and xref stream
+    #     when both are present.
+    #   * Object-stream reconstruction: rebuild an XrefSection from a
+    #     /Type /ObjStm stream when its header is intact but the
+    #     xref stream is missing.
     module Recovery
       OBJ_PATTERN = /(\d+)\s+(\d+)\s+obj\b/.freeze
-      private_constant :OBJ_PATTERN
+      TRAILER_ROOT_PATTERN = %r{/Root\s+(\d+)\s+(\d+)\s+R}.freeze
+      TRAILER_ENCRYPT_PATTERN = %r{/Encrypt\s+(\d+)\s+(\d+)\s+R}.freeze
+      TRAILER_INFO_PATTERN = %r{/Info\s+(\d+)\s+(\d+)\s+R}.freeze
+      private_constant :OBJ_PATTERN, :TRAILER_ROOT_PATTERN,
+                       :TRAILER_ENCRYPT_PATTERN, :TRAILER_INFO_PATTERN
 
       module_function
 
@@ -30,6 +44,56 @@ module Pdfrb
         end
         section
       end
+
+      # Scan the file for /Root, /Info, /Encrypt references when the
+      # trailer dict is unreadable. Returns a Hash with :Root, :Info,
+      # :Encrypt keys as References (or nil per key).
+      def recover_trailer_references(io)
+        io.seek(0, IO::SEEK_SET)
+        data = io.read.to_s
+        data.force_encoding(Encoding::BINARY)
+
+        root_match = data.match(TRAILER_ROOT_PATTERN)
+        info_match = data.match(TRAILER_INFO_PATTERN)
+        encrypt_match = data.match(TRAILER_ENCRYPT_PATTERN)
+
+        {
+          Root: root_match ? Pdfrb::Model::Reference.new(root_match[1].to_i, root_match[2].to_i) : nil,
+          Info: info_match ? Pdfrb::Model::Reference.new(info_match[1].to_i, info_match[2].to_i) : nil,
+          Encrypt: encrypt_match ? Pdfrb::Model::Reference.new(encrypt_match[1].to_i, encrypt_match[2].to_i) : nil,
+        }
+      end
+
+      # Detect hybrid xref: PDF 1.7+ allows both a classical xref
+      # table AND an xref stream in the same revision, referenced
+      # from the table via /XRefStm. Returns true if the file has
+      # both. Pure-Ruby: scans for `startxref` followed by both
+      # `xref` and a Type=XRef stream object.
+      def hybrid_xref?(io)
+        io.seek(0, IO::SEEK_SET)
+        data = io.read.to_s
+        data.force_encoding(Encoding::BINARY)
+
+        has_table = data.include?("\nxref\n")
+        has_stream = data.match?(/\/Type\s*\/XRef\b/)
+        has_table && has_stream
+      end
+
+      # Reconstruct an XrefSection from a /Type /ObjStm stream by
+      # reading its /N + /First + decompressed body. Used when the
+      # outer xref stream is corrupt but a known ObjStm is intact.
+      def rebuild_from_object_stream(objstm, document)
+        return nil unless objstm
+
+        pairs = ObjectStreamReader.read(objstm, document)
+        section = XrefSection.new
+        pairs.each_key do |oid|
+          # Mark as compressed in objstm 0 (placeholder; caller
+          # fills in the real objstm_oid).
+          section.add_compressed(oid, 0, 0, objstm.oid)
+        end
+        section
+      end
     end
   end
 end

data/lib/pdfrb/source/tokenizer.rb

@@ -52,6 +52,27 @@ module Pdfrb
         self
       end
 
+      # Whether the underlying IO is at end of stream.
+      def eof?
+        @io.eof?
+      end
+
+      # Read one byte from the underlying IO. Returns nil at EOF.
+      def read_byte
+        b = @io.getbyte
+        @pos += 1 if b
+        b
+      end
+
+      # Skip whitespace bytes (NUL, HT, LF, FF, CR, SP).
+      def skip_whitespace
+        while (b = peek_byte)
+          break unless WHITESPACE_BYTES.include?(b)
+
+          advance_byte
+        end
+      end
+
       private
 
       def fill_lookahead(n)

data/lib/pdfrb/source.rb

@@ -20,5 +20,6 @@ module Pdfrb
     autoload :ObjectStreamReader, "pdfrb/source/object_stream_reader"
     autoload :Recovery, "pdfrb/source/recovery"
     autoload :LinearizationDetection, "pdfrb/source/linearization_detection"
+    autoload :LinearizationReader, "pdfrb/source/linearization_reader"
   end
 end