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);
20 $VERSION = '2.000_08';
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();
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 ;
334 IO::Uncompress::RawInflate - Perl interface to read RFC 1951 files/buffers
339 use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
341 my $status = rawinflate $input => $output [,OPTS]
342 or die "rawinflate failed: $RawInflateError\n";
344 my $z = new IO::Uncompress::RawInflate $input [OPTS]
345 or die "rawinflate failed: $RawInflateError\n";
347 $status = $z->read($buffer)
348 $status = $z->read($buffer, $length)
349 $status = $z->read($buffer, $length, $offset)
350 $line = $z->getline()
355 $status = $z->inflateSync()
358 $data = $z->getHeaderInfo()
360 $z->seek($position, $whence)
372 read($z, $buffer, $length);
373 read($z, $buffer, $length, $offset);
375 seek($z, $position, $whence)
386 B<WARNING -- This is a Beta release>.
390 =item * DO NOT use in production code.
392 =item * The documentation is incomplete in places.
394 =item * Parts of the interface defined here are tentative.
396 =item * Please report any problems you find.
404 This module provides a Perl interface that allows the reading of
405 files/buffers that conform to RFC 1951.
407 For writing RFC 1951 files/buffers, see the companion module IO::Compress::RawDeflate.
411 =head1 Functional Interface
413 A top-level function, C<rawinflate>, is provided to carry out
414 "one-shot" uncompression between buffers and/or files. For finer
415 control over the uncompression process, see the L</"OO Interface">
418 use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
420 rawinflate $input => $output [,OPTS]
421 or die "rawinflate failed: $RawInflateError\n";
425 The functional interface needs Perl5.005 or better.
428 =head2 rawinflate $input => $output [, OPTS]
431 C<rawinflate> expects at least two parameters, C<$input> and C<$output>.
433 =head3 The C<$input> parameter
435 The parameter, C<$input>, is used to define the source of
438 It can take one of the following forms:
444 If the C<$input> parameter is a simple scalar, it is assumed to be a
445 filename. This file will be opened for reading and the input data
446 will be read from it.
450 If the C<$input> parameter is a filehandle, the input data will be
452 The string '-' can be used as an alias for standard input.
454 =item A scalar reference
456 If C<$input> is a scalar reference, the input data will be read
459 =item An array reference
461 If C<$input> is an array reference, each element in the array must be a
464 The input data will be read from each file in turn.
466 The complete array will be walked to ensure that it only
467 contains valid filenames before any data is uncompressed.
471 =item An Input FileGlob string
473 If C<$input> is a string that is delimited by the characters "<" and ">"
474 C<rawinflate> will assume that it is an I<input fileglob string>. The
475 input is the list of files that match the fileglob.
477 If the fileglob does not match any files ...
479 See L<File::GlobMapper|File::GlobMapper> for more details.
484 If the C<$input> parameter is any other type, C<undef> will be returned.
488 =head3 The C<$output> parameter
490 The parameter C<$output> is used to control the destination of the
491 uncompressed data. This parameter can take one of these forms.
497 If the C<$output> parameter is a simple scalar, it is assumed to be a
498 filename. This file will be opened for writing and the uncompressed
499 data will be written to it.
503 If the C<$output> parameter is a filehandle, the uncompressed data
504 will be written to it.
505 The string '-' can be used as an alias for standard output.
508 =item A scalar reference
510 If C<$output> is a scalar reference, the uncompressed data will be
511 stored in C<$$output>.
515 =item An Array Reference
517 If C<$output> is an array reference, the uncompressed data will be
518 pushed onto the array.
520 =item An Output FileGlob
522 If C<$output> is a string that is delimited by the characters "<" and ">"
523 C<rawinflate> will assume that it is an I<output fileglob string>. The
524 output is the list of files that match the fileglob.
526 When C<$output> is an fileglob string, C<$input> must also be a fileglob
527 string. Anything else is an error.
531 If the C<$output> parameter is any other type, C<undef> will be returned.
537 When C<$input> maps to multiple files/buffers and C<$output> is a single
538 file/buffer the uncompressed input files/buffers will all be stored
539 in C<$output> as a single uncompressed stream.
543 =head2 Optional Parameters
545 Unless specified below, the optional parameters for C<rawinflate>,
546 C<OPTS>, are the same as those used with the OO interface defined in the
547 L</"Constructor Options"> section below.
551 =item AutoClose =E<gt> 0|1
553 This option applies to any input or output data streams to
554 C<rawinflate> that are filehandles.
556 If C<AutoClose> is specified, and the value is true, it will result in all
557 input and/or output filehandles being closed once C<rawinflate> has
560 This parameter defaults to 0.
564 =item BinModeOut =E<gt> 0|1
566 When writing to a file or filehandle, set C<binmode> before writing to the
575 =item -Append =E<gt> 0|1
579 =item -MultiStream =E<gt> 0|1
581 Creates a new stream after each file.
594 To read the contents of the file C<file1.txt.1951> and write the
595 compressed data to the file C<file1.txt>.
599 use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
601 my $input = "file1.txt.1951";
602 my $output = "file1.txt";
603 rawinflate $input => $output
604 or die "rawinflate failed: $RawInflateError\n";
607 To read from an existing Perl filehandle, C<$input>, and write the
608 uncompressed data to a buffer, C<$buffer>.
612 use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
615 my $input = new IO::File "<file1.txt.1951"
616 or die "Cannot open 'file1.txt.1951': $!\n" ;
618 rawinflate $input => \$buffer
619 or die "rawinflate failed: $RawInflateError\n";
621 To uncompress all files in the directory "/my/home" that match "*.txt.1951" and store the compressed data in the same directory
625 use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
627 rawinflate '</my/home/*.txt.1951>' => '</my/home/#1.txt>'
628 or die "rawinflate failed: $RawInflateError\n";
630 and if you want to compress each file one at a time, this will do the trick
634 use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
636 for my $input ( glob "/my/home/*.txt.1951" )
639 $output =~ s/.1951// ;
640 rawinflate $input => $output
641 or die "Error compressing '$input': $RawInflateError\n";
648 The format of the constructor for IO::Uncompress::RawInflate is shown below
651 my $z = new IO::Uncompress::RawInflate $input [OPTS]
652 or die "IO::Uncompress::RawInflate failed: $RawInflateError\n";
654 Returns an C<IO::Uncompress::RawInflate> object on success and undef on failure.
655 The variable C<$RawInflateError> will contain an error message on failure.
657 If you are running Perl 5.005 or better the object, C<$z>, returned from
658 IO::Uncompress::RawInflate can be used exactly like an L<IO::File|IO::File> filehandle.
659 This means that all normal input file operations can be carried out with
660 C<$z>. For example, to read a line from a compressed file/buffer you can
661 use either of these forms
663 $line = $z->getline();
666 The mandatory parameter C<$input> is used to determine the source of the
667 compressed data. This parameter can take one of three forms.
673 If the C<$input> parameter is a scalar, it is assumed to be a filename. This
674 file will be opened for reading and the compressed data will be read from it.
678 If the C<$input> parameter is a filehandle, the compressed data will be
680 The string '-' can be used as an alias for standard input.
683 =item A scalar reference
685 If C<$input> is a scalar reference, the compressed data will be read from
690 =head2 Constructor Options
693 The option names defined below are case insensitive and can be optionally
694 prefixed by a '-'. So all of the following are valid
701 OPTS is a combination of the following options:
705 =item -AutoClose =E<gt> 0|1
707 This option is only valid when the C<$input> parameter is a filehandle. If
708 specified, and the value is true, it will result in the file being closed once
709 either the C<close> method is called or the IO::Uncompress::RawInflate object is
712 This parameter defaults to 0.
714 =item -MultiStream =E<gt> 0|1
718 This option is a no-op.
722 =item -Prime =E<gt> $string
724 This option will uncompress the contents of C<$string> before processing the
727 This option can be useful when the compressed data is embedded in another
728 file/data structure and it is not possible to work out where the compressed
729 data begins without having to read the first few bytes. If this is the
730 case, the uncompression can be I<primed> with these bytes using this
733 =item -Transparent =E<gt> 0|1
735 If this option is set and the input file or buffer is not compressed data,
736 the module will allow reading of it anyway.
738 This option defaults to 1.
740 =item -BlockSize =E<gt> $num
742 When reading the compressed input data, IO::Uncompress::RawInflate will read it in
743 blocks of C<$num> bytes.
745 This option defaults to 4096.
747 =item -InputLength =E<gt> $size
749 When present this option will limit the number of compressed bytes read
750 from the input file/buffer to C<$size>. This option can be used in the
751 situation where there is useful data directly after the compressed data
752 stream and you know beforehand the exact length of the compressed data
755 This option is mostly used when reading from a filehandle, in which case
756 the file pointer will be left pointing to the first byte directly after the
757 compressed data stream.
761 This option defaults to off.
763 =item -Append =E<gt> 0|1
765 This option controls what the C<read> method does with uncompressed data.
767 If set to 1, all uncompressed data will be appended to the output parameter
768 of the C<read> method.
770 If set to 0, the contents of the output parameter of the C<read> method
771 will be overwritten by the uncompressed data.
775 =item -Strict =E<gt> 0|1
779 This option is a no-op.
798 $status = $z->read($buffer)
800 Reads a block of compressed data (the size the the compressed block is
801 determined by the C<Buffer> option in the constructor), uncompresses it and
802 writes any uncompressed data into C<$buffer>. If the C<Append> parameter is
803 set in the constructor, the uncompressed data will be appended to the
804 C<$buffer> parameter. Otherwise C<$buffer> will be overwritten.
806 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
807 or a negative number on error.
813 $status = $z->read($buffer, $length)
814 $status = $z->read($buffer, $length, $offset)
816 $status = read($z, $buffer, $length)
817 $status = read($z, $buffer, $length, $offset)
819 Attempt to read C<$length> bytes of uncompressed data into C<$buffer>.
821 The main difference between this form of the C<read> method and the
822 previous one, is that this one will attempt to return I<exactly> C<$length>
823 bytes. The only circumstances that this function will not is if end-of-file
824 or an IO error is encountered.
826 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
827 or a negative number on error.
834 $line = $z->getline()
839 This method fully supports the use of of the variable C<$/>
840 (or C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use) to
841 determine what constitutes an end of line. Both paragraph mode and file
842 slurp mode are supported.
851 Read a single character.
857 $char = $z->ungetc($string)
865 $status = $z->inflateSync()
874 $hdr = $z->getHeaderInfo();
875 @hdrs = $z->getHeaderInfo();
877 This method returns either a hash reference (in scalar context) or a list
878 or hash references (in array context) that contains information about each
879 of the header fields in the compressed data stream(s).
891 Returns the uncompressed file offset.
902 Returns true if the end of the compressed input stream has been reached.
908 $z->seek($position, $whence);
909 seek($z, $position, $whence);
914 Provides a sub-set of the C<seek> functionality, with the restriction
915 that it is only legal to seek forward in the input file/buffer.
916 It is a fatal error to attempt to seek backward.
920 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
921 SEEK_CUR or SEEK_END.
923 Returns 1 on success, 0 on failure.
932 This is a noop provided for completeness.
938 Returns true if the object currently refers to a opened file/buffer.
942 my $prev = $z->autoflush()
943 my $prev = $z->autoflush(EXPR)
945 If the C<$z> object is associated with a file or a filehandle, this method
946 returns the current autoflush setting for the underlying filehandle. If
947 C<EXPR> is present, and is non-zero, it will enable flushing after every
948 write/print operation.
950 If C<$z> is associated with a buffer, this method has no effect and always
953 B<Note> that the special variable C<$|> B<cannot> be used to set or
954 retrieve the autoflush setting.
956 =head2 input_line_number
958 $z->input_line_number()
959 $z->input_line_number(EXPR)
963 Returns the current uncompressed line number. If C<EXPR> is present it has
964 the effect of setting the line number. Note that setting the line number
965 does not change the current position within the file/buffer being read.
967 The contents of C<$/> are used to to determine what constitutes a line
977 If the C<$z> object is associated with a file or a filehandle, this method
978 will return the underlying file descriptor.
980 If the C<$z> object is is associated with a buffer, this method will
990 Closes the output file/buffer.
994 For most versions of Perl this method will be automatically invoked if
995 the IO::Uncompress::RawInflate object is destroyed (either explicitly or by the
996 variable with the reference to the object going out of scope). The
997 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
998 these cases, the C<close> method will be called automatically, but
999 not until global destruction of all live objects when the program is
1002 Therefore, if you want your scripts to be able to run on all versions
1003 of Perl, you should call C<close> explicitly and not rely on automatic
1006 Returns true on success, otherwise 0.
1008 If the C<AutoClose> option has been enabled when the IO::Uncompress::RawInflate
1009 object was created, and the object is associated with a file, the
1010 underlying file will also be closed.
1017 No symbolic constants are required by this IO::Uncompress::RawInflate at present.
1023 Imports C<rawinflate> and C<$RawInflateError>.
1026 use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
1037 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::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
1039 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1041 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1042 L<Archive::Tar|Archive::Tar>,
1043 L<IO::Zlib|IO::Zlib>
1046 For RFC 1950, 1951 and 1952 see
1047 F<http://www.faqs.org/rfcs/rfc1950.html>,
1048 F<http://www.faqs.org/rfcs/rfc1951.html> and
1049 F<http://www.faqs.org/rfcs/rfc1952.html>
1051 The I<zlib> compression library was written by Jean-loup Gailly
1052 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1054 The primary site for the I<zlib> compression library is
1055 F<http://www.zlib.org>.
1057 The primary site for gzip is F<http://www.gzip.org>.
1067 The I<IO::Uncompress::RawInflate> module was written by Paul Marquess,
1072 =head1 MODIFICATION HISTORY
1074 See the Changes file.
1076 =head1 COPYRIGHT AND LICENSE
1079 Copyright (c) 2005-2006 Paul Marquess. All rights reserved.
1081 This program is free software; you can redistribute it and/or
1082 modify it under the same terms as Perl itself.