1 package IO::Compress::RawDeflate ;
10 use IO::Compress::Base;
11 use IO::Compress::Base::Common qw(:Status createSelfTiedObject);
12 use IO::Compress::Adapter::Deflate ;
17 our ($VERSION, @ISA, @EXPORT_OK, %DEFLATE_CONSTANTS, %EXPORT_TAGS, $RawDeflateError);
19 $VERSION = '2.000_13';
20 $RawDeflateError = '';
22 @ISA = qw(Exporter IO::Compress::Base);
23 @EXPORT_OK = qw( $RawDeflateError rawdeflate ) ;
24 push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
26 %EXPORT_TAGS = ( flush => [qw{
52 foreach (keys %EXPORT_TAGS )
54 push @{$EXPORT_TAGS{constants}},
58 $EXPORT_TAGS{all} = $EXPORT_TAGS{constants} ;
61 %DEFLATE_CONSTANTS = %EXPORT_TAGS;
63 Exporter::export_ok_tags('all');
71 my $obj = createSelfTiedObject($class, \$RawDeflateError);
73 return $obj->_create(undef, @_);
78 my $obj = createSelfTiedObject(undef, \$RawDeflateError);
79 return $obj->_def(@_);
96 my ($obj, $errstr, $errno) = IO::Compress::Adapter::Deflate::mkCompObject(
98 $got->value('Adler32'),
100 $got->value('Strategy')
103 return $self->saveErrorString(undef, $errstr, $errno)
137 return $self->getZlibParams();
144 use IO::Compress::Base::Common qw(:Parse);
145 use Compress::Raw::Zlib qw(Z_DEFLATED Z_DEFAULT_COMPRESSION Z_DEFAULT_STRATEGY);
151 #'Method' => [0, 1, Parse_unsigned, Z_DEFLATED],
152 'Level' => [0, 1, Parse_signed, Z_DEFAULT_COMPRESSION],
153 'Strategy' => [0, 1, Parse_signed, Z_DEFAULT_STRATEGY],
155 'CRC32' => [0, 1, Parse_boolean, 0],
156 'ADLER32' => [0, 1, Parse_boolean, 0],
157 'Merge' => [1, 1, Parse_boolean, 0],
165 return ('IO::Uncompress::RawInflate',
166 \$IO::Uncompress::RawInflate::RawInflateError);
177 use IO::Seekable qw(SEEK_SET);
182 my $outValue = shift ;
183 my $outType = shift ;
185 my ($invClass, $error_ref) = $self->getInverseClass();
186 eval "require $invClass"
189 my $inf = $invClass->new( $outValue,
194 or return $self->saveErrorString(undef, "Cannot create InflateScan object: $$error_ref" ) ;
198 or return $self->saveErrorString(undef, "Error Scanning: $$error_ref", $inf->errorNo) ;
199 $inf->zap($end_offset)
200 or return $self->saveErrorString(undef, "Error Zapping: $$error_ref", $inf->errorNo) ;
202 my $def = *$self->{Compress} = $inf->createDeflate();
204 *$self->{Header} = *$inf->{Info}{Header};
205 *$self->{UnCompSize} = *$inf->{UnCompSize}->clone();
206 *$self->{CompSize} = *$inf->{CompSize}->clone();
208 #*$self->{CompSize} = new U64(0, *$self->{UnCompSize_32bit});
211 if ( $outType eq 'buffer')
212 { substr( ${ *$self->{Buffer} }, $end_offset) = '' }
213 elsif ($outType eq 'handle' || $outType eq 'filename') {
214 *$self->{FH} = *$inf->{FH} ;
216 *$self->{FH}->flush() ;
217 *$self->{Handle} = 1 if $outType eq 'handle';
219 #seek(*$self->{FH}, $end_offset, SEEK_SET)
220 *$self->{FH}->seek($end_offset, SEEK_SET)
221 or return $self->saveErrorString(undef, $!, $!) ;
227 #### zlib specific methods
234 my $strategy = shift ;
236 my $status = *$self->{Compress}->deflateParams(Level => $level, Strategy => $strategy) ;
237 return $self->saveErrorString(0, *$self->{Compress}{Error}, *$self->{Compress}{ErrorNo})
238 if $status == STATUS_ERROR;
254 IO::Compress::RawDeflate - Write RFC 1951 files/buffers
260 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
263 my $status = rawdeflate $input => $output [,OPTS]
264 or die "rawdeflate failed: $RawDeflateError\n";
266 my $z = new IO::Compress::RawDeflate $output [,OPTS]
267 or die "rawdeflate failed: $RawDeflateError\n";
270 $z->printf($format, $string);
272 $z->syswrite($string [, $length, $offset]);
276 $z->seek($position, $whence);
281 $z->input_line_number();
282 $z->newStream( [OPTS] );
293 printf $z $format, $string;
296 seek $z, $position, $whence
306 B<WARNING -- This is a Beta release>.
310 =item * DO NOT use in production code.
312 =item * The documentation is incomplete in places.
314 =item * Parts of the interface defined here are tentative.
316 =item * Please report any problems you find.
323 This module provides a Perl interface that allows writing compressed
324 data to files or buffer as defined in RFC 1951.
330 Note that RFC 1951 data is not a good choice of compression format
331 to use in isolation, especially if you want to auto-detect it.
337 For reading RFC 1951 files/buffers, see the companion module
338 L<IO::Uncompress::RawInflate|IO::Uncompress::RawInflate>.
341 =head1 Functional Interface
343 A top-level function, C<rawdeflate>, is provided to carry out
344 "one-shot" compression between buffers and/or files. For finer
345 control over the compression process, see the L</"OO Interface">
348 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
350 rawdeflate $input => $output [,OPTS]
351 or die "rawdeflate failed: $RawDeflateError\n";
355 The functional interface needs Perl5.005 or better.
358 =head2 rawdeflate $input => $output [, OPTS]
361 C<rawdeflate> expects at least two parameters, C<$input> and C<$output>.
363 =head3 The C<$input> parameter
365 The parameter, C<$input>, is used to define the source of
366 the uncompressed data.
368 It can take one of the following forms:
374 If the C<$input> parameter is a simple scalar, it is assumed to be a
375 filename. This file will be opened for reading and the input data
376 will be read from it.
380 If the C<$input> parameter is a filehandle, the input data will be
382 The string '-' can be used as an alias for standard input.
384 =item A scalar reference
386 If C<$input> is a scalar reference, the input data will be read
389 =item An array reference
391 If C<$input> is an array reference, each element in the array must be a
394 The input data will be read from each file in turn.
396 The complete array will be walked to ensure that it only
397 contains valid filenames before any data is compressed.
401 =item An Input FileGlob string
403 If C<$input> is a string that is delimited by the characters "<" and ">"
404 C<rawdeflate> will assume that it is an I<input fileglob string>. The
405 input is the list of files that match the fileglob.
407 If the fileglob does not match any files ...
409 See L<File::GlobMapper|File::GlobMapper> for more details.
414 If the C<$input> parameter is any other type, C<undef> will be returned.
418 =head3 The C<$output> parameter
420 The parameter C<$output> is used to control the destination of the
421 compressed data. This parameter can take one of these forms.
427 If the C<$output> parameter is a simple scalar, it is assumed to be a
428 filename. This file will be opened for writing and the compressed
429 data will be written to it.
433 If the C<$output> parameter is a filehandle, the compressed data
434 will be written to it.
435 The string '-' can be used as an alias for standard output.
438 =item A scalar reference
440 If C<$output> is a scalar reference, the compressed data will be
441 stored in C<$$output>.
445 =item An Array Reference
447 If C<$output> is an array reference, the compressed data will be
448 pushed onto the array.
450 =item An Output FileGlob
452 If C<$output> is a string that is delimited by the characters "<" and ">"
453 C<rawdeflate> will assume that it is an I<output fileglob string>. The
454 output is the list of files that match the fileglob.
456 When C<$output> is an fileglob string, C<$input> must also be a fileglob
457 string. Anything else is an error.
461 If the C<$output> parameter is any other type, C<undef> will be returned.
469 When C<$input> maps to multiple files/buffers and C<$output> is a single
470 file/buffer the input files/buffers will be stored
471 in C<$output> as a concatenated series of compressed data streams.
478 =head2 Optional Parameters
480 Unless specified below, the optional parameters for C<rawdeflate>,
481 C<OPTS>, are the same as those used with the OO interface defined in the
482 L</"Constructor Options"> section below.
486 =item C<< AutoClose => 0|1 >>
488 This option applies to any input or output data streams to
489 C<rawdeflate> that are filehandles.
491 If C<AutoClose> is specified, and the value is true, it will result in all
492 input and/or output filehandles being closed once C<rawdeflate> has
495 This parameter defaults to 0.
498 =item C<< BinModeIn => 0|1 >>
500 When reading from a file or filehandle, set C<binmode> before reading.
508 =item C<< Append => 0|1 >>
519 To read the contents of the file C<file1.txt> and write the compressed
520 data to the file C<file1.txt.1951>.
524 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
526 my $input = "file1.txt";
527 rawdeflate $input => "$input.1951"
528 or die "rawdeflate failed: $RawDeflateError\n";
531 To read from an existing Perl filehandle, C<$input>, and write the
532 compressed data to a buffer, C<$buffer>.
536 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
539 my $input = new IO::File "<file1.txt"
540 or die "Cannot open 'file1.txt': $!\n" ;
542 rawdeflate $input => \$buffer
543 or die "rawdeflate failed: $RawDeflateError\n";
545 To compress all files in the directory "/my/home" that match "*.txt"
546 and store the compressed data in the same directory
550 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
552 rawdeflate '</my/home/*.txt>' => '<*.1951>'
553 or die "rawdeflate failed: $RawDeflateError\n";
555 and if you want to compress each file one at a time, this will do the trick
559 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
561 for my $input ( glob "/my/home/*.txt" )
563 my $output = "$input.1951" ;
564 rawdeflate $input => $output
565 or die "Error compressing '$input': $RawDeflateError\n";
573 The format of the constructor for C<IO::Compress::RawDeflate> is shown below
575 my $z = new IO::Compress::RawDeflate $output [,OPTS]
576 or die "IO::Compress::RawDeflate failed: $RawDeflateError\n";
578 It returns an C<IO::Compress::RawDeflate> object on success and undef on failure.
579 The variable C<$RawDeflateError> will contain an error message on failure.
581 If you are running Perl 5.005 or better the object, C<$z>, returned from
582 IO::Compress::RawDeflate can be used exactly like an L<IO::File|IO::File> filehandle.
583 This means that all normal output file operations can be carried out
585 For example, to write to a compressed file/buffer you can use either of
588 $z->print("hello world\n");
589 print $z "hello world\n";
591 The mandatory parameter C<$output> is used to control the destination
592 of the compressed data. This parameter can take one of these forms.
598 If the C<$output> parameter is a simple scalar, it is assumed to be a
599 filename. This file will be opened for writing and the compressed data
600 will be written to it.
604 If the C<$output> parameter is a filehandle, the compressed data will be
606 The string '-' can be used as an alias for standard output.
609 =item A scalar reference
611 If C<$output> is a scalar reference, the compressed data will be stored
616 If the C<$output> parameter is any other type, C<IO::Compress::RawDeflate>::new will
619 =head2 Constructor Options
621 C<OPTS> is any combination of the following options:
625 =item C<< AutoClose => 0|1 >>
627 This option is only valid when the C<$output> parameter is a filehandle. If
628 specified, and the value is true, it will result in the C<$output> being
629 closed once either the C<close> method is called or the C<IO::Compress::RawDeflate>
632 This parameter defaults to 0.
634 =item C<< Append => 0|1 >>
636 Opens C<$output> in append mode.
638 The behaviour of this option is dependent on the type of C<$output>.
644 If C<$output> is a buffer and C<Append> is enabled, all compressed data
645 will be append to the end if C<$output>. Otherwise C<$output> will be
646 cleared before any data is written to it.
650 If C<$output> is a filename and C<Append> is enabled, the file will be
651 opened in append mode. Otherwise the contents of the file, if any, will be
652 truncated before any compressed data is written to it.
656 If C<$output> is a filehandle, the file pointer will be positioned to the
657 end of the file via a call to C<seek> before any compressed data is written
658 to it. Otherwise the file pointer will not be moved.
662 This parameter defaults to 0.
668 =item C<< Merge => 0|1 >>
670 This option is used to compress input data and append it to an existing
671 compressed data stream in C<$output>. The end result is a single compressed
672 data stream stored in C<$output>.
676 It is a fatal error to attempt to use this option when C<$output> is not an
677 RFC 1951 data stream.
681 There are a number of other limitations with the C<Merge> option:
687 This module needs to have been built with zlib 1.2.1 or better to work. A
688 fatal error will be thrown if C<Merge> is used with an older version of
693 If C<$output> is a file or a filehandle, it must be seekable.
698 This parameter defaults to 0.
704 Defines the compression level used by zlib. The value should either be
705 a number between 0 and 9 (0 means no compression and 9 is maximum
706 compression), or one of the symbolic constants defined below.
711 Z_DEFAULT_COMPRESSION
713 The default is Z_DEFAULT_COMPRESSION.
715 Note, these constants are not imported by C<IO::Compress::RawDeflate> by default.
717 use IO::Compress::RawDeflate qw(:strategy);
718 use IO::Compress::RawDeflate qw(:constants);
719 use IO::Compress::RawDeflate qw(:all);
723 Defines the strategy used to tune the compression. Use one of the symbolic
724 constants defined below.
732 The default is Z_DEFAULT_STRATEGY.
739 =item C<< Strict => 0|1 >>
743 This is a placeholder option.
762 Compresses and outputs the contents of the C<$data> parameter. This
763 has the same behaviour as the C<print> built-in.
765 Returns true if successful.
771 $z->printf($format, $data)
772 printf $z $format, $data
774 Compresses and outputs the contents of the C<$data> parameter.
776 Returns true if successful.
783 $z->syswrite $data, $length
784 $z->syswrite $data, $length, $offset
786 Compresses and outputs the contents of the C<$data> parameter.
788 Returns the number of uncompressed bytes written, or C<undef> if
796 $z->write $data, $length
797 $z->write $data, $length, $offset
799 Compresses and outputs the contents of the C<$data> parameter.
801 Returns the number of uncompressed bytes written, or C<undef> if
810 $z->flush($flush_type);
813 Flushes any pending compressed data to the output file/buffer.
816 This method takes an optional parameter, C<$flush_type>, that controls
817 how the flushing will be carried out. By default the C<$flush_type>
818 used is C<Z_FINISH>. Other valid values for C<$flush_type> are
819 C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
820 strongly recommended that you only set the C<flush_type> parameter if
821 you fully understand the implications of what it does - overuse of C<flush>
822 can seriously degrade the level of compression achieved. See the C<zlib>
823 documentation for details.
826 Returns true on success.
836 Returns the uncompressed file offset.
847 Returns true if the C<close> method has been called.
853 $z->seek($position, $whence);
854 seek($z, $position, $whence);
859 Provides a sub-set of the C<seek> functionality, with the restriction
860 that it is only legal to seek forward in the output file/buffer.
861 It is a fatal error to attempt to seek backward.
863 Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
867 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
868 SEEK_CUR or SEEK_END.
870 Returns 1 on success, 0 on failure.
879 This is a noop provided for completeness.
885 Returns true if the object currently refers to a opened file/buffer.
889 my $prev = $z->autoflush()
890 my $prev = $z->autoflush(EXPR)
892 If the C<$z> object is associated with a file or a filehandle, this method
893 returns the current autoflush setting for the underlying filehandle. If
894 C<EXPR> is present, and is non-zero, it will enable flushing after every
895 write/print operation.
897 If C<$z> is associated with a buffer, this method has no effect and always
900 B<Note> that the special variable C<$|> B<cannot> be used to set or
901 retrieve the autoflush setting.
903 =head2 input_line_number
905 $z->input_line_number()
906 $z->input_line_number(EXPR)
909 This method always returns C<undef> when compressing.
918 If the C<$z> object is associated with a file or a filehandle, this method
919 will return the underlying file descriptor.
921 If the C<$z> object is is associated with a buffer, this method will
931 Flushes any pending compressed data and then closes the output file/buffer.
935 For most versions of Perl this method will be automatically invoked if
936 the IO::Compress::RawDeflate object is destroyed (either explicitly or by the
937 variable with the reference to the object going out of scope). The
938 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
939 these cases, the C<close> method will be called automatically, but
940 not until global destruction of all live objects when the program is
943 Therefore, if you want your scripts to be able to run on all versions
944 of Perl, you should call C<close> explicitly and not rely on automatic
947 Returns true on success, otherwise 0.
949 If the C<AutoClose> option has been enabled when the IO::Compress::RawDeflate
950 object was created, and the object is associated with a file, the
951 underlying file will also be closed.
956 =head2 newStream([OPTS])
960 $z->newStream( [OPTS] )
962 Closes the current compressed data stream and starts a new one.
964 OPTS consists of any of the the options that are available when creating
967 See the L</"Constructor Options"> section for more details.
982 A number of symbolic constants are required by some methods in
983 C<IO::Compress::RawDeflate>. None are imported by default.
992 Imports C<rawdeflate>, C<$RawDeflateError> and all symbolic
993 constants that can be used by C<IO::Compress::RawDeflate>. Same as doing this
995 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError :constants) ;
999 Import all symbolic constants. Same as doing this
1002 use IO::Compress::RawDeflate qw(:flush :level :strategy) ;
1007 These symbolic constants are used by the C<flush> method.
1018 These symbolic constants are used by the C<Level> option in the constructor.
1023 Z_DEFAULT_COMPRESSION
1028 These symbolic constants are used by the C<Strategy> option in the constructor.
1059 L<Compress::Zlib>, L<IO::Compress::Gzip>, L<IO::Uncompress::Gunzip>, L<IO::Compress::Deflate>, L<IO::Uncompress::Inflate>, L<IO::Uncompress::RawInflate>, L<IO::Compress::Bzip2>, L<IO::Uncompress::Bunzip2>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
1061 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1063 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1064 L<Archive::Tar|Archive::Tar>,
1065 L<IO::Zlib|IO::Zlib>
1068 For RFC 1950, 1951 and 1952 see
1069 F<http://www.faqs.org/rfcs/rfc1950.html>,
1070 F<http://www.faqs.org/rfcs/rfc1951.html> and
1071 F<http://www.faqs.org/rfcs/rfc1952.html>
1073 The I<zlib> compression library was written by Jean-loup Gailly
1074 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1076 The primary site for the I<zlib> compression library is
1077 F<http://www.zlib.org>.
1079 The primary site for gzip is F<http://www.gzip.org>.
1086 This module was written by Paul Marquess, F<pmqs@cpan.org>.
1090 =head1 MODIFICATION HISTORY
1092 See the Changes file.
1094 =head1 COPYRIGHT AND LICENSE
1096 Copyright (c) 2005-2006 Paul Marquess. All rights reserved.
1098 This program is free software; you can redistribute it and/or
1099 modify it under the same terms as Perl itself.