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