1 package IO::Compress::RawDeflate ;
9 use IO::Compress::Base;
10 use CompressPlugin::Deflate ;
13 use Compress::Zlib::Common qw(:Status createSelfTiedObject);
16 our ($VERSION, @ISA, @EXPORT_OK, %DEFLATE_CONSTANTS, %EXPORT_TAGS, $RawDeflateError);
18 $VERSION = '2.000_07';
19 $RawDeflateError = '';
21 @ISA = qw(Exporter IO::Compress::Base);
22 @EXPORT_OK = qw( $RawDeflateError rawdeflate ) ;
23 push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
25 %EXPORT_TAGS = ( flush => [qw{
51 foreach (keys %EXPORT_TAGS )
53 push @{$EXPORT_TAGS{constants}},
57 $EXPORT_TAGS{all} = $EXPORT_TAGS{constants} ;
60 %DEFLATE_CONSTANTS = %EXPORT_TAGS;
62 Exporter::export_ok_tags('all');
70 my $obj = createSelfTiedObject($class, \$RawDeflateError);
72 return $obj->_create(undef, @_);
77 my $obj = createSelfTiedObject(undef, \$RawDeflateError);
78 return $obj->_def(@_);
95 #return CompressPlugin::Deflate::mkCompObject($self, $class, $got)
96 my ($obj, $errstr, $errno) = CompressPlugin::Deflate::mkCompObject(
98 $got->value('Adler32'),
100 $got->value('Strategy')
103 return $self->saveErrorString(undef, $errstr, $errno)
137 return $self->getZlibParams();
144 use Compress::Zlib::ParseParameters;
145 use Compress::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_32bit} =
206 *$self->{BytesWritten} = *$inf->{UnCompSize_32bit} ;
209 if ( $outType eq 'buffer')
210 { substr( ${ *$self->{Buffer} }, $end_offset) = '' }
211 elsif ($outType eq 'handle' || $outType eq 'filename') {
212 *$self->{FH} = *$inf->{FH} ;
214 *$self->{FH}->flush() ;
215 *$self->{Handle} = 1 if $outType eq 'handle';
217 #seek(*$self->{FH}, $end_offset, SEEK_SET)
218 *$self->{FH}->seek($end_offset, SEEK_SET)
219 or return $self->saveErrorString(undef, $!, $!) ;
225 #### zlib specific methods
232 my $strategy = shift ;
234 my $status = *$self->{Compress}->deflateParams(Level => $level, Strategy => $strategy) ;
235 return $self->saveErrorString(0, *$self->{Compress}{Error}, *$self->{Compress}{ErrorNo})
236 if $status == STATUS_ERROR;
250 IO::Compress::RawDeflate - Perl interface to write RFC 1951 files/buffers
254 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
257 my $status = rawdeflate $input => $output [,OPTS]
258 or die "rawdeflate failed: $RawDeflateError\n";
260 my $z = new IO::Compress::RawDeflate $output [,OPTS]
261 or die "rawdeflate failed: $RawDeflateError\n";
264 $z->printf($format, $string);
266 $z->syswrite($string [, $length, $offset]);
270 $z->seek($position, $whence);
273 $z->newStream( [OPTS] );
282 printf $z $format, $string;
283 syswrite $z, $string [, $length, $offset];
287 seek $z, $position, $whence
297 B<WARNING -- This is a Beta release>.
301 =item * DO NOT use in production code.
303 =item * The documentation is incomplete in places.
305 =item * Parts of the interface defined here are tentative.
307 =item * Please report any problems you find.
313 This module provides a Perl interface that allows writing compressed
314 data to files or buffer as defined in RFC 1951.
319 Note that RFC1951 data is not a good choice of compression format
320 to use in isolation, especially if you want to auto-detect it.
323 For reading RFC 1951 files/buffers, see the companion module
324 L<IO::Uncompress::RawInflate|IO::Uncompress::RawInflate>.
327 =head1 Functional Interface
329 A top-level function, C<rawdeflate>, is provided to carry out
330 "one-shot" compression between buffers and/or files. For finer
331 control over the compression process, see the L</"OO Interface">
334 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
336 rawdeflate $input => $output [,OPTS]
337 or die "rawdeflate failed: $RawDeflateError\n";
341 The functional interface needs Perl5.005 or better.
344 =head2 rawdeflate $input => $output [, OPTS]
347 C<rawdeflate> expects at least two parameters, C<$input> and C<$output>.
349 =head3 The C<$input> parameter
351 The parameter, C<$input>, is used to define the source of
352 the uncompressed data.
354 It can take one of the following forms:
360 If the C<$input> parameter is a simple scalar, it is assumed to be a
361 filename. This file will be opened for reading and the input data
362 will be read from it.
366 If the C<$input> parameter is a filehandle, the input data will be
368 The string '-' can be used as an alias for standard input.
370 =item A scalar reference
372 If C<$input> is a scalar reference, the input data will be read
375 =item An array reference
377 If C<$input> is an array reference, each element in the array must be a
380 The input data will be read from each file in turn.
382 The complete array will be walked to ensure that it only
383 contains valid filenames before any data is compressed.
387 =item An Input FileGlob string
389 If C<$input> is a string that is delimited by the characters "<" and ">"
390 C<rawdeflate> will assume that it is an I<input fileglob string>. The
391 input is the list of files that match the fileglob.
393 If the fileglob does not match any files ...
395 See L<File::GlobMapper|File::GlobMapper> for more details.
400 If the C<$input> parameter is any other type, C<undef> will be returned.
404 =head3 The C<$output> parameter
406 The parameter C<$output> is used to control the destination of the
407 compressed data. This parameter can take one of these forms.
413 If the C<$output> parameter is a simple scalar, it is assumed to be a
414 filename. This file will be opened for writing and the compressed
415 data will be written to it.
419 If the C<$output> parameter is a filehandle, the compressed data
420 will be written to it.
421 The string '-' can be used as an alias for standard output.
424 =item A scalar reference
426 If C<$output> is a scalar reference, the compressed data will be
427 stored in C<$$output>.
431 =item An Array Reference
433 If C<$output> is an array reference, the compressed data will be
434 pushed onto the array.
436 =item An Output FileGlob
438 If C<$output> is a string that is delimited by the characters "<" and ">"
439 C<rawdeflate> will assume that it is an I<output fileglob string>. The
440 output is the list of files that match the fileglob.
442 When C<$output> is an fileglob string, C<$input> must also be a fileglob
443 string. Anything else is an error.
447 If the C<$output> parameter is any other type, C<undef> will be returned.
453 When C<$input> maps to multiple files/buffers and C<$output> is a single
454 file/buffer the compressed input files/buffers will all be stored
455 in C<$output> as a single compressed stream.
459 =head2 Optional Parameters
461 Unless specified below, the optional parameters for C<rawdeflate>,
462 C<OPTS>, are the same as those used with the OO interface defined in the
463 L</"Constructor Options"> section below.
467 =item AutoClose =E<gt> 0|1
469 This option applies to any input or output data streams to
470 C<rawdeflate> that are filehandles.
472 If C<AutoClose> is specified, and the value is true, it will result in all
473 input and/or output filehandles being closed once C<rawdeflate> has
476 This parameter defaults to 0.
480 =item BinModeIn =E<gt> 0|1
482 When reading from a file or filehandle, set C<binmode> before reading.
490 =item -Append =E<gt> 0|1
501 To read the contents of the file C<file1.txt> and write the compressed
502 data to the file C<file1.txt.1951>.
506 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
508 my $input = "file1.txt";
509 rawdeflate $input => "$input.1951"
510 or die "rawdeflate failed: $RawDeflateError\n";
513 To read from an existing Perl filehandle, C<$input>, and write the
514 compressed data to a buffer, C<$buffer>.
518 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
521 my $input = new IO::File "<file1.txt"
522 or die "Cannot open 'file1.txt': $!\n" ;
524 rawdeflate $input => \$buffer
525 or die "rawdeflate failed: $RawDeflateError\n";
527 To compress all files in the directory "/my/home" that match "*.txt"
528 and store the compressed data in the same directory
532 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
534 rawdeflate '</my/home/*.txt>' => '<*.1951>'
535 or die "rawdeflate failed: $RawDeflateError\n";
537 and if you want to compress each file one at a time, this will do the trick
541 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
543 for my $input ( glob "/my/home/*.txt" )
545 my $output = "$input.1951" ;
546 rawdeflate $input => $output
547 or die "Error compressing '$input': $RawDeflateError\n";
555 The format of the constructor for C<IO::Compress::RawDeflate> is shown below
557 my $z = new IO::Compress::RawDeflate $output [,OPTS]
558 or die "IO::Compress::RawDeflate failed: $RawDeflateError\n";
560 It returns an C<IO::Compress::RawDeflate> object on success and undef on failure.
561 The variable C<$RawDeflateError> will contain an error message on failure.
563 If you are running Perl 5.005 or better the object, C<$z>, returned from
564 IO::Compress::RawDeflate can be used exactly like an L<IO::File|IO::File> filehandle.
565 This means that all normal output file operations can be carried out
567 For example, to write to a compressed file/buffer you can use either of
570 $z->print("hello world\n");
571 print $z "hello world\n";
573 The mandatory parameter C<$output> is used to control the destination
574 of the compressed data. This parameter can take one of these forms.
580 If the C<$output> parameter is a simple scalar, it is assumed to be a
581 filename. This file will be opened for writing and the compressed data
582 will be written to it.
586 If the C<$output> parameter is a filehandle, the compressed data will be
588 The string '-' can be used as an alias for standard output.
591 =item A scalar reference
593 If C<$output> is a scalar reference, the compressed data will be stored
598 If the C<$output> parameter is any other type, C<IO::Compress::RawDeflate>::new will
601 =head2 Constructor Options
603 C<OPTS> is any combination of the following options:
607 =item -AutoClose =E<gt> 0|1
609 This option is only valid when the C<$output> parameter is a filehandle. If
610 specified, and the value is true, it will result in the C<$output> being
611 closed once either the C<close> method is called or the C<IO::Compress::RawDeflate>
614 This parameter defaults to 0.
616 =item -Append =E<gt> 0|1
618 Opens C<$output> in append mode.
620 The behaviour of this option is dependent on the type of C<$output>.
626 If C<$output> is a buffer and C<Append> is enabled, all compressed data
627 will be append to the end if C<$output>. Otherwise C<$output> will be
628 cleared before any data is written to it.
632 If C<$output> is a filename and C<Append> is enabled, the file will be
633 opened in append mode. Otherwise the contents of the file, if any, will be
634 truncated before any compressed data is written to it.
638 If C<$output> is a filehandle, the file pointer will be positioned to the
639 end of the file via a call to C<seek> before any compressed data is written
640 to it. Otherwise the file pointer will not be moved.
644 This parameter defaults to 0.
646 =item -Merge =E<gt> 0|1
648 This option is used to compress input data and append it to an existing
649 compressed data stream in C<$output>. The end result is a single compressed
650 data stream stored in C<$output>.
654 It is a fatal error to attempt to use this option when C<$output> is not an
655 RFC 1951 data stream.
659 There are a number of other limitations with the C<Merge> option:
665 This module needs to have been built with zlib 1.2.1 or better to work. A
666 fatal error will be thrown if C<Merge> is used with an older version of
671 If C<$output> is a file or a filehandle, it must be seekable.
676 This parameter defaults to 0.
680 Defines the compression level used by zlib. The value should either be
681 a number between 0 and 9 (0 means no compression and 9 is maximum
682 compression), or one of the symbolic constants defined below.
687 Z_DEFAULT_COMPRESSION
689 The default is Z_DEFAULT_COMPRESSION.
691 Note, these constants are not imported by C<IO::Compress::RawDeflate> by default.
693 use IO::Compress::RawDeflate qw(:strategy);
694 use IO::Compress::RawDeflate qw(:constants);
695 use IO::Compress::RawDeflate qw(:all);
699 Defines the strategy used to tune the compression. Use one of the symbolic
700 constants defined below.
708 The default is Z_DEFAULT_STRATEGY.
714 =item -Strict =E<gt> 0|1
718 This is a placeholder option.
737 Compresses and outputs the contents of the C<$data> parameter. This
738 has the same behaviour as the C<print> built-in.
740 Returns true if successful.
746 $z->printf($format, $data)
747 printf $z $format, $data
749 Compresses and outputs the contents of the C<$data> parameter.
751 Returns true if successful.
758 $z->syswrite $data, $length
759 $z->syswrite $data, $length, $offset
762 syswrite $z, $data, $length
763 syswrite $z, $data, $length, $offset
765 Compresses and outputs the contents of the C<$data> parameter.
767 Returns the number of uncompressed bytes written, or C<undef> if
775 $z->write $data, $length
776 $z->write $data, $length, $offset
778 Compresses and outputs the contents of the C<$data> parameter.
780 Returns the number of uncompressed bytes written, or C<undef> if
788 $z->flush($flush_type);
790 flush $z $flush_type;
792 Flushes any pending compressed data to the output file/buffer.
794 This method takes an optional parameter, C<$flush_type>, that controls
795 how the flushing will be carried out. By default the C<$flush_type>
796 used is C<Z_FINISH>. Other valid values for C<$flush_type> are
797 C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
798 strongly recommended that you only set the C<flush_type> parameter if
799 you fully understand the implications of what it does - overuse of C<flush>
800 can seriously degrade the level of compression achieved. See the C<zlib>
801 documentation for details.
803 Returns true on success.
813 Returns the uncompressed file offset.
824 Returns true if the C<close> method has been called.
830 $z->seek($position, $whence);
831 seek($z, $position, $whence);
836 Provides a sub-set of the C<seek> functionality, with the restriction
837 that it is only legal to seek forward in the output file/buffer.
838 It is a fatal error to attempt to seek backward.
840 Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
844 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
845 SEEK_CUR or SEEK_END.
847 Returns 1 on success, 0 on failure.
856 This is a noop provided for completeness.
863 If the C<$z> object is associated with a file, this method will return
864 the underlying filehandle.
866 If the C<$z> object is is associated with a buffer, this method will
876 Flushes any pending compressed data and then closes the output file/buffer.
880 For most versions of Perl this method will be automatically invoked if
881 the IO::Compress::RawDeflate object is destroyed (either explicitly or by the
882 variable with the reference to the object going out of scope). The
883 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
884 these cases, the C<close> method will be called automatically, but
885 not until global destruction of all live objects when the program is
888 Therefore, if you want your scripts to be able to run on all versions
889 of Perl, you should call C<close> explicitly and not rely on automatic
892 Returns true on success, otherwise 0.
894 If the C<AutoClose> option has been enabled when the IO::Compress::RawDeflate
895 object was created, and the object is associated with a file, the
896 underlying file will also be closed.
901 =head2 newStream([OPTS])
905 $z->newStream( [OPTS] )
907 Closes the current compressed data stream and starts a new one.
909 OPTS consists of the following sub-set of the the options that are
910 available when creating the C<$z> object,
930 A number of symbolic constants are required by some methods in
931 C<IO::Compress::RawDeflate>. None are imported by default.
937 Imports C<rawdeflate>, C<$RawDeflateError> and all symbolic
938 constants that can be used by C<IO::Compress::RawDeflate>. Same as doing this
940 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError :constants) ;
944 Import all symbolic constants. Same as doing this
946 use IO::Compress::RawDeflate qw(:flush :level :strategy) ;
950 These symbolic constants are used by the C<flush> method.
962 These symbolic constants are used by the C<Level> option in the constructor.
967 Z_DEFAULT_COMPRESSION
972 These symbolic constants are used by the C<Strategy> option in the constructor.
995 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::Uncompress::AnyInflate>
997 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
999 L<File::GlobMapper|File::GlobMapper>, L<Archive::Tar|Archive::Zip>,
1000 L<IO::Zlib|IO::Zlib>
1002 For RFC 1950, 1951 and 1952 see
1003 F<http://www.faqs.org/rfcs/rfc1950.html>,
1004 F<http://www.faqs.org/rfcs/rfc1951.html> and
1005 F<http://www.faqs.org/rfcs/rfc1952.html>
1007 The primary site for the gzip program is F<http://www.gzip.org>.
1011 The I<IO::Compress::RawDeflate> module was written by Paul Marquess,
1012 F<pmqs@cpan.org>. The latest copy of the module can be
1013 found on CPAN in F<modules/by-module/Compress/Compress-Zlib-x.x.tar.gz>.
1015 The I<zlib> compression library was written by Jean-loup Gailly
1016 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1018 The primary site for the I<zlib> compression library is
1019 F<http://www.zlib.org>.
1021 =head1 MODIFICATION HISTORY
1023 See the Changes file.
1025 =head1 COPYRIGHT AND LICENSE
1028 Copyright (c) 2005-2006 Paul Marquess. All rights reserved.
1029 This program is free software; you can redistribute it and/or
1030 modify it under the same terms as Perl itself.