= Archive::Zip - ZIP Archival Made Easy

The Archive::Zip library intends to provide a simple, yet complete and
Ruby-esque, interface to working with ZIP archives.

Basic archive creation and extraction can be handled using only a few methods.
More complex operations involving the manipulation of existing archives in place
(adding, removing, and modifying entries) are also possible with a little more
work.  Even adding advanced features such as new compression codecs are
supported with a moderate amount of effort.


== License

Copyright © 2010 Jeremy Bopp <jeremy at bopp dot net>

Licensed under the same terms as Ruby -- See the included LICENSE file for
details


== Installation/Removal

Download the GEM file and install it with:
  % sudo gem install archive-zip-VERSION.gem

or directly with:
  % sudo gem install archive-zip

Removal is the same in either case:
  % sudo gem uninstall archive-zip


== Example
More examples can be found in the +examples+ directory of the source
distribution.

Create a few archives:
  gem 'archive-zip'  # Use require_gem for rubygems versions older than 0.9.0.
  require 'archive/zip'

  # Add a_directory and its contents to example1.zip.
  Archive::Zip.archive('example1.zip', 'a_directory')

  # Add the contents of a_directory to example2.zip.
  Archive::Zip.archive('example2.zip', 'a_directory/.')

  # Add a_file and a_directory and its contents to example3.zip.
  Archive::Zip.archive('example3.zip', ['a_directory', 'a_file'])

  # Add only the files and symlinks contained in a_directory under the path
  # a/b/c/a_directory in example4.zip.
  Archive::Zip.archive(
    'example4.zip',
    'a_directory',
    :directories => false,
    :path_prefix => 'a/b/c'
  )

  # Add the contents of a_directory to example5.zip and encrypt Ruby source
  # files.
  require 'archive/zip/codec/null_encryption'
  require 'archive/zip/codec/traditional_encryption'
  Archive::Zip.archive(
    'example5.zip',
    'a_directory/.',
    :encryption_codec => lambda do |entry|
      if entry.file? and entry.zip_path =~ /\.rb$/ then
        Archive::Zip::Codec::TraditionalEncryption
      else
        Archive::Zip::Codec::NullEncryption
      end
    end,
    :password => 'seakrit'
  )

  # Create a new archive which will be written to a pipe.
  # Assume $stdout is the write end a pipe.
  # (ruby example.rb | cat >example.zip)
  Archive::Zip.open($stdout, :w) do |z|
    z.archive('a_directory')
  end

Now extract those archives:
  gem 'archive-zip'  # Use require_gem for rubygems versions older than 0.9.0.
  require 'archive/zip'

  # Extract example1.zip to a_destination.
  Archive::Zip.extract('example1.zip', 'a_destination')

  # Extract example2.zip to a_destination, skipping directory entries.
  Archive::Zip.extract(
    'example2.zip',
    'a_destination',
    :directories => false
  )

  # Extract example3.zip to a_destination, skipping symlinks.
  Archive::Zip.extract(
    'example3.zip',
    'a_destination',
    :symlinks => false
  )

  # Extract example4.zip to a_destination, skipping entries for which files
  # already exist but are newer or for which files do not exist at all.
  Archive::Zip.extract(
    'example4.zip',
    'a_destination',
    :create => false,
    :overwrite => :older
  )

  # Extract example5.zip to a_destination, decrypting the contents.
  Archive::Zip.extract('example5.zip', 'a_destination', :password => 'seakrit')


== Features

1.  100% native Ruby.  (Well, almost... depends on zlib.)
2.  Archive creation and extraction is supported with only a few lines of code.
3.  Archives can be updated "in place" or dumped out to other files or pipes.
4.  Files, symlinks, and directories are supported within archives.
5.  Unix permission/mode bits are supported.
6.  Unix user and group ownerships are supported.
7.  Unix last accessed and last modified times are supported.
8.  Entry extension (AKA extra field) implementations can be added on the fly.
9.  Unknown entry extension types are preserved during archive processing.
10. The Deflate and Store compression codecs are supported out of the box.
11. More compression codecs can be added on the fly.
12. Traditional (weak) encryption is supported out of the box.


== Known Bugs/Limitations

1.  More testcases are needed.
2.  All file entries are archived and extracted in binary mode.  No attempt is
    made to normalize text files to the line ending convention of any target
    system.
3.  Hard links and device files are not currently supported within archives.
4.  Reading archives from non-seekable IO, such as pipes and sockets, is not
    supported.
5.  MSDOS permission attributes are not supported.
6.  Strong encryption is not supported.
7.  Zip64 is not supported.
8.  Digital signatures are not supported.


== Contributing

Contributions for bug fixes, documentation, extensions, tests, etc. are
encouraged.  Please read the file HACKING for details.