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
-
100% native Ruby. (Well, almost… depends on zlib.)
-
Archive creation and extraction is supported with only a few lines of code.
-
Archives can be updated “in place” or dumped out to other files or pipes.
-
Files, symlinks, and directories are supported within archives.
-
Unix permission/mode bits are supported.
-
Unix user and group ownerships are supported.
-
Unix last accessed and last modified times are supported.
-
Entry extension (AKA extra field) implementations can be added on the fly.
-
Unknown entry extension types are preserved during archive processing.
-
The Deflate and Store compression codecs are supported out of the box.
-
More compression codecs can be added on the fly.
-
Traditional (weak) encryption is supported out of the box.
Known Bugs/Limitations
-
More testcases are needed.
-
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.
-
Hard links and device files are not currently supported within archives.
-
Reading archives from non-seekable IO, such as pipes and sockets, is not supported.
-
MSDOS permission attributes are not supported.
-
Strong encryption is not supported.
-
Zip64 is not supported.
-
Digital signatures are not supported.
Contributing
Contributions for bug fixes, documentation, extensions, tests, etc. are encouraged. Please read the file HACKING for details.