pdf-reader 2.14.1 → 2.15.0

data/lib/pdf/reader/object_hash.rb

@@ -32,8 +32,24 @@ class PDF::Reader
   class ObjectHash
     include Enumerable
 
+    #: type securityHandler = (
+    #|   PDF::Reader::NullSecurityHandler |
+    #|   PDF::Reader::AesV2SecurityHandler |
+    #|   PDF::Reader::Rc4SecurityHandler |
+    #|   PDF::Reader::AesV3SecurityHandler |
+    #|   PDF::Reader::UnimplementedSecurityHandler
+    #| )
+
+    #: untyped
     attr_accessor :default
-    attr_reader :trailer, :pdf_version
+
+    #: Hash[Symbol, untyped]
+    attr_reader :trailer
+
+    #: Float
+    attr_reader :pdf_version
+
+    #: securityHandler
     attr_reader :sec_handler
 
     # Creates a new ObjectHash object. Input can be a string with a valid filename
@@ -43,21 +59,25 @@ class PDF::Reader
     #
     #   :password - the user password to decrypt the source PDF
     #
+    #: ((IO | Tempfile | StringIO | String), ?Hash[Symbol, untyped]) -> void
     def initialize(input, opts = {})
-      @io          = extract_io_from(input)
-      @xref        = PDF::Reader::XRef.new(@io)
-      @pdf_version = read_version
-      @trailer     = @xref.trailer
-      @cache       = opts[:cache] || PDF::Reader::ObjectCache.new
-      @sec_handler = NullSecurityHandler.new
+      @io          = extract_io_from(input) #: IO | Tempfile | StringIO
+      @xref        = PDF::Reader::XRef.new(@io) #: PDF::Reader::XRef[PDF::Reader::Reference]
+      @pdf_version = read_version #: Float
+      @trailer     = @xref.trailer #: Hash[Symbol, untyped]
+      @cache       = opts[:cache] || PDF::Reader::ObjectCache.new #: PDF::Reader::ObjectCache
+      @sec_handler = NullSecurityHandler.new #: securityHandler
       @sec_handler = SecurityHandlerFactory.build(
         deref(trailer[:Encrypt]),
         deref(trailer[:ID]),
         opts[:password]
       )
+      @page_references = nil #: Array[PDF::Reader::Reference | Hash[Symbol, untyped]]?
+      @object_streams = nil #: Hash[PDF::Reader::Reference, PDF::Reader::ObjectStream]?
     end
 
     # returns the type of object a ref points to
+    #: ((Integer | PDF::Reader::Reference)) -> Symbol?
     def obj_type(ref)
       self[ref].class.to_s.to_sym
     rescue
@@ -65,6 +85,7 @@ class PDF::Reader
     end
 
     # returns true if the supplied references points to an object with a stream
+    #: ((Integer | PDF::Reader::Reference)) -> bool
     def stream?(ref)
       self.has_key?(ref) && self[ref].is_a?(PDF::Reader::Stream)
     end
@@ -78,6 +99,7 @@ class PDF::Reader
     # If a PDF::Reader::Reference object is used the exact ID and generation number
     # can be specified.
     #
+    #: ((Integer | PDF::Reader::Reference)) -> untyped
     def [](key)
       return default if key.to_i <= 0
 
@@ -93,6 +115,7 @@ class PDF::Reader
     # If key is a PDF::Reader::Reference object, lookup the corresponding
     # object in the PDF and return it. Otherwise return key untouched.
     #
+    #: (untyped) -> untyped
     def object(key)
       key.is_a?(PDF::Reader::Reference) ? self[key] : key
     end
@@ -104,6 +127,7 @@ class PDF::Reader
     # Guaranteed to only return an Array or nil. If the dereference results in
     # any other type then a MalformedPDFError exception will raise. Useful when
     # expecting an Array and no other type will do.
+    #: (untyped) -> Array[untyped]?
     def deref_array(key)
       obj = deref(key)
 
@@ -122,6 +146,7 @@ class PDF::Reader
     # expecting an Array and no other type will do.
     #
     # Some effort to cast array elements to a number is made for any non-numeric elements.
+    #: (untyped) -> Array[Numeric]?
     def deref_array_of_numbers(key)
       arr = deref(key)
 
@@ -148,6 +173,7 @@ class PDF::Reader
     # Guaranteed to only return a Hash or nil. If the dereference results in
     # any other type then a MalformedPDFError exception will raise. Useful when
     # expecting an Array and no other type will do.
+    #: (untyped) -> Hash[Symbol, untyped]?
     def deref_hash(key)
       obj = deref(key)
 
@@ -166,6 +192,7 @@ class PDF::Reader
     # expecting an Array and no other type will do.
     #
     # Some effort to cast to a symbol is made when the reference points to a non-symbol.
+    #: (untyped) -> Symbol?
     def deref_name(key)
       obj = deref(key)
 
@@ -190,6 +217,7 @@ class PDF::Reader
     # expecting an Array and no other type will do.
     #
     # Some effort to cast to an int is made when the reference points to a non-integer.
+    #: (untyped) -> Integer?
     def deref_integer(key)
       obj = deref(key)
 
@@ -214,6 +242,7 @@ class PDF::Reader
     # expecting an Array and no other type will do.
     #
     # Some effort to cast to a number is made when the reference points to a non-number.
+    #: (untyped) -> Numeric?
     def deref_number(key)
       obj = deref(key)
 
@@ -238,6 +267,7 @@ class PDF::Reader
     # Guaranteed to only return a PDF::Reader::Stream or nil. If the dereference results in
     # any other type then a MalformedPDFError exception will raise. Useful when
     # expecting a stream and no other type will do.
+    #: (untyped) -> PDF::Reader::Stream?
     def deref_stream(key)
       obj = deref(key)
 
@@ -258,6 +288,7 @@ class PDF::Reader
     # expecting a string and no other type will do.
     #
     # Some effort to cast to a string is made when the reference points to a non-string.
+    #: (untyped) -> String?
     def deref_string(key)
       obj = deref(key)
 
@@ -280,6 +311,7 @@ class PDF::Reader
     # Guaranteed to only return a PDF Name (symbol), Array or nil. If the dereference results in
     # any other type then a MalformedPDFError exception will raise. Useful when
     # expecting a Name or Array and no other type will do.
+    #: (untyped) -> (Symbol | Array[untyped] | nil)
     def deref_name_or_array(key)
       obj = deref(key)
 
@@ -298,6 +330,7 @@ class PDF::Reader
     # Guaranteed to only return a PDF::Reader::Stream, Array or nil. If the dereference results in
     # any other type then a MalformedPDFError exception will raise. Useful when
     # expecting a stream or Array and no other type will do.
+    #: (untyped) -> (PDF::Reader::Stream | Array[untyped] | nil)
     def deref_stream_or_array(key)
       obj = deref(key)
 
@@ -313,10 +346,12 @@ class PDF::Reader
     # Recursively dereferences the object refered to be +key+. If +key+ is not
     # a PDF::Reader::Reference, the key is returned unchanged.
     #
+    #: (untyped) -> untyped
     def deref!(key)
       deref_internal!(key, {})
     end
 
+    #: (untyped) -> Array[untyped]?
     def deref_array!(key)
       deref!(key).tap { |obj|
         if !obj.nil? && !obj.is_a?(Array)
@@ -325,6 +360,7 @@ class PDF::Reader
       }
     end
 
+    #: (untyped) -> Hash[Symbol, untyped]?
     def deref_hash!(key)
       deref!(key).tap { |obj|
         if !obj.nil? && !obj.is_a?(Hash)
@@ -345,6 +381,7 @@ class PDF::Reader
     # local_default is the object that will be returned if the requested key doesn't
     # exist.
     #
+    #: (untyped, ?untyped) -> untyped
     def fetch(key, local_default = nil)
       obj = self[key]
       if obj
@@ -358,6 +395,8 @@ class PDF::Reader
 
     # iterate over each key, value. Just like a ruby hash.
     #
+    # @override(allow_incompatible: true)
+    #: () { (PDF::Reader::Reference, untyped) -> untyped } -> untyped
     def each(&block)
       @xref.each do |ref|
         yield ref, self[ref]
@@ -367,6 +406,7 @@ class PDF::Reader
 
     # iterate over each key. Just like a ruby hash.
     #
+    #: { (PDF::Reader::Reference) -> untyped } -> untyped
     def each_key(&block)
       each do |id, obj|
         yield id
@@ -375,6 +415,7 @@ class PDF::Reader
 
     # iterate over each value. Just like a ruby hash.
     #
+    #: { (untyped) -> untyped } -> untyped
     def each_value(&block)
       each do |id, obj|
         yield obj
@@ -383,6 +424,7 @@ class PDF::Reader
 
     # return the number of objects in the file. An object with multiple generations
     # is counted once.
+    #: () -> Integer
     def size
       xref.size
     end
@@ -390,6 +432,7 @@ class PDF::Reader
 
     # return true if there are no objects in this file
     #
+    #: () -> bool
     def empty?
       size == 0 ? true : false
     end
@@ -397,6 +440,7 @@ class PDF::Reader
     # return true if the specified key exists in the file. key
     # can be an int or a PDF::Reader::Reference
     #
+    #: (untyped) -> bool
     def has_key?(check_key)
       # TODO update from O(n) to O(1)
       each_key do |key|
@@ -414,6 +458,7 @@ class PDF::Reader
 
     # return true if the specifiedvalue exists in the file
     #
+    #: (untyped) -> bool
     def has_value?(value)
       # TODO update from O(n) to O(1)
       each_value do |obj|
@@ -423,12 +468,14 @@ class PDF::Reader
     end
     alias :value? :has_key?
 
+    #: () -> String
     def to_s
       "<PDF::Reader::ObjectHash size: #{self.size}>"
     end
 
     # return an array of all keys in the file
     #
+    #: () -> Array[PDF::Reader::Reference]
     def keys
       ret = []
       each_key { |k| ret << k }
@@ -437,6 +484,7 @@ class PDF::Reader
 
     # return an array of all values in the file
     #
+    #: () -> untyped
     def values
       ret = []
       each_value { |v| ret << v }
@@ -445,12 +493,14 @@ class PDF::Reader
 
     # return an array of all values from the specified keys
     #
+    #: (*untyped) -> untyped
     def values_at(*ids)
       ids.map { |id| self[id] }
     end
 
     # return an array of arrays. Each sub array contains a key/value pair.
     #
+    #: () -> untyped
     def to_a
       ret = []
       each do |id, obj|
@@ -465,6 +515,7 @@ class PDF::Reader
     #
     # Useful for apps that want to extract data from specific pages.
     #
+    #: () -> Array[PDF::Reader::Reference | Hash[Symbol, untyped]]
     def page_references
       root  = fetch(trailer[:Root])
       @page_references ||= begin
@@ -473,10 +524,12 @@ class PDF::Reader
                            end
     end
 
+    #: () -> bool
     def encrypted?
       trailer.has_key?(:Encrypt)
     end
 
+    #: () -> bool
     def sec_handler?
       !!sec_handler
     end
@@ -486,6 +539,17 @@ class PDF::Reader
     # parse a traditional object from the PDF, starting from the byte offset indicated
     # in the xref table
     #
+    #: (PDF::Reader::Reference) -> (
+    #|   PDF::Reader::Reference |
+    #|   PDF::Reader::Token |
+    #|   PDF::Reader::Stream |
+    #|   Numeric |
+    #|   String |
+    #|   Symbol |
+    #|   Array[untyped] |
+    #|   Hash[untyped, untyped] |
+    #|   nil
+    #| )
     def fetch_object(key)
       if xref[key].is_a?(Integer)
         buf = new_buffer(xref[key])
@@ -495,13 +559,25 @@ class PDF::Reader
 
     # parse a object that's embedded in an object stream in the PDF
     #
+    #: (PDF::Reader::Reference) -> (
+    #|   PDF::Reader::Reference |
+    #|   PDF::Reader::Token |
+    #|   PDF::Reader::Stream |
+    #|   Numeric |
+    #|   String |
+    #|   Symbol |
+    #|   Array[untyped] |
+    #|   Hash[untyped, untyped] |
+    #|   nil
+    #| )
     def fetch_object_stream(key)
       if xref[key].is_a?(PDF::Reader::Reference)
         container_key = xref[key]
         stream = deref_stream(container_key)
         raise MalformedPDFError, "Object Stream cannot be nil" if stream.nil?
-        object_streams[container_key] ||= PDF::Reader::ObjectStream.new(stream)
-        object_streams[container_key][key.id]
+        if objstream = object_streams[container_key] ||= PDF::Reader::ObjectStream.new(stream)
+          objstream[key.id]
+        end
       end
     end
 
@@ -509,6 +585,17 @@ class PDF::Reader
     # isn't publicly available. It's used to avoid endless loops in the recursion, and
     # doesn't need to be part of the public API.
     #
+    #: (untyped, Hash[Integer, untyped]) -> (
+    #|   PDF::Reader::Reference |
+    #|   PDF::Reader::Token |
+    #|   PDF::Reader::Stream |
+    #|   Numeric |
+    #|   String |
+    #|   Symbol |
+    #|   Array[untyped] |
+    #|   Hash[untyped, untyped] |
+    #|   nil
+    #| )
     def deref_internal!(key, seen)
       seen_key = key.is_a?(PDF::Reader::Reference) ? key : key.object_id
 
@@ -538,6 +625,17 @@ class PDF::Reader
       end
     end
 
+    #: (PDF::Reader::Reference, untyped) -> (
+    #|   PDF::Reader::Reference |
+    #|   PDF::Reader::Token |
+    #|   PDF::Reader::Stream |
+    #|   Numeric |
+    #|   String |
+    #|   Symbol |
+    #|   Array[untyped] |
+    #|   Hash[untyped, untyped] |
+    #|   nil
+    #| )
     def decrypt(ref, obj)
       case obj
       when PDF::Reader::Stream then
@@ -559,14 +657,17 @@ class PDF::Reader
       end
     end
 
+    #: (?Integer) -> PDF::Reader::Buffer
     def new_buffer(offset = 0)
       PDF::Reader::Buffer.new(@io, :seek => offset)
     end
 
+    #: () -> PDF::Reader::XRef[PDF::Reader::Reference]
     def xref
       @xref
     end
 
+    #: () -> Hash[PDF::Reader::Reference, PDF::Reader::ObjectStream]
     def object_streams
       @object_streams ||= {}
     end
@@ -574,6 +675,9 @@ class PDF::Reader
     # returns an array of object references for all pages in this object store. The ordering of
     # the Array is significant and matches the page ordering of the document
     #
+    #: (PDF::Reader::Reference | Hash[Symbol, untyped]) -> (
+    #|   Array[PDF::Reader::Reference | Hash[Symbol, untyped] ]
+    #| )
     def get_page_objects(obj)
       derefed_obj = deref_hash(obj)
 
@@ -591,6 +695,7 @@ class PDF::Reader
       end
     end
 
+    #: () -> Float
     def read_version
       @io.seek(0)
       _m, version = *@io.read(10).to_s.match(/PDF-(\d.\d)/)
@@ -598,6 +703,7 @@ class PDF::Reader
       version.to_f
     end
 
+    #: (IO | Tempfile | StringIO | String) -> (IO | Tempfile | StringIO)
     def extract_io_from(input)
       if input.is_a?(IO) || input.is_a?(StringIO) || input.is_a?(Tempfile)
         input
@@ -608,6 +714,7 @@ class PDF::Reader
       end
     end
 
+    #: (String) -> (String)
     def read_as_binary(input)
       if File.respond_to?(:binread)
         File.binread(input.to_s)

data/lib/pdf/reader/object_stream.rb

@@ -8,11 +8,24 @@ class PDF::Reader
   # This is done for added compression and is described as an "Object Stream" in the spec.
   #
   class ObjectStream # :nodoc:
+    #: (PDF::Reader::Stream) -> void
     def initialize(stream)
-      @dict = stream.hash
-      @data = stream.unfiltered_data
+      @dict = stream.hash #: Hash[Symbol, untyped]
+      @data = stream.unfiltered_data #: String
+      @offsets = nil #: Hash[Integer, Integer] | nil
+      @buffer = nil #: PDF::Reader::Buffer | nil
     end
 
+    #: (Integer) -> (
+    #|   PDF::Reader::Reference |
+    #|   PDF::Reader::Token |
+    #|   Numeric |
+    #|   String |
+    #|   Symbol |
+    #|   Array[untyped] |
+    #|   Hash[untyped, untyped] |
+    #|   nil
+    #| )
     def [](objid)
       if offsets[objid].nil?
         nil
@@ -23,12 +36,14 @@ class PDF::Reader
       end
     end
 
+    #: () -> Integer
     def size
       TypeCheck.cast_to_int!(@dict[:N])
     end
 
     private
 
+    #: () -> Hash[Integer, Integer]
     def offsets
       @offsets ||= {}
       return @offsets if @offsets.keys.size > 0
@@ -39,10 +54,12 @@ class PDF::Reader
       @offsets
     end
 
+    #: () -> Integer
     def first
       TypeCheck.cast_to_int!(@dict[:First])
     end
 
+    #: () -> PDF::Reader::Buffer
     def buffer
       @buffer ||= PDF::Reader::Buffer.new(StringIO.new(@data))
     end

data/lib/pdf/reader/overlapping_runs_filter.rb

@@ -9,8 +9,9 @@ class PDF::Reader
 
     # This should be between 0 and 1. If TextRun B obscures this much of TextRun A (and they
     # have identical characters) then one will be discarded
-    OVERLAPPING_THRESHOLD = 0.5
+    OVERLAPPING_THRESHOLD = 0.5 #: Float
 
+    #: (Array[PDF::Reader::TextRun]) -> Array[PDF::Reader::TextRun]
     def self.exclude_redundant_runs(runs)
       sweep_line_status = Array.new
       event_point_schedule = Array.new
@@ -38,6 +39,7 @@ class PDF::Reader
       runs - to_exclude
     end
 
+    #: (Array[PDF::Reader::TextRun], PDF::Reader::EventPoint) -> bool
     def self.detect_intersection(sweep_line_status, event_point)
       sweep_line_status.each do |open_text_run|
         if open_text_run.text == event_point.run.text &&
@@ -55,15 +57,19 @@ class PDF::Reader
   # looking for duplicates
   class EventPoint
 
+    #: Numeric
     attr_reader :x
 
+    #: PDF::Reader::TextRun
     attr_reader :run
 
+    #: (Numeric, PDF::Reader::TextRun) -> void
     def initialize(x, run)
       @x = x
       @run = run
     end
 
+    #: () -> bool
     def start?
       @x == @run.x
     end