pdfrb 0.2.1 → 0.6.0

data/lib/pdfrb/annotation/base.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Annotation
+    # Base annotation builder. Subclasses override +subtype+ and
+    # +default_fields+ to provide type-specific defaults. Each subclass
+    # calls +register_as+ at load time.
+    class Base
+      class << self
+        # @return [Symbol] the /Subtype value (e.g. :Link).
+        def subtype
+          raise NotImplementedError, "#{self} must define subtype"
+        end
+
+        # Extra fields to merge into the annotation dict.
+        # @return [Hash]
+        def default_fields
+          {}
+        end
+
+        # Create the annotation and attach it to the page's /Annots.
+        def create(document:, page:, rect:, **opts)
+          dict = base_dict(page: page, rect: rect, **opts).merge!(default_fields).merge!(type_overrides(opts))
+          annot = document.add(dict, type: Pdfrb::Model::Type::Annotation)
+          attach_to_page(page, annot)
+          annot
+        end
+
+        # Register this class in the Annotation registry.
+        def register_as(symbol = subtype)
+          Annotation.register(symbol, self)
+          self
+        end
+
+        private
+
+        def base_dict(page:, rect:, contents: nil, flags: 0, **)
+          {
+            Type: :Annot,
+            Subtype: subtype,
+            Rect: rect,
+            P: Pdfrb::Model::Reference.new(page.oid, page.gen),
+            Contents: contents,
+            F: flags,
+          }.compact
+        end
+
+        def type_overrides(opts)
+          overrides = {}
+          overrides[:C] = opts[:color] if opts.key?(:color)
+          overrides[:Border] = opts[:border] if opts.key?(:border)
+          overrides[:A] = opts[:action] if opts.key?(:action)
+          overrides[:Dest] = opts[:dest] if opts.key?(:dest)
+          overrides[:H] = opts[:highlight] if opts.key?(:highlight)
+          overrides[:BS] = opts[:border_style] if opts.key?(:border_style)
+          overrides[:QuadPoints] = opts[:quad_points] if opts.key?(:quad_points)
+          overrides[:T] = opts[:title] if opts.key?(:title)
+          overrides[:RC] = opts[:rich_contents] if opts.key?(:rich_contents)
+          overrides[:CreationDate] = opts[:created_at] if opts.key?(:created_at)
+          overrides[:M] = opts[:modified_at] if opts.key?(:modified_at)
+          overrides[:NM] = opts[:name] if opts.key?(:name)
+          overrides.compact
+        end
+
+        def attach_to_page(page, annot)
+          annots = page.value[:Annots]
+          ref = Pdfrb::Model::Reference.new(annot.oid, annot.gen)
+          if annots.nil?
+            page.value[:Annots] = [ref]
+          elsif annots.is_a?(::Array)
+            annots << ref
+          else
+            page.value[:Annots] = [annots, ref]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/annotation/types.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Annotation
+    # Concrete annotation types (ISO 32000-2 §12.5.6). Each class
+    # defines its /Subtype and type-specific defaults, then registers
+    # itself via +register_as+.
+    #
+    # OCP: new annotation type = new class + register_as. No edits
+    # to existing code.
+
+    # Text annotation (sticky note). §12.5.6.4
+    class Text < Base
+      class << self
+        def subtype; :Text; end
+
+        def default_fields
+          { Name: :Comment }
+        end
+      end
+      register_as
+    end
+
+    # Link annotation (hyperlink). §12.5.6.5
+    class Link < Base
+      class << self
+        def subtype; :Link; end
+
+        def default_fields
+          { H: :I } # Invert highlight by default
+        end
+      end
+      register_as
+    end
+
+    # FreeText annotation (free-form text box). §12.5.6.6
+    class FreeText < Base
+      class << self
+        def subtype; :FreeText; end
+
+        def default_fields
+          { DA: "/Helv 0 Tf 0 g" }
+        end
+      end
+      register_as
+    end
+
+    # Stamp annotation (rubber stamp). §12.5.6.8
+    class Stamp < Base
+      class << self
+        def subtype; :Stamp; end
+
+        def default_fields
+          { Name: :Draft }
+        end
+      end
+      register_as
+    end
+
+    # Popup annotation. §12.5.6.13. Usually paired with a markup annot
+    # via the markup's /Popup key.
+    class Popup < Base
+      class << self
+        def subtype; :Popup; end
+
+        def default_fields
+          { Open: false }
+        end
+      end
+      register_as
+    end
+
+    # FileAttachment annotation (embedded file). §12.5.6.15
+    # Inspired by mn2pdf's FileAttachmentAnnotation.
+    class FileAttachment < Base
+      class << self
+        def subtype; :FileAttachment; end
+
+        def default_fields
+          { Name: :PushPin }
+        end
+      end
+      register_as
+    end
+
+    # Highlight (text markup). §12.5.6.10
+    class Highlight < Base
+      class << self
+        def subtype; :Highlight; end
+      end
+      register_as
+    end
+
+    # Underline (text markup). §12.5.6.10
+    class Underline < Base
+      class << self
+        def subtype; :Underline; end
+      end
+      register_as
+    end
+
+    # Squiggly (text markup). §12.5.6.10
+    class Squiggly < Base
+      class << self
+        def subtype; :Squiggly; end
+      end
+      register_as
+    end
+
+    # StrikeOut (text markup). §12.5.6.10
+    class StrikeOut < Base
+      class << self
+        def subtype; :StrikeOut; end
+      end
+      register_as
+    end
+
+    # Square (shape markup). §12.5.6.8
+    class Square < Base
+      class << self
+        def subtype; :Square; end
+      end
+      register_as
+    end
+
+    # Circle (shape markup). §12.5.6.8
+    class Circle < Base
+      class << self
+        def subtype; :Circle; end
+      end
+      register_as
+    end
+
+    # Line annotation. §12.5.6.7
+    class Line < Base
+      class << self
+        def subtype; :Line; end
+      end
+      register_as
+    end
+
+    # Polygon annotation. §12.5.6.9
+    class Polygon < Base
+      class << self
+        def subtype; :Polygon; end
+      end
+      register_as
+    end
+
+    # Polyline annotation. §12.5.6.9
+    class Polyline < Base
+      class << self
+        def subtype; :Polyline; end
+      end
+      register_as
+    end
+
+    # Ink annotation (freehand). §12.5.6.13
+    class Ink < Base
+      class << self
+        def subtype; :Ink; end
+      end
+      register_as
+    end
+
+    # Widget annotation (form field). §12.5.6.19
+    class Widget < Base
+      class << self
+        def subtype; :Widget; end
+      end
+      register_as
+    end
+
+    # Caret annotation. §12.5.6.11
+    class Caret < Base
+      class << self
+        def subtype; :Caret; end
+      end
+      register_as
+    end
+
+    # Redact annotation. §12.5.6.16
+    class Redact < Base
+      class << self
+        def subtype; :Redact; end
+      end
+      register_as
+    end
+
+    # Watermark annotation. §12.5.6.23 (PDF 2.0)
+    class Watermark < Base
+      class << self
+        def subtype; :Watermark; end
+      end
+      register_as
+    end
+
+    # PrinterMark annotation. §12.5.6.17
+    class PrinterMark < Base
+      class << self
+        def subtype; :PrinterMark; end
+      end
+      register_as
+    end
+
+    # Screen annotation. §12.5.6.18
+    class Screen < Base
+      class << self
+        def subtype; :Screen; end
+      end
+      register_as
+    end
+
+    # Sound annotation. §12.5.6.18
+    class Sound < Base
+      class << self
+        def subtype; :Sound; end
+      end
+      register_as
+    end
+  end
+end

data/lib/pdfrb/annotation.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  # Annotation types (ISO 32000-2 §12.5). Each subtype is a thin builder
+  # that produces a correctly-shaped annotation dictionary and registers
+  # itself in the +Annotation::REGISTRY+ for open/closed extensibility.
+  module Annotation
+    autoload :Base, "pdfrb/annotation/base"
+    autoload :Types, "pdfrb/annotation/types"
+    # Each annotation builder class lives in types.rb. Autoload from
+    # that file so direct class references work.
+    autoload :Text, "pdfrb/annotation/types"
+    autoload :Link, "pdfrb/annotation/types"
+    autoload :FreeText, "pdfrb/annotation/types"
+    autoload :Stamp, "pdfrb/annotation/types"
+    autoload :Popup, "pdfrb/annotation/types"
+    autoload :FileAttachment, "pdfrb/annotation/types"
+    autoload :Highlight, "pdfrb/annotation/types"
+    autoload :Underline, "pdfrb/annotation/types"
+    autoload :Squiggly, "pdfrb/annotation/types"
+    autoload :StrikeOut, "pdfrb/annotation/types"
+    autoload :Square, "pdfrb/annotation/types"
+    autoload :Circle, "pdfrb/annotation/types"
+    autoload :Line, "pdfrb/annotation/types"
+    autoload :Polygon, "pdfrb/annotation/types"
+    autoload :Polyline, "pdfrb/annotation/types"
+    autoload :Ink, "pdfrb/annotation/types"
+    autoload :Widget, "pdfrb/annotation/types"
+    autoload :Caret, "pdfrb/annotation/types"
+    autoload :Redact, "pdfrb/annotation/types"
+    autoload :Watermark, "pdfrb/annotation/types"
+    autoload :PrinterMark, "pdfrb/annotation/types"
+    autoload :Screen, "pdfrb/annotation/types"
+    autoload :Sound, "pdfrb/annotation/types"
+
+    class << self
+      def create(subtype, document:, page:, **opts)
+        ensure_loaded
+        klass = registry[subtype]
+        return build_fallback(subtype, document, page, opts) unless klass
+
+        klass.create(document: document, page: page, **opts)
+      end
+
+      def registry
+        @registry ||= {}
+      end
+
+      def register(subtype, klass)
+        registry[subtype] = klass
+      end
+
+      def [](subtype)
+        ensure_loaded
+        registry[subtype]
+      end
+
+      def subtypes
+        ensure_loaded
+        registry.keys
+      end
+
+      private
+
+      def ensure_loaded
+        return if @loaded
+
+        # Trigger the types.rb load which registers all subtypes.
+        Pdfrb::Annotation::Text
+        @loaded = true
+      end
+
+      def build_fallback(subtype, document, page, opts)
+        Base.create(subtype, document: document, page: page, **opts)
+      end
+    end
+  end
+end

data/lib/pdfrb/appearance/generator.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module Pdfrb
+  module Appearance
+    # Generates /AP /N appearance streams for form fields and annotations.
+    # Each method creates a Form XObject with the field's visual
+    # representation and sets it as the /AP /N entry on the field.
+    #
+    # For PDF/A-4, /NeedAppearances must be false (or absent), so every
+    # field needs a pre-computed appearance stream.
+    class Generator
+      DEFAULT_BORDER_WIDTH = 1.0
+      DEFAULT_FONT_SIZE = 12
+      DEFAULT_PADDING = 3
+
+      attr_reader :document
+
+      def initialize(document)
+        @document = document
+      end
+
+      # Generate appearance for a text field.
+      # @param field [Pdfrb::Model::Type::Annotation] the Widget/field.
+      # @param value [String] the text value to display.
+      # @param font_name [Symbol] resource name of the font.
+      # @param font_size [Integer] point size.
+      def text_field(field, value:, font_name: :Helv, font_size: DEFAULT_FONT_SIZE)
+        rect = field.value[:Rect]
+        return unless rect
+
+        form = build_form_xobject(rect) do |canvas|
+          draw_border(canvas, rect)
+          if value && !value.to_s.empty?
+            canvas.text(value.to_s,
+                        at: [DEFAULT_PADDING, DEFAULT_PADDING],
+                        font: font_name, size: font_size)
+          end
+        end
+
+        set_appearance(field, form)
+      end
+
+      # Generate appearance for a checkbox.
+      # @param field [Pdfrb::Model::Type::Annotation] the Widget/field.
+      # @param checked [Boolean] whether the box is checked.
+      def checkbox(field, checked:)
+        rect = field.value[:Rect]
+        return unless rect
+
+        form = build_form_xobject(rect) do |canvas|
+          draw_border(canvas, rect)
+          if checked
+            draw_check(canvas, rect)
+          end
+        end
+
+        state_name = checked ? :Yes : :Off
+        set_appearance(field, form, state_name)
+        field.value[:AS] = state_name
+      end
+
+      # Generate appearance for a combo box (dropdown).
+      # @param field [Pdfrb::Model::Type::Annotation] the Widget/field.
+      # @param value [String] the selected value.
+      # @param font_name [Symbol] resource name of the font.
+      # @param font_size [Integer] point size.
+      def combo(field, value:, font_name: :Helv, font_size: DEFAULT_FONT_SIZE)
+        text_field(field, value: value, font_name: font_name, font_size: font_size)
+      end
+
+      # Generate appearance for a push button.
+      # @param field [Pdfrb::Model::Type::Annotation] the Widget/field.
+      # @param label [String] the button label.
+      # @param font_name [Symbol] resource name of the font.
+      def button(field, label:, font_name: :Helv)
+        rect = field.value[:Rect]
+        return unless rect
+
+        form = build_form_xobject(rect) do |canvas|
+          draw_border(canvas, rect)
+          if label
+            w = rect[2] - rect[0]
+            h = rect[3] - rect[1]
+            canvas.text(label,
+                        at: [w / 3, h / 3],
+                        font: font_name, size: DEFAULT_FONT_SIZE)
+          end
+        end
+
+        set_appearance(field, form)
+      end
+
+      # Generate appearance for a radio button.
+      # @param field [Pdfrb::Model::Type::Annotation] the Widget/field.
+      # @param selected [String] the selected state name (e.g. :Yes).
+      # @param options [Array<String>] all possible state names.
+      def radio_button(field, selected:, options: [:Yes])
+        rect = field.value[:Rect]
+        return unless rect
+
+        options.each do |state|
+          form = build_form_xobject(rect) do |canvas|
+            draw_border(canvas, rect)
+            draw_radio_circle(canvas, rect, selected: state == selected)
+          end
+          set_appearance(field, form, state_name: state.to_sym)
+        end
+        field.value[:AS] = selected.to_sym
+      end
+
+      # Generate appearance for a list box field.
+      # @param field [Pdfrb::Model::Type::Annotation] the Widget/field.
+      # @param items [Array<String>] the list items to show.
+      # @param selected [Integer, nil] index of the selected item.
+      # @param font_name [Symbol] resource name of the font.
+      # @param font_size [Integer] point size.
+      def list_box(field, items:, selected: nil, font_name: :Helv,
+                   font_size: DEFAULT_FONT_SIZE)
+        rect = field.value[:Rect]
+        return unless rect
+
+        form = build_form_xobject(rect) do |canvas|
+          draw_border(canvas, rect)
+          items.each_with_index do |item, i|
+            y_pos = (rect[3] - rect[1]) - DEFAULT_PADDING - ((i + 1) * font_size)
+            break if y_pos.negative?
+
+            if i == selected
+              w = rect[2] - rect[0]
+              canvas.fill_color([0.8, 0.8, 1.0])
+              canvas.rectangle(0, y_pos - 2, w, font_size + 4)
+              canvas.fill
+              canvas.fill_color([0, 0, 0])
+            end
+            canvas.text(item.to_s, at: [DEFAULT_PADDING, y_pos],
+                                   font: font_name, size: font_size)
+          end
+        end
+        set_appearance(field, form)
+      end
+
+      private
+
+      def build_form_xobject(rect)
+        x0, y0, x1, y1 = rect
+        form = document.create_form_xobject(
+          name: "AP",
+          bbox: [0, 0, x1 - x0, y1 - y0]
+        )
+        canvas = form.canvas
+        yield canvas
+        form.finalize!
+        form
+      end
+
+      def draw_border(canvas, rect)
+        w = rect[2] - rect[0]
+        h = rect[3] - rect[1]
+        canvas.line_width = 0.5
+        canvas.rectangle(0, 0, w, h)
+        canvas.stroke
+      end
+
+      def draw_radio_circle(canvas, rect, selected:)
+        w = rect[2] - rect[0]
+        h = rect[3] - rect[1]
+        r = ([w, h].min / 2) - 1
+        cx = w / 2
+        cy = h / 2
+        canvas.line_width = 1.0
+
+        # Approximate a circle with a rectangle for now (Canvas lacks arc).
+        canvas.rectangle(cx - r, cy - r, r * 2, r * 2)
+        canvas.stroke
+
+        if selected
+          canvas.line_width = 2.0
+          inner_r = r * 0.4
+          canvas.rectangle(cx - inner_r, cy - inner_r, inner_r * 2, inner_r * 2)
+          canvas.fill
+        end
+      end
+
+      def draw_check(canvas, rect)
+        w = rect[2] - rect[0]
+        h = rect[3] - rect[1]
+        m = [w * 0.2, h * 0.2].min
+        canvas.line_width = 1.5
+        canvas.line(m, m, w - m, h - m)
+        canvas.line(m, h - m, w - m, m)
+        canvas.stroke
+      end
+
+      def set_appearance(field, form, state_name = :Normal)
+        form_stream = form.stream
+        ref = Pdfrb::Model::Reference.new(form_stream.oid, form_stream.gen)
+
+        ap = field.value[:AP]
+        if ap.nil?
+          ap = {}
+          field.value[:AP] = ap
+        end
+
+        if state_name == :Normal
+          ap[:N] = ref
+        else
+          n_dict = ap[:N].is_a?(::Hash) ? ap[:N] : {}
+          n_dict[state_name] = ref
+          ap[:N] = n_dict
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/appearance.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  # Appearance stream generation (ISO 32000-2 §12.5.5). Generates
+  # /AP /N (normal appearance) streams for form fields and annotations
+  # using the Canvas API. Required for PDF/A-4 compliance (which
+  # prohibits /NeedAppearances).
+  module Appearance
+    autoload :Generator, "pdfrb/appearance/generator"
+  end
+end

data/lib/pdfrb/arlington/object_definition.rb

@@ -20,8 +20,8 @@ module Pdfrb
         new(name: name, version: version, fields: fields)
       end
 
-      def each_field(&block)
-        @fields.each(&block)
+      def each_field(&)
+        @fields.each(&)
       end
 
       def field_for(key)

data/lib/pdfrb/arlington/predicate/evaluator.rb

@@ -68,7 +68,7 @@ module Pdfrb
         def walk(start, segments)
           cur = start
           segments.each do |seg|
-            return nil unless cur.respond_to?(:[])
+            return nil unless cur.is_a?(Hash)
             next if seg.nil?
 
             cur = cur[seg.to_sym]

data/lib/pdfrb/arlington/predicate/functions.rb

@@ -9,8 +9,18 @@ module Pdfrb
       module Functions
         @registry = {}
 
+        autoload :VersionPredicates, "pdfrb/arlington/predicate/functions/version"
+        autoload :PresencePredicates, "pdfrb/arlington/predicate/functions/presence"
+        autoload :LogicalPredicates, "pdfrb/arlington/predicate/functions/logical"
+        autoload :ArithmeticPredicates, "pdfrb/arlington/predicate/functions/arithmetic"
+        autoload :ReferencePredicates, "pdfrb/arlington/predicate/functions/reference"
+        autoload :FilePredicates, "pdfrb/arlington/predicate/functions/file"
+
         class << self
-          attr_reader :registry
+          def registry
+            eager_load! unless @eager_loaded
+            @registry
+          end
 
           def register(name, &block)
             @registry[name.to_s] = block
@@ -19,16 +29,22 @@ module Pdfrb
           def clear!
             @registry.clear
           end
+
+          # Force-load all function groups so register calls fire.
+          # Idempotent.
+          def eager_load!
+            return if @eager_loaded
+
+            constants.each do |c|
+              const_get(c)
+            rescue NameError, LoadError
+              # Skip autoload targets that don't define a class
+              # or whose file doesn't exist yet.
+            end
+            @eager_loaded = true
+          end
         end
       end
     end
   end
 end
-
-# Load built-in function groups. Each calls Functions.register on load.
-require "pdfrb/arlington/predicate/functions/version"
-require "pdfrb/arlington/predicate/functions/presence"
-require "pdfrb/arlington/predicate/functions/logical"
-require "pdfrb/arlington/predicate/functions/arithmetic"
-require "pdfrb/arlington/predicate/functions/reference"
-require "pdfrb/arlington/predicate/functions/file"

data/lib/pdfrb/arlington/predicate.rb

@@ -12,11 +12,7 @@ module Pdfrb
       autoload :AST, "pdfrb/arlington/predicate/ast"
       autoload :Evaluator, "pdfrb/arlington/predicate/evaluator"
       autoload :Context, "pdfrb/arlington/predicate/context"
+      autoload :Functions, "pdfrb/arlington/predicate/functions"
     end
   end
 end
-
-# Eager-load the function registry so predicates are registered as
-# soon as the Predicate namespace is touched. (Functions.register is
-# called at the bottom of each functions/*.rb.)
-require "pdfrb/arlington/predicate/functions"