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