archive-zip 0.3.0 → 0.4.0

data/lib/archive/zip.rb

@@ -1,12 +1,11 @@
-#!/usr/bin/env ruby
+# encoding: UTF-8
 
 require 'fileutils'
 require 'set'
 require 'tempfile'
 
-require 'archive/support/io'
+require 'archive/support/ioextensions'
 require 'archive/support/iowindow'
-require 'archive/support/stringio'
 require 'archive/support/time'
 require 'archive/support/zlib'
 require 'archive/zip/codec'
@@ -44,20 +43,61 @@ module Archive # :nodoc:
     DD_SIGNATURE       = "PK\x7\x8" # 0x08074b50
 
 
-    # A convenience method which opens a new or existing archive located in the
-    # path indicated by _archive_path_, adds and updates entries based on the
-    # paths given in _paths_, and then saves and closes the archive.  See the
-    # instance method #archive for more information about _paths_ and _options_.
-    def self.archive(archive_path, paths, options = {})
-      open(archive_path) { |z| z.archive(paths, options) }
+    # Creates or possibly updates an archive using _paths_ for new contents.
+    #
+    # If _archive_ is a String, it is treated as a file path which will receive
+    # the archive contents.  If the file already exists, it is assumed to be an
+    # archive and will be updated "in place".  Otherwise, a new archive
+    # is created.  The archive will be closed once written.
+    #
+    # If _archive_ has any other kind of value, it is treated as a writable
+    # IO-like object which will be left open after the completion of this
+    # method.
+    #
+    # <b>NOTE:</b> No attempt is made to prevent adding multiple entries with
+    # the same archive path.
+    #
+    # See the instance method #archive for more information about _paths_ and
+    # _options_.
+    def self.archive(archive, paths, options = {})
+      if archive.kind_of?(String) && File.exist?(archive) then
+        # Update the archive "in place".
+        tmp_archive_path = nil
+        File.open(archive) do |archive_in|
+          Tempfile.open(*File.split(archive_in.path).reverse) do |archive_out|
+            # Save off the path so that the temporary file can be renamed to the
+            # archive file later.
+            tmp_archive_path = archive_out.path
+            # Ensure the file is in binary mode for Windows.
+            archive_out.binmode
+            # Update the archive.
+            open(archive_in, :r) do |z_in|
+              open(archive_out, :w) do |z_out|
+                z_in.each  { |entry| z_out << entry }
+                z_out.archive(paths, options)
+              end
+            end
+          end
+        end
+        # Set more reasonable permissions than those set by Tempfile.
+        File.chmod(0666 & ~File.umask, tmp_archive_path)
+        # Replace the input archive with the output archive.
+        File.rename(tmp_archive_path, archive)
+      else
+        open(archive, :w) { |z| z.archive(paths, options) }
+      end
     end
 
-    # A convenience method which opens an archive located in the path indicated
-    # by _archive_path_, extracts the entries to the path indicated by
-    # _destination_, and then closes the archive.  See the instance method
-    # #extract for more information about _destination_ and _options_.
-    def self.extract(archive_path, destination, options = {})
-      open(archive_path) { |z| z.extract(destination, options) }
+    # Extracts the entries from an archive to _destination_.
+    #
+    # If _archive_ is a String, it is treated as a file path pointing to an
+    # existing archive file.  Otherwise, it is treated as a seekable and
+    # readable IO-like object.
+    #
+    # See the instance method #extract for more information about _destination_
+    # and _options_.
+    def self.extract(archive, destination, options = {})
+      open(archive, :r) { |z| z.extract(destination, options) }
     end
 
     # Calls #new with the given arguments and yields the resulting Zip instance
@@ -65,8 +105,8 @@ module Archive # :nodoc:
     # Zip instance is closed.
     #
     # This is a synonym for #new if no block is given.
-    def self.open(archive_path, archive_out = nil)
-      zf = new(archive_path, archive_out)
+    def self.open(archive, mode = :r)
+      zf = new(archive, mode)
       return zf unless block_given?
 
       begin
@@ -76,140 +116,121 @@ module Archive # :nodoc:
       end
     end
 
-    # Open and parse the file located at the path indicated by _archive_path_ if
-    # _archive_path_ is not +nil+ and the path exists. If _archive_out_ is
-    # unspecified or +nil+, any changes made will be saved in place, replacing
-    # the current archive with a new one having the same name.  If _archive_out_
-    # is a String, it points to a file which will recieve the new archive's
-    # contents.  Otherwise, _archive_out_ is assumed to be a writable, IO-like
-    # object operating in *binary* mode which will recieve the new archive's
-    # contents.
-    #
-    # At least one of _archive_path_ and _archive_out_ must be specified and
-    # non-nil; otherwise, an error will be raised.
-    def initialize(archive_path, archive_out = nil)
-      if (archive_path.nil? || archive_path.empty?) &&
-         (archive_out.nil? ||
-          archive_out.kind_of?(String) && archive_out.empty?) then
-        raise ArgumentError, 'No valid source or destination archive specified'
+    # Opens an existing archive and/or creates a new archive.
+    #
+    # If _archive_ is a String, it will be treated as a file path; otherwise, it
+    # is assumed to be an IO-like object with the necessary read or write
+    # support depending on the setting of _mode_.  IO-like objects are not
+    # closed when the archive is closed, but files opened from file paths are.
+    # Set _mode_ to <tt>:r</tt> or <tt>"r"</tt> to read the archive, and set it
+    # to <tt>:w</tt> or <tt>"w"</tt> to write the archive.
+    #
+    # <b>NOTE:</b> The #close method must be called in order to save any
+    # modifications to the archive.  Due to limitations in the Ruby finalization
+    # capabilities, the #close method is _not_ automatically called when this
+    # object is garbage collected.  Make sure to call #close when finished with
+    # this object.
+    def initialize(archive, mode = :r)
+      @archive = archive
+      mode = mode.to_sym
+      if mode == :r || mode == :w then
+        @mode = mode
+      else
+        raise ArgumentError, "illegal access mode #{mode}"
+      end
+
+      @close_delegate = false
+      if @archive.kind_of?(String) then
+        @close_delegate = true
+        if mode == :r then
+          @archive = File.open(@archive, 'rb')
+        else
+          @archive = File.open(@archive, 'wb')
+        end
       end
-      @archive_path = archive_path
-      @archive_out = archive_out
-      @entries = {}
-      @dirty = false
+      @entries = []
       @comment = ''
       @closed = false
-      if ! @archive_path.nil? && File.exist?(@archive_path) then
-        @archive_in = File.new(@archive_path, 'rb')
-        parse(@archive_in)
-      end
     end
 
     # A comment string for the ZIP archive.
     attr_accessor :comment
 
-    # Close the archive.  It is at this point that any changes made to the
-    # archive will be persisted to an output stream.
+    # Closes the archive.
+    #
+    # Failure to close the archive by calling this method may result in a loss
+    # of data for writable archives.
+    #
+    # <b>NOTE:</b> The underlying stream is only closed if the archive was
+    # opened with a String for the _archive_ parameter.
     #
     # Raises Archive::Zip::IOError if called more than once.
     def close
       raise IOError, 'closed archive' if closed?
 
-      if @dirty then
-        # There is something to write...
-        if @archive_out.nil? then
-          # Update the archive "in place".
-          tmp_archive_path = nil
-          Tempfile.open(*File.split(@archive_path).reverse) do |archive_out|
-            # Ensure the file is in binary mode for Windows.
-            archive_out.binmode
-            # Save off the path so that the temporary file can be renamed to the
-            # archive file later.
-            tmp_archive_path = archive_out.path
-            dump(archive_out)
-          end
-          File.chmod(0666 & ~File.umask, tmp_archive_path)
-        elsif @archive_out.kind_of?(String) then
-          # Open a new archive to receive the data.
-          File.open(@archive_out, 'wb') do |archive_out|
-            dump(archive_out)
-          end
-        else
-          # Assume the given object is an IO-like object and dump the archive
-          # contents to it.
-          dump(@archive_out)
-        end
-        @archive_in.close unless @archive_in.nil?
-        # The rename must happen after the original archive is closed when
-        # running on Windows since that platform does not allow a file which is
-        # in use to be replaced as is required when trying to update the archive
-        # "in place".
-        File.rename(tmp_archive_path, @archive_path) if @archive_out.nil?
-      elsif ! @archive_in.nil? then
-        @archive_in.close
+      if writable? then
+        # Write the new archive contents.
+        dump(@archive)
       end
 
-      closed = true
+      # Note that we only close delegate streams which are opened by us so that
+      # the user may do so for other delegate streams at his/her discretion.
+      @archive.close if @close_delegate
+
+      @closed = true
       nil
     end
 
-    # Returns +true+ if the ZIP archive is closed, false otherwise.
+    # Returns +true+ if the ZIP archive is closed, +false+ otherwise.
     def closed?
       @closed
     end
 
-    # When the ZIP archive is open, this method iterates through each entry in
-    # turn yielding each one to the given block.  Since Zip includes Enumerable,
-    # Zip instances are enumerables of Entry instances.
+    # Returns +true+ if the ZIP archive is readable, +false+ otherwise.
+    def readable?
+      @mode == :r
+    end
+
+    # Returns +true+ if the ZIP archive is writable, +false+ otherwise.
+    def writable?
+      @mode == :w
+    end
+
+    # Iterates through each entry of a readable ZIP archive in turn yielding
+    # each one to the given block.
     #
-    # Raises Archive::Zip::IOError if called after #close.
+    # Raises Archive::Zip::IOError if called on a non-readable archive or after
+    # the archive is closed.
     def each(&b)
-      raise IOError, 'closed archive' if @closed
+      raise IOError, 'non-readable archive' unless readable?
+      raise IOError, 'closed archive' if closed?
 
-      @entries.each_value(&b)
+      unless @parse_complete then
+        parse(@archive)
+        @parse_complete = true
+      end
+      @entries.each(&b)
     end
 
-    # Add _entry_ into the ZIP archive replacing any existing entry with the
-    # same zip path.
+    # Adds _entry_ into a writable ZIP archive.
+    #
+    # <b>NOTE:</b> No attempt is made to prevent adding multiple entries with
+    # the same archive path.
     #
-    # Raises Archive::Zip::IOError if called after #close.
+    # Raises Archive::Zip::IOError if called on a non-writable archive or after
+    # the archive is closed.
     def add_entry(entry)
-      raise IOError, 'closed archive' if @closed
+      raise IOError, 'non-writable archive' unless writable?
+      raise IOError, 'closed archive' if closed?
       unless entry.kind_of?(Entry) then
         raise ArgumentError, 'Archive::Zip::Entry instance required'
       end
 
-      @entries[entry.zip_path] = entry
-      @dirty = true
+      @entries << entry
       self
     end
     alias :<< :add_entry
 
-    # Look up an entry based on the zip path located in _zip_path_.  Returns
-    # +nil+ if no entry is found.
-    def get_entry(zip_path)
-      @entries[zip_path]
-    end
-    alias :[] :get_entry
-
-    # Removes an entry from the ZIP file and returns the entry or +nil+ if no
-    # entry was found to remove.  If _entry_ is an instance of
-    # Archive::Zip::Entry, the zip_path attribute is used to find the entry to
-    # remove; otherwise, _entry_ is assumed to be a zip path matching an entry
-    # in the ZIP archive.
-    #
-    # Raises Archive::Zip::IOError if called after #close.
-    def remove_entry(entry)
-      raise IOError, 'closed archive' if @closed
-
-      zip_path = entry
-      zip_path = entry.zip_path if entry.kind_of?(Entry)
-      entry = @entries.delete(zip_path)
-      entry = entry[1] unless entry.nil?
-      @dirty ||= ! entry.nil?
-      entry
-    end
-
     # Adds _paths_ to the archive.  _paths_ may be either a single path or an
     # Array of paths.  The files and directories referenced by _paths_ are added
     # using their respective basenames as their zip paths.  The exception to
@@ -267,10 +288,13 @@ module Archive # :nodoc:
     # Any other options which are supported by Archive::Zip::Entry.from_file are
     # also supported.
     #
-    # Raises Archive::Zip::IOError if called after #close.  Raises
-    # Archive::Zip::EntryError if the <b>:on_error</b> option is either unset or
-    # indicates that the error should be raised and
-    # Archive::Zip::Entry.from_file raises an error.
+    # <b>NOTE:</b> No attempt is made to prevent adding multiple entries with
+    # the same archive path.
+    #
+    # Raises Archive::Zip::IOError if called on a non-writable archive or after
+    # the archive is closed.  Raises Archive::Zip::EntryError if the
+    # <b>:on_error</b> option is either unset or indicates that the error should
+    # be raised and Archive::Zip::Entry.from_file raises an error.
     #
     # == Example
     #
@@ -317,7 +341,8 @@ module Archive # :nodoc:
     #                    zip-test/dir1/
     #                    zip-test/dir2/
     def archive(paths, options = {})
-      raise IOError, 'closed archive' if @closed
+      raise IOError, 'non-writable archive' unless writable?
+      raise IOError, 'closed archive' if closed?
 
       # Ensure that paths is an enumerable.
       paths = [paths] unless paths.kind_of?(Enumerable)
@@ -472,7 +497,8 @@ module Archive # :nodoc:
     # Any other options which are supported by Archive::Zip::Entry#extract are
     # also supported.
     #
-    # Raises Archive::Zip::IOError if called after #close.
+    # Raises Archive::Zip::IOError if called on a non-readable archive or after
+    # the archive is closed.
     #
     # == Example
     #
@@ -529,7 +555,8 @@ module Archive # :nodoc:
     #               +- dir1
     #               +- dir2
     def extract(destination, options = {})
-      raise IOError, 'closed archive' if @closed
+      raise IOError, 'non-readable archive' unless readable?
+      raise IOError, 'closed archive' if closed?
 
       # Ensure that unspecified options have default values.
       options[:directories] = true  unless options.has_key?(:directories)
@@ -627,23 +654,16 @@ module Archive # :nodoc:
 
     private
 
-    # <b>NOTE:</b> For now _io_ MUST be seekable and report such by returning
-    # +true+ from its seekable? method.  See IO#seekable?.
-    #
-    # Raises Archive::Zip::IOError if _io_ is not seekable.
+    # <b>NOTE:</b> For now _io_ MUST be seekable.
     def parse(io)
-      # Error out if the IO object is not confirmed seekable.
-      raise Zip::IOError, 'non-seekable IO object given' unless io.respond_to?(:seekable?) and io.seekable?
-
       socd_pos = find_central_directory(io)
       io.seek(socd_pos)
       # Parse each entry in the central directory.
       loop do
-        signature = io.readbytes(4)
+        signature = IOExtensions.read_exactly(io, 4)
         break unless signature == CFH_SIGNATURE
-        add_entry(Zip::Entry.parse(io))
+        @entries << Zip::Entry.parse(io)
       end
-      @dirty = false
       # Maybe add support for digital signatures and ZIP64 records... Later
 
       nil
@@ -665,9 +685,12 @@ module Archive # :nodoc:
       eocd_offset = -22
       loop do
         io.seek(eocd_offset, IO::SEEK_END)
-        if io.readbytes(4) == EOCD_SIGNATURE then
+        if IOExtensions.read_exactly(io, 4) == EOCD_SIGNATURE then
           io.seek(16, IO::SEEK_CUR)
-          break if io.readbytes(2).unpack('v')[0] == (eocd_offset + 22).abs
+          if IOExtensions.read_exactly(io, 2).unpack('v')[0] ==
+               (eocd_offset + 22).abs then
+            break
+          end
         end
         eocd_offset -= 1
       end
@@ -676,7 +699,7 @@ module Archive # :nodoc:
       # Now, jump into the location in the record which contains a pointer to
       # the start of the central directory record and return the value.
       io.seek(eocd_offset + 16, IO::SEEK_END)
-      return io.readbytes(4).unpack('V')[0]
+      return IOExtensions.read_exactly(io, 4).unpack('V')[0]
     rescue Errno::EINVAL
       raise Zip::UnzipError, 'unable to locate end-of-central-directory record'
     end
@@ -686,12 +709,11 @@ module Archive # :nodoc:
     # bytes written.
     def dump(io)
       bytes_written = 0
-      entries = @entries.values
-      entries.each do |entry|
+      @entries.each do |entry|
         bytes_written += entry.dump_local_file_record(io, bytes_written)
       end
       central_directory_offset = bytes_written
-      entries.each do |entry|
+      @entries.each do |entry|
         bytes_written += entry.dump_central_file_record(io)
       end
       central_directory_length = bytes_written - central_directory_offset
@@ -700,8 +722,8 @@ module Archive # :nodoc:
         [
           0,
           0,
-          entries.length,
-          entries.length,
+          @entries.length,
+          @entries.length,
           central_directory_length,
           central_directory_offset,
           comment.length

data/lib/archive/zip/codec.rb

@@ -1,3 +1,5 @@
+# encoding: UTF-8
+
 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

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

@@ -1,3 +1,5 @@
+# encoding: UTF-8
+
 require 'archive/support/zlib'
 require 'archive/zip/codec'
 require 'archive/zip/data_descriptor'
@@ -40,8 +42,17 @@ module Archive; class Zip; module Codec
       # compression to be applied to the data stream.
       def initialize(io, compression_level)
         super(io, compression_level, -Zlib::MAX_WBITS)
+        @crc32 = 0
       end
 
+      # The CRC32 checksum of the uncompressed data written using this object.
+      #
+      # <b>NOTE:</b> Anything still in the internal write buffer has not been
+      # processed, so calling #flush prior to examining this attribute may be
+      # necessary for an accurate computation.
+      attr_reader :crc32
+      alias :checksum :crc32
+
       # 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.
@@ -50,15 +61,29 @@ module Archive; class Zip; module Codec
         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.
+      # Returns an instance of Archive::Zip::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
+
+      private
+
+      def unbuffered_seek(offset, whence = IO::SEEK_SET)
+        result = super(offset, whence)
+        @crc32 = 0 if whence == IO::SEEK_SET
+        result
+      end
+
+      def unbuffered_write(string)
+        result = super(string)
+        @crc32 = Zlib.crc32(string, @crc32)
+        result
+      end
     end
 
     # Archive::Zip::Codec::Deflate::Decompress extends Zlib::ZReader in order to
@@ -92,8 +117,17 @@ module Archive; class Zip; module Codec
       # method, this class' _rewind_ method will be enabled.
       def initialize(io)
         super(io, -Zlib::MAX_WBITS)
+        @crc32 = 0
       end
 
+      # The CRC32 checksum of the uncompressed data read using this object.
+      #
+      # <b>NOTE:</b> The contents of the internal read buffer are immediately
+      # processed any time the internal buffer is filled, so this checksum is
+      # only accurate if all data has been read out of this object.
+      attr_reader :crc32
+      alias :checksum :crc32
+
       # 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.
@@ -102,14 +136,28 @@ module Archive; class Zip; module Codec
         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.
+      # Returns an instance of Archive::Zip::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
+
+      private
+
+      def unbuffered_read(length)
+        result = super(length)
+        @crc32 = Zlib.crc32(result, @crc32)
+        result
+      end
+
+      def unbuffered_seek(offset, whence = IO::SEEK_SET)
+        result = super(offset, whence)
+        @crc32 = 0 if whence == IO::SEEK_SET
+        result
+      end
     end
 
     # The numeric identifier assigned to this compression codec by the ZIP