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