Feat: Reader.foreach support

lib/bzip2/ffi/reader.rb

@@ -131,6 +131,54 @@ def open(io_or_path, options = {})
           end
         end
 
+        # Reads and decompresses data from the bzip2 compressed stream or file
+        # and yields each line to the block. The block is called with each line
+        # as a `String`.
+        #
+        # The following options can be specified using the `options` `Hash`:
+        #
+        # * `:autoclose` - When passing an IO-like object, set to `true` to
+        #                  close it when the compressed data has been read.
+        # * `:first_only` - Bzip2 files can contain multiple consecutive
+        #                   compressed strctures. Normally all the structures
+        #                   will be decompressed with the decompressed bytes
+        #                   concatenated. Set to `true` to only read the first
+        #                   structure.
+        # * `:small` - Set to `true` to use an alternative decompression
+        #              algorithm that uses less memory, but at the cost of
+        #              decompressing more slowly (roughly 2,300 kB less memory
+        #              at about half the speed).
+        #
+        # If an IO-like object that has a `#binmode` method is passed to {foreach},
+        # `#binmode` will be called on `io_or_path` before any compressed data
+        # is read.
+        #
+        # @param io_or_path [Object] Either an IO-like object with a `#read`
+        #                            method or a file path as a `String` or
+        #                            `Pathname`.
+        # @param options [Hash] Optional parameters (`:autoclose`, `:first_only`
+        #                       and `:small`).
+        # @yield [line] The block is called with each line as a `String`.
+        # @yieldparam line [String] A line of decompressed data.
+        # @return [NilType] `nil`.
+        # @raise [ArgumentError] If `io_or_path` is _not_ a `String`, `Pathname`
+        #                        or an IO-like object with a `#read` method.
+        # @raise [Errno::ENOENT] If the specified file does not exist.
+        # @raise [Error::Bzip2Error] If an error occurs when initializing
+        #                            libbz2 or decompressing data.
+        def foreach(io_or_path, options = {})
+          open(io_or_path, options) do |reader|
+            buffer = +""
+            until reader.eof?
+              buffer << reader.read
+              lines = buffer.split("\n")
+              lines[0...-1].each { |line| yield line }
+              buffer = lines.last
+            end
+            yield buffer unless buffer.empty?
+          end
+        end
+
         # Reads and decompresses and entire bzip2 compressed structure from
         # either an IO-like object or a file and returns the decompressed bytes
         # as a `String`. IO-like objects must have a `#read` method. Files can

test/reader_test.rb

@@ -684,6 +684,14 @@ def test_open_after_open_file_exception_closes_file
     assert(file.closed?)
   end
 
+  def test_foreach_block_io
+    lines = []
+    Bzip2::FFI::Reader.foreach(fixture_path('lorem-first-structure-4096-bytes.txt.bz2'), encoding: "UTF-8") do |line|
+      lines << line.force_encoding('UTF-8')
+    end
+    assert_equal("Lorém ipsúm dòlòr sìt amét, vix cu alìa póstulant, pri ea odio falli ", lines.first)
+  end
+
   def test_class_read_initialize_nil_io
     assert_raises(ArgumentError) { Bzip2::FFI::Reader.read(nil) }
   end