"Fossies" - the Fresh Open Source Software Archive

Member "install-tl-20200916/tlpkg/tlperl/lib/IO/Uncompress/AnyUncompress.pm" (7 Mar 2020, 30622 Bytes) of package /windows/misc/install-tl.zip:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) Perl source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file.

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