The Archive::Zip module allows a Perl program to create, manipulate, read,
and write Zip archive files. Zip archives can be created, or you can read
from existing zip files. Once created, they can be written to files, streams,
or strings. Members can be added, removed, extracted, replaced, rearranged,
and enumerated. They can also be renamed or have their dates, comments, or
other attributes queried or modified. Their data can be compressed or
uncompressed as needed. Members can be created from members in existing Zip
files, or from existing directories, files, or strings. This module uses the
Compress::Zlib library to read and write the compressed
streams inside the files.

Regardless of what your local file system uses for file naming, names in a
Zip file are in Unix format (forward slashes (/) separating directory
names, etc.).
Archive::Zip tries to be consistent with file naming
conventions, and will
translate back and forth between native and Zip file names.
However, it can't guess which format names are in. So two rules control what
kind of file name you must pass various routines:

This applies to every method that refers to an archive member, or
provides a name for new archive members. The extract() methods
that can take one or two names will convert from local to zip names
if you call them with a single name.

Archive::Zip::Archive objects are what you ordinarily deal with.
These maintain the structure of a zip file, without necessarily
holding data. When a zip is read from a disk file, the (possibly
compressed) data still lives in the file, not in memory. Archive
members hold information about the individual members, but not
(usually) the actual member data. When the zip is written to a
(different) file, the member data is compressed or copied as needed.
It is possible to make archive members whose data is held in a string
in memory, but this is not done when a zip file is read. Directory
members don't have any data.

Exporter
Archive::Zip Common base class, has defs.
Archive::Zip::Archive A Zip archive.
Archive::Zip::Member Abstract superclass for all members.
Archive::Zip::StringMember Member made from a string
Archive::Zip::FileMember Member made from an external file
Archive::Zip::ZipFileMember Member that lives in a zip file
Archive::Zip::NewFileMember Member whose data is in a file
Archive::Zip::DirectoryMember Member that is a directory

Archive::Zip allows each member of a ZIP file to be compressed (using the
Deflate algorithm) or uncompressed. Other compression algorithms that some
versions of ZIP have been able to produce are not supported. Each member has
two compression methods: the one it's stored as (this is always
COMPRESSION_STORED for string and external file members), and the one you
desire for the member in the zip file. These can be different, of course, so
you can make a zip member that is not compressed out of one that is, and vice
versa. You can inquire about the current compression and set the desired
compression method:

If a member's desiredCompressionMethod is COMPRESSION_DEFLATED, you
can choose different compression levels. This choice may affect the
speed of compression and decompression, as well as the size of the
compressed member data.

The Archive::Zip class (and its invisible subclass Archive::Zip::Archive)
implement generic zip file functionality. Creating a new Archive::Zip object
actually makes an Archive::Zip::Archive object, but you don't have to worry
about this unless you're subclassing.

Report or change chunk size used for reading and writing.
This can make big differences in dealing with large files.
Currently, this defaults to 32K. This also changes the chunk
size used for Compress::Zlib. You must call setChunkSize()
before reading or writing. This is not exportable, so you
must call it like:

Archive::Zip::setChunkSize( 4096 );

or as a method on a zip (though this is a global setting).
Returns old chunk size.

Change the subroutine called with error strings. This
defaults to \&Carp::carp, but you may want to change it to
get the error strings. This is not exportable, so you must
call it like:

Archive::Zip::setErrorHandler( \&myErrorHandler );

If myErrorHandler is undef, resets handler to default.
Returns old error handler. Note that if you call Carp::carp
or a similar routine or if you're chaining to the default
error handler from your error handler, you may want to
increment the number of caller levels that are skipped (do
not just set it to a number):

Create a uniquely named temp file. It will be returned open
for read/write. If $tmpdir is given, it is used as the
name of a directory to create the file in. If not given,
creates the file using File::Spec::tmpdir(). Generally, you can
override this choice using the

$ENV{TMPDIR}

environment variable. But see the File::Spec
documentation for your system. Note that on many systems, if you're
running in taint mode, then you must make sure that $ENV{TMPDIR} is
untainted for it to be used.
Will NOT create $tmpdir if it doesn't exist (this is a change
from prior versions!). Returns file handle and name:

Return the disk number that holds the beginning of the
central directory. Not used for writing zips, but might be
interesting if you read a zip in. This should be 0, as
Archive::Zip does not handle multi-volume archives.

Returns the (unexpected) number of bytes between where the
EOCD was found and where it expected to be. This is normally
0, but would be positive if something (a virus, perhaps) had
added bytes somewhere before the EOCD. Not used for writing
zips, but might be interesting if you read a zip in. Here is
an example of how you can diagnose this:

Various operations on a zip file modify members. When a member is
passed as an argument, you can either use a reference to the member
itself, or the name of a member. Of course, using the name requires
that names be unique within a zip (this is not enforced).

Extract the given member, or match its name and extract it.
Returns undef if member doesn't exist in this Zip. If
optional second arg is given, use it as the name of the
extracted member. Otherwise, the internal filename of the
member is used as the name of the extracted file or
directory.
If you pass $extractedName, it should be in the local file
system's format.
All necessary directories will be created. Returns AZ_OK
on success.

Extract the given member, or match its name and extract it.
Does not use path information (extracts into the current
directory). Returns undef if member doesn't exist in this
Zip.
If optional second arg is given, use it as the name of the
extracted member (its paths will be deleted too). Otherwise,
the internal filename of the member (minus paths) is used as
the name of the extracted file or directory. Returns AZ_OK
on success.

Append a member (possibly from another zip file) to the zip
file. Returns the new member. Generally, you will use
addFile(), addDirectory(), addFileOrDirectory(), addString(),
or read() to add members.

Update a single member from the file or directory named $fileName.
Returns the (possibly added or updated) member, if any; undef on
errors.
The comparison is based on lastModTime() and (in the case of a
non-directory) the size of the file.

Append a member whose data comes from an external file,
returning the member or undef. The member will have its file
name set to the name of the external file, and its
desiredCompressionMethod set to COMPRESSION_DEFLATED. The
file attributes and last modification time will be set from
the file.
If the name given does not represent a readable plain file or
symbolic link, undef will be returned. $fileName must be
in the format required for the local file system.
The optional $newName argument sets the internal file name
to something different than the given $fileName. $newName,
if given, must be in Zip name format (i.e. Unix).
The text mode bit will be set if the contents appears to be
text (as returned by the -T perl operator).

NOTE that you shouldn't (generally) use absolute path names
in zip member names, as this will cause problems with some zip
tools as well as introduce a security hole and make the zip
harder to use.

Append a member created from the given directory name. The
directory name does not have to name an existing directory.
If the named directory exists, the file modification time and
permissions are set from the existing directory, otherwise
they are set to now and permissive default permissions.
$directoryName must be in local file system format.
The optional second argument sets the name of the archive
member (which defaults to $directoryName). If given, it
must be in Zip (Unix) format.
Returns the new member.

Append a member from the file or directory named $name. If
$newName is given, use it for the name of the new member.
Will add or remove trailing slashes from $newName as needed.
$name must be in local file system format.
The optional second argument sets the name of the archive
member (which defaults to $name). If given, it must be in
Zip (Unix) format.

Append a member created from the given string or string
reference. The name is given by the second argument.
Returns the new member. The last modification time will be
set to now, and the file attributes will be set to permissive
defaults.

Note that if you use the same name as an existing zip file
that you read in, you will clobber ZipFileMembers. So
instead, write to a different file name, then delete the
original.
If you use the overwrite() or overwriteAs() methods, you can
re-write the original zip in this way.
$fileName should be a valid file name on your system.

Write a zip archive to a file handle. Return AZ_OK on
success. The optional second arg tells whether or not to try
to seek backwards to re-write headers. If not provided, it is
set if the Perl -f test returns true. This could fail on
some operating systems, though.

If this method fails during the write of a member, that
member and all following it will return false from
wasWritten(). See writeCentralDirectory() for a way to
deal with this.
If you want, you can write data to the file handle before
passing it to writeToFileHandle(); this could be used (for
instance) for making self-extracting archives. However, this
only works reliably when writing to a real file (as opposed
to STDOUT or some other possible non-file).
See examples/selfex.pl for how to write a self-extracting
archive.

Writes the central directory structure to the given file
handle. Returns AZ_OK on success. If given an $offset, will
seek to that point before writing. This can be used for
recovery in cases where writeToFileHandle or writeToFileNamed
returns an IO error because of running out of space on the
destination file. You can truncate the zip by seeking
backwards and then writing the directory:

Write the zip to the specified file, as safely as possible.
This is done by first writing to a temp file, then renaming
the original if it exists, then renaming the temp file, then
deleting the renamed original if it exists. Returns AZ_OK if
successful.

Read zipfile headers from an already-opened file handle,
appending new members. Does not close the file handle.
Returns AZ_OK or error code. Note that this requires a
seekable file handle; reading from a stream is not yet
supported.

$root is the root of the tree of files and directories to be
added. It is a valid directory name on your system. $dest is
the name for the root in the zip file (undef or blank means
to use relative pathnames). It is a valid ZIP directory name
(that is, it uses forward slashes (/) for separating
directory components). $pred is an optional subroutine
reference to select files: it is passed the name of the
prospective file or directory using $_, and if it returns
true, the file or directory will be included. The default is
to add all readable files and directories. For instance,
using

my $pred = sub { /\.txt/ };
$zip->addTree( '.', '', $pred );

will add all the .txt files in and below the current
directory, using relative names, and making the names
identical in the zipfile:

$root is the root of the tree of files and directories to be
added $dest is the name for the root in the zip file (undef
means to use relative pathnames) $pattern is a (non-anchored)
regular expression for filenames to match $pred is an
optional subroutine reference to select files: it is passed
the name of the prospective file or directory in $_, and
if it returns true, the file or directory will be included.
The default is to add all readable files and directories. To
add all files in and below the current dirctory whose names
end in .pl, and make them extract into a subdirectory
named xyz, do this:

$zip->addTreeMatching( '.', 'xyz', '\.pl$' )

To add all writable files in and below the dirctory named
/abc whose names end in .pl, and make them extract into
a subdirectory named xyz, do this:

$zip->addTreeMatching( '/abc', 'xyz', '\.pl$', sub { -w } )

Returns AZ_OK on success. Note that this will not follow
symbolic links to directories.

If you don't give any arguments at all, will extract all the
files in the zip with their original names.

If you supply one argument for $root, extractTree will extract
all the members whose names start with $root into the current
directory, stripping off $root first.
$root is in Zip (Unix) format.
For instance,

$zip->extractTree( 'a' );

when applied to a zip containing the files:
a/x a/b/c ax/d/e d/e will extract:

a/x as ./x

a/b/c as ./b/c

If you give two arguments, extractTree extracts all the members
whose names start with $root. It will translate $root into
$dest to construct the destination file name.
$root and $dest are in Zip (Unix) format.
For instance,

$zip->extractTree( 'a', 'd/e' );

when applied to a zip containing the files:
a/x a/b/c ax/d/e d/e will extract:

a/x to d/e/x

a/b/c to d/e/b/c and ignore ax/d/e and d/e

If you give three arguments, extractTree extracts all the members
whose names start with $root. It will translate $root into
$dest to construct the destination file name, and then it will
convert to local file system format, using $volume as the name of
the destination volume.

$root and $dest are in Zip (Unix) format.

$volume is in local file system format.

For instance, under Windows,

$zip->extractTree( 'a', 'd/e', 'f:' );

when applied to a zip containing the files:
a/x a/b/c ax/d/e d/e will extract:

a/x to f:d/e/x

a/b/c to f:d/e/b/c and ignore ax/d/e and d/e

If you want absolute paths (the prior example used paths relative to
the current directory on the destination volume, you can specify these
in $dest:

$zip->extractTree( 'a', '/d/e', 'f:' );

when applied to a zip containing the files:
a/x a/b/c ax/d/e d/e will extract:

Several constructors allow you to construct members without adding
them to a zip archive. These work the same as the addFile(),
addDirectory(), and addString() zip instance methods described above,
but they don't add the new members to a zip.

Returns the member compression method. This is the method
that is currently being used to compress the member data.
This will be COMPRESSION_STORED for added string or file
members, or any of the COMPRESSION_* values for members
from a zip file. However, this module can only handle members
whose data is in COMPRESSION_STORED or COMPRESSION_DEFLATED
format.

Get or set the member's desiredCompressionMethod. This is
the compression method that will be used when the member is
written. Returns prior desiredCompressionMethod. Only
COMPRESSION_DEFLATED or COMPRESSION_STORED are valid
arguments. Changing to COMPRESSION_STORED will change the
member desiredCompressionLevel to 0; changing to
COMPRESSION_DEFLATED will change the member
desiredCompressionLevel to COMPRESSION_LEVEL_DEFAULT.

Get or set the member's desiredCompressionLevel This is the
method that will be used to write. Returns prior
desiredCompressionLevel. Valid arguments are 0 through 9,
COMPRESSION_LEVEL_NONE, COMPRESSION_LEVEL_DEFAULT,
COMPRESSION_LEVEL_BEST_COMPRESSION, and
COMPRESSION_LEVEL_FASTEST. 0 or COMPRESSION_LEVEL_NONE will
change the desiredCompressionMethod to COMPRESSION_STORED.
All other arguments will change the desiredCompressionMethod
to COMPRESSION_DEFLATED.

Get or set the member's internal filename. Returns the
(possibly new) filename. Names will have backslashes
converted to forward slashes, and will have multiple
consecutive slashes converted to single ones.

Gets or sets the extra field that was read from the local
header. This is not set for a member from a zip file until
after the member has been written out. The extra field must
be in the proper format.

Get or set the data descriptor flag. If this is set, the
local header will not necessarily have the correct data
sizes. Instead, a small structure will be stored at the end
of the member data with these values. This should be
transparent in normal operation.

Return the CRC-32 value for this member as an 8 character
printable hex string. This will not be set for members that
were constructed from strings or external files until after
the member has been written.

Returns true if I am a text file. Also can set the status if
given an argument (then returns old state). Note that this
module does not currently do anything with this flag upon
extraction or storage. That is, bytes are stored in native
format whether or not they came from a text file.

Returns true if I am a binary file. Also can set the status
if given an argument (then returns old state). Note that this
module does not currently do anything with this flag upon
extraction or storage. That is, bytes are stored in native
format whether or not they came from a text file.

Extract me to a file with the given name. The file will be
created with default modes. Directories will be created as
needed.
The $fileName argument should be a valid file name on your
file system.
Returns AZ_OK on success.

It is possible to use lower-level routines to access member data
streams, rather than the extract* methods and contents(). For
instance, here is how to print the uncompressed contents of a member
in chunks using these methods:

This reads the next chunk of given size from the member's
data stream and compresses or uncompresses it as necessary,
returning a reference to the bytes read and a status. If size
argument is not given, defaults to global set by
Archive::Zip::setChunkSize. Status is AZ_OK on success until
the last chunk, where it returns AZ_STREAM_END. Returns (
\$bytes, $status).

Rewind data and set up for reading data streams or writing
zip files. Can take options for inflateInit() or
deflateInit(), but this isn't likely to be necessary.
Subclass overrides should call this method. Returns AZ_OK
on success.

The Archive::Zip::FileMember class extends Archive::Zip::Member. It is the
base class for both ZipFileMember and NewFileMember classes. This class adds
an externalFileName and an fh member to keep track of the external
file.