view release on metacpan or  search on metacpan

lib/Archive/Zip/SimpleZip.pm  view on Meta::CPAN

    # store 'my/abc.txt' in the zip archive
    $z->add('/my/abc.txt') ;

    # store '/my/abc.txt' in the zip archive as an absolute path
    $z->add('/my/abc.txt', CanonoicalName => 0) ;

    # store '/some/file' as 'xyz' in the zip archive
    $z->add('/some/file', Name => 'xyz') ;

    # store 'file3.txt' in the zip archive by using a filter to remove the leading path
    $z->add('/my/file3.txt', FilterName => sub { s#.*/## } ) ;

    # no Name option, so store "" as the name 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 as an absolute path
    $z->addString('payload data', Name => '/abc/def', CanonoicalName => 0) ;

    $z->close();


=head2 Overall Zip Archive Structure

=over 5

=item C<< Minimal => 1|0 >>

If specified, this option will disable the automatic creation of all
I<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

    "UT" Extended Timestamp
    "ux" ExtraExtra Type 3 (if running Unix)


This option is useful in a number of scenarios.

Firstly, it may be needed if you require the zip files created by
C<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.

The other main use-case when C<Minimal> is handy is when the data that
C<Minimal> suppresses is not needed, and so just adds unnecessary bloat to
the zip file.  The extra fields that C<Archive::Zip::SimpleZip> adds by
default all store information that assume the entry in the zip file
corresponds to a file that will be stored in a filesystem.  This
information is very useful 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>.

This parameter defaults to 0.

=item C<< Stream => 0|1 >>

This option controls whether the zip archive is created in I<streaming
mode>.

Note that when outputting to a file or filehandle with streaming mode
disabled (C<Stream> is 0), the output file/handle I<must> be seekable.

When outputting to '-' (STDOUT) the C<Stream> option is automatically
enabled.

The default is 0.

=item C<< Zip64 => 0|1 >>

ZIP64 is an extension to the Zip archive structure that allows

=over 5

=item * Zip archives larger than 4Gig.

=item * Zip archives with more that 64K members.

=back

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.

The default is 0.

=back

=head2 Other Options

=over 5

=item C<< AutoFlush => 0|1 >>

When true this option enabled flushing of the underlying filehandle after
each write/print operation.

If SimpleZip is writing to a buffer, this option is ignored.



=item C<< Comment => $comment >>

This option allows the creation of a comment that is associated with the
member added to the zip archive with the C<add> and C<addString> methods.

This option is not valid in the constructor.

By default, no comment field is written to the zip archive.

=item C<< Encode => "encoding" >>

The C<Encode> option allows you to set the character encoding of the data
before it is compressed and written to the zip file. The option is only
valid with the C<add> or C<addString> methods. It will be ignored if you
use it with the C<add> option.

lib/Archive/Zip/SimpleZip.pm  view on Meta::CPAN

    Z_DEFAULT_COMPRESSION

=item :strategy

These symbolic constants are used by the C<Strategy> option in the
constructor.

    Z_FILTERED
    Z_HUFFMAN_ONLY
    Z_RLE
    Z_FIXED
    Z_DEFAULT_STRATEGY

=item :zip_method

These symbolic constants are used by the C<Method> option in the
constructor.

    ZIP_CM_STORE
    ZIP_CM_DEFLATE
    ZIP_CM_BZIP2

=back

=head1 FAQ


=head2 Can SimpleZip update an existing Zip file?

No. You can only create a zip file from scratch.

=head2 Can I write a Zip Archive to STDOUT?

Yes. Writing zip files to filehandles that are not seekable (so that
includes both STDOUT and sockets) is supported by this module. You just
have to set the C<Stream> option when you call the constructor.

    use Archive::Zip::SimpleZip qw($SimpleZipError) ;

    my $zipData ;
    my $z = Archive::Zip::SimpleZip->new('-'),
                        Stream => 1
        or die "$SimpleZipError\n" ;

    $z->add("file1.txt");
    $z->close();

See L</What is a Streamed Zip file?> for a discussion on the C<Stream>
option.

=head2 Can I write a Zip Archive directly to a socket?

See previous question.

=head2 What is a Streamed Zip file?

Streaming mode allows you to write a zip file in situation where you cannot
seek backwards/forwards. The classic examples are when you are working with
sockets or need to write the zip file to STDOUT.

By default C<Archive::Zip::SimpleZip> does I<not> use streaming mode when
writing to a zip file (you need to set the C<Stream> option to 1 to enable
it).

If you plan to create a streamed Zip file be aware that it will be slightly
larger than the non-streamed equivalent. If the files you archive are
32-bit the overhead will be an extra 16 bytes per file written to the zip
archive. For 64-bit it is 24 bytes per file.

=head1 SUPPORT

General feedback/questions/bug reports should be sent to
L<https://github.com/pmqs/Archive-Zip-SimpleZip/issues> (preferred) or
L<https://rt.cpan.org/Public/Dist/Display.html?Name=Archive-Zip-SimpleZip>.

=head1 SEE ALSO


L<Archive::Zip::SimpleUnzip>, L<IO::Compress::Zip>, L<Archive::Zip>, L<IO::Uncompress::UnZip>


=head1 AUTHOR

This module was written by Paul Marquess, F<pmqs@cpan.org>.

=head1 MODIFICATION HISTORY

See the Changes file.

=head1 COPYRIGHT AND LICENSE

Copyright (c) 2012-2024 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.