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