"Fossies" - the Fresh Open Source Software Archive

Member "install-tl-20200916/tlpkg/tlperl/lib/IO/Uncompress/RawInflate.pm" (7 Mar 2020, 31641 Bytes) of package /windows/misc/install-tl.zip:


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.

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