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