bzip2-ffi 1.0.0 → 1.1.1

data/lib/bzip2/ffi/writer.rb

@@ -1,9 +1,12 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
 require 'pathname'
 
 module Bzip2
   module FFI
-    # `Writer` compresses and writes a bzip2 compressed stream or file. The
-    # public instance methods of `Writer` are intended to be equivalent to those
+    # {Writer} compresses and writes a bzip2 compressed stream or file. The
+    # public instance methods of {Writer} are intended to be equivalent to those
     # of a standard `IO` object.
     #
     # Data can be written as a stream using {open} and {#write}. For example,
@@ -15,7 +18,7 @@ module Bzip2
     #       end
     #     end
     #
-    # Alternatively, without passing a block to `open`:
+    # Alternatively, without passing a block to {open}:
     #
     #     writer = Bzip2::FFI::Writer.open(io_or_path)
     #     begin
@@ -30,41 +33,45 @@ module Bzip2
     #
     #     Bzip2::FFI::Writer.write(io_or_path, 'Hello, World!')
     #
-    # The {open} and {write} methods accept either an `IO`-like object or a file
-    # path. `IO`-like objects must have a `write` method. Paths can be given as
+    # The {open} and {write} methods accept either an IO-like object or a file
+    # path. IO-like objects must have a `#write` method. Paths can be given as
     # either a `String` or `Pathname`.
     #
     # No character conversion is performed when writing and compressing. The
     # {write} and {#write} methods compress the raw bytes from the given
     # `String` (using the encoding of the `String`).
+    #
+    # {Writer} does not support seeking (it's not supported by the underlying
+    # libbz2 library). There are no `#seek` or `#pos=` methods.
     class Writer < IO
       # Size of the buffer passed to libbz2 for it to write compressed data to.
       #
       # @private
       OUT_BUFFER_SIZE = 4096 #:nodoc:
+      private_constant :OUT_BUFFER_SIZE
 
       class << self
         # Use send to keep this hidden from YARD (visibility tag does not work).
         send(:public, :new)
 
-        # Opens a {Writer} to compress and write bzip2 compressed data to
-        # either an `IO`-like object or a file. `IO`-like objects must have a
-        # `write` method. Files can be specified using either a `String`
-        # containing the file path or a `Pathname`.
+        # Opens a {Writer} to compress and write bzip2 compressed data to either
+        # an IO-like object or a file. IO-like objects must have a `#write`
+        # method. Files can be specified using either a `String` containing the
+        # file path or a `Pathname`.
         #
-        # If no block is given, the opened `Writer` instance is returned. After
+        # If no block is given, the opened {Writer} instance is returned. After
         # writing data, the instance must be closed using the {#close} method in
         # order to complete the compression process.
         #
-        # If a block is given, it will be passed the opened `Writer` instance
-        # as an argument. After the block terminates, the `Writer` instance will
+        # If a block is given, it will be passed the opened {Writer} instance
+        # as an argument. After the block terminates, the {Writer} instance will
         # automatically be closed. `open` will then return the result of the
         # block.
         #
         # The following options can be specified using the `options` `Hash`:
         #
-        # * `:autoclose` - When passing an `IO`-like object, set to `true` to
-        #                  close the `IO` when the `Writer` instance is closed.
+        # * `:autoclose` - When passing an IO-like object, set to `true` to
+        #                  close it when the {Writer} instance is closed.
         # * `:block_size` - Specifies the block size used for compression. It
         #                   should be set to an integer between 1 and 9
         #                   inclusive. The actual block size used is 100 kB
@@ -86,25 +93,25 @@ module Bzip2
         #                    the fallback. Allowable values range from 0 to 250
         #                    inclusive. 0 is a special case, equivalent to using
         #                    the default libbz2 work factor value (30 as of
-        #                    bzip2 v1.0.6). If not specified, `:work_factor`
+        #                    bzip2 v1.0.8). If not specified, `:work_factor`
         #                    defaults to 0.
         #
-        # If an `IO`-like object that has a `binmode` method is passed to
-        # `open`, `binmode` will be called on `io_or_path` before yielding to
-        # the block or returning.
+        # If an IO-like object that has a `#binmode` method is passed to {open},
+        # `#binmode` will be called on `io_or_path` before yielding to the block
+        # or returning.
         #
         # If a path to a file that already exists is passed to `open`, the file
         # will be truncated before writing.
         #
-        # @param io_or_path [Object] Either an `IO`-like object with a `write`
+        # @param io_or_path [Object] Either an IO-like object with a `#write`
         #                            method or a file path as a `String` or
         #                            `Pathname`.
         # @param options [Hash] Optional parameters (`:autoclose`, `:block_size`
         #                       and `:small`).
-        # @return [Object] The opened `Writer` instance if no block is given, or
+        # @return [Object] The opened {Writer} instance if no block is given, or
         #                  the result of the block if a block is given.
         # @raise [ArgumentError] If `io_or_path` is _not_ a `String`, `Pathname`
-        #                        or an `IO`-like object with a `write` method.
+        #                        or an IO-like object with a `#write` method.
         # @raise [Errno::ENOENT] If the parent directory of the specified file
         #                        does not exist.
         # @raise [Error::Bzip2Error] If an error occurs when initializing
@@ -122,14 +129,14 @@ module Bzip2
         end
 
         # Compresses data from a `String` and writes an entire bzip2 compressed
-        # structure to either an `IO`-like object or a file. `IO`-like objects
-        # must have a `write` method. Files can be specified using either a
+        # structure to either an IO-like object or a file. IO-like objects
+        # must have a `#write` method. Files can be specified using either a
         # `String` containing the file path or a `Pathname`.
         #
         # The following options can be specified using the `options` `Hash`:
         #
-        # * `:autoclose` - When passing an `IO`-like object, set to `true` to
-        #                  close the `IO` when the `Writer` instance is closed.
+        # * `:autoclose` - When passing an IO-like object, set to `true` to
+        #                  close it when the {Writer} instance is closed.
         # * `:block_size` - Specifies the block size used for compression. It
         #                   should be set to an integer between 1 and 9
         #                   inclusive. The actual block size used is 100 kB
@@ -151,28 +158,28 @@ module Bzip2
         #                    the fallback. Allowable values range from 0 to 250
         #                    inclusive. 0 is a special case, equivalent to using
         #                    the default libbz2 work factor value (30 as of
-        #                    bzip2 v1.0.6). If not specified, `:work_factor`
+        #                    bzip2 v1.0.8). If not specified, `:work_factor`
         #                    defaults to 0.
         #
         # No character conversion is performed. The raw bytes from `string` are
         # compressed (using the encoding of `string`).
         #
-        # If an `IO`-like object that has a `binmode` method is passed to
-        # `write`, `binmode` will be called on `io_or_path` before any
+        # If an IO-like object that has a `#binmode` method is passed to
+        # {write}, `#binmode` will be called on `io_or_path` before any
         # compressed data is written.
         #
         # The number of uncompressed bytes written is returned.
         #
-        # @param io_or_path [Object] Either an `IO`-like object with a `write`
+        # @param io_or_path [Object] Either an IO-like object with a `#write`
         #                            method or a file path as a `String` or
         #                            `Pathname`.
-        # @param string [Object] The string to write (`to_s` will be called
-        #                        before writing).
+        # @param string [Object] The string to write (the result of calling
+        #                        `#to_s` on `string` will be written).
         # @param options [Hash] Optional parameters (`:autoclose`, `:block_size`
         #                       and `:small`).
         # @return [Integer] The number of uncompressed bytes written.
         # @raise [ArgumentError] If `io_or_path` is _not_ a `String`, `Pathname`
-        #                        or an `IO`-like object with a `write` method.
+        #                        or an IO-like object with a `#write` method.
         # @raise [Errno::ENOENT] If the parent directory of the specified file
         #                        does not exist.
         # @raise [Error::Bzip2Error] If an error occurs when initializing
@@ -186,10 +193,10 @@ module Bzip2
         private
 
         # Returns a Proc that can be used as a finalizer to call
-        # `BZ2_bzCompressEnd` with the given `stream`.
+        # {Libbz2::BZ2_bzCompressEnd} with the given `stream`.
         #
         # @param stream [Libbz2::BzStream] The stream that should be passed to
-        #                                  `BZ2_bzCompressEnd`.
+        #                                  {Libbz2::BZ2_bzCompressEnd}.
         def finalize(stream)
           ->(id) do
             Libbz2::BZ2_bzCompressEnd(stream)
@@ -197,13 +204,13 @@ module Bzip2
         end
       end
 
-      # Initializes a {Writer} to write compressed data to an `IO`-like object
-      # (`io`). `io` must have a `write` method.
+      # Initializes a {Writer} to write compressed data to an IO-like object
+      # (`io`). `io` must have a `#write` method.
       #
       # The following options can be specified using the `options` `Hash`:
       #
-      # * `:autoclose` - When passing an `IO`-like object, set to `true` to
-      #                  close the `IO` when the `Writer` instance is closed.
+      # * `:autoclose` - When passing an IO-like object, set to `true` to
+      #                  close it when the {Writer} instance is closed.
       # * `:block_size` - Specifies the block size used for compression. It
       #                   should be set to an integer between 1 and 9
       #                   inclusive. The actual block size used is 100 kB
@@ -225,32 +232,32 @@ module Bzip2
       #                    the fallback. Allowable values range from 0 to 250
       #                    inclusive. 0 is a special case, equivalent to using
       #                    the default libbz2 work factor value (30 as of
-      #                    bzip2 v1.0.6). If not specified, `:work_factor`
+      #                    bzip2 v1.0.8). If not specified, `:work_factor`
       #                    defaults to 0.
       #
-      # `binmode` is called on `io` if `io` responds to `binmode`.
+      # `#binmode` is called on `io` if `io` responds to `#binmode`.
       #
-      # After use, the `Writer` instance must be closed using the {#close}
+      # After use, the {Writer} instance must be closed using the {#close}
       # method in order to complete the compression process.
       #
-      # @param io [Object] An `IO`-like object that has a `write` method.
+      # @param io [Object] An IO-like object that has a `#write` method.
       # @param options [Hash] Optional parameters (`:autoclose`, `:block_size`
       #                       and `:small`).
-      # @raise [ArgumentError] If `io` is `nil` or does not respond to `write`.
+      # @raise [ArgumentError] If `io` is `nil` or does not respond to `#write`.
       # @raise [RangeError] If `options[:block_size]` is less than 1 or greater
       #                     than 9, or `options[:work_factor]` is less than 0 or
       #                     greater than 250.
       # @raise [Error::Bzip2Error] If an error occurs when initializing libbz2.
-      def initialize(io, options = {})    
+      def initialize(io, options = {})
         super
         raise ArgumentError, 'io must respond to write' unless io.respond_to?(:write)
-        
+
         block_size = options[:block_size] || 9
         work_factor = options[:work_factor] || 0
-        
+
         raise RangeError, 'block_size must be >= 1 and <= 9' if block_size < 1 || block_size > 9
         raise RangeError, 'work_factor must be >= 0 and <= 250' if work_factor < 0 || work_factor > 250
-        
+
         check_error(Libbz2::BZ2_bzCompressInit(stream, block_size, 0, work_factor))
 
         ObjectSpace.define_finalizer(self, self.class.send(:finalize, stream))
@@ -261,11 +268,11 @@ module Bzip2
       # {Writer}.
       #
       # If the {open} method is used with a block, it is not necessary to call
-      # `close`. Otherwise, `close` must be called once the all the data to be
+      # {close}. Otherwise, {close} must be called once the all the data to be
       # compressed has been passed to `#write`.
       #
       # @return [NilType] `nil`.
-      # @raise [IOError] If the `Writer` has already been closed.
+      # @raise [IOError] If the {Writer} has already been closed.
       def close
         s = stream
         flush_buffers(s, Libbz2::BZ_FINISH, Libbz2::BZ_STREAM_END)
@@ -283,11 +290,11 @@ module Bzip2
       #
       # The number of uncompressed bytes written is returned.
       #
-      # @param string [Object] The string to write (`to_s` will be called
-      #                        before writing).
+      # @param string [Object] The string to write (the result of calling
+      #                        `#to_s` on `string` will be written).
       # @return [Integer] The number of uncompressed bytes written.
       # @raise [Error::Bzip2Error] If an error occurs during compression.
-      # @raise [IOError] If the `Writer` has been closed.
+      # @raise [IOError] If the {Writer} has been closed.
       def write(string)
         string = string.to_s
 
@@ -296,7 +303,7 @@ module Bzip2
         buffer = ::FFI::MemoryPointer.new(1, OUT_BUFFER_SIZE)
         begin
           next_in.write_bytes(string)
-          s[:next_in] = next_in        
+          s[:next_in] = next_in
           s[:avail_in] = next_in.size
 
           while s[:avail_in] > 0
@@ -322,29 +329,41 @@ module Bzip2
       # writes out the current bzip2 compressed block to the underlying
       # compressed stream or file.
       #
-      # It is not usually necessary to call `flush`.
+      # It is not usually necessary to call {flush}.
       #
-      # Calling `flush` may result in a larger compressed output.
+      # Calling {flush} may result in a larger compressed output.
       #
       # @return [Writer] `self`.
       # @raise [Error::Bzip2Error] If an error occurs during the flush
       #                            operation.
-      # @raise [IOError] If the `Writer` has been closed.
+      # @raise [IOError] If the {Writer} has been closed.
       def flush
         flush_buffers(stream, Libbz2::BZ_FLUSH, Libbz2::BZ_RUN_OK)
         self
       end
 
+      # Returns the number of uncompressed bytes that have been written.
+      #
+      # @return [Integer] The number of uncompressed bytes that have been
+      #                   written.
+      # @raise [IOError] If the {Writer} has been closed.
+      def tell
+        s = stream
+        (s[:total_in_hi32] << 32) | s[:total_in_lo32]
+      end
+      alias pos tell
+
       private
 
-      # Calls `BZ2_bzCompress` repeatedly without input to complete compression
-      # of data that has been provided in prior calls.
+      # Calls {Libbz2::BZ2_bzCompress} repeatedly without input to complete
+      # compression of data that has been provided in prior calls.
       #
-      # @param s [Libbz2::BzStream] The stream to pass to `BZ2_bzCompress`.
-      # @param action [Integer] The action to pass to `BZ2_bzCompress`.
+      # @param s [Libbz2::BzStream] The stream to pass to
+      #                             {Libbz2::BZ2_bzCompress}.
+      # @param action [Integer] The action to pass to {Libbz2::BZ2_bzCompress}.
       # @param terminate_result [Integer] The result code that indicates when
       #                                   the action has been completed.
-      # @raise [Error::Bzip2Error] If `BZ2_bzCompress` reports an error.
+      # @raise [Error::Bzip2Error] If {Libbz2::BZ2_bzCompress} reports an error.
       def flush_buffers(s, action, terminate_result)
         s[:next_in] = nil
         s[:avail_in] = 0
@@ -367,7 +386,7 @@ module Bzip2
           buffer.free
           s[:next_out] = nil
         end
-      end     
+      end
     end
   end
 end

data/lib/bzip2/ffi.rb

@@ -1,3 +1,6 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
 module Bzip2
   # Bzip2::FFI is a wrapper for libbz2 using FFI bindings. Bzip2 compressed data
   # can be read and written as a stream using the Reader and Writer classes.
@@ -5,10 +8,10 @@ module Bzip2
   end
 end
 
-require 'bzip2/ffi/libbz2'
-require 'bzip2/ffi/error'
-require 'bzip2/ffi/io'
-require 'bzip2/ffi/reader'
-require 'bzip2/ffi/writer'
-require 'bzip2/ffi/version'
+require_relative 'ffi/libbz2'
+require_relative 'ffi/error'
+require_relative 'ffi/io'
+require_relative 'ffi/reader'
+require_relative 'ffi/writer'
+require_relative 'ffi/version'
 

data/test/error_test.rb

@@ -1,4 +1,7 @@
-require 'test_helper'
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative 'test_helper'
 
 class ErrorTest < Minitest::Test
   def test_initialize_base_class
@@ -7,30 +10,26 @@ class ErrorTest < Minitest::Test
     assert_same(message, error.message)
   end
 
-  def test_initialize_sub_classes
-    classes = [
-      Bzip2::FFI::Error::SequenceError,
-      Bzip2::FFI::Error::ParamError,
-      Bzip2::FFI::Error::MemoryError,
-      Bzip2::FFI::Error::ParamError,
-      Bzip2::FFI::Error::DataError,
-      Bzip2::FFI::Error::MagicDataError,
-      Bzip2::FFI::Error::ConfigError,
-      Bzip2::FFI::Error::UnexpectedEofError
-    ]
-
-    classes.each do |c|
+  [
+    Bzip2::FFI::Error::SequenceError,
+    Bzip2::FFI::Error::ParamError,
+    Bzip2::FFI::Error::MemoryError,
+    Bzip2::FFI::Error::DataError,
+    Bzip2::FFI::Error::MagicDataError,
+    Bzip2::FFI::Error::ConfigError,
+    Bzip2::FFI::Error::UnexpectedEofError
+  ].each do |c|
+    define_method("test_initialize_sub_classes_#{c.name.split('::').last.gsub(/([a-z])([A-Z])/, '\1_\2').downcase}") do
       error = c.new
       refute_nil(error.message)
     end
   end
 
-  def test_initialize_unexpected
-    # -6, -7 and -8 are errors that are only raised by the libbz2 high-level
-    # interface. Only the low-level interface is used by Bzip2::FFI.
-    # -10 is not defined by libbz2.
-
-    [-6, -7, -8, -10].each do |code|
+  # -6, -7 and -8 are errors that are only raised by the libbz2 high-level
+  # interface. Only the low-level interface is used by Bzip2::FFI. -10 is not
+  # defined by libbz2.
+  [-6, -7, -8, -10].each do |code|
+    define_method("test_initialize_unexpected_#{code}") do
       error = Bzip2::FFI::Error::UnexpectedError.new(code)
       assert_includes(error.message, code.to_s)
     end

data/test/io_test.rb

@@ -1,11 +1,14 @@
-require 'test_helper'
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative 'test_helper'
 
 class IOTest < Minitest::Test
   class DummyIO
     def initialize
       @closed = false
     end
-    
+
     def close
       @closed = true
     end
@@ -36,6 +39,9 @@ class IOTest < Minitest::Test
     end
   end
 
+  # Private constant.
+  LIBBZ2 = Bzip2::FFI.const_get(:Libbz2)
+
   def test_autoclose_set_true
     io = TestIO.new(DummyIO.new, autoclose: false)
     assert_equal(false, io.autoclose?)
@@ -138,7 +144,7 @@ class IOTest < Minitest::Test
     io.close
     assert_equal(true, io.closed?)
   end
-  
+
   def test_external_encoding
     io = TestIO.new(DummyIO.new)
     assert_equal(Encoding::ASCII_8BIT, io.external_encoding)
@@ -192,7 +198,7 @@ class IOTest < Minitest::Test
     io = TestIO.new(DummyIO.new)
     s = io.stream
     refute_nil(s)
-    assert_kind_of(Bzip2::FFI::Libbz2::BzStream, s)
+    assert_kind_of(LIBBZ2.const_get(:BzStream), s)
   end
 
   def test_stream_when_closed
@@ -213,38 +219,34 @@ class IOTest < Minitest::Test
     assert_equal('closed stream', e.message)
   end
 
-  def test_check_error_not_error
-    io = TestIO.new(DummyIO.new)
-    
-    (0..4).each do |i|
+  (0..4).each do |i|
+    define_method("test_check_error_not_error_#{i}") do
+      io = TestIO.new(DummyIO.new)
       assert_equal(i, io.check_error(i))
     end
   end
 
-  def test_check_error_error
-    codes = {
-      Bzip2::FFI::Libbz2::BZ_SEQUENCE_ERROR => Bzip2::FFI::Error::SequenceError,
-      Bzip2::FFI::Libbz2::BZ_PARAM_ERROR => Bzip2::FFI::Error::ParamError,
-      Bzip2::FFI::Libbz2::BZ_MEM_ERROR => Bzip2::FFI::Error::MemoryError,
-      Bzip2::FFI::Libbz2::BZ_DATA_ERROR => Bzip2::FFI::Error::DataError,
-      Bzip2::FFI::Libbz2::BZ_DATA_ERROR_MAGIC => Bzip2::FFI::Error::MagicDataError,
-      Bzip2::FFI::Libbz2::BZ_CONFIG_ERROR => Bzip2::FFI::Error::ConfigError
-    }
-
-    io = TestIO.new(DummyIO.new)
-
-    codes.each do |code, error_class|
+  {
+    :BZ_SEQUENCE_ERROR => Bzip2::FFI::Error::SequenceError,
+    :BZ_PARAM_ERROR => Bzip2::FFI::Error::ParamError,
+    :BZ_MEM_ERROR => Bzip2::FFI::Error::MemoryError,
+    :BZ_DATA_ERROR => Bzip2::FFI::Error::DataError,
+    :BZ_DATA_ERROR_MAGIC => Bzip2::FFI::Error::MagicDataError,
+    :BZ_CONFIG_ERROR => Bzip2::FFI::Error::ConfigError
+  }.each do |type, error_class|
+    define_method("test_check_error_error_#{type}") do
+      io = TestIO.new(DummyIO.new)
+      code = LIBBZ2.const_get(type)
       assert_raises(error_class) { io.check_error(code) }
     end
   end
 
-  def test_check_error_unexpected
-    io = TestIO.new(DummyIO.new)
-
-    # -6, -7 and -8 are codes that are only raised by the libbz2 high-level
-    # interface. Only the low-level interface is used by Bzip2::FFI.
-    # -10 is not defined by libbz2.
-    [-6, -7, -8, -10].each do |code|
+  # -6, -7 and -8 are codes that are only raised by the libbz2 high-level
+  # interface. Only the low-level interface is used by Bzip2::FFI. -10 is not
+  # defined by libbz2.
+  [-6, -7, -8, -10].each do |code|
+    define_method("test_check_error_unexpected_#{code}") do
+      io = TestIO.new(DummyIO.new)
       error = assert_raises(Bzip2::FFI::Error::UnexpectedError) { io.check_error(code) }
       assert_includes(error.message, code.to_s)
     end
@@ -304,14 +306,14 @@ class IOTest < Minitest::Test
     res = TestIO.open(dummy_io) do |io|
       assert_kind_of(TestIO, io)
       refute(io.closed?)
-      assert_equal(false, io.autoclose?) 
+      assert_equal(false, io.autoclose?)
       assert_same(dummy_io, io.io)
       copy_io = io
       42
     end
 
     assert(copy_io.closed?)
-    assert_equal(42, res)    
+    assert_equal(42, res)
   end
 
   def test_open_block_options
@@ -321,14 +323,14 @@ class IOTest < Minitest::Test
     res = TestIO.open(dummy_io, autoclose: true) do |io|
       assert_kind_of(TestIO, io)
       refute(io.closed?)
-      assert_equal(true, io.autoclose?) 
+      assert_equal(true, io.autoclose?)
       assert_same(dummy_io, io.io)
       copy_io = io
       42
     end
 
     assert(copy_io.closed?)
-    assert_equal(42, res) 
+    assert_equal(42, res)
   end
 
   def test_open_block_closes