"Fossies" - the Fresh Open Source Software Archive

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