bzip2-ffi 1.0.0 → 1.1.1

data/lib/bzip2/ffi/io.rb

@@ -1,19 +1,22 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
 module Bzip2
   module FFI
-    # `IO` is a base class providing common functionality for the {Reader} and
+    # {IO} is a base class providing common functionality for the {Reader} and
     # {Writer} subclasses.
     #
-    # `Bzip2::FFI::IO` holds a reference to an underlying `IO`-like stream
-    # representing the bzip2-compressed data to be read from or written to.
+    # Holds a reference to an underlying IO-like stream representing the bzip2
+    # compressed data to be read from or written to.
     class IO
       class << self
         protected :new
 
         protected
 
-        # If no block is provided, returns a new `IO`. If a block is provided,
-        # a new `IO` is created and yielded to the block. After the block has
-        # executed, the `IO` is closed and the result of the block is returned.
+        # If no block is provided, returns a new {IO}. If a block is provided,
+        # a new {IO} is created and yielded to the block. After the block has
+        # executed, the {IO} is closed and the result of the block is returned.
         #
         # If `io_or_proc` is a `Proc`, it is called to obtain an IO-like
         # instance to pass to `new`. Otherwise `io_or_proc` is passed directly
@@ -22,6 +25,11 @@ module Bzip2
         # @param io_or_proc [Object] An IO-like object or a `Proc` that returns
         #                            an IO-like object when called.
         # @param options [Hash] Options to pass to `new`.
+        # @yield [io] If a block is given, it is yielded to.
+        # @yieldparam io [IO] The new {IO} instance.
+        # @yieldresult [Object] A result to be returned as the result of {open}.
+        # @return [Object] The result of the block if a block is given,
+        #                  otherwise the new {IO} instance.
         def open(io_or_proc, options = {})
           if io_or_proc.kind_of?(Proc)
             io = io_or_proc.call
@@ -36,7 +44,7 @@ module Bzip2
           end
 
           if block_given?
-            begin            
+            begin
               yield bz_io
             ensure
               bz_io.close unless bz_io.closed?
@@ -46,7 +54,7 @@ module Bzip2
           end
         end
 
-        # Opens and returns a bzip `File` using the specified mode. The system
+        # Opens and returns a bzip file using the specified mode. The system
         # is advised that the file will be accessed once sequentially.
         #
         # @param path [String] The path to open.
@@ -67,9 +75,9 @@ module Bzip2
 
         private
 
-        # Advises the system that an `IO` will be accessed once sequentially.
+        # Advises the system that an `::IO` will be accessed once sequentially.
         #
-        # @param io [IO] An `IO` instance to advise.
+        # @param io [::IO] An `::IO` instance to advise.
         def after_open_file(io)
           # JRuby 1.7.18 doesn't have a File#advise method (in any mode).
           if io.respond_to?(:advise)
@@ -79,67 +87,69 @@ module Bzip2
         end
       end
 
-      # Returns `true` if the underlying compressed `IO` instance will be closed
-      # when {#close} is called, otherwise `false`.
+      # Returns `true` if the underlying compressed IO-like instance will be
+      # closed when {#close} is called, otherwise `false`.
       #
-      # @return [Boolean] `true` if the underlying compressed IO instance will
-      #                   be closed when {#close} is closed, otherwise `false`.
-      # @raise [IOError] If the instance has been closed.
+      # @return [Boolean] `true` if the underlying compressed IO-like instance
+      #                   will be closed when {#close} is closed, otherwise
+      #                   `false`.
+      # @raise [IOError] If the {IO} instance has been closed.
       def autoclose?
         check_closed
         @autoclose
       end
 
-      # Sets whether the underlying compressed `IO` instance should be closed
+      # Sets whether the underlying compressed IO-like instance should be closed
       # when {#close} is called (`true`) or left open (`false`).
       #
       # @param autoclose [Boolean] `true` if the underlying compressed `IO`
       #                            instance should be closed when {#close} is
       #                            called, or `false` if it should be left open.
-      # @raise [IOError] If the instance has been closed.
+      # @raise [IOError] If the {IO} instance has been closed.
       def autoclose=(autoclose)
         check_closed
         @autoclose = !!autoclose
       end
 
-      # Returns `true` to indicate that the `IO` is operating in binary mode
-      # (as is always the case).
+      # Returns `true` to indicate that the {IO} instance is operating in binary
+      # mode (as is always the case).
       #
       # @return [Boolean] `true`.
-      # @raise [IOError] If the `IO` has been closed.
+      # @raise [IOError] If the {IO} instance has been closed.
       def binmode?
         check_closed
         true
       end
 
-      # Puts the `IO` into binary mode.
+      # Puts the {IO} instance into binary mode.
       #
-      # Note that `Bzip2::FFI::IO` and subclasses always operate in binary mode,
-      # so calling `binmode` has no effect.
+      # Note that {IO} and subclasses always operate in binary mode, so calling
+      # `binmode` has no effect.
       #
       # @return [IO] `self`.
-      # @raise [IOError] If the `IO` has been closed.
+      # @raise [IOError] If the {IO} instance has been closed.
       def binmode
         check_closed
         self
       end
 
-      # Closes the `IO`.
+      # Closes the {IO} instance.
       #
-      # If {#autoclose?} is true and the underlying compressed `IO` responds to
-      # `close`, it will also be closed.
+      # If {#autoclose?} is true and the underlying compressed IO-like instance
+      # responds to `close`, it will also be closed.
       #
       # @return [NilClass] `nil`.
-      # @raise [IOError] If the `IO` has already been closed.
+      # @raise [IOError] If the {IO} instance has already been closed.
       def close
         check_closed
         @io.close if autoclose? && @io.respond_to?(:close)
         @stream = nil
       end
 
-      # Indicates whether the `IO` has been closed by calling {#close}.
+      # Indicates whether the {IO} instance has been closed by calling {#close}.
       #
-      # @return [Boolean] `true` if the `IO` has been closed, otherwise `false`.
+      # @return [Boolean] `true` if the {IO} instance has been closed, otherwise
+      #                   `false`.
       def closed?
         !@stream
       end
@@ -151,7 +161,7 @@ module Bzip2
       # returns `Encoding::ASCII_8BIT` (also known as `Encoding::BINARY`).
       #
       # @return [Encoding] `Encoding::ASCII_8BIT`.
-      # @raise [IOError] If the `IO` has been closed.
+      # @raise [IOError] If the {IO} instance has been closed.
       def external_encoding
         check_closed
         Encoding::ASCII_8BIT
@@ -168,32 +178,33 @@ module Bzip2
         check_closed
         Encoding::ASCII_8BIT
       end
-      
+
       protected
 
-      # The underlying compressed `IO` instance.
+      # The underlying compressed IO-like instance.
       attr_reader :io
 
-      # Initializes a new {Bzip2::FFI::IO} instance with an underlying
-      # compressed `IO` instance and `options` `Hash`.
+      # Initializes a new {IO} instance with an underlying compressed IO-like
+      # instance and `options` `Hash`.
       #
       # `binmode` is called on `io` if `io` responds to `binmode`.
       #
-      # A single `:autoclose` option is supported. Set `:autoclose` to true
-      # to close the underlying compressed `IO` instance when {#close} is
+      # A single `:autoclose` option is supported. Set `:autoclose` to true to
+      # close the underlying compressed IO-like instance when {#close} is
       # called.
       #
-      # @param io [IO] An `IO`-like object that represents the compressed data.
+      # @param io [Object] An IO-like object that represents the compressed
+      #                    data.
       # @param options [Hash] Optional parameters (:autoclose).
       # @raise [ArgumentError] If `io` is nil.
       def initialize(io, options = {})
         raise ArgumentError, 'io is required' unless io
-        
+
         @io = io
-        @io.binmode if @io.respond_to?(:binmode)        
+        @io.binmode if @io.respond_to?(:binmode)
 
         @autoclose = !!options[:autoclose]
-        
+
         @stream = Libbz2::BzStream.new
       end
 
@@ -202,22 +213,23 @@ module Bzip2
       #
       # @return [Libbz2::BzStream] The {Libbz2::BzStream} instance being used
       #                            to interface with libbz2.
-      # @raise [IOError] If the `IO` has been closed.
+      # @raise [IOError] If the {IO} instance has been closed.
       def stream
         check_closed
         @stream
-      end      
+      end
 
-      # Raises an `IOError` if {#close} has been called to close the {IO}.
+      # Raises an `IOError` if {#close} has been called to close the {IO}
+      # instance.
       #
-      # @raise [IOError] If the `IO` has been closed.
+      # @raise [IOError] If the {IO} instance has been closed.
       def check_closed
         raise IOError, 'closed stream' if closed?
       end
 
       # Checks a return code from a libbz2 function. If it is greater than or
       # equal to 0 (success), the return code is returned. If it is less than
-      # zero (an error), the appropriate {Bzip2::Bzip2Error} sub-class is
+      # zero (an error), the appropriate {Error::Bzip2Error} sub-class is
       # raised.
       #
       # @param res [Integer] The result of a call to a libbz2 function.
@@ -244,7 +256,7 @@ module Bzip2
         end
 
         raise error_class.new
-      end      
+      end
     end
   end
 end

data/lib/bzip2/ffi/libbz2.rb

@@ -1,10 +1,13 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
 require 'ffi'
 
 module Bzip2
   module FFI
     # FFI bindings for the libbz2 low-level interface.
     #
-    # See bzlib.h and http://bzip.org/docs.html.
+    # See bzlib.h and https://sourceware.org/bzip2/docs.html.
     #
     # @private
     module Libbz2 #:nodoc:
@@ -50,7 +53,7 @@ module Bzip2
 
                :bzalloc,        :bzalloc,
                :bzfree,         :bzfree,
-               :opaque,         :pointer       
+               :opaque,         :pointer
       end
 
       # int BZ2_bzCompressInt(bz_stream* strm, int blockSize100k, int verbosity, int workFactor);
@@ -61,7 +64,7 @@ module Bzip2
 
       # int BZ2_bzCompressEnd (bz_stream* strm);
       attach_function :BZ2_bzCompressEnd, [BzStream.by_ref], :int
-      
+
       # int BZ2_bzDecompressInit (bz_stream *strm, int verbosity, int small);
       attach_function :BZ2_bzDecompressInit, [BzStream.by_ref, :int, :int], :int
 
@@ -71,5 +74,6 @@ module Bzip2
       # int BZ2_bzDecompressEnd (bz_stream *strm);
       attach_function :BZ2_bzDecompressEnd, [BzStream.by_ref], :int
     end
+    private_constant :Libbz2
   end
 end