Archive::Zip::SimpleZip - Create Zip Archives
use Archive::Zip::SimpleZip qw($SimpleZipError) ; my $z = new Archive::Zip::SimpleZip "my.zip" or die "Cannot create zip file: $SimpleZipError\n" ; $z->add("/some/file1.txt"); $z->addString("some text", Name => "myfile"); $z->close();
Archive::Zip::SimpleZip is a module that allows the creation of Zip archives. It doesn't allow modification of existing zip archives - it just writes zip archives from scratch.
There are a few methods available in Archive::Zip::SimpleZip, and quite a few options, but for the most part all you need to know is how to create a Zip object and how to add a file to the zip archive. Below is a typical example of how it is used
use Archive::Zip::SimpleZip qw($SimpleZipError) ; my $z = new Archive::Zip::SimpleZip "my.zip" or die "Cannot create zip file: $SimpleZipError\n" ; $z->add("/some/file1.txt"); $z->add("/some/file2.txt"); $z->close();
$z = new Archive::Zip::SimpleZip "myzipfile.zip" [, OPTIONS] ; $z = new Archive::Zip::SimpleZip \$buffer [, OPTIONS] ; $z = new Archive::Zip::SimpleZip $filehandle [, OPTIONS] ;
The constructor takes one mandatory parameter along with zero or more optional patameters.
The mandatory parameter controls where the zip archive is written. This can be any of the the following
A File
When SimpleZip is passed a string, it will write the zip archive to the filename stored in the string.
A String
When SimpleZip is passed a string reference, it will write the zip archive to the string.
A Filehandle
When SimpleZip is passed a filehandle, it will write the zip archive to that filehandle.
Use the string '-' to write the zip archive to standard output (Note - this will also enable the Stream option).
Stream
See "Options" for a list of the optional parameters that can be specified when calling the constructor.
The add method writes the contents of the filename stored in $filename to the zip archive.
add
$filename
Currenly the module supports these file types.
Standard files
The contents of the the file are written to the zip archive.
Directories
The directory name is stored in the zip archive.
Symbolic Links
By default this module will store the contents of the file that the symbolic link refers to. It is possible though to store the symbolic link itself by setting the StoreLink option to 1.
StoreLink
By default the name of the entry created in the zip archive will be based on the value of the $filename parameter. See "File Naming Options" for more details.
See "Options" for a full list of the options available for this method.
Returns 1 if the file was added, or 0. Check the $SimpleZipError for a message.
The addString method writes <$string> to the zip archive. The Name option must be supplied.
See "Options" for the options available for this method.
Returns 1 if the zip archive was closed successfully, or 0. Check the $SimpleZipError for a message.
The majority of options are valid in both the constructor and in the methods that accept options. Any exceptions are noted in the text below.
Options specified in the constructor will be used as the defaults for all subsequent method call.
For example, in the constructor below, the Method is set to ZIP_CM_STORE.
Method
ZIP_CM_STORE
use Archive::Zip::SimpleZip qw($SimpleZipError) ; my $z = new Archive::Zip::SimpleZip "my.zip", Method => ZIP_CM_STORE or die "Cannot create zip file: $SimpleZipError\n" ; $z->add("file1", Method => ZIP_CM_DEFLATE); $z->add("file2"); $z->close();
The first call to add overrides the new default to use ZIP_CM_DEFLATE, while the second uses the value set in the constructor, ZIP_CM_STORE.
ZIP_CM_DEFLATE
These options control how the names of the files are store in the zip archive.
Name => $string
Stores the contents of $string in the zip filename header field.
$string
When used with the add method, this option will override any filename that was passed as a parameter.
The Name option is mandatory for the addString method.
addString
This option is not valid in the constructor.
CanonicalName => 0|1
This option controls whether the filename field in the zip header is normalized into Unix format before being written to the zip archive.
It is recommended that you keep this option enabled unless you really need to create a non-standard Zip archive.
This is what APPNOTE.TXT has to say on what should be stored in the zip filename header field.
The name of the file, with optional relative path. The path stored should not contain a drive or device letter, or a leading slash. All slashes should be forward slashes '/' as opposed to backwards slashes '\' for compatibility with Amiga and UNIX file systems etc.
This option defaults to true.
FilterName => sub { ... }
This option allow the filename field in the zip archive to be modified before it is written to the zip archive.
This option takes a parameter that must be a reference to a sub. On entry to the sub the $_ variable will contain the name to be filtered. If no filename is available $_ will contain an empty string.
$_
The value of $_ when the sub returns will be stored in the filename header field.
Note that if CanonicalName is enabled, a normalized filename will be passed to the sub.
CanonicalName
If you use FilterName to modify the filename, it is your responsibility to keep the filename in Unix format.
FilterName
The example below shows how to FilterName can be use to remove the path from the filename.
use Archive::Zip::SimpleZip qw($SimpleZipError) ; my $z = new Archive::Zip::SimpleZip "my.zip" or die "$SimpleZipError\n" ; for ( </some/path/*.c> ) { $z->add($_, FilterName => sub { s[^.*/][] } ) or die "Cannot add '$_' to zip file: $SimpleZipError\n" ; } $z->close();
The filename entry stored in a Zip archive is constructed as follows.
The initial source for the filename entry that gets stored in the zip archive is the filename parameter supplied to the add method, or the value supplied with the Name option to the addSTring method.
addSTring
Next, for the add option, if the Name option is supplied that will overide the filename parameter.
Name
If the CanonicalName option is enabled, and it is by default, the filename gets normalized into Unix format. If the filename was absolute, it will be changed into a relative filename.
Finally, is the FilterName option is enabled, the filename will get passed to the sub supplied via the $_ variable. The value of $_ on exit from the sub will get stored in the zip archive.
Here are some examples
use Archive::Zip::SimpleZip qw($SimpleZipError) ; my $z = new Archive::Zip::SimpleZip "my.zip" or die "$SimpleZipError\n" ; # store "my/abc.txt" in the zip archive $z->add("/my/abc.txt") ; # store "/my/abc.txt" in the zip archive $z->add("/my/abc.txt", CanonoicalName => 0) ; # store "xyz" in the zip archive $z->add("/some/file", Name => "xyz") ; # store "file3.txt" in the zip archive $z->add("/my/file3.txt", FilterName => sub { s#.*/## } ) ; # store "" in the zip archive $z->addString("payload data") ; # store "xyz" in the zip archive $z->addString("payload data", Name => "xyz") ; # store "/abc/def" in the zip archive $z->addString("payload data", Name => "/abc/def", CanonoicalName => 0) ; $z->close();
Minimal => 1|0
If specified, this option will disable the creation of all extra fields in the zip local and central headers (with the exception of those needed for Zip64). In particular the following fields will not be created
Extended Time TODO
This option is useful in a number of scenarios.
Firstly, the option may be needed if you require the zip files created by Archive::Zip::SimpleZip to be read using a legacy version of unzip or by an application that only supports a sub-set of the zip features.
Archive::Zip::SimpleZip
The other main use-case when Minimal is handy is when the data that Minimal suppresses is not needed, and so just adds unnecessary bloat to the zip file. The extra fields that Archive::Zip::SimpleZip adds by default all store additional information that assume the entry in the zip file corresponds to a file that will be stored in a filesystem. This information is very handy when archiving files from a filesystem - it means the unzipped files will more closely match their originals. If the zip file isn't going to be unzipped to a filesystem you can save a few bytes by enabling <Minimal>.
Minimal
This parameter defaults to 0.
Stream => 0|1
This option controls whether the zip farchive is created in streaming mode.
Note that when outputting to a file or filehandle with streaming mode disabled (Stream is 0), the output file/handle must be seekable.
When outputting to '-' (STDOUT) Stream is automatically enabled.
TODO - when to use & interoperability issues.
The default is 0.
Zip64 => 0|1
ZIP64 is an extension to the Zip archive structure that allows
Zip archives larger than 4Gig.
Zip archives with more that 64K members.
The module will automatically enable ZIP64 mode as needed when creating zip archive.
You can force creation of a Zip64 zip archive by enabling this option.
If you intend to manipulate the Zip64 zip archives created with this module using an external zip/unzip program/library, make sure that it supports Zip64.
Comment => $comment
This option allows the creation of a comment that is associated with the entry added to the zip archive with the add and addString methods.
By default, no comment field is written to the zip archive.
Method => $method
Controls which compression method is used. At present four compression methods are supported, namely Store (no compression at all), Deflate, Bzip2 and Lzma.
The symbols, ZIP_CM_STORE, ZIP_CM_DEFLATE, ZIP_CM_BZIP2 and ZIP_CM_LZMA are used to select the compression method.
These constants are not imported by default by this module.
use Archive::Zip::SimpleZip qw(:zip_method); use Archive::Zip::SimpleZip qw(:constants); use Archive::Zip::SimpleZip qw(:all);
Note that to create Bzip2 content, the module IO::Compress::Bzip2 must be installed. A fatal error will be thrown if you attempt to create Bzip2 content when IO::Compress::Bzip2 is not available.
IO::Compress::Bzip2
Note that to create Lzma content, the module IO::Compress::Lzma must be installed. A fatal error will be thrown if you attempt to create Lzma content when IO::Compress::Lzma is not available.
IO::Compress::Lzma
The default method is ZIP_CM_DEFLATE for files and ZIP_CM_STORE for directories and symbolic links.
StoreLink => 1|0
Controls what Archive::Zip::SimpleZip does with a symbolic link.
When true, it stores the link itself. When false, it stores the contents of the file the link refers to.
If your platform does not support symbolic links this option is ignored.
Default is 0.
TextFlag => 0|1
This parameter controls the setting of a flag in the zip central header. It is used to signal that the data stored in the zip archive is probably text.
ZipComment => $comment
This option allows the creation of a comment field for the entire zip archive.
This option is only valid in the constructor.
These option are only valid if the Method is ZIP_CM_DEFLATE. They are ignored otherwise.
Level => value
Defines the compression level used by zlib. The value should either be a number between 0 and 9 (0 means no compression and 9 is maximum compression), or one of the symbolic constants defined below.
Z_NO_COMPRESSION Z_BEST_SPEED Z_BEST_COMPRESSION Z_DEFAULT_COMPRESSION
The default is Z_DEFAULT_COMPRESSION.
Strategy => value
Defines the strategy used to tune the compression. Use one of the symbolic constants defined below.
Z_FILTERED Z_HUFFMAN_ONLY Z_RLE Z_FIXED Z_DEFAULT_STRATEGY
The default is Z_DEFAULT_STRATEGY.
These option are only valid if the Method is ZIP_CM_BZIP2. They are ignored otherwise.
BlockSize100K => number
Specify the number of 100K blocks bzip2 uses during compression.
Valid values are from 1 to 9, where 9 is best compression.
The default is 1.
WorkFactor => number
Specifies how much effort bzip2 should take before resorting to a slower fallback compression algorithm.
Valid values range from 0 to 250, where 0 means use the default value 30.
These option are only valid if the Method is ZIP_CM_LZMA. They are ignored otherwise.
Preset => number
Used to choose the LZMA compression preset.
Valid values are 0-9 and LZMA_PRESET_DEFAULT.
LZMA_PRESET_DEFAULT
0 is the fastest compression with the lowest memory usage and the lowest compression.
9 is the slowest compession with the highest memory usage but with the best compression.
Defaults to LZMA_PRESET_DEFAULT (6).
Extreme => 0|1
Makes LZMA compression a lot slower, but a small compression gain.
Defaults to 0.
By default Archive::Zip::SimpleZip will do the following
Use Deflate Compression for all standard files.
Create a non-streamed Zip archive
Follow Symbolic Links
Canonicalise the filename before adding it to the zip archive
Only use create a ZIP64 Zip archive if any of the input files is greater than 4 Gig or there are more than 64K members in the zip archive.
Fill out the following zip extended attributes
"UT" Extended Timestamp "ux" ExtraExtra Type 3 (if running Unix)
You can change the behaviour of most of the features mentioned above.
Add all the "C" files in the current directory to the zip archive "my.zip".
use Archive::Zip::SimpleZip qw($SimpleZipError) ; my $z = new Archive::Zip::SimpleZip "my.zip" or die "$SimpleZipError\n" ; for ( <*.c> ) { $z->add($_) or die "Cannot add '$_' to zip file: $SimpleZipError\n" ; } $z->close();
TODO
A number of symbolic constants are required by some methods in Archive::Zip::SimpleZip. None are imported by default.
Imports zip, $SimpleZipError and all symbolic constants that can be used by IArchive::Zip::SimpleZip. Same as doing this
zip
$SimpleZipError
IArchive::Zip::SimpleZip
use Archive::Zip::SimpleZip qw(zip $SimpleZipError :constants) ;
Import all symbolic constants. Same as doing this
use Archive::Zip::SimpleZip qw(:flush :level :strategy :zip_method) ;
These symbolic constants are used by the flush method.
flush
Z_NO_FLUSH Z_PARTIAL_FLUSH Z_SYNC_FLUSH Z_FULL_FLUSH Z_FINISH Z_BLOCK
These symbolic constants are used by the Level option in the constructor.
Level
These symbolic constants are used by the Strategy option in the constructor.
Strategy
These symbolic constants are used by the Method option in the constructor.
ZIP_CM_STORE ZIP_CM_DEFLATE ZIP_CM_BZIP2
IO::Compress::Zip, Archive::Zip, IO::Uncompress::UnZip
This module was written by Paul Marquess, pmqs@cpan.org.
See the Changes file.
Copyright (c) 2012 Paul Marquess. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Archive::Zip::SimpleZip, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Archive::Zip::SimpleZip
CPAN shell
perl -MCPAN -e shell install Archive::Zip::SimpleZip
For more information on module installation, please visit the detailed CPAN module installation guide.