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_14';
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);
171 IO::Compress::Deflate - Write RFC 1950 files/buffers
177 use IO::Compress::Deflate qw(deflate $DeflateError) ;
180 my $status = deflate $input => $output [,OPTS]
181 or die "deflate failed: $DeflateError\n";
183 my $z = new IO::Compress::Deflate $output [,OPTS]
184 or die "deflate failed: $DeflateError\n";
187 $z->printf($format, $string);
189 $z->syswrite($string [, $length, $offset]);
193 $z->seek($position, $whence);
198 $z->input_line_number();
199 $z->newStream( [OPTS] );
210 printf $z $format, $string;
213 seek $z, $position, $whence
223 B<WARNING -- This is a Beta release>.
227 =item * DO NOT use in production code.
229 =item * The documentation is incomplete in places.
231 =item * Parts of the interface defined here are tentative.
233 =item * Please report any problems you find.
240 This module provides a Perl interface that allows writing compressed
241 data to files or buffer as defined in RFC 1950.
253 For reading RFC 1950 files/buffers, see the companion module
254 L<IO::Uncompress::Inflate|IO::Uncompress::Inflate>.
257 =head1 Functional Interface
259 A top-level function, C<deflate>, is provided to carry out
260 "one-shot" compression between buffers and/or files. For finer
261 control over the compression process, see the L</"OO Interface">
264 use IO::Compress::Deflate qw(deflate $DeflateError) ;
266 deflate $input => $output [,OPTS]
267 or die "deflate failed: $DeflateError\n";
271 The functional interface needs Perl5.005 or better.
274 =head2 deflate $input => $output [, OPTS]
277 C<deflate> expects at least two parameters, C<$input> and C<$output>.
279 =head3 The C<$input> parameter
281 The parameter, C<$input>, is used to define the source of
282 the uncompressed data.
284 It can take one of the following forms:
290 If the C<$input> parameter is a simple scalar, it is assumed to be a
291 filename. This file will be opened for reading and the input data
292 will be read from it.
296 If the C<$input> parameter is a filehandle, the input data will be
298 The string '-' can be used as an alias for standard input.
300 =item A scalar reference
302 If C<$input> is a scalar reference, the input data will be read
305 =item An array reference
307 If C<$input> is an array reference, each element in the array must be a
310 The input data will be read from each file in turn.
312 The complete array will be walked to ensure that it only
313 contains valid filenames before any data is compressed.
317 =item An Input FileGlob string
319 If C<$input> is a string that is delimited by the characters "<" and ">"
320 C<deflate> will assume that it is an I<input fileglob string>. The
321 input is the list of files that match the fileglob.
323 If the fileglob does not match any files ...
325 See L<File::GlobMapper|File::GlobMapper> for more details.
330 If the C<$input> parameter is any other type, C<undef> will be returned.
334 =head3 The C<$output> parameter
336 The parameter C<$output> is used to control the destination of the
337 compressed data. This parameter can take one of these forms.
343 If the C<$output> parameter is a simple scalar, it is assumed to be a
344 filename. This file will be opened for writing and the compressed
345 data will be written to it.
349 If the C<$output> parameter is a filehandle, the compressed data
350 will be written to it.
351 The string '-' can be used as an alias for standard output.
354 =item A scalar reference
356 If C<$output> is a scalar reference, the compressed data will be
357 stored in C<$$output>.
361 =item An Array Reference
363 If C<$output> is an array reference, the compressed data will be
364 pushed onto the array.
366 =item An Output FileGlob
368 If C<$output> is a string that is delimited by the characters "<" and ">"
369 C<deflate> will assume that it is an I<output fileglob string>. The
370 output is the list of files that match the fileglob.
372 When C<$output> is an fileglob string, C<$input> must also be a fileglob
373 string. Anything else is an error.
377 If the C<$output> parameter is any other type, C<undef> will be returned.
385 When C<$input> maps to multiple files/buffers and C<$output> is a single
386 file/buffer the input files/buffers will be stored
387 in C<$output> as a concatenated series of compressed data streams.
394 =head2 Optional Parameters
396 Unless specified below, the optional parameters for C<deflate>,
397 C<OPTS>, are the same as those used with the OO interface defined in the
398 L</"Constructor Options"> section below.
402 =item C<< AutoClose => 0|1 >>
404 This option applies to any input or output data streams to
405 C<deflate> that are filehandles.
407 If C<AutoClose> is specified, and the value is true, it will result in all
408 input and/or output filehandles being closed once C<deflate> has
411 This parameter defaults to 0.
414 =item C<< BinModeIn => 0|1 >>
416 When reading from a file or filehandle, set C<binmode> before reading.
424 =item C<< Append => 0|1 >>
436 To read the contents of the file C<file1.txt> and write the compressed
437 data to the file C<file1.txt.1950>.
441 use IO::Compress::Deflate qw(deflate $DeflateError) ;
443 my $input = "file1.txt";
444 deflate $input => "$input.1950"
445 or die "deflate failed: $DeflateError\n";
448 To read from an existing Perl filehandle, C<$input>, and write the
449 compressed data to a buffer, C<$buffer>.
453 use IO::Compress::Deflate qw(deflate $DeflateError) ;
456 my $input = new IO::File "<file1.txt"
457 or die "Cannot open 'file1.txt': $!\n" ;
459 deflate $input => \$buffer
460 or die "deflate failed: $DeflateError\n";
462 To compress all files in the directory "/my/home" that match "*.txt"
463 and store the compressed data in the same directory
467 use IO::Compress::Deflate qw(deflate $DeflateError) ;
469 deflate '</my/home/*.txt>' => '<*.1950>'
470 or die "deflate failed: $DeflateError\n";
472 and if you want to compress each file one at a time, this will do the trick
476 use IO::Compress::Deflate qw(deflate $DeflateError) ;
478 for my $input ( glob "/my/home/*.txt" )
480 my $output = "$input.1950" ;
481 deflate $input => $output
482 or die "Error compressing '$input': $DeflateError\n";
490 The format of the constructor for C<IO::Compress::Deflate> is shown below
492 my $z = new IO::Compress::Deflate $output [,OPTS]
493 or die "IO::Compress::Deflate failed: $DeflateError\n";
495 It returns an C<IO::Compress::Deflate> object on success and undef on failure.
496 The variable C<$DeflateError> will contain an error message on failure.
498 If you are running Perl 5.005 or better the object, C<$z>, returned from
499 IO::Compress::Deflate can be used exactly like an L<IO::File|IO::File> filehandle.
500 This means that all normal output file operations can be carried out
502 For example, to write to a compressed file/buffer you can use either of
505 $z->print("hello world\n");
506 print $z "hello world\n";
508 The mandatory parameter C<$output> is used to control the destination
509 of the compressed data. This parameter can take one of these forms.
515 If the C<$output> parameter is a simple scalar, it is assumed to be a
516 filename. This file will be opened for writing and the compressed data
517 will be written to it.
521 If the C<$output> parameter is a filehandle, the compressed data will be
523 The string '-' can be used as an alias for standard output.
526 =item A scalar reference
528 If C<$output> is a scalar reference, the compressed data will be stored
533 If the C<$output> parameter is any other type, C<IO::Compress::Deflate>::new will
536 =head2 Constructor Options
538 C<OPTS> is any combination of the following options:
542 =item C<< AutoClose => 0|1 >>
544 This option is only valid when the C<$output> parameter is a filehandle. If
545 specified, and the value is true, it will result in the C<$output> being
546 closed once either the C<close> method is called or the C<IO::Compress::Deflate>
549 This parameter defaults to 0.
551 =item C<< Append => 0|1 >>
553 Opens C<$output> in append mode.
555 The behaviour of this option is dependent on the type of C<$output>.
561 If C<$output> is a buffer and C<Append> is enabled, all compressed data
562 will be append to the end if C<$output>. Otherwise C<$output> will be
563 cleared before any data is written to it.
567 If C<$output> is a filename and C<Append> is enabled, the file will be
568 opened in append mode. Otherwise the contents of the file, if any, will be
569 truncated before any compressed data is written to it.
573 If C<$output> is a filehandle, the file pointer will be positioned to the
574 end of the file via a call to C<seek> before any compressed data is written
575 to it. Otherwise the file pointer will not be moved.
579 This parameter defaults to 0.
585 =item C<< Merge => 0|1 >>
587 This option is used to compress input data and append it to an existing
588 compressed data stream in C<$output>. The end result is a single compressed
589 data stream stored in C<$output>.
593 It is a fatal error to attempt to use this option when C<$output> is not an
594 RFC 1950 data stream.
598 There are a number of other limitations with the C<Merge> option:
604 This module needs to have been built with zlib 1.2.1 or better to work. A
605 fatal error will be thrown if C<Merge> is used with an older version of
610 If C<$output> is a file or a filehandle, it must be seekable.
615 This parameter defaults to 0.
621 Defines the compression level used by zlib. The value should either be
622 a number between 0 and 9 (0 means no compression and 9 is maximum
623 compression), or one of the symbolic constants defined below.
628 Z_DEFAULT_COMPRESSION
630 The default is Z_DEFAULT_COMPRESSION.
632 Note, these constants are not imported by C<IO::Compress::Deflate> by default.
634 use IO::Compress::Deflate qw(:strategy);
635 use IO::Compress::Deflate qw(:constants);
636 use IO::Compress::Deflate qw(:all);
640 Defines the strategy used to tune the compression. Use one of the symbolic
641 constants defined below.
649 The default is Z_DEFAULT_STRATEGY.
656 =item C<< Strict => 0|1 >>
660 This is a placeholder option.
679 Compresses and outputs the contents of the C<$data> parameter. This
680 has the same behaviour as the C<print> built-in.
682 Returns true if successful.
688 $z->printf($format, $data)
689 printf $z $format, $data
691 Compresses and outputs the contents of the C<$data> parameter.
693 Returns true if successful.
700 $z->syswrite $data, $length
701 $z->syswrite $data, $length, $offset
703 Compresses and outputs the contents of the C<$data> parameter.
705 Returns the number of uncompressed bytes written, or C<undef> if
713 $z->write $data, $length
714 $z->write $data, $length, $offset
716 Compresses and outputs the contents of the C<$data> parameter.
718 Returns the number of uncompressed bytes written, or C<undef> if
727 $z->flush($flush_type);
730 Flushes any pending compressed data to the output file/buffer.
733 This method takes an optional parameter, C<$flush_type>, that controls
734 how the flushing will be carried out. By default the C<$flush_type>
735 used is C<Z_FINISH>. Other valid values for C<$flush_type> are
736 C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
737 strongly recommended that you only set the C<flush_type> parameter if
738 you fully understand the implications of what it does - overuse of C<flush>
739 can seriously degrade the level of compression achieved. See the C<zlib>
740 documentation for details.
743 Returns true on success.
753 Returns the uncompressed file offset.
764 Returns true if the C<close> method has been called.
770 $z->seek($position, $whence);
771 seek($z, $position, $whence);
776 Provides a sub-set of the C<seek> functionality, with the restriction
777 that it is only legal to seek forward in the output file/buffer.
778 It is a fatal error to attempt to seek backward.
780 Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
784 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
785 SEEK_CUR or SEEK_END.
787 Returns 1 on success, 0 on failure.
796 This is a noop provided for completeness.
802 Returns true if the object currently refers to a opened file/buffer.
806 my $prev = $z->autoflush()
807 my $prev = $z->autoflush(EXPR)
809 If the C<$z> object is associated with a file or a filehandle, this method
810 returns the current autoflush setting for the underlying filehandle. If
811 C<EXPR> is present, and is non-zero, it will enable flushing after every
812 write/print operation.
814 If C<$z> is associated with a buffer, this method has no effect and always
817 B<Note> that the special variable C<$|> B<cannot> be used to set or
818 retrieve the autoflush setting.
820 =head2 input_line_number
822 $z->input_line_number()
823 $z->input_line_number(EXPR)
826 This method always returns C<undef> when compressing.
835 If the C<$z> object is associated with a file or a filehandle, this method
836 will return the underlying file descriptor.
838 If the C<$z> object is is associated with a buffer, this method will
848 Flushes any pending compressed data and then closes the output file/buffer.
852 For most versions of Perl this method will be automatically invoked if
853 the IO::Compress::Deflate object is destroyed (either explicitly or by the
854 variable with the reference to the object going out of scope). The
855 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
856 these cases, the C<close> method will be called automatically, but
857 not until global destruction of all live objects when the program is
860 Therefore, if you want your scripts to be able to run on all versions
861 of Perl, you should call C<close> explicitly and not rely on automatic
864 Returns true on success, otherwise 0.
866 If the C<AutoClose> option has been enabled when the IO::Compress::Deflate
867 object was created, and the object is associated with a file, the
868 underlying file will also be closed.
873 =head2 newStream([OPTS])
877 $z->newStream( [OPTS] )
879 Closes the current compressed data stream and starts a new one.
881 OPTS consists of any of the the options that are available when creating
884 See the L</"Constructor Options"> section for more details.
899 A number of symbolic constants are required by some methods in
900 C<IO::Compress::Deflate>. None are imported by default.
909 Imports C<deflate>, C<$DeflateError> and all symbolic
910 constants that can be used by C<IO::Compress::Deflate>. Same as doing this
912 use IO::Compress::Deflate qw(deflate $DeflateError :constants) ;
916 Import all symbolic constants. Same as doing this
919 use IO::Compress::Deflate qw(:flush :level :strategy) ;
924 These symbolic constants are used by the C<flush> method.
935 These symbolic constants are used by the C<Level> option in the constructor.
940 Z_DEFAULT_COMPRESSION
945 These symbolic constants are used by the C<Strategy> option in the constructor.
976 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::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
978 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
980 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
981 L<Archive::Tar|Archive::Tar>,
985 For RFC 1950, 1951 and 1952 see
986 F<http://www.faqs.org/rfcs/rfc1950.html>,
987 F<http://www.faqs.org/rfcs/rfc1951.html> and
988 F<http://www.faqs.org/rfcs/rfc1952.html>
990 The I<zlib> compression library was written by Jean-loup Gailly
991 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
993 The primary site for the I<zlib> compression library is
994 F<http://www.zlib.org>.
996 The primary site for gzip is F<http://www.gzip.org>.
1003 This module was written by Paul Marquess, F<pmqs@cpan.org>.
1007 =head1 MODIFICATION HISTORY
1009 See the Changes file.
1011 =head1 COPYRIGHT AND LICENSE
1013 Copyright (c) 2005-2006 Paul Marquess. All rights reserved.
1015 This program is free software; you can redistribute it and/or
1016 modify it under the same terms as Perl itself.