pdfrb 0.2.1 → 0.6.0

data/lib/pdfrb/linearization/writer.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+require "stringio"
+require "zlib"
+
+module Pdfrb
+  module Linearization
+    # Writes a PDF in linearized format (ISO 32000-2 §7.6.2, Annex F).
+    #
+    # Approach: serialize all objects to a temp buffer, compute final
+    # offsets, then assemble the file with the linearization parameter
+    # dict as the first indirect object. The lin dict values (/L, /H,
+    # /O, /E, /N, /T) are filled from the computed layout.
+    #
+    # This produces a structurally valid linearized PDF with page-offset
+    # hints. Full optimization (shared-object tables, minimal-download
+    # ordering) is future work.
+    class Writer
+      # Internal value object carrying computed offsets through assembly.
+      Layout = Struct.new(
+        :lin_dict_offset, :lin_dict_size,
+        :hint_offset, :hint_length,
+        :first_page_oid, :first_page_end,
+        :xref_offset, :total_size, :num_pages,
+        :ordered_objects, :hint_oid,
+        :hint_dict, :hint_compressed,
+        :xref_bytes, :trailer_bytes,
+        keyword_init: true
+      )
+
+      def initialize(document)
+        @document = document
+        @serializer = Pdfrb::Serializer.new
+      end
+
+      # @param io [IO] target output.
+      # @return [void]
+      def write(io)
+        io.binmode
+
+        pages = collect_pages
+        return write_non_linearized(io) if pages.length < 2
+
+        layout = compute_layout(pages)
+        assembled = assemble_file(pages, layout)
+        io.write(assembled)
+      end
+
+      private
+
+      def collect_pages
+        @document.pages.each.to_a
+      end
+
+      def compute_layout(pages) # rubocop:disable Metrics/MethodLength
+        all_objects = @document.each_indirect_object.to_a
+        first_page_closure = object_closure(pages.first)
+        first_page_objects, rest_objects = all_objects.partition { |o| first_page_closure.include?(o.oid) }
+
+        ordered = first_page_objects + rest_objects
+        hint_oid = @document.next_oid || 1
+
+        offsets = {}
+        temp = StringIO.new
+        temp.binmode
+        temp << header_bytes
+        lin_dict_size = estimate_lin_dict_size(pages.length)
+        lin_dict_offset = temp.pos
+        temp.write("X" * lin_dict_size)
+
+        ordered.each do |obj|
+          offsets[obj.oid] = temp.pos
+          temp << @serializer.serialize_indirect(obj)
+        end
+        first_page_end = temp.pos if first_page_objects.any?
+
+        hint = build_hint_stream(pages, offsets)
+        hint_data = hint.encode
+        hint_compressed = ::Zlib::Deflate.deflate(hint_data)
+        hint_offset = temp.pos
+        hint_dict = @serializer.serialize(
+          Type: :XRef,
+          S: HintStream::DEFAULT_ITEM_BITS,
+          Filter: :FlateDecode,
+          Length: hint_compressed.bytesize
+        )
+        temp << "#{hint_oid} 0 obj\n"
+        temp << hint_dict
+        temp << "\nstream\n"
+        temp << hint_compressed
+        temp << "\nendstream\nendobj\n"
+        offsets[hint_oid] = hint_offset
+
+        xref_offset = temp.pos
+        xref_bytes = build_xref(offsets)
+        temp << xref_bytes
+        temp << build_trailer(xref_offset)
+
+        Layout.new(
+          lin_dict_offset: lin_dict_offset,
+          lin_dict_size: lin_dict_size,
+          hint_offset: hint_offset,
+          hint_length: hint_compressed.bytesize,
+          first_page_oid: pages.first.oid,
+          first_page_end: first_page_end || temp.pos,
+          xref_offset: xref_offset,
+          total_size: temp.pos,
+          num_pages: pages.length,
+          ordered_objects: ordered,
+          hint_oid: hint_oid,
+          hint_dict: hint_dict,
+          hint_compressed: hint_compressed,
+          xref_bytes: xref_bytes,
+          trailer_bytes: build_trailer(xref_offset)
+        )
+      end
+
+      def assemble_file(_pages, layout)
+        buf = String.new(encoding: Encoding::BINARY)
+        buf << header_bytes.b
+
+        lin_dict = serialize_lin_dict(
+          total_size: layout.total_size,
+          hint_offset: layout.hint_offset,
+          hint_length: layout.hint_length,
+          first_page_oid: layout.first_page_oid,
+          first_page_end: layout.first_page_end,
+          num_pages: layout.num_pages,
+          xref_offset: layout.xref_offset
+        )
+        lin_padded = pad_to_size(lin_dict, layout.lin_dict_size)
+        buf << lin_padded
+
+        layout.ordered_objects.each do |obj|
+          buf << @serializer.serialize_indirect(obj)
+        end
+
+        buf << "#{layout.hint_oid} 0 obj\n"
+        buf << layout.hint_dict
+        buf << "\nstream\n"
+        buf << layout.hint_compressed
+        buf << "\nendstream\nendobj\n"
+
+        buf << layout.xref_bytes
+        buf << layout.trailer_bytes
+
+        buf.force_encoding(Encoding::BINARY)
+      end
+
+      def serialize_lin_dict(total_size:, hint_offset:, hint_length:,
+                             first_page_oid:, first_page_end:, num_pages:, xref_offset:)
+        dict_str = @serializer.serialize(
+          Linearized: 1,
+          L: total_size,
+          H: Pdfrb::Model::PdfArray.new([hint_offset, hint_length]),
+          O: first_page_oid,
+          E: first_page_end,
+          N: num_pages,
+          T: xref_offset
+        )
+        "1 0 obj\n#{dict_str}\nendobj\n"
+      end
+
+      def pad_to_size(str, target_size)
+        return str if str.bytesize >= target_size
+
+        str + ("\n" * (target_size - str.bytesize))
+      end
+
+      def estimate_lin_dict_size(_num_pages)
+        300
+      end
+
+      def build_hint_stream(pages, offsets)
+        hint = HintStream.new
+        base_offset = offsets[pages.first.oid] || 0
+
+        pages.each do |page|
+          offset = offsets[page.oid] || 0
+          hint.add_page(
+            offset_delta: offset - base_offset,
+            page_length: 200,
+            num_objects: 1,
+            page_obj_num: page.oid
+          )
+        end
+        hint
+      end
+
+      def object_closure(root)
+        seen = Set.new
+        queue = [root]
+
+        until queue.empty?
+          obj = queue.shift
+          next if seen.include?(obj.oid)
+
+          seen << obj.oid
+
+          value = obj.is_a?(Pdfrb::Model::Object) ? obj.value : obj
+          walk_for_refs(value) do |ref|
+            child = @document.object(ref)
+            queue << child if child && !seen.include?(child.oid)
+          end
+        end
+
+        seen
+      end
+
+      def walk_for_refs(value, &block)
+        case value
+        when ::Hash
+          value.each_value { |v| walk_for_refs(v, &block) }
+        when ::Array, Pdfrb::Model::PdfArray
+          value.each { |v| walk_for_refs(v, &block) }
+        when Pdfrb::Model::Reference
+          yield value
+        end
+      end
+
+      def build_xref(offsets)
+        buf = +""
+        oids = offsets.keys.sort
+        max_oid = oids.max || 0
+        buf << "xref\n"
+        buf << "0 #{max_oid + 1}\n"
+        buf << "0000000000 65535 f \r\n"
+        (1..max_oid).each do |oid|
+          off = offsets[oid]
+          buf << if off
+                   sprintf("%010d %05d n \r\n", off, 0)
+                 else
+                   "0000000000 00000 f \r\n"
+                 end
+        end
+        buf
+      end
+
+      def build_trailer(xref_offset)
+        root = @document.catalog
+        root_ref = if root.is_a?(Pdfrb::Model::Object) && root.indirect?
+                     Pdfrb::Model::Reference.new(root.oid, root.gen)
+                   end
+        size = [@document.next_oid || 1, 2].max
+
+        trailer_str = @serializer.serialize(Size: size, Root: root_ref)
+        "trailer\n#{trailer_str}\nstartxref\n#{xref_offset}\n%%EOF\n"
+      end
+
+      def header_bytes
+        "%PDF-1.7\n%\xE2\xE3\xCF\xD3\n"
+      end
+
+      def write_non_linearized(io)
+        Pdfrb::Writer.write(@document, io)
+      end
+    end
+  end
+end

data/lib/pdfrb/linearization.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  # Linearization (PDF 1.2+ fast-web-view, ISO 32000-2 §7.6.2 + Annex F).
+  #
+  # A linearized PDF is structured so the first page's data appears near
+  # the front of the file, enabling incremental download and display.
+  # The structure has:
+  #   Part 1: Linearization parameter dict + first-page xref
+  #   Part 2: First page's document objects
+  #   Part 3: Remaining pages' objects
+  #   Part 4: Hint stream (page-offset + shared-object tables)
+  #   Part 5: Main xref + trailer
+  #
+  # Detection: see Pdfrb::Source::LinearizationDetection.
+  # Writing: see Pdfrb::Linearization::Writer.
+  module Linearization
+    autoload :Writer, "pdfrb/linearization/writer"
+    autoload :HintStream, "pdfrb/linearization/hint_stream"
+  end
+end

data/lib/pdfrb/model/cos/dictionary.rb

@@ -271,6 +271,18 @@ module Pdfrb
           data.deref(document)
         end
 
+        # PDF Boolean values can come back as Ruby +true+/+false+, as the
+        # strings +"true"+/+"false"+ (from arlington defaults), or as
+        # +nil+ when absent. Normalise to a Ruby boolean.
+        def truthy?(value)
+          return false if value.nil? || value == false
+          return true if value == true
+          return false if value.to_s.downcase == "false"
+          return false if value.to_s.downcase == "no"
+
+          !!value
+        end
+
         private
 
         def unbox_object?(obj)

data/lib/pdfrb/model/pdf_array.rb

@@ -13,8 +13,8 @@ module Pdfrb
         super(Array(arr), oid: oid, gen: gen, document: document)
       end
 
-      def each(&block)
-        @value.each(&block)
+      def each(&)
+        @value.each(&)
         self
       end
 

data/lib/pdfrb/model/type/action.rb

@@ -13,6 +13,48 @@ module Pdfrb
 
         register_type :Action
 
+        def subtype; self[:S]; end
+        def next_action; self[:Next]; end
+
+        def next_actions
+          value = self[:Next]
+          return [] unless value
+
+          value.is_a?(Pdfrb::Model::PdfArray) ? value.to_a : value
+        end
+
+        def goto?
+          subtype&.to_sym == :GoTo
+        end
+
+        def uri?
+          subtype&.to_sym == :URI
+        end
+
+        def launch?
+          subtype&.to_sym == :Launch
+        end
+
+        def javascript?
+          subtype&.to_sym == :JavaScript
+        end
+
+        def named?
+          subtype&.to_sym == :Named
+        end
+
+        def uri
+          return nil unless uri?
+
+          self[:URI]
+        end
+
+        def d
+          return nil unless goto?
+
+          self[:D]
+        end
+
         class << self
           def subtype_map
             @subtype_map ||= {}

data/lib/pdfrb/model/type/action_go_to_3d_view.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    module Type
+      # GoTo3DView action (s12.6.4.12, PDF 1.6+). Navigate within a 3D stream.
+      class ActionGoTo3DView < Action
+        register_subtype :GoTo3DView
+
+        def target_view; self[:TA]; end
+      end
+    end
+  end
+end

data/lib/pdfrb/model/type/action_go_to_dp.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    module Type
+      # GoToDp action (s12.6.4.2, PDF 2.0). Destination pointer variant
+      # of GoTo that supports /DP (destination page) over a /D array.
+      class ActionGoToDp < Action
+        register_subtype :GoToDp
+
+        def destination_page; self[:DP]; end
+        def destination; self[:D]; end
+      end
+    end
+  end
+end

data/lib/pdfrb/model/type/action_go_to_r.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    module Type
+      # Remote GoTo action (s12.6.4.3). Navigate to a destination in
+      # another PDF file.
+      class ActionGoToR < Action
+        register_subtype :GoToR
+
+        def file_spec; self[:F]; end
+        def destination; self[:D]; end
+        def new_window?; self[:NewWindow] == true; end
+        def open_in_new_window?; new_window?; end
+
+        def named_destination?
+          destination.is_a?(String) || destination.is_a?(Symbol)
+        end
+
+        def page_index_destination?
+          destination.is_a?(Array) && destination.first.is_a?(Integer)
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/model/type/action_goto.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    module Type
+      # GoTo action (s12.6.4.2). Navigate to a destination.
+      class ActionGoTo < Action
+        register_subtype :GoTo
+
+        def destination; self[:D]; end
+
+        def page_index_destination?
+          destination.is_a?(Array) && destination.first.is_a?(Integer)
+        end
+
+        def named_destination?
+          destination.is_a?(Symbol) || destination.is_a?(String)
+        end
+
+        def target_page_number
+          return nil unless page_index_destination?
+
+          destination.first
+        end
+
+        def display_option
+          return nil unless page_index_destination?
+
+          destination[1..]
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/model/type/action_hide.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    module Type
+      # Hide action (s12.6.4.10). Show/hide annotations.
+      class ActionHide < Action
+        register_subtype :Hide
+
+        def targets; self[:T]; end
+        def hide?; self[:H] != false; end
+
+        def each_target
+          return enum_for(:each_target) unless block_given?
+          return unless targets && document
+
+          arr = targets.is_a?(Array) ? targets : [targets]
+          arr.each do |ref|
+            obj = ref.is_a?(Pdfrb::Model::Reference) ? document.object(ref) : ref
+            yield obj if obj
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/model/type/action_import_data.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    module Type
+      # Import-data action (s12.7.6.4). Imports form data from an FDF/XFDF file.
+      class ActionImportData < Action
+        register_subtype :ImportData
+
+        def file_spec; self[:F]; end
+
+        def has_file?
+          !!file_spec
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/model/type/action_java_script.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    module Type
+      # JavaScript action (s12.6.4.16). Execute JavaScript code.
+      class ActionJavaScript < Action
+        register_subtype :JavaScript
+
+        def script; self[:JS]; end
+
+        def has_script?
+          !!script && (!script.is_a?(String) || !script.empty?)
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/model/type/action_launch.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    module Type
+      # Launch action (s12.6.4.5). Launch an external application.
+      class ActionLaunch < Action
+        register_subtype :Launch
+
+        def file_spec; self[:F]; end
+        def new_window?; self[:NewWindow] == true; end
+        def win_target; self[:Win]; end
+        def mac_target; self[:Mac]; end
+        def unix_target; self[:Unix]; end
+
+        def has_platform_target?
+          !!win_target || !!mac_target || !!unix_target
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/model/type/action_movie.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    module Type
+      # Movie action (s12.6.4.8). Deprecated in PDF 2.0 but still
+      # appears in legacy PDFs. Plays/stops a Movie annotation.
+      class ActionMovie < Action
+        register_subtype :Movie
+
+        def annotation; self[:Annotation]; end
+        def title; self[:T]; end
+        def operation; self[:Operation]&.to_sym || :Play; end
+
+        def play?; operation == :Play; end
+        def stop?; operation == :Stop; end
+        def pause?; operation == :Pause; end
+        def resume?; operation == :Resume; end
+      end
+    end
+  end
+end

data/lib/pdfrb/model/type/action_named.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    module Type
+      # Named action (s12.6.4.19). Pre-defined action by name (NextPage,
+      # PrevPage, FirstPage, LastPage, Print, etc.).
+      class ActionNamed < Action
+        register_subtype :Named
+
+        def action_name; self[:N]; end
+
+        def next_page?; action_name&.to_sym == :NextPage; end
+        def prev_page?; action_name&.to_sym == :PrevPage; end
+        def first_page?; action_name&.to_sym == :FirstPage; end
+        def last_page?; action_name&.to_sym == :LastPage; end
+        def print?; action_name&.to_sym == :Print; end
+        def save?; action_name&.to_sym == :Save; end
+        def find?; action_name&.to_sym == :Find; end
+      end
+    end
+  end
+end

data/lib/pdfrb/model/type/action_nop.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    module Type
+      # NOP action (PDF 1.2 deprecated). No-op placeholder.
+      class ActionNOP < Action
+        register_subtype :NOP
+      end
+    end
+  end
+end

data/lib/pdfrb/model/type/action_rendition.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    module Type
+      # Rendition action (s12.6.4.12). Controls multimedia rendition
+      # on screen annotations.
+      class ActionRendition < Action
+        register_subtype :Rendition
+
+        def rendition; self[:R]; end
+        def screen_annotation; self[:AN]; end
+        def operation; self[:OP]; end
+        def javascript; self[:JS]; end
+
+        def play?; operation.zero?; end
+        def stop?; operation == 1; end
+        def pause?; operation == 2; end
+        def resume?; operation == 3; end
+        def play_resume?; operation == 4; end
+
+        def has_javascript?
+          !!javascript
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/model/type/action_reset_form.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    module Type
+      # Reset-form action (s12.7.6.3). Resets form fields to defaults.
+      class ActionResetForm < Action
+        register_subtype :ResetForm
+
+        def fields; self[:Fields]; end
+
+        def include_exclude?
+          !!self[:Flags] && self[:Flags].anybits?(1)
+        end
+
+        def has_field_list?
+          !!fields && (!fields.is_a?(Array) || !fields.empty?)
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/model/type/action_rich_media_execute.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Model
+    module Type
+      # RichMediaExecute action (s12.6.4.12, PDF 2.0). Execute a
+      # command on a RichMedia annotation.
+      class ActionRichMediaExecute < Action
+        register_subtype :RichMediaExecute
+
+        def target; self[:TA]; end
+        def instance; self[:Instance]; end
+        def arguments; self[:Args]; end
+      end
+    end
+  end
+end