"Fossies" - the Fresh Open Source Software Archive

Member "IO-Compress-2.093/lib/IO/Uncompress/RawInflate.pm" (7 Dec 2019, 31945 Bytes) of package /linux/privat/IO-Compress-2.093.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) Perl source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "RawInflate.pm" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 2.092_vs_2.093.

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