pdf-reader 2.9.2 → 2.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc98ab07b3c66f13f663ea5faf8132b45d769912e0da737917dd054e38318ede
-  data.tar.gz: 0f2928d9778b5b3ea8fca5e723a2b3fa6f275df70b02f1eb4385e077c535ac78
+  metadata.gz: 1be615eb6abc5557e61ba53958c7211fac0f1528e75dc54eff27ffb5554d7c80
+  data.tar.gz: 875221f31dc119cd0f7ae3cc0246b3bbb70f6127c0047ec924c8030e9186b55b
 SHA512:
-  metadata.gz: 210cd8c8cef93b0e0fac1446c091c2a62772ffe8b1786627089e5a330ca7defd501df7cccc0b48d326d38ff74318b162e512220e8a4460260bebe7da0ef8b757
-  data.tar.gz: 047e7f6641411557b1d3b50035dbdf55647c63deede273b6ce4442230b85372045494b81e88c1ffcaa09a7c5ea26823ee33b33c3bf82013328d0e32a95021284
+  metadata.gz: 4b4501ca72d06b5a569fdcc77f384131fbd85342f8da7a084a02210ec7a3821e8b9f1cad88685262d0cc4e993f7b0031bed5d510c353c7d8fb5fe28f97a2ea83
+  data.tar.gz: a4fe329f2d8ae7cc295cb17d573963ddab6c0cde52d6524ad182f4651dab8ba90215bcb1ecf60c7fcf248135aed152b50a1d34afa03b270b93c5a172ac4048b3

data/CHANGELOG

@@ -1,3 +1,42 @@
+v2.15.0 (13th August 2025)
+
+- Overhaul sorbet types, moving from an external RBI file to inline comments in RBS syntax
+  - multiple PRs, but mainly https://github.com/yob/pdf-reader/pull/562
+  - See https://railsatscale.com/2025-04-23-rbs-support-for-sorbet/
+  - No impact expected for most users, but projects that use sorbet may find subtle changes in
+    the RBI file that is shipped with the gem
+- Relax version requirements for dependency `afm`, allow 1.x (https://github.com/yob/pdf-reader/pull/557)
+- Improve text positioning logic in some PDFs (https://github.com/yob/pdf-reader/pull/554)
+- Multiple fixes for encrypted files
+  - Some files with passwords > 32 bytes long (https://github.com/yob/pdf-reader/pull/555)
+  - Some files that contain cipher text with a 16 byte IV and no further blocks (https://github.com/yob/pdf-reader/pull/561)
+  - Some files that encrypted data with no padding (https://github.com/yob/pdf-reader/pull/564)
+- Add jruby 10 to CI matrix (https://github.com/yob/pdf-reader/pull/552)
+
+v2.14.1 (4th February 2025)
+- Fix issue in RBI signatures, introduced in v2.14.0(https://github.com/yob/pdf-reader/pull/550)
+
+v2.14.0 (29th January 2025)
+- Raise minimum supported ruby to 2.1 (https://github.com/yob/pdf-reader/pull/543)
+- Add support for filtering to Page#text (https://github.com/yob/pdf-reader/pull/545)
+
+v2.13.0 (2nd November 2024)
+- Permit Ascii86 v1.0 and v2.0 (https://github.com/yob/pdf-reader/pull/539)
+- Allow StringIO type for PDF::Reader input (https://github.com/yob/pdf-reader/pull/535)
+
+v2.12.0 (26th December 2023)
+- Fix a sorbet method signature (http://github.com/yob/pdf-reader/pull/512)
+- Reduce allocations when parsing PDFs with hex strings (http://github.com/yob/pdf-reader/pull/528)
+- Fix text extraction of some rare unicode codepoints (http://github.com/yob/pdf-reader/pull/529)
+
+v2.11.0 (26th October 2022)
+- Various bug fixes
+- Expanded sorbet type annotations
+
+v2.10.0 (12th May 2022)
+- Various bug fixes
+- Expanded sorbet type annotations
+
 v2.9.2 (20th February 2022)
 - Fix PDF::Reader::ObjectHash#page_references to return an Array of PDF::Reader::Reference (http://github.com/yob/pdf-reader/pull/444)
 

data/README.md

@@ -20,7 +20,7 @@ page.
 The recommended installation method is via Rubygems.
 
 ```ruby
-  gem install pdf-reader
+gem install pdf-reader
 ```
 
 # Usage
@@ -30,23 +30,23 @@ level information (metadata, page count, bookmarks, etc) is available via
 this object.
 
 ```ruby
-    reader = PDF::Reader.new("somefile.pdf")
+reader = PDF::Reader.new("somefile.pdf")
 
-    puts reader.pdf_version
-    puts reader.info
-    puts reader.metadata
-    puts reader.page_count
+puts reader.pdf_version
+puts reader.info
+puts reader.metadata
+puts reader.page_count
  ```
 
 PDF::Reader.new accepts an IO stream or a filename. Here's an example with
 an IO stream:
 
 ```ruby
-    require 'open-uri'
+require 'open-uri'
 
-    io     = open('http://example.com/somefile.pdf')
-    reader = PDF::Reader.new(io)
-    puts reader.info
+io     = open('http://example.com/somefile.pdf')
+reader = PDF::Reader.new(io)
+puts reader.info
  ```
 
 If you open a PDF with File#open or IO#open, I strongly recommend using "rb"
@@ -54,47 +54,47 @@ mode to ensure the file isn't mangled by ruby being 'helpful'. This is
 particularly important on windows and MRI >= 1.9.2.
 
 ```ruby
-    File.open("somefile.pdf", "rb") do |io|
-      reader = PDF::Reader.new(io)
-      puts reader.info
-    end
+File.open("somefile.pdf", "rb") do |io|
+  reader = PDF::Reader.new(io)
+  puts reader.info
+end
  ```
 
 PDF is a page based file format, so most visible information is available via
 page-based iteration
 
 ```ruby
-    reader = PDF::Reader.new("somefile.pdf")
+reader = PDF::Reader.new("somefile.pdf")
 
-    reader.pages.each do |page|
-      puts page.fonts
-      puts page.text
-      puts page.raw_content
-    end
+reader.pages.each do |page|
+  puts page.fonts
+  puts page.text
+  puts page.raw_content
+end
 ```
 
 If you need to access the full program for rendering a page, use the walk() method
 of PDF::Reader::Page.
 
 ```ruby
-    class RedGreenBlue
-      def set_rgb_color_for_nonstroking(r, g, b)
-        puts "R: #{r}, G: #{g}, B: #{b}"
-      end
-    end
-
-    reader   = PDF::Reader.new("somefile.pdf")
-    page     = reader.page(1)
-    receiver = RedGreenBlue.new
-    page.walk(receiver)
+class RedGreenBlue
+  def set_rgb_color_for_nonstroking(r, g, b)
+    puts "R: #{r}, G: #{g}, B: #{b}"
+  end
+end
+
+reader   = PDF::Reader.new("somefile.pdf")
+page     = reader.page(1)
+receiver = RedGreenBlue.new
+page.walk(receiver)
 ```
 
 For low level access to the objects in a PDF file, use the ObjectHash class like
 so:
 
 ```ruby
-    reader  = PDF::Reader.new("somefile.pdf")
-    puts reader.objects.inspect
+reader  = PDF::Reader.new("somefile.pdf")
+puts reader.objects.inspect
 ```
 
 # Text Encoding
@@ -141,7 +141,7 @@ the spec folder when you checkout a branch from Git.
 To remove any invalid CRLF characters added while checking out a branch from Git, run:
 
 ```ruby
-    rake fix_integrity
+rake fix_integrity
 ```
 
 # Maintainers

data/Rakefile

@@ -14,7 +14,7 @@ desc "Run cane to check quality metrics"
 Cane::RakeTask.new(:quality) do |cane|
   cane.abc_max = 20
   cane.style_measure = 100
-  cane.max_violations = 28
+  cane.max_violations = 33
 
   cane.use Morecane::EncodingCheck, :encoding_glob => "{app,lib,spec}/**/*.rb"
 end
@@ -41,7 +41,7 @@ end
 desc "Create a YAML file of integrity info for PDFs in the spec suite"
 task :integrity_yaml do
   data = {}
-  Dir.glob("spec/data/**/*.*").sort.each do |path|
+  Dir.glob("spec/data/**/*.pdf").sort.each do |path|
     path_without_spec = path.gsub("spec/","")
     data[path_without_spec] = {
       :bytes => File.size(path),

data/lib/pdf/reader/advanced_text_run_filter.rb

@@ -0,0 +1,152 @@
+# coding: utf-8
+# frozen_string_literal: true
+# typed: strict
+
+class PDF::Reader
+  # Filter a collection of TextRun objects based on a set of conditions.
+  # It can be used to filter text runs based on their attributes.
+  # The filter can return the text runs that matches the conditions (only) or
+  # the text runs that do not match the conditions (exclude).
+  #
+  # You can filter the text runs based on all its attributes with the operators
+  # mentioned in VALID_OPERATORS.
+  # The filter can be nested with 'or' and 'and' conditions.
+  #
+  # Examples:
+  # 1. Single condition
+  # AdvancedTextRunFilter.exclude(text_runs, text: { include: 'sample' })
+  #
+  # 2. Multiple conditions (and)
+  # AdvancedTextRunFilter.exclude(text_runs, {
+  #   font_size: { greater_than: 10, less_than: 15 }
+  # })
+  #
+  # 3. Multiple possible values (or)
+  # AdvancedTextRunFilter.exclude(text_runs, {
+  #  font_size: { equal: [10, 12] }
+  # })
+  #
+  # 4. Complex AND/OR filter
+  # AdvancedTextRunFilter.exclude(text_runs, {
+  #   and: [
+  #     { font_size: { greater_than: 10 } },
+  #     { or: [
+  #       { text: { include: "sample" } },
+  #       { width: { greater_than: 100 } }
+  #     ]}
+  #   ]
+  # })
+  class AdvancedTextRunFilter
+    VALID_OPERATORS = %i[
+      equal
+      not_equal
+      greater_than
+      less_than
+      greater_than_or_equal
+      less_than_or_equal
+      include
+      exclude
+    ] #: Array[Symbol]
+
+    #: (Array[PDF::Reader::TextRun], Hash[Symbol, untyped]) -> Array[PDF::Reader::TextRun]
+    def self.only(text_runs, filter_hash)
+      new(text_runs, filter_hash).only
+    end
+
+    #: (Array[PDF::Reader::TextRun], Hash[Symbol, untyped]) -> Array[PDF::Reader::TextRun]
+    def self.exclude(text_runs, filter_hash)
+      new(text_runs, filter_hash).exclude
+    end
+
+    #: Array[PDF::Reader::TextRun]
+    attr_reader :text_runs
+
+    #: Hash[Symbol, untyped]
+    attr_reader :filter_hash
+
+    #: (Array[PDF::Reader::TextRun], Hash[Symbol, untyped]) -> void
+    def initialize(text_runs, filter_hash)
+      @text_runs = text_runs
+      @filter_hash = filter_hash
+    end
+
+    #: () -> Array[PDF::Reader::TextRun]
+    def only
+      return text_runs if filter_hash.empty?
+      text_runs.select { |text_run| evaluate_filter(text_run) }
+    end
+
+    #: () -> Array[PDF::Reader::TextRun]
+    def exclude
+      return text_runs if filter_hash.empty?
+      text_runs.reject { |text_run| evaluate_filter(text_run) }
+    end
+
+    private
+
+    #: (PDF::Reader::TextRun) -> bool
+    def evaluate_filter(text_run)
+      if filter_hash[:or]
+        evaluate_or_filters(text_run, filter_hash[:or])
+      elsif filter_hash[:and]
+        evaluate_and_filters(text_run, filter_hash[:and])
+      else
+        evaluate_filters(text_run, filter_hash)
+      end
+    end
+
+    #: (PDF::Reader::TextRun, Array[Hash[Symbol, untyped]]) -> bool
+    def evaluate_or_filters(text_run, conditions)
+      conditions.any? do |condition|
+        evaluate_filters(text_run, condition)
+      end
+    end
+
+    #: (PDF::Reader::TextRun, Array[Hash[Symbol, untyped]]) -> bool
+    def evaluate_and_filters(text_run, conditions)
+      conditions.all? do |condition|
+        evaluate_filters(text_run, condition)
+      end
+    end
+
+    #: (PDF::Reader::TextRun, Hash[Symbol, untyped]) -> bool
+    def evaluate_filters(text_run, filter_hash)
+      filter_hash.all? do |attribute, conditions|
+        evaluate_attribute_conditions(text_run, attribute, conditions)
+      end
+    end
+
+    #: (PDF::Reader::TextRun, Symbol, Hash[Symbol, untyped]) -> bool
+    def evaluate_attribute_conditions(text_run, attribute, conditions)
+      conditions.all? do |operator, value|
+        unless VALID_OPERATORS.include?(operator)
+          raise ArgumentError, "Invalid operator: #{operator}"
+        end
+
+        apply_operator(text_run.send(attribute), operator, value)
+      end
+    end
+
+    #: (untyped, Symbol, untyped) -> bool
+    def apply_operator(attribute_value, operator, filter_value)
+      case operator
+      when :equal
+        Array(filter_value).include?(attribute_value)
+      when :not_equal
+        !Array(filter_value).include?(attribute_value)
+      when :greater_than
+        attribute_value > filter_value
+      when :less_than
+        attribute_value < filter_value
+      when :greater_than_or_equal
+        attribute_value >= filter_value
+      when :less_than_or_equal
+        attribute_value <= filter_value
+      when :include
+        Array(filter_value).any? { |v| attribute_value.to_s.include?(v.to_s) }
+      when :exclude
+        Array(filter_value).none? { |v| attribute_value.to_s.include?(v.to_s) }
+      end
+    end
+  end
+end

data/lib/pdf/reader/aes_v2_security_handler.rb

@@ -11,6 +11,7 @@ class PDF::Reader
   #
   class AesV2SecurityHandler
 
+    #: (String) -> void
     def initialize(key)
       @encrypt_key = key
     end
@@ -21,10 +22,38 @@ class PDF::Reader
     #
     # version == 4 and CFM == AESV2
     #
+    # used to decrypt PDF streams (buf). Input data should be in bytesizes of
+    # a multiple of 16, anything else is an error. The first 16 bytes are the initialization
+    # vector, so any input of exactly 16 bytes decrypts to an empty string
+    #
     # buf - a string to decrypt
     # ref - a PDF::Reader::Reference for the object to decrypt
     #
+    #: (String, PDF::Reader::Reference) -> String
     def decrypt( buf, ref )
+      if buf.bytesize % 16 > 0
+        raise PDF::Reader::MalformedPDFError.new("Ciphertext not a multiple of 16")
+      elsif buf.bytesize == 16
+        return ""
+      else
+        begin
+          internal_decrypt(buf, ref)
+        rescue OpenSSL::Cipher::CipherError
+          # If we failed to decrypt it might be a padding error, so try again
+          # and assume no padding in the ciphertext. This will "suceed" but might
+          # return garbage if the key is incorrect but that's OK - well before this
+          # class is used we have confirmed the user provided key is correct so if
+          # this works without error we can be confident the returned plaintext is
+          #  correct
+          internal_decrypt(buf, ref, false)
+        end
+      end
+    end
+
+    private
+
+    #: (String, PDF::Reader::Reference, ?bool) -> String
+    def internal_decrypt(buf, ref, padding = true)
       objKey = @encrypt_key.dup
       (0..2).each { |e| objKey << (ref.id >> e*8 & 0xFF ) }
       (0..1).each { |e| objKey << (ref.gen >> e*8 & 0xFF ) }
@@ -32,6 +61,7 @@ class PDF::Reader
       length = objKey.length < 16 ? objKey.length : 16
       cipher = OpenSSL::Cipher.new("AES-#{length << 3}-CBC")
       cipher.decrypt
+      cipher.padding = 0 unless padding
       cipher.key = Digest::MD5.digest(objKey)[0,length]
       cipher.iv = buf[0..15]
       cipher.update(buf[16..-1]) + cipher.final

data/lib/pdf/reader/aes_v3_security_handler.rb

@@ -12,27 +12,59 @@ class PDF::Reader
   #
   class AesV3SecurityHandler
 
+    #: (String) -> void
     def initialize(key)
+      if key.bytesize != 32
+        raise PDF::Reader::MalformedPDFError.new(
+          "AES-256 key must be exactly 32 bytes, got #{key.bytesize}"
+        )
+      end
       @encrypt_key = key
-      @cipher = "AES-256-CBC"
+      @cipher = "AES-256-CBC" #: String
     end
 
     ##7.6.2 General Encryption Algorithm
     #
     # Algorithm 1: Encryption of data using the RC4 or AES algorithms
     #
-    # used to decrypt RC4/AES encrypted PDF streams (buf)
+    # used to decrypt RC4/AES encrypted PDF streams (buf). Input data should be in bytesizes of
+    # a multiple of 16, anything else is an error. The first 16 bytes are the initialization
+    # vector, so any input of exactly 16 bytes decrypts to an empty string
     #
     # buf - a string to decrypt
     # ref - a PDF::Reader::Reference for the object to decrypt
     #
+    #: (String, PDF::Reader::Reference) -> String
     def decrypt( buf, ref )
+      if buf.bytesize % 16 > 0
+        raise PDF::Reader::MalformedPDFError.new("Ciphertext not a multiple of 16")
+      elsif buf.bytesize == 16
+        return ""
+      else
+        begin
+          internal_decrypt(buf, ref)
+        rescue OpenSSL::Cipher::CipherError
+          # If we failed to decrypt it might be a padding error, so try again
+          # and assume no padding in the ciphertext. This will "suceed" but might
+          # return garbage if the key is incorrect but that's OK - well before this
+          # class is used we have confirmed the user provided key is correct so if
+          # this works without error we can be confident the returned plaintext is
+          #  correct
+         internal_decrypt(buf, ref, false)
+        end
+      end
+    end
+
+    private
+
+    #: (String, PDF::Reader::Reference, ?bool) -> String
+    def internal_decrypt(buf, ref, padding = true)
       cipher = OpenSSL::Cipher.new(@cipher)
       cipher.decrypt
+      cipher.padding = 0 unless padding
       cipher.key = @encrypt_key.dup
       cipher.iv = buf[0..15]
       cipher.update(buf[16..-1]) + cipher.final
     end
-
   end
 end

data/lib/pdf/reader/bounding_rectangle_runs_filter.rb

@@ -8,6 +8,7 @@ class PDF::Reader
   # MediaBox or CropBox, but could be a user specified rectangle too
   class BoundingRectangleRunsFilter
 
+    #: (Array[PDF::Reader::TextRun], PDF::Reader::Rectangle) -> Array[PDF::Reader::TextRun]
     def self.runs_within_rect(runs, rect)
       runs.select { |run| rect.contains?(run.origin) }
     end

data/lib/pdf/reader/buffer.rb

@@ -1,5 +1,5 @@
 # coding: ASCII-8BIT
-# typed: true
+# typed: strict
 # frozen_string_literal: true
 
 ################################################################################
@@ -38,30 +38,31 @@ class PDF::Reader
   # the raw tokens into objects we can work with (strings, ints, arrays, etc)
   #
   class Buffer
-    TOKEN_WHITESPACE=[0x00, 0x09, 0x0A, 0x0C, 0x0D, 0x20]
-    TOKEN_DELIMITER=[0x25, 0x3C, 0x3E, 0x28, 0x5B, 0x7B, 0x29, 0x5D, 0x7D, 0x2F]
+    TOKEN_WHITESPACE=[0x00, 0x09, 0x0A, 0x0C, 0x0D, 0x20] #: Array[Integer]
+    TOKEN_DELIMITER=[0x25, 0x3C, 0x3E, 0x28, 0x5B, 0x7B, 0x29, 0x5D, 0x7D, 0x2F] #: Array[Integer]
 
     # some strings for comparissons. Declaring them here avoids creating new
     # strings that need GC over and over
-    LEFT_PAREN = "("
-    LESS_THAN = "<"
-    STREAM = "stream"
-    ID = "ID"
-    FWD_SLASH = "/"
-    NULL_BYTE = "\x00"
-    CR = "\r"
-    LF = "\n"
-    CRLF = "\r\n"
-    WHITE_SPACE = [LF, CR, ' ']
+    LEFT_PAREN = "(" #: String
+    LESS_THAN = "<" #: String
+    STREAM = "stream" #: String
+    ID = "ID" #: String
+    FWD_SLASH = "/" #: String
+    NULL_BYTE = "\x00" #: String
+    CR = "\r" #: String
+    LF = "\n" #: String
+    CRLF = "\r\n" #: String
+    WHITE_SPACE = ["\n", "\r", ' '] #: Array[String]
 
     # Quite a few PDFs have trailing junk.
     # This can be several k of nuls in some cases
     # Allow for this here
-    TRAILING_BYTECOUNT = 5000
+    TRAILING_BYTECOUNT = 5000 #: Integer
 
     # must match whole tokens
-    DIGITS_ONLY = %r{\A\d+\z}
+    DIGITS_ONLY = %r{\A\d+\z} #: Regexp
 
+    #: Integer
     attr_reader :pos
 
     # Creates a new buffer.
@@ -76,17 +77,19 @@ class PDF::Reader
     #   :content_stream - set to true if buffer will be tokenising a
     #                     content stream. Defaults to false
     #
+    #: ((StringIO | Tempfile | IO), ?Hash[Symbol, untyped]) -> void
     def initialize(io, opts = {})
       @io = io
-      @tokens = []
-      @in_content_stream = opts[:content_stream]
+      @tokens = [] #: Array[String | PDF::Reader::Reference]
+      @in_content_stream = opts[:content_stream] #: bool
 
       @io.seek(opts[:seek]) if opts[:seek]
-      @pos = @io.pos
+      @pos = @io.pos #: Integer
     end
 
     # return true if there are no more tokens left
     #
+    #: () -> bool
     def empty?
       prepare_tokens if @tokens.size < 3
 
@@ -105,6 +108,7 @@ class PDF::Reader
     #   Skipping a bare CR is not spec-compliant.
     #   This is because the data may start with LF.
     #   However we check for CRLF first, so the ambiguity is avoided.
+    #: (Integer, ?Hash[Symbol, untyped]) -> String?
     def read(bytes, opts = {})
       reset_pos
 
@@ -130,6 +134,7 @@ class PDF::Reader
     # return the next token from the source. Returns a string if a token
     # is found, nil if there are no tokens left.
     #
+    #: () -> (nil | String | PDF::Reader::Reference)
     def token
       reset_pos
       prepare_tokens if @tokens.size < 3
@@ -141,6 +146,7 @@ class PDF::Reader
 
     # return the byte offset where the first XRef table in th source can be found.
     #
+    #: () -> Integer
     def find_first_xref_offset
       check_size_is_non_zero
       @io.seek(-TRAILING_BYTECOUNT, IO::SEEK_END) rescue @io.seek(0)
@@ -164,6 +170,7 @@ class PDF::Reader
 
     private
 
+    #: () -> void
     def check_size_is_non_zero
       @io.seek(-1, IO::SEEK_END)
       @io.seek(0)
@@ -173,12 +180,14 @@ class PDF::Reader
 
     # Returns true if this buffer is parsing a content stream
     #
+    #: () -> bool
     def in_content_stream?
       @in_content_stream ? true : false
     end
 
     # Some bastard moved our IO stream cursor. Restore it.
     #
+    #: () -> void
     def reset_pos
       @io.seek(@pos) if @io.pos != @pos
     end
@@ -186,12 +195,14 @@ class PDF::Reader
     # save the current position of the source IO stream. If someone else (like another buffer)
     # moves the cursor, we can then restore it.
     #
+    #: () -> void
     def save_pos
       @pos = @io.pos
     end
 
     # attempt to prime the buffer with the next few tokens.
     #
+    #: () -> void
     def prepare_tokens
       10.times do
         case state
@@ -208,6 +219,7 @@ class PDF::Reader
     # tokenising behaves slightly differently based on the current context.
     # Determine the current context/state by examining the last token we found
     #
+    #: () -> Symbol
     def state
       case @tokens.last
       when LEFT_PAREN then :literal_string
@@ -236,6 +248,7 @@ class PDF::Reader
     # indirect reference, so test for that case first and avoid the relatively
     # expensive regexp checks if possible.
     #
+    #: () -> void
     def merge_indirect_reference
       return if @tokens.size < 3
       return if @tokens[2] != "R"
@@ -253,6 +266,7 @@ class PDF::Reader
     # If the EI follows white-space the space is dropped from the data
     # The EI must followed by white-space or end of buffer
     # This is to reduce the chance of accidentally matching an embedded EI
+    #: () -> void
     def prepare_inline_token
       idstart = @io.pos
       prevchr = ''
@@ -299,14 +313,14 @@ class PDF::Reader
     # if we're currently inside a hex string, read hex nibbles until
     # we find a closing >
     #
+    #: () -> void
     def prepare_hex_token
-      finished = :false
       str = "".dup
 
-      until finished == :true
+      loop do
         byte = @io.getbyte
         if byte.nil?
-          finished = :true # unbalanced params
+          break
         elsif (48..57).include?(byte) || (65..90).include?(byte) || (97..122).include?(byte)
           str << byte
         elsif byte <= 32
@@ -315,7 +329,7 @@ class PDF::Reader
           @tokens << str if str.size > 0
           @tokens << ">" if byte != 0x3E # '>'
           @tokens << byte.chr
-          finished = :true
+          break
         end
       end
     end
@@ -329,6 +343,7 @@ class PDF::Reader
     # processing to fix things like escaped new lines, but that's someone else's
     # problem.
     #
+    #: () -> void
     def prepare_literal_token
       str = "".dup
       count = 1
@@ -359,6 +374,7 @@ class PDF::Reader
     # What each byte means is complex, check out section "3.1.1 Character Set" of the 1.7 spec
     # to read up on it.
     #
+    #: () -> void
     def prepare_regular_token
       tok = "".dup
 
@@ -436,6 +452,7 @@ class PDF::Reader
     # peek at the next character in the io stream, leaving the stream position
     # untouched
     #
+    #: () -> (Integer | nil)
     def peek_byte
       byte = @io.getbyte
       @io.seek(-1, IO::SEEK_CUR) if byte