pdfrb 0.3.0 → 0.6.0

data/lib/pdfrb/document/annotations.rb

@@ -2,7 +2,7 @@
 
 module Pdfrb
   class Document
-    # Annotations facade (stub). Full implementation in TODO 131.
+    # Annotations facade. Adds and enumerates annotations on pages.
     class Annotations
       attr_reader :document
 
@@ -27,8 +27,88 @@ module Pdfrb
         annot
       end
 
-      def each(page)
-        return enum_for(:each, page) unless block_given?
+      # Sticky-note / comment text annotation.
+      def add_text_note(page, rect:, contents:, open: false)
+        annot = add(page, subtype: :Text, rect: rect, contents: contents)
+        annot.value[:Open] = open unless open == false
+        annot
+      end
+
+      # Hyperlink annotation pointing at a destination.
+      def add_link(page, rect:, dest: nil, uri: nil, highlight: :Invert)
+        annot = add(page, subtype: :Link, rect: rect)
+        annot.value[:H] = highlight
+        if dest
+          annot.value[:Dest] = dest
+        elsif uri
+          action = document.add(
+            { Type: :Action, S: :URI, URI: uri },
+            type: Pdfrb::Model::Type::Action
+          )
+          annot.value[:A] = Pdfrb::Model::Reference.new(action.oid, action.gen)
+        end
+        annot
+      end
+
+      # Free-text annotation showing inline text on the page.
+      def add_free_text(page, rect:, contents:, font: nil, font_size: nil, color: nil)
+        annot = document.add(
+          {
+            Type: :Annot, Subtype: :FreeText, Rect: rect,
+            P: Pdfrb::Model::Reference.new(page.oid, page.gen),
+            Contents: contents
+          },
+          type: Pdfrb::Model::Type::FreeTextAnnotation
+        )
+        da_parts = []
+        da_parts << "/#{font} #{font_size} Tf" if font && font_size
+        da_parts << "#{color.join(' ')} rg" if color
+        annot.value[:DA] = da_parts.join(" ") unless da_parts.empty?
+        annots = (page.value[:Annots] ||= [])
+        annots << Pdfrb::Model::Reference.new(annot.oid, annot.gen)
+        annot
+      end
+
+      # Highlight text-markup annotation over the given quad points.
+      def add_highlight(page, quad_points:, contents: nil)
+        annot = document.add(
+          {
+            Type: :Annot, Subtype: :Highlight,
+            QuadPoints: quad_points,
+            P: Pdfrb::Model::Reference.new(page.oid, page.gen),
+            Contents: contents
+          }.compact,
+          type: Pdfrb::Model::Type::HighlightAnnotation
+        )
+        annots = (page.value[:Annots] ||= [])
+        annots << Pdfrb::Model::Reference.new(annot.oid, annot.gen)
+        annot
+      end
+
+      # Stamp annotation (e.g. DRAFT, APPROVED, CONFIDENTIAL).
+      def add_stamp(page, rect:, name: :Draft, contents: nil)
+        annot = document.add(
+          {
+            Type: :Annot, Subtype: :Stamp, Rect: rect, Name: name,
+            P: Pdfrb::Model::Reference.new(page.oid, page.gen),
+            Contents: contents
+          }.compact,
+          type: Pdfrb::Model::Type::StampAnnotation
+        )
+        annots = (page.value[:Annots] ||= [])
+        annots << Pdfrb::Model::Reference.new(annot.oid, annot.gen)
+        annot
+      end
+
+      def count(page)
+        annots = page.value[:Annots]
+        return 0 unless annots
+
+        annots.is_a?(::Array) ? annots.length : 1
+      end
+
+      def each(page, &block)
+        return enum_for(:each, page) unless block
 
         annots = page.value[:Annots]
         return self unless annots
@@ -39,6 +119,43 @@ module Pdfrb
         end
         self
       end
+
+      # Iterate annotations of a specific subtype across the whole doc.
+      def each_of_subtype(subtype, &block)
+        return enum_for(:each_of_subtype, subtype) unless block
+
+        document.pages.each do |page|
+          each(page) do |annot|
+            next unless annot[:Subtype]&.to_sym == subtype
+
+            yield annot
+          end
+        end
+        self
+      end
+
+      # Iterate every link annotation in the document.
+      def each_link(&block)
+        return enum_for(:each_link) unless block
+
+        each_of_subtype(:Link, &block)
+      end
+
+      # Iterate every widget (form) annotation in the document.
+      def each_widget(&block)
+        return enum_for(:each_widget) unless block
+
+        each_of_subtype(:Widget, &block)
+      end
+
+      # Iterate every text-markup annotation in the document.
+      def each_text_markup(&block)
+        return enum_for(:each_text_markup) unless block
+
+        %i[Highlight Underline Squiggly StrikeOut].each do |sub|
+          each_of_subtype(sub, &block)
+        end
+      end
     end
   end
 end

data/lib/pdfrb/document/associated_files.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  class Document
+    # Associated Files (AF) facade. PDF 2.0 introduced /AF arrays on
+    # Catalog, Page, and StructElem to declare the relationship between
+    # embedded files and the context they appear in.
+    #
+    # Relationship types (ISO 32000-2 §7.11.3):
+    #   :Source       — source document for the content
+    #   :Data         — data file referenced by the content
+    #   :Alternative  — alternative representation
+    #   :Supplement   — supplemental information
+    #   :Unspecified  — relationship not specified
+    #
+    # App Note 002: https://github.com/pdf-association/appnote-pdf20-002-af
+    class AssociatedFiles
+      RELATIONSHIP_TYPES = %i[
+        Source Data Alternative Supplement Unspecified
+        Encrypted Payload FormData Schema Template
+      ].freeze
+
+      attr_reader :document
+
+      def initialize(document)
+        @document = document
+      end
+
+      # Associate a filespec with the Catalog-level /AF array.
+      # @param filespec_ref [Pdfrb::Model::Reference] the /Filespec ref.
+      # @param relationship [Symbol] one of RELATIONSHIP_TYPES.
+      def add_to_catalog(filespec_ref, relationship: :Unspecified)
+        ensure_relationship(filespec_ref, relationship)
+        append_to_af_array(document.catalog, filespec_ref)
+      end
+
+      # Associate a filespec with a specific page's /AF array.
+      def add_to_page(page, filespec_ref, relationship: :Unspecified)
+        ensure_relationship(filespec_ref, relationship)
+        append_to_af_array(page, filespec_ref)
+      end
+
+      # Associate a filespec with a structure element's /AF array.
+      def add_to_element(struct_elem, filespec_ref, relationship: :Unspecified)
+        ensure_relationship(filespec_ref, relationship)
+        append_to_af_array(struct_elem, filespec_ref)
+      end
+
+      # Convenience: create a filespec + embedded file from raw bytes,
+      # then associate it at the catalog level.
+      # @return [Pdfrb::Model::Reference] the filespec reference.
+      def embed(filename:, data:, relationship: :Unspecified,
+                description: nil, mime_type: nil)
+        filespec = document.files.add(data, name: filename,
+                                            description: description,
+                                            mime_type: mime_type)
+        ref = Pdfrb::Model::Reference.new(filespec.oid, filespec.gen)
+        filespec.value[:AFRelationship] = relationship
+        add_to_catalog(ref, relationship: relationship)
+        ref
+      end
+
+      # List all catalog-level AF filespecs.
+      def catalog_files
+        read_af_array(document.catalog)
+      end
+
+      private
+
+      def ensure_relationship(filespec_ref, relationship)
+        unless RELATIONSHIP_TYPES.include?(relationship)
+          raise ArgumentError, "invalid AF relationship: #{relationship}"
+        end
+
+        filespec = document.object(filespec_ref)
+        return unless filespec.is_a?(Pdfrb::Model::Cos::Dictionary)
+
+        filespec.value[:AFRelationship] = relationship
+      end
+
+      def append_to_af_array(dict_obj, ref)
+        af = dict_obj.value[:AF]
+        if af.nil?
+          dict_obj.value[:AF] = [ref]
+        elsif af.is_a?(::Array)
+          af << ref
+        else
+          dict_obj.value[:AF] = [af, ref]
+        end
+      end
+
+      def read_af_array(dict_obj)
+        af = dict_obj.value[:AF]
+        return [] unless af
+
+        refs = af.is_a?(::Array) ? af : [af]
+        refs.filter_map do |ref|
+          obj = ref.is_a?(Pdfrb::Model::Reference) ? document.object(ref) : ref
+          obj if obj.is_a?(Pdfrb::Model::Cos::Dictionary)
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/document/colors.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  class Document
+    # Facade for color space management. Embeds ICC profiles, registers
+    # named color spaces in page Resources, and provides lookup.
+    class Colors
+      attr_reader :document
+
+      def initialize(document)
+        @document = document
+        @next_cs_number = 1
+      end
+
+      # Embed an ICC profile as a stream and return the color space
+      # array [/ICCBased <ref>] for use in Resources.
+      #
+      # @param icc_bytes [String] raw ICC profile bytes.
+      # @param alternate [Symbol, nil] fallback color space
+      #   (:DeviceRGB, :DeviceCMYK, :DeviceGray, :Lab). Derived from
+      #   the profile header if nil.
+      # @return [Pdfrb::Model::PdfArray] the [/ICCBased <ref>] array.
+      def embed_icc_profile(icc_bytes, alternate: nil)
+        profile = Pdfrb::Color::ICCProfile.new(icc_bytes, alternate: alternate)
+        stream = document.add(
+          { **profile.stream_dictionary_fields,
+            Length: profile.raw_data.bytesize },
+          type: Pdfrb::Model::Cos::Stream
+        )
+        stream.stream = profile.raw_data
+        Pdfrb::Model::PdfArray.new([
+                                     :ICCBased,
+                                     Pdfrb::Model::Reference.new(stream.oid, stream.gen),
+                                   ])
+      end
+
+      # Register a color space in a page's Resources /ColorSpace dict
+      # and return the name (e.g. :CS1) for use in content streams.
+      #
+      # @param page [Pdfrb::Model::Cos::Dictionary] the target page.
+      # @param color_space the color space value (name, array, or ref).
+      # @return [Symbol] the registered name.
+      def register(page, color_space)
+        resources = ensure_resources(page)
+        cs_dict = resources.value[:ColorSpace]
+        cs_dict = ensure_color_space_dict(resources, cs_dict)
+
+        name = cs_name
+        cs_dict[name] = color_space
+        name
+      end
+
+      private
+
+      def ensure_resources(page)
+        resources = page.value[:Resources]
+        return resources if resources.is_a?(Pdfrb::Model::Cos::Dictionary)
+
+        resources_hash = if resources.is_a?(Pdfrb::Model::Reference)
+                           document.object(resources)&.value
+                         else
+                           resources
+                         end
+        if resources_hash.nil?
+          resources_hash = {}
+          page.value[:Resources] = resources_hash
+        end
+        wrap_resources(page, resources_hash)
+      end
+
+      def wrap_resources(page, hash)
+        existing = page.value[:Resources]
+        return existing if existing.is_a?(Pdfrb::Model::Cos::Dictionary)
+
+        wrapped = Pdfrb::Model::Cos::Dictionary.new(hash)
+        page.value[:Resources] = wrapped
+        wrapped
+      end
+
+      def ensure_color_space_dict(resources, cs_dict)
+        return cs_dict if cs_dict.is_a?(::Hash) || cs_dict.is_a?(Pdfrb::Model::Cos::Dictionary)
+
+        cs_hash = {}
+        resources.value[:ColorSpace] = cs_hash
+        cs_hash
+      end
+
+      def cs_name
+        name = :"CS#{@next_cs_number}"
+        @next_cs_number += 1
+        name
+      end
+    end
+  end
+end

data/lib/pdfrb/document/destinations.rb

@@ -2,7 +2,8 @@
 
 module Pdfrb
   class Document
-    # Named-destinations facade (stub). Full implementation in TODO 129.
+    # Named-destinations facade. Manages both name-tree destinations
+    # (Catalog /Names /Dests) and the explicit /Dests dictionary.
     class Destinations
       attr_reader :document
 
@@ -10,12 +11,133 @@ module Pdfrb
         @document = document
       end
 
+      # Look up a named destination by name. Returns the destination
+      # array or nil.
       def [](name)
-        names = document.catalog.value[:Names]
-        return nil unless names.is_a?(::Hash) || names.is_a?(Pdfrb::Model::Cos::Dictionary)
+        dests_dict = resolved_explicit_dict
+        return dests_dict[name] if dests_dict && dests_dict[name]
 
-        dests = names.is_a?(Pdfrb::Model::Cos::Dictionary) ? names.value[:Dests] : names[:Dests]
-        dests ? dests[name] : nil
+        name_tree = resolved_name_tree
+        lookup_in_name_tree(name_tree, name)
+      end
+
+      # Add an explicit destination under +name+. Creates the /Dests
+      # dictionary if absent. +destination+ is typically an Array
+      # [page_ref, fit_keyword, *args].
+      def add(name, destination)
+        ensure_dictionaries
+        catalog = document.catalog
+        catalog.value[:Dests] ||= {}
+        catalog.value[:Dests][name.to_sym] = destination
+        name.to_sym
+      end
+
+      # Enumerate all destination names (from both /Dests and /Names/Dests).
+      def each_name(&)
+        return enum_for(:each_name) unless block_given?
+
+        seen = Set.new
+        explicit = resolved_explicit_dict
+        explicit&.each_key do |k|
+          next if seen.include?(k)
+
+          seen << k
+          yield k
+        end
+
+        name_tree = resolved_name_tree
+        each_name_tree_key(name_tree) do |k|
+          next if seen.include?(k)
+
+          seen << k
+          yield k
+        end
+      end
+
+      def names
+        each_name.to_a
+      end
+
+      def empty?
+        names.empty?
+      end
+
+      def count
+        names.size
+      end
+
+      private
+
+      def ensure_dictionaries
+        catalog = document.catalog
+        catalog.value[:Names] ||= {}
+        catalog.value[:Names][:Dests] ||= {}
+      end
+
+      def resolved_explicit_dict
+        catalog = document.catalog
+        d = catalog.value[:Dests]
+        return nil unless d
+
+        d.is_a?(Pdfrb::Model::Reference) ? document.object(d) : d
+      end
+
+      def resolved_name_tree
+        catalog = document.catalog
+        names = catalog.value[:Names]
+        return nil unless names
+
+        names = document.object(names) if names.is_a?(Pdfrb::Model::Reference)
+        return nil unless names
+
+        d = names.is_a?(Pdfrb::Model::Cos::Dictionary) ? names.value[:Dests] : names[:Dests]
+        return nil unless d
+
+        d.is_a?(Pdfrb::Model::Reference) ? document.object(d) : d
+      end
+
+      def lookup_in_name_tree(node, name)
+        return nil unless node
+
+        if node.is_a?(Pdfrb::Model::Cos::Dictionary) && node.value[:Names]
+          arr = node.value[:Names]
+          arr = arr.to_a if arr.is_a?(Pdfrb::Model::PdfArray)
+          arr.each_slice(2) { |k, v| return v if k == name }
+        elsif node.is_a?(Pdfrb::Model::Cos::Dictionary) && node.value[:Kids]
+          arr = node.value[:Kids]
+          arr = arr.to_a if arr.is_a?(Pdfrb::Model::PdfArray)
+          arr.each do |kid_ref|
+            kid = kid_ref.is_a?(Pdfrb::Model::Reference) ? document.object(kid_ref) : kid_ref
+            result = lookup_in_name_tree(kid, name)
+            return result if result
+          end
+        elsif node.is_a?(Hash) && node[:Names]
+          arr = node[:Names]
+          arr = arr.to_a if arr.is_a?(Pdfrb::Model::PdfArray)
+          arr.each_slice(2) { |k, v| return v if k == name }
+        end
+        nil
+      end
+
+      def each_name_tree_key(node, &block)
+        return unless node
+
+        if node.is_a?(Pdfrb::Model::Cos::Dictionary) && node.value[:Names]
+          arr = node.value[:Names]
+          arr = arr.to_a if arr.is_a?(Pdfrb::Model::PdfArray)
+          arr.each_slice(2) { |k, _v| yield k }
+        elsif node.is_a?(Pdfrb::Model::Cos::Dictionary) && node.value[:Kids]
+          arr = node.value[:Kids]
+          arr = arr.to_a if arr.is_a?(Pdfrb::Model::PdfArray)
+          arr.each do |kid_ref|
+            kid = kid_ref.is_a?(Pdfrb::Model::Reference) ? document.object(kid_ref) : kid_ref
+            each_name_tree_key(kid, &block)
+          end
+        elsif node.is_a?(Hash) && node[:Names]
+          arr = node[:Names]
+          arr = arr.to_a if arr.is_a?(Pdfrb::Model::PdfArray)
+          arr.each_slice(2) { |k, _v| yield k }
+        end
       end
     end
   end

data/lib/pdfrb/document/display.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  class Document
+    # Catalog display controls. Sets viewer behavior: hide toolbar,
+    # page layout, page mode, and open-action destination.
+    #
+    # /ViewerPreferences — fine-grained viewer controls
+    # /PageLayout — how pages are laid out in the viewer
+    # /PageMode — which panels are visible on open
+    # /OpenAction — initial destination or action
+    class Display
+      PAGE_LAYOUTS = %i[
+        SinglePage OneColumn TwoColumnLeft TwoColumnRight
+        TwoPageLeft TwoPageRight
+      ].freeze
+
+      PAGE_MODES = %i[
+        UseNone UseOutlines UseThumbs FullScreen UseOC UseAttachments
+      ].freeze
+
+      NON_FULLSCREEN_PAGE_MODES = %i[UseNone UseOutlines UseThumbs UseOC].freeze
+
+      DIRECTIONS = %i[L2R R2L].freeze
+
+      attr_reader :document
+
+      def initialize(document)
+        @document = document
+      end
+
+      # @param layout [Symbol] one of PAGE_LAYOUTS.
+      def page_layout=(layout)
+        raise ArgumentError, "invalid page layout: #{layout}" unless PAGE_LAYOUTS.include?(layout)
+
+        document.catalog.value[:PageLayout] = layout
+      end
+
+      # @param mode [Symbol] one of PAGE_MODES.
+      def page_mode=(mode)
+        raise ArgumentError, "invalid page mode: #{mode}" unless PAGE_MODES.include?(mode)
+
+        document.catalog.value[:PageMode] = mode
+      end
+
+      # Set the /OpenAction destination or action.
+      # @param dest_or_action [Array, Hash, Pdfrb::Destination::Fit,
+      #   Pdfrb::Model::PdfArray] the destination array or action dict.
+      def open_action=(dest_or_action)
+        document.catalog.value[:OpenAction] = dest_or_action
+      end
+
+      # Get or set /ViewerPreferences as a keyword-hash.
+      def viewer_preferences(**opts)
+        return read_viewer_preferences if opts.empty?
+
+        vp = document.catalog.value[:ViewerPreferences]
+        vp ||= {}
+        opts.each do |key, value|
+          vp[key] = value
+        end
+        document.catalog.value[:ViewerPreferences] = vp
+      end
+
+      # Convenience: hide toolbar and menubar, fit window.
+      def presentation_mode!
+        viewer_preferences(
+          HideToolbar: true,
+          HideMenubar: true,
+          FitWindow: true,
+          CenterWindow: true,
+          DisplayDocTitle: true
+        )
+        self.page_mode = :FullScreen
+      end
+
+      private
+
+      def read_viewer_preferences
+        document.catalog.value[:ViewerPreferences] || {}
+      end
+    end
+  end
+end