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.009 ;
   9 use IO::Compress::Base::Common  2.009 qw(:Status createSelfTiedObject);
  10
  11 use IO::Uncompress::Base  2.009 ;
  12 use IO::Uncompress::Adapter::Inflate  2.009 ;
  13
  14
  15
  16
  17 require Exporter ;
  18 our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, %DEFLATE_CONSTANTS, $RawInflateError);
  19
  20 $VERSION = '2.009';
  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 IO::Uncompress::RawInflate - Read RFC 1951 files/buffers
 335
 336 =head1 SYNOPSIS
 337
 338     use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
 339
 340     my $status = rawinflate $input => $output [,OPTS]
 341         or die "rawinflate failed: $RawInflateError\n";
 342
 343     my $z = new IO::Uncompress::RawInflate $input [OPTS]
 344         or die "rawinflate failed: $RawInflateError\n";
 345
 346     $status = $z->read($buffer)
 347     $status = $z->read($buffer, $length)
 348     $status = $z->read($buffer, $length, $offset)
 349     $line = $z->getline()
 350     $char = $z->getc()
 351     $char = $z->ungetc()
 352     $char = $z->opened()
 353
 354     $status = $z->inflateSync()
 355
 356     $data = $z->trailingData()
 357     $status = $z->nextStream()
 358     $data = $z->getHeaderInfo()
 359     $z->tell()
 360     $z->seek($position, $whence)
 361     $z->binmode()
 362     $z->fileno()
 363     $z->eof()
 364     $z->close()
 365
 366     $RawInflateError ;
 367
 368     # IO::File mode
 369
 370     <$z>
 371     read($z, $buffer);
 372     read($z, $buffer, $length);
 373     read($z, $buffer, $length, $offset);
 374     tell($z)
 375     seek($z, $position, $whence)
 376     binmode($z)
 377     fileno($z)
 378     eof($z)
 379     close($z)
 380
 381 =head1 DESCRIPTION
 382
 383 This module provides a Perl interface that allows the reading of
 384 files/buffers that conform to RFC 1951.
 385
 386 For writing RFC 1951 files/buffers, see the companion module IO::Compress::RawDeflate.
 387
 388 =head1 Functional Interface
 389
 390 A top-level function, C<rawinflate>, is provided to carry out
 391 "one-shot" uncompression between buffers and/or files. For finer
 392 control over the uncompression process, see the L</"OO Interface">
 393 section.
 394
 395     use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
 396
 397     rawinflate $input => $output [,OPTS]
 398         or die "rawinflate failed: $RawInflateError\n";
 399
 400 The functional interface needs Perl5.005 or better.
 401
 402 =head2 rawinflate $input => $output [, OPTS]
 403
 404 C<rawinflate> expects at least two parameters, C<$input> and C<$output>.
 405
 406 =head3 The C<$input> parameter
 407
 408 The parameter, C<$input>, is used to define the source of
 409 the compressed data.
 410
 411 It can take one of the following forms:
 412
 413 =over 5
 414
 415 =item A filename
 416
 417 If the C<$input> parameter is a simple scalar, it is assumed to be a
 418 filename. This file will be opened for reading and the input data
 419 will be read from it.
 420
 421 =item A filehandle
 422
 423 If the C<$input> parameter is a filehandle, the input data will be
 424 read from it.
 425 The string '-' can be used as an alias for standard input.
 426
 427 =item A scalar reference
 428
 429 If C<$input> is a scalar reference, the input data will be read
 430 from C<$$input>.
 431
 432 =item An array reference
 433
 434 If C<$input> is an array reference, each element in the array must be a
 435 filename.
 436
 437 The input data will be read from each file in turn.
 438
 439 The complete array will be walked to ensure that it only
 440 contains valid filenames before any data is uncompressed.
 441
 442 =item An Input FileGlob string
 443
 444 If C<$input> is a string that is delimited by the characters "<" and ">"
 445 C<rawinflate> will assume that it is an I<input fileglob string>. The
 446 input is the list of files that match the fileglob.
 447
 448 If the fileglob does not match any files ...
 449
 450 See L<File::GlobMapper|File::GlobMapper> for more details.
 451
 452 =back
 453
 454 If the C<$input> parameter is any other type, C<undef> will be returned.
 455
 456 =head3 The C<$output> parameter
 457
 458 The parameter C<$output> is used to control the destination of the
 459 uncompressed data. This parameter can take one of these forms.
 460
 461 =over 5
 462
 463 =item A filename
 464
 465 If the C<$output> parameter is a simple scalar, it is assumed to be a
 466 filename.  This file will be opened for writing and the uncompressed
 467 data will be written to it.
 468
 469 =item A filehandle
 470
 471 If the C<$output> parameter is a filehandle, the uncompressed data
 472 will be written to it.
 473 The string '-' can be used as an alias for standard output.
 474
 475 =item A scalar reference
 476
 477 If C<$output> is a scalar reference, the uncompressed data will be
 478 stored in C<$$output>.
 479
 480 =item An Array Reference
 481
 482 If C<$output> is an array reference, the uncompressed data will be
 483 pushed onto the array.
 484
 485 =item An Output FileGlob
 486
 487 If C<$output> is a string that is delimited by the characters "<" and ">"
 488 C<rawinflate> will assume that it is an I<output fileglob string>. The
 489 output is the list of files that match the fileglob.
 490
 491 When C<$output> is an fileglob string, C<$input> must also be a fileglob
 492 string. Anything else is an error.
 493
 494 =back
 495
 496 If the C<$output> parameter is any other type, C<undef> will be returned.
 497
 498 =head2 Notes
 499
 500 When C<$input> maps to multiple compressed files/buffers and C<$output> is
 501 a single file/buffer, after uncompression C<$output> will contain a
 502 concatenation of all the uncompressed data from each of the input
 503 files/buffers.
 504
 505 =head2 Optional Parameters
 506
 507 Unless specified below, the optional parameters for C<rawinflate>,
 508 C<OPTS>, are the same as those used with the OO interface defined in the
 509 L</"Constructor Options"> section below.
 510
 511 =over 5
 512
 513 =item C<< AutoClose => 0|1 >>
 514
 515 This option applies to any input or output data streams to
 516 C<rawinflate> that are filehandles.
 517
 518 If C<AutoClose> is specified, and the value is true, it will result in all
 519 input and/or output filehandles being closed once C<rawinflate> has
 520 completed.
 521
 522 This parameter defaults to 0.
 523
 524 =item C<< BinModeOut => 0|1 >>
 525
 526 When writing to a file or filehandle, set C<binmode> before writing to the
 527 file.
 528
 529 Defaults to 0.
 530
 531 =item C<< Append => 0|1 >>
 532
 533 TODO
 534
 535 =item C<< MultiStream => 0|1 >>
 536
 537 This option is a no-op.
 538
 539 =item C<< TrailingData => $scalar >>
 540
 541 Returns the data, if any, that is present immediately after the compressed
 542 data stream once uncompression is complete.
 543
 544 This option can be used when there is useful information immediately
 545 following the compressed data stream, and you don't know the length of the
 546 compressed data stream.
 547
 548 If the input is a buffer, C<trailingData> will return everything from the
 549 end of the compressed data stream to the end of the buffer.
 550
 551 If the input is a filehandle, C<trailingData> will return the data that is
 552 left in the filehandle input buffer once the end of the compressed data
 553 stream has been reached. You can then use the filehandle to read the rest
 554 of the input file.
 555
 556 Don't bother using C<trailingData> if the input is a filename.
 557
 558 If you know the length of the compressed data stream before you start
 559 uncompressing, you can avoid having to use C<trailingData> by setting the
 560 C<InputLength> option.
 561
 562 =back
 563
 564 =head2 Examples
 565
 566 To read the contents of the file C<file1.txt.1951> and write the
 567 compressed data to the file C<file1.txt>.
 568
 569     use strict ;
 570     use warnings ;
 571     use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
 572
 573     my $input = "file1.txt.1951";
 574     my $output = "file1.txt";
 575     rawinflate $input => $output
 576         or die "rawinflate failed: $RawInflateError\n";
 577
 578 To read from an existing Perl filehandle, C<$input>, and write the
 579 uncompressed data to a buffer, C<$buffer>.
 580
 581     use strict ;
 582     use warnings ;
 583     use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
 584     use IO::File ;
 585
 586     my $input = new IO::File "<file1.txt.1951"
 587         or die "Cannot open 'file1.txt.1951': $!\n" ;
 588     my $buffer ;
 589     rawinflate $input => \$buffer
 590         or die "rawinflate failed: $RawInflateError\n";
 591
 592 To uncompress all files in the directory "/my/home" that match "*.txt.1951" and store the compressed data in the same directory
 593
 594     use strict ;
 595     use warnings ;
 596     use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
 597
 598     rawinflate '</my/home/*.txt.1951>' => '</my/home/#1.txt>'
 599         or die "rawinflate failed: $RawInflateError\n";
 600
 601 and if you want to compress each file one at a time, this will do the trick
 602
 603     use strict ;
 604     use warnings ;
 605     use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
 606
 607     for my $input ( glob "/my/home/*.txt.1951" )
 608     {
 609         my $output = $input;
 610         $output =~ s/.1951// ;
 611         rawinflate $input => $output
 612             or die "Error compressing '$input': $RawInflateError\n";
 613     }
 614
 615 =head1 OO Interface
 616
 617 =head2 Constructor
 618
 619 The format of the constructor for IO::Uncompress::RawInflate is shown below
 620
 621     my $z = new IO::Uncompress::RawInflate $input [OPTS]
 622         or die "IO::Uncompress::RawInflate failed: $RawInflateError\n";
 623
 624 Returns an C<IO::Uncompress::RawInflate> object on success and undef on failure.
 625 The variable C<$RawInflateError> will contain an error message on failure.
 626
 627 If you are running Perl 5.005 or better the object, C<$z>, returned from
 628 IO::Uncompress::RawInflate can be used exactly like an L<IO::File|IO::File> filehandle.
 629 This means that all normal input file operations can be carried out with
 630 C<$z>.  For example, to read a line from a compressed file/buffer you can
 631 use either of these forms
 632
 633     $line = $z->getline();
 634     $line = <$z>;
 635
 636 The mandatory parameter C<$input> is used to determine the source of the
 637 compressed data. This parameter can take one of three forms.
 638
 639 =over 5
 640
 641 =item A filename
 642
 643 If the C<$input> parameter is a scalar, it is assumed to be a filename. This
 644 file will be opened for reading and the compressed data will be read from it.
 645
 646 =item A filehandle
 647
 648 If the C<$input> parameter is a filehandle, the compressed data will be
 649 read from it.
 650 The string '-' can be used as an alias for standard input.
 651
 652 =item A scalar reference
 653
 654 If C<$input> is a scalar reference, the compressed data will be read from
 655 C<$$output>.
 656
 657 =back
 658
 659 =head2 Constructor Options
 660
 661 The option names defined below are case insensitive and can be optionally
 662 prefixed by a '-'.  So all of the following are valid
 663
 664     -AutoClose
 665     -autoclose
 666     AUTOCLOSE
 667     autoclose
 668
 669 OPTS is a combination of the following options:
 670
 671 =over 5
 672
 673 =item C<< AutoClose => 0|1 >>
 674
 675 This option is only valid when the C<$input> parameter is a filehandle. If
 676 specified, and the value is true, it will result in the file being closed once
 677 either the C<close> method is called or the IO::Uncompress::RawInflate object is
 678 destroyed.
 679
 680 This parameter defaults to 0.
 681
 682 =item C<< MultiStream => 0|1 >>
 683
 684 Allows multiple concatenated compressed streams to be treated as a single
 685 compressed stream. Decompression will stop once either the end of the
 686 file/buffer is reached, an error is encountered (premature eof, corrupt
 687 compressed data) or the end of a stream is not immediately followed by the
 688 start of another stream.
 689
 690 This parameter defaults to 0.
 691
 692 =item C<< Prime => $string >>
 693
 694 This option will uncompress the contents of C<$string> before processing the
 695 input file/buffer.
 696
 697 This option can be useful when the compressed data is embedded in another
 698 file/data structure and it is not possible to work out where the compressed
 699 data begins without having to read the first few bytes. If this is the
 700 case, the uncompression can be I<primed> with these bytes using this
 701 option.
 702
 703 =item C<< Transparent => 0|1 >>
 704
 705 If this option is set and the input file/buffer is not compressed data,
 706 the module will allow reading of it anyway.
 707
 708 In addition, if the input file/buffer does contain compressed data and
 709 there is non-compressed data immediately following it, setting this option
 710 will make this module treat the whole file/bufffer as a single data stream.
 711
 712 This option defaults to 1.
 713
 714 =item C<< BlockSize => $num >>
 715
 716 When reading the compressed input data, IO::Uncompress::RawInflate will read it in
 717 blocks of C<$num> bytes.
 718
 719 This option defaults to 4096.
 720
 721 =item C<< InputLength => $size >>
 722
 723 When present this option will limit the number of compressed bytes read
 724 from the input file/buffer to C<$size>. This option can be used in the
 725 situation where there is useful data directly after the compressed data
 726 stream and you know beforehand the exact length of the compressed data
 727 stream.
 728
 729 This option is mostly used when reading from a filehandle, in which case
 730 the file pointer will be left pointing to the first byte directly after the
 731 compressed data stream.
 732
 733 This option defaults to off.
 734
 735 =item C<< Append => 0|1 >>
 736
 737 This option controls what the C<read> method does with uncompressed data.
 738
 739 If set to 1, all uncompressed data will be appended to the output parameter
 740 of the C<read> method.
 741
 742 If set to 0, the contents of the output parameter of the C<read> method
 743 will be overwritten by the uncompressed data.
 744
 745 Defaults to 0.
 746
 747 =item C<< Strict => 0|1 >>
 748
 749 This option is a no-op.
 750
 751 =back
 752
 753 =head2 Examples
 754
 755 TODO
 756
 757 =head1 Methods
 758
 759 =head2 read
 760
 761 Usage is
 762
 763     $status = $z->read($buffer)
 764
 765 Reads a block of compressed data (the size the the compressed block is
 766 determined by the C<Buffer> option in the constructor), uncompresses it and
 767 writes any uncompressed data into C<$buffer>. If the C<Append> parameter is
 768 set in the constructor, the uncompressed data will be appended to the
 769 C<$buffer> parameter. Otherwise C<$buffer> will be overwritten.
 770
 771 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
 772 or a negative number on error.
 773
 774 =head2 read
 775
 776 Usage is
 777
 778     $status = $z->read($buffer, $length)
 779     $status = $z->read($buffer, $length, $offset)
 780
 781     $status = read($z, $buffer, $length)
 782     $status = read($z, $buffer, $length, $offset)
 783
 784 Attempt to read C<$length> bytes of uncompressed data into C<$buffer>.
 785
 786 The main difference between this form of the C<read> method and the
 787 previous one, is that this one will attempt to return I<exactly> C<$length>
 788 bytes. The only circumstances that this function will not is if end-of-file
 789 or an IO error is encountered.
 790
 791 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
 792 or a negative number on error.
 793
 794 =head2 getline
 795
 796 Usage is
 797
 798     $line = $z->getline()
 799     $line = <$z>
 800
 801 Reads a single line.
 802
 803 This method fully supports the use of of the variable C<$/> (or
 804 C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use) to
 805 determine what constitutes an end of line. Paragraph mode, record mode and
 806 file slurp mode are all supported.
 807
 808 =head2 getc
 809
 810 Usage is
 811
 812     $char = $z->getc()
 813
 814 Read a single character.
 815
 816 =head2 ungetc
 817
 818 Usage is
 819
 820     $char = $z->ungetc($string)
 821
 822 =head2 inflateSync
 823
 824 Usage is
 825
 826     $status = $z->inflateSync()
 827
 828 TODO
 829
 830 =head2 getHeaderInfo
 831
 832 Usage is
 833
 834     $hdr  = $z->getHeaderInfo();
 835     @hdrs = $z->getHeaderInfo();
 836
 837 This method returns either a hash reference (in scalar context) or a list
 838 or hash references (in array context) that contains information about each
 839 of the header fields in the compressed data stream(s).
 840
 841 =head2 tell
 842
 843 Usage is
 844
 845     $z->tell()
 846     tell $z
 847
 848 Returns the uncompressed file offset.
 849
 850 =head2 eof
 851
 852 Usage is
 853
 854     $z->eof();
 855     eof($z);
 856
 857 Returns true if the end of the compressed input stream has been reached.
 858
 859 =head2 seek
 860
 861     $z->seek($position, $whence);
 862     seek($z, $position, $whence);
 863
 864 Provides a sub-set of the C<seek> functionality, with the restriction
 865 that it is only legal to seek forward in the input file/buffer.
 866 It is a fatal error to attempt to seek backward.
 867
 868 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
 869 SEEK_CUR or SEEK_END.
 870
 871 Returns 1 on success, 0 on failure.
 872
 873 =head2 binmode
 874
 875 Usage is
 876
 877     $z->binmode
 878     binmode $z ;
 879
 880 This is a noop provided for completeness.
 881
 882 =head2 opened
 883
 884     $z->opened()
 885
 886 Returns true if the object currently refers to a opened file/buffer.
 887
 888 =head2 autoflush
 889
 890     my $prev = $z->autoflush()
 891     my $prev = $z->autoflush(EXPR)
 892
 893 If the C<$z> object is associated with a file or a filehandle, this method
 894 returns the current autoflush setting for the underlying filehandle. If
 895 C<EXPR> is present, and is non-zero, it will enable flushing after every
 896 write/print operation.
 897
 898 If C<$z> is associated with a buffer, this method has no effect and always
 899 returns C<undef>.
 900
 901 B<Note> that the special variable C<$|> B<cannot> be used to set or
 902 retrieve the autoflush setting.
 903
 904 =head2 input_line_number
 905
 906     $z->input_line_number()
 907     $z->input_line_number(EXPR)
 908
 909 Returns the current uncompressed line number. If C<EXPR> is present it has
 910 the effect of setting the line number. Note that setting the line number
 911 does not change the current position within the file/buffer being read.
 912
 913 The contents of C<$/> are used to to determine what constitutes a line
 914 terminator.
 915
 916 =head2 fileno
 917
 918     $z->fileno()
 919     fileno($z)
 920
 921 If the C<$z> object is associated with a file or a filehandle, C<fileno>
 922 will return the underlying file descriptor. Once the C<close> method is
 923 called C<fileno> will return C<undef>.
 924
 925 If the C<$z> object is is associated with a buffer, this method will return
 926 C<undef>.
 927
 928 =head2 close
 929
 930     $z->close() ;
 931     close $z ;
 932
 933 Closes the output file/buffer.
 934
 935 For most versions of Perl this method will be automatically invoked if
 936 the IO::Uncompress::RawInflate object is destroyed (either explicitly or by the
 937 variable with the reference to the object going out of scope). The
 938 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
 939 these cases, the C<close> method will be called automatically, but
 940 not until global destruction of all live objects when the program is
 941 terminating.
 942
 943 Therefore, if you want your scripts to be able to run on all versions
 944 of Perl, you should call C<close> explicitly and not rely on automatic
 945 closing.
 946
 947 Returns true on success, otherwise 0.
 948
 949 If the C<AutoClose> option has been enabled when the IO::Uncompress::RawInflate
 950 object was created, and the object is associated with a file, the
 951 underlying file will also be closed.
 952
 953 =head2 nextStream
 954
 955 Usage is
 956
 957     my $status = $z->nextStream();
 958
 959 Skips to the next compressed data stream in the input file/buffer. If a new
 960 compressed data stream is found, the eof marker will be cleared and C<$.>
 961 will be reset to 0.
 962
 963 Returns 1 if a new stream was found, 0 if none was found, and -1 if an
 964 error was encountered.
 965
 966 =head2 trailingData
 967
 968 Usage is
 969
 970     my $data = $z->trailingData();
 971
 972 Returns the data, if any, that is present immediately after the compressed
 973 data stream once uncompression is complete. It only makes sense to call
 974 this method once the end of the compressed data stream has been
 975 encountered.
 976
 977 This option can be used when there is useful information immediately
 978 following the compressed data stream, and you don't know the length of the
 979 compressed data stream.
 980
 981 If the input is a buffer, C<trailingData> will return everything from the
 982 end of the compressed data stream to the end of the buffer.
 983
 984 If the input is a filehandle, C<trailingData> will return the data that is
 985 left in the filehandle input buffer once the end of the compressed data
 986 stream has been reached. You can then use the filehandle to read the rest
 987 of the input file.
 988
 989 Don't bother using C<trailingData> if the input is a filename.
 990
 991 If you know the length of the compressed data stream before you start
 992 uncompressing, you can avoid having to use C<trailingData> by setting the
 993 C<InputLength> option in the constructor.
 994
 995 =head1 Importing
 996
 997 No symbolic constants are required by this IO::Uncompress::RawInflate at present.
 998
 999 =over 5
1000
1001 =item :all
1002
1003 Imports C<rawinflate> and C<$RawInflateError>.
1004 Same as doing this
1005
1006     use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
1007
1008 =back
1009
1010 =head1 EXAMPLES
1011
1012 =head2 Working with Net::FTP
1013
1014 See L<IO::Uncompress::RawInflate::FAQ|IO::Uncompress::RawInflate::FAQ/"Compressed files and Net::FTP">
1015
1016 =head1 SEE ALSO
1017
1018 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>
1019
1020 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1021
1022 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1023 L<Archive::Tar|Archive::Tar>,
1024 L<IO::Zlib|IO::Zlib>
1025
1026 For RFC 1950, 1951 and 1952 see
1027 F<http://www.faqs.org/rfcs/rfc1950.html>,
1028 F<http://www.faqs.org/rfcs/rfc1951.html> and
1029 F<http://www.faqs.org/rfcs/rfc1952.html>
1030
1031 The I<zlib> compression library was written by Jean-loup Gailly
1032 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1033
1034 The primary site for the I<zlib> compression library is
1035 F<http://www.zlib.org>.
1036
1037 The primary site for gzip is F<http://www.gzip.org>.
1038
1039 =head1 AUTHOR
1040
1041 This module was written by Paul Marquess, F<pmqs@cpan.org>.
1042
1043 =head1 MODIFICATION HISTORY
1044
1045 See the Changes file.
1046
1047 =head1 COPYRIGHT AND LICENSE
1048
1049 Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
1050
1051 This program is free software; you can redistribute it and/or
1052 modify it under the same terms as Perl itself.
1053