ext/IO_Compress_Zlib/lib/IO/Uncompress/RawInflate.pm

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