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

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