archive-zip 0.1.0

data/lib/archive/zip/codec.rb

@@ -0,0 +1,30 @@
+module Archive; class Zip
+  # Archive::Zip::Codec is a factory class for generating codec object instances
+  # based on the compression method and general purpose flag fields of ZIP
+  # entries.  When adding a new codec, add a mapping in the _CODECS_ constant
+  # from the compression method field value reserved for the codec in the ZIP
+  # specification to the class implementing the codec.  See the implementations
+  # of Archive::Zip::Codec::Deflate and Archive::Zip::Codec::Store for details
+  # on implementing custom codecs.
+  module Codec
+    # A Hash mapping compression methods to codec implementations.  New codecs
+    # must add a mapping here when defined in order to be used.
+    CODECS = {}
+
+    # Returns a new codec instance based on _compression_method_ and
+    # _general_purpose_flags_.
+    def self.create(compression_method, general_purpose_flags)
+      CODECS[compression_method].new(general_purpose_flags)
+    end
+
+    # Returns +true+ if _compression_method_ is mapped to a codec, +false+
+    # otherwise.
+    def self.supported?(compression_method)
+      CODECS.has_key?(compression_method)
+    end
+  end
+end; end
+
+# Load the standard codecs.
+require 'archive/zip/codec/deflate'
+require 'archive/zip/codec/store'

data/lib/archive/zip/codec/deflate.rb

@@ -0,0 +1,206 @@
+require 'archive/support/zlib'
+require 'archive/zip/codec'
+require 'archive/zip/datadescriptor'
+
+module Archive; class Zip; module Codec
+  # Archive::Zip::Codec::Deflate is a handle for the deflate-inflate codec as
+  # defined in Zlib which provides convenient interfaces for writing and reading
+  # deflated streams.
+  class Deflate
+    # Archive::Zip::Codec::Deflate::Deflate extends Zlib::ZWriter in order to
+    # specify the standard Zlib options required by ZIP archives and to provide
+    # a close method which can optionally close the delegate IO-like object.  In
+    # addition a convenience method is provided for generating DataDescriptor
+    # objects based on the data which is passed through this object.
+    #
+    # Instances of this class should only be accessed via the
+    # Archive::Zip::Codec::Deflate#compressor method.
+    class Deflate < Zlib::ZWriter
+      # Creates a new instance of this class with the given arguments using #new
+      # and then passes the instance to the given block.  The #close method is
+      # guaranteed to be called after the block completes.
+      #
+      # Equivalent to #new if no block is given.
+      def self.open(io, compression_level)
+        deflate_io = new(io, compression_level)
+        return deflate_io unless block_given?
+
+        begin
+          yield(deflate_io)
+        ensure
+          deflate_io.close unless deflate_io.closed?
+        end
+      end
+
+      # Creates a new instance of this class using _io_ as a data sink.  _io_
+      # must be writable and must provide a _write_ method as IO does or errors
+      # will be raised when performing write operations.  _compression_level_
+      # must be one of Zlib::DEFAULT_COMPRESSION, Zlib::BEST_COMPRESSION,
+      # Zlib::BEST_SPEED, or Zlib::NO_COMPRESSION and specifies the amount of
+      # compression to be applied to the data stream.
+      def initialize(io, compression_level)
+        super(io, compression_level, -Zlib::MAX_WBITS)
+      end
+
+      # Closes this object so that further write operations will fail.  If
+      # _close_delegate_ is +true+, the delegate object used as a data sink will
+      # also be closed using its close method.
+      def close(close_delegate = true)
+        super()
+        delegate.close if close_delegate
+      end
+
+      # Returns an instance of Archive::Zip::Entry::DataDescriptor with
+      # information regarding the data which has passed through this object to
+      # the delegate object.  The close or flush methods should be called before
+      # using this method in order to ensure that any possibly buffered data is
+      # flushed to the delegate object; otherwise, the contents of the data
+      # descriptor may be inaccurate.
+      def data_descriptor
+        DataDescriptor.new(crc32, compressed_size, uncompressed_size)
+      end
+    end
+
+    # Archive::Zip::Codec::Deflate::Inflate extends Zlib::ZReader in order to
+    # specify the standard Zlib options required by ZIP archives and to provide
+    # a close method which can optionally close the delegate IO-like object.  In
+    # addition a convenience method is provided for generating DataDescriptor
+    # objects based on the data which is passed through this object.
+    #
+    # Instances of this class should only be accessed via the
+    # Archive::Zip::Codec::Deflate#decompressor method.
+    class Inflate < Zlib::ZReader
+      # Creates a new instance of this class with the given arguments using #new
+      # and then passes the instance to the given block.  The #close method is
+      # guaranteed to be called after the block completes.
+      #
+      # Equivalent to #new if no block is given.
+      def self.open(io)
+        inflate_io = new(io)
+        return inflate_io unless block_given?
+
+        begin
+          yield(inflate_io)
+        ensure
+          inflate_io.close unless inflate_io.closed?
+        end
+      end
+
+      # Creates a new instance of this class using _io_ as a data source.  _io_
+      # must be readable and provide a _read_ method as IO does or errors will
+      # be raised when performing read operations.  If _io_ provides a _rewind_
+      # method, this class' _rewind_ method will be enabled.
+      def initialize(io)
+        super(io, -Zlib::MAX_WBITS)
+      end
+
+      # Closes this object so that further read operations will fail.  If
+      # _close_delegate_ is +true+, the delegate object used as a data source
+      # will also be closed using its close method.
+      def close(close_delegate = true)
+        super()
+        delegate.close if close_delegate
+      end
+
+      # Returns an instance of Archive::Zip::Entry::DataDescriptor with
+      # information regarding the data which has passed through this object
+      # from the delegate object.  It is recommended to call the close method
+      # before calling this in order to ensure that no further read operations
+      # change the state of this object.
+      def data_descriptor
+        DataDescriptor.new(crc32, compressed_size, uncompressed_size)
+      end
+    end
+
+    # The numeric identifier assigned to this codec by the ZIP specification.
+    ID = 8
+
+    # Register this codec.
+    CODECS[ID] = self
+
+    # A bit mask used to denote that Zlib's default compression level should be
+    # used.
+    NORMAL = 0b000
+    # A bit mask used to denote that Zlib's highest/slowest compression level
+    # should be used.
+    MAXIMUM = 0b010
+    # A bit mask used to denote that Zlib's lowest/fastest compression level
+    # should be used.
+    FAST = 0b100
+    # A bit mask used to denote that Zlib should not compress data at all.
+    SUPER_FAST = 0b110
+
+    # This method signature is part of the interface contract expected by
+    # Archive::Zip::Entry for codec objects.
+    #
+    # Creates a new instance of this class using bits 1 and 2 of
+    # _general_purpose_flags_ to select a compression level to be used by
+    # #compressor to set up a compression IO object.  The constants NORMAL,
+    # MAXIMUM, FAST, and SUPER_FAST can be used for _general_purpose_flags_ to
+    # manually set the compression level.
+    def initialize(general_purpose_flags = NORMAL)
+      @compression_level = general_purpose_flags & 0b110
+      @zlib_compression_level = case @compression_level
+                                when NORMAL
+                                  Zlib::DEFAULT_COMPRESSION
+                                when MAXIMUM
+                                  Zlib::BEST_COMPRESSION
+                                when FAST
+                                  Zlib::BEST_SPEED
+                                when SUPER_FAST
+                                  Zlib::NO_COMPRESSION
+                                else
+                                  raise Error, 'Invalid compression level'
+                                end
+    end
+
+    # This method signature is part of the interface contract expected by
+    # Archive::Zip::Entry for codec objects.
+    #
+    # A convenience method for creating an Archive::Zip::Codec::Deflate::Deflate
+    # object using that class' open method.  The compression level for the open
+    # method is pulled from the value of the _general_purpose_flags_ argument of
+    # new.
+    def compressor(io, &b)
+      Deflate.open(io, @zlib_compression_level, &b)
+    end
+
+    # This method signature is part of the interface contract expected by
+    # Archive::Zip::Entry for codec objects.
+    #
+    # A convenience method for creating an Archive::Zip::Codec::Deflate::Inflate
+    # object using that class' open method.
+    def decompressor(io, &b)
+      Inflate.open(io, &b)
+    end
+
+    # This method signature is part of the interface contract expected by
+    # Archive::Zip::Entry for codec objects.
+    #
+    # Returns an integer which indicates the version of the official ZIP
+    # specification which introduced support for this codec.
+    def version_needed_to_extract
+      0x0014
+    end
+
+    # This method signature is part of the interface contract expected by
+    # Archive::Zip::Entry for codec objects.
+    #
+    # Returns an integer used to flag that this codec is used for a particular
+    # ZIP archive entry.
+    def compression_method
+      ID
+    end
+
+    # This method signature is part of the interface contract expected by
+    # Archive::Zip::Entry for codec objects.
+    #
+    # Returns an integer representing the general purpose flags of a ZIP archive
+    # entry where bits 1 and 2 are set according to the compression level
+    # selected for this object.  All other bits are zero'd out.
+    def general_purpose_flags
+      @compression_level
+    end
+  end
+end; end; end
+

data/lib/archive/zip/codec/store.rb

@@ -0,0 +1,241 @@
+require 'archive/support/io-like'
+require 'archive/zip/codec'
+require 'archive/zip/datadescriptor'
+
+module Archive; class Zip; module Codec
+  # Archive::Zip::Codec::Store is a handle for the store-unstore (no
+  # compression) codec.
+  class Store
+    # Archive::Zip::Codec::Store::Store is simply a writable, IO-like wrapper
+    # around a writable, IO-like object which provides a CRC32 checksum of the
+    # data written through it as well as the count of the total amount of data.
+    # A #close method is also provided which can optionally close the delegate
+    # object.  In addition a convenience method is provided for generating
+    # DataDescriptor objects based on the data which is passed through this
+    # object.
+    class Store
+      include IO::Like
+
+      # Creates a new instance of this class with the given argument using #new
+      # and then passes the instance to the given block.  The #close method is
+      # guaranteed to be called after the block completes.
+      #
+      # Equivalent to #new if no block is given.
+      def self.open(io)
+        store_io = new(io)
+        return store_io unless block_given?
+
+        begin
+          yield(store_io)
+        ensure
+          store_io.close unless store_io.closed?
+        end
+      end
+
+      # Creates a new instance of this class using _io_ as a data sink.  _io_
+      # must be writable and must provide a write method as IO does or errors
+      # will be raised when performing write operations.
+      #
+      # The _flush_size_ attribute is set to +0+ by default under the assumption
+      # that _io_ is already buffered.
+      def initialize(io)
+        @io = io
+        @crc32 = 0
+        @uncompressed_size = 0
+        # Assume that the delegate IO object is already buffered.
+        self.flush_size = 0
+      end
+
+      # Closes this object so that further write operations will fail.  If
+      # _close_delegate_ is +true+, the delegate object used as a data sink will
+      # also be closed using its close method.
+      def close(close_delegate = true)
+        super()
+        @io.close if close_delegate
+        nil
+      end
+
+      # Returns an instance of Archive::Zip::Entry::DataDescriptor with
+      # information regarding the data which has passed through this object to
+      # the delegate object.  The close or flush methods should be called before
+      # using this method in order to ensure that any possibly buffered data is
+      # flushed to the delegate object; otherwise, the contents of the data
+      # descriptor may be inaccurate.
+      def data_descriptor
+        DataDescriptor.new(
+          @crc32,
+          @uncompressed_size,
+          @uncompressed_size
+        )
+      end
+
+      private
+
+      # Writes _string_ to the delegate object and returns the number of bytes
+      # actually written.  Updates the uncompressed_size and crc32 attributes as
+      # a side effect.
+      def unbuffered_write(string)
+        bytes_written = @io.write(string)
+        @uncompressed_size += bytes_written
+        @crc32 = Zlib.crc32(string.slice(0, bytes_written), @crc32)
+        bytes_written
+      end
+    end
+
+    # Archive::Zip::Codec::Store::Unstore is a readable, IO-like wrapper around
+    # a readable, IO-like object which provides a CRC32 checksum of the data
+    # read through it as well as the count of the total amount of data.  A
+    # #close method is also provided which can optionally close the delegate
+    # object.  In addition a convenience method is provided for generating
+    # DataDescriptor objects based on the data which is passed through this
+    # object.
+    class Unstore
+      include IO::Like
+
+      # Creates a new instance of this class with the given arguments using #new
+      # and then passes the instance to the given block.  The #close method is
+      # guaranteed to be called after the block completes.
+      #
+      # Equivalent to #new if no block is given.
+      def self.open(io)
+        unstore_io = new(io)
+        return unstore_io unless block_given?
+
+        begin
+          yield(unstore_io)
+        ensure
+          unstore_io.close unless unstore_io.closed?
+        end
+      end
+
+      # Creates a new instance of this class using _io_ as a data source.  _io_
+      # must be readable and provide a read method as IO does or errors will be
+      # raised when performing read operations.  If _io_ provides a rewind
+      # method, this class' rewind method will be enabled.
+      #
+      # The _fill_size_ attribute is set to +0+ by default under the assumption
+      # that _io_ is already buffered.
+      def initialize(io)
+        @io = io
+        @crc32 = 0
+        @uncompressed_size = 0
+        # Assume that the delegate IO object is already buffered.
+        self.fill_size = 0
+      end
+
+      # Closes this object so that further read operations will fail.  If
+      # _close_delegate_ is +true+, the delegate object used as a data source
+      # will also be closed using its close method.
+      def close(close_delegate = true)
+        super()
+        @io.close if close_delegate
+        nil
+      end
+
+      # Returns an instance of Archive::Zip::Entry::DataDescriptor with
+      # information regarding the data which has passed through this object
+      # from the delegate object.  It is recommended to call the close method
+      # before calling this in order to ensure that no further read operations
+      # change the state of this object.
+      def data_descriptor
+        DataDescriptor.new(
+          @crc32,
+          @uncompressed_size,
+          @uncompressed_size
+        )
+      end
+
+      private
+
+      # Returns at most _length_ bytes from the delegate object.  Updates the
+      # uncompressed_size and crc32 attributes as a side effect.
+      def unbuffered_read(length)
+        buffer = @io.read(length)
+        if buffer.nil? then
+          raise EOFError, 'end of file reached'
+        else
+          @uncompressed_size += buffer.length
+          @crc32 = Zlib.crc32(buffer, @crc32)
+        end
+        buffer
+      end
+
+      # Allows resetting this object and the delegate object back to the
+      # beginning of the stream.  _offset_ must be +0+ and _whence_ must be
+      # IO::SEEK_SET or an error will be raised.  The delegate object must
+      # respond to the _rewind_ method or an error will be raised.  The
+      # uncompressed_size and crc32 attributes are reinitialized as a side
+      # effect.
+      def unbuffered_seek(offset, whence = IO::SEEK_SET)
+        unless offset == 0 && whence == IO::SEEK_SET then
+          raise Errno::EINVAL, 'Invalid argument'
+        end
+        unless @io.respond_to?(:rewind) then
+          raise Errno::ESPIPE, 'Illegal seek'
+        end
+        @io.rewind
+        @crc32 = 0
+        @uncompressed_size = 0
+      end
+    end
+
+    # The numeric identifier assigned to this codec by the ZIP specification.
+    ID = 0
+
+    # Register this codec.
+    CODECS[ID] = self
+
+    # This method signature is part of the interface contract expected by
+    # Archive::Zip::Entry for codec objects.
+    #
+    # Creates a new instance of this class.  _general_purpose_flags_ is not
+    # used.
+    def initialize(general_purpose_flags = 0)
+    end
+
+    # This method signature is part of the interface contract expected by
+    # Archive::Zip::Entry for codec objects.
+    #
+    # A convenience method for creating an Archive::Zip::Codec::Store::Store
+    # object using that class' open method.
+    def compressor(io, &b)
+      Store.open(io, &b)
+    end
+
+    # This method signature is part of the interface contract expected by
+    # Archive::Zip::Entry for codec objects.
+    #
+    # A convenience method for creating an Archive::Zip::Codec::Store::Unstore
+    # object using that class' open method.
+    def decompressor(io, &b)
+      Unstore.open(io, &b)
+    end
+
+    # This method signature is part of the interface contract expected by
+    # Archive::Zip::Entry for codec objects.
+    #
+    # Returns an integer which indicates the version of the official ZIP
+    # specification which introduced support for this codec.
+    def version_needed_to_extract
+      0x000a
+    end
+
+    # This method signature is part of the interface contract expected by
+    # Archive::Zip::Entry for codec objects.
+    #
+    # Returns an integer used to flag that this codec is used for a particular
+    # ZIP archive entry.
+    def compression_method
+      ID
+    end
+
+    # This method signature is part of the interface contract expected by
+    # Archive::Zip::Entry for codec objects.
+    #
+    # Returns +0+ since this codec does not make use of general purpose flags of
+    # ZIP archive entries.
+    def general_purpose_flags
+      0
+    end
+  end
+end; end; end