ruby-xz 0.2.1 → 1.0.1

data/lib/xz/stream_writer.rb

@@ -1,9 +1,10 @@
 # -*- coding: utf-8 -*-
-# (The MIT license)
-#
+#--
 # Basic liblzma-bindings for Ruby.
 #
-# Copyright © 2012 Marvin Gülker
+# Copyright © 2011-2018 Marvin Gülker et al.
+#
+# See AUTHORS for the full list of contributors.
 #
 # Permission is hereby granted, free of charge, to any person obtaining a
 # copy of this software and associated documentation files (the ‘Software’),
@@ -22,194 +23,243 @@
 # 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 writer class for XZ-compressed data, allowing you to write
-#uncompressed data to a stream which ends up as compressed data in
-#a wrapped stream such as a file.
-#
-#A StreamWriter object actually wraps another IO object it writes the
-#XZ-compressed data to. Here’s an ASCII art image to demonstrate
-#way data flows when using StreamWriter to write to a compressed
-#file:
+# An IO-like writer class for XZ-compressed data, allowing you to
+# write uncompressed data to a stream which ends up as compressed data
+# in a wrapped stream such as a file.
 #
-#          +----------------+  +------------+
-#  YOUR  =>|StreamWriter's  |=>|Wrapped IO's|=> ACTUAL
-#  DATA  =>|internal buffers|=>|buffers     |=>  FILE
-#          +----------------+  +------------+
+# A StreamWriter object actually wraps another IO object it writes the
+# XZ-compressed data to. Here’s an ASCII art image to demonstrate way
+# data flows when using StreamWriter to write to a compressed file:
 #
-#This graphic also illustrates why it is unlikely to see written
-#data directly appear in the file on your harddisk; the data is
-#cached at least twice before it actually gets written out. Regarding
-#file closing that means that before you can be sure any pending data
-#has been written to the file you have to close both the StreamWriter
-#instance and then the wrapped IO object (in *exactly* that order, otherwise
-#data loss and unexpected exceptions may occur!).
+#           +-----------------+  +------------+
+#   YOUR  =>|StreamWriter's   |=>|Wrapped IO's|=> ACTUAL
+#   DATA  =>|(liblzma) buffers|=>|buffers     |=>  FILE
+#           +-----------------+  +------------+
 #
-#As it might be tedious to always remember the correct closing order,
-#it’s possible to pass a filename to the ::new method. In this case,
-#StreamWriter will open the file internally and also takes care closing
-#it when you call the #close method.
+# This graphic also illustrates why it is unlikely to see written data
+# directly appear in the file on your harddisk; the data is cached at
+# least twice before it actually gets written out. Regarding file
+# closing that means that before you can be sure any pending data has
+# been written to the file you have to close both the StreamWriter
+# instance and then the wrapped IO object (in *exactly* that order,
+# otherwise data loss and unexpected exceptions may occur!).
 #
-#See the +io-like+ gem’s documentation for the IO-writing methods
-#available for this class (although you’re probably familiar with
-#them through Ruby’s own IO class ;-)).
+# Calling the #close method closes both the XZ writer and the
+# underlying IO object in the correct order. This is akin to the
+# behaviour exposed by Ruby's own Zlib::GzipWriter class. If you
+# expressly don't want to close the underlying IO instance, you need
+# to manually call StreamWriter#finish and never call
+# StreamWriter#close. Instead, you then close your IO object manually
+# using IO#close once you're done with it.
 #
-#==Example
-#Together with the <tt>archive-tar-minitar</tt> gem, this library
-#can be used to create XZ-compressed TAR archives (these commonly
-#use a file extension of <tt>.tar.xz</tt> or rarely <tt>.txz</tt>).
-#
-#  XZ::StreamWriter.open("foo.tar.xz") do |txz|
-#    # This automatically closes txz
-#    Archive::Tar::Minitar.pack("foo", txz)
-#  end
+# *NOTE*: Using #finish inside the +open+ method's block allows
+# you to continue using that writer's File instance as it is
+# returned by #finish.
 class XZ::StreamWriter < XZ::Stream
 
-  #call-seq:
-  # open(delegate, compression_level = 6, check = :crc64, extreme = false) → a_stream_writer
-  # new(delegate, compression_level = 6, check = :crc64, extreme = false)  → a_stream_writer
-  #
-  #Creates a new StreamWriter instance. The block form automatically
-  #calls the #close method when the block has finished executing.
-  #==Parameters
-  #[delegate] An IO object to write the data to or a filename
-  #           which will be opened internally. If you pass an IO,
-  #           the #close method won’t close the passed IO object;
-  #           if you passed a filename, the created internal file
-  #           of course gets closed.
-  #The other parameters are identical to what the XZ::compress_stream
-  #method expects.
-  #==Return value
-  #The newly created instance.
-  #==Example
-  #  # Wrap it around a file
-  #  f = File.open("data.xz")
-  #  w = XZ::StreamWriter.new(f)
-  #
-  #  # Use SHA256 as the checksum and use a higher compression level
-  #  # than the default (6)
-  #  f = File.open("data.xz")
-  #  w = XZ::StreamWriter.new(f, 8, :sha256)
-  #
-  #  # Instruct liblzma to use ultra-really-high compression
-  #  # (may take eternity)
-  #  f = File.open("data.xz")
-  #  w = XZ::StreamWriter.new(f, 9, :crc64, true)
-  #
-  #  # Passing a filename
-  #  w = XZ::StreamWriter.new("compressed_data.xz")
-  def initialize(delegate, compression_level = 6, check = :crc64, extreme = false)
-    if delegate.respond_to?(:to_io)
-      super(delegate)
-    else
-      @file = File.open(delegate, "wb")
-      super(@file)
-    end
+  # Compression level used for this writer (set on instanciation).
+  attr_reader :level
+  # Checksum algorithm in use.
+  attr_reader :check
 
-    # Initialize the internal LZMA stream for encoding
-    res = XZ::LibLZMA.lzma_easy_encoder(@lzma_stream.pointer,
-                                  compression_level | (extreme ? XZ::LibLZMA::LZMA_PRESET_EXTREME : 0),
-                                  XZ::LibLZMA::LZMA_CHECK[:"lzma_check_#{check}"])
-    XZ::LZMAError.raise_if_necessary(res)
+  # call-seq:
+  #   open(filename [, compression_level = 6 [, options ]]) → stream_writer
+  #   open(filename [, compression_level = 6 [, options ]]){|sw| ...} → stream_writer
+  #
+  # Creates a new instance for writing to a compressed file. The File
+  # instance is opened internally and then wrapped via ::new. The
+  # block form automatically closes both the liblzma stream and the
+  # internal File instance in the correct order. The non-block form
+  # does neither, leaving it to you to call #finish or #close later.
+  #
+  # === Parameters
+  # [filename]
+  #   The file to open.
+  # [sw (block argument)]
+  #   The created StreamWriter instance.
+  #
+  # See ::new for the other parameters.
+  #
+  # === Return value
+  # Returns the newly created instance.
+  #
+  # === Remarks
+  # Starting with version 1.0.0, the block form also returns the newly
+  # created instance rather than the block's return value. This is
+  # in line with Ruby's own GzipWriter.open API.
+  #
+  # === Example
+  #     # Normal usage
+  #     XZ::StreamWriter.open("myfile.txt.xz") do |xz|
+  #       xz.puts "Compress this line"
+  #       xz.puts "And this line as well"
+  #     end
+  #
+  #     # If for whatever reason you want to do something else with
+  #     # the internally opened file:
+  #     file = nil
+  #     XZ::StreamWriter.open("myfile.txt.xz") do |xz|
+  #       xz.puts "Compress this line"
+  #       xz.puts "And this line as well"
+  #       file = xz.finish
+  #     end
+  #     # At this point, the liblzma stream has been closed, but `file'
+  #     # now contains the internally created File instance, which is
+  #     # still open. Don't forget to close it yourself at some point
+  #     # to flush it.
+  #     file.close
+  #
+  #     # Or just don't use the block form:
+  #     xz = StreamWriter.open("myfile.txt.xz")
+  #     xz.puts "Compress this line"
+  #     xz.puts "And this line as well"
+  #     file = xz.finish
+  #     file.close # Don't forget to close it manually (or use xz.close instead of xz.finish above)
+  def self.open(filename, **args)
+    file = File.open(filename, "wb")
+    writer = new(file, **args)
 
     if block_given?
       begin
-        yield(self)
+        yield(writer)
       ensure
-        close unless closed?
+        # Close both writer and delegate IO via writer.close
+        # unless the writer has manually been finished (usually
+        # not closing the delegate IO then).
+        writer.close unless writer.finished?
       end
     end
-  end
-  self.class.send(:alias_method, :open, :new)
-
-  #Closes this StreamWriter instance and flushes all internal buffers.
-  #Don’t use it afterwards anymore.
-  #==Return vaule
-  #The total number of bytes written, i.e. the size of the compressed
-  #data.
-  #==Example
-  #  w.close #=> 424
-  #==Remarks
-  #If you passed an IO object to ::new, this method doesn’t close it,
-  #you have to do that yourself.
-  def close
-    super
 
-    #1. Close the current block ("file") (an XZ stream may actually include
-    #   multiple compressed files, which however is not supported by
-    #   this library). For this we have to tell liblzma that
-    #   the next bytes we pass to it are the last bytes (by means of
-    #   the FINISH action). Just that we don’t pass any new input ;-)
-
-    output_buffer_p         = FFI::MemoryPointer.new(XZ::CHUNK_SIZE)
+    writer
+  end
 
-    # Get any pending data (LZMA_FINISH causes libzlma to flush its
-    # internal buffers) and write it out to our wrapped IO.
-    loop do
-      @lzma_stream[:next_out]  = output_buffer_p
-      @lzma_stream[:avail_out] = output_buffer_p.size
+  # Creates a new instance that is wrapped around the given IO instance.
+  #
+  # === Parameters
+  # ==== Positional parameters
+  # [delegate_io]
+  #   The IO instance to wrap. It has to be opened in binary mode,
+  #   otherwise the data it writes to the hard disk will be corrupt.
+  #
+  # ==== Keyword arguments
+  # [compression_level (6)]
+  #   Compression strength. Higher values indicate a
+  #   smaller result, but longer compression time. Maximum
+  #   is 9.
+  # [:check (:crc64)]
+  #   The checksum algorithm to use for verifying
+  #   the data inside the archive. Possible values are:
+  #   * :none
+  #   * :crc32
+  #   * :crc64
+  #   * :sha256
+  # [:extreme (false)]
+  #   Tries to get the last bit out of the
+  #   compression. This may succeed, but you can end
+  #   up with *very* long computation times.
+  # [:external_encoding (Encoding.default_external)]
+  #   Transcode to this encoding when writing. Defaults
+  #   to Encoding.default_external, which by default is
+  #   set from the environment.
+  #
+  # === Return value
+  # Returns the newly created instance.
+  #
+  # === Remarks
+  # This method does not close the underlying IO nor does it automatically
+  # flush libzlma. You'll need to do that manually using #close or #finish.
+  # See ::open for a method that supports a block with auto-closing.
+  #
+  # This method used to accept a block in earlier versions. This
+  # behaviour has been removed in version 1.0.0 to synchronise the API
+  # with Ruby's own GzipWriter.new.
+  #
+  # === Example
+  #     # Normal usage:
+  #     file = File.open("myfile.txt.xz", "wb") # Note binary mode
+  #     xz = XZ::StreamWriter.new(file)
+  #     xz.puts("Compress this line")
+  #     xz.puts("And this second line")
+  #     xz.close # Closes both the libzlma stream and `file'
+  #
+  #     # Expressly closing the delegate IO manually:
+  #     File.open("myfile.txt.xz", "wb") do |file| # Note binary mode
+  #       xz = XZ::StreamWriter.new(file)
+  #       xz.puts("Compress this line")
+  #       xz.puts("And this second line")
+  #       xz.finish # Flushes libzlma, but keeps `file' open.
+  #     end # Here, `file' is closed.
+  def initialize(delegate_io, level: 6, check: :crc64, extreme: false, external_encoding: nil)
+    super(delegate_io)
 
-      res = XZ::LibLZMA.lzma_code(@lzma_stream.pointer, XZ::LibLZMA::LZMA_ACTION[:lzma_finish])
-      XZ::LZMAError.raise_if_necessary(res)
+    raise(ArgumentError, "Invalid compression level!")  unless (0..9).include?(level)
+    raise(ArgumentError, "Invalid checksum specified!") unless [:none, :crc32, :crc64, :sha256].include?(check)
 
-      @delegate_io.write(output_buffer_p.read_string(output_buffer_p.size - @lzma_stream[:avail_out]))
+    set_encoding(external_encoding) if external_encoding
 
-      break unless @lzma_stream[:avail_out] == 0
-    end
+    @check  = check
+    @level  = level
+    @level |= LibLZMA::LZMA_PRESET_EXTREME if extreme
 
-    #2. Close the whole XZ stream.
-    res = XZ::LibLZMA.lzma_end(@lzma_stream.pointer)
+    res = XZ::LibLZMA.lzma_easy_encoder(@lzma_stream.to_ptr,
+                                    @level,
+                                    XZ::LibLZMA.const_get(:"LZMA_CHECK_#{@check.upcase}"))
     XZ::LZMAError.raise_if_necessary(res)
+  end
 
-    #2b. If we wrapped a file automatically, close it.
-    @file.close if @file
+  # Mostly like IO#write. Additionally it raises an IOError
+  # if #finish has been called previously.
+  def write(*args)
+    raise(IOError, "Cannot write to a finished liblzma stream") if @finished
 
-    #3. Return the number of bytes written in total.
-    @lzma_stream[:total_out]
-  end
+    origpos = @pos
 
-  #call-seq:
-  #  pos()  → an_integer
-  #  tell() → an_integer
-  #
-  #Total number of input bytes read so far from what you
-  #supplied to any writer method.
-  def pos
-    @lzma_stream[:total_in]
-  end
-  alias tell pos
+    args.each do |arg|
+      @pos += arg.to_s.bytesize
 
-  private
+      # Apply external encoding if requested
+      if @external_encoding && @external_encoding != Encoding::BINARY
+        arg = arg.to_s.encode(@external_encoding)
+      end
 
-  #Called by io-like’s write methods such as #write. Does the heavy
-  #work of feeding liblzma the uncompressed data and reading the
-  #returned compressed data.
-  def unbuffered_write(data)
-    output_buffer_p = FFI::MemoryPointer.new(XZ::CHUNK_SIZE)
-    input_buffer_p  = FFI::MemoryPointer.from_string(data) # This adds a terminating NUL byte we don’t want to compress!
+      lzma_code(arg.to_s, XZ::LibLZMA::LZMA_RUN) do |compressed|
+        @delegate_io.write(compressed)
+      end
+    end
 
-    @lzma_stream[:next_in]  = input_buffer_p
-    @lzma_stream[:avail_in] = input_buffer_p.size - 1 # Don’t hand the terminating NUL
+    @pos - origpos # Return number of bytes consumed from input
+  end
 
-    loop do
-      @lzma_stream[:next_out]  = output_buffer_p
-      @lzma_stream[:avail_out] = output_buffer_p.size
+  # Like superclass' method, but also ensures liblzma flushes all
+  # compressed data to the delegate IO.
+  def finish
+    lzma_code("", XZ::LibLZMA::LZMA_FINISH) { |compressed| @delegate_io.write(compressed) }
+    super
+  end
 
-      # Compress the data
-      res = XZ::LibLZMA.lzma_code(@lzma_stream.pointer, XZ::LibLZMA::LZMA_ACTION[:lzma_run])
-      XZ::LZMAError.raise_if_necessary(res) # TODO: Warnings
+  # Abort the current compression process and reset everything
+  # to the start. Writing into this writer will cause existing data
+  # on the underlying IO to be overwritten after this method has been
+  # called.
+  #
+  # The delegte IO has to support the #rewind method. Otherwise like
+  # IO#rewind.
+  def rewind
+    super
 
-      # Write the compressed data
-      result = output_buffer_p.read_string(output_buffer_p.size - @lzma_stream[:avail_out])
-      @delegate_io.write(result)
+    res = XZ::LibLZMA.lzma_easy_encoder(@lzma_stream.to_ptr,
+                                    @level,
+                                    XZ::LibLZMA.const_get(:"LZMA_CHECK_#{@check.upcase}"))
+    XZ::LZMAError.raise_if_necessary(res)
 
-      # Loop until liblzma ate the whole data.
-      break if @lzma_stream[:avail_in] == 0
-    end
+    0 # Mimic IO#rewind's return value
+  end
 
-    binary_size(data)
-  rescue XZ::LZMAError => e
-    raise(SystemCallError, e.message)
+  # Human-readable description
+  def inspect
+    "<#{self.class} pos=#{@pos} finished=#{@finished} closed=#{closed?} io=#{@delegate_io.inspect}>"
   end
 
 end

data/lib/xz/version.rb

@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+#--
+# Basic liblzma-bindings for Ruby.
+#
+# Copyright © 2011-2018 Marvin Gülker et al.
+#
+# See AUTHORS for the full list of contributors.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the ‘Software’),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the Software
+# is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# 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
+
+  # The version of this library.
+  VERSION = "1.0.1".freeze
+
+end