1 package IO::Uncompress::RawInflate ;
8 use Compress::Zlib::Common qw(:Status createSelfTiedObject);
9 use Compress::Zlib::ParseParameters ;
11 use IO::Uncompress::Base ;
12 use UncompressPlugin::Inflate ;
18 our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, %DEFLATE_CONSTANTS, $RawInflateError);
20 $VERSION = '2.000_07';
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) = UncompressPlugin::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}->count();
151 if ($status == STATUS_ENDSTREAM) {
152 if (*$self->{MultiStream}
153 && (length $temp_buf || ! $self->smartEof())){
154 *$self->{NewStream} = 1 ;
155 *$self->{EndStream} = 0 ;
156 $self->pushBack($temp_buf);
159 *$self->{EndStream} = 1 ;
160 $self->pushBack($temp_buf);
163 *$self->{HeaderPending} = $buffer ;
164 *$self->{InflatedBytesRead} = $buf_len ;
165 *$self->{TotalInflatedBytesRead} += $buf_len ;
166 *$self->{Type} = 'rfc1951';
168 $self->saveStatus(STATUS_OK);
173 'TrailerLength' => 0,
183 # inflateSync is a no-op in Plain mode
187 return 0 if *$self->{Closed} ;
188 #return G_EOF if !length *$self->{Pending} && *$self->{EndStream} ;
189 return 0 if ! length *$self->{Pending} && *$self->{EndStream} ;
192 *$self->{Strict} = 0 ;
199 if (length *$self->{Pending} )
201 $temp_buf = *$self->{Pending} ;
202 *$self->{Pending} = '';
206 $status = $self->smartRead(\$temp_buf, *$self->{BlockSize}) ;
207 return $self->saveErrorString(0, "Error Reading Data")
211 *$self->{EndStream} = 1 ;
212 return $self->saveErrorString(0, "unexpected end of file", STATUS_ERROR);
216 $status = *$self->{Uncomp}->sync($temp_buf) ;
218 if ($status == STATUS_OK)
220 *$self->{Pending} .= $temp_buf ;
224 last unless $status == STATUS_ERROR ;
235 # my $end_offset = 0;
237 # $status = $self->scan()
238 # #or return $self->saveErrorString(undef, "Error Scanning: $$error_ref", $self->errorNo) ;
239 # or return $self->saveErrorString(G_ERR, "Error Scanning: $status")
241 # $status = $self->zap($end_offset)
242 # or return $self->saveErrorString(G_ERR, "Error Zapping: $status");
243 # #or return $self->saveErrorString(undef, "Error Zapping: $$error_ref", $self->errorNo) ;
245 # #(*$obj->{Deflate}, $status) = $inf->createDeflate();
247 ## *$obj->{Header} = *$inf->{Info}{Header};
248 ## *$obj->{UnCompSize_32bit} =
249 ## *$obj->{BytesWritten} = *$inf->{UnCompSize_32bit} ;
250 ## *$obj->{CompSize_32bit} = *$inf->{CompSize_32bit} ;
253 ## if ( $outType eq 'buffer')
254 ## { substr( ${ *$self->{Buffer} }, $end_offset) = '' }
255 ## elsif ($outType eq 'handle' || $outType eq 'filename') {
256 ## *$self->{FH} = *$inf->{FH} ;
257 ## delete *$inf->{FH};
258 ## *$obj->{FH}->flush() ;
259 ## *$obj->{Handle} = 1 if $outType eq 'handle';
261 ## #seek(*$obj->{FH}, $end_offset, SEEK_SET)
262 ## *$obj->{FH}->seek($end_offset, SEEK_SET)
263 ## or return $obj->saveErrorString(undef, $!, $!) ;
272 return 1 if *$self->{Closed} ;
273 return 1 if !length *$self->{Pending} && *$self->{EndStream} ;
278 $len = $self->_raw_read(\$buffer, 1)
279 while ! *$self->{EndStream} && $len >= 0 ;
281 #return $len if $len < 0 ? $len : 0 ;
282 return $len < 0 ? 0 : 1 ;
289 my $headerLength = *$self->{Info}{HeaderLength};
290 my $block_offset = $headerLength + *$self->{Uncomp}->getLastBlockOffset();
291 $_[0] = $headerLength + *$self->{Uncomp}->getEndOffset();
292 #printf "# End $_[0], headerlen $headerLength \n";;
293 #printf "# block_offset $block_offset %x\n", $block_offset;
295 ( $self->smartSeek($block_offset) &&
296 $self->smartRead(\$byte, 1) )
297 or return $self->saveErrorString(0, $!, $!);
299 #printf "#byte is %x\n", unpack('C*',$byte);
300 *$self->{Uncomp}->resetLastBlockByte($byte);
301 #printf "#to byte is %x\n", unpack('C*',$byte);
303 ( $self->smartSeek($block_offset) &&
304 $self->smartWrite($byte) )
305 or return $self->saveErrorString(0, $!, $!);
307 #$self->smartSeek($end_offset, 1);
315 my ($def, $status) = *$self->{Uncomp}->createDeflateStream(
317 -WindowBits => - MAX_WBITS,
318 -CRC32 => *$self->{Params}->value('CRC32'),
319 -ADLER32 => *$self->{Params}->value('ADLER32'),
322 return wantarray ? ($status, $def) : $def ;
333 IO::Uncompress::RawInflate - Perl interface to read RFC 1951 files/buffers
337 use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
339 my $status = rawinflate $input => $output [,OPTS]
340 or die "rawinflate failed: $RawInflateError\n";
342 my $z = new IO::Uncompress::RawInflate $input [OPTS]
343 or die "rawinflate failed: $RawInflateError\n";
345 $status = $z->read($buffer)
346 $status = $z->read($buffer, $length)
347 $status = $z->read($buffer, $length, $offset)
348 $line = $z->getline()
351 $status = $z->inflateSync()
353 $data = $z->getHeaderInfo()
355 $z->seek($position, $whence)
367 read($z, $buffer, $length);
368 read($z, $buffer, $length, $offset);
370 seek($z, $position, $whence)
381 B<WARNING -- This is a Beta release>.
385 =item * DO NOT use in production code.
387 =item * The documentation is incomplete in places.
389 =item * Parts of the interface defined here are tentative.
391 =item * Please report any problems you find.
399 This module provides a Perl interface that allows the reading of
400 files/buffers that conform to RFC 1951.
402 For writing RFC 1951 files/buffers, see the companion module IO::Compress::RawDeflate.
406 =head1 Functional Interface
408 A top-level function, C<rawinflate>, is provided to carry out
409 "one-shot" uncompression between buffers and/or files. For finer
410 control over the uncompression process, see the L</"OO Interface">
413 use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
415 rawinflate $input => $output [,OPTS]
416 or die "rawinflate failed: $RawInflateError\n";
420 The functional interface needs Perl5.005 or better.
423 =head2 rawinflate $input => $output [, OPTS]
426 C<rawinflate> expects at least two parameters, C<$input> and C<$output>.
428 =head3 The C<$input> parameter
430 The parameter, C<$input>, is used to define the source of
433 It can take one of the following forms:
439 If the C<$input> parameter is a simple scalar, it is assumed to be a
440 filename. This file will be opened for reading and the input data
441 will be read from it.
445 If the C<$input> parameter is a filehandle, the input data will be
447 The string '-' can be used as an alias for standard input.
449 =item A scalar reference
451 If C<$input> is a scalar reference, the input data will be read
454 =item An array reference
456 If C<$input> is an array reference, each element in the array must be a
459 The input data will be read from each file in turn.
461 The complete array will be walked to ensure that it only
462 contains valid filenames before any data is uncompressed.
466 =item An Input FileGlob string
468 If C<$input> is a string that is delimited by the characters "<" and ">"
469 C<rawinflate> will assume that it is an I<input fileglob string>. The
470 input is the list of files that match the fileglob.
472 If the fileglob does not match any files ...
474 See L<File::GlobMapper|File::GlobMapper> for more details.
479 If the C<$input> parameter is any other type, C<undef> will be returned.
483 =head3 The C<$output> parameter
485 The parameter C<$output> is used to control the destination of the
486 uncompressed data. This parameter can take one of these forms.
492 If the C<$output> parameter is a simple scalar, it is assumed to be a
493 filename. This file will be opened for writing and the uncompressed
494 data will be written to it.
498 If the C<$output> parameter is a filehandle, the uncompressed data
499 will be written to it.
500 The string '-' can be used as an alias for standard output.
503 =item A scalar reference
505 If C<$output> is a scalar reference, the uncompressed data will be
506 stored in C<$$output>.
510 =item An Array Reference
512 If C<$output> is an array reference, the uncompressed data will be
513 pushed onto the array.
515 =item An Output FileGlob
517 If C<$output> is a string that is delimited by the characters "<" and ">"
518 C<rawinflate> will assume that it is an I<output fileglob string>. The
519 output is the list of files that match the fileglob.
521 When C<$output> is an fileglob string, C<$input> must also be a fileglob
522 string. Anything else is an error.
526 If the C<$output> parameter is any other type, C<undef> will be returned.
532 When C<$input> maps to multiple files/buffers and C<$output> is a single
533 file/buffer the uncompressed input files/buffers will all be stored
534 in C<$output> as a single uncompressed stream.
538 =head2 Optional Parameters
540 Unless specified below, the optional parameters for C<rawinflate>,
541 C<OPTS>, are the same as those used with the OO interface defined in the
542 L</"Constructor Options"> section below.
546 =item AutoClose =E<gt> 0|1
548 This option applies to any input or output data streams to
549 C<rawinflate> that are filehandles.
551 If C<AutoClose> is specified, and the value is true, it will result in all
552 input and/or output filehandles being closed once C<rawinflate> has
555 This parameter defaults to 0.
559 =item BinModeOut =E<gt> 0|1
561 When writing to a file or filehandle, set C<binmode> before writing to the
570 =item -Append =E<gt> 0|1
574 =item -MultiStream =E<gt> 0|1
576 Creates a new stream after each file.
589 To read the contents of the file C<file1.txt.1951> and write the
590 compressed data to the file C<file1.txt>.
594 use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
596 my $input = "file1.txt.1951";
597 my $output = "file1.txt";
598 rawinflate $input => $output
599 or die "rawinflate failed: $RawInflateError\n";
602 To read from an existing Perl filehandle, C<$input>, and write the
603 uncompressed data to a buffer, C<$buffer>.
607 use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
610 my $input = new IO::File "<file1.txt.1951"
611 or die "Cannot open 'file1.txt.1951': $!\n" ;
613 rawinflate $input => \$buffer
614 or die "rawinflate failed: $RawInflateError\n";
616 To uncompress all files in the directory "/my/home" that match "*.txt.1951" and store the compressed data in the same directory
620 use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
622 rawinflate '</my/home/*.txt.1951>' => '</my/home/#1.txt>'
623 or die "rawinflate failed: $RawInflateError\n";
625 and if you want to compress each file one at a time, this will do the trick
629 use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
631 for my $input ( glob "/my/home/*.txt.1951" )
634 $output =~ s/.1951// ;
635 rawinflate $input => $output
636 or die "Error compressing '$input': $RawInflateError\n";
643 The format of the constructor for IO::Uncompress::RawInflate is shown below
646 my $z = new IO::Uncompress::RawInflate $input [OPTS]
647 or die "IO::Uncompress::RawInflate failed: $RawInflateError\n";
649 Returns an C<IO::Uncompress::RawInflate> object on success and undef on failure.
650 The variable C<$RawInflateError> will contain an error message on failure.
652 If you are running Perl 5.005 or better the object, C<$z>, returned from
653 IO::Uncompress::RawInflate can be used exactly like an L<IO::File|IO::File> filehandle.
654 This means that all normal input file operations can be carried out with
655 C<$z>. For example, to read a line from a compressed file/buffer you can
656 use either of these forms
658 $line = $z->getline();
661 The mandatory parameter C<$input> is used to determine the source of the
662 compressed data. This parameter can take one of three forms.
668 If the C<$input> parameter is a scalar, it is assumed to be a filename. This
669 file will be opened for reading and the compressed data will be read from it.
673 If the C<$input> parameter is a filehandle, the compressed data will be
675 The string '-' can be used as an alias for standard input.
678 =item A scalar reference
680 If C<$input> is a scalar reference, the compressed data will be read from
685 =head2 Constructor Options
688 The option names defined below are case insensitive and can be optionally
689 prefixed by a '-'. So all of the following are valid
696 OPTS is a combination of the following options:
700 =item -AutoClose =E<gt> 0|1
702 This option is only valid when the C<$input> parameter is a filehandle. If
703 specified, and the value is true, it will result in the file being closed once
704 either the C<close> method is called or the IO::Uncompress::RawInflate object is
707 This parameter defaults to 0.
709 =item -MultiStream =E<gt> 0|1
713 This option is a no-op.
717 =item -Prime =E<gt> $string
719 This option will uncompress the contents of C<$string> before processing the
722 This option can be useful when the compressed data is embedded in another
723 file/data structure and it is not possible to work out where the compressed
724 data begins without having to read the first few bytes. If this is the
725 case, the uncompression can be I<primed> with these bytes using this
728 =item -Transparent =E<gt> 0|1
730 If this option is set and the input file or buffer is not compressed data,
731 the module will allow reading of it anyway.
733 This option defaults to 1.
735 =item -BlockSize =E<gt> $num
737 When reading the compressed input data, IO::Uncompress::RawInflate will read it in
738 blocks of C<$num> bytes.
740 This option defaults to 4096.
742 =item -InputLength =E<gt> $size
744 When present this option will limit the number of compressed bytes read
745 from the input file/buffer to C<$size>. This option can be used in the
746 situation where there is useful data directly after the compressed data
747 stream and you know beforehand the exact length of the compressed data
750 This option is mostly used when reading from a filehandle, in which case
751 the file pointer will be left pointing to the first byte directly after the
752 compressed data stream.
756 This option defaults to off.
758 =item -Append =E<gt> 0|1
760 This option controls what the C<read> method does with uncompressed data.
762 If set to 1, all uncompressed data will be appended to the output parameter
763 of the C<read> method.
765 If set to 0, the contents of the output parameter of the C<read> method
766 will be overwritten by the uncompressed data.
770 =item -Strict =E<gt> 0|1
774 This option is a no-op.
792 $status = $z->read($buffer)
794 Reads a block of compressed data (the size the the compressed block is
795 determined by the C<Buffer> option in the constructor), uncompresses it and
796 writes any uncompressed data into C<$buffer>. If the C<Append> parameter is
797 set in the constructor, the uncompressed data will be appended to the
798 C<$buffer> parameter. Otherwise C<$buffer> will be overwritten.
800 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
801 or a negative number on error.
807 $status = $z->read($buffer, $length)
808 $status = $z->read($buffer, $length, $offset)
810 $status = read($z, $buffer, $length)
811 $status = read($z, $buffer, $length, $offset)
813 Attempt to read C<$length> bytes of uncompressed data into C<$buffer>.
815 The main difference between this form of the C<read> method and the
816 previous one, is that this one will attempt to return I<exactly> C<$length>
817 bytes. The only circumstances that this function will not is if end-of-file
818 or an IO error is encountered.
820 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
821 or a negative number on error.
828 $line = $z->getline()
833 This method fully supports the use of of the variable C<$/>
834 (or C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use) to
835 determine what constitutes an end of line. Both paragraph mode and file
836 slurp mode are supported.
845 Read a single character.
851 $char = $z->ungetc($string)
858 $status = $z->inflateSync()
866 $hdr = $z->getHeaderInfo();
867 @hdrs = $z->getHeaderInfo();
869 This method returns either a hash reference (in scalar context) or a list
870 or hash references (in array context) that contains information about each
871 of the header fields in the compressed data stream(s).
883 Returns the uncompressed file offset.
894 Returns true if the end of the compressed input stream has been reached.
900 $z->seek($position, $whence);
901 seek($z, $position, $whence);
906 Provides a sub-set of the C<seek> functionality, with the restriction
907 that it is only legal to seek forward in the input file/buffer.
908 It is a fatal error to attempt to seek backward.
912 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
913 SEEK_CUR or SEEK_END.
915 Returns 1 on success, 0 on failure.
924 This is a noop provided for completeness.
931 If the C<$z> object is associated with a file, this method will return
932 the underlying filehandle.
934 If the C<$z> object is is associated with a buffer, this method will
944 Closes the output file/buffer.
948 For most versions of Perl this method will be automatically invoked if
949 the IO::Uncompress::RawInflate object is destroyed (either explicitly or by the
950 variable with the reference to the object going out of scope). The
951 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
952 these cases, the C<close> method will be called automatically, but
953 not until global destruction of all live objects when the program is
956 Therefore, if you want your scripts to be able to run on all versions
957 of Perl, you should call C<close> explicitly and not rely on automatic
960 Returns true on success, otherwise 0.
962 If the C<AutoClose> option has been enabled when the IO::Uncompress::RawInflate
963 object was created, and the object is associated with a file, the
964 underlying file will also be closed.
971 No symbolic constants are required by this IO::Uncompress::RawInflate at present.
977 Imports C<rawinflate> and C<$RawInflateError>.
980 use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
991 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::AnyInflate>
993 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
995 L<File::GlobMapper|File::GlobMapper>, L<Archive::Tar|Archive::Zip>,
998 For RFC 1950, 1951 and 1952 see
999 F<http://www.faqs.org/rfcs/rfc1950.html>,
1000 F<http://www.faqs.org/rfcs/rfc1951.html> and
1001 F<http://www.faqs.org/rfcs/rfc1952.html>
1003 The primary site for the gzip program is F<http://www.gzip.org>.
1007 The I<IO::Uncompress::RawInflate> module was written by Paul Marquess,
1008 F<pmqs@cpan.org>. The latest copy of the module can be
1009 found on CPAN in F<modules/by-module/Compress/Compress-Zlib-x.x.tar.gz>.
1011 The I<zlib> compression library was written by Jean-loup Gailly
1012 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1014 The primary site for the I<zlib> compression library is
1015 F<http://www.zlib.org>.
1017 =head1 MODIFICATION HISTORY
1019 See the Changes file.
1021 =head1 COPYRIGHT AND LICENSE
1024 Copyright (c) 2005-2006 Paul Marquess. All rights reserved.
1025 This program is free software; you can redistribute it and/or
1026 modify it under the same terms as Perl itself.