use Archive::SimpleZip;

# Create a zip archive in the filesystem
    my $zip = SimpleZip.new("mine.zip");

# Add a file to the zip archive
    # Will read anything that coerced to an IO()
    $zip.add("somefile.txt");
    $zip.add("somefile.txt".IO);

# Add multiple files in one step
    # It will consume anything that is an Iterable
    $z.add(@list_of_files);

# Add a glob of files
    use IO::Glob;
    $zip.add(glob("*.c"));

# When used in a method chain it will accept an Iterable and output a Seq
    # here is a somewhat contrived example
    glob("*.c").map().sort.$zip.uc.say ;

# Create a zip entry from a string/blob

$zip.create("file1", "payload data here");
    $zip.create("file2", Blob.new([2,4,6]));

# Drop a filehandle into the zip archive
    my $handle = "some file".IO.open;
    $zip.create("file3", $handle);

# below is equivalent to $zip.add: "somefile", name:("file5");
    $zip.create("file5"), "somefile".IO;

# but means you can add a file like this as long as the value is an IO
    $zip<file6> = "/some/other/file".IO ;

$zip.close();

Simple write-only interface to allow creation of Zip files in the filesystem.

Please note - this is module is a prototype. The interface will change.

METHODS

method new($filename [, options] )

Instantiate a SimpleZip object

my $zip = SimpleZip.new: "my.zip";

Takes one mandatoty parameter, namely the name of the zip file to create in the filesystem, and zero or more optional parameters.

Options

Most of these options control the setting of defaults that will be used in subsequent calls to the add or create methods.

The default setting can be overridden for an individual member where the constructor, new, and the add/create methods have an identically named options.

For example:

#  Set the default to make all members in the archive streamed.
    my $zip = SimpleZip.new($archive, :stream);

# This uses the default, so is streamed
    $zip.add: "file1" ;

# This changes the default, so is NOT streamed
    $zip.add("file2".IO, :!stream)  ;

# This uses the default, so is streamed
    $zip.add("file3".IO)  ;

stream => True|False

Write the zip archive in streaming mode. Default is False.

my $zip = SimpleZip.new($archive, :stream);

Specify the stream option on individual calls to add/create to override this default.

method => Zip-CM-Deflate|Zip-CM-Store

Used to set the default compression algorithm used for all members of the archive. If not specified then <Zip-CM-Deflate> is the default.

The exception is when the code is certain there is no payload data to be stored in the zip archive, in which case Zip-CM-Store will be used. Examples are for empty files, or directories.

Specify the method option on individual calls to add/create to override this default.

Valid values are

• Zip-CM-Deflate

• Zip-CM-Store

comment => String

Creates a comment for the archive.

my $zip = SimpleZip.new($archive, :comment<filefile comment>);

canonical-name => True|False

Used to set the default for normalizing the name field before it is written to the zip archive. The normalization carried out involves converting the name into a Unix-style relative path.

For example, the following shows how to disable the normalization of filenames:

my $zip = SimpleZip.new($archive, :!canonical-name);

Below is what APPNOTE.TXT (the specification for Zip archives) has to say on what should be stored in the zip name header field.

The name of the file, with optional relative path.
    The path stored MUST not contain a drive or
    device letter, or a leading slash.  All slashes
    MUST be forward slashes '/' as opposed to
    backwards slashes '\' for compatibility with Amiga
    and UNIX file systems etc.

Unless you have a use-case that needs non-standard Zip member names, you should leave this option well alone.

Unsurprizingly then, the default for this option is True.

Bool zip64 => True|False

TODO -- this option has not been implemented yet.

Specify the zip64 option on individual call to add to override this default.

method add($filename|@filenames [,options])

Used to add one or more a files to a Zip archive. The method expects one mandatory parameter and zero or more optional parameters.

The first, mandatory, parameter contains the filename (or filenames) to be added to the zip file. The method returns the number of files added.

To add a single file from the filesystem the first parameter must be coercable to IO::Path

# Add a single file to the zip archive
    $zip.add("/tmp/fred");

Multiple files can be added in one step by passing add an Iterable, like so

my @files = 'file1.txt', 'file2.txt';
    $zip.add: @files;

or via the Seq that File::Find uses

use File::Find;
    $zip.add: find(:dir<.>));

or via an IO::Glob

use IO::Glob;
    $zip.add: glob("*.c");

Options

name => String

Override the name field in the zip archive.

By default add will use a normalized version of the filename that is passed in the first parameter. When the name option is supplied, the value passed in the option will be stored in the Zip archive, rather than the filename.

If the canonical-name option is also True, the value of the name option will be normalized to Unix format before being written to the Zip archive.

method => Zip-CM-Deflate|Zip-CM-Store

Used to set the compression algorithm used for this member. If method has not been specifed here or in new it will default to Zip-CM-Deflate.

Valid values are

• Zip-CM-Deflate

• Zip-CM-Store

Bool stream => True|False

Write this member in streaming mode.

comment => String

Creates a comment for the member.

my $zip = SimpleZip.new($archive, :comment<my comment>);

Note: this is different from the comment option in the new method.

canonical-name => True|False

Controls how the name field is written top the zip archive.

zip64 => True|False

method create($name, $payload [, options])

Create a zip entry using a string or a blob for the payload data. Takes two mandatory parameters, namely the name of the zip entry to be written to the zipfile and the payload data to be compressed. Also takes zero or more optional parameters.

To add a string/blob to a zip archive

# Create a zip entry from a string
    $zip.create("file1", "payload data here");

# Create a zip entry from a blob
    $zip.create("file2", Blob.new([2,4,6]));

Drop a filehandle into the zip archive

my $handle = "some file".IO.open;
    $zip.create("file3", $handle);

create also provides nother way to write the contents of a file into a zipfile. The payload paramter must of of type IO for this to work.

$zip.create("file4", "/a/real/filename".IO);

Behind the scenes create will be used if Associative syntax is used

$zip<file5> = "payload data";
    $zip<file6> = Blob.new([2,4,6]);
    $zip<file7> = $filehandle;
    $zip<file8> = "/a/real/filename".IO;

Options

Same options as add.

method close

Does the following

• Writes the zip file central directory to the output file

• closes the file

Use of SimpleZip in a Method Chain

It is possible to use this module in a method chain. For example, you could add all the files matched by File::Find using the add method

use Archive::SimpleZip;
    use File::Find;

my $zip = SimpleZip.new: "test.zip";

$zip.add: find(:dir<.>));

$zip.close;

Alternatively,instead of using the add method you can use this to achieve the same thing

find(:dir<.>).$zip;

Here is a more complex example

my $zip = SimpleZip: "my.zip";
    find(:dir<.>).grep( ! *.d).$zip.uc.sort.say ;
    $z.close();

this chain does the following

• use find to get a list of files

• uses grep to discard directories

• add the remaining files to the zip file

• converts the filenames to upper case

• displays the uppercase filename

TODO

• Zip64

• Bzip2

Bzip2 suppport is written but disabled because Compress::Bzip2 isn't building on Winows or MacOS.

• Support for extra fields

• Standard extra fields to store more accurate timestams.