qr_reader 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 676cc0ecf84f68ef07fc1b05b6c473c301eb4b82ee8ab615dc30bb036030834f
-  data.tar.gz: c7b893b1828be74bb1f4feed942b325b34b8183dc7c318919fb891f84b64b24d
+  metadata.gz: 95bfd13bd094f9f117def4165ec4af69923fff4c6b45dde7140a633ecf3fd092
+  data.tar.gz: 33b8813834b0bffb325c3951948db515d7a2108f55e0487becfd63e20bf33fd5
 SHA512:
-  metadata.gz: '095f7dead62ad0f612d662155e30f2ff11b8b5120d8e74114f8ea55fca78286e5609994794e69b596f055b1c52cb101607ad36ad1434536505428e48c94ee2a1'
-  data.tar.gz: f9b0da7897ad79f9162f1e16fafc592d36421dab0521354110685a9f9e11a57720ec8e9173915b969f023d6c9a37fdd2cf68f14db018c3c304b0f5c552540304
+  metadata.gz: 3341a29636745a3fe5712e9e3c402b77eae8c4f56ee8fef45a40f2c65e1e4b8c86974e59a18a29c9142f2925ab3643d647c70089a0fbe5cbb7440c35fb956c78
+  data.tar.gz: 4790cd51e562e400bdb0e4ef080883ff36505412797447b39b0d8c00e575c42ea7cd4190f7725cd82a70849f5b8ead9f40f5af5bc482ee8025bd578b2b1880d3

data/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 ## [Unreleased]
 
+## [0.0.3] - 2026-10-16
+
+- **Breaking:** a `String` input is always a file path, never image data;
+  pass image bytes as an IO (`QrReader.decode(StringIO.new(bytes))`, or the
+  upload's `Tempfile` directly), like `File.read` and `PDF::Reader.new`.
+  Before, Strings were sniffed: bytes that spelled the path of an existing
+  file (e.g. an uploaded "image" containing `/etc/...` or the path of a
+  server-side image with a QR code) were read from disk, and the error for
+  unrecognised data echoed the file's first bytes. A `String` that looks like
+  image data now raises `ArgumentError` with that hint.
+- PDF: a document that draws no image and no code-like vector group (e.g. a
+  text-only invoice page) has no codes: `decode_all` returns `[]` and
+  `decode` `nil` instead of raising `UnsupportedImageError` "PDF contains no
+  raster images". PDFs whose images all fail to decode still raise.
+- PDF: data behind a `%PDF-` header without a page tree raises `ImageError`
+  "corrupt PDF (no pages found)" instead of "PDF contains no raster images".
+- ruby.wasm: PNG and PDF (Flate) images no longer crash the VM ("null
+  function or function signature mismatch"). Zlib is no longer called with a
+  block, because Ruby code that allocates inside zlib's callback crashes
+  ruby.wasm; data is inflated in 16 KB slices instead.
+- TruffleRuby: Shift_JIS (Kanji) and EUC-KR payloads are converted correctly;
+  `String#encode` on the whole text mis-converted some of them there (and
+  could raise on Shift_JIS). They are converted one character at a time,
+  with the same result as before on MRI.
+- JRuby: `Decoder.diagnose` no longer raises `TypeError` when no attempt
+  succeeds.
+- `QrReader.read!`: like `read`, but raises `NotFoundError` when no code is
+  found (the `Result` counterpart of `decode!`).
+- qr_reader-native: the check that the native kernels were built from the
+  same sources now compares code tokens, not file bytes, so comments and
+  layout in the kernel files no longer switch the native kernels off.
+- Releases (qr_reader and qr_reader-native) are signed with Sigstore and
+  pushed with their attestations, so RubyGems.org shows their provenance.
+- Tested on JRuby 10 and TruffleRuby 25 as well as MRI 3.2–4.0; the tests'
+  time limits are scaled on JRuby and TruffleRuby (JIT warmup).
+
 ## [0.0.2] - 2026-10-13
 
 - JPEG 2000: pure-Ruby decoder for all of Part 1 (`Formats::JPEG2000`), used

data/README.md

@@ -21,6 +21,9 @@ code.points          # => [[x, y], ...] corners: top-left, top-right, bottom-rig
 QrReader.scan("scans.tiff") do |code|  # lazily, page by page
   puts "page #{code.page}: #{code.text}"
 end
+
+QrReader.decode(params[:file].tempfile)  # an upload: any IO works
+QrReader.decode(StringIO.new(bytes))     # image bytes you already hold
 ```
 
 ## Installation
@@ -34,6 +37,10 @@ no native libraries — it also runs on Rubies without C extensions. Enable YJIT
 for the best speed (`RUBY_YJIT_ENABLE=1`, `ruby --yjit`, or
 `RubyVM::YJIT.enable` at boot).
 
+It runs on every major Ruby implementation. The full test suite passes on MRI
+(CRuby) 3.2, 3.3, 3.4 and 4.0, JRuby 10 and TruffleRuby 25, and ruby.wasm
+(Ruby 4.0) decodes PNGs and PDFs.
+
 ### Optional: native kernels (qr_reader-native)
 
 The hot loops (image decoding, binarization, pattern scanning) are written as
@@ -52,19 +59,27 @@ without the gem — or with `QR_READER_NATIVE=0` — the same code runs as Ruby.
 
 ## Usage
 
+The `decode` methods return the text of a code; the `read` methods return a
+`QrReader::Result` with the text plus metadata (version, position, page, ...).
+
 | method | returns |
 |---|---|
 | `QrReader.decode(input)` | text of the first code, or `nil` |
 | `QrReader.decode!(input)` | text of the first code, or raises `QrReader::NotFoundError` |
 | `QrReader.decode_all(input)` | texts of all codes (all pages) |
 | `QrReader.read(input)` | first code as a `QrReader::Result`, or `nil` |
+| `QrReader.read!(input)` | first code as a `QrReader::Result`, or raises `QrReader::NotFoundError` |
 | `QrReader.read_all(input)` | all codes as `QrReader::Result`s |
 | `QrReader.scan(input) { \|result\| }` | yields codes as they are found; an `Enumerator` without a block |
 
-`input` can be a file path (`String` or `Pathname`), an `IO`, a binary
-`String` with the encoded image, a `QrReader::Image`, or any object with
-`width`, `height` and `pixels` (e.g. a `ChunkyPNG::Image`). Raw pixel buffers
-can be wrapped with `QrReader::Image.from_pixels(width, height, bytes, :rgba)`
+`input` can be a file path (`String` or `Pathname`), an `IO` with the encoded
+image (a `File`, an upload's `Tempfile`, `StringIO.new(bytes)`), a
+`QrReader::Image`, or any object with `width`, `height` and `pixels` (e.g. a
+`ChunkyPNG::Image`). As with `File.read` or `PDF::Reader.new`, a `String` is
+always a path and never image data: image bytes go in as an IO. A `String`
+that looks like image data raises `ArgumentError` instead of being guessed at,
+so bytes from a client can never be taken for a path on the server. Raw pixel
+buffers can be wrapped with `QrReader::Image.from_pixels(width, height, bytes, :rgba)`
 (also `:rgb`, `:bgr`, `:bgra`, `:gray`, ...).
 
 Options (for every method, and `QrReader::Reader.new` for reuse):
@@ -86,9 +101,11 @@ A `QrReader::Result` is an immutable `Data` object:
 | `mirrored?`, `errors_corrected` | read mirrored? / number of repaired codewords |
 | `eci`, `segments`, `structured_append`, `fnc1`, `symbology_identifier` | encoding details |
 
-Errors: `QrReader::ImageError` (unreadable image data),
-`QrReader::UnsupportedImageError` (e.g. WebP, HEIC, encrypted PDF),
-`Errno::ENOENT` for missing files.
+Errors: `QrReader::ImageError` (unreadable image data, corrupt PDF),
+`QrReader::UnsupportedImageError` (e.g. WebP, HEIC, encrypted PDF, a PDF
+whose images all fail to decode), `Errno::ENOENT` for missing files, `ArgumentError` for image bytes passed
+as a `String` (use `StringIO.new(bytes)`). A PDF that draws nothing that could
+be a code (a text-only page) is not an error: it just has no codes.
 
 ### Command line
 
@@ -217,13 +234,16 @@ SPINEL_HOME=~/workspace/spinel bundle exec rake native:generate
 bundle exec rake native:compile native:test
 ```
 
-CI fails when the generated sources are out of date.
+CI fails when the generated sources are out of date. Only code counts:
+comments, blank lines and spacing in the kernel files can change without
+regenerating.
 
 ### Releasing
 
 Releases are published from GitHub Actions with RubyGems
 [trusted publishing](https://guides.rubygems.org/trusted-publishing/) — no API
-key is stored anywhere. One tag releases both gems, qr_reader and
+key is stored anywhere — and each gem carries a Sigstore attestation, so
+RubyGems.org shows which repository, workflow and commit built it. One tag releases both gems, qr_reader and
 qr_reader-native, at the same version. Bump `QrReader::VERSION`, update
 `CHANGELOG.md`, then:
 

data/exe/qr_reader

@@ -31,7 +31,7 @@ end
 status = 0
 reader = QrReader::Reader.new(try_harder: options[:try_harder], inverted: options[:inverted])
 files.each do |file|
-  input = file == "-" ? $stdin.binmode.read : file
+  input = file == "-" ? $stdin.binmode : file
   results = begin
     options[:all] ? reader.read_all(input) : [reader.read(input)].compact
   rescue QrReader::Error, SystemCallError => e

data/lib/qr_reader/decoder/character_set.rb

@@ -87,7 +87,9 @@ module QrReader
           # Windows-31J one by one, so the rest keep their JIS X 0208 mapping.
           # Ruby maps 0x815C to U+2014 EM DASH; ZXing and zxing-cpp (like
           # Unicode's SHIFTJIS.TXT and Windows-31J) to U+2015 HORIZONTAL BAR.
-          bytes.encode(UTF_8, SHIFT_JIS, invalid: :replace, fallback: WINDOWS_31J_FALLBACK).tr("\u2014", "\u2015")
+          by_char(bytes, SHIFT_JIS, WINDOWS_31J_FALLBACK).tr("\u2014", "\u2015")
+        when Encoding::EUC_KR
+          by_char(bytes, Encoding::EUC_KR)
         when GB18030
           # Ruby uses the GB 18030-2000 private-use mappings for 11 GBK codes
           # that GB 18030-2005 (and zxing-cpp) map to standard characters.
@@ -100,6 +102,22 @@ module QrReader
         end
       end
 
+      # Converts +bytes+ to UTF-8 one character at a time; invalid characters
+      # become U+FFFD, characters +encoding+ cannot map go to +fallback+ (or
+      # U+FFFD). For Shift_JIS and EUC-KR this gives exactly what String#encode
+      # with invalid/undef: :replace gives on MRI, but String#encode on the
+      # whole string mis-converts some of their input on TruffleRuby 25
+      # (Shift_JIS even when valid, and it can return invalid UTF-8).
+      def by_char(bytes, encoding, fallback = nil)
+        bytes.dup.force_encoding(encoding).each_char.map do |char|
+          next "\uFFFD" unless char.valid_encoding?
+
+          char.encode(UTF_8)
+        rescue Encoding::UndefinedConversionError
+          fallback ? fallback.call(char) : "\uFFFD"
+        end.join
+      end
+
       # ZXing's Latin-1 vs. Shift_JIS heuristics (bytes known not to be UTF-8).
       def guess_latin1_or_shift_jis(bytes)
         can_be_latin1 = true

data/lib/qr_reader/decoder.rb

@@ -63,7 +63,9 @@ module QrReader
         result = run(bits, bit_matrix.width, try_mirrored, diags)
         return diags.find { |diag| diag[:result].equal?(result) } if result
 
-        diags.max_by.with_index { |diag, i| [STATUSES.index(diag[:status]), -i] }
+        # each_with_index.max_by, not max_by.with_index: JRuby passes the latter's
+        # block one [diag, i] Array.
+        diags.each_with_index.max_by { |diag, i| [STATUSES.index(diag[:status]), -i] }.first
       end
 
       private

data/lib/qr_reader/errors.rb

@@ -9,6 +9,6 @@ module QrReader
   # The image format was recognised but is not supported (e.g. arithmetic-coded JPEG).
   class UnsupportedImageError < ImageError; end
 
-  # Raised by QrReader.decode! when no QR code could be read.
+  # Raised by QrReader.decode! and QrReader.read! when no QR code could be read.
   class NotFoundError < Error; end
 end

data/lib/qr_reader/formats/pdf.rb

@@ -129,6 +129,10 @@ module QrReader
 
           document = guard { Document.new(binary(bytes)) }
           pages = guard { document.pages }
+          # Every PDF has at least one page; none found means the document
+          # structure is broken (or this is not really a PDF).
+          raise ImageError, "corrupt PDF (no pages found)" if pages.empty?
+
           failures = []
           count = 0
           pages.each_with_index do |page, index|
@@ -156,7 +160,9 @@ module QrReader
                              dpi: [dpi, dpi], vector: true }
             end
           end
-          raise no_images(failures) if count.zero?
+          # A PDF that draws nothing readable (text only) simply has no
+          # images; one whose images all failed to decode is an error.
+          raise no_images(failures) if count.zero? && !failures.empty?
 
           nil
         end
@@ -217,8 +223,6 @@ module QrReader
         end
 
         def no_images(failures)
-          return UnsupportedImageError.new("PDF contains no raster images") if failures.empty?
-
           reason = failures.first.message
           if failures.any?(UnsupportedImageError)
             UnsupportedImageError.new("PDF contains no decodable raster image (#{reason})")
@@ -1500,6 +1504,8 @@ module QrReader
         NONZERO = /[^\x00]/n
         HEX_DIGITS = "^0-9A-Fa-f"
         WHITESPACE = "\x00\t\n\f\r "
+        # Compressed bytes per Zlib::Inflate#inflate call (see inflate_with).
+        INFLATE_SLICE = 16_384
 
         class << self
           # Applies +filters+ in order; the output of the last one is cut
@@ -1542,14 +1548,19 @@ module QrReader
 
           # Inflated data (partial for truncated or damaged streams), nil if
           # nothing could be inflated.
+          # The data is fed in slices instead of through the block form of
+          # Zlib::Inflate#inflate: Ruby code running inside zlib's callback
+          # (allocating, collecting garbage) crashes ruby.wasm. The slices
+          # also bound how far the output can run past +limit+.
           def inflate_with(zstream, data, limit)
             out = String.new(encoding: Encoding::BINARY)
             full = false
+            pos = 0
             begin
-              zstream.inflate(data) do |chunk|
-                out << chunk
+              while pos < data.bytesize && !full
+                out << zstream.inflate(data.byteslice(pos, INFLATE_SLICE))
+                pos += INFLATE_SLICE
                 full = out.bytesize >= limit
-                break if full
               end
             rescue Zlib::Error
               failed = true

data/lib/qr_reader/formats/png.rb

@@ -40,7 +40,7 @@ module QrReader
 
       # Compressed bytes fed to zlib at a time (bounds the work done for
       # zip bombs: the output of one slice is at most ~66 MB, streamed).
-      INFLATE_SLICE = 1 << 16
+      INFLATE_SLICE = 16_384
       # Inflated bytes collected before a kernel call (bounds memory).
       KERNEL_SLICE = 1 << 20
 
@@ -268,8 +268,11 @@ module QrReader
         end
 
         # Yields the inflated IDAT payload in pieces, until the consumer
-        # sets @enough.
-        def each_inflated(&block)
+        # sets @enough. Not through the block form of Zlib::Inflate#inflate:
+        # Ruby code running inside zlib's callback (allocating, collecting
+        # garbage) crashes ruby.wasm, so each slice's output is yielded after
+        # the C call has returned.
+        def each_inflated
           zstream = Zlib::Inflate.new
           @idat.each do |pos, length|
             stop = pos + length
@@ -277,14 +280,17 @@ module QrReader
               return if @enough
 
               n = [stop - pos, INFLATE_SLICE].min
-              zstream.inflate(@bytes.byteslice(pos, n), &block)
+              data = zstream.inflate(@bytes.byteslice(pos, n))
               pos += n
+              yield data unless data.empty?
             end
           end
         rescue Zlib::Error => e
-          # Data inflated before the error was used; what is missing is
+          # Data inflated before the error is used; what is missing is
           # reported as truncation by the caller.
           @zlib_error = e
+          rest = zstream.flush_next_out.to_s
+          yield rest unless rest.empty? || @enough
         ensure
           if zstream
             zstream.reset # an unfinished stream would warn on close

data/lib/qr_reader/formats.rb

@@ -100,7 +100,7 @@ module QrReader
 
       def first_pdf_image(bytes)
         PDF.each_image(bytes) { |image, _info| return image }
-        raise UnsupportedImageError, "PDF contains no decodable raster image"
+        raise UnsupportedImageError, "PDF contains no raster image"
       end
 
       def unrecognized(bytes)

data/lib/qr_reader/kernel_digest.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module QrReader
+  # Fingerprint of the kernel sources that qr_reader-native was compiled from
+  # (stored in the native gem by script/native_generate.rb, compared by
+  # NativeKernels at load time).
+  #
+  # It hashes the Ruby tokens rather than the file bytes, so comments, blank
+  # lines and spacing can change without switching the native kernels off;
+  # any change to the code itself still does. "# spinel-sample:" comments
+  # count as code: they give Spinel the argument types.
+  module KernelDigest
+    # Tokens that carry no code: spacing, comments, =begin/=end blocks.
+    SKIPPED = %i[on_sp on_ignored_sp on_comment on_embdoc_beg on_embdoc on_embdoc_end].freeze
+    # A newline, whether Ruby treats it as a statement end or not.
+    LINE_BREAKS = %i[on_nl on_ignored_nl].freeze
+    SPINEL_COMMENT = /\A#\s*spinel-/
+    LINE_BREAK = "\n"
+
+    module_function
+
+    # SHA-256 over +files+ (paths relative to +lib+), nil if one is missing.
+    def digest(files, lib)
+      require "digest"
+      sha = Digest::SHA256.new
+      files.each do |rel|
+        path = File.join(lib, rel)
+        return nil unless File.file?(path)
+
+        sha << rel << "\0"
+        tokens(File.read(path, encoding: Encoding::UTF_8)).each { |token| sha << token << "\0" }
+      end
+      sha.hexdigest
+    end
+
+    # The code tokens of +source+ as "type\0text" Strings. Every run of line
+    # breaks (newlines, blank lines, comments, which end in the newline they
+    # take from Ripper) becomes one LINE_BREAK, so a trailing comment or an
+    # extra blank line does not change the result but joining two
+    # statements into one line does.
+    def tokens(source)
+      require "ripper"
+      out = []
+      Ripper.lex(source).each do |_position, type, text, _state|
+        if type == :on_comment && text.match?(SPINEL_COMMENT)
+          out << "spinel\0#{text.strip}"
+          line_break(out)
+        elsif LINE_BREAKS.include?(type) || (SKIPPED.include?(type) && text.end_with?("\n"))
+          line_break(out)
+        elsif !SKIPPED.include?(type)
+          out << "#{type}\0#{text}"
+        end
+      end
+      out.pop if out.last == LINE_BREAK
+      out
+    end
+
+    def line_break(out)
+      out << LINE_BREAK unless out.empty? || out.last == LINE_BREAK
+    end
+  end
+end

data/lib/qr_reader/native_kernels.rb

@@ -52,7 +52,8 @@ module QrReader
           return false
         end
 
-        expected = digest(QrReaderNative.kernel_files)
+        require_relative "kernel_digest"
+        expected = KernelDigest.digest(QrReaderNative.kernel_files, File.expand_path("..", __dir__))
         if expected != QrReaderNative.kernels_digest
           @reason = "qr_reader-native #{QrReaderNative.kernels_digest[0, 12]} was built from other kernel " \
                     "sources than qr_reader #{VERSION} (#{expected[0, 12] if expected}); using pure Ruby"
@@ -104,22 +105,6 @@ module QrReader
         else value
         end
       end
-
-      private
-
-      # SHA-256 over the given files (paths relative to lib/), nil if one is missing.
-      def digest(files)
-        require "digest"
-        lib = File.expand_path("..", __dir__)
-        sha = Digest::SHA256.new
-        files.each do |rel|
-          path = File.join(lib, rel)
-          return nil unless File.file?(path)
-
-          sha << rel << "\0" << File.binread(path) << "\0"
-        end
-        sha.hexdigest
-      end
     end
   end
 

data/lib/qr_reader/reader.rb

@@ -36,16 +36,21 @@ module QrReader
       @inverted = inverted
     end
 
+    # The input is a file path (String or Pathname), an IO with encoded image
+    # bytes (a File, StringIO.new(bytes), an upload's Tempfile), a
+    # QrReader::Image or a ChunkyPNG-style canvas. A String is always a path,
+    # never image data.
+
     # First decoded Result, or nil.
     def read(input)
-      each_result(input, false) { |result| return result }
+      each_result(self.class.source(input), false) { |result| return result }
       nil
     end
 
     # All decoded Results (distinct symbols, all pages), possibly empty.
     def read_all(input)
       results = []
-      each_result(input, true) { |result| results << result }
+      each_result(self.class.source(input), true) { |result| results << result }
       results
     end
 
@@ -54,52 +59,43 @@ module QrReader
     def scan(input, &block)
       return enum_for(:scan, input) unless block
 
-      each_result(input, true, &block)
+      each_result(self.class.source(input), true, &block)
       self
     end
 
     class << self
-      # Converts any supported input into an Image (the first page of
-      # multi-page documents).
+      # Converts any supported input (see #read) into an Image (the first
+      # page of multi-page documents).
       def load_image(input)
-        return input if input.is_a?(Image)
-
-        bytes = input_bytes(input)
-        if bytes
-          # Formats.decode reads the first page of TIFF and PDF too; this also
-          # finds PDFs with junk before their header.
-          if container_format(bytes) == :pdf
-            Formats::PDF.each_image(bytes) { |image, _info| return image }
-          end
-          return Formats.decode(bytes)
-        end
+        source = source(input)
+        return source if source.is_a?(Image)
 
-        if input.respond_to?(:width) && input.respond_to?(:height) && input.respond_to?(:pixels)
-          # ChunkyPNG-style canvas: pixels are 0xRRGGBBAA integers.
-          return Image.from_pixels(input.width, input.height, input.pixels.pack("N*"), :rgba)
+        # Formats.decode reads the first page of TIFF and PDF too; this also
+        # finds PDFs with junk before their header.
+        if container_format(source) == :pdf
+          Formats::PDF.each_image(source) { |image, _info| return image }
         end
-
-        raise ArgumentError, "unsupported input #{input.class}: expected a path, IO, image bytes or QrReader::Image"
+        Formats.decode(source)
       end
 
-      # Encoded image bytes for paths, IOs and byte strings; nil for other objects.
-      def input_bytes(input)
-        if input.is_a?(String)
-          # A short String naming an existing file is a path, even if it
-          # starts like image data ("GIF89a.gif", "P5 scan.pgm").
-          short = input.bytesize <= 4096 && !input.include?("\0")
-          return File.binread(input) if short && File.file?(input)
-          return input.b if Formats.format_of(input) || container_format(input)
-          raise ImageError, "unrecognised image data" unless short
-
-          File.binread(input) # raises Errno::ENOENT etc. like File.read
-        elsif input.respond_to?(:to_path)
-          File.binread(input.to_path)
-        elsif input.respond_to?(:read)
-          data = input.read
-          raise ImageError, "IO returned no data" unless data
-
-          data.b
+      # The input as encoded image bytes (a binary String) or an Image.
+      def source(input)
+        case input
+        when Image then input
+        when String then path_bytes(input)
+        else
+          # IOs first: since Ruby 3.2 every IO has #to_path ($stdin's is "<STDIN>").
+          if input.respond_to?(:read)
+            data = input.read or raise ImageError, "IO returned no data"
+            data.b
+          elsif input.respond_to?(:to_path)
+            File.binread(input.to_path)
+          elsif input.respond_to?(:width) && input.respond_to?(:height) && input.respond_to?(:pixels)
+            # ChunkyPNG-style canvas: pixels are 0xRRGGBBAA integers.
+            Image.from_pixels(input.width, input.height, input.pixels.pack("N*"), :rgba)
+          else
+            raise ArgumentError, "unsupported input #{input.class}: expected a file path, an IO or a QrReader::Image"
+          end
         end
       end
 
@@ -111,11 +107,27 @@ module QrReader
 
         nil
       end
+
+      private
+
+      # A positional String is a path and nothing else. Image bytes passed by
+      # mistake fail here instead of being read (or worse: bytes that spell a
+      # path being read as one), so the mix-up shows up on the first try.
+      def path_bytes(path)
+        return File.binread(path) if !path.include?("\0") && File.file?(path)
+        if path.include?("\0") || Formats.format_of(path) || container_format(path)
+          raise ArgumentError, "expected a file path, got a String that looks like image data " \
+                               "(#{path.bytesize} bytes); pass image bytes as an IO: StringIO.new(bytes)"
+        end
+
+        File.binread(path) # raises Errno::ENOENT etc. like File.read
+      end
     end
 
     private
 
-    # Yields decoded results (deduplicated) until the caller stops iterating.
+    # Yields decoded results (deduplicated) until the caller stops iterating;
+    # +input+ is a #source (encoded bytes or an Image).
     def each_result(input, multi, &block)
       @multi = multi
       @emit = block
@@ -127,13 +139,7 @@ module QrReader
         return
       end
 
-      bytes = self.class.input_bytes(input)
-      unless bytes
-        scan_pyramid(self.class.load_image(input), nil)
-        return
-      end
-
-      @y_scale = 1.0
+      bytes = input
       case self.class.container_format(bytes)
       when :tiff
         # Pages that cannot be decoded are skipped.

data/lib/qr_reader/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module QrReader
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/lib/qr_reader.rb

@@ -24,9 +24,14 @@ require_relative "qr_reader/native_kernels"
 #   QrReader.read("label.png")            # => #<data QrReader::Result text=..., version=3, ...>
 #   QrReader.scan("scans.tiff") { |code| puts "page #{code.page}: #{code.text}" }
 #
-# Every method accepts a file path (String or Pathname), an IO, encoded image
-# bytes (PNG, JPEG, JPEG 2000, GIF, BMP, PNM, TIFF, PDF), a QrReader::Image, or a
-# ChunkyPNG-style canvas (#width, #height, #pixels), plus these options:
+# Every method takes a file path (String or Pathname), an IO with encoded
+# image bytes (PNG, JPEG, JPEG 2000, GIF, BMP, PNM, TIFF, PDF), a
+# QrReader::Image, or a ChunkyPNG-style canvas (#width, #height, #pixels). A
+# String is always a path, never image data; wrap bytes in an IO:
+#
+#   QrReader.decode(StringIO.new(bytes))
+#
+# Options:
 #
 #   try_harder: true    - fall back to slower strategies when the fast ones find nothing
 #   inverted:   :auto   - also look for light-on-dark codes (true: only those, false: never)
@@ -52,6 +57,11 @@ module QrReader
       Reader.new(**options).read(input)
     end
 
+    # Like #read, but raises NotFoundError when no code can be read.
+    def read!(input, **options)
+      read(input, **options) or raise NotFoundError, "no QR code found"
+    end
+
     # All QR codes found (on all pages) as Results, possibly empty.
     def read_all(input, **options)
       Reader.new(**options).read_all(input)
@@ -66,8 +76,8 @@ module QrReader
       nil
     end
 
-    # Loads an image (path, IO, encoded bytes, Image or ChunkyPNG-style canvas)
-    # as a grayscale QrReader::Image; multi-page documents yield their first page.
+    # Loads an image (path, IO, Image or ChunkyPNG-style canvas) as a
+    # grayscale QrReader::Image; multi-page documents yield their first page.
     def load_image(input)
       Reader.load_image(input)
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: qr_reader
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Andi Idogawa
@@ -72,6 +72,7 @@ files:
 - lib/qr_reader/formats/pnm.rb
 - lib/qr_reader/formats/tiff.rb
 - lib/qr_reader/image.rb
+- lib/qr_reader/kernel_digest.rb
 - lib/qr_reader/kernels.rb
 - lib/qr_reader/kernels/binarizer.rb
 - lib/qr_reader/kernels/ccitt.rb