Archive::Zip represents a ZIP archive compatible with InfoZip tools and the archives they generate. It currently supports both stored and deflated ZIP entries, directory entries, file entries, and symlink entries. File and directory accessed and modified times, POSIX permissions, and ownerships can be archived and restored as well depending on platform support for such metadata. Traditional (weak) encryption is also supported.
Zip64, digital signatures, and strong encryption are not supported. ZIP archives can only be read from seekable kinds of IO, such as files; reading archives from pipes or any other non-seekable kind of IO is not supported. However, writing to such IO objects IS supported.
VERSION | = | "0.5.0" | The current version of this gem. | |
EOCD_SIGNATURE | = | "PK\x5\x6" | The lead-in marker for the end of central directory record. | |
DS_SIGNATURE | = | "PK\x5\x5" | The lead-in marker for the digital signature record. | |
Z64EOCD_SIGNATURE | = | "PK\x6\x6" | The lead-in marker for the ZIP64 end of central directory record. | |
Z64EOCDL_SIGNATURE | = | "PK\x6\x7" | The lead-in marker for the ZIP64 end of central directory locator record. | |
CFH_SIGNATURE | = | "PK\x1\x2" | The lead-in marker for a central file record. | |
LFH_SIGNATURE | = | "PK\x3\x4" | The lead-in marker for a local file record. | |
DD_SIGNATURE | = | "PK\x7\x8" | The lead-in marker for data descriptor record. |
comment | [RW] | A comment string for the ZIP archive. |
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.
NOTE: 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.
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 :r or "r" to read the archive, and set it to :w or "w" to write the archive.
NOTE: 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.
Adds entry into a writable ZIP archive.
NOTE: 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.
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 this is when the basename for a path is either "." or "..". In this case, the path is replaced with the paths to the contents of the directory it references.
options is a Hash optionally containing the following:
:path_prefix: | Specifies a prefix to be added to the zip_path attribute of each entry where `/’ is the file separator character. This defaults to the empty string. All values are passed through Archive::Zip::Entry.expand_path before use. |
:recursion: | When set to true (the default), the contents of directories are recursively added to the archive. |
:directories: | When set to true (the default), entries are added to the archive for directories. Otherwise, the entries for directories will not be added; however, the contents of the directories will still be considered if the :recursion option is true. |
:symlinks: | When set to false (the default), entries for symlinks are excluded from the archive. Otherwise, they are included. NOTE: Unless :follow_symlinks is explicitly set, it will be set to the logical NOT of this option in calls to Archive::Zip::Entry.from_file. If symlinks should be completely ignored, set both this option and :follow_symlinks to false. See Archive::Zip::Entry.from_file for details regarding :follow_symlinks. |
:flatten: | When set to false (the default), the directory paths containing archived files will be included in the zip paths of entries representing the files. When set to true, files are archived without any containing directory structure in the zip paths. Setting to true implies that :directories is false and :path_prefix is empty. |
:exclude: | Specifies a proc or lambda which takes a single argument containing a prospective zip entry and returns true if the entry should be excluded from the archive and false if it should be included. NOTE: If a directory is excluded in this way, the :recursion option has no effect for it. |
:password: | Specifies a proc, lambda, or a String. If a proc or lambda is used, it must take a single argument containing a zip entry and return a String to be used as an encryption key for the entry. If a String is used, it will be used as an encryption key for all encrypted entries. |
:on_error: | Specifies a proc or lambda which is called when an exception is raised during the archival of an entry. It takes two arguments, a file path and an exception object generated while attempting to archive the entry. If :retry is returned, archival of the entry is attempted again. If :skip is returned, the entry is skipped. Otherwise, the exception is raised. |
Any other options which are supported by Archive::Zip::Entry.from_file are also supported.
NOTE: 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 :on_error option is either unset or indicates that the error should be raised and Archive::Zip::Entry.from_file raises an error.
A directory contains:
zip-test +- dir1 | +- file2.txt +- dir2 +- file1.txt
Create some archives:
Archive::Zip.open('zip-test1.zip') do |z| z.archive('zip-test') end Archive::Zip.open('zip-test2.zip') do |z| z.archive('zip-test/.', :path_prefix => 'a/b/c/d') end Archive::Zip.open('zip-test3.zip') do |z| z.archive('zip-test', :directories => false) end Archive::Zip.open('zip-test4.zip') do |z| z.archive('zip-test', :exclude => lambda { |e| e.file? }) end
The archives contain:
zip-test1.zip -> zip-test/ zip-test/dir1/ zip-test/dir1/file2.txt zip-test/dir2/ zip-test/file1.txt zip-test2.zip -> a/b/c/d/dir1/ a/b/c/d/dir1/file2.txt a/b/c/d/dir2/ a/b/c/d/file1.txt zip-test3.zip -> zip-test/dir1/file2.txt zip-test/file1.txt zip-test4.zip -> zip-test/ zip-test/dir1/ zip-test/dir2/
Extracts the contents of the archive to destination, where destination is a path to a directory which will contain the contents of the archive. The destination path will be created if it does not already exist.
options is a Hash optionally containing the following:
:directories: | When set to true (the default), entries representing directories in the archive are extracted. This happens after all non-directory entries are extracted so that directory metadata can be properly updated. |
:symlinks: | When set to false (the default), entries representing symlinks in the archive are skipped. When set to true, such entries are extracted. Exceptions may be raised on plaforms/file systems which do not support symlinks. |
:overwrite: | When set to :all (the default), files which already exist will be replaced. When set to :older, such files will only be replaced if they are older according to their last modified times than the zip entry which would replace them. When set to :none, such files will never be replaced. Any other value is the same as :all. |
:create: | When set to true (the default), files and directories which do not already exist will be extracted. When set to false, only files and directories which already exist will be extracted (depending on the setting of :overwrite). |
:flatten: | When set to false (the default), the directory paths containing extracted files will be created within destination in order to contain the files. When set to true, files are extracted directly to destination and directory entries are skipped. |
:exclude: | Specifies a proc or lambda which takes a single argument containing a zip entry and returns true if the entry should be skipped during extraction and false if it should be extracted. |
:password: | Specifies a proc, lambda, or a String. If a proc or lambda is used, it must take a single argument containing a zip entry and return a String to be used as a decryption key for the entry. If a String is used, it will be used as a decryption key for all encrypted entries. |
:on_error: | Specifies a proc or lambda which is called when an exception is raised during the extraction of an entry. It takes two arguments, a zip entry and an exception object generated while attempting to extract the entry. If :retry is returned, extraction of the entry is attempted again. If :skip is returned, the entry is skipped. Otherwise, the exception is raised. |
Any other options which are supported by Archive::Zip::Entry#extract are also supported.
Raises Archive::Zip::IOError if called on a non-readable archive or after the archive is closed.
An archive, archive.zip, contains:
zip-test/ zip-test/dir1/ zip-test/dir1/file2.txt zip-test/dir2/ zip-test/file1.txt
A directory, extract4, contains:
zip-test +- dir1 +- file1.txt
Extract the archive:
Archive::Zip.open('archive.zip') do |z| z.extract('extract1') end Archive::Zip.open('archive.zip') do |z| z.extract('extract2', :flatten => true) end Archive::Zip.open('archive.zip') do |z| z.extract('extract3', :create => false) end Archive::Zip.open('archive.zip') do |z| z.extract('extract3', :create => true) end Archive::Zip.open('archive.zip') do |z| z.extract( 'extract5', :exclude => lambda { |e| e.file? }) end
The directories contain:
extract1 -> zip-test +- dir1 | +- file2.txt +- dir2 +- file1.txt extract2 -> file2.txt file1.txt extract3 -> <empty> extract4 -> zip-test +- dir2 +- file1.txt <- from archive contents extract5 -> zip-test +- dir1 +- dir2