"Fossies" - the Fresh Open Source Software Archive

Member "IO-Compress-2.093/lib/IO/Uncompress/AnyUncompress.pm" (7 Dec 2019, 31011 Bytes) of package /linux/privat/IO-Compress-2.093.tar.gz:


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. For more information about "AnyUncompress.pm" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 2.092_vs_2.093.

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