pdfrb 0.1.0

data/lib/pdfrb/model/cos/string_encoding.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    module Cos
+      # Helpers for PDF String (s7.3.2 + s7.9.2).
+      #
+      # Two flavours:
+      #   * text  -> UTF-8 on the Ruby side; serialised as either
+      #              UTF-16BE-with-BOM or PDFDocEncoding on the wire.
+      #   * byte  -> ASCII-8BIT on the Ruby side; serialised as a
+      #              raw byte string (used for /ID, /U, /O, /OE, /UE).
+      #
+      # HexaPDF uses Ruby encoding flags to distinguish; we do the same:
+      # UTF-8 = text, BINARY = byte.
+      module StringEncoding
+        UTF16_BOM = "\xFE\xFF".b
+
+        module_function
+
+        # Decide whether +str+ can be losslessly encoded in PDFDocEncoding.
+        def pdf_doc_encodable?(str)
+          str.encode("UTF-8").each_char.all? do |ch|
+            cp = ch.ord
+            cp < 256 && PDF_DOC_ENCODING[cp] != nil
+          end
+        end
+
+        # Convert a binary string from a PDF source to UTF-8 text.
+        # Auto-detect UTF-16BE BOM; fall back to PDFDocEncoding.
+        def decode_text(bytes, on_invalid: nil)
+          return bytes.encode("UTF-8") if bytes.encoding == Encoding::UTF_8
+
+          s = bytes.dup.force_encoding(Encoding::BINARY)
+          if s.start_with?(UTF16_BOM)
+            body = s.byteslice(2..)
+            utf16 = body.force_encoding(Encoding::UTF_16BE)
+            if utf16.valid_encoding?
+              utf16.encode("UTF-8")
+            elsif on_invalid
+              on_invalid.call(s)
+            else
+              utf16.encode("UTF-8", invalid: :replace, undef: :replace)
+            end
+          else
+            pdf_doc_to_utf8(s)
+          end
+        end
+
+        # Convert a UTF-8 string to PDF wire bytes for a text string.
+        # Uses UTF-16BE+BOM if any char isn't PDFDocEncoding-representable.
+        def encode_text(str)
+          utf8 = str.to_s.encode("UTF-8")
+          if pdf_doc_encodable?(utf8)
+            utf8.encode(Encoding::BINARY, fallback: ->(c) { c.bytes.first.chr })
+          else
+            (UTF16_BOM.dup.force_encoding(Encoding::BINARY) <<
+              utf8.encode(Encoding::UTF_16BE).force_encoding(Encoding::BINARY))
+          end
+        end
+
+        # Mark a string as binary (byte string). Returns a frozen
+        # ASCII-8BIT copy.
+        def mark_binary(str)
+          str.to_s.dup.force_encoding(Encoding::BINARY).freeze
+        end
+
+        # ---- PDFDocEncoding table (s7.9.2.3, Appendix D.2) ----
+        # 256-entry map: byte -> Unicode codepoint. nil = undefined.
+        PDF_DOC_ENCODING = begin
+          table = Array.new(256, nil)
+          (0..255).each { |b| table[b] = b if b < 0x80 } # ASCII pass-through
+          # High-byte mappings per Appendix D.2 (subset; full set is long).
+          high = {
+            0x80 => 0x00C4, 0x81 => 0x00C5, 0x82 => 0x00C7, 0x83 => 0x00C9,
+            0x84 => 0x00D1, 0x85 => 0x00D6, 0x86 => 0x00DC, 0x87 => 0x00E1,
+            0x88 => 0x00E0, 0x89 => 0x00E2, 0x8A => 0x00E4, 0x8B => 0x00E3,
+            0x8C => 0x00E5, 0x8D => 0x00E7, 0x8E => 0x00E9, 0x8F => 0x00E8,
+            0x90 => 0x00EA, 0x91 => 0x00EB, 0x92 => 0x00ED, 0x93 => 0x00EC,
+            0x94 => 0x00EE, 0x95 => 0x00EF, 0x96 => 0x00F1, 0x97 => 0x00F3,
+            0x98 => 0x00F2, 0x99 => 0x00F4, 0x9A => 0x00F6, 0x9B => 0x00F5,
+            0x9C => 0x00FA, 0x9D => 0x00F9, 0x9E => 0x00FB, 0x9F => 0x00FC,
+            0xA0 => 0x2020, 0xA1 => 0x00B0, 0xA2 => 0x00A2, 0xA3 => 0x00A3,
+            0xA4 => 0x00A7, 0xA5 => 0x2022, 0xA6 => 0x00B6, 0xA7 => 0x00DF,
+            0xA8 => 0x00AE, 0xA9 => 0x00A9, 0xAA => 0x2122, 0xAB => 0x00B4,
+            0xAC => 0x00A8, 0xAD => 0x2260, 0xAE => 0x00C6, 0xAF => 0x00D8,
+            0xB0 => 0x221E, 0xB1 => 0x00B1, 0xB2 => 0x2264, 0xB3 => 0x2265,
+            0xB4 => 0x00A5, 0xB5 => 0x00B5, 0xB6 => 0x2202, 0xB7 => 0x2211,
+            0xB8 => 0x220F, 0xB9 => 0x03C0, 0xBA => 0x222B, 0xBB => 0x00AA,
+            0xBC => 0x00BA, 0xBD => 0x03A9, 0xBE => 0x00E6, 0xBF => 0x00F8,
+            0xC0 => 0x00BF, 0xC1 => 0x00A1, 0xC2 => 0x00AC, 0xC3 => 0x221A,
+            0xC4 => 0x0192, 0xC5 => 0x2248, 0xC6 => 0x2206, 0xC7 => 0x00AB,
+            0xC8 => 0x00BB, 0xC9 => 0x2026, 0xCA => 0x00A0, 0xCB => 0x00C0,
+            0xCC => 0x00C3, 0xCD => 0x00D5, 0xCE => 0x0152, 0xCF => 0x0153,
+            0xD0 => 0x2013, 0xD1 => 0x2014, 0xD2 => 0x201C, 0xD3 => 0x201D,
+            0xD4 => 0x2018, 0xD5 => 0x2019, 0xD6 => 0x00F7, 0xD7 => 0x25CA,
+            0xD8 => 0x00FF, 0xD9 => 0x0178, 0xDA => 0x2044, 0xDB => 0x20AC,
+            0xDC => 0x2039, 0xDD => 0x203A, 0xDE => 0xFB01, 0xDF => 0xFB02,
+            0xE0 => 0x2021, 0xE1 => 0x00B7, 0xE2 => 0x201A, 0xE3 => 0x201E,
+            0xE4 => 0x2030, 0xE5 => 0x00C2, 0xE6 => 0x00CA, 0xE7 => 0x00C1,
+            0xE8 => 0x00CB, 0xE9 => 0x00C8, 0xEA => 0x00CD, 0xEB => 0x00CE,
+            0xEC => 0x00CF, 0xED => 0x00CC, 0xEE => 0x00D3, 0xEF => 0x00D4,
+            0xF0 => 0xF8FF, 0xF1 => 0x00D2, 0xF2 => 0x00DA, 0xF3 => 0x00DB,
+            0xF4 => 0x00D9, 0xF5 => 0x0131, 0xF6 => 0x02C6, 0xF7 => 0x02DC,
+            0xF8 => 0x00AF, 0xF9 => 0x02D8, 0xFA => 0x02D9, 0xFB => 0x02DA,
+            0xFC => 0x00B8, 0xFD => 0x02DD, 0xFE => 0x02DB, 0xFF => 0x02C7
+          }
+          high.each { |b, cp| table[b] = cp }
+          table.freeze
+        end
+
+        # Private; build inverse for UTF-8 -> PDFDocEncoding.
+        INVERSE_PDF_DOC_ENCODING =
+          PDF_DOC_ENCODING.each_with_index.each_with_object({}) do |(cp, byte), h|
+            h[cp] = byte if cp
+          end.freeze
+
+        def pdf_doc_to_utf8(bytes)
+          bytes.each_byte.with_object(+"".encode("UTF-8")) do |b, buf|
+            cp = PDF_DOC_ENCODING[b]
+            buf << (cp ? [cp].pack("U") : "?")
+          end
+        end
+
+        def utf8_to_pdf_doc(str)
+          str.each_char.with_object(+"") do |ch, buf|
+            cp = ch.ord
+            byte = INVERSE_PDF_DOC_ENCODING[cp]
+            buf << (byte ? byte.chr : "?")
+          end.force_encoding(Encoding::BINARY)
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/model/cos.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    # COS value layer: literal PDF types and the Dictionary field system
+    # that drives semantic Type subclasses.
+    #
+    # Scalars use native Ruby types wherever possible (no wrapper classes):
+    #   true/false, Integer, Float, Symbol (Name), String, nil (Null).
+    # Helpers for Name encode/decode and String text/binary conversion
+    # live in Cos::NameEncoding and Cos::StringEncoding.
+    module Cos
+      autoload :Fields, "pdfrb/model/cos/fields"
+      autoload :NameEncoding, "pdfrb/model/cos/name_encoding"
+      autoload :StringEncoding, "pdfrb/model/cos/string_encoding"
+      autoload :Dictionary, "pdfrb/model/cos/dictionary"
+      autoload :Stream, "pdfrb/model/cos/stream"
+    end
+  end
+end

data/lib/pdfrb/model/date.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Pdfrb
+  module Model
+    # PDF date (s7.9.4): `D:YYYYMMDDHHmmSSOHH'mm'` string.
+    # Immutable value object wrapping a +Time+.
+    class Date
+      # Tolerates missing fields and the historical quirks Adobe
+      # parsers accept in the wild.
+      REGEX = /\A\s*D?:?(\d{4})(\d\d)?(\d\d)?(\d\d)?(\d\d)?(\d\d)?(Z|[+-])?(?:(\d+)(?:'|'(\d+)'?'?)?)?\s*\z/.freeze
+
+      private_constant :REGEX
+
+      attr_reader :time
+
+      def initialize(time)
+        @time = time
+        freeze
+      end
+
+      def self.parse(str)
+        return new(str) if str.is_a?(::Time)
+        return nil if str.nil?
+        return nil if str.is_a?(::String) && str.empty?
+
+        unless str.is_a?(::String) && (m = REGEX.match(str))
+          raise Pdfrb::ParseError, "invalid PDF date: #{str.inspect}"
+        end
+
+        sign = m[7]
+        utc_offset =
+          if sign.nil? || sign == "Z"
+            0
+          else
+            mul = sign == "-" ? -1 : 1
+            (m[8].to_i * 3600 + m[9].to_i * 60) * mul
+          end
+
+        ::Time.new(
+          m[1].to_i,
+          m[2] ? m[2].to_i.clamp(1, 12) : 1,
+          m[3] ? m[3].to_i.clamp(1, 31) : 1,
+          m[4].to_i.clamp(0, 23),
+          m[5].to_i.clamp(0, 59),
+          m[6].to_i.clamp(0, 59),
+          utc_offset
+        )
+      end
+
+      def self.format(time)
+        off = time.utc_offset
+        sign = off >= 0 ? "+" : "-"
+        aoff = off.abs
+        oh = aoff / 3600
+        om = (aoff % 3600) / 60
+        "D:%04d%02d%02d%02d%02d%02d%s%02d'%02d'" % [
+          time.year, time.month, time.day, time.hour, time.min, time.sec,
+          sign, oh, om
+        ]
+      end
+
+      def to_s
+        self.class.format(@time)
+      end
+
+      def ==(other)
+        case other
+        when Date then @time == other.time
+        when ::Time then @time == other
+        else false
+        end
+      end
+      alias eql? ==
+
+      def hash
+        @time.hash
+      end
+    end
+  end
+end

data/lib/pdfrb/model/matrix.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    # 2D affine transformation matrix `[a b c d e f]` per s8.4.4.
+    # Composes via right-multiplication (PDF convention).
+    # Immutable value object.
+    class Matrix
+      attr_reader :a, :b, :c, :d, :e, :f
+
+      def initialize(a = 1.0, b = 0.0, c = 0.0, d = 1.0, e = 0.0, f = 0.0)
+        @a = a.to_f
+        @b = b.to_f
+        @c = c.to_f
+        @d = d.to_f
+        @e = e.to_f
+        @f = f.to_f
+        freeze
+      end
+
+      def self.identity; new; end
+
+      def self.translate(tx, ty); new(1, 0, 0, 1, tx, ty); end
+
+      def self.scale(sx, sy = sx); new(sx, 0, 0, sy, 0, 0); end
+
+      def self.rotate(rad)
+        co = Math.cos(rad)
+        si = Math.sin(rad)
+        new(co, si, -si, co, 0, 0)
+      end
+
+      def self.skew(alpha, beta)
+        new(1, Math.tan(alpha), Math.tan(beta), 1, 0, 0)
+      end
+
+      def self.from_array(arr)
+        case arr
+        when Matrix then arr
+        when PdfArray, Array then new(*arr.take(6))
+        else raise ArgumentError, "cannot build Matrix from #{arr.class}"
+        end
+      end
+
+      # Compose with +other+. Column-vector convention: the product
+      # `M1 * M2` first transforms a point by M2, then by M1. Matches
+      # PDF's `cm` operator (CTM_new = M_argument * CTM_old).
+      def *(other)
+        Matrix.new(
+          @a * other.a + @c * other.b,
+          @b * other.a + @d * other.b,
+          @a * other.c + @c * other.d,
+          @b * other.c + @d * other.d,
+          @a * other.e + @c * other.f + @e,
+          @b * other.e + @d * other.f + @f
+        )
+      end
+
+      def transform_point(x, y)
+        [@a * x + @c * y + @e, @b * x + @d * y + @f]
+      end
+
+      def identity?
+        @a == 1.0 && @b == 0.0 && @c == 0.0 && @d == 1.0 && @e == 0.0 && @f == 0.0
+      end
+
+      def to_a
+        [@a, @b, @c, @d, @e, @f]
+      end
+
+      def ==(other)
+        other.is_a?(Matrix) && to_a == other.to_a
+      end
+      alias eql? ==
+
+      def hash
+        to_a.hash
+      end
+
+      def inspect
+        "#<Matrix a=#{@a} b=#{@b} c=#{@c} d=#{@d} e=#{@e} f=#{@f}>"
+      end
+    end
+  end
+end

data/lib/pdfrb/model/object.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    # Base wrapper for every PDF value (direct or indirect). Carries
+    # the indirect-reference metadata (oid, gen) and a back-reference
+    # to the owning Document for lazy resolution.
+    #
+    # The wrapped +value+ is the raw Ruby representation:
+    #   Boolean  -> true / false
+    #   Integer  -> Integer
+    #   Real     -> Float
+    #   Name     -> Symbol
+    #   String   -> String (UTF-8 for text, BINARY for bytes)
+    #   Null     -> nil
+    #   Array    -> Array or PdfArray
+    #   Dict     -> Hash or Dictionary
+    #   Stream   -> Stream (subclass of Dictionary)
+    #   Ref      -> Reference
+    class Object
+      attr_reader :value, :oid, :gen, :document
+
+      def initialize(value, oid: 0, gen: 0, document: nil)
+        @value = value
+        @oid = oid.to_i
+        @gen = gen.to_i
+        @document = document
+      end
+
+      # True when this object is referenced indirectly (oid > 0).
+      def indirect?
+        @oid > 0
+      end
+
+      # Overridable. PDF types that must be indirect (Catalog, Pages, ...)
+      # override to return true.
+      def must_be_indirect?
+        false
+      end
+
+      # Resolve a Reference; pass-through for everything else.
+      def deref
+        self
+      end
+
+      # The PDF /Type name (e.g. :Catalog). Subclasses override via
+      # `define_type`. Falls back to value[:Type] for raw dicts.
+      def pdf_type
+        own = self.class.pdf_type
+        return own if own
+        return nil unless @value.is_a?(Hash)
+
+        @value[:Type]
+      end
+
+      def ==(other)
+        return false unless other.is_a?(Pdfrb::Model::Object)
+        return object_id == other.object_id if indirect? && other.indirect?
+
+        @value == other.value
+      end
+
+      class << self
+        # Statically declare the /Type value for this class. Read via
+        # `pdf_type`. Used by Document#wrap to dispatch.
+        def define_type(type)
+          @pdf_type = type
+        end
+
+        def pdf_type
+          defined?(@pdf_type) ? @pdf_type : nil
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/model/pdf_array.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    # Wraps a Ruby Array of PDF values. Subclass of Object so it can
+    # carry oid/gen when stored as an indirect object. Preserves
+    # insertion order and supports type-aware wrapping on access
+    # when nested inside a typed Dictionary (field-driven).
+    class PdfArray < Pdfrb::Model::Object
+      include Enumerable
+
+      def initialize(arr = [], oid: 0, gen: 0, document: nil)
+        super(Array(arr), oid: oid, gen: gen, document: document)
+      end
+
+      def each(&block)
+        @value.each(&block)
+        self
+      end
+
+      def length; @value.length; end
+      alias size length
+
+      def empty?; @value.empty?; end
+
+      def [](idx)
+        @value[idx]
+      end
+
+      def []=(idx, v)
+        @value[idx] = v
+      end
+
+      def <<(v)
+        @value << v
+        self
+      end
+
+      def push(*items)
+        @value.push(*items)
+        self
+      end
+
+      def delete_at(idx)
+        @value.delete_at(idx)
+      end
+
+      def to_a
+        @value.dup
+      end
+
+      def ==(other)
+        return @value == other.value if other.is_a?(PdfArray)
+
+        @value == other
+      end
+
+      def inspect
+        "PdfArray[#{@value.inspect}]"
+      end
+    end
+  end
+end

data/lib/pdfrb/model/rectangle.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    # PDF rectangle (s7.9.5): 4-number array `[llx lly urx ury]`.
+    # Immutable value object.
+    class Rectangle
+      attr_reader :llx, :lly, :urx, :ury
+
+      def initialize(llx, lly, urx, ury)
+        @llx = llx.to_f
+        @lly = lly.to_f
+        @urx = urx.to_f
+        @ury = ury.to_f
+        freeze
+      end
+
+      def self.from_array(arr)
+        case arr
+        when Rectangle then arr
+        when PdfArray, Array then new(arr[0], arr[1], arr[2], arr[3])
+        else raise ArgumentError, "cannot build Rectangle from #{arr.class}"
+        end
+      end
+
+      def width;  @urx - @llx; end
+      def height; @ury - @lly; end
+      def left;   @llx; end
+      def bottom; @lly; end
+      def right;  @urx; end
+      def top;    @ury; end
+
+      def origin; [@llx, @lly]; end
+      def corner; [@urx, @ury]; end
+
+      def to_a
+        [@llx, @lly, @urx, @ury]
+      end
+
+      def ==(other)
+        other.is_a?(Rectangle) && to_a == other.to_a
+      end
+      alias eql? ==
+
+      def hash
+        to_a.hash
+      end
+
+      def inspect
+        "#<Rectangle llx=#{@llx} lly=#{@lly} urx=#{@urx} ury=#{@ury}>"
+      end
+    end
+  end
+end

data/lib/pdfrb/model/reference.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    # A pointer to an indirect object (s7.3.10). Value-equal by (oid, gen)
+    # so it can be a Hash key. Stored inside dictionaries/arrays wherever
+    # an indirect reference appears in source.
+    class Reference
+      include Comparable
+
+      attr_reader :oid, :gen
+
+      def initialize(oid, gen = 0)
+        @oid = oid.to_i
+        @gen = gen.to_i
+        freeze
+      end
+
+      def <=>(other)
+        return nil unless other.is_a?(Reference)
+
+        [oid, gen] <=> [other.oid, other.gen]
+      end
+
+      def hash
+        [oid, gen].hash
+      end
+
+      def eql?(other)
+        other.is_a?(Reference) && oid == other.oid && gen == other.gen
+      end
+
+      alias == eql?
+
+      def to_s
+        "#{oid} #{gen} R"
+      end
+
+      def inspect
+        "#<Pdfrb::Model::Reference oid=#{oid} gen=#{gen}>"
+      end
+
+      # Resolve via the document's object reader. Returns an Object.
+      def deref(document)
+        document.object(self)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    module Type
+      # Action base class (s12.6). Like annotations, action subtypes
+      # each have their own TSV (ActionGoTo, ActionURI, ...) so the
+      # common fields are hand-coded here.
+      class Action < Pdfrb::Model::Cos::Dictionary
+        define_field :Type, type: Symbol, default: :Action
+        define_field :S, type: Symbol, required: true
+        define_field :Next, type: Pdfrb::Model::PdfArray
+
+        register_type :Action
+
+        class << self
+          def subtype_map
+            @subtype_map ||= {}
+          end
+
+          def register_subtype(symbol, klass = self)
+            subtype_map[symbol] = klass
+          end
+
+          def for_subtype(symbol)
+            subtype_map[symbol]
+          end
+        end
+      end
+    end
+  end
+end
+

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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    module Type
+      # PDF 2.0 Associated-File embedded stream (App Note 002).
+      class AFEmbeddedFile < EmbeddedFile
+        arlington_object "AFEmbeddedFileStream"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    module Type
+      # PDF 2.0 Associated-File FileSpec (App Note 002). Adds
+      # /AFRelationship to the base FileSpec.
+      class AFFileSpecification < FileSpecification
+        arlington_object "AFFileSpecification"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    module Type
+      # Annotation base class (s12.5). The base dict shape is encoded
+      # across the per-subtype TSVs (AnnotLink, AnnotText, ...), not
+      # a single Annot.tsv — so the base class registers in the
+      # type_map and dispatches to a specific subtype class via
+      # /Subtype lookup.
+      class Annotation < Pdfrb::Model::Cos::Dictionary
+        # Common annotation fields per s12.5.2 (hand-coded; base dict
+        # is shared across all subtypes before subtype-specific keys).
+        define_field :Type, type: Symbol, default: :Annot
+        define_field :Subtype, type: Symbol, required: true
+        define_field :Rect, type: Pdfrb::Model::Rectangle
+        define_field :Contents, type: String
+        define_field :P, type: Pdfrb::Model::Cos::Dictionary, indirect: true
+        define_field :NM, type: String
+        define_field :M, type: Pdfrb::Model::Cos::Fields::PDFDate
+        define_field :F, type: Integer
+        define_field :AP, type: Pdfrb::Model::Cos::Dictionary
+        define_field :AS, type: Symbol
+        define_field :Border, type: Pdfrb::Model::PdfArray
+        define_field :C, type: Pdfrb::Model::PdfArray
+        define_field :A, type: Pdfrb::Model::Cos::Dictionary
+        define_field :AA, type: Pdfrb::Model::Cos::Dictionary
+
+        register_type :Annot
+
+        class << self
+          # Dispatch by /Subtype. Subclasses register via
+          # `register_subtype :Link`.
+          def subtype_map
+            @subtype_map ||= {}
+          end
+
+          def register_subtype(symbol, klass = self)
+            subtype_map[symbol] = klass
+          end
+
+          def for_subtype(symbol)
+            subtype_map[symbol]
+          end
+        end
+      end
+    end
+  end
+end
+