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