class Zip::File

Zip::File is modeled after java.util.zip.ZipFile from the Java SDK. The most important methods are those 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::File.open(‘my.zip’, create: true) do |zipfile|

zipfile.get_output_stream('first.txt') { |f| f.puts 'Hello from Zip::File' }
zipfile.mkdir('a_dir')

end “‘

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::File.open(‘my.zip’, create: true) do |zipfile|

puts zipfile.read('first.txt')
zipfile.remove('first.txt')

end

Zip::FileSystem offers an alternative API that emulates ruby’s interface for accessing the filesystem, ie. the ::File and ::Dir classes.

Attributes

name[R]

The name of this zip archive.

restore_ownership[RW]

default -> false.

restore_permissions[RW]

default -> true.

restore_times[RW]

default -> true.

Public Class Methods

count_entries(path_or_io) click to toggle source

Count the entries in a zip archive without reading the whole set of entry data into memory.

# File lib/zip/file.rb, line 170
def count_entries(path_or_io)
  cdir = ::Zip::CentralDirectory.new

  if path_or_io.kind_of?(String)
    ::File.open(path_or_io, 'rb') do |f|
      cdir.count_entries(f)
    end
  else
    cdir.count_entries(path_or_io)
  end
end

foreach(zip_file_name, &block) click to toggle source

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/file.rb, line 162
def foreach(zip_file_name, &block)
  ::Zip::File.open(zip_file_name) do |zip_file|
    zip_file.each(&block)
  end
end

new(path_or_io, create: false, buffer: false, restore_ownership: DEFAULT_RESTORE_OPTIONS[:restore_ownership], restore_permissions: DEFAULT_RESTORE_OPTIONS[:restore_permissions], restore_times: DEFAULT_RESTORE_OPTIONS[:restore_times], compression_level: ::Zip.default_compression, suppress_extra_fields: false) click to toggle source

Opens a zip archive. Pass create: true to create a new archive if it doesn’t exist already.

Calls superclass method

# File lib/zip/file.rb, line 75
def initialize(path_or_io, create: false, buffer: false,
               restore_ownership: DEFAULT_RESTORE_OPTIONS[:restore_ownership],
               restore_permissions: DEFAULT_RESTORE_OPTIONS[:restore_permissions],
               restore_times: DEFAULT_RESTORE_OPTIONS[:restore_times],
               compression_level: ::Zip.default_compression,
               suppress_extra_fields: false)
  super()

  @name    = path_or_io.respond_to?(:path) ? path_or_io.path : path_or_io
  @create  = create ? true : false # allow any truthy value to mean true

  initialize_cdir(path_or_io, buffer: buffer)

  @restore_ownership     = restore_ownership
  @restore_permissions   = restore_permissions
  @restore_times         = restore_times
  @compression_level     = compression_level
  @suppress_extra_fields = suppress_extra_fields
end

open(file_name, create: false, restore_ownership: DEFAULT_RESTORE_OPTIONS[:restore_ownership], restore_permissions: DEFAULT_RESTORE_OPTIONS[:restore_permissions], restore_times: DEFAULT_RESTORE_OPTIONS[:restore_times], compression_level: ::Zip.default_compression, suppress_extra_fields: false) { |zf| ... } click to toggle source

Similar to ::new. If a block is passed the Zip::File object is passed to the block and is automatically closed afterwards, just as with ruby’s builtin File::open method.

# File lib/zip/file.rb, line 99
def open(file_name, create: false,
         restore_ownership: DEFAULT_RESTORE_OPTIONS[:restore_ownership],
         restore_permissions: DEFAULT_RESTORE_OPTIONS[:restore_permissions],
         restore_times: DEFAULT_RESTORE_OPTIONS[:restore_times],
         compression_level: ::Zip.default_compression,
         suppress_extra_fields: false)
  zf = ::Zip::File.new(file_name, create:                create,
                                  restore_ownership:     restore_ownership,
                                  restore_permissions:   restore_permissions,
                                  restore_times:         restore_times,
                                  compression_level:     compression_level,
                                  suppress_extra_fields: suppress_extra_fields)

  return zf unless block_given?

  begin
    yield zf
  ensure
    zf.close
  end
end

open_buffer(io = ::StringIO.new, create: false, restore_ownership: DEFAULT_RESTORE_OPTIONS[:restore_ownership], restore_permissions: DEFAULT_RESTORE_OPTIONS[:restore_permissions], restore_times: DEFAULT_RESTORE_OPTIONS[:restore_times], compression_level: ::Zip.default_compression, suppress_extra_fields: false) { |zf| ... } click to toggle source

Like open, but reads zip archive contents from a String or open IO stream, and outputs data to a buffer. (This can be used to extract data from a downloaded zip archive without first saving it to disk.)

# File lib/zip/file.rb, line 125
def open_buffer(io = ::StringIO.new, create: false,
                restore_ownership: DEFAULT_RESTORE_OPTIONS[:restore_ownership],
                restore_permissions: DEFAULT_RESTORE_OPTIONS[:restore_permissions],
                restore_times: DEFAULT_RESTORE_OPTIONS[:restore_times],
                compression_level: ::Zip.default_compression,
                suppress_extra_fields: false)
  unless IO_METHODS.map { |method| io.respond_to?(method) }.all? || io.kind_of?(String)
    raise 'Zip::File.open_buffer expects a String or IO-like argument' \
          "(responds to #{IO_METHODS.join(', ')}). Found: #{io.class}"
  end

  io = ::StringIO.new(io) if io.kind_of?(::String)

  zf = ::Zip::File.new(io, create: create, buffer: true,
                           restore_ownership:     restore_ownership,
                           restore_permissions:   restore_permissions,
                           restore_times:         restore_times,
                           compression_level:     compression_level,
                           suppress_extra_fields: suppress_extra_fields)

  return zf unless block_given?

  yield zf

  begin
    zf.write_buffer(io)
  rescue IOError => e
    raise unless e.message == 'not opened for writing'
  end
end

Public Instance Methods

add(entry, src_path, &continue_on_exists_proc) click to toggle source

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

# File lib/zip/file.rb, line 231
def add(entry, src_path, &continue_on_exists_proc)
  continue_on_exists_proc ||= proc { ::Zip.continue_on_exists_proc }
  check_entry_exists(entry, continue_on_exists_proc, 'add')
  new_entry = if entry.kind_of?(::Zip::Entry)
                entry
              else
                ::Zip::Entry.new(
                  @name, entry.to_s,
                  compression_level: @compression_level
                )
              end
  new_entry.gather_fileinfo_from_srcpath(src_path)
  @cdir << new_entry
end

add_stored(entry, src_path, &continue_on_exists_proc) click to toggle source

Convenience method for adding the contents of a file to the archive in Stored format (uncompressed)

# File lib/zip/file.rb, line 248
def add_stored(entry, src_path, &continue_on_exists_proc)
  entry = ::Zip::Entry.new(
    @name, entry.to_s, compression_method: ::Zip::Entry::STORED
  )
  add(entry, src_path, &continue_on_exists_proc)
end

close() click to toggle source

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

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

commit() click to toggle source

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

# File lib/zip/file.rb, line 291
def commit
  return if name.kind_of?(StringIO) || !commit_required?

  on_success_replace do |tmp_file|
    ::Zip::OutputStream.open(tmp_file, suppress_extra_fields: @suppress_extra_fields) do |zos|
      @cdir.each do |e|
        e.write_to_zip_output_stream(zos)
        e.clean_up
      end
      zos.comment = comment
    end
    true
  end
  initialize_cdir(@name)
end

commit_required?() click to toggle source

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

# File lib/zip/file.rb, line 324
def commit_required?
  return true if @create || @cdir.dirty?

  @cdir.each do |e|
    return true if e.dirty?
  end

  false
end

extract(entry, entry_path = nil, destination_directory: '.', &block) click to toggle source

Extracts ‘entry` to a file at `entry_path`, with `destination_directory` as the base location in the filesystem.

NB: The caller is responsible for making sure ‘destination_directory` is safe, if it is passed.

# File lib/zip/file.rb, line 282
def extract(entry, entry_path = nil, destination_directory: '.', &block)
  block ||= proc { ::Zip.on_exists_proc }
  found_entry = get_entry(entry)
  entry_path ||= found_entry.name
  found_entry.extract(entry_path, destination_directory: destination_directory, &block)
end

find_entry(entry_name) click to toggle source

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

# File lib/zip/file.rb, line 336
def find_entry(entry_name)
  selected_entry = @cdir.find_entry(entry_name)
  return if selected_entry.nil?

  selected_entry.restore_ownership   = @restore_ownership
  selected_entry.restore_permissions = @restore_permissions
  selected_entry.restore_times       = @restore_times
  selected_entry
end

get_entry(entry) click to toggle source

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

# File lib/zip/file.rb, line 348
def get_entry(entry)
  selected_entry = find_entry(entry)
  raise Errno::ENOENT, entry if selected_entry.nil?

  selected_entry
end

get_input_stream(entry, &a_proc) click to toggle source

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/file.rb, line 186
def get_input_stream(entry, &a_proc)
  get_entry(entry).get_input_stream(&a_proc)
end

get_output_stream(entry, permissions: nil, comment: nil, extra: nil, compressed_size: nil, crc: nil, compression_method: nil, compression_level: nil, size: nil, time: nil, &a_proc) click to toggle source

Returns an output stream to the specified entry. If entry is not an instance of Zip::Entry, a new Zip::Entry will be initialized using the arguments specified. 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/file.rb, line 195
def get_output_stream(entry, permissions: nil, comment: nil,
                      extra: nil, compressed_size: nil, crc: nil,
                      compression_method: nil, compression_level: nil,
                      size: nil, time: nil, &a_proc)
  new_entry =
    if entry.kind_of?(Entry)
      entry
    else
      Entry.new(
        @name, entry.to_s, comment: comment, extra: extra,
        compressed_size: compressed_size, crc: crc, size: size,
        compression_method: compression_method,
        compression_level: compression_level, time: time
      )
    end
  if new_entry.directory?
    raise ArgumentError,
          "cannot open stream to directory entry - '#{new_entry}'"
  end
  new_entry.unix_perms = permissions
  zip_streamable_entry = StreamableStream.new(new_entry)
  @cdir << zip_streamable_entry
  zip_streamable_entry.get_output_stream(&a_proc)
end

mkdir(entry_name, permission = 0o755) click to toggle source

Creates a directory

# File lib/zip/file.rb, line 356
def mkdir(entry_name, permission = 0o755)
  raise Errno::EEXIST, "File exists - #{entry_name}" if find_entry(entry_name)

  entry_name = entry_name.dup.to_s
  entry_name << '/' unless entry_name.end_with?('/')
  @cdir << ::Zip::StreamableDirectory.new(@name, entry_name, nil, permission)
end

read(entry) click to toggle source

Returns a string containing the contents of the specified entry

# File lib/zip/file.rb, line 226
def read(entry)
  get_input_stream(entry, &:read)
end

remove(entry) click to toggle source

Removes the specified entry.

# File lib/zip/file.rb, line 256
def remove(entry)
  @cdir.delete(get_entry(entry))
end

rename(entry, new_name, &continue_on_exists_proc) click to toggle source

Renames the specified entry.

# File lib/zip/file.rb, line 261
def rename(entry, new_name, &continue_on_exists_proc)
  found_entry = get_entry(entry)
  check_entry_exists(new_name, continue_on_exists_proc, 'rename')
  @cdir.delete(found_entry)
  found_entry.name = new_name
  @cdir << found_entry
end

replace(entry, src_path) click to toggle source

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

# File lib/zip/file.rb, line 271
def replace(entry, src_path)
  check_file(src_path)
  remove(entry)
  add(entry, src_path)
end

to_s() click to toggle source

Returns the name of the zip archive

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

write_buffer(io = ::StringIO.new) click to toggle source

Write buffer write changes to buffer and return

# File lib/zip/file.rb, line 308
def write_buffer(io = ::StringIO.new)
  return io unless commit_required?

  ::Zip::OutputStream.write_buffer(io, suppress_extra_fields: @suppress_extra_fields) do |zos|
    @cdir.each { |e| e.write_to_zip_output_stream(zos) }
    zos.comment = comment
  end
end

Private Instance Methods

check_entry_exists(entry_name, continue_on_exists_proc, proc_name) click to toggle source

# File lib/zip/file.rb, line 398
def check_entry_exists(entry_name, continue_on_exists_proc, proc_name)
  return unless @cdir.include?(entry_name)

  continue_on_exists_proc ||= proc { Zip.continue_on_exists_proc }
  raise ::Zip::EntryExistsError.new proc_name, entry_name unless continue_on_exists_proc.call

  remove get_entry(entry_name)
end

check_file(path) click to toggle source

# File lib/zip/file.rb, line 407
def check_file(path)
  raise Errno::ENOENT, path unless ::File.readable?(path)
end

initialize_cdir(path_or_io, buffer: false) click to toggle source

# File lib/zip/file.rb, line 366
def initialize_cdir(path_or_io, buffer: false)
  @cdir = ::Zip::CentralDirectory.new

  if ::File.size?(@name.to_s)
    # There is a file, which exists, that is associated with this zip.
    @create = false
    @file_permissions = ::File.stat(@name).mode

    if buffer
      # https://github.com/rubyzip/rubyzip/issues/119
      path_or_io.binmode if path_or_io.respond_to?(:binmode)
      @cdir.read_from_stream(path_or_io)
    else
      ::File.open(@name, 'rb') do |f|
        @cdir.read_from_stream(f)
      end
    end
  elsif buffer && path_or_io.size > 0
    # This zip is probably a non-empty StringIO.
    @create = false
    @cdir.read_from_stream(path_or_io)
  elsif !@create && ::File.empty?(@name)
    # A file exists, but it is empty, and we've said we're
    # NOT creating a new zip.
    raise Error, "File #{@name} has zero size. Did you mean to pass the create flag?"
  elsif !@create
    # If we get here, and we're not creating a new zip, then
    # everything is wrong.
    raise Error, "File #{@name} not found"
  end
end

on_success_replace() { |tmp_filename| ... } click to toggle source

# File lib/zip/file.rb, line 411
def on_success_replace
  dirname, basename = ::File.split(name)
  ::Dir::Tmpname.create(basename, dirname) do |tmp_filename|
    if yield tmp_filename
      ::File.rename(tmp_filename, name)
      ::File.chmod(@file_permissions, name) unless @create
    end
  ensure
    FileUtils.rm_f(tmp_filename)
  end
end