pdfrb 0.3.0 → 0.7.1

data/lib/pdfrb/document/form.rb

@@ -0,0 +1,338 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  class Document
+    # Facade for AcroForm interactive forms (ISO 32000-2 §12.7).
+    #
+    # Creates the /AcroForm dictionary on the Catalog and manages
+    # form fields. Each field is a /Type /Annot /Subtype /Widget
+    # indirect object linked to a page via /P and positioned via /Rect.
+    #
+    # Supported field types (FT):
+    #   :Btn — button (checkbox, radio, pushbutton)
+    #   :Tx  — text input
+    #   :Ch  — choice (list, combo)
+    #   :Sig — digital signature
+    #
+    # Appearance streams are generated by the viewer when /NeedAppearances
+    # is true on the /AcroForm dict.
+    class Form
+      attr_reader :document
+
+      def initialize(document)
+        @document = document
+      end
+
+      # Enable AcroForm by creating the /AcroForm dict on the Catalog.
+      # Idempotent. @return [Hash] the AcroForm dict value.
+      def enable!
+        catalog = document.catalog
+        return catalog.value[:AcroForm] if catalog.value[:AcroForm]
+
+        acroform = {
+          Fields: [],
+          NeedAppearances: true,
+          DA: "/Helv 0 Tf 0 g",
+        }
+        catalog.value[:AcroForm] = acroform
+        acroform
+      end
+
+      # Add a text field. @return [Pdfrb::Model::Cos::Dictionary] the field.
+      def add_text_field(name, page:, rect:, value: nil, multiline: false)
+        enable!
+        flags = 0
+        flags |= 0x1000 if multiline # bit 13 = multiline
+
+        field = build_widget(name, page: page, rect: rect)
+        field.value[:FT] = :Tx
+        field.value[:Ff] = flags if flags.positive?
+        field.value[:V] = value if value
+        register_field(field)
+        field
+      end
+
+      # Add a checkbox field. @return [Pdfrb::Model::Cos::Dictionary] the field.
+      def add_checkbox(name, page:, rect:, checked: false)
+        enable!
+        field = build_widget(name, page: page, rect: rect)
+        field.value[:FT] = :Btn
+        field.value[:V] = checked ? :Yes : :Off
+        register_field(field)
+        field
+      end
+
+      # Add a combo box (dropdown) field.
+      # @return [Pdfrb::Model::Cos::Dictionary] the field.
+      def add_combo(name, page:, rect:, options:, value: nil)
+        enable!
+        field = build_widget(name, page: page, rect: rect)
+        field.value[:FT] = :Ch
+        field.value[:Ff] = 0x20000 # bit 18 = Combo
+        field.value[:Opt] = options
+        field.value[:V] = value if value
+        register_field(field)
+        field
+      end
+
+      # Total field count.
+      def count
+        acroform = document.catalog.value[:AcroForm]
+        return 0 unless acroform
+
+        fields = acroform[:Fields]
+        fields ? fields.length : 0
+      end
+
+      # Find a field by fully qualified name.
+      def find(name)
+        each_field.find { |f| f.value[:T] == name }
+      end
+
+      # Enumerate all top-level fields.
+      def each_field(&block)
+        acroform = document.catalog.value[:AcroForm]
+        return enum_for(:each_field) unless block
+
+        return unless acroform
+
+        fields = acroform[:Fields] || []
+        fields.each do |ref|
+          obj = ref.is_a?(Pdfrb::Model::Reference) ? document.object(ref) : ref
+          yield obj if obj
+        end
+      end
+
+      # List of fully qualified field names (T values).
+      def field_names
+        each_field.filter_map { |f| f.value[:T] }
+      end
+
+      # Set a field value by name. Auto-regenerates the appearance stream
+      # for text/checkbox fields. For unsupported types, sets /V only.
+      # @param name [String] the field's /T value.
+      # @param value [Object] the new /V value.
+      # @return [Pdfrb::Model::Cos::Dictionary, nil] the field if found.
+      def set_value(name, value)
+        field = find(name)
+        return nil unless field
+
+        field.value[:V] = normalize_value(field, value)
+        regenerate_appearance(field)
+        field
+      end
+
+      # Get a field value by name.
+      # @param name [String] the field's /T value.
+      # @return [Object, nil] the /V value, or nil if not found.
+      def get_value(name)
+        field = find(name)
+        return nil unless field
+
+        field.value[:V]
+      end
+
+      # Flatten all form fields: stamp their appearance streams into page
+      # content, then remove the field from /AcroForm /Fields. After
+      # flattening, the form is read-only.
+      def flatten!
+        each_field.to_a.each do |field|
+          stamp_field_appearance(field)
+          remove_field(field)
+        end
+        acroform = document.catalog.value[:AcroForm]
+        delete_acroform_key(acroform, :Fields)
+        delete_acroform_key(acroform, :NeedAppearances)
+        document
+      end
+
+      def delete_acroform_key(acroform, key)
+        return unless acroform
+
+        if acroform.is_a?(Pdfrb::Model::Cos::Dictionary)
+          acroform.value.delete(key)
+        else
+          acroform.delete(key)
+        end
+      end
+
+      # Remove a single field from /AcroForm /Fields and its widget from
+      # the page's /Annots array.
+      def remove_field(field)
+        acroform = document.catalog.value[:AcroForm]
+        return nil unless acroform
+
+        fields = acroform[:Fields]
+        return nil unless fields
+
+        field_ref = Pdfrb::Model::Reference.new(field.oid, field.gen)
+        fields.delete_if { |r| r == field_ref || (r.is_a?(Pdfrb::Model::Reference) && r.oid == field.oid) }
+
+        # Remove widget annotation from page /Annots
+        page_ref = field.value[:P]
+        if page_ref
+          page = page_ref.is_a?(Pdfrb::Model::Reference) ? document.object(page_ref) : page_ref
+          annots = page&.value&.[](:Annots)
+          annots&.delete_if { |r| r == field_ref || (r.is_a?(Pdfrb::Model::Reference) && r.oid == field.oid) }
+        end
+        field
+      end
+
+      private
+
+      def normalize_value(field, value)
+        case field.value[:FT]&.to_sym
+        when :Btn
+          # Buttons accept :Yes/:Off or boolean. Normalize to symbol.
+          if [true, :Yes].include?(value)
+            :Yes
+          else
+            ([false, :Off].include?(value) ? :Off : value)
+          end
+        when :Ch
+          # Choices: validate against /Opt if present.
+          value
+        else
+          # Text and signature: accept strings.
+          value.to_s
+        end
+      end
+
+      def regenerate_appearance(field)
+        ft = field.value[:FT]&.to_sym
+        generator = Pdfrb::Appearance::Generator.new(document)
+        case ft
+        when :Tx
+          generator.text_field(field, value: field.value[:V].to_s)
+        when :Btn
+          checked = field.value[:V] == :Yes
+          generator.checkbox(field, checked: checked)
+        end
+      rescue StandardError
+        # Appearance generation is best-effort; viewer can regenerate.
+      end
+
+      def stamp_field_appearance(field)
+        form_stream = appearance_form_stream(field)
+        return unless form_stream
+
+        page_ref = field.value[:P]
+        return unless page_ref
+
+        page = page_ref.is_a?(Pdfrb::Model::Reference) ? document.object(page_ref) : page_ref
+        return unless page
+
+        name = register_form_on_page(page, form_stream)
+        rect = field.value[:Rect]
+        origin = rect ? [rect[0], rect[1]] : [0, 0]
+        emit_do_on_page(page, name, origin)
+      end
+
+      # Resolve the Form XObject stream that backs the field's current
+      # appearance. Handles single-state (/AP /N -> ref) and multi-state
+      # (/AP /N -> {state -> ref}, picked from /AS).
+      def appearance_form_stream(field)
+        ap = field.value[:AP]
+        return nil unless ap
+
+        n = dictionary_get(ap, :N)
+        return nil unless n
+
+        target = if dictionary?(n)
+                   state = field.value[:AS]
+                   dictionary_get(n, state) ||
+                     dictionary_get(n, :Normal) ||
+                     dictionary_values(n).first
+                 else
+                   n
+                 end
+        return nil unless target
+
+        target.is_a?(Pdfrb::Model::Reference) ? document.object(target) : target
+      end
+
+      def dictionary?(value)
+        value.is_a?(::Hash) || value.is_a?(Pdfrb::Model::Cos::Dictionary)
+      end
+
+      def dictionary_get(dict, key)
+        return nil unless key
+
+        if dict.is_a?(Pdfrb::Model::Cos::Dictionary)
+          dict.value[key]
+        else
+          dict[key]
+        end
+      end
+
+      def dictionary_values(dict)
+        if dict.is_a?(Pdfrb::Model::Cos::Dictionary)
+          dict.value.values
+        else
+          dict.values
+        end
+      end
+
+      def register_form_on_page(page, form_stream)
+        resources = page.value[:Resources]
+        resources = page.value[:Resources] = Pdfrb::Model::Cos::Dictionary.new({}) unless resources.is_a?(Pdfrb::Model::Cos::Dictionary)
+        xobjects = resources.value[:XObject] || {}
+        name = unique_xobject_name(xobjects)
+        xobjects[name] = Pdfrb::Model::Reference.new(form_stream.oid, form_stream.gen)
+        resources.value[:XObject] = xobjects
+        name
+      end
+
+      def unique_xobject_name(existing)
+        counter = (existing.keys.map { |k| k.to_s[/\d+\z/].to_i }.max || 0) + 1
+        :"Fm#{counter}"
+      end
+
+      def emit_do_on_page(page, name, at)
+        canvas = page.canvas
+        canvas.save_graphics_state
+        canvas.translate(at[0], at[1]) if at[0] != 0 || at[1] != 0
+        canvas.emit_op(Pdfrb::Content::Operator::InvokeXObject, name)
+        canvas.restore_graphics_state
+      rescue StandardError
+        # Pages without a content stream or with malformed resources
+        # cannot be stamped; flattening still removes the widget.
+      end
+
+      def build_widget(name, page:, rect:)
+        widget = document.add(
+          {
+            Type: :Annot,
+            Subtype: :Widget,
+            T: name,
+            Rect: rect,
+            P: Pdfrb::Model::Reference.new(page.oid, page.gen),
+            FT: :Tx,
+          },
+          type: Pdfrb::Model::Type::Annotation
+        )
+        add_annot_to_page(page, widget)
+        widget
+      end
+
+      def add_annot_to_page(page, widget)
+        annots = page.value[:Annots]
+        ref = Pdfrb::Model::Reference.new(widget.oid, widget.gen)
+        if annots.nil?
+          page.value[:Annots] = [ref]
+        elsif annots.is_a?(::Array)
+          annots << ref
+        else
+          page.value[:Annots] = [annots, ref]
+        end
+      end
+
+      def register_field(field)
+        acroform = document.catalog.value[:AcroForm]
+        fields = acroform[:Fields]
+        ref = Pdfrb::Model::Reference.new(field.oid, field.gen)
+        fields << ref
+      end
+    end
+  end
+end

data/lib/pdfrb/document/graphics_state.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  class Document
+    # Facade for managing ExtGState (graphics state) entries on pages.
+    # Each page can reference a /ExtGState sub-dict in /Resources that
+    # holds named graphics-state parameter sets (transparency, line
+    # width, overprint, etc.).
+    class GraphicsState
+      attr_reader :document
+
+      def initialize(document)
+        @document = document
+        @next_gs_number = 1
+      end
+
+      # Register an ExtGState parameter dict on a page and return the
+      # resource name (e.g., :GS1).
+      #
+      # @param page [Pdfrb::Model::Type::Page] target page.
+      # @param params [Hash] graphics state parameters (e.g.,
+      #   { CA: 0.5, ca: 0.5 } for 50% stroke + fill alpha).
+      # @return [Symbol] resource name.
+      def register(page, **params)
+        gs = document.add({ Type: :ExtGState, **params },
+                          type: Pdfrb::Model::Type::GraphicsStateParameter)
+        ref = Pdfrb::Model::Reference.new(gs.oid, gs.gen)
+
+        resources = ensure_resources(page)
+        ext_gstate = resources.value[:ExtGState] || {}
+        name = gs_name
+        ext_gstate[name] = ref
+        resources.value[:ExtGState] = ext_gstate
+        name
+      end
+
+      # Convenience: register a transparency state.
+      def register_transparency(page, opacity:, blend_mode: nil)
+        params = { ca: opacity, CA: opacity }
+        params[:BM] = blend_mode if blend_mode
+        register(page, **params)
+      end
+
+      # Convenience: register a line-width state.
+      def register_line_width(page, width:, line_cap: nil, line_join: nil)
+        params = { LW: width }
+        params[:LC] = line_cap if line_cap
+        params[:LJ] = line_join if line_join
+        register(page, **params)
+      end
+
+      # Enumerate ExtGState entries on a page.
+      def each(page, &block)
+        return enum_for(:each, page) unless block
+
+        resources = page_resources(page)
+        return unless resources
+
+        ext = resources.value[:ExtGState]
+        return unless ext
+
+        ext.each(&block)
+      end
+
+      def count(page)
+        each(page).count
+      end
+
+      private
+
+      def ensure_resources(page)
+        resources = page.value[:Resources]
+        return resources if resources.is_a?(Pdfrb::Model::Cos::Dictionary)
+
+        wrapped = Pdfrb::Model::Cos::Dictionary.new(resources || {})
+        page.value[:Resources] = wrapped
+        wrapped
+      end
+
+      def page_resources(page)
+        page.value[:Resources]
+      end
+
+      def gs_name
+        name = :"GS#{@next_gs_number}"
+        @next_gs_number += 1
+        name
+      end
+    end
+  end
+end

data/lib/pdfrb/document/images.rb

@@ -18,8 +18,8 @@ module Pdfrb
       # 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)
+      def add(io, **)
+        image = Pdfrb::ImageLoader.load(document, io, **)
         name = next_resource_name
         attach_to_resources(name, image)
         registry[name] = image
@@ -30,10 +30,10 @@ module Pdfrb
         registry[name]
       end
 
-      def each(&block)
+      def each(&)
         return enum_for(:each) unless block_given?
 
-        registry.each(&block)
+        registry.each(&)
         self
       end
 

data/lib/pdfrb/document/info.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  class Document
+    # Document Info dictionary facade (PDF 1.x metadata on /Info).
+    # Also bridges to XMP packet so both metadata representations stay
+    # in sync. PDF 2.0 deprecates /Info in favor of XMP-only, but
+    # /Info is still required for backward compatibility.
+    class Info
+      attr_reader :document
+
+      def initialize(document)
+        @document = document
+      end
+
+      FIELD_MAP = {
+        title: :Title,
+        author: :Author,
+        subject: :Subject,
+        keywords: :Keywords,
+        creator: :Creator,
+        producer: :Producer,
+      }.freeze
+
+      FIELD_MAP.each do |method_name, pdf_key|
+        define_method(method_name) do
+          info_dict[pdf_key]
+        end
+
+        define_method("#{method_name}=") do |value|
+          set_info_field(pdf_key, value)
+        end
+      end
+
+      def creation_date
+        info_dict[:CreationDate]
+      end
+
+      def creation_date=(value)
+        set_info_field(:CreationDate, pdf_date(value))
+      end
+
+      def mod_date
+        info_dict[:ModDate]
+      end
+
+      def mod_date=(value)
+        set_info_field(:ModDate, pdf_date(value))
+      end
+
+      def trapped
+        info_dict[:Trapped]
+      end
+
+      def trapped=(value)
+        set_info_field(:Trapped, value)
+      end
+
+      # Returns the /Info dictionary object (creating one if needed).
+      def info_dict
+        info_ref = document.trailer && document.trailer[:Info]
+        return document.object(info_ref) if info_ref
+
+        info = document.add({}, type: Pdfrb::Model::Cos::Dictionary)
+        if document.trailer
+          document.trailer[:Info] = Pdfrb::Model::Reference.new(info.oid, info.gen)
+        end
+        info
+      end
+
+      private
+
+      def set_info_field(field, value)
+        return if value.nil?
+
+        dict = info_dict
+        stored = field == :Trapped ? value : value.to_s
+        dict.value[field] = stored
+        sync_xmp(field, value)
+      end
+
+      def sync_xmp(field, value)
+        case field
+        when :Title then document.xmp.title = value
+        when :Author then document.xmp.creator = value
+        when :Subject then document.xmp.description = value
+        when :Keywords then document.xmp.keywords = value
+        when :Creator then document.xmp.creator_tool = value
+        when :Producer then document.xmp.producer = value
+        end
+      end
+
+      def pdf_date(time)
+        return time.to_s if time.is_a?(::String)
+
+        t = time.is_a?(::Time) ? time : Time.now
+        utc = t.utc
+        "D:#{utc.strftime('%Y%m%d%H%M%S')}+00'00'"
+      end
+    end
+  end
+end

data/lib/pdfrb/document/layers.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  class Document
+    # Facade for Optional Content Groups (layers). OCGs let authors
+    # mark content as belonging to a named layer that can be toggled
+    # on/off by the viewer (ISO 32000-2 §8.11).
+    #
+    # Each layer is a /Type /OCG dictionary with a /Name. The
+    # Catalog gets an /OCProperties entry:
+    #   /OCGs — array of all OCG indirect refs.
+    #   /D — default viewing config:
+    #     /BaseState /ON, /OFF [list of off-by-default OCGs], etc.
+    class Layers
+      attr_reader :document, :groups
+
+      def initialize(document)
+        @document = document
+        @groups = []
+      end
+
+      # Add a named layer. @return [Pdfrb::Model::Cos::Dictionary] the OCG.
+      def add(name, default_on: true)
+        ensure_oc_properties
+        ocg = document.add(
+          { Type: :OCG, Name: name },
+          type: Pdfrb::Model::Cos::Dictionary
+        )
+        ref = Pdfrb::Model::Reference.new(ocg.oid, ocg.gen)
+        @groups << { ref: ref, ocg: ocg, default_on: default_on }
+        ocg
+      end
+
+      # Write /OCProperties to the Catalog. Called automatically by #add
+      # but can be called again to refresh after external modifications.
+      def sync!
+        return if @groups.empty?
+
+        ocgs_array = @groups.map { |g| g[:ref] }
+        off_array = @groups.reject { |g| g[:default_on] }.map { |g| g[:ref] }
+
+        default_config = { BaseState: :ON }
+        default_config[:OFF] = off_array unless off_array.empty?
+
+        catalog = document.catalog
+        catalog.value[:OCProperties] = {
+          OCGs: ocgs_array,
+          D: default_config,
+        }
+      end
+
+      private
+
+      def ensure_oc_properties
+        catalog = document.catalog
+        return if catalog.value[:OCProperties]
+
+        catalog.value[:OCProperties] = { OCGs: [], D: { BaseState: :ON } }
+      end
+    end
+  end
+end

data/lib/pdfrb/document/metadata.rb

@@ -2,10 +2,6 @@
 
 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
@@ -29,6 +25,17 @@ module Pdfrb
         write_field(field, value)
       end
 
+      def to_xmp
+        begin
+          packet = Pdfrb::XMP::Packet.new
+        rescue StandardError
+          return ""
+        end
+        title = read_field(:Title)
+        packet.title = title if title
+        packet.to_xmp
+      end
+
       private
 
       def read_field(field)
@@ -54,7 +61,7 @@ module Pdfrb
         obj = ref ? document.object(ref) : nil
 
         if obj.nil? && create
-          obj = document.add({ Type: :Metadata }, type: Pdfrb::Model::Type::Info)
+          obj = document.add({}, type: Pdfrb::Model::Type::Info)
           document.trailer[:Info] = Pdfrb::Model::Reference.new(obj.oid, obj.gen)
         end
         @cached_info = obj