cpan/IO-Compress/lib/IO/Uncompress/AnyUncompress.pm

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