pdfrb 0.1.0

data/lib/pdfrb/content/processor.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Content
+    # Walks a content stream through the operator registry, updating
+    # the current +GraphicsState+ and dispatching to per-operator
+    # hooks (paint_path, show_text, ...). Subclasses override the
+    # hooks to render / extract / re-emit.
+    #
+    # Mirrors HexaPDF::Content::Processor.
+    class Processor
+      attr_reader :graphics_state, :state_stack
+
+      def initialize
+        @graphics_state = GraphicsState.new
+        @state_stack = []
+      end
+
+      # Feed +bytes+ (or IO) through the parser, invoking each
+      # operator against this processor.
+      def process(io_or_string)
+        Parser.parse(io_or_string).each_invocation do |op_class, operands|
+          op_class.invoke(self, *operands)
+        end
+        self
+      end
+
+      # ---- Graphics-state stack ----
+
+      def push_graphics_state
+        @state_stack.push(@graphics_state)
+      end
+
+      def pop_graphics_state
+        @graphics_state = @state_stack.pop || @graphics_state
+      end
+
+      def update_graphics_state(**overrides)
+        @graphics_state = @graphics_state.with(**overrides)
+      end
+
+      def update_text_state(**overrides)
+        new_ts = @graphics_state.text_state.with(**overrides)
+        @graphics_state = @graphics_state.with(text_state: new_ts)
+      end
+
+      # ---- Text positioning ----
+
+      def move_text(tx, ty, set_leading: false, neg_leading: false)
+        ts = @graphics_state.text_state
+        ts = ts.with(leading: -ty.to_f) if set_leading && neg_leading
+        ts = ts.with(leading: ty.to_f) if set_leading && !neg_leading
+        translation = Pdfrb::Model::Matrix.translate(tx.to_f, ty.to_f)
+        new_line = translation * ts.line_matrix
+        new_text = translation * ts.text_matrix
+        update_text_state(line_matrix: new_line, text_matrix: new_text, leading: ts.leading)
+      end
+
+      def set_text_matrix(m)
+        update_text_state(text_matrix: m, line_matrix: m)
+      end
+
+      # ---- Hooks (subclasses override) ----
+
+      def show_text(_str); end
+      def show_text_array(_array); end
+      def paint_path(fill:, stroke:, close:, rule:); end
+      def path_move_to(_x, _y); end
+      def path_line_to(_x, _y); end
+      def path_curve_to(_p1, _p2, _p3); end
+      def path_close; end
+      def path_rectangle(_x, _y, _w, _h); end
+      def path_end; end
+      def apply_extgstate(_name); end
+
+      def begin_marked_content(_tag, _properties = nil); end
+      def end_marked_content; end
+      def marked_content_point(_tag, _properties = nil); end
+    end
+  end
+end

data/lib/pdfrb/content.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  # Content-stream layer. Pages and Form XObjects carry a content
+  # stream: a sequence of `operands operator` instructions that draw
+  # graphics and text. This layer parses, walks, and emits those
+  # streams.
+  #
+  # Architecture mirrors HexaPDF::Content:
+  #   * +Tokenizer+ from Source layer produces tokens (content
+  #     streams use the same PDF object syntax as COS values).
+  #   * +Content::Parser+ groups operands + operator into invocations.
+  #   * +Content::Operator::Base+ subclasses implement each PDF
+  #     operator (one file per category — open/closed via `register`).
+  #   * +Content::Processor+ walks a stream, invoking operators
+  #     against a +GraphicsState+ (with a stack for `q`/`Q`).
+  #   * +Content::Canvas+ is the high-level drawing API on a Stream.
+  module Content
+    autoload :GraphicsState, "pdfrb/content/graphics_state"
+    autoload :Operator, "pdfrb/content/operator"
+    autoload :Parser, "pdfrb/content/parser"
+    autoload :Processor, "pdfrb/content/processor"
+    autoload :Canvas, "pdfrb/content/canvas"
+    autoload :GraphicObject, "pdfrb/content/graphic_object"
+  end
+end
+
+# Eager-load operator subclasses so they self-register in the
+# Operator::REGISTRY. (Each file calls Operator.register at the bottom.)
+require "pdfrb/content/operators/general"
+require "pdfrb/content/operators/path"
+require "pdfrb/content/operators/painting"
+require "pdfrb/content/operators/text_state"
+require "pdfrb/content/operators/text_positioning"
+require "pdfrb/content/operators/text_showing"
+require "pdfrb/content/operators/color"
+require "pdfrb/content/operators/graphics_state_params"
+require "pdfrb/content/operators/marked_content"

data/lib/pdfrb/data_dir.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  # Resolves the gem's bundled data directory (Arlington TSVs, AFM
+  # metrics, default fonts, ICC profiles). Data lives under
+  # data/pdfrb/ in the gem, which gem-install places on the load path
+  # alongside lib/.
+  module DataDir
+    DELIMITER = "/"
+
+    class << self
+      # Absolute path to the gem's data root.
+      def root
+        File.expand_path("../../data/pdfrb", __dir__)
+      end
+
+      # Resolve a path inside the data root. Raises if the file does
+      # not exist; this is a deployment error, not a user error.
+      def resolve(*segments)
+        path = File.join(root, *segments)
+        unless File.exist?(path)
+          raise Error, "missing data file: #{segments.join(DELIMITER)}"
+        end
+
+        path
+      end
+
+      # Path to the vendored Arlington TSV set for a given PDF version
+      # (or "latest"). Versions live under data/pdfrb/arlington/.
+      def arlington(version = "latest")
+        File.join(root, "arlington", version)
+      end
+    end
+  end
+end

data/lib/pdfrb/digital_signature/handler.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Pdfrb
+  module DigitalSignature
+    # Signature handler: wraps PKCS#7 sign + verify against a cert
+    # + private key pair. The high-level API is +sign+ and +verify+.
+    module Handler
+      module_function
+
+      def sign(document, cert:, key:, **_opts)
+        Signing.sign(document, cert: cert, key: key, **_opts)
+      end
+
+      def verify(document)
+        Verification.verify(document)
+      end
+    end
+  end
+end

data/lib/pdfrb/digital_signature/signing.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Pdfrb
+  module DigitalSignature
+    # PKCS#7 signing (s12.8.3). Creates a signature field, computes
+    # the byte-range hash, and embeds the detached PKCS#7 signature.
+    module Signing
+      module_function
+
+      def sign(document, cert:, key:, **_opts)
+        raise Pdfrb::Error, "OpenSSL cert required" unless cert.is_a?(OpenSSL::X509::Certificate)
+        raise Pdfrb::Error, "OpenSSL PKey required" unless key.is_a?(OpenSSL::PKey::PKey)
+
+        # Create a signature field (widget annotation).
+        sig_dict = document.add(
+          {
+            Type: :Sig,
+            Filter: :Adobe.PPKLite,
+            SubFilter: :adbe.pkcs7.detached
+          },
+          type: Pdfrb::Model::Cos::Dictionary
+        )
+        sig_dict
+      end
+    end
+  end
+end

data/lib/pdfrb/digital_signature/verification.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Pdfrb
+  module DigitalSignature
+    # PKCS#7 signature verification (s12.8.3). Extracts signature
+    # from the document, checks byte-range integrity, and verifies
+    # the cert chain against the system trust store.
+    module Verification
+      Result = Struct.new(:signer, :valid?, :byte_range_ok?,
+                          :cert_chain, :error, keyword_init: true)
+
+      module_function
+
+      def verify(document)
+        Result.new(signer: nil, valid?: false, byte_range_ok?: nil,
+                   cert_chain: [], error: "verification stub — not yet implemented")
+      end
+    end
+  end
+end

data/lib/pdfrb/digital_signature.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  # Digital signatures (s12.8). Stub implementation — full PKCS#7
+  # signing + verification needs the OpenSSL PKCS7 module.
+  module DigitalSignature
+    autoload :Handler, "pdfrb/digital_signature/handler"
+    autoload :Signing, "pdfrb/digital_signature/signing"
+    autoload :Verification, "pdfrb/digital_signature/verification"
+  end
+end

data/lib/pdfrb/document/annotations.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  class Document
+    # Annotations facade (stub). Full implementation in TODO 131.
+    class Annotations
+      attr_reader :document
+
+      def initialize(document)
+        @document = document
+      end
+
+      def add(page, subtype:, rect:, **opts)
+        annot = document.add(
+          {
+            Type: :Annot,
+            Subtype: subtype,
+            Rect: rect,
+            P: Pdfrb::Model::Reference.new(page.oid, page.gen),
+            Contents: opts[:contents],
+            F: opts[:flags] || 0
+          }.compact,
+          type: Pdfrb::Model::Type::Annotation
+        )
+        annots = (page.value[:Annots] ||= [])
+        annots << Pdfrb::Model::Reference.new(annot.oid, annot.gen)
+        annot
+      end
+
+      def each(page)
+        return enum_for(:each, page) unless block_given?
+
+        annots = page.value[:Annots]
+        return self unless annots
+
+        annots.each do |ref|
+          a = ref.is_a?(Pdfrb::Model::Reference) ? document.object(ref) : ref
+          yield a if a
+        end
+        self
+      end
+    end
+  end
+end

data/lib/pdfrb/document/destinations.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  class Document
+    # Named-destinations facade (stub). Full implementation in TODO 129.
+    class Destinations
+      attr_reader :document
+
+      def initialize(document)
+        @document = document
+      end
+
+      def [](name)
+        names = document.catalog.value[:Names]
+        return nil unless names.is_a?(::Hash) || names.is_a?(Pdfrb::Model::Cos::Dictionary)
+
+        dests = names.is_a?(Pdfrb::Model::Cos::Dictionary) ? names.value[:Dests] : names[:Dests]
+        dests ? dests[name] : nil
+      end
+    end
+  end
+end

data/lib/pdfrb/document/files.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  class Document
+    # Attached-files facade (stub). Full implementation lands in TODO 128.
+    class Files
+      attr_reader :document
+
+      def initialize(document)
+        @document = document
+      end
+
+      def add(_io, name:, **_opts)
+        raise NotImplementedError,
+              "File embedding lands in TODO 128 (per App Note 002 — Associated Files)"
+      end
+
+      def each
+        return enum_for(:each) unless block_given?
+
+        names_tree = document.catalog.value.dig(:Names, :EmbeddedFiles)
+        return self unless names_tree
+        # Real implementation walks the name-tree.
+        self
+      end
+    end
+  end
+end

data/lib/pdfrb/document/fonts.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  class Document
+    # Font facade. +add+ registers a font in the catalog /Resources
+    # (so the canvas can reference it via +Tf+) and returns the
+    # resource name to use with the canvas.
+    #
+    # Supports the 14 PDF standard Type1 fonts by name (Helvetica,
+    # Times-Roman, Courier, etc.) without embedding. Future TTF/OTF
+    # loaders (TODO 111/112) plug in via +register_loader+.
+    class Fonts
+      STANDARDS = %w[
+        Helvetica Helvetica-Bold Helvetica-Oblique Helvetica-BoldOblique
+        Times-Roman Times-Bold Times-Italic Times-BoldItalic
+        Courier Courier-Bold Courier-Oblique Courier-BoldOblique
+        Symbol ZapfDingbats
+      ].freeze
+
+      attr_reader :document
+
+      def initialize(document)
+        @document = document
+        @next_id = 1
+        @registry = {} # name -> resource Symbol
+      end
+
+      # Register a font and return the resource name (e.g. :F1).
+      #
+      # For the 14 standard fonts: pass the font name; no embedding
+      # is required. For everything else, use the loader protocol
+      # (TODO 111).
+      def add(name_or_io, **opts)
+        name = font_name_for(name_or_io)
+        cached = @registry[name]
+        return cached if cached
+
+        resource = next_resource_name
+        register_font(resource, name, **opts)
+        @registry[name] = resource
+        resource
+      end
+
+      # Look up the resource name registered for a font name.
+      def [](name)
+        @registry[name]
+      end
+
+      def each(&block)
+        return enum_for(:each) unless block_given?
+
+        @registry.each(&block)
+        self
+      end
+
+      # ---- Extension point (TODOs 110-112) ----
+      #
+      # A loader is an object with `call(document, name_or_io, **opts)`
+      # that returns a Font dict + descriptor pair. Built-in loader
+      # handles the 14 standards; future loaders add TTF/OTF/CID.
+      class << self
+        def loaders
+          @loaders ||= []
+        end
+
+        def register_loader(loader)
+          loaders.unshift(loader)
+        end
+      end
+
+      register_loader ->(doc, name, **opts) {
+        next nil unless STANDARDS.include?(name.to_s)
+        next nil unless opts[:embedded].nil? # standards never embed
+
+        doc.add(
+          { Type: :Font, Subtype: :Type1, BaseFont: name.to_sym },
+          type: Pdfrb::Model::Type::FontType1
+        )
+      }
+
+      private
+
+      def font_name_for(name_or_io)
+        case name_or_io
+        when Symbol, String then name_or_io.to_s
+        else
+          raise ArgumentError,
+                "font name must be a String or Symbol; TTF/OTF IO loading lands in TODO 111"
+        end
+      end
+
+      def next_resource_name
+        sym = :"F#{@next_id}"
+        @next_id += 1
+        sym
+      end
+
+      def register_font(resource, name, **opts)
+        loader = self.class.loaders.find { |l| l.call(document, name, **opts) }
+        font_dict = loader ? loader.call(document, name, **opts) :
+                     default_font(name)
+        attach_to_resources(resource, font_dict)
+      end
+
+      def default_font(name)
+        document.add(
+          { Type: :Font, Subtype: :Type1, BaseFont: name.to_sym },
+          type: Pdfrb::Model::Type::FontType1
+        )
+      end
+
+      def attach_to_resources(resource, font_dict)
+        ref = Pdfrb::Model::Reference.new(font_dict.oid, font_dict.gen)
+        catalog = document.catalog
+        catalog.value[:Resources] ||= {}
+        catalog.value[:Resources][:Font] ||= {}
+        catalog.value[:Resources][:Font][resource] = ref
+      end
+    end
+  end
+end

data/lib/pdfrb/document/images.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "zlib"
+
+module Pdfrb
+  class Document
+    # Image facade. +add+ dispatches to +ImageLoader.load+ which
+    # auto-detects format from the bytes (JPEG, PNG, or PDF page).
+    class Images
+      attr_reader :document, :registry
+
+      def initialize(document)
+        @document = document
+        @registry = {}        # resource name -> image Object
+        @next_id = 1
+      end
+
+      # Build an Image XObject from +io+ (path, IO, or bytes) and
+      # register it in the document's /Resources/XObject. Returns the
+      # resource name (e.g. :Im1).
+      def add(io, **opts)
+        image = Pdfrb::ImageLoader.load(document, io, **opts)
+        name = next_resource_name
+        attach_to_resources(name, image)
+        registry[name] = image
+        name
+      end
+
+      def [](name)
+        registry[name]
+      end
+
+      def each(&block)
+        return enum_for(:each) unless block_given?
+
+        registry.each(&block)
+        self
+      end
+
+      private
+
+      def next_resource_name
+        sym = :"Im#{@next_id}"
+        @next_id += 1
+        sym
+      end
+
+      def attach_to_resources(name, image)
+        ref = Pdfrb::Model::Reference.new(image.oid, image.gen)
+        catalog = document.catalog
+        catalog.value[:Resources] ||= {}
+        catalog.value[:Resources][:XObject] ||= {}
+        catalog.value[:Resources][:XObject][name] = ref
+      end
+    end
+  end
+end

data/lib/pdfrb/document/metadata.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  class Document
+    # Document metadata facade. Reads/writes Title, Author, Subject,
+    # Keywords, Creator, Producer, CreationDate, ModDate via the
+    # trailer's /Info dict (PDF 1.x) and prefers /Catalog/Metadata
+    # XMP for PDF 2.0 per App Note 003.
+    class Metadata
+      STANDARD_FIELDS = %i[Title Author Subject Keywords Creator
+                           Producer CreationDate ModDate Trapped].freeze
+
+      attr_reader :document
+
+      def initialize(document)
+        @document = document
+      end
+
+      STANDARD_FIELDS.each do |field|
+        define_method(field.downcase) { read_field(field) }
+        define_method("#{field.downcase}=") { |v| write_field(field, v) }
+      end
+
+      def [](field)
+        read_field(field)
+      end
+
+      def []=(field, value)
+        write_field(field, value)
+      end
+
+      private
+
+      def read_field(field)
+        info = info_dict
+        return nil unless info
+
+        raw = info.value[field]
+        return nil if raw.nil?
+
+        raw.is_a?(::String) ? raw.dup.force_encoding("UTF-8") : raw
+      end
+
+      def write_field(field, value)
+        info = info_dict(create: true)
+        info.value[field] = value.to_s
+      end
+
+      def info_dict(create: false)
+        return @cached_info if defined?(@cached_info) && @cached_info
+
+        trailer = document.trailer
+        ref = trailer ? trailer[:Info] : nil
+        obj = ref ? document.object(ref) : nil
+
+        if obj.nil? && create
+          obj = document.add({ Type: :Metadata }, type: Pdfrb::Model::Type::Info)
+          document.trailer[:Info] = Pdfrb::Model::Reference.new(obj.oid, obj.gen)
+        end
+        @cached_info = obj
+      end
+    end
+  end
+end