pdfrb 0.1.0

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

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    module Cos
+      # Common Object Syntax dictionary (s7.3.7). Wraps a Hash of
+      # Symbol -> PDF value. Subclassed by every semantic Type::*.
+      #
+      # Field metadata can come from two sources (mutually exclusive
+      # per field; last declaration wins):
+      #   * `define_field` — hand-coded (HexaPDF shape).
+      #   * `arlington_object "Name"` — auto-loaded from vendored TSVs
+      #     via Pdfrb::Arlington::Loader. Calls `define_field` under
+      #     the hood with types translated to Ruby classes.
+      class Dictionary < Pdfrb::Model::Object
+        # ---- Per-class field registry ----
+
+        # Shared type registry (s7.7 /Type symbol -> Dictionary
+        # subclass). Lives on the Dictionary class itself, NOT on
+        # subclasses, so register_type from any subclass lands in the
+        # same map.
+        TYPE_MAP = {}
+        private_constant :TYPE_MAP
+
+        class << self
+          # /Type-symbol -> Dictionary subclass. Populated by
+          # `register_type`. Used by Document#wrap to dispatch.
+          def type_map
+            TYPE_MAP
+          end
+
+          def register_type(symbol, klass = self)
+            TYPE_MAP[symbol] = klass
+            klass.define_type(symbol) unless klass.pdf_type
+          end
+
+          def lookup_type(symbol)
+            TYPE_MAP[symbol]
+          end
+
+          # Declare a field on this class. Mirrors HexaPDF's
+          # define_field shape; we add an `arlington:` slot for the
+          # source FieldDefinition.
+          def define_field(pdf_name, type:, required: false, default: nil,
+                           indirect: nil, allowed_values: nil, version: "1.0",
+                           arlington: nil)
+            own_fields[pdf_name] = Fields::Field.new(
+              pdf_name, type: type, required: required, default: default,
+              indirect: indirect, allowed_values: allowed_values,
+              version: version, arlington: arlington
+            )
+          end
+
+          # Look up a field by name; walks the inheritance chain.
+          def field(name)
+            return own_fields[name] if own_fields.key?(name)
+            return superclass.field(name) if superclass <= Pdfrb::Model::Cos::Dictionary
+
+            nil
+          end
+
+          # Iterate (name, Field) pairs across the inheritance chain.
+          def each_field
+            return enum_for(:each_field) unless block_given?
+
+            if superclass <= Pdfrb::Model::Cos::Dictionary
+              superclass.each_field { |n, f| yield n, f }
+            end
+            own_fields.each { |n, f| yield n, f }
+          end
+
+          # Pull field metadata from the named Arlington TSV. Idempotent.
+          # Silently no-ops when the Arlington layer or the TSV is
+          # unavailable, so hand-coded subclasses still work.
+          #
+          # Also registers +self+ in Pdfrb::Model::Type.arlington_registry
+          # under +name+ so field-link resolution can find this class
+          # when other Types reference it.
+          def arlington_object(name, version: "latest")
+            return if arlington_loaded_for?(name)
+            return unless arlington_available?
+
+            definition = Pdfrb::Arlington::Loader.object_definition(name, version: version)
+            return unless definition
+
+            arlington_mark_loaded(name)
+            Pdfrb::Model::Type.register_arlington(name, self) if Pdfrb::Model.const_defined?(:Type)
+            definition.each_field do |field_def|
+              define_field_from_arlington(field_def)
+            end
+          end
+
+          def own_fields
+            @own_fields ||= {}
+          end
+          private :own_fields
+
+          def arlington_loaded_for?(_name)
+            @arlington_loaded_name == name
+          end
+          private :arlington_loaded_for?
+
+          def arlington_mark_loaded(name)
+            @arlington_loaded_name = name
+          end
+          private :arlington_mark_loaded
+
+          def arlington_available?
+            Pdfrb.const_defined?(:Arlington) &&
+              Pdfrb::Arlington.const_defined?(:Loader)
+          rescue StandardError
+            false
+          end
+          private :arlington_available?
+
+          def define_field_from_arlington(field_def)
+            types = arlington_types_to_ruby(field_def)
+            return if types.empty?
+
+            key = arlington_key_to_symbol(field_def.key)
+            define_field(
+              key,
+              type: types.length == 1 ? types.first : types,
+              required: arlington_required?(field_def),
+              default: arlington_default(field_def),
+              version: arlington_version(field_def),
+              arlington: field_def
+            )
+          end
+          private :define_field_from_arlington
+
+          def arlington_types_to_ruby(field_def)
+            field_def.types.map { |t| arlington_one_type_to_ruby(t) }.flatten.compact.uniq
+          end
+          private :arlington_types_to_ruby
+
+          def arlington_one_type_to_ruby(t)
+            case t
+            when :boolean then [TrueClass, FalseClass]
+            when :integer then Integer
+            when :number then [Integer, Float]
+            when :name then Symbol
+            when :string, :"string-ascii", :"string-text" then String
+            when :"string-byte" then Fields::PDFByteString
+            when :array then Pdfrb::Model::PdfArray
+            when :dictionary then Pdfrb::Model::Cos::Dictionary
+            when :stream then Pdfrb::Model::Cos::Stream
+            when :null then NilClass
+            when :date then Fields::PDFDate
+            when :rectangle then Pdfrb::Model::Rectangle
+            when :matrix then Pdfrb::Model::Matrix
+            when :bitmask then Integer
+            when :"name-tree", :"number-tree" then Pdfrb::Model::Cos::Dictionary
+            end
+          end
+          private :arlington_one_type_to_ruby
+
+          def arlington_key_to_symbol(key)
+            key.to_sym
+          end
+          private :arlington_key_to_symbol
+
+          def arlington_required?(field_def)
+            field_def.required_literal == true
+          end
+          private :arlington_required?
+
+          def arlington_default(field_def)
+            return nil if field_def.default_value.nil?
+
+            field_def.default_value
+          end
+          private :arlington_default
+
+          def arlington_version(field_def)
+            field_def.since_version.to_s
+          end
+          private :arlington_version
+        end
+
+        def initialize(value = {}, oid: 0, gen: 0, document: nil)
+          value ||= {}
+          unless value.is_a?(::Hash)
+            raise ArgumentError, "Dictionary value must be a Hash, got #{value.class}"
+          end
+
+          super(value, oid: oid, gen: gen, document: document)
+          apply_required_defaults
+        end
+
+        # Typed access. Resolves References, wraps in field-specific
+        # subclass, applies default, runs converters.
+        def [](name)
+          name = name.to_sym unless name.is_a?(::Symbol)
+          field = self.class.field(name)
+          data = @value[name]
+          data = field.default if data.nil? && field&.default?
+          return nil if data.nil?
+
+          data = dereference(data)
+          data = data.value if unbox_object?(data)
+
+          return data unless field
+
+          converted = Fields.apply(field, data, document)
+          if converted
+            @value[name] = converted
+            converted
+          else
+            data
+          end
+        end
+
+        def []=(name, value)
+          raise ArgumentError, "Dictionary keys must be Symbols" unless name.is_a?(::Symbol)
+
+          @value[name] = value
+        end
+
+        def key?(name)
+          name = name.to_sym unless name.is_a?(::Symbol)
+          !@value[name].nil?
+        end
+
+        def delete(name)
+          name = name.to_sym unless name.is_a?(::Symbol)
+          @value.delete(name)
+        end
+
+        # Iterate (Symbol, processed-value) pairs. Slower than #each_raw
+        # because it runs the full accessor pipeline; use that when
+        # you don't need wrapping.
+        def each
+          return enum_for(:each) unless block_given?
+
+          @value.each_key { |k| yield(k, self[k]) }
+          self
+        end
+
+        # Iterate (Symbol, raw-value) pairs without accessor pipeline.
+        def each_raw
+          return enum_for(:each_raw) unless block_given?
+
+          @value.each { |k, v| yield(k, v) }
+          self
+        end
+
+        def keys; @value.keys; end
+        def empty?; @value.empty?; end
+
+        def pdf_type
+          self.class.pdf_type || self[:Type]
+        end
+
+        # Walk every declared field and yield (message, correctable)
+        # for each violation. Returns an Enumerator if no block given.
+        def validate
+          return enum_for(:validate) unless block_given?
+
+          self.class.each_field do |name, field|
+            validate_one(name, field) { |*a| yield(*a) }
+          end
+        end
+
+        protected
+
+        def dereference(data)
+          return data unless data.is_a?(Pdfrb::Model::Reference)
+          return data if document.nil?
+
+          data.deref(document)
+        end
+
+        private
+
+        def unbox_object?(obj)
+          obj.is_a?(Pdfrb::Model::Object) && !obj.is_a?(Pdfrb::Model::Cos::Dictionary)
+        end
+
+        def apply_required_defaults
+          self.class.each_field do |name, field|
+            next if @value.key?(name) || !field.required? || !field.default?
+
+            @value[name] = field.default
+          end
+        end
+
+        def validate_one(name, field)
+          value = key?(name) ? self[name] : nil
+          if field.required? && value.nil?
+            yield("Required field #{name} is missing", field.default?)
+            self[name] = field.default if field.default?
+            return
+          end
+          return if value.nil?
+
+          unless field.valid_value?(value)
+            yield("Field #{name} has wrong type: #{value.class}", !field.required?)
+            return
+          end
+
+          return unless field.has_allowed_values?
+          return if field.allowed_values.include?(value)
+
+          yield("Field #{name} has disallowed value: #{value.inspect}", false)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    module Cos
+      # Field metadata for a Dictionary entry. Field instances are
+      # created by `Dictionary.define_field` (hand-coded) or by
+      # `arlington_object` (TSV-driven). They drive type conversion,
+      # default application, and validation.
+      module Fields
+        # Use this constant for boolean fields.
+        Boolean = [TrueClass, FalseClass].freeze
+
+        # Marker class for binary-encoded string fields.
+        PDFByteString = Class.new do
+          private_class_method :new
+        end.freeze
+
+        # Marker class for date fields (string in PDF, Time in Ruby).
+        PDFDate = Class.new do
+          private_class_method :new
+        end.freeze
+
+        # One declared field on a Dictionary subclass.
+        class Field
+          attr_reader :pdf_name, :type, :required, :default, :indirect,
+                      :allowed_values, :version, :arlington
+
+          def initialize(pdf_name, type:, required: false, default: nil,
+                         indirect: nil, allowed_values: nil, version: "1.0",
+                         arlington: nil)
+            @pdf_name = pdf_name
+            @type = [type].flatten.freeze
+            @required = required
+            @default = default
+            @indirect = indirect
+            @allowed_values = allowed_values && [allowed_values].flatten.freeze
+            @version = version
+            @arlington = arlington
+            freeze
+          end
+
+          def required?; !!@required; end
+          def default?;  !@default.nil?; end
+          def has_allowed_values?; !@allowed_values.nil?; end
+
+          # Resolve Symbol types via Dictionary.type_map. Returns an
+          # array of Class objects (or empty if no resolution yet).
+          def resolved_types
+            @type.map do |t|
+              next t unless t.is_a?(Symbol)
+              Pdfrb::Model::Cos::Dictionary.lookup_type(t)
+            end.compact
+          end
+
+          def valid_value?(value)
+            types = resolved_types
+            return true if types.empty?
+
+            types.any? do |t|
+              case value
+              when Pdfrb::Model::Object
+                t === value.value || value.is_a?(t)
+              else
+                t === value
+              end
+            end
+          end
+        end
+
+        # ---- Converter modules ----
+        # Stateless. `usable_for?(type)` filters; `convert(data, type,
+        # document)` returns the converted value or nil to fall through.
+
+        module DictionaryConverter
+          module_function
+
+          def usable_for?(type)
+            return true if type.is_a?(Symbol)
+            type.is_a?(Class) && type <= Pdfrb::Model::Cos::Dictionary
+          end
+
+          def additional_types; ::Hash; end
+
+          def convert(data, type, document)
+            first = type.first
+            return if first.nil?
+            return if data.is_a?(first) && !upgradeable?(data, first)
+            return unless data.is_a?(::Hash) || data.is_a?(Pdfrb::Model::Cos::Dictionary)
+
+            # No `type:` — let document#wrap dispatch via /Type so a
+            # field typed as bare Cos::Dictionary still upgrades to a
+            # specific Type::* subclass when the value has a /Type.
+            document&.wrap(data)
+          end
+
+          def upgradeable?(data, declared)
+            # Already-typed subclass of declared base — leave alone.
+            return false unless data.is_a?(Pdfrb::Model::Cos::Dictionary)
+            return false if data.class == Pdfrb::Model::Cos::Dictionary
+
+            data.class <= declared
+          end
+          module_function :upgradeable?
+        end
+
+        module ArrayConverter
+          module_function
+
+          def usable_for?(type); type == Pdfrb::Model::PdfArray; end
+          def additional_types; ::Array; end
+
+          def convert(data, _type, document)
+            return unless data.is_a?(::Array)
+            return data if data.is_a?(Pdfrb::Model::PdfArray)
+
+            document&.wrap(data, type: Pdfrb::Model::PdfArray)
+          end
+        end
+
+        module StringConverter
+          module_function
+
+          def usable_for?(type); type == ::String; end
+          def additional_types; nil; end
+
+          def convert(str, _type, document)
+            return unless str.is_a?(::String)
+            return unless str.encoding == Encoding::BINARY
+
+            handler = document&.config&.[]("document.on_invalid_string")
+            decoded = StringEncoding.decode_text(str, on_invalid: handler)
+            decoded&.encode(Encoding::UTF_8)
+          end
+        end
+
+        module ByteStringConverter
+          module_function
+
+          def usable_for?(type); type == PDFByteString; end
+          def additional_types; ::String; end
+
+          def convert(str, _type, _document)
+            return unless str.is_a?(::String)
+            return str if str.encoding == Encoding::BINARY
+
+            str.dup.force_encoding(Encoding::BINARY)
+          end
+        end
+
+        module DateConverter
+          module_function
+
+          def usable_for?(type); type == PDFDate; end
+          def additional_types; [::String, ::Time]; end
+
+          def convert(value, _type, _document)
+            case value
+            when ::Time then value
+            when ::String then (Pdfrb::Model::Date.parse(value) rescue nil)
+            end
+          end
+        end
+
+        module RectangleConverter
+          module_function
+
+          def usable_for?(type); type == Pdfrb::Model::Rectangle; end
+          def additional_types; [::Array, Pdfrb::Model::PdfArray]; end
+
+          def convert(data, _type, _document)
+            return unless data.is_a?(::Array) || data.is_a?(Pdfrb::Model::PdfArray)
+            return nil if data.empty?
+
+            Pdfrb::Model::Rectangle.from_array(data.to_a)
+          end
+        end
+
+        module IntegerConverter
+          module_function
+
+          def usable_for?(type); type == ::Integer; end
+          def additional_types; nil; end
+
+          def convert(data, _type, _document)
+            return unless data.is_a?(::Float) && data == data.to_i
+
+            data.to_i
+          end
+        end
+
+        CONVERTERS = [
+          DictionaryConverter, ArrayConverter, StringConverter,
+          ByteStringConverter, DateConverter, RectangleConverter,
+          IntegerConverter
+        ].freeze
+
+        def self.converter_for(type)
+          CONVERTERS.find { |c| c.usable_for?(type) }
+        end
+
+        def self.apply(field, data, document)
+          field.type.each do |t|
+            converter = converter_for(t)
+            next unless converter
+
+            result = converter.convert(data, field.type, document)
+            return result if result
+          end
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    module Cos
+      # Helpers for PDF Name (s7.3.5): a Symbol on the Ruby side, a
+      # `/...` token on the wire. Non-printable or delimiter bytes are
+      # `#xx`-escaped; we always emit `#` escapes for the delimiter set
+      # even when printable, to match HexaPDF behaviour.
+      module NameEncoding
+        DELIMITERS = "()<>[]{}/%".b
+        WHITESPACE = " \t\n\f\r\0".b
+        ESCAPE_CHARS = (DELIMITERS + WHITESPACE + "#").b.chars.uniq.freeze
+
+        module_function
+
+        # Symbol -> "/..." String ready for the byte stream.
+        def encode(sym)
+          raise ArgumentError, "Name must be a Symbol" unless sym.is_a?(Symbol)
+
+          +"/" << sym.to_s.each_char.with_object(+"") do |ch, buf|
+            buf << if ESCAPE_CHARS.include?(ch) || ch.bytes.any? { |b| b < 33 || b > 126 }
+                     "#%02X" % ch.bytes.first
+                   else
+                     ch
+                   end
+          end
+        end
+
+        # "/..." or "..." String -> Symbol. `#xx` sequences decoded.
+        def decode(str)
+          s = str.to_s
+          s = s.delete_prefix("/")
+          out = +""
+          i = 0
+          bytes = s.bytes
+          while i < bytes.length
+            b = bytes[i]
+            if b == 35 # #
+              hex = bytes[i + 1, 2]
+              if hex && hex.length == 2 && hex.all? { |h| hex_byte?(h) }
+                hex_str = hex.map(&:chr).join
+                out << hex_str.to_i(16).chr
+                i += 3
+              else
+                out << "#"
+                i += 1
+              end
+            else
+              out << b.chr
+              i += 1
+            end
+          end
+          out.to_sym
+        end
+
+        def hex_byte?(b)
+          (48..57).cover?(b) || (65..70).cover?(b) || (97..102).cover?(b)
+        end
+        module_function :hex_byte?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    module Cos
+      # A Dictionary with an associated raw byte payload (s7.3.8.1).
+      # Filters (s7.4) are applied on read via `decoded_stream` and on
+      # write via `encoded_stream=`.
+      class Stream < Dictionary
+        def initialize(value = {}, stream: "".b, oid: 0, gen: 0, document: nil)
+          super(value, oid: oid, gen: gen, document: document)
+          @stream = stream.to_s.dup.force_encoding(Encoding::BINARY)
+        end
+
+        attr_reader :stream
+
+        def stream=(bytes)
+          @stream = bytes.to_s.dup.force_encoding(Encoding::BINARY)
+          @value[:Length] = @stream.bytesize
+        end
+
+        # Apply /Filter pipeline (if any) to decode the raw stream.
+        # Returns raw bytes when no filter or /Filter /Identity.
+        def decoded_stream
+          filter = raw_filter
+          return @stream if filter.nil? || filter == :Identity
+
+          unless Pdfrb.const_defined?(:Filter)
+            raise Pdfrb::FilterError, "Filter layer not loaded"
+          end
+
+          Pdfrb::Filter.apply(
+            @stream,
+            filters: as_filter_list(filter),
+            parms: as_parms_list(raw_decode_parms),
+            direction: :decode,
+            document: document
+          )
+        end
+
+        # Apply /Filter pipeline in reverse to encode +bytes+. Sets
+        # /Length to the encoded byte count.
+        def encoded_stream=(bytes)
+          filter = raw_filter
+          if filter.nil?
+            @stream = bytes.to_s.dup.force_encoding(Encoding::BINARY)
+          else
+            @stream = Pdfrb::Filter.apply(
+              bytes,
+              filters: as_filter_list(filter),
+              parms: as_parms_list(raw_decode_parms),
+              direction: :encode,
+              document: document
+            )
+          end
+          @value[:Length] = @stream.bytesize
+        end
+
+        private
+
+        def raw_filter
+          @value[:Filter]
+        end
+
+        def raw_decode_parms
+          @value[:DecodeParms] || @value[:DP]
+        end
+
+        # Normalise /Filter to an Array of filter names. /Filter may
+        # be a single Name or an Array of Names.
+        def as_filter_list(filter)
+          case filter
+          when ::Array then filter
+          when Pdfrb::Model::PdfArray then filter.value
+          else [filter]
+          end
+        end
+
+        # Normalise /DecodeParms to an Array of Hashes (one per
+        # filter). /DecodeParms may be a single Hash (applies to all
+        # filters) or an Array of Hashes.
+        # NOTE: Array(Hash) returns [[:k, :v], ...], NOT [hash]. We
+        # must check the type explicitly.
+        def as_parms_list(parms)
+          case parms
+          when nil then []
+          when ::Array then parms
+          when Pdfrb::Model::PdfArray then parms.value
+          when ::Hash then [parms]
+          else [parms]
+          end
+        end
+      end
+    end
+  end
+end