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.004 qw(createSelfTiedObject);
  10
  11 use IO::Uncompress::Adapter::Inflate  2.004 ();
  12
  13
  14 use IO::Uncompress::Base  2.004 ;
  15 use IO::Uncompress::Gunzip  2.004 ;
  16 use IO::Uncompress::Inflate  2.004 ;
  17 use IO::Uncompress::RawInflate  2.004 ;
  18 use IO::Uncompress::Unzip  2.004 ;
  19
  20 require Exporter ;
  21
  22 our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $AnyInflateError);
  23
  24 $VERSION = '2.004';
  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.004 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/buffer is not compressed data,
 572 the module will allow reading of it anyway.
 573
 574 In addition, if the input file/buffer does contain compressed data and
 575 there is non-compressed data immediately following it, setting this option
 576 will make this module treat the whole file/bufffer as a single data stream.
 577
 578 This option defaults to 1.
 579
 580 =item C<< BlockSize => $num >>
 581
 582 When reading the compressed input data, IO::Uncompress::AnyInflate will read it in
 583 blocks of C<$num> bytes.
 584
 585 This option defaults to 4096.
 586
 587 =item C<< InputLength => $size >>
 588
 589 When present this option will limit the number of compressed bytes read
 590 from the input file/buffer to C<$size>. This option can be used in the
 591 situation where there is useful data directly after the compressed data
 592 stream and you know beforehand the exact length of the compressed data
 593 stream.
 594
 595 This option is mostly used when reading from a filehandle, in which case
 596 the file pointer will be left pointing to the first byte directly after the
 597 compressed data stream.
 598
 599
 600
 601 This option defaults to off.
 602
 603 =item C<< Append => 0|1 >>
 604
 605 This option controls what the C<read> method does with uncompressed data.
 606
 607 If set to 1, all uncompressed data will be appended to the output parameter
 608 of the C<read> method.
 609
 610 If set to 0, the contents of the output parameter of the C<read> method
 611 will be overwritten by the uncompressed data.
 612
 613 Defaults to 0.
 614
 615 =item C<< Strict => 0|1 >>
 616
 617
 618
 619 This option controls whether the extra checks defined below are used when
 620 carrying out the decompression. When Strict is on, the extra tests are
 621 carried out, when Strict is off they are not.
 622
 623 The default for this option is off.
 624
 625
 626 If the input is an RFC 1950 data stream, the following will be checked:
 627
 628
 629
 630
 631 =over 5
 632
 633 =item 1
 634
 635 The ADLER32 checksum field must be present.
 636
 637 =item 2
 638
 639 The value of the ADLER32 field read must match the adler32 value of the
 640 uncompressed data actually contained in the file.
 641
 642 =back
 643
 644
 645
 646 If the input is a gzip (RFC 1952) data stream, the following will be checked:
 647
 648
 649
 650
 651 =over 5
 652
 653 =item 1
 654
 655 If the FHCRC bit is set in the gzip FLG header byte, the CRC16 bytes in the
 656 header must match the crc16 value of the gzip header actually read.
 657
 658 =item 2
 659
 660 If the gzip header contains a name field (FNAME) it consists solely of ISO
 661 8859-1 characters.
 662
 663 =item 3
 664
 665 If the gzip header contains a comment field (FCOMMENT) it consists solely
 666 of ISO 8859-1 characters plus line-feed.
 667
 668 =item 4
 669
 670 If the gzip FEXTRA header field is present it must conform to the sub-field
 671 structure as defined in RFC 1952.
 672
 673 =item 5
 674
 675 The CRC32 and ISIZE trailer fields must be present.
 676
 677 =item 6
 678
 679 The value of the CRC32 field read must match the crc32 value of the
 680 uncompressed data actually contained in the gzip file.
 681
 682 =item 7
 683
 684 The value of the ISIZE fields read must match the length of the
 685 uncompressed data actually read from the file.
 686
 687 =back
 688
 689
 690
 691
 692
 693 =item C<< RawInflate => 0|1 >>
 694
 695 When auto-detecting the compressed format, try to test for raw-deflate (RFC
 696 1951) content using the C<IO::Uncompress::RawInflate> module.
 697
 698 The reason this is not default behaviour is because RFC 1951 content can
 699 only be detected by attempting to uncompress it. This process is error
 700 prone and can result is false positives.
 701
 702 Defaults to 0.
 703
 704
 705
 706
 707 =item C<< ParseExtra => 0|1 >>
 708 If the gzip FEXTRA header field is present and this option is set, it will
 709 force the module to check that it conforms to the sub-field structure as
 710 defined in RFC 1952.
 711
 712 If the C<Strict> is on it will automatically enable this option.
 713
 714 Defaults to 0.
 715
 716
 717
 718
 719 =back
 720
 721 =head2 Examples
 722
 723 TODO
 724
 725 =head1 Methods
 726
 727 =head2 read
 728
 729 Usage is
 730
 731     $status = $z->read($buffer)
 732
 733 Reads a block of compressed data (the size the the compressed block is
 734 determined by the C<Buffer> option in the constructor), uncompresses it and
 735 writes any uncompressed data into C<$buffer>. If the C<Append> parameter is
 736 set in the constructor, the uncompressed data will be appended to the
 737 C<$buffer> parameter. Otherwise C<$buffer> will be overwritten.
 738
 739 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
 740 or a negative number on error.
 741
 742 =head2 read
 743
 744 Usage is
 745
 746     $status = $z->read($buffer, $length)
 747     $status = $z->read($buffer, $length, $offset)
 748
 749     $status = read($z, $buffer, $length)
 750     $status = read($z, $buffer, $length, $offset)
 751
 752 Attempt to read C<$length> bytes of uncompressed data into C<$buffer>.
 753
 754 The main difference between this form of the C<read> method and the
 755 previous one, is that this one will attempt to return I<exactly> C<$length>
 756 bytes. The only circumstances that this function will not is if end-of-file
 757 or an IO error is encountered.
 758
 759 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
 760 or a negative number on error.
 761
 762
 763 =head2 getline
 764
 765 Usage is
 766
 767     $line = $z->getline()
 768     $line = <$z>
 769
 770 Reads a single line.
 771
 772 This method fully supports the use of of the variable C<$/> (or
 773 C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use) to
 774 determine what constitutes an end of line. Paragraph mode, record mode and
 775 file slurp mode are all supported.
 776
 777
 778 =head2 getc
 779
 780 Usage is
 781
 782     $char = $z->getc()
 783
 784 Read a single character.
 785
 786 =head2 ungetc
 787
 788 Usage is
 789
 790     $char = $z->ungetc($string)
 791
 792
 793
 794 =head2 inflateSync
 795
 796 Usage is
 797
 798     $status = $z->inflateSync()
 799
 800 TODO
 801
 802
 803 =head2 getHeaderInfo
 804
 805 Usage is
 806
 807     $hdr  = $z->getHeaderInfo();
 808     @hdrs = $z->getHeaderInfo();
 809
 810 This method returns either a hash reference (in scalar context) or a list
 811 or hash references (in array context) that contains information about each
 812 of the header fields in the compressed data stream(s).
 813
 814
 815
 816
 817 =head2 tell
 818
 819 Usage is
 820
 821     $z->tell()
 822     tell $z
 823
 824 Returns the uncompressed file offset.
 825
 826 =head2 eof
 827
 828 Usage is
 829
 830     $z->eof();
 831     eof($z);
 832
 833
 834
 835 Returns true if the end of the compressed input stream has been reached.
 836
 837
 838
 839 =head2 seek
 840
 841     $z->seek($position, $whence);
 842     seek($z, $position, $whence);
 843
 844
 845
 846
 847 Provides a sub-set of the C<seek> functionality, with the restriction
 848 that it is only legal to seek forward in the input file/buffer.
 849 It is a fatal error to attempt to seek backward.
 850
 851
 852
 853 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
 854 SEEK_CUR or SEEK_END.
 855
 856 Returns 1 on success, 0 on failure.
 857
 858 =head2 binmode
 859
 860 Usage is
 861
 862     $z->binmode
 863     binmode $z ;
 864
 865 This is a noop provided for completeness.
 866
 867 =head2 opened
 868
 869     $z->opened()
 870
 871 Returns true if the object currently refers to a opened file/buffer.
 872
 873 =head2 autoflush
 874
 875     my $prev = $z->autoflush()
 876     my $prev = $z->autoflush(EXPR)
 877
 878 If the C<$z> object is associated with a file or a filehandle, this method
 879 returns the current autoflush setting for the underlying filehandle. If
 880 C<EXPR> is present, and is non-zero, it will enable flushing after every
 881 write/print operation.
 882
 883 If C<$z> is associated with a buffer, this method has no effect and always
 884 returns C<undef>.
 885
 886 B<Note> that the special variable C<$|> B<cannot> be used to set or
 887 retrieve the autoflush setting.
 888
 889 =head2 input_line_number
 890
 891     $z->input_line_number()
 892     $z->input_line_number(EXPR)
 893
 894
 895
 896 Returns the current uncompressed line number. If C<EXPR> is present it has
 897 the effect of setting the line number. Note that setting the line number
 898 does not change the current position within the file/buffer being read.
 899
 900 The contents of C<$/> are used to to determine what constitutes a line
 901 terminator.
 902
 903
 904
 905 =head2 fileno
 906
 907     $z->fileno()
 908     fileno($z)
 909
 910 If the C<$z> object is associated with a file or a filehandle, this method
 911 will return the underlying file descriptor.
 912
 913 If the C<$z> object is is associated with a buffer, this method will
 914 return undef.
 915
 916 =head2 close
 917
 918     $z->close() ;
 919     close $z ;
 920
 921
 922
 923 Closes the output file/buffer.
 924
 925
 926
 927 For most versions of Perl this method will be automatically invoked if
 928 the IO::Uncompress::AnyInflate object is destroyed (either explicitly or by the
 929 variable with the reference to the object going out of scope). The
 930 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
 931 these cases, the C<close> method will be called automatically, but
 932 not until global destruction of all live objects when the program is
 933 terminating.
 934
 935 Therefore, if you want your scripts to be able to run on all versions
 936 of Perl, you should call C<close> explicitly and not rely on automatic
 937 closing.
 938
 939 Returns true on success, otherwise 0.
 940
 941 If the C<AutoClose> option has been enabled when the IO::Uncompress::AnyInflate
 942 object was created, and the object is associated with a file, the
 943 underlying file will also be closed.
 944
 945
 946
 947
 948 =head2 nextStream
 949
 950 Usage is
 951
 952     my $status = $z->nextStream();
 953
 954 Skips to the next compressed data stream in the input file/buffer. If a new
 955 compressed data stream is found, the eof marker will be cleared and C<$.>
 956 will be reset to 0.
 957
 958 Returns 1 if a new stream was found, 0 if none was found, and -1 if an
 959 error was encountered.
 960
 961 =head2 trailingData
 962
 963 Usage is
 964
 965     my $data = $z->trailingData();
 966
 967 Returns the data, if any, that is present immediately after the compressed
 968 data stream once uncompression is complete. It only makes sense to call
 969 this method once the end of the compressed data stream has been
 970 encountered.
 971
 972 This option can be used when there is useful information immediately
 973 following the compressed data stream, and you don't know the length of the
 974 compressed data stream.
 975
 976 If the input is a buffer, C<trailingData> will return everything from the
 977 end of the compressed data stream to the end of the buffer.
 978
 979 If the input is a filehandle, C<trailingData> will return the data that is
 980 left in the filehandle input buffer once the end of the compressed data
 981 stream has been reached. You can then use the filehandle to read the rest
 982 of the input file.
 983
 984 Don't bother using C<trailingData> if the input is a filename.
 985
 986
 987
 988 If you know the length of the compressed data stream before you start
 989 uncompressing, you can avoid having to use C<trailingData> by setting the
 990 C<InputLength> option in the constructor.
 991
 992 =head1 Importing
 993
 994 No symbolic constants are required by this IO::Uncompress::AnyInflate at present.
 995
 996 =over 5
 997
 998 =item :all
 999
1000 Imports C<anyinflate> and C<$AnyInflateError>.
1001 Same as doing this
1002
1003     use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;
1004
1005 =back
1006
1007 =head1 EXAMPLES
1008
1009
1010
1011
1012 =head1 SEE ALSO
1013
1014 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>
1015
1016 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1017
1018 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1019 L<Archive::Tar|Archive::Tar>,
1020 L<IO::Zlib|IO::Zlib>
1021
1022
1023 For RFC 1950, 1951 and 1952 see
1024 F<http://www.faqs.org/rfcs/rfc1950.html>,
1025 F<http://www.faqs.org/rfcs/rfc1951.html> and
1026 F<http://www.faqs.org/rfcs/rfc1952.html>
1027
1028 The I<zlib> compression library was written by Jean-loup Gailly
1029 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1030
1031 The primary site for the I<zlib> compression library is
1032 F<http://www.zlib.org>.
1033
1034 The primary site for gzip is F<http://www.gzip.org>.
1035
1036
1037
1038
1039 =head1 AUTHOR
1040
1041 This module was written by Paul Marquess, F<pmqs@cpan.org>.
1042
1043
1044
1045 =head1 MODIFICATION HISTORY
1046
1047 See the Changes file.
1048
1049 =head1 COPYRIGHT AND LICENSE
1050
1051 Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
1052
1053 This program is free software; you can redistribute it and/or
1054 modify it under the same terms as Perl itself.
1055