pdf-reader 2.14.1 → 2.15.0

data/lib/pdf/reader/page.rb

@@ -2,6 +2,8 @@
 # typed: strict
 # frozen_string_literal: true
 
+require 'set'
+
 module PDF
   class Reader
 
@@ -17,14 +19,17 @@ module PDF
       extend Forwardable
 
       # lowlevel hash-like access to all objects in the underlying PDF
+      #: PDF::Reader::ObjectHash
       attr_reader :objects
 
       # the raw PDF object that defines this page
+      #: Hash[Symbol, untyped]
       attr_reader :page_object
 
       # a Hash-like object for storing cached data. Generally this is scoped to
       # the current document and is used to avoid repeating expensive
       # operations
+      #: PDF::Reader::ObjectCache | Hash[untyped, untyped]
       attr_reader :cache
 
       def_delegators :resources, :color_spaces
@@ -41,10 +46,16 @@ module PDF
       # * objects - an ObjectHash instance that wraps a PDF file
       # * pagenum - an int specifying the page number to expose. 1 indexed.
       #
+      #: (PDF::Reader::ObjectHash, Integer, ?Hash[Symbol, untyped]) -> void
       def initialize(objects, pagenum, options = {})
-        @objects, @pagenum = objects, pagenum
-        @page_object = objects.deref_hash(objects.page_references[pagenum - 1]) || {}
-        @cache       = options[:cache] || {}
+        @objects = objects
+        @pagenum = pagenum
+        @page_ref = objects.page_references[pagenum - 1] #: (Reference | Hash[Symbol, untyped])?
+        @page_object = objects.deref_hash(@page_ref) || {} #: Hash[Symbol, untyped]
+        @cache       = options[:cache] || {} #: PDF::Reader::ObjectCache | Hash[untyped, untyped]
+        @attributes = nil #: Hash[Symbol, untyped] | nil
+        @root = nil #: Hash[Symbol, untyped] | nil
+        @resources = nil #: PDF::Reader::Resources | nil
 
         if @page_object.empty?
           raise InvalidPageError, "Invalid page: #{pagenum}"
@@ -53,12 +64,14 @@ module PDF
 
       # return the number of this page within the full document
       #
+      #: () -> Integer
       def number
         @pagenum
       end
 
       # return a friendly string representation of this page
       #
+      #: () -> String
       def inspect
         "<PDF::Reader::Page page: #{@pagenum}>"
       end
@@ -66,6 +79,7 @@ module PDF
       # Returns the attributes that accompany this page, including
       # attributes inherited from parents.
       #
+      #: () -> Hash[Symbol, untyped]
       def attributes
         @attributes ||= {}.tap { |hash|
           page_with_ancestors.reverse.each do |obj|
@@ -78,18 +92,21 @@ module PDF
         @attributes
       end
 
+      #: () -> Numeric
       def height
         rect = Rectangle.new(*attributes[:MediaBox])
         rect.apply_rotation(rotate) if rotate > 0
         rect.height
       end
 
+      #: () -> Numeric
       def width
         rect = Rectangle.new(*attributes[:MediaBox])
         rect.apply_rotation(rotate) if rotate > 0
         rect.width
       end
 
+      #: () -> Array[Numeric]
       def origin
         rect = Rectangle.new(*attributes[:MediaBox])
         rect.apply_rotation(rotate) if rotate > 0
@@ -99,6 +116,7 @@ module PDF
 
       # Convenience method to identify the page's orientation.
       #
+      #: () -> String
       def orientation
         if height > width
           "portrait"
@@ -110,6 +128,7 @@ module PDF
       # returns the plain text content of this page encoded as UTF-8. Any
       # characters that can't be translated will be returned as a ▯
       #
+      #: (?Hash[Symbol, untyped]) -> String
       def text(opts = {})
         receiver = PageTextReceiver.new
         walk(receiver)
@@ -122,6 +141,7 @@ module PDF
       end
       alias :to_s :text
 
+      #: (?Hash[Symbol, untyped]) -> Array[PDF::Reader::TextRun]
       def runs(opts = {})
         receiver = PageTextReceiver.new
         walk(receiver)
@@ -151,6 +171,7 @@ module PDF
       # a set of instructions and associated resources. Calling walk() executes
       # the program in the correct order and calls out to your implementation.
       #
+      #: (*untyped) -> untyped
       def walk(*receivers)
         receivers = receivers.map { |receiver|
           ValidatingReceiver.new(receiver)
@@ -162,6 +183,7 @@ module PDF
       # returns the raw content stream for this page. This is plumbing, nothing to
       # see here unless you're a PDF nerd like me.
       #
+      #: () -> String
       def raw_content
         contents = objects.deref_stream_or_array(@page_object[:Contents])
         [contents].flatten.compact.map { |obj|
@@ -173,6 +195,7 @@ module PDF
 
       # returns the angle to rotate the page clockwise. Always 0, 90, 180 or 270
       #
+      #: () -> Integer
       def rotate
         value = attributes[:Rotate].to_i
         case value
@@ -188,6 +211,7 @@ module PDF
       #
       # DEPRECATED. Recommend using Page#rectangles instead
       #
+      #: () -> Hash[Symbol, Array[Numeric]]
       def boxes
         # In ruby 2.4+ we could use Hash#transform_values
         Hash[rectangles.map{ |k,rect| [k,rect.to_a] } ]
@@ -196,6 +220,7 @@ module PDF
       # returns the "boxes" that define the page object.
       # values are defaulted according to section 7.7.3.3 of the PDF Spec 1.7
       #
+      #: () -> Hash[Symbol, PDF::Reader::Rectangle]
       def rectangles
         # attributes[:MediaBox] can never be nil, but I have no easy way to tell sorbet that atm
         mediabox = objects.deref_array_of_numbers(attributes[:MediaBox]) || []
@@ -233,6 +258,7 @@ module PDF
 
       private
 
+      #: () -> Hash[Symbol, untyped]
       def root
         @root ||= objects.deref_hash(@objects.trailer[:Root]) || {}
       end
@@ -240,10 +266,12 @@ module PDF
       # Returns the resources that accompany this page. Includes
       # resources inherited from parents.
       #
+      #: () -> PDF::Reader::Resources
       def resources
         @resources ||= Resources.new(@objects, @objects.deref_hash(attributes[:Resources]) || {})
       end
 
+      #: (Array[untyped], String) -> void
       def content_stream(receivers, instructions)
         buffer       = Buffer.new(StringIO.new(instructions), :content_stream => true)
         parser       = Parser.new(buffer, @objects)
@@ -265,6 +293,7 @@ module PDF
       #
       # The silly style here is because sorbet won't let me use splat arguments
       #
+      #: (Array[Object], Symbol, ?Array[untyped]) -> void
       def callback(receivers, name, params=[])
         receivers.each do |receiver|
           if receiver.respond_to?(name)
@@ -286,25 +315,30 @@ module PDF
         end
       end
 
+      #: () -> untyped
       def page_with_ancestors
-        [ @page_object ] + ancestors
+        [ @page_object ] + ancestors(@page_object[:Parent], Set[@page_ref.hash])
       end
 
-      def ancestors(origin = @page_object[:Parent])
+      #: (?untyped, ?Set[Integer]) -> untyped
+      def ancestors(origin = @page_object[:Parent], seen = Set.new)
         if origin.nil?
           []
+        elsif seen.include?(origin.hash)
+          raise PDF::Reader::MalformedPDFError.new("loop found in ancestor path")
         else
           obj = objects.deref_hash(origin)
           if obj.nil?
-            raise MalformedPDFError, "parent mus not be nil"
+            raise MalformedPDFError, "parent must not be nil"
           end
-          [ select_inheritable(obj) ] + ancestors(obj[:Parent])
+          [ select_inheritable(obj) ] + ancestors(obj[:Parent], seen.add(origin.hash))
         end
       end
 
       # select the elements from a Pages dictionary that can be inherited by
       # child Page dictionaries.
       #
+      #: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
       def select_inheritable(obj)
         ::Hash[obj.select { |key, value|
           [:Resources, :MediaBox, :CropBox, :Rotate, :Parent].include?(key)

data/lib/pdf/reader/page_layout.rb

@@ -14,23 +14,29 @@ class PDF::Reader
   # page to be rendered as described by the page's MediaBox attribute
   class PageLayout
 
-    DEFAULT_FONT_SIZE = 12
+    DEFAULT_FONT_SIZE = 12 #: Numeric
 
+    #: (Array[PDF::Reader::TextRun], Array[Numeric] | PDF::Reader::Rectangle) -> void
     def initialize(runs, mediabox)
       # mediabox is a 4-element array for now, but it'd be nice to switch to a
       # PDF::Reader::Rectangle at some point
       PDF::Reader::Error.validate_not_nil(mediabox, "mediabox")
 
-      @mediabox = process_mediabox(mediabox)
-      @runs = runs
-      @mean_font_size   = mean(@runs.map(&:font_size)) || DEFAULT_FONT_SIZE
+      @mediabox = process_mediabox(mediabox) #: PDF::Reader::Rectangle
+      @runs = runs #: Array[PDF::Reader::TextRun]
+      @mean_font_size   = mean(@runs.map(&:font_size)) || DEFAULT_FONT_SIZE #: Numeric
       @mean_font_size = DEFAULT_FONT_SIZE if @mean_font_size == 0
-      @median_glyph_width = median(@runs.map(&:mean_character_width)) || 0
-      @x_offset = @runs.map(&:x).sort.first || 0
-      lowest_y = @runs.map(&:y).sort.first || 0
-      @y_offset = lowest_y > 0 ? 0 : lowest_y
+      @median_glyph_width = median(@runs.map(&:mean_character_width)) || 0 #: Numeric
+      @x_offset = @runs.map(&:x).sort.first || 0 #: Numeric
+      lowest_y = @runs.map(&:y).sort.first || 0 #: Numeric
+      @y_offset = lowest_y > 0 ? 0 : lowest_y #: Numeric
+      @row_count = nil #: Numeric | nil
+      @col_count = nil #: Numeric | nil
+      @row_multiplier = nil #: Numeric | nil
+      @col_multiplier = nil #: Numeric | nil
     end
 
+    #: () -> String
     def to_s
       return "" if @runs.empty?
       return "" if row_count == 0
@@ -48,10 +54,12 @@ class PDF::Reader
 
     private
 
+    #: () -> Numeric
     def page_width
       @mediabox.width
     end
 
+    #: () -> Numeric
     def page_height
       @mediabox.height
     end
@@ -62,6 +70,7 @@ class PDF::Reader
     #   interesting_rows([ "", "one", "two", "" ])
     #   => [ "one", "two" ]
     #
+    #: (untyped) -> untyped
     def interesting_rows(rows)
       line_lengths = rows.map { |l| l.strip.length }
 
@@ -73,22 +82,27 @@ class PDF::Reader
       rows[first_line_with_text, interesting_line_count].map
     end
 
+    #: () -> untyped
     def row_count
       @row_count ||= (page_height / @mean_font_size).floor
     end
 
+    #: () -> untyped
     def col_count
       @col_count ||= ((page_width  / @median_glyph_width) * 1.05).floor
     end
 
+    #: () -> untyped
     def row_multiplier
       @row_multiplier ||= page_height.to_f / row_count.to_f
     end
 
+    #: () -> untyped
     def col_multiplier
       @col_multiplier ||= page_width.to_f / col_count.to_f
     end
 
+    #: (untyped) -> untyped
     def mean(collection)
       if collection.size == 0
         0
@@ -97,6 +111,7 @@ class PDF::Reader
       end
     end
 
+    #: (untyped) -> untyped
     def median(collection)
       if collection.size == 0
         0
@@ -105,10 +120,12 @@ class PDF::Reader
       end
     end
 
+    #: (untyped, untyped, untyped) -> untyped
     def local_string_insert(haystack, needle, index)
       haystack[Range.new(index, index + needle.length - 1)] = String.new(needle)
     end
 
+    #: (untyped) -> untyped
     def process_mediabox(mediabox)
       if mediabox.is_a?(Array)
         msg = "Passing the mediabox to PageLayout as an Array is deprecated," +

data/lib/pdf/reader/page_state.rb

@@ -20,9 +20,10 @@ class PDF::Reader
         :text_mode      => 0,
         :text_rise      => 0,
         :text_knockout  => 0
-      }
+      } #: Hash[Symbol, Numeric | nil]
 
       # starting a new page
+      #: (untyped) -> void
       def initialize(page)
         @page          = page
         @cache         = page.cache
@@ -48,12 +49,14 @@ class PDF::Reader
       # Any changes that are subsequently made to the state can then by reversed
       # by calling restore_graphics_state.
       #
+      #: () -> untyped
       def save_graphics_state
         @stack.push clone_state
       end
 
       # Restore the state to the previous value on the stack.
       #
+      #: () -> untyped
       def restore_graphics_state
         @stack.pop
       end
@@ -118,7 +121,7 @@ class PDF::Reader
         @font_size ||= begin
                          _, zero = trm_transform(0,0)
                          _, one  = trm_transform(1,1)
-                         (zero - one).abs
+                         (zero - one).abs.round(10)
                        end
       end
 

data/lib/pdf/reader/page_text_receiver.rb

@@ -14,9 +14,13 @@ module PDF
     class PageTextReceiver
       extend Forwardable
 
-      SPACE = " "
+      SPACE = " " #: String
 
-      attr_reader :state, :options
+      #: untyped
+      attr_reader :state
+
+      #: untyped
+      attr_reader :options
 
       ########## BEGIN FORWARDERS ##########
       # Graphics State Operators

data/lib/pdf/reader/pages_strategy.rb

@@ -180,7 +180,7 @@ class PDF::Reader
       'y'   => :append_curved_segment_final_point_replicated,
       '\''  => :move_to_next_line_and_show_text,
       '"'   => :set_spacing_next_line_show_text,
-    }
+    } #: Hash[String, Symbol]
   end
   ################################################################################
 end

data/lib/pdf/reader/parser.rb

@@ -1,5 +1,5 @@
 # coding: utf-8
-# typed: true
+# typed: strict
 # frozen_string_literal: true
 
 ################################################################################
@@ -33,7 +33,7 @@ class PDF::Reader
   # them into useable ruby objects (hash's, arrays, true, false, etc)
   class Parser
 
-    TOKEN_STRATEGY = proc { |parser, token| Token.new(token) }
+    TOKEN_STRATEGY = proc { |parser, token| Token.new(token) } #: Proc
 
     STRATEGIES = {
       "/"  => proc { |parser, token| parser.send(:pdf_name) },
@@ -55,13 +55,14 @@ class PDF::Reader
       "]"         => TOKEN_STRATEGY,
       ">"         => TOKEN_STRATEGY,
       ")"         => TOKEN_STRATEGY
-    }
+    } #: Hash[String?, Proc]
 
     ################################################################################
     # Create a new parser around a PDF::Reader::Buffer object
     #
     # buffer - a PDF::Reader::Buffer object that contains PDF data
     # objects  - a PDF::Reader::ObjectHash object that can return objects from the PDF file
+    #: (PDF::Reader::Buffer, ?PDF::Reader::ObjectHash?) -> void
     def initialize(buffer, objects=nil)
       @buffer = buffer
       @objects  = objects
@@ -71,11 +72,24 @@ class PDF::Reader
     # object
     #
     # operators - a hash of supported operators to read from the underlying buffer.
+    #: (?Hash[String | PDF::Reader::Token, Symbol]) -> (
+    #|   PDF::Reader::Reference |
+    #|   PDF::Reader::Token |
+    #|   Numeric |
+    #|   String |
+    #|   Symbol |
+    #|   Array[untyped] |
+    #|   Hash[untyped, untyped] |
+    #|   nil
+    #| )
     def parse_token(operators={})
       token = @buffer.token
 
-      if STRATEGIES.has_key? token
-        STRATEGIES[token].call(self, token)
+      if token.nil?
+        nil
+      elsif token.is_a?(String) && STRATEGIES.has_key?(token)
+        proc = STRATEGIES[token]
+        proc.call(self, token) if proc
       elsif token.is_a? PDF::Reader::Reference
         token
       elsif operators.has_key? token
@@ -95,6 +109,17 @@ class PDF::Reader
     #
     # id  - the object ID to return
     # gen - the object revision number to return
+    #: (Integer, Integer) -> (
+    #|   PDF::Reader::Reference |
+    #|   PDF::Reader::Token |
+    #|   PDF::Reader::Stream |
+    #|   Numeric |
+    #|   String |
+    #|   Symbol |
+    #|   Array[untyped] |
+    #|   Hash[untyped, untyped] |
+    #|   nil
+    #| )
     def object(id, gen)
       idCheck = parse_token
 
@@ -120,6 +145,7 @@ class PDF::Reader
 
     ################################################################################
     # reads a PDF dict from the buffer and converts it to a Ruby Hash.
+    #: () -> Hash[Symbol, untyped]
     def dictionary
       dict = {}
 
@@ -138,15 +164,25 @@ class PDF::Reader
     end
     ################################################################################
     # reads a PDF name from the buffer and converts it to a Ruby Symbol
+    #: () -> Symbol
     def pdf_name
       tok = @buffer.token
-      tok = tok.dup.gsub(/#([A-Fa-f0-9]{2})/) do |match|
-        match[1, 2].hex.chr
+
+      if tok.is_a?(String)
+        tok = tok.dup.gsub(/#([A-Fa-f0-9]{2})/) do |match|
+          res = match[1, 2]
+          res ? res.hex.chr : ""
+        end
+        tok.to_sym
+      elsif tok.is_a?(PDF::Reader::Reference)
+        raise MalformedPDFError, "unexpected reference"
+      else
+        raise MalformedPDFError, "unexpected nil PDF Name"
       end
-      tok.to_sym
     end
     ################################################################################
     # reads a PDF array from the buffer and converts it to a Ruby Array.
+    #: () -> Array[untyped]
     def array
       a = []
 
@@ -161,6 +197,7 @@ class PDF::Reader
     end
     ################################################################################
     # Reads a PDF hex string from the buffer and converts it to a Ruby String
+    #: () -> String
     def hex_string
       str = "".dup
 
@@ -177,8 +214,11 @@ class PDF::Reader
     end
     ################################################################################
     # Reads a PDF String from the buffer and converts it to a Ruby String
+    #: () -> String
     def string
       str = @buffer.token
+      raise MalformedPDFError, "unexpected reference" if str.is_a?(PDF::Reader::Reference)
+      raise MalformedPDFError, "unexpected nil PDF String" if str.nil?
       return "".dup.force_encoding("binary") if str == ")"
       Error.assert_equal(parse_token, ")")
 
@@ -206,10 +246,11 @@ class PDF::Reader
       "\\\n" => "",
       "\\\r" => "",
       "\\\r\n" => "",
-    }
+    } #: Hash[String, String]
 
     ################################################################################
     # Decodes the contents of a PDF Stream and returns it as a Ruby String.
+    #: (Hash[Symbol, untyped]) -> PDF::Reader::Stream
     def stream(dict)
       raise MalformedPDFError, "PDF malformed, missing stream length" unless dict.has_key?(:Length)
       if @objects
@@ -231,7 +272,7 @@ class PDF::Reader
       # matter if it's missing, and other readers seems to handle its absence just fine
       # Error.str_assert(parse_token, "endobj")
 
-      PDF::Reader::Stream.new(dict, data)
+      PDF::Reader::Stream.new(dict, data || "")
     end
     ################################################################################
   end

data/lib/pdf/reader/point.rb

@@ -10,12 +10,19 @@ module PDF
     #
     class Point
 
-      attr_reader :x, :y
+      #: Numeric
+      attr_reader :x
 
+      #: Numeric
+      attr_reader :y
+
+      #: (Numeric, Numeric) -> void
       def initialize(x, y)
-        @x, @y = x, y
+        @x = x
+        @y = y
       end
 
+      #: (PDF::Reader::Point) -> bool
       def ==(other)
         other.respond_to?(:x) && other.respond_to?(:y) && x == other.x && y == other.y
       end

data/lib/pdf/reader/print_receiver.rb

@@ -8,16 +8,12 @@ class PDF::Reader
   #
   class PrintReceiver
 
-    attr_accessor :callbacks
-
-    def initialize
-      @callbacks = []
-    end
-
+    #: (untyped) -> bool
     def respond_to?(meth)
       true
     end
 
+    #: (Symbol, *untyped) -> void
     def method_missing(methodname, *args)
       puts "#{methodname} => #{args.inspect}"
     end

data/lib/pdf/reader/rc4_security_handler.rb

@@ -12,6 +12,7 @@ class PDF::Reader
   #
   class Rc4SecurityHandler
 
+    #: (String) -> void
     def initialize(key)
       @encrypt_key = key
     end
@@ -25,6 +26,7 @@ class PDF::Reader
     # buf - a string to decrypt
     # ref - a PDF::Reader::Reference for the object to decrypt
     #
+    #: (String, PDF::Reader::Reference) -> String
     def decrypt( buf, ref )
       objKey = @encrypt_key.dup
       (0..2).each { |e| objKey << (ref.id >> e*8 & 0xFF ) }

data/lib/pdf/reader/rectangle.rb

@@ -20,12 +20,28 @@ module PDF
     #
     class Rectangle
 
-      attr_reader :bottom_left, :bottom_right, :top_left, :top_right
+      #: PDF::Reader::Point
+      attr_reader :bottom_left
 
+      #: PDF::Reader::Point
+      attr_reader :bottom_right
+
+      #: PDF::Reader::Point
+      attr_reader :top_left
+
+      #: PDF::Reader::Point
+      attr_reader :top_right
+
+      #: (Numeric, Numeric, Numeric, Numeric) -> void
       def initialize(x1, y1, x2, y2)
+        @bottom_left = Point.new(0,0) #: PDF::Reader::Point
+        @bottom_right = Point.new(0,0) #: PDF::Reader::Point
+        @top_left = Point.new(0,0) #: PDF::Reader::Point
+        @top_right = Point.new(0,0) #: PDF::Reader::Point
         set_corners(x1, y1, x2, y2)
       end
 
+      #: (Array[Numeric]) -> PDF::Reader::Rectangle
       def self.from_array(arr)
         if arr.size != 4
           raise ArgumentError, "Only 4-element Arrays can be converted to a Rectangle"
@@ -39,24 +55,29 @@ module PDF
         )
       end
 
+      #: (PDF::Reader::Rectangle) -> bool
       def ==(other)
         to_a == other.to_a
       end
 
+      #: () -> Numeric
       def height
         top_right.y - bottom_right.y
       end
 
+      #: () -> Numeric
       def width
         bottom_right.x - bottom_left.x
       end
 
+      #: (PDF::Reader::Point) -> bool
       def contains?(point)
         point.x >= bottom_left.x && point.x <= top_right.x &&
           point.y >= bottom_left.y && point.y <= top_right.y
       end
 
       # A pdf-style 4-number array
+      #: () -> Array[Numeric]
       def to_a
         [
           bottom_left.x,
@@ -66,6 +87,7 @@ module PDF
         ]
       end
 
+      #: (Integer) -> void
       def apply_rotation(degrees)
         return if degrees != 90 && degrees != 180 && degrees != 270
 
@@ -90,6 +112,7 @@ module PDF
 
       private
 
+      #: (Numeric, Numeric, Numeric, Numeric) -> void
       def set_corners(x1, y1, x2, y2)
         @bottom_left = PDF::Reader::Point.new(
           [x1, x2].min,