This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
IO::Compress::*
[perl5.git] / ext / Compress / IO / Zlib / lib / IO / Compress / Zip.pm
1 package IO::Compress::Zip ;
2
3 use strict ;
4 use warnings;
5 use bytes;
6
7 use IO::Compress::Base::Common qw(:Status createSelfTiedObject);
8 use IO::Compress::RawDeflate;
9 use IO::Compress::Adapter::Deflate;
10 use IO::Compress::Adapter::Identity;
11
12 use Compress::Raw::Zlib qw(crc32) ;
13 BEGIN
14 {
15     eval { require IO::Compress::Adapter::Bzip2; 
16            import IO::Compress::Adapter::Bzip2; 
17            require IO::Compress::Bzip2; 
18            import IO::Compress::Bzip2; 
19          } ;
20 }
21
22
23 require Exporter ;
24
25 our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $ZipError);
26
27 $VERSION = '2.000_11';
28 $ZipError = '';
29
30 @ISA = qw(Exporter IO::Compress::RawDeflate);
31 @EXPORT_OK = qw( $ZipError zip ) ;
32 %EXPORT_TAGS = %IO::Compress::RawDeflate::DEFLATE_CONSTANTS ;
33 push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
34
35 $EXPORT_TAGS{zip_method} = [qw( ZIP_CM_STORE ZIP_CM_DEFLATE ZIP_CM_BZIP2 )];
36 push @{ $EXPORT_TAGS{all} }, @{ $EXPORT_TAGS{zip_method} };
37
38 Exporter::export_ok_tags('all');
39
40 use constant ZIP_CM_STORE                      => 0 ;
41 use constant ZIP_CM_DEFLATE                    => 8 ;
42 use constant ZIP_CM_BZIP2                      => 12 ;
43
44 use constant ZIP_LOCAL_HDR_SIG                 => 0x04034b50;
45 use constant ZIP_DATA_HDR_SIG                  => 0x08074b50;
46 use constant ZIP_CENTRAL_HDR_SIG               => 0x02014b50;
47 use constant ZIP_END_CENTRAL_HDR_SIG           => 0x06054b50;
48
49
50 our (%ZIP_CM_MIN_VERSIONS);
51 %ZIP_CM_MIN_VERSIONS = (
52             ZIP_CM_STORE()                      => 20,
53             ZIP_CM_DEFLATE()                    => 20,
54             ZIP_CM_BZIP2()                      => 46,
55             );
56
57 sub new
58 {
59     my $class = shift ;
60
61     my $obj = createSelfTiedObject($class, \$ZipError);    
62     $obj->_create(undef, @_);
63 }
64
65 sub zip
66 {
67     my $obj = createSelfTiedObject(undef, \$ZipError);    
68     return $obj->_def(@_);
69 }
70
71 sub mkComp
72 {
73     my $self = shift ;
74     my $class = shift ;
75     my $got = shift ;
76
77     my ($obj, $errstr, $errno) ;
78
79     if (*$self->{ZipData}{Method} == ZIP_CM_STORE) {
80         ($obj, $errstr, $errno) = IO::Compress::Adapter::Identity::mkCompObject(
81                                                  $got->value('Level'),
82                                                  $got->value('Strategy')
83                                                  );
84     }
85     elsif (*$self->{ZipData}{Method} == ZIP_CM_DEFLATE) {
86         ($obj, $errstr, $errno) = IO::Compress::Adapter::Deflate::mkCompObject(
87                                                  $got->value('CRC32'),
88                                                  $got->value('Adler32'),
89                                                  $got->value('Level'),
90                                                  $got->value('Strategy')
91                                                  );
92     }
93     elsif (*$self->{ZipData}{Method} == ZIP_CM_BZIP2) {
94         ($obj, $errstr, $errno) = IO::Compress::Adapter::Bzip2::mkCompObject(
95                                                 $got->value('BlockSize100K'),
96                                                 $got->value('WorkFactor'),
97                                                 $got->value('Verbosity')
98                                                );
99         *$self->{ZipData}{CRC32} = crc32(undef);
100     }
101
102     return $self->saveErrorString(undef, $errstr, $errno)
103        if ! defined $obj;
104
105     if (! defined *$self->{ZipData}{StartOffset}) {
106         *$self->{ZipData}{StartOffset} = *$self->{ZipData}{Offset} = 0;
107     }
108
109     return $obj;    
110 }
111
112 sub reset
113 {
114     my $self = shift ;
115
116     *$self->{Compress}->reset();
117     *$self->{ZipData}{CRC32} = Compress::Raw::Zlib::crc32('');
118
119     return STATUS_OK;    
120 }
121
122 sub filterUncompressed
123 {
124     my $self = shift ;
125
126     if (*$self->{ZipData}{Method} == ZIP_CM_DEFLATE) {
127         *$self->{ZipData}{CRC32} = *$self->{Compress}->crc32();
128     }
129     else {
130         *$self->{ZipData}{CRC32} = crc32(${$_[0]}, *$self->{ZipData}{CRC32});
131
132     }
133 }
134
135 sub mkHeader
136 {
137     my $self  = shift;
138     my $param = shift ;
139     
140     my $filename = '';
141     $filename = $param->value('Name') || '';
142
143     my $comment = '';
144     $comment = $param->value('Comment') || '';
145
146     my $hdr = '';
147
148     my $time = _unixToDosTime($param->value('Time'));
149     *$self->{ZipData}{StartOffset} = *$self->{ZipData}{Offset} ;
150
151     my $strm = *$self->{ZipData}{Stream} ? 8 : 0 ;
152     # bzip2 is 12, deflate is 8
153     my $method = *$self->{ZipData}{Method} ;
154
155     # deflate is 20
156     # bzip2 is 46
157     my $extract = $param->value('OS_Code') << 8 +
158                     $ZIP_CM_MIN_VERSIONS{$method};
159
160     $hdr .= pack "V", ZIP_LOCAL_HDR_SIG ; # signature
161     $hdr .= pack 'v', $extract   ; # extract Version & OS
162     $hdr .= pack 'v', $strm      ; # general purpose flag (set streaming mode)
163     $hdr .= pack 'v', $method    ; # compression method (deflate)
164     $hdr .= pack 'V', $time      ; # last mod date/time
165     $hdr .= pack 'V', 0          ; # crc32               - 0 when streaming
166     $hdr .= pack 'V', 0          ; # compressed length   - 0 when streaming
167     $hdr .= pack 'V', 0          ; # uncompressed length - 0 when streaming
168     $hdr .= pack 'v', length $filename ; # filename length
169     $hdr .= pack 'v', 0          ; # extra length
170     
171     $hdr .= $filename ;
172
173
174     my $ctl = '';
175
176     $ctl .= pack "V", ZIP_CENTRAL_HDR_SIG ; # signature
177     $ctl .= pack 'v', $extract   ; # version made by
178     $ctl .= pack 'v', $extract   ; # extract Version
179     $ctl .= pack 'v', $strm      ; # general purpose flag (streaming mode)
180     $ctl .= pack 'v', $method    ; # compression method (deflate)
181     $ctl .= pack 'V', $time      ; # last mod date/time
182     $ctl .= pack 'V', 0          ; # crc32
183     $ctl .= pack 'V', 0          ; # compressed length
184     $ctl .= pack 'V', 0          ; # uncompressed length
185     $ctl .= pack 'v', length $filename ; # filename length
186     $ctl .= pack 'v', 0          ; # extra length
187     $ctl .= pack 'v', length $comment ;  # file comment length
188     $ctl .= pack 'v', 0          ; # disk number start 
189     $ctl .= pack 'v', 0          ; # internal file attributes
190     $ctl .= pack 'V', 0          ; # external file attributes
191     $ctl .= pack 'V', *$self->{ZipData}{Offset}  ; # offset to local header
192     
193     $ctl .= $filename ;
194     #$ctl .= $extra ;
195     $ctl .= $comment ;
196
197     *$self->{ZipData}{Offset} += length $hdr ;
198
199     *$self->{ZipData}{CentralHeader} = $ctl;
200
201     return $hdr;
202 }
203
204 sub mkTrailer
205 {
206     my $self = shift ;
207
208     my $crc32 ;
209     if (*$self->{ZipData}{Method} == ZIP_CM_DEFLATE) {
210         $crc32 = *$self->{Compress}->crc32();
211     }
212     else {
213         $crc32 = *$self->{ZipData}{CRC32};
214     }
215
216     my $compressedBytes   = *$self->{Compress}->compressedBytes();
217     my $uncompressedBytes = *$self->{Compress}->uncompressedBytes();
218
219     my $data ;
220     $data .= pack "V", $crc32 ;                           # CRC32
221     $data .= pack "V", $compressedBytes   ;               # Compressed Size
222     $data .= pack "V", $uncompressedBytes;                # Uncompressed Size
223
224     my $hdr = '';
225
226     if (*$self->{ZipData}{Stream}) {
227         $hdr  = pack "V", ZIP_DATA_HDR_SIG ;                       # signature
228         $hdr .= $data ;
229     }
230     else {
231         $self->writeAt(*$self->{ZipData}{StartOffset} + 14, $data)
232             or return undef;
233     }
234
235     my $ctl = *$self->{ZipData}{CentralHeader} ;
236     substr($ctl, 16, 12) = $data ;
237     #substr($ctl, 16, 4) = pack "V", $crc32 ;             # CRC32
238     #substr($ctl, 20, 4) = pack "V", $compressedBytes   ; # Compressed Size
239     #substr($ctl, 24, 4) = pack "V", $uncompressedBytes ; # Uncompressed Size
240
241     *$self->{ZipData}{Offset} += length($hdr) + $compressedBytes;
242     push @{ *$self->{ZipData}{CentralDir} }, $ctl ;
243
244     return $hdr;
245 }
246
247 sub mkFinalTrailer
248 {
249     my $self = shift ;
250
251     my $comment = '';
252     $comment = *$self->{ZipData}{ZipComment} ;
253
254     my $entries = @{ *$self->{ZipData}{CentralDir} };
255     my $cd = join '', @{ *$self->{ZipData}{CentralDir} };
256
257     my $ecd = '';
258     $ecd .= pack "V", ZIP_END_CENTRAL_HDR_SIG ; # signature
259     $ecd .= pack 'v', 0          ; # number of disk
260     $ecd .= pack 'v', 0          ; # number if disk with central dir
261     $ecd .= pack 'v', $entries   ; # entries in central dir on this disk
262     $ecd .= pack 'v', $entries   ; # entries in central dir
263     $ecd .= pack 'V', length $cd ; # size of central dir
264     $ecd .= pack 'V', *$self->{ZipData}{Offset} ; # offset to start central dir
265     $ecd .= pack 'v', length $comment ; # zipfile comment length
266     $ecd .= $comment;
267
268     return $cd . $ecd ;
269 }
270
271 sub ckParams
272 {
273     my $self = shift ;
274     my $got = shift;
275     
276     $got->value('CRC32' => 1);
277
278     if (! $got->parsed('Time') ) {
279         # Modification time defaults to now.
280         $got->value('Time' => time) ;
281     }
282
283     *$self->{ZipData}{Stream} = $got->value('Stream');
284     #*$self->{ZipData}{Store} = $got->value('Store');
285
286     my $method = $got->value('Method');
287     #if ($method != 0 && $method != 8 && $method != 12) {
288     return $self->saveErrorString(undef, "Unknown Method '$method'")   
289         if ! defined $ZIP_CM_MIN_VERSIONS{$method};
290
291     return $self->saveErrorString(undef, "Bzip2 not available")
292         if $method == ZIP_CM_BZIP2 and 
293            ! defined $IO::Compress::Adapter::Bzip2::VERSION;
294
295     *$self->{ZipData}{Method} = $method;
296
297     *$self->{ZipData}{ZipComment} = $got->value('ZipComment') ;
298
299     return undef
300         if defined $IO::Compress::Bzip2::VERSION
301             and ! IO::Compress::Bzip2::ckParams($self, $got);
302
303     return 1 ;
304 }
305
306 #sub newHeader
307 #{
308 #    my $self = shift ;
309 #
310 #    return $self->mkHeader(*$self->{Got});
311 #}
312
313 sub getExtraParams
314 {
315     my $self = shift ;
316
317     use IO::Compress::Base::Common qw(:Parse);
318     use Compress::Raw::Zlib qw(Z_DEFLATED Z_DEFAULT_COMPRESSION Z_DEFAULT_STRATEGY);
319
320     my @Bzip2 = ();
321     
322     @Bzip2 = IO::Compress::Bzip2::getExtraParams($self)
323         if defined $IO::Compress::Bzip2::VERSION;
324     
325     return (
326             # zlib behaviour
327             $self->getZlibParams(),
328
329             'Stream'    => [1, 1, Parse_boolean,   1],
330            #'Store'     => [0, 1, Parse_boolean,   0],
331             'Method'    => [0, 1, Parse_unsigned,  ZIP_CM_DEFLATE],
332             
333 #            # Zip header fields
334 #           'Minimal'   => [0, 1, Parse_boolean,   0],
335             'Comment'   => [0, 1, Parse_any,       ''],
336             'ZipComment'=> [0, 1, Parse_any,       ''],
337             'Name'      => [0, 1, Parse_any,       ''],
338             'Time'      => [0, 1, Parse_any,       undef],
339             'OS_Code'   => [0, 1, Parse_unsigned,  $Compress::Raw::Zlib::gzip_os_code],
340             
341 #           'TextFlag'  => [0, 1, Parse_boolean,   0],
342 #           'ExtraField'=> [0, 1, Parse_string,    ''],
343
344             @Bzip2,
345         );
346 }
347
348 sub getInverseClass
349 {
350     return ('IO::Uncompress::Unzip',
351                 \$IO::Uncompress::Unzip::UnzipError);
352 }
353
354 sub getFileInfo
355 {
356     my $self = shift ;
357     my $params = shift;
358     my $filename = shift ;
359
360     my $defaultTime = (stat($filename))[9] ;
361
362     $params->value('Name' => $filename)
363         if ! $params->parsed('Name') ;
364
365     $params->value('Time' => $defaultTime) 
366         if ! $params->parsed('Time') ;
367     
368     
369 }
370
371 # from Archive::Zip
372 sub _unixToDosTime    # Archive::Zip::Member
373 {
374         my $time_t = shift;
375     # TODO - add something to cope with unix time < 1980 
376         my ( $sec, $min, $hour, $mday, $mon, $year ) = localtime($time_t);
377         my $dt = 0;
378         $dt += ( $sec >> 1 );
379         $dt += ( $min << 5 );
380         $dt += ( $hour << 11 );
381         $dt += ( $mday << 16 );
382         $dt += ( ( $mon + 1 ) << 21 );
383         $dt += ( ( $year - 80 ) << 25 );
384         return $dt;
385 }
386
387 1;
388
389 __END__
390
391 =head1 NAME
392
393
394
395 IO::Compress::Zip - Write zip files/buffers
396  
397  
398
399 =head1 SYNOPSIS
400
401     use IO::Compress::Zip qw(zip $ZipError) ;
402
403
404     my $status = zip $input => $output [,OPTS] 
405         or die "zip failed: $ZipError\n";
406
407     my $z = new IO::Compress::Zip $output [,OPTS]
408         or die "zip failed: $ZipError\n";
409
410     $z->print($string);
411     $z->printf($format, $string);
412     $z->write($string);
413     $z->syswrite($string [, $length, $offset]);
414     $z->flush();
415     $z->tell();
416     $z->eof();
417     $z->seek($position, $whence);
418     $z->binmode();
419     $z->fileno();
420     $z->opened();
421     $z->autoflush();
422     $z->input_line_number();
423     $z->newStream( [OPTS] );
424     
425     $z->deflateParams();
426     
427     $z->close() ;
428
429     $ZipError ;
430
431     # IO::File mode
432
433     print $z $string;
434     printf $z $format, $string;
435     tell $z
436     eof $z
437     seek $z, $position, $whence
438     binmode $z
439     fileno $z
440     close $z ;
441     
442
443 =head1 DESCRIPTION
444
445
446
447 B<WARNING -- This is a Beta release>. 
448
449 =over 5
450
451 =item * DO NOT use in production code.
452
453 =item * The documentation is incomplete in places.
454
455 =item * Parts of the interface defined here are tentative.
456
457 =item * Please report any problems you find.
458
459 =back
460
461
462
463
464 This module provides a Perl interface that allows writing zip 
465 compressed data to files or buffer.
466
467
468
469
470
471
472
473 Note that IO::Compress::Zip is not intended to be a replacement for the module
474 C<Archive::Zip>.
475
476 The primary aim of this module is not as an archiver, but to provide
477 streaming write access to zip file files and buffers.
478
479
480
481 For reading zip files/buffers, see the companion module 
482 L<IO::Uncompress::Unzip|IO::Uncompress::Unzip>.
483
484
485 =head1 Functional Interface
486
487 A top-level function, C<zip>, is provided to carry out
488 "one-shot" compression between buffers and/or files. For finer
489 control over the compression process, see the L</"OO Interface">
490 section.
491
492     use IO::Compress::Zip qw(zip $ZipError) ;
493
494     zip $input => $output [,OPTS] 
495         or die "zip failed: $ZipError\n";
496
497
498
499 The functional interface needs Perl5.005 or better.
500
501
502 =head2 zip $input => $output [, OPTS]
503
504
505 C<zip> expects at least two parameters, C<$input> and C<$output>.
506
507 =head3 The C<$input> parameter
508
509 The parameter, C<$input>, is used to define the source of
510 the uncompressed data. 
511
512 It can take one of the following forms:
513
514 =over 5
515
516 =item A filename
517
518 If the C<$input> parameter is a simple scalar, it is assumed to be a
519 filename. This file will be opened for reading and the input data
520 will be read from it.
521
522 =item A filehandle
523
524 If the C<$input> parameter is a filehandle, the input data will be
525 read from it.
526 The string '-' can be used as an alias for standard input.
527
528 =item A scalar reference 
529
530 If C<$input> is a scalar reference, the input data will be read
531 from C<$$input>.
532
533 =item An array reference 
534
535 If C<$input> is an array reference, each element in the array must be a
536 filename.
537
538 The input data will be read from each file in turn. 
539
540 The complete array will be walked to ensure that it only
541 contains valid filenames before any data is compressed.
542
543
544
545 =item An Input FileGlob string
546
547 If C<$input> is a string that is delimited by the characters "<" and ">"
548 C<zip> will assume that it is an I<input fileglob string>. The
549 input is the list of files that match the fileglob.
550
551 If the fileglob does not match any files ...
552
553 See L<File::GlobMapper|File::GlobMapper> for more details.
554
555
556 =back
557
558 If the C<$input> parameter is any other type, C<undef> will be returned.
559
560
561 In addition, if C<$input> is a simple filename, the default values for
562 the C<Name> and C<Time> options will be sourced from that file.
563
564 If you do not want to use these defaults they can be overridden by
565 explicitly setting the C<Name> and C<Time> options or by setting the
566 C<Minimal> parameter.
567
568
569
570 =head3 The C<$output> parameter
571
572 The parameter C<$output> is used to control the destination of the
573 compressed data. This parameter can take one of these forms.
574
575 =over 5
576
577 =item A filename
578
579 If the C<$output> parameter is a simple scalar, it is assumed to be a
580 filename.  This file will be opened for writing and the compressed
581 data will be written to it.
582
583 =item A filehandle
584
585 If the C<$output> parameter is a filehandle, the compressed data
586 will be written to it.
587 The string '-' can be used as an alias for standard output.
588
589
590 =item A scalar reference 
591
592 If C<$output> is a scalar reference, the compressed data will be
593 stored in C<$$output>.
594
595
596
597 =item An Array Reference
598
599 If C<$output> is an array reference, the compressed data will be
600 pushed onto the array.
601
602 =item An Output FileGlob
603
604 If C<$output> is a string that is delimited by the characters "<" and ">"
605 C<zip> will assume that it is an I<output fileglob string>. The
606 output is the list of files that match the fileglob.
607
608 When C<$output> is an fileglob string, C<$input> must also be a fileglob
609 string. Anything else is an error.
610
611 =back
612
613 If the C<$output> parameter is any other type, C<undef> will be returned.
614
615
616
617 =head2 Notes
618
619 When C<$input> maps to multiple files/buffers and C<$output> is a single
620 file/buffer the compressed input files/buffers will all be stored
621 in C<$output> as a single compressed stream.
622
623
624
625 =head2 Optional Parameters
626
627 Unless specified below, the optional parameters for C<zip>,
628 C<OPTS>, are the same as those used with the OO interface defined in the
629 L</"Constructor Options"> section below.
630
631 =over 5
632
633 =item AutoClose =E<gt> 0|1
634
635 This option applies to any input or output data streams to 
636 C<zip> that are filehandles.
637
638 If C<AutoClose> is specified, and the value is true, it will result in all
639 input and/or output filehandles being closed once C<zip> has
640 completed.
641
642 This parameter defaults to 0.
643
644
645
646 =item BinModeIn =E<gt> 0|1
647
648 When reading from a file or filehandle, set C<binmode> before reading.
649
650 Defaults to 0.
651
652
653
654
655
656 =item -Append =E<gt> 0|1
657
658 TODO
659
660
661 =back
662
663
664
665 =head2 Examples
666
667 To read the contents of the file C<file1.txt> and write the compressed
668 data to the file C<file1.txt.zip>.
669
670     use strict ;
671     use warnings ;
672     use IO::Compress::Zip qw(zip $ZipError) ;
673
674     my $input = "file1.txt";
675     zip $input => "$input.zip"
676         or die "zip failed: $ZipError\n";
677
678
679 To read from an existing Perl filehandle, C<$input>, and write the
680 compressed data to a buffer, C<$buffer>.
681
682     use strict ;
683     use warnings ;
684     use IO::Compress::Zip qw(zip $ZipError) ;
685     use IO::File ;
686
687     my $input = new IO::File "<file1.txt"
688         or die "Cannot open 'file1.txt': $!\n" ;
689     my $buffer ;
690     zip $input => \$buffer 
691         or die "zip failed: $ZipError\n";
692
693 To compress all files in the directory "/my/home" that match "*.txt"
694 and store the compressed data in the same directory
695
696     use strict ;
697     use warnings ;
698     use IO::Compress::Zip qw(zip $ZipError) ;
699
700     zip '</my/home/*.txt>' => '<*.zip>'
701         or die "zip failed: $ZipError\n";
702
703 and if you want to compress each file one at a time, this will do the trick
704
705     use strict ;
706     use warnings ;
707     use IO::Compress::Zip qw(zip $ZipError) ;
708
709     for my $input ( glob "/my/home/*.txt" )
710     {
711         my $output = "$input.zip" ;
712         zip $input => $output 
713             or die "Error compressing '$input': $ZipError\n";
714     }
715
716
717 =head1 OO Interface
718
719 =head2 Constructor
720
721 The format of the constructor for C<IO::Compress::Zip> is shown below
722
723     my $z = new IO::Compress::Zip $output [,OPTS]
724         or die "IO::Compress::Zip failed: $ZipError\n";
725
726 It returns an C<IO::Compress::Zip> object on success and undef on failure. 
727 The variable C<$ZipError> will contain an error message on failure.
728
729 If you are running Perl 5.005 or better the object, C<$z>, returned from 
730 IO::Compress::Zip can be used exactly like an L<IO::File|IO::File> filehandle. 
731 This means that all normal output file operations can be carried out 
732 with C<$z>. 
733 For example, to write to a compressed file/buffer you can use either of 
734 these forms
735
736     $z->print("hello world\n");
737     print $z "hello world\n";
738
739 The mandatory parameter C<$output> is used to control the destination
740 of the compressed data. This parameter can take one of these forms.
741
742 =over 5
743
744 =item A filename
745
746 If the C<$output> parameter is a simple scalar, it is assumed to be a
747 filename. This file will be opened for writing and the compressed data
748 will be written to it.
749
750 =item A filehandle
751
752 If the C<$output> parameter is a filehandle, the compressed data will be
753 written to it.
754 The string '-' can be used as an alias for standard output.
755
756
757 =item A scalar reference 
758
759 If C<$output> is a scalar reference, the compressed data will be stored
760 in C<$$output>.
761
762 =back
763
764 If the C<$output> parameter is any other type, C<IO::Compress::Zip>::new will
765 return undef.
766
767 =head2 Constructor Options
768
769 C<OPTS> is any combination of the following options:
770
771 =over 5
772
773 =item AutoClose =E<gt> 0|1
774
775 This option is only valid when the C<$output> parameter is a filehandle. If
776 specified, and the value is true, it will result in the C<$output> being
777 closed once either the C<close> method is called or the C<IO::Compress::Zip>
778 object is destroyed.
779
780 This parameter defaults to 0.
781
782 =item Append =E<gt> 0|1
783
784 Opens C<$output> in append mode. 
785
786 The behaviour of this option is dependent on the type of C<$output>.
787
788 =over 5
789
790 =item * A Buffer
791
792 If C<$output> is a buffer and C<Append> is enabled, all compressed data
793 will be append to the end if C<$output>. Otherwise C<$output> will be
794 cleared before any data is written to it.
795
796 =item * A Filename
797
798 If C<$output> is a filename and C<Append> is enabled, the file will be
799 opened in append mode. Otherwise the contents of the file, if any, will be
800 truncated before any compressed data is written to it.
801
802 =item * A Filehandle
803
804 If C<$output> is a filehandle, the file pointer will be positioned to the
805 end of the file via a call to C<seek> before any compressed data is written
806 to it.  Otherwise the file pointer will not be moved.
807
808 =back
809
810 This parameter defaults to 0.
811
812
813
814 =item -Name =E<gt> $string
815
816 Stores the contents of C<$string> in the zip filename header field. If
817 C<Name> is not specified, no zip filename field will be created.
818
819 =item -Time =E<gt> $number
820
821 Sets the last modified time field in the zip header to $number.
822
823 This field defaults to the time the C<IO::Compress::Zip> object was created
824 if this option is not specified.
825
826 =item Method =E<gt> $method
827
828 Controls which compression method is used. At present three compression
829 methods are supported, namely Store (no compression at all), Deflate and
830 Bzip2.
831
832 The symbols, ZIP_CM_STORE, ZIP_CM_DEFLATE and ZIP_CM_BZIP2 are used to
833 select the compression method.
834
835 These constants are not imported by C<IO::Compress::Zip> by default.
836
837     use IO::Compress::Zip qw(:zip_method);
838     use IO::Compress::Zip qw(:constants);
839     use IO::Compress::Zip qw(:all);
840
841 Note that to create Bzip2 content, the module C<IO::Compress::Bzip2> must
842 be installed. A fatal error will be thrown if you attempt to create Bzip2
843 content when C<IO::Compress::Bzip2> is not available.
844
845 The default method is ZIP_CM_DEFLATE.
846
847 =item -Stream =E<gt> 0|1
848
849 This option controls whether the zip file/buffer output is created in
850 streaming mode.
851
852 The default is 1.
853
854 =item BlockSize100K =E<gt> number
855
856 Specify the number of 100K blocks bzip2 uses during compression. 
857
858 Valid values are from 1 to 9, where 9 is best compression.
859
860 This option is only valid if the C<Method> is ZIP_CM_BZIP2. It is ignored
861 otherwise.
862
863 The default is 1.
864
865 =item WorkFactor =E<gt> number
866
867 Specifies how much effort bzip2 should take before resorting to a slower
868 fallback compression algorithm.
869
870 Valid values range from 0 to 250, where 0 means use the default value 30.
871
872 This option is only valid if the C<Method> is ZIP_CM_BZIP2. It is ignored
873 otherwise.
874
875 The default is 0.
876
877
878
879
880 =item -Level 
881
882 Defines the compression level used by zlib. The value should either be
883 a number between 0 and 9 (0 means no compression and 9 is maximum
884 compression), or one of the symbolic constants defined below.
885
886    Z_NO_COMPRESSION
887    Z_BEST_SPEED
888    Z_BEST_COMPRESSION
889    Z_DEFAULT_COMPRESSION
890
891 The default is Z_DEFAULT_COMPRESSION.
892
893 Note, these constants are not imported by C<IO::Compress::Zip> by default.
894
895     use IO::Compress::Zip qw(:strategy);
896     use IO::Compress::Zip qw(:constants);
897     use IO::Compress::Zip qw(:all);
898
899 =item -Strategy 
900
901 Defines the strategy used to tune the compression. Use one of the symbolic
902 constants defined below.
903
904    Z_FILTERED
905    Z_HUFFMAN_ONLY
906    Z_RLE
907    Z_FIXED
908    Z_DEFAULT_STRATEGY
909
910 The default is Z_DEFAULT_STRATEGY.
911
912
913
914
915
916
917 =item -Strict =E<gt> 0|1
918
919
920
921 This is a placeholder option.
922
923
924
925 =back
926
927 =head2 Examples
928
929 TODO
930
931 =head1 Methods 
932
933 =head2 print
934
935 Usage is
936
937     $z->print($data)
938     print $z $data
939
940 Compresses and outputs the contents of the C<$data> parameter. This
941 has the same behaviour as the C<print> built-in.
942
943 Returns true if successful.
944
945 =head2 printf
946
947 Usage is
948
949     $z->printf($format, $data)
950     printf $z $format, $data
951
952 Compresses and outputs the contents of the C<$data> parameter.
953
954 Returns true if successful.
955
956 =head2 syswrite
957
958 Usage is
959
960     $z->syswrite $data
961     $z->syswrite $data, $length
962     $z->syswrite $data, $length, $offset
963
964 Compresses and outputs the contents of the C<$data> parameter.
965
966 Returns the number of uncompressed bytes written, or C<undef> if
967 unsuccessful.
968
969 =head2 write
970
971 Usage is
972
973     $z->write $data
974     $z->write $data, $length
975     $z->write $data, $length, $offset
976
977 Compresses and outputs the contents of the C<$data> parameter.
978
979 Returns the number of uncompressed bytes written, or C<undef> if
980 unsuccessful.
981
982 =head2 flush
983
984 Usage is
985
986
987     $z->flush;
988     $z->flush($flush_type);
989
990
991 Flushes any pending compressed data to the output file/buffer.
992
993
994 This method takes an optional parameter, C<$flush_type>, that controls
995 how the flushing will be carried out. By default the C<$flush_type>
996 used is C<Z_FINISH>. Other valid values for C<$flush_type> are
997 C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
998 strongly recommended that you only set the C<flush_type> parameter if
999 you fully understand the implications of what it does - overuse of C<flush>
1000 can seriously degrade the level of compression achieved. See the C<zlib>
1001 documentation for details.
1002
1003
1004 Returns true on success.
1005
1006
1007 =head2 tell
1008
1009 Usage is
1010
1011     $z->tell()
1012     tell $z
1013
1014 Returns the uncompressed file offset.
1015
1016 =head2 eof
1017
1018 Usage is
1019
1020     $z->eof();
1021     eof($z);
1022
1023
1024
1025 Returns true if the C<close> method has been called.
1026
1027
1028
1029 =head2 seek
1030
1031     $z->seek($position, $whence);
1032     seek($z, $position, $whence);
1033
1034
1035
1036
1037 Provides a sub-set of the C<seek> functionality, with the restriction
1038 that it is only legal to seek forward in the output file/buffer.
1039 It is a fatal error to attempt to seek backward.
1040
1041 Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
1042
1043
1044
1045 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
1046 SEEK_CUR or SEEK_END.
1047
1048 Returns 1 on success, 0 on failure.
1049
1050 =head2 binmode
1051
1052 Usage is
1053
1054     $z->binmode
1055     binmode $z ;
1056
1057 This is a noop provided for completeness.
1058
1059 =head2 opened
1060
1061     $z->opened()
1062
1063 Returns true if the object currently refers to a opened file/buffer. 
1064
1065 =head2 autoflush
1066
1067     my $prev = $z->autoflush()
1068     my $prev = $z->autoflush(EXPR)
1069
1070 If the C<$z> object is associated with a file or a filehandle, this method
1071 returns the current autoflush setting for the underlying filehandle. If
1072 C<EXPR> is present, and is non-zero, it will enable flushing after every
1073 write/print operation.
1074
1075 If C<$z> is associated with a buffer, this method has no effect and always
1076 returns C<undef>.
1077
1078 B<Note> that the special variable C<$|> B<cannot> be used to set or
1079 retrieve the autoflush setting.
1080
1081 =head2 input_line_number
1082
1083     $z->input_line_number()
1084     $z->input_line_number(EXPR)
1085
1086
1087 This method always returns C<undef> when compressing. 
1088
1089
1090
1091 =head2 fileno
1092
1093     $z->fileno()
1094     fileno($z)
1095
1096 If the C<$z> object is associated with a file or a filehandle, this method
1097 will return the underlying file descriptor.
1098
1099 If the C<$z> object is is associated with a buffer, this method will
1100 return undef.
1101
1102 =head2 close
1103
1104     $z->close() ;
1105     close $z ;
1106
1107
1108
1109 Flushes any pending compressed data and then closes the output file/buffer. 
1110
1111
1112
1113 For most versions of Perl this method will be automatically invoked if
1114 the IO::Compress::Zip object is destroyed (either explicitly or by the
1115 variable with the reference to the object going out of scope). The
1116 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
1117 these cases, the C<close> method will be called automatically, but
1118 not until global destruction of all live objects when the program is
1119 terminating.
1120
1121 Therefore, if you want your scripts to be able to run on all versions
1122 of Perl, you should call C<close> explicitly and not rely on automatic
1123 closing.
1124
1125 Returns true on success, otherwise 0.
1126
1127 If the C<AutoClose> option has been enabled when the IO::Compress::Zip
1128 object was created, and the object is associated with a file, the
1129 underlying file will also be closed.
1130
1131
1132
1133
1134 =head2 newStream([OPTS])
1135
1136 Usage is
1137
1138     $z->newStream( [OPTS] )
1139
1140 Closes the current compressed data stream and starts a new one.
1141
1142 OPTS consists of the following sub-set of the the options that are
1143 available when creating the C<$z> object,
1144
1145 =over 5
1146
1147
1148
1149 =item * Level
1150
1151
1152
1153 =back
1154
1155
1156 =head2 deflateParams
1157
1158 Usage is
1159
1160     $z->deflateParams
1161
1162 TODO
1163
1164
1165 =head1 Importing 
1166
1167
1168 A number of symbolic constants are required by some methods in 
1169 C<IO::Compress::Zip>. None are imported by default.
1170
1171
1172
1173 =over 5
1174
1175 =item :all
1176
1177
1178 Imports C<zip>, C<$ZipError> and all symbolic
1179 constants that can be used by C<IO::Compress::Zip>. Same as doing this
1180
1181     use IO::Compress::Zip qw(zip $ZipError :constants) ;
1182
1183 =item :constants
1184
1185 Import all symbolic constants. Same as doing this
1186
1187
1188     use IO::Compress::Zip qw(:flush :level :strategy :zip_method) ;
1189
1190
1191 =item :flush
1192
1193 These symbolic constants are used by the C<flush> method.
1194
1195     Z_NO_FLUSH
1196     Z_PARTIAL_FLUSH
1197     Z_SYNC_FLUSH
1198     Z_FULL_FLUSH
1199     Z_FINISH
1200     Z_BLOCK
1201
1202 =item :level
1203
1204 These symbolic constants are used by the C<Level> option in the constructor.
1205
1206     Z_NO_COMPRESSION
1207     Z_BEST_SPEED
1208     Z_BEST_COMPRESSION
1209     Z_DEFAULT_COMPRESSION
1210
1211
1212 =item :strategy
1213
1214 These symbolic constants are used by the C<Strategy> option in the constructor.
1215
1216     Z_FILTERED
1217     Z_HUFFMAN_ONLY
1218     Z_RLE
1219     Z_FIXED
1220     Z_DEFAULT_STRATEGY
1221
1222
1223 =item :zip_method
1224
1225 These symbolic constants are used by the C<Method> option in the
1226 constructor.
1227
1228     ZIP_CM_STORE
1229     ZIP_CM_DEFLATE
1230     ZIP_CM_BZIP2
1231
1232     
1233     
1234
1235 =back
1236
1237 For 
1238
1239 =head1 EXAMPLES
1240
1241 TODO
1242
1243
1244
1245
1246
1247
1248 =head1 SEE ALSO
1249
1250 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::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
1251
1252 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1253
1254 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1255 L<Archive::Tar|Archive::Tar>,
1256 L<IO::Zlib|IO::Zlib>
1257
1258
1259 For RFC 1950, 1951 and 1952 see 
1260 F<http://www.faqs.org/rfcs/rfc1950.html>,
1261 F<http://www.faqs.org/rfcs/rfc1951.html> and
1262 F<http://www.faqs.org/rfcs/rfc1952.html>
1263
1264 The I<zlib> compression library was written by Jean-loup Gailly
1265 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1266
1267 The primary site for the I<zlib> compression library is
1268 F<http://www.zlib.org>.
1269
1270 The primary site for gzip is F<http://www.gzip.org>.
1271
1272
1273
1274
1275 =head1 AUTHOR
1276
1277 This module was written by Paul Marquess, F<pmqs@cpan.org>. 
1278
1279
1280
1281 =head1 MODIFICATION HISTORY
1282
1283 See the Changes file.
1284
1285 =head1 COPYRIGHT AND LICENSE
1286
1287 Copyright (c) 2005-2006 Paul Marquess. All rights reserved.
1288
1289 This program is free software; you can redistribute it and/or
1290 modify it under the same terms as Perl itself.
1291
1292