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