Update IO-Compress to CPAN version 2.069
[perl.git] / cpan / IO-Compress / lib / IO / Uncompress / Gunzip.pm
1
2 package IO::Uncompress::Gunzip ;
3
4 require 5.006 ;
5
6 # for RFC1952
7
8 use strict ;
9 use warnings;
10 use bytes;
11
12 use IO::Uncompress::RawInflate 2.069 ;
13
14 use Compress::Raw::Zlib 2.069 () ;
15 use IO::Compress::Base::Common 2.069 qw(:Status );
16 use IO::Compress::Gzip::Constants 2.069 ;
17 use IO::Compress::Zlib::Extra 2.069 ;
18
19 require Exporter ;
20
21 our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $GunzipError);
22
23 @ISA = qw( Exporter IO::Uncompress::RawInflate );
24 @EXPORT_OK = qw( $GunzipError gunzip );
25 %EXPORT_TAGS = %IO::Uncompress::RawInflate::DEFLATE_CONSTANTS ;
26 push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
27 Exporter::export_ok_tags('all');
28
29 $GunzipError = '';
30
31 $VERSION = '2.069';
32
33 sub new
34 {
35     my $class = shift ;
36     $GunzipError = '';
37     my $obj = IO::Compress::Base::Common::createSelfTiedObject($class, \$GunzipError);
38
39     $obj->_create(undef, 0, @_);
40 }
41
42 sub gunzip
43 {
44     my $obj = IO::Compress::Base::Common::createSelfTiedObject(undef, \$GunzipError);
45     return $obj->_inf(@_) ;
46 }
47
48 sub getExtraParams
49 {
50     return ( 'parseextra' => [IO::Compress::Base::Common::Parse_boolean,  0] ) ;
51 }
52
53 sub ckParams
54 {
55     my $self = shift ;
56     my $got = shift ;
57
58     # gunzip always needs crc32
59     $got->setValue('crc32' => 1);
60
61     return 1;
62 }
63
64 sub ckMagic
65 {
66     my $self = shift;
67
68     my $magic ;
69     $self->smartReadExact(\$magic, GZIP_ID_SIZE);
70
71     *$self->{HeaderPending} = $magic ;
72
73     return $self->HeaderError("Minimum header size is " . 
74                               GZIP_MIN_HEADER_SIZE . " bytes") 
75         if length $magic != GZIP_ID_SIZE ;                                    
76
77     return $self->HeaderError("Bad Magic")
78         if ! isGzipMagic($magic) ;
79
80     *$self->{Type} = 'rfc1952';
81
82     return $magic ;
83 }
84
85 sub readHeader
86 {
87     my $self = shift;
88     my $magic = shift;
89
90     return $self->_readGzipHeader($magic);
91 }
92
93 sub chkTrailer
94 {
95     my $self = shift;
96     my $trailer = shift;
97
98     # Check CRC & ISIZE 
99     my ($CRC32, $ISIZE) = unpack("V V", $trailer) ;
100     *$self->{Info}{CRC32} = $CRC32;    
101     *$self->{Info}{ISIZE} = $ISIZE;    
102
103     if (*$self->{Strict}) {
104         return $self->TrailerError("CRC mismatch")
105             if $CRC32 != *$self->{Uncomp}->crc32() ;
106
107         my $exp_isize = *$self->{UnCompSize}->get32bit();
108         return $self->TrailerError("ISIZE mismatch. Got $ISIZE"
109                                   . ", expected $exp_isize")
110             if $ISIZE != $exp_isize ;
111     }
112
113     return STATUS_OK;
114 }
115
116 sub isGzipMagic
117 {
118     my $buffer = shift ;
119     return 0 if length $buffer < GZIP_ID_SIZE ;
120     my ($id1, $id2) = unpack("C C", $buffer) ;
121     return $id1 == GZIP_ID1 && $id2 == GZIP_ID2 ;
122 }
123
124 sub _readFullGzipHeader($)
125 {
126     my ($self) = @_ ;
127     my $magic = '' ;
128
129     $self->smartReadExact(\$magic, GZIP_ID_SIZE);
130
131     *$self->{HeaderPending} = $magic ;
132
133     return $self->HeaderError("Minimum header size is " . 
134                               GZIP_MIN_HEADER_SIZE . " bytes") 
135         if length $magic != GZIP_ID_SIZE ;                                    
136
137
138     return $self->HeaderError("Bad Magic")
139         if ! isGzipMagic($magic) ;
140
141     my $status = $self->_readGzipHeader($magic);
142     delete *$self->{Transparent} if ! defined $status ;
143     return $status ;
144 }
145
146 sub _readGzipHeader($)
147 {
148     my ($self, $magic) = @_ ;
149     my ($HeaderCRC) ;
150     my ($buffer) = '' ;
151
152     $self->smartReadExact(\$buffer, GZIP_MIN_HEADER_SIZE - GZIP_ID_SIZE)
153         or return $self->HeaderError("Minimum header size is " . 
154                                      GZIP_MIN_HEADER_SIZE . " bytes") ;
155
156     my $keep = $magic . $buffer ;
157     *$self->{HeaderPending} = $keep ;
158
159     # now split out the various parts
160     my ($cm, $flag, $mtime, $xfl, $os) = unpack("C C V C C", $buffer) ;
161
162     $cm == GZIP_CM_DEFLATED 
163         or return $self->HeaderError("Not Deflate (CM is $cm)") ;
164
165     # check for use of reserved bits
166     return $self->HeaderError("Use of Reserved Bits in FLG field.")
167         if $flag & GZIP_FLG_RESERVED ; 
168
169     my $EXTRA ;
170     my @EXTRA = () ;
171     if ($flag & GZIP_FLG_FEXTRA) {
172         $EXTRA = "" ;
173         $self->smartReadExact(\$buffer, GZIP_FEXTRA_HEADER_SIZE) 
174             or return $self->TruncatedHeader("FEXTRA Length") ;
175
176         my ($XLEN) = unpack("v", $buffer) ;
177         $self->smartReadExact(\$EXTRA, $XLEN) 
178             or return $self->TruncatedHeader("FEXTRA Body");
179         $keep .= $buffer . $EXTRA ;
180
181         if ($XLEN && *$self->{'ParseExtra'}) {
182             my $bad = IO::Compress::Zlib::Extra::parseRawExtra($EXTRA,
183                                                 \@EXTRA, 1, 1);
184             return $self->HeaderError($bad)
185                 if defined $bad;
186         }
187     }
188
189     my $origname ;
190     if ($flag & GZIP_FLG_FNAME) {
191         $origname = "" ;
192         while (1) {
193             $self->smartReadExact(\$buffer, 1) 
194                 or return $self->TruncatedHeader("FNAME");
195             last if $buffer eq GZIP_NULL_BYTE ;
196             $origname .= $buffer 
197         }
198         $keep .= $origname . GZIP_NULL_BYTE ;
199
200         return $self->HeaderError("Non ISO 8859-1 Character found in Name")
201             if *$self->{Strict} && $origname =~ /$GZIP_FNAME_INVALID_CHAR_RE/o ;
202     }
203
204     my $comment ;
205     if ($flag & GZIP_FLG_FCOMMENT) {
206         $comment = "";
207         while (1) {
208             $self->smartReadExact(\$buffer, 1) 
209                 or return $self->TruncatedHeader("FCOMMENT");
210             last if $buffer eq GZIP_NULL_BYTE ;
211             $comment .= $buffer 
212         }
213         $keep .= $comment . GZIP_NULL_BYTE ;
214
215         return $self->HeaderError("Non ISO 8859-1 Character found in Comment")
216             if *$self->{Strict} && $comment =~ /$GZIP_FCOMMENT_INVALID_CHAR_RE/o ;
217     }
218
219     if ($flag & GZIP_FLG_FHCRC) {
220         $self->smartReadExact(\$buffer, GZIP_FHCRC_SIZE) 
221             or return $self->TruncatedHeader("FHCRC");
222
223         $HeaderCRC = unpack("v", $buffer) ;
224         my $crc16 = Compress::Raw::Zlib::crc32($keep) & 0xFF ;
225
226         return $self->HeaderError("CRC16 mismatch.")
227             if *$self->{Strict} && $crc16 != $HeaderCRC;
228
229         $keep .= $buffer ;
230     }
231
232     # Assume compression method is deflated for xfl tests
233     #if ($xfl) {
234     #}
235
236     *$self->{Type} = 'rfc1952';
237
238     return {
239         'Type'          => 'rfc1952',
240         'FingerprintLength'  => 2,
241         'HeaderLength'  => length $keep,
242         'TrailerLength' => GZIP_TRAILER_SIZE,
243         'Header'        => $keep,
244         'isMinimalHeader' => $keep eq GZIP_MINIMUM_HEADER ? 1 : 0,
245
246         'MethodID'      => $cm,
247         'MethodName'    => $cm == GZIP_CM_DEFLATED ? "Deflated" : "Unknown" ,
248         'TextFlag'      => $flag & GZIP_FLG_FTEXT ? 1 : 0,
249         'HeaderCRCFlag' => $flag & GZIP_FLG_FHCRC ? 1 : 0,
250         'NameFlag'      => $flag & GZIP_FLG_FNAME ? 1 : 0,
251         'CommentFlag'   => $flag & GZIP_FLG_FCOMMENT ? 1 : 0,
252         'ExtraFlag'     => $flag & GZIP_FLG_FEXTRA ? 1 : 0,
253         'Name'          => $origname,
254         'Comment'       => $comment,
255         'Time'          => $mtime,
256         'OsID'          => $os,
257         'OsName'        => defined $GZIP_OS_Names{$os} 
258                                  ? $GZIP_OS_Names{$os} : "Unknown",
259         'HeaderCRC'     => $HeaderCRC,
260         'Flags'         => $flag,
261         'ExtraFlags'    => $xfl,
262         'ExtraFieldRaw' => $EXTRA,
263         'ExtraField'    => [ @EXTRA ],
264
265
266         #'CompSize'=> $compsize,
267         #'CRC32'=> $CRC32,
268         #'OrigSize'=> $ISIZE,
269       }
270 }
271
272
273 1;
274
275 __END__
276
277
278 =head1 NAME
279
280 IO::Uncompress::Gunzip - Read RFC 1952 files/buffers
281
282 =head1 SYNOPSIS
283
284     use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
285
286     my $status = gunzip $input => $output [,OPTS]
287         or die "gunzip failed: $GunzipError\n";
288
289     my $z = new IO::Uncompress::Gunzip $input [OPTS] 
290         or die "gunzip failed: $GunzipError\n";
291
292     $status = $z->read($buffer)
293     $status = $z->read($buffer, $length)
294     $status = $z->read($buffer, $length, $offset)
295     $line = $z->getline()
296     $char = $z->getc()
297     $char = $z->ungetc()
298     $char = $z->opened()
299
300     $status = $z->inflateSync()
301
302     $data = $z->trailingData()
303     $status = $z->nextStream()
304     $data = $z->getHeaderInfo()
305     $z->tell()
306     $z->seek($position, $whence)
307     $z->binmode()
308     $z->fileno()
309     $z->eof()
310     $z->close()
311
312     $GunzipError ;
313
314     # IO::File mode
315
316     <$z>
317     read($z, $buffer);
318     read($z, $buffer, $length);
319     read($z, $buffer, $length, $offset);
320     tell($z)
321     seek($z, $position, $whence)
322     binmode($z)
323     fileno($z)
324     eof($z)
325     close($z)
326
327 =head1 DESCRIPTION
328
329 This module provides a Perl interface that allows the reading of
330 files/buffers that conform to RFC 1952.
331
332 For writing RFC 1952 files/buffers, see the companion module IO::Compress::Gzip.
333
334 =head1 Functional Interface
335
336 A top-level function, C<gunzip>, is provided to carry out
337 "one-shot" uncompression between buffers and/or files. For finer
338 control over the uncompression process, see the L</"OO Interface">
339 section.
340
341     use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
342
343     gunzip $input_filename_or_reference => $output_filename_or_reference [,OPTS] 
344         or die "gunzip failed: $GunzipError\n";
345
346 The functional interface needs Perl5.005 or better.
347
348 =head2 gunzip $input_filename_or_reference => $output_filename_or_reference [, OPTS]
349
350 C<gunzip> expects at least two parameters,
351 C<$input_filename_or_reference> and C<$output_filename_or_reference>.
352
353 =head3 The C<$input_filename_or_reference> parameter
354
355 The parameter, C<$input_filename_or_reference>, is used to define the
356 source of the compressed data. 
357
358 It can take one of the following forms:
359
360 =over 5
361
362 =item A filename
363
364 If the <$input_filename_or_reference> parameter is a simple scalar, it is
365 assumed to be a filename. This file will be opened for reading and the
366 input data will be read from it.
367
368 =item A filehandle
369
370 If the C<$input_filename_or_reference> parameter is a filehandle, the input
371 data will be read from it.  The string '-' can be used as an alias for
372 standard input.
373
374 =item A scalar reference 
375
376 If C<$input_filename_or_reference> is a scalar reference, the input data
377 will be read from C<$$input_filename_or_reference>.
378
379 =item An array reference 
380
381 If C<$input_filename_or_reference> is an array reference, each element in
382 the array must be a filename.
383
384 The input data will be read from each file in turn. 
385
386 The complete array will be walked to ensure that it only
387 contains valid filenames before any data is uncompressed.
388
389 =item An Input FileGlob string
390
391 If C<$input_filename_or_reference> is a string that is delimited by the
392 characters "<" and ">" C<gunzip> will assume that it is an 
393 I<input fileglob string>. The input is the list of files that match the 
394 fileglob.
395
396 See L<File::GlobMapper|File::GlobMapper> for more details.
397
398 =back
399
400 If the C<$input_filename_or_reference> parameter is any other type,
401 C<undef> will be returned.
402
403 =head3 The C<$output_filename_or_reference> parameter
404
405 The parameter C<$output_filename_or_reference> is used to control the
406 destination of the uncompressed data. This parameter can take one of
407 these forms.
408
409 =over 5
410
411 =item A filename
412
413 If the C<$output_filename_or_reference> parameter is a simple scalar, it is
414 assumed to be a filename.  This file will be opened for writing and the 
415 uncompressed data will be written to it.
416
417 =item A filehandle
418
419 If the C<$output_filename_or_reference> parameter is a filehandle, the
420 uncompressed data will be written to it.  The string '-' can be used as
421 an alias for standard output.
422
423 =item A scalar reference 
424
425 If C<$output_filename_or_reference> is a scalar reference, the
426 uncompressed data will be stored in C<$$output_filename_or_reference>.
427
428 =item An Array Reference
429
430 If C<$output_filename_or_reference> is an array reference, 
431 the uncompressed data will be pushed onto the array.
432
433 =item An Output FileGlob
434
435 If C<$output_filename_or_reference> is a string that is delimited by the
436 characters "<" and ">" C<gunzip> will assume that it is an
437 I<output fileglob string>. The output is the list of files that match the
438 fileglob.
439
440 When C<$output_filename_or_reference> is an fileglob string,
441 C<$input_filename_or_reference> must also be a fileglob string. Anything
442 else is an error.
443
444 See L<File::GlobMapper|File::GlobMapper> for more details.
445
446 =back
447
448 If the C<$output_filename_or_reference> parameter is any other type,
449 C<undef> will be returned.
450
451 =head2 Notes
452
453 When C<$input_filename_or_reference> maps to multiple compressed
454 files/buffers and C<$output_filename_or_reference> is
455 a single file/buffer, after uncompression C<$output_filename_or_reference> will contain a
456 concatenation of all the uncompressed data from each of the input
457 files/buffers.
458
459 =head2 Optional Parameters
460
461 Unless specified below, the optional parameters for C<gunzip>,
462 C<OPTS>, are the same as those used with the OO interface defined in the
463 L</"Constructor Options"> section below.
464
465 =over 5
466
467 =item C<< AutoClose => 0|1 >>
468
469 This option applies to any input or output data streams to 
470 C<gunzip> that are filehandles.
471
472 If C<AutoClose> is specified, and the value is true, it will result in all
473 input and/or output filehandles being closed once C<gunzip> has
474 completed.
475
476 This parameter defaults to 0.
477
478 =item C<< BinModeOut => 0|1 >>
479
480 When writing to a file or filehandle, set C<binmode> before writing to the
481 file.
482
483 Defaults to 0.
484
485 =item C<< Append => 0|1 >>
486
487 The behaviour of this option is dependent on the type of output data
488 stream.
489
490 =over 5
491
492 =item * A Buffer
493
494 If C<Append> is enabled, all uncompressed data will be append to the end of
495 the output buffer. Otherwise the output buffer will be cleared before any
496 uncompressed data is written to it.
497
498 =item * A Filename
499
500 If C<Append> is enabled, the file will be opened in append mode. Otherwise
501 the contents of the file, if any, will be truncated before any uncompressed
502 data is written to it.
503
504 =item * A Filehandle
505
506 If C<Append> is enabled, the filehandle will be positioned to the end of
507 the file via a call to C<seek> before any uncompressed data is
508 written to it.  Otherwise the file pointer will not be moved.
509
510 =back
511
512 When C<Append> is specified, and set to true, it will I<append> all uncompressed 
513 data to the output data stream.
514
515 So when the output is a filehandle it will carry out a seek to the eof
516 before writing any uncompressed data. If the output is a filename, it will be opened for
517 appending. If the output is a buffer, all uncompressed data will be
518 appended to the existing buffer.
519
520 Conversely when C<Append> is not specified, or it is present and is set to
521 false, it will operate as follows.
522
523 When the output is a filename, it will truncate the contents of the file
524 before writing any uncompressed data. If the output is a filehandle
525 its position will not be changed. If the output is a buffer, it will be
526 wiped before any uncompressed data is output.
527
528 Defaults to 0.
529
530 =item C<< MultiStream => 0|1 >>
531
532 If the input file/buffer contains multiple compressed data streams, this
533 option will uncompress the whole lot as a single data stream.
534
535 Defaults to 0.
536
537 =item C<< TrailingData => $scalar >>
538
539 Returns the data, if any, that is present immediately after the compressed
540 data stream once uncompression is complete. 
541
542 This option can be used when there is useful information immediately
543 following the compressed data stream, and you don't know the length of the
544 compressed data stream.
545
546 If the input is a buffer, C<trailingData> will return everything from the
547 end of the compressed data stream to the end of the buffer.
548
549 If the input is a filehandle, C<trailingData> will return the data that is
550 left in the filehandle input buffer once the end of the compressed data
551 stream has been reached. You can then use the filehandle to read the rest
552 of the input file. 
553
554 Don't bother using C<trailingData> if the input is a filename.
555
556 If you know the length of the compressed data stream before you start
557 uncompressing, you can avoid having to use C<trailingData> by setting the
558 C<InputLength> option.
559
560 =back
561
562 =head2 Examples
563
564 To read the contents of the file C<file1.txt.gz> and write the
565 uncompressed data to the file C<file1.txt>.
566
567     use strict ;
568     use warnings ;
569     use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
570
571     my $input = "file1.txt.gz";
572     my $output = "file1.txt";
573     gunzip $input => $output
574         or die "gunzip failed: $GunzipError\n";
575
576 To read from an existing Perl filehandle, C<$input>, and write the
577 uncompressed data to a buffer, C<$buffer>.
578
579     use strict ;
580     use warnings ;
581     use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
582     use IO::File ;
583
584     my $input = new IO::File "<file1.txt.gz"
585         or die "Cannot open 'file1.txt.gz': $!\n" ;
586     my $buffer ;
587     gunzip $input => \$buffer 
588         or die "gunzip failed: $GunzipError\n";
589
590 To uncompress all files in the directory "/my/home" that match "*.txt.gz" and store the compressed data in the same directory
591
592     use strict ;
593     use warnings ;
594     use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
595
596     gunzip '</my/home/*.txt.gz>' => '</my/home/#1.txt>'
597         or die "gunzip failed: $GunzipError\n";
598
599 and if you want to compress each file one at a time, this will do the trick
600
601     use strict ;
602     use warnings ;
603     use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
604
605     for my $input ( glob "/my/home/*.txt.gz" )
606     {
607         my $output = $input;
608         $output =~ s/.gz// ;
609         gunzip $input => $output 
610             or die "Error compressing '$input': $GunzipError\n";
611     }
612
613 =head1 OO Interface
614
615 =head2 Constructor
616
617 The format of the constructor for IO::Uncompress::Gunzip is shown below
618
619     my $z = new IO::Uncompress::Gunzip $input [OPTS]
620         or die "IO::Uncompress::Gunzip failed: $GunzipError\n";
621
622 Returns an C<IO::Uncompress::Gunzip> object on success and undef on failure.
623 The variable C<$GunzipError> will contain an error message on failure.
624
625 If you are running Perl 5.005 or better the object, C<$z>, returned from
626 IO::Uncompress::Gunzip can be used exactly like an L<IO::File|IO::File> filehandle.
627 This means that all normal input file operations can be carried out with
628 C<$z>.  For example, to read a line from a compressed file/buffer you can
629 use either of these forms
630
631     $line = $z->getline();
632     $line = <$z>;
633
634 The mandatory parameter C<$input> is used to determine the source of the
635 compressed data. This parameter can take one of three forms.
636
637 =over 5
638
639 =item A filename
640
641 If the C<$input> parameter is a scalar, it is assumed to be a filename. This
642 file will be opened for reading and the compressed data will be read from it.
643
644 =item A filehandle
645
646 If the C<$input> parameter is a filehandle, the compressed data will be
647 read from it.
648 The string '-' can be used as an alias for standard input.
649
650 =item A scalar reference 
651
652 If C<$input> is a scalar reference, the compressed data will be read from
653 C<$$input>.
654
655 =back
656
657 =head2 Constructor Options
658
659 The option names defined below are case insensitive and can be optionally
660 prefixed by a '-'.  So all of the following are valid
661
662     -AutoClose
663     -autoclose
664     AUTOCLOSE
665     autoclose
666
667 OPTS is a combination of the following options:
668
669 =over 5
670
671 =item C<< AutoClose => 0|1 >>
672
673 This option is only valid when the C<$input> parameter is a filehandle. If
674 specified, and the value is true, it will result in the file being closed once
675 either the C<close> method is called or the IO::Uncompress::Gunzip object is
676 destroyed.
677
678 This parameter defaults to 0.
679
680 =item C<< MultiStream => 0|1 >>
681
682 Allows multiple concatenated compressed streams to be treated as a single
683 compressed stream. Decompression will stop once either the end of the
684 file/buffer is reached, an error is encountered (premature eof, corrupt
685 compressed data) or the end of a stream is not immediately followed by the
686 start of another stream.
687
688 This parameter defaults to 0.
689
690 =item C<< Prime => $string >>
691
692 This option will uncompress the contents of C<$string> before processing the
693 input file/buffer.
694
695 This option can be useful when the compressed data is embedded in another
696 file/data structure and it is not possible to work out where the compressed
697 data begins without having to read the first few bytes. If this is the
698 case, the uncompression can be I<primed> with these bytes using this
699 option.
700
701 =item C<< Transparent => 0|1 >>
702
703 If this option is set and the input file/buffer is not compressed data,
704 the module will allow reading of it anyway.
705
706 In addition, if the input file/buffer does contain compressed data and
707 there is non-compressed data immediately following it, setting this option
708 will make this module treat the whole file/buffer as a single data stream.
709
710 This option defaults to 1.
711
712 =item C<< BlockSize => $num >>
713
714 When reading the compressed input data, IO::Uncompress::Gunzip will read it in
715 blocks of C<$num> bytes.
716
717 This option defaults to 4096.
718
719 =item C<< InputLength => $size >>
720
721 When present this option will limit the number of compressed bytes read
722 from the input file/buffer to C<$size>. This option can be used in the
723 situation where there is useful data directly after the compressed data
724 stream and you know beforehand the exact length of the compressed data
725 stream. 
726
727 This option is mostly used when reading from a filehandle, in which case
728 the file pointer will be left pointing to the first byte directly after the
729 compressed data stream.
730
731 This option defaults to off.
732
733 =item C<< Append => 0|1 >>
734
735 This option controls what the C<read> method does with uncompressed data.
736
737 If set to 1, all uncompressed data will be appended to the output parameter
738 of the C<read> method.
739
740 If set to 0, the contents of the output parameter of the C<read> method
741 will be overwritten by the uncompressed data.
742
743 Defaults to 0.
744
745 =item C<< Strict => 0|1 >>
746
747 This option controls whether the extra checks defined below are used when
748 carrying out the decompression. When Strict is on, the extra tests are
749 carried out, when Strict is off they are not.
750
751 The default for this option is off.
752
753 =over 5
754
755 =item 1 
756
757 If the FHCRC bit is set in the gzip FLG header byte, the CRC16 bytes in the
758 header must match the crc16 value of the gzip header actually read.
759
760 =item 2
761
762 If the gzip header contains a name field (FNAME) it consists solely of ISO
763 8859-1 characters.
764
765 =item 3
766
767 If the gzip header contains a comment field (FCOMMENT) it consists solely
768 of ISO 8859-1 characters plus line-feed.
769
770 =item 4
771
772 If the gzip FEXTRA header field is present it must conform to the sub-field
773 structure as defined in RFC 1952.
774
775 =item 5
776
777 The CRC32 and ISIZE trailer fields must be present.
778
779 =item 6
780
781 The value of the CRC32 field read must match the crc32 value of the
782 uncompressed data actually contained in the gzip file.
783
784 =item 7
785
786 The value of the ISIZE fields read must match the length of the
787 uncompressed data actually read from the file.
788
789 =back
790
791 =item C<< ParseExtra => 0|1 >>
792 If the gzip FEXTRA header field is present and this option is set, it will
793 force the module to check that it conforms to the sub-field structure as
794 defined in RFC 1952.
795
796 If the C<Strict> is on it will automatically enable this option.
797
798 Defaults to 0.
799
800 =back
801
802 =head2 Examples
803
804 TODO
805
806 =head1 Methods 
807
808 =head2 read
809
810 Usage is
811
812     $status = $z->read($buffer)
813
814 Reads a block of compressed data (the size of the compressed block is
815 determined by the C<Buffer> option in the constructor), uncompresses it and
816 writes any uncompressed data into C<$buffer>. If the C<Append> parameter is
817 set in the constructor, the uncompressed data will be appended to the
818 C<$buffer> parameter. Otherwise C<$buffer> will be overwritten.
819
820 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
821 or a negative number on error.
822
823 =head2 read
824
825 Usage is
826
827     $status = $z->read($buffer, $length)
828     $status = $z->read($buffer, $length, $offset)
829
830     $status = read($z, $buffer, $length)
831     $status = read($z, $buffer, $length, $offset)
832
833 Attempt to read C<$length> bytes of uncompressed data into C<$buffer>.
834
835 The main difference between this form of the C<read> method and the
836 previous one, is that this one will attempt to return I<exactly> C<$length>
837 bytes. The only circumstances that this function will not is if end-of-file
838 or an IO error is encountered.
839
840 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
841 or a negative number on error.
842
843 =head2 getline
844
845 Usage is
846
847     $line = $z->getline()
848     $line = <$z>
849
850 Reads a single line. 
851
852 This method fully supports the use of the variable C<$/> (or
853 C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use) to
854 determine what constitutes an end of line. Paragraph mode, record mode and
855 file slurp mode are all supported. 
856
857 =head2 getc
858
859 Usage is 
860
861     $char = $z->getc()
862
863 Read a single character.
864
865 =head2 ungetc
866
867 Usage is
868
869     $char = $z->ungetc($string)
870
871 =head2 inflateSync
872
873 Usage is
874
875     $status = $z->inflateSync()
876
877 TODO
878
879 =head2 getHeaderInfo
880
881 Usage is
882
883     $hdr  = $z->getHeaderInfo();
884     @hdrs = $z->getHeaderInfo();
885
886 This method returns either a hash reference (in scalar context) or a list
887 or hash references (in array context) that contains information about each
888 of the header fields in the compressed data stream(s).
889
890 =over 5
891
892 =item Name
893
894 The contents of the Name header field, if present. If no name is
895 present, the value will be undef. Note this is different from a zero length
896 name, which will return an empty string.
897
898 =item Comment
899
900 The contents of the Comment header field, if present. If no comment is
901 present, the value will be undef. Note this is different from a zero length
902 comment, which will return an empty string.
903
904 =back
905
906 =head2 tell
907
908 Usage is
909
910     $z->tell()
911     tell $z
912
913 Returns the uncompressed file offset.
914
915 =head2 eof
916
917 Usage is
918
919     $z->eof();
920     eof($z);
921
922 Returns true if the end of the compressed input stream has been reached.
923
924 =head2 seek
925
926     $z->seek($position, $whence);
927     seek($z, $position, $whence);
928
929 Provides a sub-set of the C<seek> functionality, with the restriction
930 that it is only legal to seek forward in the input file/buffer.
931 It is a fatal error to attempt to seek backward.
932
933 Note that the implementation of C<seek> in this module does not provide
934 true random access to a compressed file/buffer. It  works by uncompressing
935 data from the current offset in the file/buffer until it reaches the
936 uncompressed offset specified in the parameters to C<seek>. For very small
937 files this may be acceptable behaviour. For large files it may cause an
938 unacceptable delay.
939
940 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
941 SEEK_CUR or SEEK_END.
942
943 Returns 1 on success, 0 on failure.
944
945 =head2 binmode
946
947 Usage is
948
949     $z->binmode
950     binmode $z ;
951
952 This is a noop provided for completeness.
953
954 =head2 opened
955
956     $z->opened()
957
958 Returns true if the object currently refers to a opened file/buffer. 
959
960 =head2 autoflush
961
962     my $prev = $z->autoflush()
963     my $prev = $z->autoflush(EXPR)
964
965 If the C<$z> object is associated with a file or a filehandle, this method
966 returns the current autoflush setting for the underlying filehandle. If
967 C<EXPR> is present, and is non-zero, it will enable flushing after every
968 write/print operation.
969
970 If C<$z> is associated with a buffer, this method has no effect and always
971 returns C<undef>.
972
973 B<Note> that the special variable C<$|> B<cannot> be used to set or
974 retrieve the autoflush setting.
975
976 =head2 input_line_number
977
978     $z->input_line_number()
979     $z->input_line_number(EXPR)
980
981 Returns the current uncompressed line number. If C<EXPR> is present it has
982 the effect of setting the line number. Note that setting the line number
983 does not change the current position within the file/buffer being read.
984
985 The contents of C<$/> are used to determine what constitutes a line
986 terminator.
987
988 =head2 fileno
989
990     $z->fileno()
991     fileno($z)
992
993 If the C<$z> object is associated with a file or a filehandle, C<fileno>
994 will return the underlying file descriptor. Once the C<close> method is
995 called C<fileno> will return C<undef>.
996
997 If the C<$z> object is associated with a buffer, this method will return
998 C<undef>.
999
1000 =head2 close
1001
1002     $z->close() ;
1003     close $z ;
1004
1005 Closes the output file/buffer. 
1006
1007 For most versions of Perl this method will be automatically invoked if
1008 the IO::Uncompress::Gunzip object is destroyed (either explicitly or by the
1009 variable with the reference to the object going out of scope). The
1010 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
1011 these cases, the C<close> method will be called automatically, but
1012 not until global destruction of all live objects when the program is
1013 terminating.
1014
1015 Therefore, if you want your scripts to be able to run on all versions
1016 of Perl, you should call C<close> explicitly and not rely on automatic
1017 closing.
1018
1019 Returns true on success, otherwise 0.
1020
1021 If the C<AutoClose> option has been enabled when the IO::Uncompress::Gunzip
1022 object was created, and the object is associated with a file, the
1023 underlying file will also be closed.
1024
1025 =head2 nextStream
1026
1027 Usage is
1028
1029     my $status = $z->nextStream();
1030
1031 Skips to the next compressed data stream in the input file/buffer. If a new
1032 compressed data stream is found, the eof marker will be cleared and C<$.>
1033 will be reset to 0.
1034
1035 Returns 1 if a new stream was found, 0 if none was found, and -1 if an
1036 error was encountered.
1037
1038 =head2 trailingData
1039
1040 Usage is
1041
1042     my $data = $z->trailingData();
1043
1044 Returns the data, if any, that is present immediately after the compressed
1045 data stream once uncompression is complete. It only makes sense to call
1046 this method once the end of the compressed data stream has been
1047 encountered.
1048
1049 This option can be used when there is useful information immediately
1050 following the compressed data stream, and you don't know the length of the
1051 compressed data stream.
1052
1053 If the input is a buffer, C<trailingData> will return everything from the
1054 end of the compressed data stream to the end of the buffer.
1055
1056 If the input is a filehandle, C<trailingData> will return the data that is
1057 left in the filehandle input buffer once the end of the compressed data
1058 stream has been reached. You can then use the filehandle to read the rest
1059 of the input file. 
1060
1061 Don't bother using C<trailingData> if the input is a filename.
1062
1063 If you know the length of the compressed data stream before you start
1064 uncompressing, you can avoid having to use C<trailingData> by setting the
1065 C<InputLength> option in the constructor.
1066
1067 =head1 Importing 
1068
1069 No symbolic constants are required by this IO::Uncompress::Gunzip at present. 
1070
1071 =over 5
1072
1073 =item :all
1074
1075 Imports C<gunzip> and C<$GunzipError>.
1076 Same as doing this
1077
1078     use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
1079
1080 =back
1081
1082 =head1 EXAMPLES
1083
1084 =head2 Working with Net::FTP
1085
1086 See L<IO::Compress::FAQ|IO::Compress::FAQ/"Compressed files and Net::FTP">
1087
1088 =head1 SEE ALSO
1089
1090 L<Compress::Zlib>, L<IO::Compress::Gzip>, L<IO::Compress::Deflate>, L<IO::Uncompress::Inflate>, L<IO::Compress::RawDeflate>, L<IO::Uncompress::RawInflate>, L<IO::Compress::Bzip2>, L<IO::Uncompress::Bunzip2>, L<IO::Compress::Lzma>, L<IO::Uncompress::UnLzma>, L<IO::Compress::Xz>, L<IO::Uncompress::UnXz>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
1091
1092 L<IO::Compress::FAQ|IO::Compress::FAQ>
1093
1094 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1095 L<Archive::Tar|Archive::Tar>,
1096 L<IO::Zlib|IO::Zlib>
1097
1098 For RFC 1950, 1951 and 1952 see 
1099 F<http://www.faqs.org/rfcs/rfc1950.html>,
1100 F<http://www.faqs.org/rfcs/rfc1951.html> and
1101 F<http://www.faqs.org/rfcs/rfc1952.html>
1102
1103 The I<zlib> compression library was written by Jean-loup Gailly
1104 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1105
1106 The primary site for the I<zlib> compression library is
1107 F<http://www.zlib.org>.
1108
1109 The primary site for gzip is F<http://www.gzip.org>.
1110
1111 =head1 AUTHOR
1112
1113 This module was written by Paul Marquess, F<pmqs@cpan.org>. 
1114
1115 =head1 MODIFICATION HISTORY
1116
1117 See the Changes file.
1118
1119 =head1 COPYRIGHT AND LICENSE
1120
1121 Copyright (c) 2005-2015 Paul Marquess. All rights reserved.
1122
1123 This program is free software; you can redistribute it and/or
1124 modify it under the same terms as Perl itself.
1125