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