IO::Compress::Zip(3pm)

1IO::Compress::Zip(3)  User Contributed Perl Documentation IO::Compress::Zip(3)
2
3
4

NAME

6       IO::Compress::Zip - Write zip files/buffers
7

SYNOPSIS

9           use IO::Compress::Zip qw(zip $ZipError) ;
10
11           my $status = zip $input => $output [,OPTS]
12               or die "zip failed: $ZipError\n";
13
14           my $z = new IO::Compress::Zip $output [,OPTS]
15               or die "zip failed: $ZipError\n";
16
17           $z->print($string);
18           $z->printf($format, $string);
19           $z->write($string);
20           $z->syswrite($string [, $length, $offset]);
21           $z->flush();
22           $z->tell();
23           $z->eof();
24           $z->seek($position, $whence);
25           $z->binmode();
26           $z->fileno();
27           $z->opened();
28           $z->autoflush();
29           $z->input_line_number();
30           $z->newStream( [OPTS] );
31
32           $z->deflateParams();
33
34           $z->close() ;
35
36           $ZipError ;
37
38           # IO::File mode
39
40           print $z $string;
41           printf $z $format, $string;
42           tell $z
43           eof $z
44           seek $z, $position, $whence
45           binmode $z
46           fileno $z
47           close $z ;
48

DESCRIPTION

50       This module provides a Perl interface that allows writing zip com‐
51       pressed data to files or buffer.
52
53       The primary purpose of this module is to provide streaming write access
54       to zip files and buffers. It is not a general-purpose file archiver. If
55       that is what you want, check out "Archive::Zip".
56
57       At present three compression methods are supported by IO::Com‐
58       press::Zip, namely Store (no compression at all), Deflate and Bzip2.
59
60       Note that to create Bzip2 content, the module "IO::Compress::Bzip2"
61       must be installed.
62
63       For reading zip files/buffers, see the companion module IO::Uncom‐
64       press::Unzip.
65

Functional Interface

67       A top-level function, "zip", is provided to carry out "one-shot" com‐
68       pression between buffers and/or files. For finer control over the com‐
69       pression process, see the "OO Interface" section.
70
71           use IO::Compress::Zip qw(zip $ZipError) ;
72
73           zip $input => $output [,OPTS]
74               or die "zip failed: $ZipError\n";
75
76       The functional interface needs Perl5.005 or better.
77
78       zip $input => $output [, OPTS]
79
80       "zip" expects at least two parameters, $input and $output.
81
82       The $input parameter
83
84       The parameter, $input, is used to define the source of the uncompressed
85       data.
86
87       It can take one of the following forms:
88
89       A filename
90            If the $input parameter is a simple scalar, it is assumed to be a
91            filename. This file will be opened for reading and the input data
92            will be read from it.
93
94       A filehandle
95            If the $input parameter is a filehandle, the input data will be
96            read from it.  The string '-' can be used as an alias for standard
97            input.
98
99       A scalar reference
100            If $input is a scalar reference, the input data will be read from
101            $$input.
102
103       An array reference
104            If $input is an array reference, each element in the array must be
105            a filename.
106
107            The input data will be read from each file in turn.
108
109            The complete array will be walked to ensure that it only contains
110            valid filenames before any data is compressed.
111
112       An Input FileGlob string
113            If $input is a string that is delimited by the characters "<" and
114            ">" "zip" will assume that it is an input fileglob string. The
115            input is the list of files that match the fileglob.
116
117            If the fileglob does not match any files ...
118
119            See File::GlobMapper for more details.
120
121       If the $input parameter is any other type, "undef" will be returned.
122
123       In addition, if $input is a simple filename, the default values for the
124       "Name", "Time", "ExtAttr" and "exTime" options will be sourced from
125       that file.
126
127       If you do not want to use these defaults they can be overridden by
128       explicitly setting the "Name", "Time", "ExtAttr" and "exTime" options
129       or by setting the "Minimal" parameter.
130
131       The $output parameter
132
133       The parameter $output is used to control the destination of the com‐
134       pressed data. This parameter can take one of these forms.
135
136       A filename
137            If the $output parameter is a simple scalar, it is assumed to be a
138            filename.  This file will be opened for writing and the compressed
139            data will be written to it.
140
141       A filehandle
142            If the $output parameter is a filehandle, the compressed data will
143            be written to it.  The string '-' can be used as an alias for
144            standard output.
145
146       A scalar reference
147            If $output is a scalar reference, the compressed data will be
148            stored in $$output.
149
150       An Array Reference
151            If $output is an array reference, the compressed data will be
152            pushed onto the array.
153
154       An Output FileGlob
155            If $output is a string that is delimited by the characters "<" and
156            ">" "zip" will assume that it is an output fileglob string. The
157            output is the list of files that match the fileglob.
158
159            When $output is an fileglob string, $input must also be a fileglob
160            string. Anything else is an error.
161
162       If the $output parameter is any other type, "undef" will be returned.
163
164       Notes
165
166       When $input maps to multiple files/buffers and $output is a single
167       file/buffer the input files/buffers will each be stored in $output as a
168       distinct entry.
169
170       Optional Parameters
171
172       Unless specified below, the optional parameters for "zip", "OPTS", are
173       the same as those used with the OO interface defined in the "Construc‐
174       tor Options" section below.
175
176       "AutoClose => 0⎪1"
177            This option applies to any input or output data streams to "zip"
178            that are filehandles.
179
180            If "AutoClose" is specified, and the value is true, it will result
181            in all input and/or output filehandles being closed once "zip" has
182            completed.
183
184            This parameter defaults to 0.
185
186       "BinModeIn => 0⎪1"
187            When reading from a file or filehandle, set "binmode" before read‐
188            ing.
189
190            Defaults to 0.
191
192       "Append => 0⎪1"
193            TODO
194
195       Examples
196
197       To read the contents of the file "file1.txt" and write the compressed
198       data to the file "file1.txt.zip".
199
200           use strict ;
201           use warnings ;
202           use IO::Compress::Zip qw(zip $ZipError) ;
203
204           my $input = "file1.txt";
205           zip $input => "$input.zip"
206               or die "zip failed: $ZipError\n";
207
208       To read from an existing Perl filehandle, $input, and write the com‐
209       pressed data to a buffer, $buffer.
210
211           use strict ;
212           use warnings ;
213           use IO::Compress::Zip qw(zip $ZipError) ;
214           use IO::File ;
215
216           my $input = new IO::File "<file1.txt"
217               or die "Cannot open 'file1.txt': $!\n" ;
218           my $buffer ;
219           zip $input => \$buffer
220               or die "zip failed: $ZipError\n";
221
222       To compress all files in the directory "/my/home" that match "*.txt"
223       and store the compressed data in the same directory
224
225           use strict ;
226           use warnings ;
227           use IO::Compress::Zip qw(zip $ZipError) ;
228
229           zip '</my/home/*.txt>' => '<*.zip>'
230               or die "zip failed: $ZipError\n";
231
232       and if you want to compress each file one at a time, this will do the
233       trick
234
235           use strict ;
236           use warnings ;
237           use IO::Compress::Zip qw(zip $ZipError) ;
238
239           for my $input ( glob "/my/home/*.txt" )
240           {
241               my $output = "$input.zip" ;
242               zip $input => $output
243                   or die "Error compressing '$input': $ZipError\n";
244           }
245

OO Interface

247       Constructor
248
249       The format of the constructor for "IO::Compress::Zip" is shown below
250
251           my $z = new IO::Compress::Zip $output [,OPTS]
252               or die "IO::Compress::Zip failed: $ZipError\n";
253
254       It returns an "IO::Compress::Zip" object on success and undef on fail‐
255       ure.  The variable $ZipError will contain an error message on failure.
256
257       If you are running Perl 5.005 or better the object, $z, returned from
258       IO::Compress::Zip can be used exactly like an IO::File filehandle.
259       This means that all normal output file operations can be carried out
260       with $z.  For example, to write to a compressed file/buffer you can use
261       either of these forms
262
263           $z->print("hello world\n");
264           print $z "hello world\n";
265
266       The mandatory parameter $output is used to control the destination of
267       the compressed data. This parameter can take one of these forms.
268
269       A filename
270            If the $output parameter is a simple scalar, it is assumed to be a
271            filename. This file will be opened for writing and the compressed
272            data will be written to it.
273
274       A filehandle
275            If the $output parameter is a filehandle, the compressed data will
276            be written to it.  The string '-' can be used as an alias for
277            standard output.
278
279       A scalar reference
280            If $output is a scalar reference, the compressed data will be
281            stored in $$output.
282
283       If the $output parameter is any other type, "IO::Compress::Zip"::new
284       will return undef.
285
286       Constructor Options
287
288       "OPTS" is any combination of the following options:
289
290       "AutoClose => 0⎪1"
291            This option is only valid when the $output parameter is a filehan‐
292            dle. If specified, and the value is true, it will result in the
293            $output being closed once either the "close" method is called or
294            the "IO::Compress::Zip" object is destroyed.
295
296            This parameter defaults to 0.
297
298       "Append => 0⎪1"
299            Opens $output in append mode.
300
301            The behaviour of this option is dependent on the type of $output.
302
303            * A Buffer
304                 If $output is a buffer and "Append" is enabled, all com‐
305                 pressed data will be append to the end if $output. Otherwise
306                 $output will be cleared before any data is written to it.
307
308            * A Filename
309                 If $output is a filename and "Append" is enabled, the file
310                 will be opened in append mode. Otherwise the contents of the
311                 file, if any, will be truncated before any compressed data is
312                 written to it.
313
314            * A Filehandle
315                 If $output is a filehandle, the file pointer will be posi‐
316                 tioned to the end of the file via a call to "seek" before any
317                 compressed data is written to it.  Otherwise the file pointer
318                 will not be moved.
319
320            This parameter defaults to 0.
321
322       "Name => $string"
323            Stores the contents of $string in the zip filename header field.
324            If "Name" is not specified, no zip filename field will be created.
325
326       "Time => $number"
327            Sets the last modified time field in the zip header to $number.
328
329            This field defaults to the time the "IO::Compress::Zip" object was
330            created if this option is not specified.
331
332       "ExtAttr => $attr"
333            This option controls the "external file attributes" field in the
334            central header of the zip file. This is a 4 byte field.
335
336            This option defaults to 0.
337
338       "exTime => [$atime, $mtime, $ctime]"
339            This option expects an array reference with exactly three ele‐
340            ments: $atime, "mtime" and $ctime. These correspond to the last
341            access time, last modification time and creation time respec‐
342            tively.
343
344            It uses these values to set the extended timestamp field in the
345            local zip header to the three values, $atime, $mtime, $ctime and
346            sets the extended timestamp field in the central zip header to
347            $mtime.
348
349            If any of the three values is "undef" that time value will not be
350            used.  So, for example, to set only the $mtime you would use this
351
352                exTime => [undef, $mtime, undef]
353
354            If the "Minimal" option is set to true, this option will be
355            ignored.
356
357            By default no extended time field is created.
358
359       "Comment => $comment"
360            Stores the contents of $comment in the Central File Header of the
361            zip file.
362
363            By default, no comment field is written to the zip file.
364
365       "ZipComment => $comment"
366            Stores the contents of $comment in the End of Central Directory
367            record of the zip file.
368
369            By default, no comment field is written to the zip file.
370
371       "Method => $method"
372            Controls which compression method is used. At present three com‐
373            pression methods are supported, namely Store (no compression at
374            all), Deflate and Bzip2.
375
376            The symbols, ZIP_CM_STORE, ZIP_CM_DEFLATE and ZIP_CM_BZIP2 are
377            used to select the compression method.
378
379            These constants are not imported by "IO::Compress::Zip" by
380            default.
381
382                use IO::Compress::Zip qw(:zip_method);
383                use IO::Compress::Zip qw(:constants);
384                use IO::Compress::Zip qw(:all);
385
386            Note that to create Bzip2 content, the module "IO::Com‐
387            press::Bzip2" must be installed. A fatal error will be thrown if
388            you attempt to create Bzip2 content when "IO::Compress::Bzip2" is
389            not available.
390
391            The default method is ZIP_CM_DEFLATE.
392
393       "Stream => 0⎪1"
394            This option controls whether the zip file/buffer output is created
395            in streaming mode.
396
397            Note that when outputting to a file with streaming mode disabled
398            ("Stream" is 0), the output file must be seekable.
399
400            The default is 1.
401
402       "Zip64 => 0⎪1"
403            Create a Zip64 zip file/buffer. This option should only be used if
404            you want to store files larger than 4 Gig.
405
406            If you intend to manipulate the Zip64 zip files created with this
407            module using an external zip/unzip make sure that it supports
408            streaming Zip64.
409
410            In particular, if you are using Info-Zip you need to have zip ver‐
411            sion 3.x or better to update a Zip64 archive and unzip version 6.x
412            to read a zip64 archive. At the time of writing both are beta sta‐
413            tus.
414
415            When the "Zip64" option is enabled, the "Stream" option must be
416            enabled as well.
417
418            The default is 0.
419
420       "TextFlag => 0⎪1"
421            This parameter controls the setting of a bit in the zip central
422            header. It is used to signal that the data stored in the zip
423            file/buffer is probably text.
424
425            The default is 0.
426
427       "ExtraFieldLocal => $data" =item "ExtraFieldCentral => $data"
428            These options allows additional metadata to be stored in the local
429            and central headers in the zip file/buffer.
430
431            An extra field consists of zero or more subfields. Each subfield
432            consists of a two byte header followed by the subfield data.
433
434            The list of subfields can be supplied in any of the following for‐
435            mats
436
437                ExtraFieldLocal => [$id1, $data1,
438                                    $id2, $data2,
439                                     ...
440                                   ]
441
442                ExtraFieldLocal => [ [$id1 => $data1],
443                                     [$id2 => $data2],
444                                     ...
445                                   ]
446
447                ExtraFieldLocal => { $id1 => $data1,
448                                     $id2 => $data2,
449                                     ...
450                                   }
451
452            Where $id1, $id2 are two byte subfield ID's.
453
454            If you use the hash syntax, you have no control over the order in
455            which the ExtraSubFields are stored, plus you cannot have Sub‐
456            Fields with duplicate ID.
457
458            Alternatively the list of subfields can by supplied as a scalar,
459            thus
460
461                ExtraField => $rawdata
462
463            The Extended Time field, set using the "exTime" option, is an
464            example of an extended field.
465
466            If the "Minimal" option is set to true, this option will be
467            ignored.
468
469            The maximum size of an extra field 65535 bytes.
470
471       "Minimal => 1⎪0"
472            If specified, this option will disable the creation of all
473            extended fields in the zip local and central headers. So the
474            "exTime", "ExtraFieldLocal" and "ExtraFieldCentral" options will
475            be ignored.
476
477            This parameter defaults to 0.
478
479       "BlockSize100K => number"
480            Specify the number of 100K blocks bzip2 uses during compression.
481
482            Valid values are from 1 to 9, where 9 is best compression.
483
484            This option is only valid if the "Method" is ZIP_CM_BZIP2. It is
485            ignored otherwise.
486
487            The default is 1.
488
489       "WorkFactor => number"
490            Specifies how much effort bzip2 should take before resorting to a
491            slower fallback compression algorithm.
492
493            Valid values range from 0 to 250, where 0 means use the default
494            value 30.
495
496            This option is only valid if the "Method" is ZIP_CM_BZIP2. It is
497            ignored otherwise.
498
499            The default is 0.
500
501       -Level
502            Defines the compression level used by zlib. The value should
503            either be a number between 0 and 9 (0 means no compression and 9
504            is maximum compression), or one of the symbolic constants defined
505            below.
506
507               Z_NO_COMPRESSION
508               Z_BEST_SPEED
509               Z_BEST_COMPRESSION
510               Z_DEFAULT_COMPRESSION
511
512            The default is Z_DEFAULT_COMPRESSION.
513
514            Note, these constants are not imported by "IO::Compress::Zip" by
515            default.
516
517                use IO::Compress::Zip qw(:strategy);
518                use IO::Compress::Zip qw(:constants);
519                use IO::Compress::Zip qw(:all);
520
521       -Strategy
522            Defines the strategy used to tune the compression. Use one of the
523            symbolic constants defined below.
524
525               Z_FILTERED
526               Z_HUFFMAN_ONLY
527               Z_RLE
528               Z_FIXED
529               Z_DEFAULT_STRATEGY
530
531            The default is Z_DEFAULT_STRATEGY.
532
533       "Strict => 0⎪1"
534            This is a placeholder option.
535
536       Examples
537
538       TODO
539

Methods

541       print
542
543       Usage is
544
545           $z->print($data)
546           print $z $data
547
548       Compresses and outputs the contents of the $data parameter. This has
549       the same behaviour as the "print" built-in.
550
551       Returns true if successful.
552
553       printf
554
555       Usage is
556
557           $z->printf($format, $data)
558           printf $z $format, $data
559
560       Compresses and outputs the contents of the $data parameter.
561
562       Returns true if successful.
563
564       syswrite
565
566       Usage is
567
568           $z->syswrite $data
569           $z->syswrite $data, $length
570           $z->syswrite $data, $length, $offset
571
572       Compresses and outputs the contents of the $data parameter.
573
574       Returns the number of uncompressed bytes written, or "undef" if unsuc‐
575       cessful.
576
577       write
578
579       Usage is
580
581           $z->write $data
582           $z->write $data, $length
583           $z->write $data, $length, $offset
584
585       Compresses and outputs the contents of the $data parameter.
586
587       Returns the number of uncompressed bytes written, or "undef" if unsuc‐
588       cessful.
589
590       flush
591
592       Usage is
593
594           $z->flush;
595           $z->flush($flush_type);
596
597       Flushes any pending compressed data to the output file/buffer.
598
599       This method takes an optional parameter, $flush_type, that controls how
600       the flushing will be carried out. By default the $flush_type used is
601       "Z_FINISH". Other valid values for $flush_type are "Z_NO_FLUSH",
602       "Z_SYNC_FLUSH", "Z_FULL_FLUSH" and "Z_BLOCK". It is strongly recom‐
603       mended that you only set the "flush_type" parameter if you fully under‐
604       stand the implications of what it does - overuse of "flush" can seri‐
605       ously degrade the level of compression achieved. See the "zlib" docu‐
606       mentation for details.
607
608       Returns true on success.
609
610       tell
611
612       Usage is
613
614           $z->tell()
615           tell $z
616
617       Returns the uncompressed file offset.
618
619       eof
620
621       Usage is
622
623           $z->eof();
624           eof($z);
625
626       Returns true if the "close" method has been called.
627
628       seek
629
630           $z->seek($position, $whence);
631           seek($z, $position, $whence);
632
633       Provides a sub-set of the "seek" functionality, with the restriction
634       that it is only legal to seek forward in the output file/buffer.  It is
635       a fatal error to attempt to seek backward.
636
637       Empty parts of the file/buffer will have NULL (0x00) bytes written to
638       them.
639
640       The $whence parameter takes one the usual values, namely SEEK_SET,
641       SEEK_CUR or SEEK_END.
642
643       Returns 1 on success, 0 on failure.
644
645       binmode
646
647       Usage is
648
649           $z->binmode
650           binmode $z ;
651
652       This is a noop provided for completeness.
653
654       opened
655
656           $z->opened()
657
658       Returns true if the object currently refers to a opened file/buffer.
659
660       autoflush
661
662           my $prev = $z->autoflush()
663           my $prev = $z->autoflush(EXPR)
664
665       If the $z object is associated with a file or a filehandle, this method
666       returns the current autoflush setting for the underlying filehandle. If
667       "EXPR" is present, and is non-zero, it will enable flushing after every
668       write/print operation.
669
670       If $z is associated with a buffer, this method has no effect and always
671       returns "undef".
672
673       Note that the special variable $⎪ cannot be used to set or retrieve the
674       autoflush setting.
675
676       input_line_number
677
678           $z->input_line_number()
679           $z->input_line_number(EXPR)
680
681       This method always returns "undef" when compressing.
682
683       fileno
684
685           $z->fileno()
686           fileno($z)
687
688       If the $z object is associated with a file or a filehandle, this method
689       will return the underlying file descriptor.
690
691       If the $z object is is associated with a buffer, this method will
692       return undef.
693
694       close
695
696           $z->close() ;
697           close $z ;
698
699       Flushes any pending compressed data and then closes the output
700       file/buffer.
701
702       For most versions of Perl this method will be automatically invoked if
703       the IO::Compress::Zip object is destroyed (either explicitly or by the
704       variable with the reference to the object going out of scope). The
705       exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In these
706       cases, the "close" method will be called automatically, but not until
707       global destruction of all live objects when the program is terminating.
708
709       Therefore, if you want your scripts to be able to run on all versions
710       of Perl, you should call "close" explicitly and not rely on automatic
711       closing.
712
713       Returns true on success, otherwise 0.
714
715       If the "AutoClose" option has been enabled when the IO::Compress::Zip
716       object was created, and the object is associated with a file, the
717       underlying file will also be closed.
718
719       newStream([OPTS])
720
721       Usage is
722
723           $z->newStream( [OPTS] )
724
725       Closes the current compressed data stream and starts a new one.
726
727       OPTS consists of any of the the options that are available when creat‐
728       ing the $z object.
729
730       See the "Constructor Options" section for more details.
731
732       deflateParams
733
734       Usage is
735
736           $z->deflateParams
737
738       TODO
739

Importing

741       A number of symbolic constants are required by some methods in
742       "IO::Compress::Zip". None are imported by default.
743
744       :all Imports "zip", $ZipError and all symbolic constants that can be
745            used by "IO::Compress::Zip". Same as doing this
746
747                use IO::Compress::Zip qw(zip $ZipError :constants) ;
748
749       :constants
750            Import all symbolic constants. Same as doing this
751
752                use IO::Compress::Zip qw(:flush :level :strategy :zip_method) ;
753
754       :flush
755            These symbolic constants are used by the "flush" method.
756
757                Z_NO_FLUSH
758                Z_PARTIAL_FLUSH
759                Z_SYNC_FLUSH
760                Z_FULL_FLUSH
761                Z_FINISH
762                Z_BLOCK
763
764       :level
765            These symbolic constants are used by the "Level" option in the
766            constructor.
767
768                Z_NO_COMPRESSION
769                Z_BEST_SPEED
770                Z_BEST_COMPRESSION
771                Z_DEFAULT_COMPRESSION
772
773       :strategy
774            These symbolic constants are used by the "Strategy" option in the
775            constructor.
776
777                Z_FILTERED
778                Z_HUFFMAN_ONLY
779                Z_RLE
780                Z_FIXED
781                Z_DEFAULT_STRATEGY
782
783       :zip_method
784            These symbolic constants are used by the "Method" option in the
785            constructor.
786
787                ZIP_CM_STORE
788                ZIP_CM_DEFLATE
789                ZIP_CM_BZIP2
790
791       For
792

EXAMPLES

794       TODO
795

AUTHOR

821       This module was written by Paul Marquess, pmqs@cpan.org.
822

MODIFICATION HISTORY

824       See the Changes file.
825

COPYRIGHT AND LICENSE

827       Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
828
829       This program is free software; you can redistribute it and/or modify it
830       under the same terms as Perl itself.
831
832
833
834perl v5.8.8                       2007-06-18              IO::Compress::Zip(3)