Class: Zip::ZipFile

Class

Zip::ZipFile

In:

lib/zip/zipfilesystem.rb
lib/zip/zip.rb

Parent:

Object

ZipFile is modeled after java.util.zip.ZipFile from the Java SDK. The most important methods are those inherited from ZipCentralDirectory for accessing information about the entries in the archive and methods such as get_input_stream and get_output_stream for reading from and writing entries to the archive. The class includes a few convenience methods such as extract for extracting entries to the filesystem, and remove, replace, rename and mkdir for making simple modifications to the archive.

Modifications to a zip archive are not committed until commit or close is called. The method open accepts a block following the pattern from File.open offering a simple way to automatically close the archive when the block returns.

The following example opens zip archive my.zip (creating it if it doesn‘t exist) and adds an entry first.txt and a directory entry a_dir to it.

  require 'zip/zip'

  Zip::ZipFile.open("my.zip", Zip::ZipFile::CREATE) {
   |zipfile|
    zipfile.get_output_stream("first.txt") { |f| f.puts "Hello from ZipFile" }
    zipfile.mkdir("a_dir")
  }

The next example reopens my.zip writes the contents of first.txt to standard out and deletes the entry from the archive.

  require 'zip/zip'

  Zip::ZipFile.open("my.zip", Zip::ZipFile::CREATE) {
    |zipfile|
    puts zipfile.read("first.txt")
    zipfile.remove("first.txt")
  }

ZipFileSystem offers an alternative API that emulates ruby‘s interface for accessing the filesystem, ie. the File and Dir classes.

Methods

add close commit commit_required? extract find_entry foreach get_entry get_input_stream get_output_stream mkdir new open read remove rename replace to_s

Included Modules

ZipFileSystem

Constants

CREATE = 1

Attributes

comment	[RW]	Returns the zip files comment, if it has one
name	[R]
restore_ownership	[RW]	default -> false
restore_permissions	[RW]	default -> false
restore_times	[RW]	default -> true

Public Class methods

foreach(aZipFileName, &block)

Iterates over the contents of the ZipFile. This is more efficient than using a ZipInputStream since this methods simply iterates through the entries in the central directory structure in the archive whereas ZipInputStream jumps through the entire archive accessing the local entry headers (which contain the same information as the central directory).

# File lib/zip/zip.rb, line 1431
    def ZipFile.foreach(aZipFileName, &block)
      ZipFile.open(aZipFileName) {
        |zipFile|
        zipFile.each(&block)
      }
    end

new(fileName, create = nil)

Opens a zip archive. Pass true as the second parameter to create a new archive if it doesn‘t exist already.

# File lib/zip/zip.rb, line 1387
    def initialize(fileName, create = nil)
      super()
      @name = fileName
      @comment = ""
      if (File.exists?(fileName))
        File.open(name, "rb") { |f| read_from_stream(f) }
      elsif (create)
        @entrySet = ZipEntrySet.new
      else
        raise ZipError, "File #{fileName} not found"
      end
      @create = create
      @storedEntries = @entrySet.dup

      @restore_ownership = false
      @restore_permissions = false
      @restore_times = true
    end

open(fileName, create = nil) {|zf| ...}

Same as new. If a block is passed the ZipFile object is passed to the block and is automatically closed afterwards just as with ruby‘s builtin File.open method.

# File lib/zip/zip.rb, line 1409
    def ZipFile.open(fileName, create = nil)
      zf = ZipFile.new(fileName, create)
      if block_given?
        begin
          yield zf
        ensure
          zf.close
        end
      else
        zf
      end
    end

Public Instance methods

add(entry, srcPath, &continueOnExistsProc)

Convenience method for adding the contents of a file to the archive

# File lib/zip/zip.rb, line 1470
    def add(entry, srcPath, &continueOnExistsProc)
      continueOnExistsProc ||= proc { false }
      check_entry_exists(entry, continueOnExistsProc, "add")
      newEntry = entry.kind_of?(ZipEntry) ? entry : ZipEntry.new(@name, entry.to_s)
      newEntry.gather_fileinfo_from_srcpath(srcPath)
      @entrySet << newEntry
    end

Closes the zip file committing any changes that has been made.

# File lib/zip/zip.rb, line 1524
    def close
      commit
    end

Commits changes that has been made since the previous commit to the zip archive.

# File lib/zip/zip.rb, line 1508
    def commit
     return if ! commit_required?
      on_success_replace(name) {
        |tmpFile|
        ZipOutputStream.open(tmpFile) {
          |zos|

          @entrySet.each { |e| e.write_to_zip_output_stream(zos) }
          zos.comment = comment
        }
        true
      }
      initialize(name)
    end

commit_required?()

Returns true if any changes has been made to this archive since the previous commit

# File lib/zip/zip.rb, line 1530
    def commit_required?
      return @entrySet != @storedEntries || @create == ZipFile::CREATE
    end

extract(entry, destPath, &onExistsProc)

Extracts entry to file destPath.

# File lib/zip/zip.rb, line 1500
    def extract(entry, destPath, &onExistsProc)
      onExistsProc ||= proc { false }
      foundEntry = get_entry(entry)
      foundEntry.extract(destPath, &onExistsProc)
    end

find_entry(entry)

Searches for entry with the specified name. Returns nil if no entry is found. See also get_entry

# File lib/zip/zip.rb, line 1536
    def find_entry(entry)
      @entrySet.detect { 
        |e| 
        e.name.sub(/\/$/, "") == entry.to_s.sub(/\/$/, "")
      }
    end

get_entry(entry)

Searches for an entry just as find_entry, but throws Errno::ENOENT if no entry is found.

# File lib/zip/zip.rb, line 1545
    def get_entry(entry)
      selectedEntry = find_entry(entry)
      unless selectedEntry
        raise Errno::ENOENT, entry
      end
      selectedEntry.restore_ownership = @restore_ownership
      selectedEntry.restore_permissions = @restore_permissions
      selectedEntry.restore_times = @restore_times

      return selectedEntry
    end

get_input_stream(entry, &aProc)

Returns an input stream to the specified entry. If a block is passed the stream object is passed to the block and the stream is automatically closed afterwards just as with ruby‘s builtin File.open method.

# File lib/zip/zip.rb, line 1441
    def get_input_stream(entry, &aProc)
      get_entry(entry).get_input_stream(&aProc)
    end

get_output_stream(entry, &aProc)

Returns an output stream to the specified entry. If a block is passed the stream object is passed to the block and the stream is automatically closed afterwards just as with ruby‘s builtin File.open method.

# File lib/zip/zip.rb, line 1448
    def get_output_stream(entry, &aProc)
      newEntry = entry.kind_of?(ZipEntry) ? entry : ZipEntry.new(@name, entry.to_s)
      if newEntry.directory?
        raise ArgumentError,
          "cannot open stream to directory entry - '#{newEntry}'"
      end
      zipStreamableEntry = ZipStreamableStream.new(newEntry)
      @entrySet << zipStreamableEntry
      zipStreamableEntry.get_output_stream(&aProc)      
    end

mkdir(entryName, permissionInt = 0755)

Creates a directory

# File lib/zip/zip.rb, line 1558
    def mkdir(entryName, permissionInt = 0755)
      if find_entry(entryName)
        raise Errno::EEXIST, "File exists - #{entryName}"
      end
      @entrySet << ZipStreamableDirectory.new(@name, entryName.to_s.ensure_end("/"), nil, permissionInt)
    end

Returns a string containing the contents of the specified entry

# File lib/zip/zip.rb, line 1465
    def read(entry)
      get_input_stream(entry) { |is| is.read } 
    end

Removes the specified entry.

# File lib/zip/zip.rb, line 1479
    def remove(entry)
      @entrySet.delete(get_entry(entry))
    end

rename(entry, newName, &continueOnExistsProc)

Renames the specified entry.

# File lib/zip/zip.rb, line 1484
    def rename(entry, newName, &continueOnExistsProc)
      foundEntry = get_entry(entry)
      check_entry_exists(newName, continueOnExistsProc, "rename")
      @entrySet.delete(foundEntry)
      foundEntry.name = newName
      @entrySet << foundEntry
    end

replace(entry, srcPath)

Replaces the specified entry with the contents of srcPath (from the file system).

# File lib/zip/zip.rb, line 1494
    def replace(entry, srcPath)
      check_file(srcPath)
      add(remove(entry), srcPath)
    end

Returns the name of the zip archive

# File lib/zip/zip.rb, line 1460
    def to_s
      @name
    end