ext/Compress/IO/Zlib/lib/IO/Uncompress/AnyInflate.pm

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