1 package IO::Compress::Deflate ;
9 use IO::Compress::RawDeflate;
11 use Compress::Raw::Zlib ;
12 use IO::Compress::Zlib::Constants;
13 use IO::Compress::Base::Common qw(createSelfTiedObject);
16 our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $DeflateError);
18 $VERSION = '2.000_08';
21 @ISA = qw(Exporter IO::Compress::RawDeflate);
22 @EXPORT_OK = qw( $DeflateError deflate ) ;
23 %EXPORT_TAGS = %IO::Compress::RawDeflate::DEFLATE_CONSTANTS ;
24 push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
25 Exporter::export_ok_tags('all');
32 my $obj = createSelfTiedObject($class, \$DeflateError);
33 return $obj->_create(undef, @_);
38 my $obj = createSelfTiedObject(undef, \$DeflateError);
39 return $obj->_def(@_);
50 return $into | (($value & $mask) << $offset ) ;
53 sub mkDeflateHdr($$$;$)
58 my $fdict_adler = shift ;
63 $fdict = 1 if defined $fdict_adler;
65 $cmf = bitmask($cmf, $method, ZLIB_CMF_CM_OFFSET, ZLIB_CMF_CM_BITS);
66 $cmf = bitmask($cmf, $cinfo, ZLIB_CMF_CINFO_OFFSET, ZLIB_CMF_CINFO_BITS);
68 $flg = bitmask($flg, $fdict, ZLIB_FLG_FDICT_OFFSET, ZLIB_FLG_FDICT_BITS);
69 $flg = bitmask($flg, $level, ZLIB_FLG_LEVEL_OFFSET, ZLIB_FLG_LEVEL_BITS);
71 my $fcheck = 31 - ($cmf * 256 + $flg) % 31 ;
72 $flg = bitmask($flg, $fcheck, ZLIB_FLG_FCHECK_OFFSET, ZLIB_FLG_FCHECK_BITS);
74 my $hdr = pack("CC", $cmf, $flg) ;
75 $hdr .= pack("N", $fdict_adler) if $fdict ;
85 my $level = $param->value('Level');
86 my $strategy = $param->value('Strategy');
90 if $level == Z_DEFAULT_COMPRESSION ;
92 if (ZLIB_VERNUM >= 0x1210)
94 if ($strategy >= Z_HUFFMAN_ONLY || $level < 2)
95 { $lflag = ZLIB_FLG_LEVEL_FASTEST }
97 { $lflag = ZLIB_FLG_LEVEL_FAST }
99 { $lflag = ZLIB_FLG_LEVEL_DEFAULT }
101 { $lflag = ZLIB_FLG_LEVEL_SLOWEST }
105 $lflag = ($level - 1) >> 1 ;
106 $lflag = 3 if $lflag > 3 ;
109 #my $wbits = (MAX_WBITS - 8) << 4 ;
111 mkDeflateHdr(ZLIB_CMF_CM_DEFLATED, $wbits, $lflag);
119 $got->value('ADLER32' => 1);
127 return pack("N", *$self->{Compress}->adler32()) ;
138 # return *$self->{Header};
144 return $self->getZlibParams(),
149 return ('IO::Uncompress::Inflate',
150 \$IO::Uncompress::Inflate::InflateError);
170 IO::Compress::Deflate - Perl interface to write RFC 1950 files/buffers
175 use IO::Compress::Deflate qw(deflate $DeflateError) ;
178 my $status = deflate $input => $output [,OPTS]
179 or die "deflate failed: $DeflateError\n";
181 my $z = new IO::Compress::Deflate $output [,OPTS]
182 or die "deflate failed: $DeflateError\n";
185 $z->printf($format, $string);
187 $z->syswrite($string [, $length, $offset]);
191 $z->seek($position, $whence);
196 $z->input_line_number();
197 $z->newStream( [OPTS] );
208 printf $z $format, $string;
211 seek $z, $position, $whence
221 B<WARNING -- This is a Beta release>.
225 =item * DO NOT use in production code.
227 =item * The documentation is incomplete in places.
229 =item * Parts of the interface defined here are tentative.
231 =item * Please report any problems you find.
238 This module provides a Perl interface that allows writing compressed
239 data to files or buffer as defined in RFC 1950.
249 For reading RFC 1950 files/buffers, see the companion module
250 L<IO::Uncompress::Inflate|IO::Uncompress::Inflate>.
253 =head1 Functional Interface
255 A top-level function, C<deflate>, is provided to carry out
256 "one-shot" compression between buffers and/or files. For finer
257 control over the compression process, see the L</"OO Interface">
260 use IO::Compress::Deflate qw(deflate $DeflateError) ;
262 deflate $input => $output [,OPTS]
263 or die "deflate failed: $DeflateError\n";
267 The functional interface needs Perl5.005 or better.
270 =head2 deflate $input => $output [, OPTS]
273 C<deflate> expects at least two parameters, C<$input> and C<$output>.
275 =head3 The C<$input> parameter
277 The parameter, C<$input>, is used to define the source of
278 the uncompressed data.
280 It can take one of the following forms:
286 If the C<$input> parameter is a simple scalar, it is assumed to be a
287 filename. This file will be opened for reading and the input data
288 will be read from it.
292 If the C<$input> parameter is a filehandle, the input data will be
294 The string '-' can be used as an alias for standard input.
296 =item A scalar reference
298 If C<$input> is a scalar reference, the input data will be read
301 =item An array reference
303 If C<$input> is an array reference, each element in the array must be a
306 The input data will be read from each file in turn.
308 The complete array will be walked to ensure that it only
309 contains valid filenames before any data is compressed.
313 =item An Input FileGlob string
315 If C<$input> is a string that is delimited by the characters "<" and ">"
316 C<deflate> will assume that it is an I<input fileglob string>. The
317 input is the list of files that match the fileglob.
319 If the fileglob does not match any files ...
321 See L<File::GlobMapper|File::GlobMapper> for more details.
326 If the C<$input> parameter is any other type, C<undef> will be returned.
330 =head3 The C<$output> parameter
332 The parameter C<$output> is used to control the destination of the
333 compressed data. This parameter can take one of these forms.
339 If the C<$output> parameter is a simple scalar, it is assumed to be a
340 filename. This file will be opened for writing and the compressed
341 data will be written to it.
345 If the C<$output> parameter is a filehandle, the compressed data
346 will be written to it.
347 The string '-' can be used as an alias for standard output.
350 =item A scalar reference
352 If C<$output> is a scalar reference, the compressed data will be
353 stored in C<$$output>.
357 =item An Array Reference
359 If C<$output> is an array reference, the compressed data will be
360 pushed onto the array.
362 =item An Output FileGlob
364 If C<$output> is a string that is delimited by the characters "<" and ">"
365 C<deflate> will assume that it is an I<output fileglob string>. The
366 output is the list of files that match the fileglob.
368 When C<$output> is an fileglob string, C<$input> must also be a fileglob
369 string. Anything else is an error.
373 If the C<$output> parameter is any other type, C<undef> will be returned.
379 When C<$input> maps to multiple files/buffers and C<$output> is a single
380 file/buffer the compressed input files/buffers will all be stored
381 in C<$output> as a single compressed stream.
385 =head2 Optional Parameters
387 Unless specified below, the optional parameters for C<deflate>,
388 C<OPTS>, are the same as those used with the OO interface defined in the
389 L</"Constructor Options"> section below.
393 =item AutoClose =E<gt> 0|1
395 This option applies to any input or output data streams to
396 C<deflate> that are filehandles.
398 If C<AutoClose> is specified, and the value is true, it will result in all
399 input and/or output filehandles being closed once C<deflate> has
402 This parameter defaults to 0.
406 =item BinModeIn =E<gt> 0|1
408 When reading from a file or filehandle, set C<binmode> before reading.
416 =item -Append =E<gt> 0|1
427 To read the contents of the file C<file1.txt> and write the compressed
428 data to the file C<file1.txt.1950>.
432 use IO::Compress::Deflate qw(deflate $DeflateError) ;
434 my $input = "file1.txt";
435 deflate $input => "$input.1950"
436 or die "deflate failed: $DeflateError\n";
439 To read from an existing Perl filehandle, C<$input>, and write the
440 compressed data to a buffer, C<$buffer>.
444 use IO::Compress::Deflate qw(deflate $DeflateError) ;
447 my $input = new IO::File "<file1.txt"
448 or die "Cannot open 'file1.txt': $!\n" ;
450 deflate $input => \$buffer
451 or die "deflate failed: $DeflateError\n";
453 To compress all files in the directory "/my/home" that match "*.txt"
454 and store the compressed data in the same directory
458 use IO::Compress::Deflate qw(deflate $DeflateError) ;
460 deflate '</my/home/*.txt>' => '<*.1950>'
461 or die "deflate failed: $DeflateError\n";
463 and if you want to compress each file one at a time, this will do the trick
467 use IO::Compress::Deflate qw(deflate $DeflateError) ;
469 for my $input ( glob "/my/home/*.txt" )
471 my $output = "$input.1950" ;
472 deflate $input => $output
473 or die "Error compressing '$input': $DeflateError\n";
481 The format of the constructor for C<IO::Compress::Deflate> is shown below
483 my $z = new IO::Compress::Deflate $output [,OPTS]
484 or die "IO::Compress::Deflate failed: $DeflateError\n";
486 It returns an C<IO::Compress::Deflate> object on success and undef on failure.
487 The variable C<$DeflateError> will contain an error message on failure.
489 If you are running Perl 5.005 or better the object, C<$z>, returned from
490 IO::Compress::Deflate can be used exactly like an L<IO::File|IO::File> filehandle.
491 This means that all normal output file operations can be carried out
493 For example, to write to a compressed file/buffer you can use either of
496 $z->print("hello world\n");
497 print $z "hello world\n";
499 The mandatory parameter C<$output> is used to control the destination
500 of the compressed data. This parameter can take one of these forms.
506 If the C<$output> parameter is a simple scalar, it is assumed to be a
507 filename. This file will be opened for writing and the compressed data
508 will be written to it.
512 If the C<$output> parameter is a filehandle, the compressed data will be
514 The string '-' can be used as an alias for standard output.
517 =item A scalar reference
519 If C<$output> is a scalar reference, the compressed data will be stored
524 If the C<$output> parameter is any other type, C<IO::Compress::Deflate>::new will
527 =head2 Constructor Options
529 C<OPTS> is any combination of the following options:
533 =item AutoClose =E<gt> 0|1
535 This option is only valid when the C<$output> parameter is a filehandle. If
536 specified, and the value is true, it will result in the C<$output> being
537 closed once either the C<close> method is called or the C<IO::Compress::Deflate>
540 This parameter defaults to 0.
542 =item Append =E<gt> 0|1
544 Opens C<$output> in append mode.
546 The behaviour of this option is dependent on the type of C<$output>.
552 If C<$output> is a buffer and C<Append> is enabled, all compressed data
553 will be append to the end if C<$output>. Otherwise C<$output> will be
554 cleared before any data is written to it.
558 If C<$output> is a filename and C<Append> is enabled, the file will be
559 opened in append mode. Otherwise the contents of the file, if any, will be
560 truncated before any compressed data is written to it.
564 If C<$output> is a filehandle, the file pointer will be positioned to the
565 end of the file via a call to C<seek> before any compressed data is written
566 to it. Otherwise the file pointer will not be moved.
570 This parameter defaults to 0.
576 =item -Merge =E<gt> 0|1
578 This option is used to compress input data and append it to an existing
579 compressed data stream in C<$output>. The end result is a single compressed
580 data stream stored in C<$output>.
584 It is a fatal error to attempt to use this option when C<$output> is not an
585 RFC 1950 data stream.
589 There are a number of other limitations with the C<Merge> option:
595 This module needs to have been built with zlib 1.2.1 or better to work. A
596 fatal error will be thrown if C<Merge> is used with an older version of
601 If C<$output> is a file or a filehandle, it must be seekable.
606 This parameter defaults to 0.
612 Defines the compression level used by zlib. The value should either be
613 a number between 0 and 9 (0 means no compression and 9 is maximum
614 compression), or one of the symbolic constants defined below.
619 Z_DEFAULT_COMPRESSION
621 The default is Z_DEFAULT_COMPRESSION.
623 Note, these constants are not imported by C<IO::Compress::Deflate> by default.
625 use IO::Compress::Deflate qw(:strategy);
626 use IO::Compress::Deflate qw(:constants);
627 use IO::Compress::Deflate qw(:all);
631 Defines the strategy used to tune the compression. Use one of the symbolic
632 constants defined below.
640 The default is Z_DEFAULT_STRATEGY.
647 =item -Strict =E<gt> 0|1
651 This is a placeholder option.
670 Compresses and outputs the contents of the C<$data> parameter. This
671 has the same behaviour as the C<print> built-in.
673 Returns true if successful.
679 $z->printf($format, $data)
680 printf $z $format, $data
682 Compresses and outputs the contents of the C<$data> parameter.
684 Returns true if successful.
691 $z->syswrite $data, $length
692 $z->syswrite $data, $length, $offset
694 Compresses and outputs the contents of the C<$data> parameter.
696 Returns the number of uncompressed bytes written, or C<undef> if
704 $z->write $data, $length
705 $z->write $data, $length, $offset
707 Compresses and outputs the contents of the C<$data> parameter.
709 Returns the number of uncompressed bytes written, or C<undef> if
718 $z->flush($flush_type);
721 Flushes any pending compressed data to the output file/buffer.
724 This method takes an optional parameter, C<$flush_type>, that controls
725 how the flushing will be carried out. By default the C<$flush_type>
726 used is C<Z_FINISH>. Other valid values for C<$flush_type> are
727 C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
728 strongly recommended that you only set the C<flush_type> parameter if
729 you fully understand the implications of what it does - overuse of C<flush>
730 can seriously degrade the level of compression achieved. See the C<zlib>
731 documentation for details.
734 Returns true on success.
744 Returns the uncompressed file offset.
755 Returns true if the C<close> method has been called.
761 $z->seek($position, $whence);
762 seek($z, $position, $whence);
767 Provides a sub-set of the C<seek> functionality, with the restriction
768 that it is only legal to seek forward in the output file/buffer.
769 It is a fatal error to attempt to seek backward.
771 Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
775 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
776 SEEK_CUR or SEEK_END.
778 Returns 1 on success, 0 on failure.
787 This is a noop provided for completeness.
793 Returns true if the object currently refers to a opened file/buffer.
797 my $prev = $z->autoflush()
798 my $prev = $z->autoflush(EXPR)
800 If the C<$z> object is associated with a file or a filehandle, this method
801 returns the current autoflush setting for the underlying filehandle. If
802 C<EXPR> is present, and is non-zero, it will enable flushing after every
803 write/print operation.
805 If C<$z> is associated with a buffer, this method has no effect and always
808 B<Note> that the special variable C<$|> B<cannot> be used to set or
809 retrieve the autoflush setting.
811 =head2 input_line_number
813 $z->input_line_number()
814 $z->input_line_number(EXPR)
817 This method always returns C<undef> when compressing.
826 If the C<$z> object is associated with a file or a filehandle, this method
827 will return the underlying file descriptor.
829 If the C<$z> object is is associated with a buffer, this method will
839 Flushes any pending compressed data and then closes the output file/buffer.
843 For most versions of Perl this method will be automatically invoked if
844 the IO::Compress::Deflate object is destroyed (either explicitly or by the
845 variable with the reference to the object going out of scope). The
846 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
847 these cases, the C<close> method will be called automatically, but
848 not until global destruction of all live objects when the program is
851 Therefore, if you want your scripts to be able to run on all versions
852 of Perl, you should call C<close> explicitly and not rely on automatic
855 Returns true on success, otherwise 0.
857 If the C<AutoClose> option has been enabled when the IO::Compress::Deflate
858 object was created, and the object is associated with a file, the
859 underlying file will also be closed.
864 =head2 newStream([OPTS])
868 $z->newStream( [OPTS] )
870 Closes the current compressed data stream and starts a new one.
872 OPTS consists of the following sub-set of the the options that are
873 available when creating the C<$z> object,
898 A number of symbolic constants are required by some methods in
899 C<IO::Compress::Deflate>. None are imported by default.
908 Imports C<deflate>, C<$DeflateError> and all symbolic
909 constants that can be used by C<IO::Compress::Deflate>. Same as doing this
911 use IO::Compress::Deflate qw(deflate $DeflateError :constants) ;
915 Import all symbolic constants. Same as doing this
917 use IO::Compress::Deflate qw(:flush :level :strategy) ;
921 These symbolic constants are used by the C<flush> method.
932 These symbolic constants are used by the C<Level> option in the constructor.
937 Z_DEFAULT_COMPRESSION
942 These symbolic constants are used by the C<Strategy> option in the constructor.
966 L<Compress::Zlib>, L<IO::Compress::Gzip>, L<IO::Uncompress::Gunzip>, L<IO::Uncompress::Inflate>, L<IO::Compress::RawDeflate>, 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>
968 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
970 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
971 L<Archive::Tar|Archive::Tar>,
975 For RFC 1950, 1951 and 1952 see
976 F<http://www.faqs.org/rfcs/rfc1950.html>,
977 F<http://www.faqs.org/rfcs/rfc1951.html> and
978 F<http://www.faqs.org/rfcs/rfc1952.html>
980 The I<zlib> compression library was written by Jean-loup Gailly
981 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
983 The primary site for the I<zlib> compression library is
984 F<http://www.zlib.org>.
986 The primary site for gzip is F<http://www.gzip.org>.
996 The I<IO::Compress::Deflate> module was written by Paul Marquess,
1001 =head1 MODIFICATION HISTORY
1003 See the Changes file.
1005 =head1 COPYRIGHT AND LICENSE
1008 Copyright (c) 2005-2006 Paul Marquess. All rights reserved.
1010 This program is free software; you can redistribute it and/or
1011 modify it under the same terms as Perl itself.