pdfrb 0.1.0

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    module Type
+      # Cross-reference stream (s7.5.8, PDF 1.5+). Doubles as the
+      # trailer dict in PDF 1.5+ documents.
+      class XRefStream < Pdfrb::Model::Cos::Stream
+        arlington_object "XRefStream"
+        register_type :XRef
+      end
+    end
+  end
+end

data/lib/pdfrb/model/type.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    # Semantic PDF types — one subclass per Arlington TSV. Each class
+    # declares `arlington_object "Name"` and gets its field metadata
+    # auto-loaded from the vendored TSVs at first access.
+    #
+    # The +arlington_registry+ maps TSV name -> Type subclass so other
+    # Types' field-link resolution can find concrete classes.
+    #
+    # Adding a new PDF type = adding one subclass that calls
+    # `arlington_object "TSVName"`. Open/closed: no switch edits.
+    module Type
+      @arlington_registry = {}
+
+      class << self
+        attr_reader :arlington_registry
+
+        # Register a Type subclass under its Arlington TSV name.
+        def register_arlington(name, klass)
+          @arlington_registry[name] = klass
+        end
+
+        # Look up a Type subclass by Arlington TSV name.
+        def lookup(name)
+          @arlington_registry[name]
+        end
+      end
+
+      # Base semantic types (one file per TSV cluster).
+      autoload :FileTrailer, "pdfrb/model/type/file_trailer"
+      autoload :Catalog, "pdfrb/model/type/catalog"
+      autoload :Info, "pdfrb/model/type/info"
+      autoload :PageTreeNode, "pdfrb/model/type/page_tree_node"
+      autoload :PageTreeNodeRoot, "pdfrb/model/type/page_tree_node"
+      autoload :Page, "pdfrb/model/type/page"
+      autoload :Resources, "pdfrb/model/type/resources"
+      autoload :Metadata, "pdfrb/model/type/metadata"
+      autoload :ObjectStream, "pdfrb/model/type/object_stream"
+      autoload :XRefStream, "pdfrb/model/type/xref_stream"
+      autoload :GraphicsStateParameter, "pdfrb/model/type/graphics_state_parameter"
+      autoload :Names, "pdfrb/model/type/names"
+      autoload :Outline, "pdfrb/model/type/outline"
+      autoload :OutlineItem, "pdfrb/model/type/outline_item"
+      autoload :InteractiveForm, "pdfrb/model/type/interactive_form"
+      autoload :OutputIntent, "pdfrb/model/type/output_intent"
+      autoload :EncryptionStandard, "pdfrb/model/type/encryption_standard"
+      autoload :EncryptionPublicKey, "pdfrb/model/type/encryption_public_key"
+      autoload :OptionalContentGroup, "pdfrb/model/type/optional_content_group"
+      autoload :OptionalContentMembership, "pdfrb/model/type/optional_content_membership"
+      autoload :OptionalContentProperties, "pdfrb/model/type/optional_content_properties"
+      autoload :FileSpecification, "pdfrb/model/type/file_specification"
+      autoload :EmbeddedFile, "pdfrb/model/type/embedded_file"
+      autoload :AFFileSpecification, "pdfrb/model/type/af_file_specification"
+      autoload :AFEmbeddedFile, "pdfrb/model/type/af_embedded_file"
+      autoload :StructTreeRoot, "pdfrb/model/type/struct_tree_root"
+      autoload :StructElem, "pdfrb/model/type/struct_elem"
+
+      # XObject family.
+      autoload :XObjectForm, "pdfrb/model/type/xobject_form"
+      autoload :XObjectImage, "pdfrb/model/type/xobject_image"
+
+      # Font family.
+      autoload :Font, "pdfrb/model/type/font"
+      autoload :FontType1, "pdfrb/model/type/font_type1"
+      autoload :FontTrueType, "pdfrb/model/type/font_true_type"
+      autoload :FontType0, "pdfrb/model/type/font_type0"
+      autoload :FontType3, "pdfrb/model/type/font_type3"
+      autoload :CIDFont, "pdfrb/model/type/cid_font"
+      autoload :FontDescriptor, "pdfrb/model/type/font_descriptor"
+
+      # Annotation + Action families (with subtype dispatch).
+      autoload :Annotation, "pdfrb/model/type/annotation"
+      autoload :Action, "pdfrb/model/type/action"
+    end
+  end
+end

data/lib/pdfrb/model.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  # Pdfrb domain model. Two layers:
+  #
+  # * COS (Common Object Syntax) — the literal PDF value types:
+  #   Boolean, Integer, Real, String, Name, Null, Array, Dictionary,
+  #   Stream, Reference. Lives under Model::Cos.
+  #
+  # * Type — semantic PDF object types (Catalog, Page, Font, ...).
+  #   Each is a Dictionary subclass whose field metadata is sourced
+  #   from the vendored Arlington TSVs. Lives under Model::Type.
+  #
+  # Both directions flow through Model:
+  #   "PDF file <=> Model"     parse/serialize target
+  #   "API Builder => Model"   Document/Canvas/Composer build into Model
+  module Model
+    autoload :Object, "pdfrb/model/object"
+    autoload :Reference, "pdfrb/model/reference"
+    autoload :PdfArray, "pdfrb/model/pdf_array"
+    autoload :Rectangle, "pdfrb/model/rectangle"
+    autoload :Matrix, "pdfrb/model/matrix"
+    autoload :Date, "pdfrb/model/date"
+    autoload :Cos, "pdfrb/model/cos"
+    autoload :Type, "pdfrb/model/type"
+  end
+end

data/lib/pdfrb/pdf_constants.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  # PDF lexical and structural constants. Sourced from ISO 32000-2:2020
+  # subclause 7.2 ("Lexical Conventions"). These are the bytes and
+  # tokens the Tokenizer operates on.
+  module PdfConstants
+    # The header magic every PDF file begins with (after optional BOM
+    # or leading whitespace, which the spec discourages but tolerates).
+    HEADER_PREFIX = "%PDF-"
+
+    # Binary-marketing comment recommended after the header so tools
+    # that sniff for binary content treat the file correctly.
+    BINARY_MARKER = "%\xE2\xE3\xCF\xD3".b
+
+    # End-of-file marker (technically just a comment, but conventional).
+    EOF_MARKER = "%%EOF"
+
+    # Whitespace bytes per s7.2.2. NUL, TAB, LF, FF, CR, SPACE.
+    WHITESPACE = "\x00\t\n\f\r ".b
+
+    # Delimiter bytes per s7.2.2.
+    DELIMITERS = "()<>[]{}/%".b
+
+    # Bytes that terminate a name token, a number, or a keyword.
+    TERMINATORS = (WHITESPACE + DELIMITERS).b
+
+    # PDF versions Pdfrb recognises, sorted oldest to newest. The
+    # Arlington model defines the canonical version set; this is its
+    # Ruby mirror.
+    PDF_VERSIONS = %w[1.0 1.1 1.2 1.3 1.4 1.5 1.6 1.7 2.0].freeze
+
+    # Latest PDF version Pdfrb fully understands. Versions newer than
+    # this raise UnsupportedVersionError on read.
+    LATEST_VERSION = "2.0"
+
+    # PDF "object" grammar keywords the Tokenizer treats specially.
+    KEYWORDS = %w[
+      obj endobj stream endstream xref startxref trailer true false null
+    ].freeze
+  end
+end

data/lib/pdfrb/serializer.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  # Model -> PDF bytes (COS values). Stateless; safe to share across
+  # documents. Indirect-object aware: a +Model::Reference+ value is
+  # emitted as `oid gen R`, not inlined.
+  #
+  # Streams are emitted only as part of an indirect object via the
+  # +Writer+ (which handles `obj`/`endobj` framing); the Serializer's
+  # job is to produce the COS-fragment bytes for the dict body, the
+  # stream payload, etc.
+  class Serializer
+    attr_reader :encrypter, :compress_streams, :compress_min_size
+
+    def initialize(encrypter: nil, compress_streams: false, compress_min_size: 256)
+      @encrypter = encrypter
+      @compress_streams = compress_streams
+      @compress_min_size = compress_min_size.to_i
+    end
+
+    class << self
+      def serialize(value, encrypter: nil, **opts)
+        new(encrypter: encrypter, **opts).serialize(value)
+      end
+    end
+
+    def serialize(value)
+      case value
+      when ::Integer then serialize_integer(value)
+      when ::Float then serialize_real(value)
+      when ::Symbol then serialize_name(value)
+      when ::String then serialize_string(value)
+      when true then "true"
+      when false then "false"
+      when nil then "null"
+      when Pdfrb::Model::Reference then serialize_reference(value)
+      when ::Array then serialize_array(value)
+      when Pdfrb::Model::PdfArray then serialize_array(value.value)
+      when ::Hash then serialize_dict(value)
+      when Pdfrb::Model::Cos::Dictionary then serialize_dict(value.value)
+      when Pdfrb::Model::Cos::Stream then serialize_dict(value.value)
+      when Pdfrb::Model::Object then serialize(value.value)
+      when Pdfrb::Model::Date then serialize_date_string(value)
+      when Pdfrb::Model::Rectangle then serialize_array(value.to_a)
+      when Pdfrb::Model::Matrix then serialize_array(value.to_a)
+      else
+        raise Pdfrb::SerializeError,
+              "cannot serialise #{value.class}: #{value.inspect}"
+      end
+    end
+
+    # Serialise an indirect object's body, including `oid gen obj`
+    # header and (for streams) the stream payload.
+    def serialize_indirect(obj)
+      raise ArgumentError, "not indirect: #{obj.inspect}" unless obj.indirect?
+
+      buffer = +""
+      buffer << "#{obj.oid} #{obj.gen} obj\n"
+      case obj
+      when Pdfrb::Model::Cos::Stream
+        dict, payload = emit_stream(obj)
+        buffer << dict
+        buffer << "\nstream\n"
+        buffer << (encrypter ? encrypter.encrypt(payload, obj.oid, obj.gen) : payload)
+        buffer << "\nendstream\n"
+      else
+        buffer << serialize(obj)
+        buffer << "\n"
+      end
+      buffer << "endobj\n"
+      buffer.force_encoding(Encoding::BINARY)
+    end
+
+    private
+
+    # Build the dict body + payload for a stream object, applying
+    # FlateDecode compression when enabled and the stream is large
+    # enough to benefit. Returns [dict_bytes, payload_bytes].
+    def emit_stream(stream_obj)
+      payload = stream_obj.stream
+      hash = stream_obj.value.dup
+      existing_filter = hash[:Filter]
+
+      if should_compress?(stream_obj, payload, existing_filter)
+        compressed = compress_bytes(payload)
+        if compressed.bytesize < payload.bytesize
+          hash[:Filter] = combine_filters(existing_filter, :FlateDecode)
+          hash[:Length] = compressed.bytesize
+          return [serialize_dict(hash), compressed]
+        end
+      end
+
+      hash[:Length] = payload.bytesize
+      [serialize_dict(hash), payload]
+    end
+
+    def should_compress?(stream_obj, payload, existing_filter)
+      return false unless @compress_streams
+      return false if existing_filter # caller knows what they want
+      return false if stream_obj.value[:Type] == :XRef # spec-recommended uncompressed
+      return false if payload.bytesize < @compress_min_size
+
+      true
+    end
+
+    def combine_filters(existing, new_filter)
+      existing ? [existing, new_filter] : new_filter
+    end
+
+    def compress_bytes(bytes)
+      require "zlib"
+      wio = StringIO.new((+"").force_encoding(Encoding::BINARY))
+      w = Zlib::Deflate.new(9)
+      wio.write(w.deflate(bytes, Zlib::FINISH))
+      w.close
+      wio.string
+    end
+
+    def serialize_integer(n)
+      n.to_s
+    end
+
+    def serialize_real(f)
+      # Minimal round-trippable form.
+      s = f.to_s
+      s = s.sub(/\.0+\z/, "") if s.match?(/\A-?\d+\.0+\z/)
+      s
+    end
+
+    def serialize_name(sym)
+      Pdfrb::Model::Cos::NameEncoding.encode(sym)
+    end
+
+    def serialize_string(str)
+      bytes = if str.encoding == Encoding::UTF_8
+                Pdfrb::Model::Cos::StringEncoding.encode_text(str)
+              else
+                str.dup.force_encoding(Encoding::BINARY)
+              end
+      body = bytes.gsub(/[\\()]/) { |c| "\\#{c}" }
+      "(#{body})".b
+    end
+
+    def serialize_reference(ref)
+      "#{ref.oid} #{ref.gen} R"
+    end
+
+    def serialize_array(arr)
+      inner = arr.map { |v| serialize(v) }.join(" ")
+      "[#{inner}]"
+    end
+
+    def serialize_dict(hash)
+      inner = hash.each_with_object(+"") do |(k, v), buf|
+        next if k == :Stream # not a real key, just metadata
+
+        buf << serialize_name(k) << " " << serialize(v) << "\n"
+      end
+      "<<\n#{inner}>>".b
+    end
+
+    def serialize_dict_with_length(stream)
+      # Always (re)set /Length to match the actual stream byte count.
+      hash = stream.value.dup
+      hash[:Length] = stream.stream.bytesize
+      serialize_dict(hash)
+    end
+
+    def serialize_date_string(date)
+      body = date.to_s
+      "(#{body})".b
+    end
+  end
+end

data/lib/pdfrb/source/header_reader.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Source
+    # Reads `%PDF-x.y` header (s7.5.2) and the recommended binary
+    # marker comment. Returns the detected version as a String.
+    module HeaderReader
+      module_function
+
+      def read(io)
+        io.seek(0, IO::SEEK_SET)
+        # Allow up to 1024 bytes of leading garbage before %PDF per
+        # Acrobat tolerance.
+        1024.times do
+          cur = io.pos
+          line = io.gets
+          return nil if line.nil?
+
+          if line.start_with?(PdfConstants::HEADER_PREFIX)
+            io.seek(cur, IO::SEEK_SET)
+            return parse_version(line)
+          end
+        end
+        nil
+      end
+
+      def parse_version(line)
+        m = line.match(/\A%PDF-(\d+\.\d+)/)
+        m ? m[1] : nil
+      end
+      private_class_method :parse_version
+    end
+  end
+end

data/lib/pdfrb/source/helpers.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module Pdfrb
+  module Source
+    # Convenience entry points for tests + one-shot parsing.
+    module_function
+
+    def parse_string(source, document: nil)
+      io = source.is_a?(::String) ? StringIO.new(source.b) : source
+      Parser.new(Tokenizer.new(io), document: document).parse_value
+    end
+
+    def tokenize_string(source)
+      io = source.is_a?(::String) ? StringIO.new(source.b) : source
+      tokens = []
+      tokenizer = Tokenizer.new(io)
+      while (t = tokenizer.next_token)
+        tokens << t
+      end
+      tokens
+    end
+  end
+end

data/lib/pdfrb/source/linearization_detection.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Source
+    # Linearization detection (s7.6.2). A linearized PDF has a
+    # Linearization dict as its first indirect object, immediately
+    # after the header. Detecting this lets readers stream pages in
+    # order (vs. waiting for the whole file to load).
+    module LinearizationDetection
+      module_function
+
+      # Returns true if the file at +io+ is linearized (per the
+      # heuristic from s7.6.2: first indirect object carries a
+      # /Linearized key).
+      def linearized?(io)
+        # Skip header.
+        Pdfrb::Source::HeaderReader.read(io)
+        tokenizer = Pdfrb::Source::Tokenizer.new(io)
+        parser = Pdfrb::Source::Parser.new(tokenizer)
+        # Parse the first indirect object we find.
+        tok = tokenizer.peek
+        return false unless tok&.type == :integer
+
+        obj = parser.parse_indirect_object
+        return false unless obj.value.is_a?(::Hash)
+
+        obj.value.key?(:Linearized)
+      rescue StandardError
+        # Malformed input isn't linearized for our purposes.
+        false
+      end
+    end
+  end
+end

data/lib/pdfrb/source/object_reader.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Source
+    # Resolves Model::Reference values to Model::Object instances by
+    # consulting the document's XrefSection. In-use entries seek and
+    # parse the indirect object at the recorded offset. Compressed
+    # entries defer to ObjectStreamReader.
+    #
+    # Caches resolved objects per document.
+    class ObjectReader
+      attr_reader :document, :xref
+
+      def initialize(document, xref)
+        @document = document
+        @xref = xref
+        @cache = {}
+        @objstm_cache = {}
+      end
+
+      def load(reference)
+        load_oid(reference.oid)
+      end
+
+      def load_oid(oid)
+        return @cache[oid] if @cache.key?(oid)
+
+        entry = xref[oid]
+        return nil if entry.nil? || entry.free?
+
+        obj = case entry.type
+              when :in_use then parse_at(entry.offset, oid, entry.gen)
+              when :compressed then load_from_objstm(entry.obj_stm_oid, entry.index, oid)
+              end
+        @cache[oid] = obj
+        obj
+      end
+
+      def clear_cache
+        @cache.clear
+        @objstm_cache.clear
+      end
+
+      private
+
+      def parse_at(offset, expected_oid, expected_gen)
+        # Try exact offset first (quiet — if it fails, scan nearby).
+        obj = try_parse_at(offset, expected_oid, expected_gen, quiet: true)
+        return obj if obj
+
+        # Real-world PDFs frequently have xref offsets that are off
+        # by a few bytes (CRLF→LF conversion, generator bugs,
+        # incremental edits). Scan ±256 bytes for the right oid/gen.
+        scan_range = (-256..256)
+        scan_range.each do |delta|
+          next if delta.zero?
+          candidate = offset + delta
+          next if candidate.negative?
+
+          obj = try_parse_at(candidate, expected_oid, expected_gen, quiet: true)
+          return obj if obj
+        end
+
+        # Last resort: scan the whole file for "N G obj" pattern.
+        recover_parse(expected_oid, expected_gen)
+      end
+
+      def try_parse_at(offset, expected_oid, expected_gen, quiet: false)
+        document.io.seek(offset, IO::SEEK_SET)
+        tokenizer = Tokenizer.new(document.io)
+        parser = Parser.new(tokenizer, document: document)
+        obj = parser.parse_indirect_object
+        if obj.oid == expected_oid && obj.gen == expected_gen
+          upgrade_to_typed(obj)
+        else
+          nil
+        end
+      rescue StandardError => e
+        quiet ? nil : raise
+      end
+
+      def recover_parse(expected_oid, expected_gen)
+        pattern = /#{expected_oid}\s+#{expected_gen}\s+obj\b/
+        document.io.seek(0, IO::SEEK_SET)
+        data = document.io.read
+        match = data.match(pattern)
+        raise Pdfrb::MalformedPdfError.new(
+          "cannot find object #{expected_oid} #{expected_gen} anywhere in file",
+          recovered: false
+        ) unless match
+
+        offset = match.begin(0)
+        try_parse_at(offset, expected_oid, expected_gen)
+      end
+
+      # Re-wrap the parsed object via document.wrap so a Type::*
+      # subclass (registered for the dict's /Type) is used instead
+      # of the base Cos::Dictionary. Streams stay Streams.
+      def upgrade_to_typed(obj)
+        return obj unless obj.is_a?(Pdfrb::Model::Cos::Dictionary)
+
+        if obj.is_a?(Pdfrb::Model::Cos::Stream)
+          target_class = stream_class_for(obj) || Pdfrb::Model::Cos::Stream
+          replacement = document.wrap(obj.value, type: target_class,
+                                             oid: obj.oid, gen: obj.gen)
+          replacement.stream = obj.stream
+          replacement
+        else
+          document.wrap(obj.value, oid: obj.oid, gen: obj.gen)
+        end
+      end
+
+      def stream_class_for(stream_obj)
+        sym = stream_obj.value[:Type]
+        mapped = sym && Pdfrb::Model::Cos::Dictionary.lookup_type(sym)
+        mapped if mapped && mapped <= Pdfrb::Model::Cos::Stream
+      end
+
+      def load_from_objstm(objstm_oid, index, expected_oid)
+        objstm = @objstm_cache[objstm_oid] ||= ObjectStreamReader.read(load_oid(objstm_oid), document)
+        pair = objstm[index]
+        return nil unless pair
+
+        # ObjectStreamReader returns [oid, value] pairs. Unpack and
+        # wrap as a typed Object so type-dispatch (Catalog, Pages,
+        # etc.) works the same as for uncompressed objects.
+        _oid, value = pair
+        document.wrap(value, oid: expected_oid, gen: 0)
+      end
+    end
+  end
+end

data/lib/pdfrb/source/object_stream_reader.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Source
+    # Object streams (s7.5.7). Decodes the /Type /ObjStm stream and
+    # yields (oid, value) pairs.
+    module ObjectStreamReader
+      module_function
+
+      # Returns an Array of (oid, value) pairs in declaration order.
+      def read(stream_object, document)
+        decoded = stream_object.decoded_stream
+        dict = stream_object
+        n = dict[:N]
+        first = dict[:First] || 0
+        raise Pdfrb::ParseError, "ObjStm missing /N or /First" if n.nil? || first.nil?
+
+        # Header: N pairs of "oid offset" separated by whitespace.
+        header = decoded.byteslice(0, first)
+        pairs = header.split(/\s+/).each_slice(2).to_a
+        raise Pdfrb::ParseError, "ObjStm header mismatch" unless pairs.length == n
+
+        body_io = StringIO.new(decoded.byteslice(first..).to_s.b)
+        tokenizer = Tokenizer.new(body_io)
+        parser = Parser.new(tokenizer, document: document)
+        pairs.each_with_index.map do |(oid_s, _off_s), _i|
+          [oid_s.to_i, parser.parse_value]
+        end
+      end
+    end
+  end
+end