1Archive::Zip::SimpleZipU(s3e)r Contributed Perl DocumentaAtricohnive::Zip::SimpleZip(3)
2
3
4

NAME

6       Archive::Zip::SimpleZip - Create Zip Archives
7

SYNOPSIS

9           use Archive::Zip::SimpleZip qw($SimpleZipError) ;
10
11           my $z = new Archive::Zip::SimpleZip "my.zip"
12               or die "Cannot create zip file: $SimpleZipError\n" ;
13
14           $z->add("/some/file1.txt");
15           $z->addString("some text", Name => "myfile");
16           $z->addFileHandle($FH, Name => "myfile2") ;
17
18           $fh = $z->openMember(Name => "mydata1.txt");
19           print $fh "some data" ;
20           $fh->print("some more data") ;
21           close $fh;
22
23           $z->close();
24

DESCRIPTION

26       Archive::Zip::SimpleZip is a module that allows the creation of Zip
27       archives. For reading Zip archives, there is a companion module, called
28       Archive::Zip::SimpleUnzip, that can read Zip archives.
29
30       The module allows Zip archives to be written to a named file, a
31       filehandle or stored in-memory.
32
33       There are a small number methods available in Archive::Zip::SimpleZip,
34       and quite a few options, but for the most part all you need to know is
35       how to create a Zip archive and how to add a file to it.
36
37       Below is an example of how this module is used to add the two files
38       "file1.txt" and "file2.txt" to the zip file called "my1.zip".
39
40           use Archive::Zip::SimpleZip qw($SimpleZipError) ;
41
42           my $z = new Archive::Zip::SimpleZip "my1.zip"
43               or die "Cannot create zip file: $SimpleZipError\n" ;
44
45           $z->add("/some/file1.txt");
46           $z->add("/some/file2.txt");
47
48           $z->close();
49
50       The data written to a zip archive doesn't need to come from the
51       filesystem.  You can also write string data directly to the zip archive
52       using the "addString" method, like this
53
54           use Archive::Zip::SimpleZip qw($SimpleZipError) ;
55
56           my $z = new Archive::Zip::SimpleZip "my2.zip"
57               or die "Cannot create zip file: $SimpleZipError\n" ;
58
59           $z->addString($myData, Name => "file2.txt");
60
61           $z->close();
62
63       Alternatively you can use the "openMember" option to get a filehandle
64       that allows you to write directly to the zip archive member using
65       standard Perl file output functions, like "print".
66
67           use Archive::Zip::SimpleZip qw($SimpleZipError) ;
68
69           my $z = new Archive::Zip::SimpleZip "my3.zip"
70               or die "Cannot create zip file: $SimpleZipError\n" ;
71
72           my $fh = $z->openMember(Name => "file3.txt");
73
74           $fh->print("some data");
75           # can also use print $fh "some data"
76
77           print $fh "more data" ;
78
79           $fh->close() ;
80           # can also use close $fh;
81
82           $z->close();
83
84       You can also "drop" a filehandle into a zip archive.
85
86           use Archive::Zip::SimpleZip qw($SimpleZipError) ;
87
88           my $z = new Archive::Zip::SimpleZip "my4.zip"
89               or die "Cannot create zip file: $SimpleZipError\n" ;
90
91           my $fh = $z->addFileHandle(FH, Name => "file3.txt");
92
93           $z->close();
94
95   Constructor
96            $z = new Archive::Zip::SimpleZip "myzipfile.zip" [, OPTIONS] ;
97            $z = new Archive::Zip::SimpleZip \$buffer [, OPTIONS] ;
98            $z = new Archive::Zip::SimpleZip $filehandle [, OPTIONS] ;
99
100       The constructor takes one mandatory parameter along with zero or more
101       optional parameters.
102
103       The mandatory parameter controls where the zip archive is written.
104       This can be any of the following
105
106       •    Output to a File
107
108            When SimpleZip is passed a string, it will write the zip archive
109            to the filename stored in the string.
110
111       •    Output to a String
112
113            When SimpleZip is passed a string reference, like "\$buffer", it
114            will write the zip archive into that string.
115
116       •    Output to a Filehandle
117
118            When SimpleZip is passed a filehandle, it will write the zip
119            archive to that filehandle.
120
121            Use the string '-' to write the zip archive to standard output
122            (Note - this will also enable the "Stream" option).
123
124       See "Options" for a list of the optional parameters that can be
125       specified when calling the constructor.
126
127   Methods
128       $z->add($filename [, OPTIONS])
129            The "add" method writes the contents of the filename stored in
130            $filename to the zip archive.
131
132            The following file types are supported.
133
134            •    Standard files
135
136                 The contents of the file is written to the zip archive.
137
138            •    Directories
139
140                 The directory name is stored in the zip archive.
141
142            •    Symbolic Links
143
144                 By default this module will store the contents of the file
145                 that the symbolic link refers to.  To store the symbolic link
146                 itself set the "StoreLink" option to 1.
147
148            By default the name of the member created in the zip archive will
149            be derived from the value of the $filename parameter.  See "File
150            Naming Options" for more details.
151
152            See "Options" for a full list of the options available for this
153            method.
154
155            Returns 1 if the file was added, or 0. Check the $SimpleZipError
156            for a message.
157
158       $z->addString($string, Name => "whatever" [, OPTIONS])
159            The "addString" method writes <$string> to the zip archive. The
160            "Name" option must be supplied.
161
162            See "Options" for the options available for this method.
163
164            Returns 1 if the file was added, or 0. Check the $SimpleZipError
165            for a message.
166
167       $z->addFileHandle($fh, Name => "whatever" [, OPTIONS])
168            The "addFileHandle" method assumes that $fh is a valid filehandle
169            that is opened for reading.
170
171            It writes what is read from $fh to the zip archive until it
172            reaches the eof. The filehandle, $fh, will not be closed by
173            "addFileHandle".
174
175            The "Name" option must be supplied.
176
177            See "Options" for the options available for this method.
178
179            Returns 1 if the file was added, or 0. Check the $SimpleZipError
180            for a message.
181
182       my $fh = $z->openMember(Name => "abc" [, OPTIONS]);
183            This option returns a filehandle ($fh)that allows you to write
184            directly to a zip member. The "Name" option must be supplied.  See
185            "Options" for the options available for this method.
186
187            The filehandle returned works just like a standard Perl
188            filehandle, so all the standard file output operators, like
189            "print", are available to write to the zip archive.
190
191            When you have finished writing data to the member, close the
192            filehandle by letting it go out of scope or by explicitly using
193            either of the two forms shown below
194
195                $fh->close()
196                close $fh;
197
198            Once the filehandle is closed you can then open another member
199            with "openMember" or use the "add" or <addString> or
200            ""addFilehandle> methods.
201
202            Note that while a zip member has been opened with "openMember",
203            you cannot use the "add" or <addString> methods, or open another
204            member with "openMember".
205
206            Also, if the enclosing zip object is closed whilst a filehandle is
207            still open for a zip member, it will be closed automatically.
208
209            Returns a filehandle on success or "undef" on failure.
210
211       $z->close()
212            Returns 1 if the zip archive was closed successfully, or 0. Check
213            the $SimpleZipError for a message.
214

Options

216       The majority of options are valid in both the constructor and in the
217       methods that accept options. Any exceptions are noted in the text
218       below.
219
220       Options specified in the constructor will be used as the defaults for
221       all subsequent method calls.
222
223       For example, in the constructor below, the "Method" is set to
224       "ZIP_CM_STORE".
225
226           use Archive::Zip::SimpleZip qw($SimpleZipError) ;
227
228           my $z = new Archive::Zip::SimpleZip "my.zip",
229                                    Method => ZIP_CM_STORE
230               or die "Cannot create zip file: $SimpleZipError\n" ;
231
232           $z->add("file1");
233           $z->add("file2", Method => ZIP_CM_DEFLATE);
234           $z->add("file3");
235
236           $z->close();
237
238       The first call to "add" doesn't specify the "Method" option, so it uses
239       the value from the constructor ("ZIP_CM_STORE"). The second call
240       overrides the default set in the constructor to use "ZIP_CM_DEFLATE".
241       The third will revert to using the default, "ZIP_CM_STORE".
242
243   File Naming Options
244       A quick bit of zip file terminology -- A zip archive consists of one or
245       more archive members, where each member has an associated filename,
246       known as the archive member name.
247
248       The options listed in this section control how the archive member name
249       (or filename) is stored the zip archive.
250
251       "Name => $string"
252            This option is used to explicitly set the archive member name in
253            the zip archive to $string.
254
255            When used with the "add" method, this option will override any
256            filename that was passed as a parameter.
257
258            The "Name" option is mandatory for the "addString" method.
259
260            This option is not valid in the constructor.
261
262       "CanonicalName => 0|1"
263            This option controls whether the archive member name is normalized
264            into Unix format before being written to the zip archive.
265
266            It is recommended that you keep this option enabled unless you
267            really need to create a non-standard Zip archive.
268
269            This is what APPNOTE.TXT has to say on what should be stored in
270            the zip filename header field.
271
272                The name of the file, with optional relative path.
273                The path stored should not contain a drive or
274                device letter, or a leading slash.  All slashes
275                should be forward slashes '/' as opposed to
276                backwards slashes '\' for compatibility with Amiga
277                and UNIX file systems etc.
278
279            This option defaults to true.
280
281       "FilterName => sub { ... }"
282            This option allow the archive member name to be modified before it
283            is written to the zip archive.
284
285            This option takes a parameter that must be a reference to a sub.
286            On entry to the sub the $_ variable will contain the name to be
287            filtered. If no filename is available $_ will contain an empty
288            string.
289
290            The value of $_ when the sub returns will be  stored in the
291            filename header field.
292
293            Note that if "CanonicalName" is enabled, a normalized filename
294            will be passed to the sub.
295
296            If you use "FilterName" to modify the filename, it is your
297            responsibility to keep the filename in Unix format.
298
299            See "Rename whilst adding" for an example of how the "FilterName"
300            option can be used.
301
302       Taking all the options described above, the archive member name stored
303       in a Zip archive is constructed as follows.
304
305       The initial source for the archive member name that gets stored in the
306       zip archive is the filename parameter supplied to the "add" method, or
307       the value supplied with the "Name" option for the "addString" and
308       "openMember" methods.
309
310       Next, if the "add" method is used, and the "Name" option is supplied
311       that will overide the filename parameter.
312
313       If the "CanonicalName" option is enabled, and it is by default, the
314       archive member name gets normalized into Unix format.  If the filename
315       was absolute, it will be changed into a relative filename.
316
317       Finally, is the "FilterName" option is enabled, the filename will get
318       passed to the sub supplied via the $_ variable.  The value of $_ on
319       exit from the sub will get stored in the zip archive.
320
321       Here are some examples
322
323           use Archive::Zip::SimpleZip qw($SimpleZipError) ;
324
325           my $z = new Archive::Zip::SimpleZip "my.zip"
326               or die "$SimpleZipError\n" ;
327
328           # store "my/abc.txt" in the zip archive
329           $z->add("/my/abc.txt") ;
330
331           # store "/my/abc.txt" in the zip archive
332           $z->add("/my/abc.txt", CanonoicalName => 0) ;
333
334           # store "xyz" in the zip archive
335           $z->add("/some/file", Name => "xyz") ;
336
337           # store "file3.txt" in the zip archive
338           $z->add("/my/file3.txt", FilterName => sub { s#.*/## } ) ;
339
340           # no Name option, so store "" in the zip archive
341           $z->addString("payload data") ;
342
343           # store "xyz" in the zip archive
344           $z->addString("payload data", Name => "xyz") ;
345
346           # store "/abc/def" in the zip archive
347           $z->addString("payload data", Name => "/abc/def", CanonoicalName => 0) ;
348
349           $z->close();
350
351   Overall Zip Archive Structure
352       "Minimal => 1|0"
353            If specified, this option will disable the automatic creation of
354            all extra fields in the zip local and central headers (with the
355            exception of those needed for Zip64).
356
357            In particular the following fields will not be created
358
359                "UT" Extended Timestamp
360                "ux" ExtraExtra Type 3 (if running Unix)
361
362            This option is useful in a number of scenarios.
363
364            Firstly, it may be needed if you require the zip files created by
365            "Archive::Zip::SimpleZip" to be read using a legacy version of
366            unzip or by an application that only supports a sub-set of the zip
367            features.
368
369            The other main use-case when "Minimal" is handy is when the data
370            that "Minimal" suppresses is not needed, and so just adds
371            unnecessary bloat to the zip file.  The extra fields that
372            "Archive::Zip::SimpleZip" adds by default all store information
373            that assume the entry in the zip file corresponds to a file that
374            will be stored in a filesystem.  This information is very useful
375            when archiving files from a filesystem - it means the unzipped
376            files will more closely match their originals.  If the zip file
377            isn't going to be unzipped to a filesystem you can save a few
378            bytes by enabling <Minimal>.
379
380            This parameter defaults to 0.
381
382       "Stream => 0|1"
383            This option controls whether the zip archive is created in
384            streaming mode.
385
386            Note that when outputting to a file or filehandle with streaming
387            mode disabled ("Stream" is 0), the output file/handle must be
388            seekable.
389
390            When outputting to '-' (STDOUT) the "Stream" option is
391            automatically enabled.
392
393            The default is 0.
394
395       "Zip64 => 0|1"
396            ZIP64 is an extension to the Zip archive structure that allows
397
398            •    Zip archives larger than 4Gig.
399
400            •    Zip archives with more that 64K members.
401
402            The module will automatically enable ZIP64 mode as needed when
403            creating zip archive.
404
405            You can force creation of a Zip64 zip archive by enabling this
406            option.
407
408            If you intend to manipulate the Zip64 zip archives created with
409            this module using an external zip/unzip program/library, make sure
410            that it supports Zip64.
411
412            The default is 0.
413
414   Other Options
415       "AutoFlush => 0|1"
416            When true this option enabled flushing of the underlying
417            filehandle after each write/print operation.
418
419            If SimpleZip is writing to a buffer, this option is ignored.
420
421       "Comment => $comment"
422            This option allows the creation of a comment that is associated
423            with the member added to the zip archive with the "add" and
424            "addString" methods.
425
426            This option is not valid in the constructor.
427
428            By default, no comment field is written to the zip archive.
429
430       "Encode => "encoding""
431            The "Encode" option allows you to set the character encoding of
432            the data before it is compressed and written to the zip file. The
433            option is only valid with the "add" or "addString" methods. It
434            will be ignored if you use it with the "add" option.
435
436            Under the hood this option relies on the "Encode" module to carry
437            do the hard work. In particular it uses the
438            "Encode::find_encoding" to check that the encoding you have
439            request exists.
440
441                use Archive::Zip::SimpleZip qw($SimpleZipError) ;
442
443                my $z = new Archive::Zip::SimpleZip "my.zip"
444                    or die "$SimpleZipError\n" ;
445
446                $z->addString("payload data", Encode => "utf8") ;
447
448       "Method => $method"
449            Controls which compression method is used. At present the
450            compression methods supported are: Store (no compression at all),
451            Deflate, Bzip2, Zstd, Xz and Lzma.
452
453            The symbols, ZIP_CM_STORE, ZIP_CM_DEFLATE, ZIP_CM_BZIP2,
454            ZIP_CM_ZSTD, ZIP_CM_XZ and ZIP_CM_LZMA are used to select the
455            compression method.
456
457            These constants are not imported by default by this module.
458
459                use Archive::Zip::SimpleZip qw(:zip_method);
460                use Archive::Zip::SimpleZip qw(:constants);
461                use Archive::Zip::SimpleZip qw(:all);
462
463            Note that to create Bzip2 content, the module
464            "IO::Compress::Bzip2" must be installed. A fatal error will be
465            thrown if you attempt to create Bzip2 content when
466            "IO::Compress::Bzip2" is not available.
467
468            Note that to create Lzma content, the module "IO::Compress::Lzma"
469            must be installed. A fatal error will be thrown if you attempt to
470            create Lzma content when "IO::Compress::Lzma" is not available.
471
472            Note that to create Xz content, the module "IO::Compress::Xz" must
473            be installed. A fatal error will be thrown if you attempt to
474            create Xz content when "IO::Compress::Xz" is not available.
475
476            Note that to create Zstd content, the module "IO::Compress::Zstd"
477            must be installed. A fatal error will be thrown if you attempt to
478            create Zstd content when "IO::Compress::Zstd" is not available.
479
480            The default method is ZIP_CM_DEFLATE for files and ZIP_CM_STORE
481            for directories and symbolic links.
482
483       "StoreLink => 1|0"
484            Controls what "Archive::Zip::SimpleZip" does with a symbolic link
485            (assuming your operating system supports .
486
487            When true, it stores the link itself.  When false, it stores the
488            contents of the file the link refers to.
489
490            If your platform does not support symbolic links this option is
491            ignored.
492
493            Default is 0.
494
495       "TextFlag => 0|1"
496            This parameter controls the setting of a flag in the zip central
497            header. It is used to signal that the data stored in the zip
498            archive is probably text.
499
500            The default is 0.
501
502       "ZipComment => $comment"
503            This option allows the creation of a comment field for the entire
504            zip archive.
505
506            This option is only valid in the constructor.
507
508            By default, no comment field is written to the zip archive.
509
510   Deflate Compression Options
511       These option are only valid if the "Method" is ZIP_CM_DEFLATE. They are
512       ignored otherwise.
513
514       "Level => value"
515            Defines the compression level used by zlib. The value should
516            either be a number between 0 and 9 (0 means no compression and 9
517            is maximum compression), or one of the symbolic constants defined
518            below.
519
520               Z_NO_COMPRESSION
521               Z_BEST_SPEED
522               Z_BEST_COMPRESSION
523               Z_DEFAULT_COMPRESSION
524
525            The default is Z_DEFAULT_COMPRESSION.
526
527       "Strategy => value"
528            Defines the strategy used to tune the compression. Use one of the
529            symbolic constants defined below.
530
531               Z_FILTERED
532               Z_HUFFMAN_ONLY
533               Z_RLE
534               Z_FIXED
535               Z_DEFAULT_STRATEGY
536
537            The default is Z_DEFAULT_STRATEGY.
538
539   Bzip2 Compression Options
540       These option are only valid if the "Method" is ZIP_CM_BZIP2. They are
541       ignored otherwise.
542
543       "BlockSize100K => number"
544            Specify the number of 100K blocks bzip2 uses during compression.
545
546            Valid values are from 1 to 9, where 9 is best compression.
547
548            The default is 1.
549
550       "WorkFactor => number"
551            Specifies how much effort bzip2 should take before resorting to a
552            slower fallback compression algorithm.
553
554            Valid values range from 0 to 250, where 0 means use the default
555            value 30.
556
557            The default is 0.
558
559   Lzma & XZ Compression Options
560       These option are only valid if the "Method" is ZIP_CM_LZMA or
561       ZIP_CM_LZMA. They are ignored otherwise.
562
563       "Preset => number"
564            Used to choose the LZMA compression preset.
565
566            Valid values are 0-9 and "LZMA_PRESET_DEFAULT".
567
568            0 is the fastest compression with the lowest memory usage and the
569            lowest compression.
570
571            9 is the slowest compession with the highest memory usage but with
572            the best compression.
573
574            Defaults to "LZMA_PRESET_DEFAULT" (6).
575
576       "Extreme => 0|1"
577            Makes LZMA compression a lot slower, but a small compression gain.
578
579            Defaults to 0.
580
581   Zstd Compression Options
582       These option are only valid if the "Method" is ZIP_CM_ZSTD. They are
583       ignored otherwise.
584
585       "Level =>"
586            Defines the compression level used.
587
588            Default value is 3.
589

Summary of Default Behaviour

591       By default "Archive::Zip::SimpleZip" will  do the following
592
593       •    Use Deflate Compression for all standard files.
594
595       •    Create a non-streamed Zip archive.
596
597       •    Follow Symbolic Links
598
599       •    Canonicalise the filename before adding it to the zip archive
600
601       •    Only use create a ZIP64 Zip archive if any of the input files is
602            greater than 4 Gig or there are more than 64K members in the zip
603            archive.
604
605       •    Fill out the following zip extended attributes
606
607                "UT" Extended Timestamp
608                "ux" ExtraExtra Type 3 (if running Unix)
609
610       You can change the behaviour of most of the features mentioned above.
611

Examples

613   A Simple example
614       Add all the "C" files in the current directory to the zip archive
615       "my.zip".
616
617           use Archive::Zip::SimpleZip qw($SimpleZipError) ;
618
619           my $z = new Archive::Zip::SimpleZip "my.zip"
620               or die "$SimpleZipError\n" ;
621
622           for ( <*.c> )
623           {
624               $z->add($_)
625                   or die "Cannot add '$_' to zip file: $SimpleZipError\n" ;
626           }
627
628           $z->close();
629
630   Creating an in-memory Zip archive
631       All you need to do if you want the zip archive to be created in-memory
632       is to pass a string reference to the constructor.  The example below
633       will store the zip archive in the variable $zipData.
634
635           use Archive::Zip::SimpleZip qw($SimpleZipError) ;
636
637           my $zipData ;
638           my $z = new Archive::Zip::SimpleZip \$zipData
639               or die "$SimpleZipError\n" ;
640
641           $z->add("part1.txt");
642           $z->close();
643
644       Below is a slight refinement of the in-memory story. As well as writing
645       the zip archive into memory, this example uses c<addString> to create
646       the member "part2.txt" without having to read anything from the
647       filesystem.
648
649           use Archive::Zip::SimpleZip qw($SimpleZipError) ;
650
651           my $zipData ;
652           my $z = new Archive::Zip::SimpleZip \$zipData
653               or die "$SimpleZipError\n" ;
654
655           $z->addString("some text", Name => "part2.txt");
656           $z->close();
657
658   Rename whilst adding
659       The example below shows how the "FilterName" option can be use to
660       remove the path from the filename before it gets written to the zip
661       archive, "my.zip".
662
663           use Archive::Zip::SimpleZip qw($SimpleZipError) ;
664
665           my $z = new Archive::Zip::SimpleZip "my.zip"
666               or die "$SimpleZipError\n" ;
667
668           for ( </some/path/*.c> )
669           {
670               $z->add($_, FilterName => sub { s[^.*/][] }  )
671                   or die "Cannot add '$_' to zip file: $SimpleZipError\n" ;
672           }
673
674           $z->close();
675
676   Adding a directory tree to a Zip archive
677       If you need to add all (or part) of a directory tree into a Zip
678       archive, you can use the standard Perl module "File::Find" in
679       conjunction with this module.
680
681       The code snippet below assumes you want the non-directories files in
682       the directory tree "myDir" added to the zip archive "found.zip".  It
683       also assume you don't want the files added to include any part of the
684       "myDir" relative path.
685
686           use strict;
687           use warnings;
688
689           use Archive::Zip::SimpleZip;
690           use File::Find;
691
692           my $filename = "found.zip";
693           my $dir = "myDir";
694           my $z = new Archive::Zip::SimpleZip $filename
695               or die "Cannot open file $filename\n";
696
697           find( sub { $z->add($_) if ! -d $_ }, $dir);
698
699           $z->close();
700
701       If you do want to include relative paths, pass the $File::Find::name
702       variable with the "Name" option, as shown below.
703
704           find( sub
705                 {
706                     $z->add($_, Name => $File::Find::name)
707                          if ! -d $_
708                 },
709                 $dir);
710
711   Using addFileHandle
712       Say you have a number of old-style ".Z" compressed files that you want
713       to uncompress and put into a zip file. The script below, Z2zip.pl, will
714       do just that
715
716           use strict;
717           use warnings;
718
719           use Archive::Zip::SimpleZip qw($SimpleZipError);
720
721           die "Usage: Z2zip.pl zipfilename file1.Z file2.Z...\n"
722               unless @ARGV >= 2 ;
723
724           my $zipFile = shift ;
725           my $zip = new Archive::Zip::SimpleZip $zipFile
726                       or die "Cannot create zip file '$zipFile': $SimpleZipError";
727
728           for my $Zfile (@ARGV)
729           {
730               my $cleanName = $Zfile ;
731               $cleanName =~ s/\.Z$//;
732
733               print "Adding $cleanName\n" ;
734
735               open my $z, "uncompress -c $Zfile |" ;
736
737               $zip->addFileHandle($z, Name => $cleanName)
738                   or die "Cannot addFileHandle '$cleanName': $SimpleZipError\n" ;
739           }
740
741   Another filehandle example - Working with Net::FTP
742       Say you want to read all the json files from
743       ftp://ftp.perl.org/pub/CPAN/ using Net::FTP and write them directly to
744       a zip archive without having to store them in the filesystem first.
745
746       Here are a couple of ways to do that. The first uses the "openMember"
747       method in conjunction with the "Net::FTP::get" method as shown below.
748
749           use strict;
750           use warnings;
751
752           use Net::FTP;
753           use Archive::Zip::SimpleZip qw($SimpleZipError);
754
755           my $zipFile = "json.zip";
756           my $host = 'ftp.perl.org';
757           my $path = "/pub/CPAN";
758
759           my $zip = new Archive::Zip::SimpleZip $zipFile
760                   or die "Cannot create zip file '$zipFile': $SimpleZipError";
761
762           my $ftp = new Net::FTP($host)
763               or die "Cannot connect to $host: $@";
764
765           $ftp->login("anonymous",'-anonymous@')
766               or die "Cannot login ", $ftp->message;
767
768           $ftp->cwd($path)
769               or die "Cannot change working directory ", $ftp->message;
770
771           my @files = $ftp->ls()
772               or die "Cannot ls", $ftp->message;
773
774           for my $file ( grep { /json$/ } @files)
775           {
776               print " Adding $file\n" ;
777
778               my $zipMember = $zip->openMember(Name => $file)
779                   or die "Cannot openMember file '$file': $SimpleZipError\n" ;
780
781               $ftp->get($file, $zipMember)
782                   or die "Cannot get", $ftp->message;
783           }
784
785       Alternatively, Net::FTP allows a read filehandle to be opened for a
786       file to transferred using the "retr" method.  This filehandle can be
787       dropped into a zip archive using "addFileHandle".  The code below is a
788       rewrite of the for loop in the previous version that shows how this is
789       done.
790
791           for my $file ( grep { /json$/ } @files)
792           {
793               print " Adding $file\n" ;
794
795               my $fh = $ftp->retr($file)
796                   or die "Cannot get", $ftp->message;
797
798               $zip->addFileHandle($fh, Name => $file)
799                   or die "Cannot addFileHandle file '$file': $SimpleZipError\n" ;
800
801               $fh->close()
802                   or die "Cannot close", $ftp->message;
803           }
804
805       One point to be aware of with the "Net::FTP::retr". Not all FTP servers
806       support it. See Net::FTP for details of how to find out what features
807       an FTP server implements.
808
809   Creating a Zip file from STDIN
810       The script below, zipstdin. shows how to create a zip file using data
811       read from STDIN.
812
813           use strict;
814           use warnings;
815
816           use Archive::Zip::SimpleZip qw($SimpleZipError);
817
818           my $zipFile = "stdin.zip";
819
820           my $zip = new Archive::Zip::SimpleZip $zipFile
821                   or die "Cannot create zip file '$zipFile': $SimpleZipError";
822           $zip->adFilehandle(STDIN, Name => "data.txt") ;
823
824       or this, to do the whole thing from the commandline
825
826           echo abc | perl -MArchive::Zip::SimpleZip -e 'Archive::Zip::SimpleZip->new("stdin.zip")->addFileHandle(STDIN, Name => "data.txt")'
827

Importing

829       A number of symbolic constants are required by some methods in
830       "Archive::Zip::SimpleZip". None are imported by default.
831
832       :all Imports "zip", $SimpleZipError and all symbolic constants that can
833            be used by "IArchive::Zip::SimpleZip". Same as doing this
834
835                use Archive::Zip::SimpleZip qw(zip $SimpleZipError :constants) ;
836
837       :constants
838            Import all symbolic constants. Same as doing this
839
840                use Archive::Zip::SimpleZip qw(:flush :level :strategy :zip_method) ;
841
842       :flush
843            These symbolic constants are used by the "flush" method.
844
845                Z_NO_FLUSH
846                Z_PARTIAL_FLUSH
847                Z_SYNC_FLUSH
848                Z_FULL_FLUSH
849                Z_FINISH
850                Z_BLOCK
851
852       :level
853            These symbolic constants are used by the "Level" option in the
854            constructor.
855
856                Z_NO_COMPRESSION
857                Z_BEST_SPEED
858                Z_BEST_COMPRESSION
859                Z_DEFAULT_COMPRESSION
860
861       :strategy
862            These symbolic constants are used by the "Strategy" option in the
863            constructor.
864
865                Z_FILTERED
866                Z_HUFFMAN_ONLY
867                Z_RLE
868                Z_FIXED
869                Z_DEFAULT_STRATEGY
870
871       :zip_method
872            These symbolic constants are used by the "Method" option in the
873            constructor.
874
875                ZIP_CM_STORE
876                ZIP_CM_DEFLATE
877                ZIP_CM_BZIP2
878

FAQ

880   Can SimpleZip update an existing Zip file?
881       No. You can only create a zip file from scratch.
882
883   Can I write a Zip Archive to STDOUT?
884       Yes. Writing zip files to filehandles that are not seekable (so that
885       includes both STDOUT and sockets) is supported by this module. You just
886       have to set the "Stream" option when you call the constructor.
887
888           use Archive::Zip::SimpleZip qw($SimpleZipError) ;
889
890           my $zipData ;
891           my $z = new Archive::Zip::SimpleZip '-',
892                               Stream => 1
893               or die "$SimpleZipError\n" ;
894
895           $z->add("file1.txt");
896           $z->close();
897
898       See "What is a Streamed Zip file?" for a discussion on the "Stream"
899       option.
900
901   Can I write a Zip Archive directly to a socket?
902       See previous question.
903
904   What is a Streamed Zip file?
905       Streaming mode allows you to write a zip file in situation where you
906       cannot seek backwards/forwards. The classic examples are when you are
907       working with sockets or need to write the zip file to STDOUT.
908
909       By default "Archive::Zip::SimpleZip" does not use streaming mode when
910       writing to a zip file (you need to set the "Stream" option to 1 to
911       enable it).
912
913       If you plan to create a streamed Zip file be aware that it will be
914       slightly larger than the non-streamed equivalent. If the files you
915       archive are 32-bit the overhead will be an extra 16 bytes per file
916       written to the zip archive. For 64-bit it is 24 bytes per file.
917

SUPPORT

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

SEE ALSO

924       Archive::Zip::SimpleUnzip, IO::Compress::Zip, Archive::Zip,
925       IO::Uncompress::UnZip
926

AUTHOR

928       This module was written by Paul Marquess, pmqs@cpan.org.
929

MODIFICATION HISTORY

931       See the Changes file.
932
934       Copyright (c) 2012-2021 Paul Marquess. All rights reserved.
935
936       This program is free software; you can redistribute it and/or modify it
937       under the same terms as Perl itself.
938
939
940
941perl v5.34.0                      2021-11-18        Archive::Zip::SimpleZip(3)
Impressum