diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/IO/Compress/Zip.pm')
-rw-r--r-- | Master/tlpkg/tlperl/lib/IO/Compress/Zip.pm | 460 |
1 files changed, 298 insertions, 162 deletions
diff --git a/Master/tlpkg/tlperl/lib/IO/Compress/Zip.pm b/Master/tlpkg/tlperl/lib/IO/Compress/Zip.pm index eabeef63e76..70b98b80d6e 100644 --- a/Master/tlpkg/tlperl/lib/IO/Compress/Zip.pm +++ b/Master/tlpkg/tlperl/lib/IO/Compress/Zip.pm @@ -4,30 +4,30 @@ use strict ; use warnings; use bytes; -use IO::Compress::Base::Common 2.084 qw(:Status ); -use IO::Compress::RawDeflate 2.084 (); -use IO::Compress::Adapter::Deflate 2.084 ; -use IO::Compress::Adapter::Identity 2.084 ; -use IO::Compress::Zlib::Extra 2.084 ; -use IO::Compress::Zip::Constants 2.084 ; +use IO::Compress::Base::Common 2.093 qw(:Status ); +use IO::Compress::RawDeflate 2.093 (); +use IO::Compress::Adapter::Deflate 2.093 ; +use IO::Compress::Adapter::Identity 2.093 ; +use IO::Compress::Zlib::Extra 2.093 ; +use IO::Compress::Zip::Constants 2.093 ; use File::Spec(); use Config; -use Compress::Raw::Zlib 2.084 (); +use Compress::Raw::Zlib 2.093 (); BEGIN { eval { require IO::Compress::Adapter::Bzip2 ; - import IO::Compress::Adapter::Bzip2 2.084 ; + import IO::Compress::Adapter::Bzip2 2.093 ; require IO::Compress::Bzip2 ; - import IO::Compress::Bzip2 2.084 ; + import IO::Compress::Bzip2 2.093 ; } ; eval { require IO::Compress::Adapter::Lzma ; - import IO::Compress::Adapter::Lzma 2.084 ; + import IO::Compress::Adapter::Lzma 2.093 ; require IO::Compress::Lzma ; - import IO::Compress::Lzma 2.084 ; + import IO::Compress::Lzma 2.093 ; } ; } @@ -36,7 +36,7 @@ require Exporter ; our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, %DEFLATE_CONSTANTS, $ZipError); -$VERSION = '2.084'; +$VERSION = '2.093'; $ZipError = ''; @ISA = qw(IO::Compress::RawDeflate Exporter); @@ -246,13 +246,17 @@ sub mkHeader &{ *$self->{ZipData}{FilterName} }() ; } -# if ( $param->getValue('utf8') ) { -# require Encode ; -# $filename = Encode::encode_utf8($filename) -# if length $filename ; -# $comment = Encode::encode_utf8($comment) -# if length $comment ; -# } + if ( $param->getValue('efs') && $] >= 5.008004) { + if (length $filename) { + utf8::downgrade($filename, 1) + or Carp::croak "Wide character in zip filename"; + } + + if (length $comment) { + utf8::downgrade($comment, 1) + or Carp::croak "Wide character in zip comment"; + } + } my $hdr = ''; @@ -325,8 +329,8 @@ sub mkHeader $gpFlag |= ZIP_GP_FLAG_LZMA_EOS_PRESENT if $method == ZIP_CM_LZMA ; -# $gpFlag |= ZIP_GP_FLAG_LANGUAGE_ENCODING -# if $param->getValue('utf8') && (length($filename) || length($comment)); + $gpFlag |= ZIP_GP_FLAG_LANGUAGE_ENCODING + if $param->getValue('efs') && (length($filename) || length($comment)); my $version = $ZIP_CM_MIN_VERSIONS{$method}; $version = ZIP64_MIN_VERSION @@ -682,7 +686,7 @@ our %PARAMS = ( 'name' => [IO::Compress::Base::Common::Parse_any, ''], 'filtername'=> [IO::Compress::Base::Common::Parse_code, undef], 'canonicalname'=> [IO::Compress::Base::Common::Parse_boolean, 0], -# 'utf8' => [IO::Compress::Base::Common::Parse_boolean, 0], + 'efs' => [IO::Compress::Base::Common::Parse_boolean, 0], 'time' => [IO::Compress::Base::Common::Parse_any, undef], 'extime' => [IO::Compress::Base::Common::Parse_any, undef], 'exunix2' => [IO::Compress::Base::Common::Parse_any, undef], @@ -905,7 +909,6 @@ IO::Compress::Zip - Write zip files/buffers binmode $z fileno $z close $z ; - =head1 DESCRIPTION @@ -916,14 +919,18 @@ The primary purpose of this module is to provide streaming write access to zip files and buffers. It is not a general-purpose file archiver. If that is what you want, check out C<Archive::Zip> or C<Archive::Zip::SimpleZip>. -At present three compression methods are supported by IO::Compress::Zip, +At present the following compression methods are supported by IO::Compress::Zip, namely Store (no compression at all), Deflate, Bzip2 and LZMA. -Note that to create Bzip2 content, the module C<IO::Compress::Bzip2> must -be installed. +B<Note> + +=over 5 + +=item * To use Bzip2 compression, the module C<IO::Compress::Bzip2> must be installed. -Note that to create LZMA content, the module C<IO::Compress::Lzma> must -be installed. +=item * To use LZMA compression, the module C<IO::Compress::Lzma> must be installed. + +=back For reading zip files/buffers, see the companion module L<IO::Uncompress::Unzip|IO::Uncompress::Unzip>. @@ -945,7 +952,8 @@ The functional interface needs Perl5.005 or better. =head2 zip $input_filename_or_reference => $output_filename_or_reference [, OPTS] C<zip> expects at least two parameters, -C<$input_filename_or_reference> and C<$output_filename_or_reference>. +C<$input_filename_or_reference> and C<$output_filename_or_reference> +and zero or more optional parameters (see L</Optional Parameters>) =head3 The C<$input_filename_or_reference> parameter @@ -958,7 +966,7 @@ It can take one of the following forms: =item A filename -If the <$input_filename_or_reference> parameter is a simple scalar, it is +If the C<$input_filename_or_reference> parameter is a simple scalar, it is assumed to be a filename. This file will be opened for reading and the input data will be read from it. @@ -1062,9 +1070,9 @@ in C<$output_filename_or_reference> as a distinct entry. =head2 Optional Parameters -Unless specified below, the optional parameters for C<zip>, -C<OPTS>, are the same as those used with the OO interface defined in the -L</"Constructor Options"> section below. +The optional parameters for the one-shot function C<zip> +are (for the most part) identical to those used with the OO interface defined in the +L</"Constructor Options"> section. The exceptions are listed below =over 5 @@ -1132,6 +1140,50 @@ Defaults to 0. =head2 Examples +Here are a few example that show the capabilities of the module. + +=head3 Streaming + +This very simple command line example demonstrates the streaming capabilities of the module. +The code reads data from STDIN, compresses it, and writes the compressed data to STDOUT. + + $ echo hello world | perl -MIO::Compress::Zip=zip -e 'zip \*STDIN => \*STDOUT' >output.zip + +The special filename "-" can be used as a standin for both C<\*STDIN> and C<\*STDOUT>, +so the above can be rewritten as + + $ echo hello world | perl -MIO::Compress::Zip=zip -e 'zip "-" => "-"' >output.zip + +One problem with creating a zip archive directly from STDIN can be demonstrated by looking at +the contents of the zip file, output.zip, that we have just created. + + $ unzip -l output.zip + Archive: output.zip + Length Date Time Name + --------- ---------- ----- ---- + 12 2019-08-16 22:21 + --------- ------- + 12 1 file + +The archive member (filename) used is the empty string. + +If that doesn't suit your needs, you can explicitly set the filename used +in the zip archive by specifying the L<Name|"File Naming Options"> option, like so + + echo hello world | perl -MIO::Compress::Zip=zip -e 'zip "-" => "-", Name => "hello.txt"' >output.zip + +Now the contents of the zip file looks like this + + $ unzip -l output.zip + Archive: output.zip + Length Date Time Name + --------- ---------- ----- ---- + 12 2019-08-16 22:22 hello.txt + --------- ------- + 12 1 file + +=head3 Compressing a file from the filesystem + To read the contents of the file C<file1.txt> and write the compressed data to the file C<file1.txt.zip>. @@ -1143,6 +1195,8 @@ data to the file C<file1.txt.zip>. zip $input => "$input.zip" or die "zip failed: $ZipError\n"; +=head3 Reading from a Filehandle and writing to an in-memory buffer + To read from an existing Perl filehandle, C<$input>, and write the compressed data to a buffer, C<$buffer>. @@ -1157,6 +1211,8 @@ compressed data to a buffer, C<$buffer>. zip $input => \$buffer or die "zip failed: $ZipError\n"; +=head3 Compressing multiple files + To create a zip file, C<output.zip>, that contains the compressed contents of the files C<alpha.txt> and C<beta.txt> @@ -1235,7 +1291,7 @@ return undef. =head2 Constructor Options -C<OPTS> is any combination of the following options: +C<OPTS> is any combination of zero or more the following options: =over 5 @@ -1278,22 +1334,52 @@ to it. Otherwise the file pointer will not be moved. This parameter defaults to 0. +=back + +=head3 File Naming Options + +A quick bit of zip file terminology -- A zip archive consists of one or more I<archive members>, where each member has an associated +filename, known as the I<archive member name>. + +The options listed in this section control how the I<archive member name> (or filename) is stored the zip archive. + +=over 5 + =item C<< Name => $string >> -Stores the contents of C<$string> in the zip filename header field. +This option is used to explicitly set the I<archive member name> in +the zip archive to C<$string>. +Most of the time you don't need to make use of this option. +By default when adding a filename to the zip archive, the I<archive member name> will match the filename. + +You should only need to use this option if you want the I<archive member name> +to be different from the uncompressed filename or when the input is a filehandle or a buffer. -If C<Name> is not specified and the C<$input> parameter is a filename, the -value of C<$input> will be used for the zip filename header field. +The default behaviour for what I<archive member name> is used when the C<Name> option +is I<not> specified depends on the form of the C<$input> parameter: + +=over 5 -If C<Name> is not specified and the C<$input> parameter is not a filename, -no zip filename field will be created. +=item * + +If the C<$input> parameter is a filename, the +value of C<$input> will be used for the I<archive member name> . + +=item * +If the C<$input> parameter is not a filename, +the I<archive member name> will be an empty string. + +=back Note that both the C<CanonicalName> and C<FilterName> options -can modify the value used for the zip filename header field. +can modify the value used for the I<archive member name>. + +Also note that you should set the C<Efs> option to true if you are working +with UTF8 filenames. =item C<< CanonicalName => 0|1 >> -This option controls whether the filename field in the zip header is +This option controls whether the I<archive member name> is I<normalized> into Unix format before being written to the zip file. It is recommended that you enable this option unless you really need @@ -1313,15 +1399,14 @@ This option defaults to B<false>. =item C<< FilterName => sub { ... } >> -This option allow the filename field in the zip header to be modified +This option allow the I<archive member> name to be modified before it is written to the zip file. This option takes a parameter that must be a reference to a sub. On entry to the sub the C<$_> variable will contain the name to be filtered. If no filename is available C<$_> will contain an empty string. -The value of C<$_> when the sub returns will be stored in the filename -header field. +The value of C<$_> when the sub returns will be used as the I<archive member name>. Note that if C<CanonicalName> is enabled, a normalized filename will be passed to the sub. @@ -1343,6 +1428,167 @@ filenames before they are stored in C<$zipfile>. FilterName => sub { s[^$dir/][] } ; } +=item C<< Efs => 0|1 >> + +This option controls setting of the "Language Encoding Flag" (EFS) in the zip +archive. When set, the filename and comment fields for the zip archive MUST +be valid UTF-8. + +If the string used for the filename and/or comment is not valid UTF-8 when this option +is true, the script will die with a "wide character" error. + +Note that this option only works with Perl 5.8.4 or better. + +This option defaults to B<false>. + +=back + +=head3 Overall Zip Archive Structure + +=over 5 + +=item C<< Minimal => 1|0 >> + +If specified, this option will disable the creation of all extra fields +in the zip local and central headers. So the C<exTime>, C<exUnix2>, +C<exUnixN>, C<ExtraFieldLocal> and C<ExtraFieldCentral> options will +be ignored. + +This parameter defaults to 0. + +=item C<< Stream => 0|1 >> + +This option controls whether the zip file/buffer output is created in +streaming mode. + +Note that when outputting to a file with streaming mode disabled (C<Stream> +is 0), the output file must be seekable. + +The default is 1. + +=item C<< Zip64 => 0|1 >> + +Create a Zip64 zip file/buffer. This option is used if you want +to store files larger than 4 Gig or store more than 64K files in a single +zip archive. + +C<Zip64> will be automatically set, as needed, if working with the one-shot +interface when the input is either a filename or a scalar reference. + +If you intend to manipulate the Zip64 zip files created with this module +using an external zip/unzip, make sure that it supports Zip64. + +In particular, if you are using Info-Zip you need to have zip version 3.x +or better to update a Zip64 archive and unzip version 6.x to read a zip64 +archive. + +The default is 0. + +=back + +=head3 Deflate Compression Options + +=over 5 + +=item -Level + +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. + +Note, these constants are not imported by C<IO::Compress::Zip> by default. + + use IO::Compress::Zip qw(:strategy); + use IO::Compress::Zip qw(:constants); + use IO::Compress::Zip qw(:all); + +=item -Strategy + +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. + +=back + +=head3 Bzip2 Compression Options + +=over 5 + +=item C<< BlockSize100K => number >> + +Specify the number of 100K blocks bzip2 uses during compression. + +Valid values are from 1 to 9, where 9 is best compression. + +This option is only valid if the C<Method> is ZIP_CM_BZIP2. It is ignored +otherwise. + +The default is 1. + +=item C<< 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. + +This option is only valid if the C<Method> is ZIP_CM_BZIP2. It is ignored +otherwise. + +The default is 0. + +=back + +=head3 Lzma Compression Options + +=over 5 + +=item C<< Preset => number >> + +Used to choose the LZMA compression preset. + +Valid values are 0-9 and C<LZMA_PRESET_DEFAULT>. + +0 is the fastest compression with the lowest memory usage and the lowest +compression. + +9 is the slowest compression with the highest memory usage but with the best +compression. + +This option is only valid if the C<Method> is ZIP_CM_LZMA. It is ignored +otherwise. + +Defaults to C<LZMA_PRESET_DEFAULT> (6). + +=item C<< Extreme => 0|1 >> + +Makes LZMA compression a lot slower, but a small compression gain. + +This option is only valid if the C<Method> is ZIP_CM_LZMA. It is ignored +otherwise. + +Defaults to 0. + +=back + +=head3 Other Options + +=over 5 + =item C<< Time => $number >> Sets the last modified time field in the zip header to $number. @@ -1424,6 +1670,8 @@ By default no UnixN extra field is created. Stores the contents of C<$comment> in the Central File Header of the zip file. +Set the C<Efs> option to true if you want to store a UTF8 comment. + By default, no comment field is written to the zip file. =item C<< ZipComment => $comment >> @@ -1458,34 +1706,6 @@ content when C<IO::Compress::Lzma> is not available. The default method is ZIP_CM_DEFLATE. -=item C<< Stream => 0|1 >> - -This option controls whether the zip file/buffer output is created in -streaming mode. - -Note that when outputting to a file with streaming mode disabled (C<Stream> -is 0), the output file must be seekable. - -The default is 1. - -=item C<< Zip64 => 0|1 >> - -Create a Zip64 zip file/buffer. This option is used if you want -to store files larger than 4 Gig or store more than 64K files in a single -zip archive. - -C<Zip64> will be automatically set, as needed, if working with the one-shot -interface when the input is either a filename or a scalar reference. - -If you intend to manipulate the Zip64 zip files created with this module -using an external zip/unzip, make sure that it supports Zip64. - -In particular, if you are using Info-Zip you need to have zip version 3.x -or better to update a Zip64 archive and unzip version 6.x to read a zip64 -archive. - -The default is 0. - =item C<< TextFlag => 0|1 >> This parameter controls the setting of a bit in the zip central header. It @@ -1546,96 +1766,6 @@ If the C<Minimal> option is set to true, this option will be ignored. The maximum size of an extra field 65535 bytes. -=item C<< Minimal => 1|0 >> - -If specified, this option will disable the creation of all extra fields -in the zip local and central headers. So the C<exTime>, C<exUnix2>, -C<exUnixN>, C<ExtraFieldLocal> and C<ExtraFieldCentral> options will -be ignored. - -This parameter defaults to 0. - -=item C<< BlockSize100K => number >> - -Specify the number of 100K blocks bzip2 uses during compression. - -Valid values are from 1 to 9, where 9 is best compression. - -This option is only valid if the C<Method> is ZIP_CM_BZIP2. It is ignored -otherwise. - -The default is 1. - -=item C<< 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. - -This option is only valid if the C<Method> is ZIP_CM_BZIP2. It is ignored -otherwise. - -The default is 0. - -=item C<< Preset => number >> - -Used to choose the LZMA compression preset. - -Valid values are 0-9 and C<LZMA_PRESET_DEFAULT>. - -0 is the fastest compression with the lowest memory usage and the lowest -compression. - -9 is the slowest compression with the highest memory usage but with the best -compression. - -This option is only valid if the C<Method> is ZIP_CM_LZMA. It is ignored -otherwise. - -Defaults to C<LZMA_PRESET_DEFAULT> (6). - -=item C<< Extreme => 0|1 >> - -Makes LZMA compression a lot slower, but a small compression gain. - -This option is only valid if the C<Method> is ZIP_CM_LZMA. It is ignored -otherwise. - -Defaults to 0. - -=item -Level - -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. - -Note, these constants are not imported by C<IO::Compress::Zip> by default. - - use IO::Compress::Zip qw(:strategy); - use IO::Compress::Zip qw(:constants); - use IO::Compress::Zip qw(:all); - -=item -Strategy - -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. - =item C<< Strict => 0|1 >> This is a placeholder option. @@ -1918,6 +2048,12 @@ See L<IO::Compress::FAQ|IO::Compress::FAQ/"Apache::GZip Revisited"> See L<IO::Compress::FAQ|IO::Compress::FAQ/"Compressed files and Net::FTP"> +=head1 SUPPORT + +General feedback/questions/bug reports should be sent to +L<https://github.com/pmqs/IO-Compress/issues> (preferred) or +L<https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Compress>. + =head1 SEE ALSO L<Compress::Zlib>, L<IO::Compress::Gzip>, L<IO::Uncompress::Gunzip>, L<IO::Compress::Deflate>, L<IO::Uncompress::Inflate>, L<IO::Compress::RawDeflate>, L<IO::Uncompress::RawInflate>, L<IO::Compress::Bzip2>, L<IO::Uncompress::Bunzip2>, L<IO::Compress::Lzma>, L<IO::Uncompress::UnLzma>, L<IO::Compress::Xz>, L<IO::Uncompress::UnXz>, L<IO::Compress::Lzip>, L<IO::Uncompress::UnLzip>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Compress::Zstd>, L<IO::Uncompress::UnZstd>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress> |