ruby-xz 0.2.1 → 0.2.2

data/lib/xz/lib_lzma.rb

@@ -1,9 +1,10 @@
 # -*- coding: utf-8 -*-
+#--
 # The MIT License
 #
 # Basic liblzma-bindings for Ruby.
 #
-# Copyright © 2011,2013 Marvin Gülker et al.
+# Copyright © 2011,2013,2015 Marvin Gülker et al.
 #
 # Permission is hereby granted, free of charge, to any person obtaining a
 # copy of this software and associated documentation files (the ‘Software’),
@@ -22,19 +23,20 @@
 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
+#++
 
 module XZ
 
-  #This module wraps functions and enums used by liblzma.
+  # This module wraps functions and enums used by liblzma.
   module LibLZMA
     extend FFI::Library
 
-    #The maximum value of an uint64_t, as defined by liblzma.
-    #Should be the same as
-    #  (2 ** 64) - 1
+    # The maximum value of an uint64_t, as defined by liblzma.
+    # Should be the same as
+    #   (2 ** 64) - 1
     UINT64_MAX = 18446744073709551615
 
-    #Activates extreme compression. Same as xz's "-e" commandline switch.
+    # Activates extreme compression. Same as xz's "-e" commandline switch.
     LZMA_PRESET_EXTREME = 1 << 31
 
     LZMA_TELL_NO_CHECK          = 0x02
@@ -42,22 +44,30 @@ module XZ
     LZMA_TELL_ANY_CHECK         = 0x04
     LZMA_CONCATENATED           = 0x08
 
-    #Placeholder enum used by liblzma for later additions.
+    # For access convenience of the above flags.
+    LZMA_DECODE_FLAGS = {
+      :tell_no_check          => LZMA_TELL_NO_CHECK,
+      :tell_unsupported_check => LZMA_TELL_UNSUPPORTED_CHECK,
+      :tell_any_check         => LZMA_TELL_ANY_CHECK,
+      :concatenated           => LZMA_CONCATENATED
+    }.freeze
+
+    # Placeholder enum used by liblzma for later additions.
     LZMA_RESERVED_ENUM = enum :lzma_reserved_enum, 0
 
-    #Actions that can be passed to the lzma_code() function.
+    # Actions that can be passed to the lzma_code() function.
     LZMA_ACTION = enum  :lzma_run, 0,
     :lzma_sync_flush,
     :lzma_full_flush,
     :lzma_finish
 
-    #Integrity check algorithms supported by liblzma.
+    # Integrity check algorithms supported by liblzma.
     LZMA_CHECK = enum :lzma_check_none,   0,
     :lzma_check_crc32,  1,
     :lzma_check_crc64,  4,
     :lzma_check_sha256, 10
 
-    #Possible return values of liblzma functions.
+    # Possible return values of liblzma functions.
     LZMA_RET = enum :lzma_ok, 0,
     :lzma_stream_end,
     :lzma_no_check,
@@ -80,10 +90,10 @@ module XZ
 
   end
 
-  #The class of the error that this library raises.
+  # The class of the error that this library raises.
   class LZMAError < StandardError
 
-    #Raises an appropriate exception if +val+ isn't a liblzma success code.
+    # Raises an appropriate exception if +val+ isn't a liblzma success code.
     def self.raise_if_necessary(val)
       case LibLZMA::LZMA_RET[val]
       when :lzma_mem_error      then raise(self, "Couldn't allocate memory!")
@@ -98,7 +108,7 @@ module XZ
 
   end
 
-  #The main struct of the liblzma library.
+  # The main struct of the liblzma library.
   class LZMAStream < FFI::Struct
     layout :next_in, :pointer, #uint8
     :avail_in, :size_t,
@@ -119,11 +129,11 @@ module XZ
     :reserved_enum1, :int,
     :reserved_enum2, :int
 
-    #This method does basicly the same thing as the
-    #LZMA_STREAM_INIT macro of liblzma. Creates a new LZMAStream
-    #that has been initialized for usage. If any argument is passed,
-    #it is assumed to be a FFI::Pointer to a lzma_stream structure
-    #and that structure is wrapped.
+    # This method does basicly the same thing as the
+    # LZMA_STREAM_INIT macro of liblzma. Creates a new LZMAStream
+    # that has been initialized for usage. If any argument is passed,
+    # it is assumed to be a FFI::Pointer to a lzma_stream structure
+    # and that structure is wrapped.
     def initialize(*args)
       if !args.empty? #Got a pointer, want to wrap it
         super

data/lib/xz/stream.rb

@@ -1,9 +1,10 @@
 # -*- coding: utf-8 -*-
+#--
 # (The MIT license)
 #
 # Basic liblzma-bindings for Ruby.
 #
-# Copyright © 2012 Marvin Gülker
+# Copyright © 2012, 2015 Marvin Gülker
 #
 # Permission is hereby granted, free of charge, to any person obtaining a
 # copy of this software and associated documentation files (the ‘Software’),
@@ -22,30 +23,31 @@
 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
+#++
 
-#The base class for XZ::StreamReader and XZ::StreamWriter.
-#This is an abstract class that is not meant to be used
-#directly; if you try, you will soon recognise that you’ve
-#created a quite limited object ;-). You can, however, test
-#against this class in <tt>kind_of?</tt> tests.
+# The base class for XZ::StreamReader and XZ::StreamWriter.
+# This is an abstract class that is not meant to be used
+# directly; if you try, you will soon recognise that you’ve
+# created a quite limited object ;-). You can, however, test
+# against this class in <tt>kind_of?</tt> tests.
 #
-#XZ::StreamReader and XZ::StreamWriter are IO-like classes that
-#allow you to access XZ-compressed data the same way you access
-#an IO-object, easily allowing to fool other libraries that expect
-#IO objects. The most noticable example for this may be reading
-#and writing XZ-compressed tarballs; see XZ::StreamReader and
-#XZ::StreamWriter for respective examples.
+# XZ::StreamReader and XZ::StreamWriter are IO-like classes that
+# allow you to access XZ-compressed data the same way you access
+# an IO-object, easily allowing to fool other libraries that expect
+# IO objects. The most noticable example for this may be reading
+# and writing XZ-compressed tarballs; see XZ::StreamReader and
+# XZ::StreamWriter for respective examples.
 #
-#Neither this class nor its subclasses document the IO-methods
-#they contain--this is due to the reason that they include the
-#great IO::Like module that provides all the necessary IO methods
-#based on a few methods you define. For all defined IO methods,
-#see the +io-like+ gem’s documentation.
+# Neither this class nor its subclasses document the IO-methods
+# they contain--this is due to the reason that they include the
+# great IO::Like module that provides all the necessary IO methods
+# based on a few methods you define. For all defined IO methods,
+# see the +io-like+ gem’s documentation.
 class XZ::Stream
   include IO::Like
 
-  #Creates a new instance of this class. Don’t use this directly,
-  #it’s only called by subclasses’ ::new methods.
+  # Creates a new instance of this class. Don’t use this directly,
+  # it’s only called by subclasses’ ::new methods.
   def initialize(delegate_io)
     @delegate_io    = delegate_io
     @lzma_stream    = XZ::LZMAStream.new
@@ -53,10 +55,10 @@ class XZ::Stream
 
   private
 
-  #This method returns the size of +str+ in bytes.
+  # This method returns the size of +str+ in bytes.
   def binary_size(str)
-    #Believe it or not, but this is faster than str.bytes.to_a.size.
-    #I benchmarked it, and it is as twice as fast.
+    # Believe it or not, but this is faster than str.bytes.to_a.size.
+    # I benchmarked it, and it is as twice as fast.
     if str.respond_to? :force_encoding
       str.dup.force_encoding(Encoding::BINARY).size
     else

data/lib/xz/stream_reader.rb

@@ -1,9 +1,10 @@
 # -*- coding: utf-8 -*-
+#--
 # (The MIT license)
 #
 # Basic liblzma-bindings for Ruby.
 #
-# Copyright © 2012 Marvin Gülker
+# Copyright © 2012, 2015 Marvin Gülker
 #
 # Permission is hereby granted, free of charge, to any person obtaining a
 # copy of this software and associated documentation files (the ‘Software’),
@@ -22,97 +23,166 @@
 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
+#++
 
-#An IO-like reader class for XZ-compressed data, allowing you to
-#access XZ-compressed data as if it was a normal IO object, but
-#please note you can’t seek in the data--this doesn’t make much
-#sense anyway. Where would you want to seek? The plain or the XZ
-#data?
+# An IO-like reader class for XZ-compressed data, allowing you to
+# access XZ-compressed data as if it was a normal IO object, but
+# please note you can’t seek in the data--this doesn’t make much
+# sense anyway. Where would you want to seek? The plain or the XZ
+# data?
 #
-#A StreamReader object actually wraps another IO object it reads
-#the compressed data from; you can either pass this IO object directly
-#to the ::new method, effectively allowing you to pass any IO-like thing
-#you can imagine (just ensure it is readable), or you can pass a path
-#to a filename to ::new, in which case StreamReader takes care of both
-#opening and closing the file correctly. You can even take it one step
-#further and use the block form of ::new which will automatically call
-#the #close method for you after the block finished. However, if you pass
-#an IO, remember you have to close:
+# A StreamReader object actually wraps another IO object it reads
+# the compressed data from; you can either pass this IO object directly
+# to the ::new method, effectively allowing you to pass any IO-like thing
+# you can imagine (just ensure it is readable), or you can pass a path
+# to a filename to ::open, in which case StreamReader takes care of both
+# opening and closing the file correctly. You can even take it one step
+# further and use the block form of ::new and ::open, which will automatically call
+# the #close method for you after the block finished. However, if you pass
+# an IO, remember you have to close:
 #
-#1. The StreamReader instance.
-#2. The IO object you passed to ::new.
+# 1. The StreamReader instance.
+# 2. The IO object you passed to ::new.
 #
-#Do it <b>in exactly that order</b>, otherwise you may lose data.
+# Do it <b>in exactly that order</b>, otherwise you may lose data.
 #
-#See the +io-like+ gem’s documentation for the IO-reading methods
-#available for this class (although you’re probably familiar with
-#them through Ruby’s own IO class ;-)).
+# *WARNING*: The closing behaviour described above is subject to
+# change in the next major version. In the future, wrapped IO
+# objects are automatically closed always, regardless of whether you
+# passed a filename or an IO instance. This is to sync the API with
+# Ruby’s own Zlib::GzipReader. To prevent that, call #finish instead
+# of #close.
 #
-#==Example
-#In this example, we’re going to use ruby-xz together with the
-#+archive-tar-minitar+ gem that allows to read tarballs. Used
-#together, the two libraries allow us to read XZ-compressed tarballs.
+# See the +io-like+ gem’s documentation for the IO-reading methods
+# available for this class (although you’re probably familiar with
+# them through Ruby’s own IO class ;-)).
 #
-#  require "xz"
-#  require "archive/tar/minitar"
+# ==Example
+# In this example, we’re going to use ruby-xz together with the
+# +archive-tar-minitar+ gem that allows to read tarballs. Used
+# together, the two libraries allow us to read XZ-compressed tarballs.
 #
-#  XZ::StreamReader.open("foo.tar.xz") do |txz|
-#    # This automatically closes txz
-#    Archive::Tar::Minitar.unpack(txz, "foo")
-#  end
+#   require "xz"
+#   require "archive/tar/minitar"
+#
+#   XZ::StreamReader.open("foo.tar.xz") do |txz|
+#     # This automatically closes txz
+#     Archive::Tar::Minitar.unpack(txz, "foo")
+#   end
 class XZ::StreamReader < XZ::Stream
 
-  #The memory limit you set for this reader (in ::new).
+  # The memory limit you set for this reader (in ::new).
   attr_reader :memory_limit
-  #The flags you set for this reader (in ::new).
-  attr_reader :flags
 
-  #call-seq:
-  #  new(delegate, memory_limit = XZ::LibLZMA::UINT64_MAX, flags = [:tell_unsupported_check])  → a_stream_reader
-  #  open(delegate, memory_limit = XZ::LibLZMA::UINT64_MAX, flags = [:tell_unsupported_check]) → a_stream_reader
-  #
-  #Creates a new StreamReader instance. If you pass an IO,
-  #remember you have to close *both* the resulting instance
-  #(via the #close method) and the IO object you pass to flush
-  #any internal buffers in order to be able to read all decompressed
-  #data.
-  #==Parameters
-  #[delegate] An IO object to read the data from, or a path
-  #           to a file to open. If you’re in an urgent need to
-  #           pass a plain string, use StringIO from Ruby’s
-  #           standard library. If this is an IO, it must be
-  #           opened for reading.
-  #The other parameters are identical to what the XZ::decompress_stream
-  #method expects.
-  #==Return value
-  #The newly created instance.
-  #==Example
-  #  # Wrap it around a file
-  #  f = File.open("foo.xz")
-  #  r = XZ::StreamReader.new(f)
-  #
-  #  # Ignore any XZ checksums (may result in invalid data being read!)
-  #  File.open("foo.xz") do |f|
-  #    r = XZ::StreamReader.new(f, XZ::LibLZMA::UINT64_MAX, [:tell_no_check]
-  #  end
-  #
-  #  # Let StreamReader handle file closing automatically
-  #  XZ::StreamReader.new("myfile.xz"){|r| r.raed}
-  def initialize(delegate, memory_limit = XZ::LibLZMA::UINT64_MAX, flags = [:tell_unsupported_check])
-    raise(ArgumentError, "Invalid memory limit set!") unless (0..XZ::LibLZMA::UINT64_MAX).include?(memory_limit)
-    flags.each do |flag|
-      raise(ArgumentError, "Unknown flag #{flag}!") unless [:tell_no_check, :tell_unsupported_check, :tell_any_check, :concatenated].include?(flag)
-    end
+  # The flags you set for this reader (in ::new).
+  attr_reader :flags
 
+  # call-seq:
+  #   new(delegate, opts = {}) → reader
+  #   new(delegate, opts = {}){|reader| …} → obj
+  #
+  # Creates a new StreamReader instance. If you pass an IO,
+  # remember you have to close *both* the resulting instance
+  # (via the #close method) and the IO object you pass to flush
+  # any internal buffers in order to be able to read all decompressed
+  # data (beware Deprecations section below).
+  #
+  # === Parameters
+  #
+  # [delegate]
+  #   An IO object to read the data from, If you’re in an urgent
+  #   need to pass a plain string, use StringIO from Ruby’s
+  #   standard library. If this is an IO, it must be
+  #   opened for reading.
+  #
+  # [opts]
+  #   Options hash accepting these parameters (defaults indicated
+  #   in parantheses):
+  #
+  #   [:memory_limit (LibLZMA::UINT64_MAX)]
+  #     If not XZ::LibLZMA::UINT64_MAX, makes liblzma use
+  #     no more memory than this amount of bytes.
+  #
+  #   [:flags ([:tell_unsupported_check])]
+  #     Additional flags passed to libzlma (an array). Possible
+  #     flags are:
+  #
+  #     [:tell_no_check]
+  #       Spit out a warning if the archive hasn’t an integrity
+  #       checksum.
+  #     [:tell_unsupported_check]
+  #       Spit out a warning if the archive has an unsupported
+  #       checksum type.
+  #     [:concatenated]
+  #       Decompress concatenated archives.
+  #
+  # [reader]
+  #   Block argument. self of the new instance.
+  #
+  # === Return value
+  #
+  # The block form returns the block’s last expression, the nonblock
+  # form returns the newly created instance.
+  #
+  # === Deprecations
+  #
+  # The old API for this method as it was documented in version 0.2.1
+  # still works, but is deprecated. Please change to the new API as
+  # soon as possible.
+  #
+  # *WARNING*: The closing behaviour of the block form is subject to
+  # upcoming change. In the next major release the wrapped IO *will*
+  # be automatically closed, unless you call #finish.
+  #
+  # === Example
+  #
+  #   # Wrap it around a file
+  #   f = File.open("foo.xz")
+  #   r = XZ::StreamReader.new(f)
+  #
+  #   # Ignore any XZ checksums (may result in invalid
+  #   # data being read!)
+  #   File.open("foo.xz") do |f|
+  #     r = XZ::StreamReader.new(f, :flags => [:tell_no_check])
+  #   end
+  def initialize(delegate, *args)
     if delegate.respond_to?(:to_io)
-      super(delegate)
+      # Correct use with IO
+      super(delegate.to_io)
+      @autoclose = false
     else
-      @file = File.open(delegate, "rb")
-      super(@file)
+      # Deprecated use of filename
+      XZ.deprecate "Calling XZ::StreamReader.new with a filename is deprecated, use XZ::StreamReader.open instead."
+
+      @autoclose = true
+      super(File.open(delegate, "rb"))
+    end
+
+    # Flag for calling #finish
+    @finish = false
+
+    opts = {}
+    if args[0].kind_of?(Hash) # New API
+      opts = args[0]
+      opts[:memory_limit] ||= XZ::LibLZMA::UINT64_MAX
+      opts[:flags] ||= [:tell_unsupported_check]
+    else # Old API
+      # no arguments may also happen in new API
+      unless args.empty?
+        XZ.deprecate "Calling XZ::StreamReader.new with explicit arguments is deprecated, use an options hash instead."
+      end
+
+      opts[:memory_limit] = args[0] || XZ::LibLZMA::UINT64_MAX
+      opts[:flags] = args[1] || [:tell_unsupported_check]
+    end
+
+    raise(ArgumentError, "Invalid memory limit set!") unless (0..XZ::LibLZMA::UINT64_MAX).include?(opts[:memory_limit])
+    opts[:flags].each do |flag|
+      raise(ArgumentError, "Unknown flag #{flag}!") unless [:tell_no_check, :tell_unsupported_check, :tell_any_check, :concatenated].include?(flag)
     end
 
-    @memory_limit = memory_limit
-    @flags        = flags
+    @memory_limit = opts[:memory_limit]
+    @flags        = opts[:flags]
 
     res = XZ::LibLZMA.lzma_stream_decoder(@lzma_stream,
                                           @memory_limit,
@@ -133,17 +203,98 @@ class XZ::StreamReader < XZ::Stream
       end
     end
   end
-  self.class.send(:alias_method, :open, :new)
-
-  #Closes this StreamReader instance. Don’t use it afterwards
-  #anymore.
-  #==Return value
-  #The total number of bytes decompressed.
-  #==Example
-  #  r.close #=> 6468
-  #==Remarks
-  #If you passed an IO to ::new, this method doesn’t close it, so
-  #you have to close it yourself.
+
+  # call-seq:
+  #   open(filename, opts = {}) → reader
+  #   open(filename, opts = {}){|reader| …} → obj
+  #
+  # Opens a file from disk and wraps an XZ::StreamReader instance
+  # around the resulting File IO object. This is a convenience
+  # method that is equivalent to calling
+  #
+  #   file = File.open(filename, "rb")
+  #   reader = XZ::StreamReader.new(file, opts)
+  #
+  # , except that you don’t have to explicitely close the File
+  # instance, this is done automatically when you call #close.
+  # Beware the Deprecations section in this regard.
+  #
+  # === Parameters
+  #
+  # [filename]
+  #   Path to a file on the disk to open. This file should
+  #   exist and be readable, otherwise you may get Errno
+  #   exceptions.
+  #
+  # [opts]
+  #   Options hash. See ::new for a description of the possible
+  #   options.
+  #
+  # [reader]
+  #   Block argument. self of the new instance.
+  #
+  # === Return value
+  #
+  # The block form returns the block’s last expression, the nonblock
+  # form returns the newly created XZ::StreamReader instance.
+  #
+  # === Deprecations
+  #
+  # In the API up to and including version 0.2.1 this method was an
+  # alias for ::new. This continues to work for now, but using it
+  # as an alias for ::new is deprecated. The next major version will
+  # only accept a string as a parameter for this method.
+  #
+  # *WARNING*: Future versions of ruby-xz will always close the
+  # wrapped IO, regardless of whether you pass in your own IO or use
+  # this convenience method! To prevent that, call the #finish method.
+  #
+  # === Examples
+  #
+  #   XZ::StreamReader.new("myfile.xz"){|r| r.read}
+  def self.open(filename, *args, &block)
+    if filename.respond_to?(:to_io)
+      # Deprecated use of IO
+      XZ.deprecate "Calling XZ::StreamReader.open with an IO is deprecated, use XZ::StreamReader.new instead"
+      new(filename.to_io, *args, &block)
+    else
+      # Correct use with filename
+      file = File.open(filename, "rb")
+
+      obj = new(file, *args)
+      obj.instance_variable_set(:@autoclose, true) # Only needed during deprecation phase (see #close)
+
+      if block_given?
+        begin
+          block.call(obj)
+        ensure
+          obj.close unless obj.closed?
+        end
+      else
+        obj
+      end
+    end
+  end
+
+  # Closes this StreamReader instance. Don’t use it afterwards
+  # anymore.
+  #
+  # === Return value
+  #
+  # The total number of bytes decompressed.
+  #
+  # === Example
+  #
+  #   r.close #=> 6468
+  #
+  # === Remarks
+  #
+  # If you passed an IO to ::new, this method doesn’t close it, so
+  # you have to close it yourself.
+  #
+  # *WARNING*: The next major release will change this behaviour.
+  # In the future, the wrapped IO object will always be closed.
+  # Use the #finish method for keeping it open.
   def close
     super
 
@@ -151,43 +302,98 @@ class XZ::StreamReader < XZ::Stream
     res = XZ::LibLZMA.lzma_end(@lzma_stream.pointer)
     XZ::LZMAError.raise_if_necessary(res)
 
-    #If we created a File object, close this as well.
-    @file.close if @file
+    unless @finish
+      # New API: Close the wrapped IO
+      #@delegate_io.close
+      # ↑ uncomment on API break and remove OLD API below. Note that with
+      # the new API that always closes the underlying IO, it is not necessary
+      # to distinguish a self-opened IO from a wrapped preexisting IO.
+      # The variable @autoclose can thus be removed on API break.
+
+      # Old API:
+      #If we created a File object, close this as well.
+      if @autoclose
+        # This does not change in the new API, so no deprecation warning.
+        @delegate_io.close
+      else
+        XZ.deprecate "XZ::StreamReader#close will automatically close the wrapped IO in the future. Use #finish to prevent that."
+      end
+    end
 
     # Return the number of bytes written in total.
     @lzma_stream[:total_out]
   end
 
-  #call-seq:
-  #  pos()  → an_integer
-  #  tell() → an_integer
+  # If called in the block form of ::new or ::open, prevents the
+  # wrapped IO from being closed, only the LZMA stream is closed
+  # then. If called outside the block form of ::new and open, behaves
+  # like #close, but only closes the underlying LZMA stream. The
+  # wrapped IO object is kept open.
+  #
+  # === Return value
+  #
+  # Returns the wrapped IO object. This allows you to wire the File
+  # instance out of a StreamReader instance that was created with
+  # ::open.
+  #
+  # === Example
   #
-  #Total number of output bytes provided to you yet.
+  #   # Nonblock form
+  #   f = File.open("foo.xz", "rb")
+  #   r = XZ::StreamReader.new(f)
+  #   r.finish
+  #   # f is still open here!
+  #
+  #   # Block form
+  #   str = nil
+  #   f = XZ::StreamReader.open("foo.xz") do |r|
+  #     str = r.read
+  #     r.finish
+  #   end
+  #   # f now is an *open* File instance of mode "rb".
+  def finish
+    # Do not close wrapped IO object in #close
+    @finish = true
+    close
+
+    @delegate_io
+  end
+
+  # call-seq:
+  #   pos()  → an_integer
+  #   tell() → an_integer
+  #
+  # Total number of output bytes provided to you yet.
   def pos
     @lzma_stream[:total_out]
   end
   alias tell pos
 
-  #Instrcuts liblzma to immediately stop decompression,
-  #rewinds the wrapped IO object and reinitalizes the
-  #StreamReader instance with the same values passed
-  #originally to the ::new method. The wrapped IO object
-  #must support the +rewind+ method for this method to
-  #work; if it doesn’t, this method throws an IOError.
-  #After the exception was thrown, the StreamReader instance
-  #is in an unusable state. You cannot continue using it
-  #(don’t call #close on it either); close the wrapped IO
-  #stream and create another instance of this class.
-  #==Raises
-  #[IOError] The wrapped IO doesn’t support rewinding.
-  #          Do not use the StreamReader instance anymore
-  #          after receiving this exception.
-  #==Remarks
-  #I don’t really like this method, it uses several dirty
-  #tricks to circumvent both io-like’s and liblzma’s control
-  #mechanisms. I only implemented this because the
-  #<tt>archive-tar-minitar</tt> gem calls this method when
-  #unpacking a TAR archive from a stream.
+  # Instrcuts liblzma to immediately stop decompression,
+  # rewinds the wrapped IO object and reinitalizes the
+  # StreamReader instance with the same values passed
+  # originally to the ::new method. The wrapped IO object
+  # must support the +rewind+ method for this method to
+  # work; if it doesn’t, this method throws an IOError.
+  # After the exception was thrown, the StreamReader instance
+  # is in an unusable state. You cannot continue using it
+  # (don’t call #close on it either); close the wrapped IO
+  # stream and create another instance of this class.
+  #
+  # === Raises
+  #
+  # [IOError]
+  #   The wrapped IO doesn’t support rewinding.
+  #   Do not use the StreamReader instance anymore
+  #   after receiving this exception.
+  #
+  # ==Remarks
+  #
+  # I don’t really like this method, it uses several dirty
+  # tricks to circumvent both io-like’s and liblzma’s control
+  # mechanisms. I only implemented this because the
+  # <tt>archive-tar-minitar</tt> gem calls this method when
+  # unpacking a TAR archive from a stream.
   def rewind
     # HACK: Wipe all data from io-like’s internal read buffer.
     # This heavily relies on io-like’s internal structure.
@@ -206,24 +412,24 @@ class XZ::StreamReader < XZ::Stream
       raise(IOError, "Delegate IO failed to rewind! Original message: #{e.message}")
     end
 
-    # Reinitialize everything. Note this doesn’t affect @file as it
+    # Reinitialize everything. Note this doesn’t affect @autofile as it
     # is already set and stays so (we don’t pass a filename here,
     # but rather an IO)
-    initialize(@delegate_io, @memory_limit, @flags)
+    initialize(@delegate_io, :memory_limit => @memory_limit, :flags => @flags)
   end
 
-  #NO, you CANNOT seek in this object!!
-  #io-like’s default behaviour is to raise Errno::ESPIPE
-  #when calling a non-defined seek, which is not what some
-  #libraries such as RubyGem’s TarReader expect (they expect
-  #a NoMethodError/NameError instead).
+  # NO, you CANNOT seek in this object!!
+  # io-like’s default behaviour is to raise Errno::ESPIPE
+  # when calling a non-defined seek, which is not what some
+  # libraries such as RubyGem’s TarReader expect (they expect
+  # a NoMethodError/NameError instead).
   undef seek
 
   private
 
-  #Called by io-like’s read methods such as #read. Does the heavy work
-  #of feeding liblzma the compressed data and reading the returned
-  #uncompressed data.
+  # Called by io-like’s read methods such as #read. Does the heavy work
+  # of feeding liblzma the compressed data and reading the returned
+  # uncompressed data.
   def unbuffered_read(length)
     raise(EOFError, "Input data completely processed!") if @__lzma_finished