pdfrb 0.2.1 → 0.6.0

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

data/lib/pdfrb/document/output_intents.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  class Document
+    # Output Intents facade. An output intent declares the intended
+    # output device color profile (ICC) so that downstream processors
+    # can render colors consistently. Required for PDF/X.
+    #
+    # /OutputIntents is an array on the Catalog. Each entry has:
+    #   /Type /OutputIntent
+    #   /S /GTS_PDFA1 (for PDF/A) or /GTS_PDFX (for PDF/X)
+    #   /OutputConditionIdentifier — registry name (e.g. "FOGRA39")
+    #   /OutputCondition — human-readable description
+    #   /RegistryName — e.g. "http://www.color.org"
+    #   /DestOutputProfile — ICC profile stream reference
+    class OutputIntents
+      attr_reader :document
+
+      def initialize(document)
+        @document = document
+      end
+
+      # Add an output intent referencing an ICC profile stream.
+      # @param icc_stream_ref [Pdfrb::Model::Reference] ICC profile stream.
+      # @param identifier [String] e.g. "FOGRA39", "CGATS TR 001".
+      # @param condition [String] human-readable description.
+      # @param registry [String] URL of the color registry.
+      # @param subtype [Symbol] :GTS_PDFA1 or :GTS_PDFX.
+      # @return [Pdfrb::Model::Cos::Dictionary] the output intent dict.
+      def add(icc_stream_ref, identifier:, condition: nil,
+              registry: nil, subtype: :GTS_PDFX)
+        intent = document.add(
+          {
+            Type: :OutputIntent,
+            S: subtype,
+            OutputConditionIdentifier: identifier,
+            OutputCondition: condition,
+            RegistryName: registry,
+            DestOutputProfile: icc_stream_ref,
+          }.compact,
+          type: Pdfrb::Model::Cos::Dictionary
+        )
+        catalog = document.catalog
+        intents = catalog.value[:OutputIntents]
+        ref = Pdfrb::Model::Reference.new(intent.oid, intent.gen)
+        if intents.nil?
+          catalog.value[:OutputIntents] = [ref]
+        elsif intents.is_a?(::Array)
+          intents << ref
+        else
+          catalog.value[:OutputIntents] = [intents, ref]
+        end
+        intent
+      end
+
+      # Convenience: embed an ICC profile and register as output intent.
+      def embed_icc(icc_bytes, identifier:, condition: nil,
+                     registry: nil, subtype: :GTS_PDFX)
+        profile = Pdfrb::Color::ICCProfile.new(icc_bytes)
+        stream = document.add(
+          { **profile.stream_dictionary_fields,
+            Length: profile.raw_data.bytesize },
+          type: Pdfrb::Model::Cos::Stream
+        )
+        stream.stream = profile.raw_data
+        ref = Pdfrb::Model::Reference.new(stream.oid, stream.gen)
+        add(ref, identifier: identifier, condition: condition, registry: registry, subtype: subtype)
+      end
+
+      # Enumerate output intents.
+      def each(&block)
+        intents = document.catalog.value[:OutputIntents]
+        return enum_for(:each) unless block
+        return self unless intents
+
+        intents.each do |ref|
+          obj = ref.is_a?(Pdfrb::Model::Reference) ? document.object(ref) : ref
+          yield obj if obj
+        end
+        self
+      end
+
+      def count
+        intents = document.catalog.value[:OutputIntents]
+        return 0 unless intents
+
+        intents.is_a?(::Array) ? intents.length : 1
+      end
+    end
+  end
+end

data/lib/pdfrb/document/page_labels.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  class Document
+    # Page Labels facade. Generates the /PageLabels number tree on the
+    # Catalog for custom page numbering (roman numerals, prefixed
+    # arabic, etc.).
+    #
+    # Usage:
+    #   doc.page_labels.set do
+    #     style :roman, count: 5      # i, ii, iii, iv, v
+    #     style :decimal, prefix: "A-" # A-1, A-2, ...
+    #   end
+    class PageLabels
+      STYLES = {
+        decimal: :D,
+        roman_lower: :r,
+        roman_upper: :R,
+        alpha_lower: :a,
+        alpha_upper: :A,
+      }.freeze
+
+      LabelRule = Struct.new(:style, :prefix, :start, :page_count, keyword_init: true)
+
+      attr_reader :document, :rules
+
+      def initialize(document)
+        @document = document
+        @rules = []
+        @current_index = 0
+      end
+
+      # Add a page labeling rule for the next batch of pages.
+      # @param style [Symbol] :decimal, :roman_lower, :roman_upper,
+      #   :alpha_lower, :alpha_upper.
+      # @param prefix [String] prefix prepended to each label.
+      # @param start [Integer] starting number (default 1).
+      # @param count [Integer, nil] number of pages this rule covers
+      #   (nil = until next rule or end).
+      def style(style, prefix: nil, start: 1, count: nil)
+        @rules << LabelRule.new(
+          style: STYLES.fetch(style),
+          prefix: prefix,
+          start: start,
+          page_count: count
+        )
+        @current_index += count if count
+        self
+      end
+
+      # Build the /PageLabels number tree and set it on the Catalog.
+      def commit!
+        return if @rules.empty?
+
+        nums = build_nums_array
+        document.catalog.value[:PageLabels] = { Nums: nums }
+      end
+
+      private
+
+      def build_nums_array
+        nums = []
+        index = 0
+        @rules.each do |rule|
+          nums << index
+          nums << rule_dict(rule)
+          index += rule.page_count if rule.page_count
+        end
+        nums
+      end
+
+      def rule_dict(rule)
+        dict = { S: rule.style }
+        dict[:P] = rule.prefix if rule.prefix
+        dict[:St] = rule.start unless rule.start == 1
+        dict
+      end
+    end
+  end
+end

data/lib/pdfrb/document/pages.rb

@@ -20,19 +20,24 @@ module Pdfrb
       #   rotate: 0                     # degrees
       #
       # Returns the new +Model::Type::Page+.
-      def add(media_box: [0, 0, 612, 792], rotate: 0)
+      def add(media_box: nil, rotate: 0, width: nil, height: nil,
+             bleed_box: nil, trim_box: nil, art_box: nil, crop_box: nil)
+        media_box ||= (width && height ? [0, 0, width, height] : [0, 0, 612, 792])
+        media_box ||= (width && height ? [0, 0, width, height] : [0, 0, 612, 792])
         root = pages_root
         contents = document.add({}, type: Pdfrb::Model::Cos::Stream)
-        page = document.add(
-          {
-            Type: :Page,
-            Parent: Pdfrb::Model::Reference.new(root.oid, root.gen),
-            MediaBox: media_box,
-            Resources: {},
-            Contents: Pdfrb::Model::Reference.new(contents.oid, 0)
-          },
-          type: Pdfrb::Model::Type::Page
-        )
+        page_hash = {
+          Type: :Page,
+          Parent: Pdfrb::Model::Reference.new(root.oid, root.gen),
+          MediaBox: media_box,
+          Resources: {},
+          Contents: Pdfrb::Model::Reference.new(contents.oid, 0)
+        }
+        page_hash[:BleedBox] = bleed_box if bleed_box
+        page_hash[:TrimBox] = trim_box if trim_box
+        page_hash[:ArtBox] = art_box if art_box
+        page_hash[:CropBox] = crop_box if crop_box
+        page = document.add(page_hash, type: Pdfrb::Model::Type::Page)
         page.value[:Rotate] = rotate if rotate.nonzero?
         kids = (root.value[:Kids] ||= [])
         kids << Pdfrb::Model::Reference.new(page.oid, page.gen)
@@ -41,10 +46,10 @@ module Pdfrb
       end
       alias << add
 
-      def each(&block)
+      def each(&)
         return enum_for(:each) unless block_given?
 
-        walk(pages_root, &block)
+        walk(pages_root, &)
         self
       end
 
@@ -83,6 +88,52 @@ module Pdfrb
         page
       end
 
+      # Delete the page at +index+ (0-based).
+      def delete_at(index)
+        page = self[index]
+        return nil unless page
+
+        delete(page)
+      end
+
+      # Set /Rotate on every page. +angle+ must be 0, 90, 180, or 270.
+      def rotate(angle)
+        each { |page| page.value[:Rotate] = angle }
+        self
+      end
+
+      # Move a page from one position to another.
+      # @param from [Integer] source index (0-based).
+      # @param to [Integer] destination index (0-based).
+      def move(from, to)
+        return self if from == to
+
+        root = pages_root
+        kids = root.value[:Kids]
+        return self unless kids.is_a?(::Array)
+
+        page = self[from]
+        return self unless page
+
+        ref = ref_to(page)
+        kids.delete(ref)
+        # Clamp to valid range after deletion.
+        insert_at = to > from ? to - 1 : to
+        kids.insert(insert_at, ref)
+        self
+      end
+
+      # Iterate pages with index.
+      def each_with_index(&)
+        return enum_for(:each_with_index) unless block_given?
+
+        i = 0
+        each do |page|
+          yield page, i
+          i += 1
+        end
+      end
+
       private
 
       def pages_root
@@ -100,26 +151,24 @@ module Pdfrb
       end
 
       def walk(node, &block)
-        kids = node.respond_to?(:value) ? node.value[:Kids] : node[:Kids]
+        kids = node.is_a?(Pdfrb::Model::Cos::Dictionary) ? node.value[:Kids] : node[:Kids]
         return unless kids
 
-        # Kids may itself be an indirect reference, especially in
-        # compressed-object PDFs (FOP output).
         kids = document.object(kids).value if kids.is_a?(Pdfrb::Model::Reference)
-        kids = kids.value if kids.respond_to?(:value) && !kids.is_a?(::Hash)
+        kids = kids.value if kids.is_a?(Pdfrb::Model::Cos::Dictionary) && !kids.is_a?(::Hash)
 
         Array(kids).each do |kid_ref|
           kid = kid_ref.is_a?(Pdfrb::Model::Reference) ?
                   document.object(kid_ref) : kid_ref
           next unless kid
 
-          type = kid.respond_to?(:value) ? kid.value[:Type] : nil
+          type = kid.is_a?(Pdfrb::Model::Cos::Dictionary) ? kid.value[:Type] : nil
           case type
           when :Pages then walk(kid, &block)
           when :Page then yield kid
           else
             # Unknown type — best effort, treat as a Page.
-            yield kid if kid.respond_to?(:value)
+            yield kid if kid.is_a?(Pdfrb::Model::Cos::Dictionary)
           end
         end
       end

data/lib/pdfrb/document/portfolio.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  class Document
+    # PDF Portfolio facade. A portfolio is a PDF with a /Collection
+    # dictionary on the Catalog that provides a collection view of
+    # embedded files (ISO 32000-2 §12.3.5).
+    #
+    # Inspired by mn2pdf's PDFPortfolio (which uses PDFBox). Provides
+    # field schema, default view configuration, and per-item metadata.
+    class Portfolio
+      Field = Struct.new(:name, :type, :subtype, :order, keyword_init: true) do
+        def pdf_hash
+          h = { N: name, T: type }
+          h[:FT] = type unless type == :text
+          h[:Subtype] = subtype if subtype
+          h[:O] = order if order
+          h
+        end
+      end
+
+      Item = Struct.new(:name, :file_bytes, :mime_type,
+                        :description, :fields, keyword_init: true)
+
+      DEFAULT_FIELDS = [
+        { name: "Name", type: :text }.freeze,
+        { name: "Description", type: :text, subtype: :Description }.freeze,
+        { name: "Size", type: :number }.freeze,
+        { name: "Modified", type: :date, subtype: :CreationDate }.freeze,
+      ].freeze
+
+      attr_reader :document, :items, :schema_fields
+
+      def initialize(document)
+        @document = document
+        @items = []
+        @schema_fields = DEFAULT_FIELDS.map { |f| Field.new(**f) }
+      end
+
+      # Add a schema field. Order matters for display.
+      def add_field(name, type: :text, subtype: nil, order: nil)
+        @schema_fields << Field.new(
+          name: name,
+          type: type,
+          subtype: subtype,
+          order: order || @schema_fields.length
+        )
+      end
+
+      # Add an item (embedded file) to the portfolio.
+      def add_item(name, file_bytes, mime_type: nil,
+                   description: nil, fields: {})
+        @items << Item.new(
+          name: name,
+          file_bytes: file_bytes,
+          mime_type: mime_type,
+          description: description,
+          fields: fields
+        )
+      end
+
+      # Commit the portfolio configuration to the document.
+      # Sets /Collection on the Catalog, creates /Filespec for each item,
+      # and embeds the file data via /EF.
+      def commit!
+        catalog = document.catalog
+        catalog.value[:Collection] = collection_dict
+      end
+
+      private
+
+      def collection_dict
+        {
+          Type: :Collection,
+          Schema: schema_fields.map(&:pdf_hash),
+          D: {
+            View: :D,
+            Hide: false,
+            Order: @schema_fields.map(&:name),
+          },
+          Items: items_references,
+        }
+      end
+
+      def items_references
+        @items.map do |item|
+          filespec = document.add(
+            {
+              Type: :Filespec,
+              F: item.name,
+              UF: item.name,
+              Desc: item.description,
+            }.compact,
+            type: Pdfrb::Model::Cos::Dictionary
+          )
+          ef = document.add(
+            {
+              F: embedded_file_ref(item),
+              UF: embedded_file_ref(item),
+            },
+            type: Pdfrb::Model::Cos::Dictionary
+          )
+          filespec.value[:EF] = Pdfrb::Model::Reference.new(ef.oid, ef.gen)
+          filespec.value[:AFRelationship] = :Unspecified
+          Pdfrb::Model::Reference.new(filespec.oid, filespec.gen)
+        end
+      end
+
+      def embedded_file_ref(item)
+        embedded = document.add(
+          { Type: :EmbeddedFile, Length: item.file_bytes.bytesize },
+          type: Pdfrb::Model::Cos::Stream
+        )
+        embedded.stream = item.file_bytes
+        Pdfrb::Model::Reference.new(embedded.oid, embedded.gen)
+      end
+    end
+  end
+end

data/lib/pdfrb/document/shadings.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  class Document
+    # Gradient shading patterns facade. Creates Type 2 (axial) and
+    # Type 3 (radial) shading dictionaries and registers them in page
+    # /Resources /Shading.
+    #
+    # For 2-stop gradients, uses a Type 2 ExponentialInterpolation
+    # function (/FunctionType 2). For multi-stop, chains Type 3
+    # StitchingFunction.
+    class Shadings
+      attr_reader :document, :registry
+
+      def initialize(document)
+        @document = document
+        @registry = {}
+        @next_id = 1
+      end
+
+      # Add an axial (linear) gradient.
+      # @param from [Array(Numeric, Numeric)] start point [x, y].
+      # @param to [Array(Numeric, Numeric)] end point [x, y].
+      # @param stops [Array<Array>] gradient stops:
+      #   [[offset, [color_family, *values]], ...]
+      # @param extend [Array<Boolean, Boolean>] extend before/after.
+      # @return [Symbol] shading resource name (e.g., :Sh1).
+      def add_axial(from:, to:, stops:, extend: [true, true])
+        color_space = stops_to_color_values(stops.first || [0, [:gray, 0]])[0]
+        name = next_name
+
+        function = build_gradient_function(stops, color_space)
+
+        shading = document.add(
+          {
+            ShadingType: 2,
+            ColorSpace: color_space,
+            Coords: Pdfrb::Model::PdfArray.new([*from, *to]),
+            Function: function,
+            Extend: Pdfrb::Model::PdfArray.new(extend),
+          },
+          type: Pdfrb::Model::Cos::Dictionary
+        )
+        register(name, shading)
+        name
+      end
+
+      # Add a radial gradient.
+      # @param from [Array(Numeric, Numeric, Numeric)] [cx, cy, radius].
+      # @param to [Array(Numeric, Numeric, Numeric)] [cx, cy, radius].
+      # @param stops [Array<Array>] same format as axial.
+      # @param extend [Array<Boolean, Boolean>] extend before/after.
+      # @return [Symbol] shading resource name.
+      def add_radial(from:, to:, stops:, extend: [true, true])
+        color_space = stops_to_color_values(stops.first || [0, [:gray, 0]])[0]
+        name = next_name
+
+        function = build_gradient_function(stops, color_space)
+
+        shading = document.add(
+          {
+            ShadingType: 3,
+            ColorSpace: color_space,
+            Coords: Pdfrb::Model::PdfArray.new([*from, *to]),
+            Function: function,
+            Extend: Pdfrb::Model::PdfArray.new(extend),
+          },
+          type: Pdfrb::Model::Cos::Dictionary
+        )
+        register(name, shading)
+        name
+      end
+
+      def [](name)
+        @registry[name]
+      end
+
+      def each(&block)
+        return enum_for(:each) unless block
+
+        @registry.each(&block)
+        self
+      end
+
+      private
+
+      def build_gradient_function(stops, color_space)
+        return build_exponential_function(nil, nil, color_space) if stops.empty?
+
+        if stops.length == 2
+          _, c0 = stops_to_color_values(stops[0])
+          _, c1 = stops_to_color_values(stops[1])
+          build_exponential_function(c0, c1, color_space)
+        else
+          build_stitching_function(stops, color_space)
+        end
+      end
+
+      def build_stitching_function(stops, color_space)
+        functions = stops.each_cons(2).map do |s0, s1|
+          _, c0 = stops_to_color_values(s0)
+          _, c1 = stops_to_color_values(s1)
+          build_exponential_function(c0, c1, color_space)
+        end
+
+        bounds = stops[1..-2].map { |s| s[0] }
+
+        document.add(
+          {
+            FunctionType: 3,
+            Domain: Pdfrb::Model::PdfArray.new([0, 1]),
+            Functions: functions.map { |f| Pdfrb::Model::Reference.new(f.oid, f.gen) },
+            Bounds: Pdfrb::Model::PdfArray.new(bounds),
+            Encode: Pdfrb::Model::PdfArray.new(stops.each_cons(2).map { [0, 1] }.flatten),
+          },
+          type: Pdfrb::Model::Cos::Dictionary
+        )
+      end
+
+      def stops_to_color_values(stop)
+        family, *values = stop[1]
+        cs = case family.to_sym
+             when :rgb then :DeviceRGB
+             when :cmyk then :DeviceCMYK
+             else :DeviceGray
+             end
+        [cs, values]
+      end
+
+      def build_exponential_function(c0, c1, _color_space)
+        document.add(
+          {
+            FunctionType: 2,
+            Domain: Pdfrb::Model::PdfArray.new([0, 1]),
+            C0: Pdfrb::Model::PdfArray.new(c0),
+            C1: Pdfrb::Model::PdfArray.new(c1),
+            N: 1,
+          },
+          type: Pdfrb::Model::Cos::Dictionary
+        )
+      end
+
+      def register(name, shading_obj)
+        @registry[name] = shading_obj
+        catalog = document.catalog
+        catalog.value[:Resources] ||= {}
+        catalog.value[:Resources][:Shading] ||= {}
+        catalog.value[:Resources][:Shading][name] =
+          Pdfrb::Model::Reference.new(shading_obj.oid, shading_obj.gen)
+      end
+
+      def next_name
+        name = :"Sh#{@next_id}"
+        @next_id += 1
+        name
+      end
+    end
+  end
+end

data/lib/pdfrb/document/stamps.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  class Document
+    # Page stamping facade. Stamps a Form XObject (logo, watermark,
+    # page number) onto every page of the document by emitting the
+    # Do operator in each page's content stream.
+    class Stamps
+      attr_reader :document
+
+      def initialize(document)
+        @document = document
+      end
+
+      # Stamp a Form XObject on every page.
+      #
+      # @param form_xobject [Pdfrb::Model::Cos::Stream] the Form XObject.
+      # @param at [Array<Numeric>] x, y position in points.
+      # @return [Symbol] the resource name (e.g., :St1).
+      def stamp_everywhere(form_xobject, at: [0, 0])
+        name = next_stamp_name
+        ref = Pdfrb::Model::Reference.new(form_xobject.oid, form_xobject.gen)
+
+        document.pages.each do |page|
+          register_xobject_in_resources(page, name, ref)
+          emit_do_operator(page, name, at)
+        end
+        name
+      end
+
+      # Stamp a Form XObject on a single page.
+      def stamp_page(page, form_xobject, at: [0, 0])
+        name = next_stamp_name
+        ref = Pdfrb::Model::Reference.new(form_xobject.oid, form_xobject.gen)
+        register_xobject_in_resources(page, name, ref)
+        emit_do_operator(page, name, at)
+        name
+      end
+
+      private
+
+      def next_stamp_name
+        @stamp_counter ||= 0
+        @stamp_counter += 1
+        :"St#{@stamp_counter}"
+      end
+
+      def register_xobject_in_resources(page, name, ref)
+        resources = page.value[:Resources]
+        resources = page.value[:Resources] = {} unless resources.is_a?(Pdfrb::Model::Cos::Dictionary)
+        xobjects = resources.value[:XObject] || {}
+        xobjects[name] = ref
+        resources.value[:XObject] = xobjects
+      end
+
+      def emit_do_operator(page, name, at)
+        canvas = page.canvas
+        x, y = at
+        canvas.save_graphics_state
+        canvas.translate(x, y) if x != 0 || y != 0
+        canvas.emit_op(Pdfrb::Content::Operator::InvokeXObject, name)
+        canvas.restore_graphics_state
+      rescue StandardError
+        # Canvas may not be available on pages with no content stream yet.
+      end
+    end
+  end
+end