1 package IO::Uncompress::RawInflate ;
8 use Compress::Raw::Zlib ;
9 use IO::Compress::Base::Common qw(:Status createSelfTiedObject);
11 use IO::Uncompress::Base ;
12 use IO::Uncompress::Adapter::Inflate ;
18 our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, %DEFLATE_CONSTANTS, $RawInflateError);
21 $RawInflateError = '';
23 @ISA = qw( Exporter IO::Uncompress::Base );
24 @EXPORT_OK = qw( $RawInflateError rawinflate ) ;
25 %DEFLATE_CONSTANTS = ();
26 %EXPORT_TAGS = %IO::Uncompress::Base::EXPORT_TAGS ;
27 push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
28 Exporter::export_ok_tags('all');
35 my $obj = createSelfTiedObject($class, \$RawInflateError);
36 $obj->_create(undef, 0, @_);
41 my $obj = createSelfTiedObject(undef, \$RawInflateError);
42 return $obj->_inf(@_);
64 my ($obj, $errstr, $errno) = IO::Uncompress::Adapter::Inflate::mkUncompObject(
66 $got->value('ADLER32'),
70 return $self->saveErrorString(undef, $errstr, $errno)
73 *$self->{Uncomp} = $obj;
75 my $magic = $self->ckMagic()
78 *$self->{Info} = $self->readHeader($magic)
90 return $self->_isRaw() ;
100 'FingerprintLength' => 0,
102 'TrailerLength' => 0,
116 my $got = $self->_isRawx(@_);
119 *$self->{Pending} = *$self->{HeaderPending} ;
122 $self->pushBack(*$self->{HeaderPending});
123 *$self->{Uncomp}->reset();
125 *$self->{HeaderPending} = '';
135 $magic = '' unless defined $magic ;
139 $self->smartRead(\$buffer, *$self->{BlockSize}) >= 0
140 or return $self->saveErrorString(undef, "No data to read");
142 my $temp_buf = $magic . $buffer ;
143 *$self->{HeaderPending} = $temp_buf ;
145 my $status = *$self->{Uncomp}->uncompr(\$temp_buf, \$buffer, $self->smartEof()) ;
146 return $self->saveErrorString(undef, *$self->{Uncomp}{Error}, STATUS_ERROR)
147 if $status == STATUS_ERROR;
149 #my $buf_len = *$self->{Uncomp}->uncompressedBytes();
150 my $buf_len = length $buffer;
152 if ($status == STATUS_ENDSTREAM) {
153 if (*$self->{MultiStream}
154 && (length $temp_buf || ! $self->smartEof())){
155 *$self->{NewStream} = 1 ;
156 *$self->{EndStream} = 0 ;
157 $self->pushBack($temp_buf);
160 *$self->{EndStream} = 1 ;
161 $self->pushBack($temp_buf);
164 *$self->{HeaderPending} = $buffer ;
165 *$self->{InflatedBytesRead} = $buf_len ;
166 *$self->{TotalInflatedBytesRead} += $buf_len ;
167 *$self->{Type} = 'rfc1951';
169 $self->saveStatus(STATUS_OK);
174 'TrailerLength' => 0,
184 # inflateSync is a no-op in Plain mode
188 return 0 if *$self->{Closed} ;
189 #return G_EOF if !length *$self->{Pending} && *$self->{EndStream} ;
190 return 0 if ! length *$self->{Pending} && *$self->{EndStream} ;
193 *$self->{Strict} = 0 ;
200 if (length *$self->{Pending} )
202 $temp_buf = *$self->{Pending} ;
203 *$self->{Pending} = '';
207 $status = $self->smartRead(\$temp_buf, *$self->{BlockSize}) ;
208 return $self->saveErrorString(0, "Error Reading Data")
212 *$self->{EndStream} = 1 ;
213 return $self->saveErrorString(0, "unexpected end of file", STATUS_ERROR);
217 $status = *$self->{Uncomp}->sync($temp_buf) ;
219 if ($status == STATUS_OK)
221 *$self->{Pending} .= $temp_buf ;
225 last unless $status == STATUS_ERROR ;
236 # my $end_offset = 0;
238 # $status = $self->scan()
239 # #or return $self->saveErrorString(undef, "Error Scanning: $$error_ref", $self->errorNo) ;
240 # or return $self->saveErrorString(G_ERR, "Error Scanning: $status")
242 # $status = $self->zap($end_offset)
243 # or return $self->saveErrorString(G_ERR, "Error Zapping: $status");
244 # #or return $self->saveErrorString(undef, "Error Zapping: $$error_ref", $self->errorNo) ;
246 # #(*$obj->{Deflate}, $status) = $inf->createDeflate();
248 ## *$obj->{Header} = *$inf->{Info}{Header};
249 ## *$obj->{UnCompSize_32bit} =
250 ## *$obj->{BytesWritten} = *$inf->{UnCompSize_32bit} ;
251 ## *$obj->{CompSize_32bit} = *$inf->{CompSize_32bit} ;
254 ## if ( $outType eq 'buffer')
255 ## { substr( ${ *$self->{Buffer} }, $end_offset) = '' }
256 ## elsif ($outType eq 'handle' || $outType eq 'filename') {
257 ## *$self->{FH} = *$inf->{FH} ;
258 ## delete *$inf->{FH};
259 ## *$obj->{FH}->flush() ;
260 ## *$obj->{Handle} = 1 if $outType eq 'handle';
262 ## #seek(*$obj->{FH}, $end_offset, SEEK_SET)
263 ## *$obj->{FH}->seek($end_offset, SEEK_SET)
264 ## or return $obj->saveErrorString(undef, $!, $!) ;
273 return 1 if *$self->{Closed} ;
274 return 1 if !length *$self->{Pending} && *$self->{EndStream} ;
279 $len = $self->_raw_read(\$buffer, 1)
280 while ! *$self->{EndStream} && $len >= 0 ;
282 #return $len if $len < 0 ? $len : 0 ;
283 return $len < 0 ? 0 : 1 ;
290 my $headerLength = *$self->{Info}{HeaderLength};
291 my $block_offset = $headerLength + *$self->{Uncomp}->getLastBlockOffset();
292 $_[0] = $headerLength + *$self->{Uncomp}->getEndOffset();
293 #printf "# End $_[0], headerlen $headerLength \n";;
294 #printf "# block_offset $block_offset %x\n", $block_offset;
296 ( $self->smartSeek($block_offset) &&
297 $self->smartRead(\$byte, 1) )
298 or return $self->saveErrorString(0, $!, $!);
300 #printf "#byte is %x\n", unpack('C*',$byte);
301 *$self->{Uncomp}->resetLastBlockByte($byte);
302 #printf "#to byte is %x\n", unpack('C*',$byte);
304 ( $self->smartSeek($block_offset) &&
305 $self->smartWrite($byte) )
306 or return $self->saveErrorString(0, $!, $!);
308 #$self->smartSeek($end_offset, 1);
316 my ($def, $status) = *$self->{Uncomp}->createDeflateStream(
318 -WindowBits => - MAX_WBITS,
319 -CRC32 => *$self->{Params}->value('CRC32'),
320 -ADLER32 => *$self->{Params}->value('ADLER32'),
323 return wantarray ? ($status, $def) : $def ;
336 IO::Uncompress::RawInflate - Read RFC 1951 files/buffers
342 use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
344 my $status = rawinflate $input => $output [,OPTS]
345 or die "rawinflate failed: $RawInflateError\n";
347 my $z = new IO::Uncompress::RawInflate $input [OPTS]
348 or die "rawinflate failed: $RawInflateError\n";
350 $status = $z->read($buffer)
351 $status = $z->read($buffer, $length)
352 $status = $z->read($buffer, $length, $offset)
353 $line = $z->getline()
358 $status = $z->inflateSync()
360 $data = $z->trailingData()
361 $status = $z->nextStream()
362 $data = $z->getHeaderInfo()
364 $z->seek($position, $whence)
376 read($z, $buffer, $length);
377 read($z, $buffer, $length, $offset);
379 seek($z, $position, $whence)
390 This module provides a Perl interface that allows the reading of
391 files/buffers that conform to RFC 1951.
393 For writing RFC 1951 files/buffers, see the companion module IO::Compress::RawDeflate.
399 =head1 Functional Interface
401 A top-level function, C<rawinflate>, is provided to carry out
402 "one-shot" uncompression between buffers and/or files. For finer
403 control over the uncompression process, see the L</"OO Interface">
406 use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
408 rawinflate $input => $output [,OPTS]
409 or die "rawinflate failed: $RawInflateError\n";
413 The functional interface needs Perl5.005 or better.
416 =head2 rawinflate $input => $output [, OPTS]
419 C<rawinflate> expects at least two parameters, C<$input> and C<$output>.
421 =head3 The C<$input> parameter
423 The parameter, C<$input>, is used to define the source of
426 It can take one of the following forms:
432 If the C<$input> parameter is a simple scalar, it is assumed to be a
433 filename. This file will be opened for reading and the input data
434 will be read from it.
438 If the C<$input> parameter is a filehandle, the input data will be
440 The string '-' can be used as an alias for standard input.
442 =item A scalar reference
444 If C<$input> is a scalar reference, the input data will be read
447 =item An array reference
449 If C<$input> is an array reference, each element in the array must be a
452 The input data will be read from each file in turn.
454 The complete array will be walked to ensure that it only
455 contains valid filenames before any data is uncompressed.
459 =item An Input FileGlob string
461 If C<$input> is a string that is delimited by the characters "<" and ">"
462 C<rawinflate> will assume that it is an I<input fileglob string>. The
463 input is the list of files that match the fileglob.
465 If the fileglob does not match any files ...
467 See L<File::GlobMapper|File::GlobMapper> for more details.
472 If the C<$input> parameter is any other type, C<undef> will be returned.
476 =head3 The C<$output> parameter
478 The parameter C<$output> is used to control the destination of the
479 uncompressed data. This parameter can take one of these forms.
485 If the C<$output> parameter is a simple scalar, it is assumed to be a
486 filename. This file will be opened for writing and the uncompressed
487 data will be written to it.
491 If the C<$output> parameter is a filehandle, the uncompressed data
492 will be written to it.
493 The string '-' can be used as an alias for standard output.
496 =item A scalar reference
498 If C<$output> is a scalar reference, the uncompressed data will be
499 stored in C<$$output>.
503 =item An Array Reference
505 If C<$output> is an array reference, the uncompressed data will be
506 pushed onto the array.
508 =item An Output FileGlob
510 If C<$output> is a string that is delimited by the characters "<" and ">"
511 C<rawinflate> will assume that it is an I<output fileglob string>. The
512 output is the list of files that match the fileglob.
514 When C<$output> is an fileglob string, C<$input> must also be a fileglob
515 string. Anything else is an error.
519 If the C<$output> parameter is any other type, C<undef> will be returned.
526 When C<$input> maps to multiple compressed files/buffers and C<$output> is
527 a single file/buffer, after uncompression C<$output> will contain a
528 concatenation of all the uncompressed data from each of the input
535 =head2 Optional Parameters
537 Unless specified below, the optional parameters for C<rawinflate>,
538 C<OPTS>, are the same as those used with the OO interface defined in the
539 L</"Constructor Options"> section below.
543 =item C<< AutoClose => 0|1 >>
545 This option applies to any input or output data streams to
546 C<rawinflate> that are filehandles.
548 If C<AutoClose> is specified, and the value is true, it will result in all
549 input and/or output filehandles being closed once C<rawinflate> has
552 This parameter defaults to 0.
555 =item C<< BinModeOut => 0|1 >>
557 When writing to a file or filehandle, set C<binmode> before writing to the
566 =item C<< Append => 0|1 >>
570 =item C<< MultiStream => 0|1 >>
574 This option is a no-op.
580 =item C<< TrailingData => $scalar >>
582 Returns the data, if any, that is present immediately after the compressed
583 data stream once uncompression is complete.
585 This option can be used when there is useful information immediately
586 following the compressed data stream, and you don't know the length of the
587 compressed data stream.
589 If the input is a buffer, C<trailingData> will return everything from the
590 end of the compressed data stream to the end of the buffer.
592 If the input is a filehandle, C<trailingData> will return the data that is
593 left in the filehandle input buffer once the end of the compressed data
594 stream has been reached. You can then use the filehandle to read the rest
597 Don't bother using C<trailingData> if the input is a filename.
601 If you know the length of the compressed data stream before you start
602 uncompressing, you can avoid having to use C<trailingData> by setting the
603 C<InputLength> option.
614 To read the contents of the file C<file1.txt.1951> and write the
615 compressed data to the file C<file1.txt>.
619 use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
621 my $input = "file1.txt.1951";
622 my $output = "file1.txt";
623 rawinflate $input => $output
624 or die "rawinflate failed: $RawInflateError\n";
627 To read from an existing Perl filehandle, C<$input>, and write the
628 uncompressed data to a buffer, C<$buffer>.
632 use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
635 my $input = new IO::File "<file1.txt.1951"
636 or die "Cannot open 'file1.txt.1951': $!\n" ;
638 rawinflate $input => \$buffer
639 or die "rawinflate failed: $RawInflateError\n";
641 To uncompress all files in the directory "/my/home" that match "*.txt.1951" and store the compressed data in the same directory
645 use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
647 rawinflate '</my/home/*.txt.1951>' => '</my/home/#1.txt>'
648 or die "rawinflate failed: $RawInflateError\n";
650 and if you want to compress each file one at a time, this will do the trick
654 use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
656 for my $input ( glob "/my/home/*.txt.1951" )
659 $output =~ s/.1951// ;
660 rawinflate $input => $output
661 or die "Error compressing '$input': $RawInflateError\n";
668 The format of the constructor for IO::Uncompress::RawInflate is shown below
671 my $z = new IO::Uncompress::RawInflate $input [OPTS]
672 or die "IO::Uncompress::RawInflate failed: $RawInflateError\n";
674 Returns an C<IO::Uncompress::RawInflate> object on success and undef on failure.
675 The variable C<$RawInflateError> will contain an error message on failure.
677 If you are running Perl 5.005 or better the object, C<$z>, returned from
678 IO::Uncompress::RawInflate can be used exactly like an L<IO::File|IO::File> filehandle.
679 This means that all normal input file operations can be carried out with
680 C<$z>. For example, to read a line from a compressed file/buffer you can
681 use either of these forms
683 $line = $z->getline();
686 The mandatory parameter C<$input> is used to determine the source of the
687 compressed data. This parameter can take one of three forms.
693 If the C<$input> parameter is a scalar, it is assumed to be a filename. This
694 file will be opened for reading and the compressed data will be read from it.
698 If the C<$input> parameter is a filehandle, the compressed data will be
700 The string '-' can be used as an alias for standard input.
703 =item A scalar reference
705 If C<$input> is a scalar reference, the compressed data will be read from
710 =head2 Constructor Options
713 The option names defined below are case insensitive and can be optionally
714 prefixed by a '-'. So all of the following are valid
721 OPTS is a combination of the following options:
725 =item C<< AutoClose => 0|1 >>
727 This option is only valid when the C<$input> parameter is a filehandle. If
728 specified, and the value is true, it will result in the file being closed once
729 either the C<close> method is called or the IO::Uncompress::RawInflate object is
732 This parameter defaults to 0.
734 =item C<< MultiStream => 0|1 >>
738 This option is a no-op.
742 =item C<< Prime => $string >>
744 This option will uncompress the contents of C<$string> before processing the
747 This option can be useful when the compressed data is embedded in another
748 file/data structure and it is not possible to work out where the compressed
749 data begins without having to read the first few bytes. If this is the
750 case, the uncompression can be I<primed> with these bytes using this
753 =item C<< Transparent => 0|1 >>
755 If this option is set and the input file or buffer is not compressed data,
756 the module will allow reading of it anyway.
758 This option defaults to 1.
760 =item C<< BlockSize => $num >>
762 When reading the compressed input data, IO::Uncompress::RawInflate will read it in
763 blocks of C<$num> bytes.
765 This option defaults to 4096.
767 =item C<< InputLength => $size >>
769 When present this option will limit the number of compressed bytes read
770 from the input file/buffer to C<$size>. This option can be used in the
771 situation where there is useful data directly after the compressed data
772 stream and you know beforehand the exact length of the compressed data
775 This option is mostly used when reading from a filehandle, in which case
776 the file pointer will be left pointing to the first byte directly after the
777 compressed data stream.
781 This option defaults to off.
783 =item C<< Append => 0|1 >>
785 This option controls what the C<read> method does with uncompressed data.
787 If set to 1, all uncompressed data will be appended to the output parameter
788 of the C<read> method.
790 If set to 0, the contents of the output parameter of the C<read> method
791 will be overwritten by the uncompressed data.
795 =item C<< Strict => 0|1 >>
799 This option is a no-op.
819 $status = $z->read($buffer)
821 Reads a block of compressed data (the size the the compressed block is
822 determined by the C<Buffer> option in the constructor), uncompresses it and
823 writes any uncompressed data into C<$buffer>. If the C<Append> parameter is
824 set in the constructor, the uncompressed data will be appended to the
825 C<$buffer> parameter. Otherwise C<$buffer> will be overwritten.
827 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
828 or a negative number on error.
834 $status = $z->read($buffer, $length)
835 $status = $z->read($buffer, $length, $offset)
837 $status = read($z, $buffer, $length)
838 $status = read($z, $buffer, $length, $offset)
840 Attempt to read C<$length> bytes of uncompressed data into C<$buffer>.
842 The main difference between this form of the C<read> method and the
843 previous one, is that this one will attempt to return I<exactly> C<$length>
844 bytes. The only circumstances that this function will not is if end-of-file
845 or an IO error is encountered.
847 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
848 or a negative number on error.
855 $line = $z->getline()
860 This method fully supports the use of of the variable C<$/> (or
861 C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use) to
862 determine what constitutes an end of line. Paragraph mode, record mode and
863 file slurp mode are all supported.
872 Read a single character.
878 $char = $z->ungetc($string)
886 $status = $z->inflateSync()
895 $hdr = $z->getHeaderInfo();
896 @hdrs = $z->getHeaderInfo();
898 This method returns either a hash reference (in scalar context) or a list
899 or hash references (in array context) that contains information about each
900 of the header fields in the compressed data stream(s).
912 Returns the uncompressed file offset.
923 Returns true if the end of the compressed input stream has been reached.
929 $z->seek($position, $whence);
930 seek($z, $position, $whence);
935 Provides a sub-set of the C<seek> functionality, with the restriction
936 that it is only legal to seek forward in the input file/buffer.
937 It is a fatal error to attempt to seek backward.
941 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
942 SEEK_CUR or SEEK_END.
944 Returns 1 on success, 0 on failure.
953 This is a noop provided for completeness.
959 Returns true if the object currently refers to a opened file/buffer.
963 my $prev = $z->autoflush()
964 my $prev = $z->autoflush(EXPR)
966 If the C<$z> object is associated with a file or a filehandle, this method
967 returns the current autoflush setting for the underlying filehandle. If
968 C<EXPR> is present, and is non-zero, it will enable flushing after every
969 write/print operation.
971 If C<$z> is associated with a buffer, this method has no effect and always
974 B<Note> that the special variable C<$|> B<cannot> be used to set or
975 retrieve the autoflush setting.
977 =head2 input_line_number
979 $z->input_line_number()
980 $z->input_line_number(EXPR)
984 Returns the current uncompressed line number. If C<EXPR> is present it has
985 the effect of setting the line number. Note that setting the line number
986 does not change the current position within the file/buffer being read.
988 The contents of C<$/> are used to to determine what constitutes a line
998 If the C<$z> object is associated with a file or a filehandle, this method
999 will return the underlying file descriptor.
1001 If the C<$z> object is is associated with a buffer, this method will
1011 Closes the output file/buffer.
1015 For most versions of Perl this method will be automatically invoked if
1016 the IO::Uncompress::RawInflate object is destroyed (either explicitly or by the
1017 variable with the reference to the object going out of scope). The
1018 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
1019 these cases, the C<close> method will be called automatically, but
1020 not until global destruction of all live objects when the program is
1023 Therefore, if you want your scripts to be able to run on all versions
1024 of Perl, you should call C<close> explicitly and not rely on automatic
1027 Returns true on success, otherwise 0.
1029 If the C<AutoClose> option has been enabled when the IO::Uncompress::RawInflate
1030 object was created, and the object is associated with a file, the
1031 underlying file will also be closed.
1040 my $status = $z->nextStream();
1042 Skips to the next compressed data stream in the input file/buffer. If a new
1043 compressed data stream is found, the eof marker will be cleared and C<$.>
1046 Returns 1 if a new stream was found, 0 if none was found, and -1 if an
1047 error was encountered.
1053 my $data = $z->trailingData();
1055 Returns the data, if any, that is present immediately after the compressed
1056 data stream once uncompression is complete. It only makes sense to call
1057 this method once the end of the compressed data stream has been
1060 This option can be used when there is useful information immediately
1061 following the compressed data stream, and you don't know the length of the
1062 compressed data stream.
1064 If the input is a buffer, C<trailingData> will return everything from the
1065 end of the compressed data stream to the end of the buffer.
1067 If the input is a filehandle, C<trailingData> will return the data that is
1068 left in the filehandle input buffer once the end of the compressed data
1069 stream has been reached. You can then use the filehandle to read the rest
1072 Don't bother using C<trailingData> if the input is a filename.
1076 If you know the length of the compressed data stream before you start
1077 uncompressing, you can avoid having to use C<trailingData> by setting the
1078 C<InputLength> option in the constructor.
1082 No symbolic constants are required by this IO::Uncompress::RawInflate at present.
1088 Imports C<rawinflate> and C<$RawInflateError>.
1091 use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
1102 L<Compress::Zlib>, L<IO::Compress::Gzip>, L<IO::Uncompress::Gunzip>, L<IO::Compress::Deflate>, L<IO::Uncompress::Inflate>, L<IO::Compress::RawDeflate>, L<IO::Compress::Bzip2>, L<IO::Uncompress::Bunzip2>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
1104 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1106 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1107 L<Archive::Tar|Archive::Tar>,
1108 L<IO::Zlib|IO::Zlib>
1111 For RFC 1950, 1951 and 1952 see
1112 F<http://www.faqs.org/rfcs/rfc1950.html>,
1113 F<http://www.faqs.org/rfcs/rfc1951.html> and
1114 F<http://www.faqs.org/rfcs/rfc1952.html>
1116 The I<zlib> compression library was written by Jean-loup Gailly
1117 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1119 The primary site for the I<zlib> compression library is
1120 F<http://www.zlib.org>.
1122 The primary site for gzip is F<http://www.gzip.org>.
1129 This module was written by Paul Marquess, F<pmqs@cpan.org>.
1133 =head1 MODIFICATION HISTORY
1135 See the Changes file.
1137 =head1 COPYRIGHT AND LICENSE
1139 Copyright (c) 2005-2006 Paul Marquess. All rights reserved.
1141 This program is free software; you can redistribute it and/or
1142 modify it under the same terms as Perl itself.