ext/Compress/IO/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 ;
   9 use IO::Compress::Base::Common qw(:Status createSelfTiedObject);
  10
  11 use IO::Uncompress::Base ;
  12 use IO::Uncompress::Adapter::Inflate ;
  13
  14
  15
  16
  17 require Exporter ;
  18 our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, %DEFLATE_CONSTANTS, $RawInflateError);
  19
  20 $VERSION = '2.001';
  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 This option is a no-op.
 739
 740
 741
 742 =item C<< Prime => $string >>
 743
 744 This option will uncompress the contents of C<$string> before processing the
 745 input file/buffer.
 746
 747 This option can be useful when the compressed data is embedded in another
 748 file/data structure and it is not possible to work out where the compressed
 749 data begins without having to read the first few bytes. If this is the
 750 case, the uncompression can be I<primed> with these bytes using this
 751 option.
 752
 753 =item C<< Transparent => 0|1 >>
 754
 755 If this option is set and the input file or buffer is not compressed data,
 756 the module will allow reading of it anyway.
 757
 758 This option defaults to 1.
 759
 760 =item C<< BlockSize => $num >>
 761
 762 When reading the compressed input data, IO::Uncompress::RawInflate will read it in
 763 blocks of C<$num> bytes.
 764
 765 This option defaults to 4096.
 766
 767 =item C<< InputLength => $size >>
 768
 769 When present this option will limit the number of compressed bytes read
 770 from the input file/buffer to C<$size>. This option can be used in the
 771 situation where there is useful data directly after the compressed data
 772 stream and you know beforehand the exact length of the compressed data
 773 stream.
 774
 775 This option is mostly used when reading from a filehandle, in which case
 776 the file pointer will be left pointing to the first byte directly after the
 777 compressed data stream.
 778
 779
 780
 781 This option defaults to off.
 782
 783 =item C<< Append => 0|1 >>
 784
 785 This option controls what the C<read> method does with uncompressed data.
 786
 787 If set to 1, all uncompressed data will be appended to the output parameter
 788 of the C<read> method.
 789
 790 If set to 0, the contents of the output parameter of the C<read> method
 791 will be overwritten by the uncompressed data.
 792
 793 Defaults to 0.
 794
 795 =item C<< Strict => 0|1 >>
 796
 797
 798
 799 This option is a no-op.
 800
 801
 802
 803
 804
 805
 806
 807 =back
 808
 809 =head2 Examples
 810
 811 TODO
 812
 813 =head1 Methods
 814
 815 =head2 read
 816
 817 Usage is
 818
 819     $status = $z->read($buffer)
 820
 821 Reads a block of compressed data (the size the the compressed block is
 822 determined by the C<Buffer> option in the constructor), uncompresses it and
 823 writes any uncompressed data into C<$buffer>. If the C<Append> parameter is
 824 set in the constructor, the uncompressed data will be appended to the
 825 C<$buffer> parameter. Otherwise C<$buffer> will be overwritten.
 826
 827 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
 828 or a negative number on error.
 829
 830 =head2 read
 831
 832 Usage is
 833
 834     $status = $z->read($buffer, $length)
 835     $status = $z->read($buffer, $length, $offset)
 836
 837     $status = read($z, $buffer, $length)
 838     $status = read($z, $buffer, $length, $offset)
 839
 840 Attempt to read C<$length> bytes of uncompressed data into C<$buffer>.
 841
 842 The main difference between this form of the C<read> method and the
 843 previous one, is that this one will attempt to return I<exactly> C<$length>
 844 bytes. The only circumstances that this function will not is if end-of-file
 845 or an IO error is encountered.
 846
 847 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
 848 or a negative number on error.
 849
 850
 851 =head2 getline
 852
 853 Usage is
 854
 855     $line = $z->getline()
 856     $line = <$z>
 857
 858 Reads a single line.
 859
 860 This method fully supports the use of of the variable C<$/> (or
 861 C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use) to
 862 determine what constitutes an end of line. Paragraph mode, record mode and
 863 file slurp mode are all supported.
 864
 865
 866 =head2 getc
 867
 868 Usage is
 869
 870     $char = $z->getc()
 871
 872 Read a single character.
 873
 874 =head2 ungetc
 875
 876 Usage is
 877
 878     $char = $z->ungetc($string)
 879
 880
 881
 882 =head2 inflateSync
 883
 884 Usage is
 885
 886     $status = $z->inflateSync()
 887
 888 TODO
 889
 890
 891 =head2 getHeaderInfo
 892
 893 Usage is
 894
 895     $hdr  = $z->getHeaderInfo();
 896     @hdrs = $z->getHeaderInfo();
 897
 898 This method returns either a hash reference (in scalar context) or a list
 899 or hash references (in array context) that contains information about each
 900 of the header fields in the compressed data stream(s).
 901
 902
 903
 904
 905 =head2 tell
 906
 907 Usage is
 908
 909     $z->tell()
 910     tell $z
 911
 912 Returns the uncompressed file offset.
 913
 914 =head2 eof
 915
 916 Usage is
 917
 918     $z->eof();
 919     eof($z);
 920
 921
 922
 923 Returns true if the end of the compressed input stream has been reached.
 924
 925
 926
 927 =head2 seek
 928
 929     $z->seek($position, $whence);
 930     seek($z, $position, $whence);
 931
 932
 933
 934
 935 Provides a sub-set of the C<seek> functionality, with the restriction
 936 that it is only legal to seek forward in the input file/buffer.
 937 It is a fatal error to attempt to seek backward.
 938
 939
 940
 941 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
 942 SEEK_CUR or SEEK_END.
 943
 944 Returns 1 on success, 0 on failure.
 945
 946 =head2 binmode
 947
 948 Usage is
 949
 950     $z->binmode
 951     binmode $z ;
 952
 953 This is a noop provided for completeness.
 954
 955 =head2 opened
 956
 957     $z->opened()
 958
 959 Returns true if the object currently refers to a opened file/buffer.
 960
 961 =head2 autoflush
 962
 963     my $prev = $z->autoflush()
 964     my $prev = $z->autoflush(EXPR)
 965
 966 If the C<$z> object is associated with a file or a filehandle, this method
 967 returns the current autoflush setting for the underlying filehandle. If
 968 C<EXPR> is present, and is non-zero, it will enable flushing after every
 969 write/print operation.
 970
 971 If C<$z> is associated with a buffer, this method has no effect and always
 972 returns C<undef>.
 973
 974 B<Note> that the special variable C<$|> B<cannot> be used to set or
 975 retrieve the autoflush setting.
 976
 977 =head2 input_line_number
 978
 979     $z->input_line_number()
 980     $z->input_line_number(EXPR)
 981
 982
 983
 984 Returns the current uncompressed line number. If C<EXPR> is present it has
 985 the effect of setting the line number. Note that setting the line number
 986 does not change the current position within the file/buffer being read.
 987
 988 The contents of C<$/> are used to to determine what constitutes a line
 989 terminator.
 990
 991
 992
 993 =head2 fileno
 994
 995     $z->fileno()
 996     fileno($z)
 997
 998 If the C<$z> object is associated with a file or a filehandle, this method
 999 will return the underlying file descriptor.
1000
1001 If the C<$z> object is is associated with a buffer, this method will
1002 return undef.
1003
1004 =head2 close
1005
1006     $z->close() ;
1007     close $z ;
1008
1009
1010
1011 Closes the output file/buffer.
1012
1013
1014
1015 For most versions of Perl this method will be automatically invoked if
1016 the IO::Uncompress::RawInflate object is destroyed (either explicitly or by the
1017 variable with the reference to the object going out of scope). The
1018 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
1019 these cases, the C<close> method will be called automatically, but
1020 not until global destruction of all live objects when the program is
1021 terminating.
1022
1023 Therefore, if you want your scripts to be able to run on all versions
1024 of Perl, you should call C<close> explicitly and not rely on automatic
1025 closing.
1026
1027 Returns true on success, otherwise 0.
1028
1029 If the C<AutoClose> option has been enabled when the IO::Uncompress::RawInflate
1030 object was created, and the object is associated with a file, the
1031 underlying file will also be closed.
1032
1033
1034
1035
1036 =head2 nextStream
1037
1038 Usage is
1039
1040     my $status = $z->nextStream();
1041
1042 Skips to the next compressed data stream in the input file/buffer. If a new
1043 compressed data stream is found, the eof marker will be cleared and C<$.>
1044 will be reset to 0.
1045
1046 Returns 1 if a new stream was found, 0 if none was found, and -1 if an
1047 error was encountered.
1048
1049 =head2 trailingData
1050
1051 Usage is
1052
1053     my $data = $z->trailingData();
1054
1055 Returns the data, if any, that is present immediately after the compressed
1056 data stream once uncompression is complete. It only makes sense to call
1057 this method once the end of the compressed data stream has been
1058 encountered.
1059
1060 This option can be used when there is useful information immediately
1061 following the compressed data stream, and you don't know the length of the
1062 compressed data stream.
1063
1064 If the input is a buffer, C<trailingData> will return everything from the
1065 end of the compressed data stream to the end of the buffer.
1066
1067 If the input is a filehandle, C<trailingData> will return the data that is
1068 left in the filehandle input buffer once the end of the compressed data
1069 stream has been reached. You can then use the filehandle to read the rest
1070 of the input file.
1071
1072 Don't bother using C<trailingData> if the input is a filename.
1073
1074
1075
1076 If you know the length of the compressed data stream before you start
1077 uncompressing, you can avoid having to use C<trailingData> by setting the
1078 C<InputLength> option in the constructor.
1079
1080 =head1 Importing
1081
1082 No symbolic constants are required by this IO::Uncompress::RawInflate at present.
1083
1084 =over 5
1085
1086 =item :all
1087
1088 Imports C<rawinflate> and C<$RawInflateError>.
1089 Same as doing this
1090
1091     use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
1092
1093 =back
1094
1095 =head1 EXAMPLES
1096
1097
1098
1099
1100 =head1 SEE ALSO
1101
1102 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>
1103
1104 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1105
1106 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1107 L<Archive::Tar|Archive::Tar>,
1108 L<IO::Zlib|IO::Zlib>
1109
1110
1111 For RFC 1950, 1951 and 1952 see
1112 F<http://www.faqs.org/rfcs/rfc1950.html>,
1113 F<http://www.faqs.org/rfcs/rfc1951.html> and
1114 F<http://www.faqs.org/rfcs/rfc1952.html>
1115
1116 The I<zlib> compression library was written by Jean-loup Gailly
1117 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1118
1119 The primary site for the I<zlib> compression library is
1120 F<http://www.zlib.org>.
1121
1122 The primary site for gzip is F<http://www.gzip.org>.
1123
1124
1125
1126
1127 =head1 AUTHOR
1128
1129 This module was written by Paul Marquess, F<pmqs@cpan.org>.
1130
1131
1132
1133 =head1 MODIFICATION HISTORY
1134
1135 See the Changes file.
1136
1137 =head1 COPYRIGHT AND LICENSE
1138
1139 Copyright (c) 2005-2006 Paul Marquess. All rights reserved.
1140
1141 This program is free software; you can redistribute it and/or
1142 modify it under the same terms as Perl itself.
1143