1 package IO::Compress::Deflate ;
9 use IO::Compress::RawDeflate 2.012 ;
11 use Compress::Raw::Zlib 2.012 ;
12 use IO::Compress::Zlib::Constants 2.012 ;
13 use IO::Compress::Base::Common 2.012 qw(createSelfTiedObject);
16 our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $DeflateError);
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);
169 IO::Compress::Deflate - Write RFC 1950 files/buffers
175 use IO::Compress::Deflate qw(deflate $DeflateError) ;
177 my $status = deflate $input => $output [,OPTS]
178 or die "deflate failed: $DeflateError\n";
180 my $z = new IO::Compress::Deflate $output [,OPTS]
181 or die "deflate failed: $DeflateError\n";
184 $z->printf($format, $string);
186 $z->syswrite($string [, $length, $offset]);
190 $z->seek($position, $whence);
195 $z->input_line_number();
196 $z->newStream( [OPTS] );
207 printf $z $format, $string;
210 seek $z, $position, $whence
218 This module provides a Perl interface that allows writing compressed
219 data to files or buffer as defined in RFC 1950.
221 For reading RFC 1950 files/buffers, see the companion module
222 L<IO::Uncompress::Inflate|IO::Uncompress::Inflate>.
224 =head1 Functional Interface
226 A top-level function, C<deflate>, is provided to carry out
227 "one-shot" compression between buffers and/or files. For finer
228 control over the compression process, see the L</"OO Interface">
231 use IO::Compress::Deflate qw(deflate $DeflateError) ;
233 deflate $input => $output [,OPTS]
234 or die "deflate failed: $DeflateError\n";
236 The functional interface needs Perl5.005 or better.
238 =head2 deflate $input => $output [, OPTS]
240 C<deflate> expects at least two parameters, C<$input> and C<$output>.
242 =head3 The C<$input> parameter
244 The parameter, C<$input>, is used to define the source of
245 the uncompressed data.
247 It can take one of the following forms:
253 If the C<$input> parameter is a simple scalar, it is assumed to be a
254 filename. This file will be opened for reading and the input data
255 will be read from it.
259 If the C<$input> parameter is a filehandle, the input data will be
261 The string '-' can be used as an alias for standard input.
263 =item A scalar reference
265 If C<$input> is a scalar reference, the input data will be read
268 =item An array reference
270 If C<$input> is an array reference, each element in the array must be a
273 The input data will be read from each file in turn.
275 The complete array will be walked to ensure that it only
276 contains valid filenames before any data is compressed.
278 =item An Input FileGlob string
280 If C<$input> is a string that is delimited by the characters "<" and ">"
281 C<deflate> will assume that it is an I<input fileglob string>. The
282 input is the list of files that match the fileglob.
284 If the fileglob does not match any files ...
286 See L<File::GlobMapper|File::GlobMapper> for more details.
290 If the C<$input> parameter is any other type, C<undef> will be returned.
292 =head3 The C<$output> parameter
294 The parameter C<$output> is used to control the destination of the
295 compressed data. This parameter can take one of these forms.
301 If the C<$output> parameter is a simple scalar, it is assumed to be a
302 filename. This file will be opened for writing and the compressed
303 data will be written to it.
307 If the C<$output> parameter is a filehandle, the compressed data
308 will be written to it.
309 The string '-' can be used as an alias for standard output.
311 =item A scalar reference
313 If C<$output> is a scalar reference, the compressed data will be
314 stored in C<$$output>.
316 =item An Array Reference
318 If C<$output> is an array reference, the compressed data will be
319 pushed onto the array.
321 =item An Output FileGlob
323 If C<$output> is a string that is delimited by the characters "<" and ">"
324 C<deflate> will assume that it is an I<output fileglob string>. The
325 output is the list of files that match the fileglob.
327 When C<$output> is an fileglob string, C<$input> must also be a fileglob
328 string. Anything else is an error.
332 If the C<$output> parameter is any other type, C<undef> will be returned.
336 When C<$input> maps to multiple files/buffers and C<$output> is a single
337 file/buffer the input files/buffers will be stored
338 in C<$output> as a concatenated series of compressed data streams.
340 =head2 Optional Parameters
342 Unless specified below, the optional parameters for C<deflate>,
343 C<OPTS>, are the same as those used with the OO interface defined in the
344 L</"Constructor Options"> section below.
348 =item C<< AutoClose => 0|1 >>
350 This option applies to any input or output data streams to
351 C<deflate> that are filehandles.
353 If C<AutoClose> is specified, and the value is true, it will result in all
354 input and/or output filehandles being closed once C<deflate> has
357 This parameter defaults to 0.
359 =item C<< BinModeIn => 0|1 >>
361 When reading from a file or filehandle, set C<binmode> before reading.
365 =item C<< Append => 0|1 >>
373 To read the contents of the file C<file1.txt> and write the compressed
374 data to the file C<file1.txt.1950>.
378 use IO::Compress::Deflate qw(deflate $DeflateError) ;
380 my $input = "file1.txt";
381 deflate $input => "$input.1950"
382 or die "deflate failed: $DeflateError\n";
384 To read from an existing Perl filehandle, C<$input>, and write the
385 compressed data to a buffer, C<$buffer>.
389 use IO::Compress::Deflate qw(deflate $DeflateError) ;
392 my $input = new IO::File "<file1.txt"
393 or die "Cannot open 'file1.txt': $!\n" ;
395 deflate $input => \$buffer
396 or die "deflate failed: $DeflateError\n";
398 To compress all files in the directory "/my/home" that match "*.txt"
399 and store the compressed data in the same directory
403 use IO::Compress::Deflate qw(deflate $DeflateError) ;
405 deflate '</my/home/*.txt>' => '<*.1950>'
406 or die "deflate failed: $DeflateError\n";
408 and if you want to compress each file one at a time, this will do the trick
412 use IO::Compress::Deflate qw(deflate $DeflateError) ;
414 for my $input ( glob "/my/home/*.txt" )
416 my $output = "$input.1950" ;
417 deflate $input => $output
418 or die "Error compressing '$input': $DeflateError\n";
425 The format of the constructor for C<IO::Compress::Deflate> is shown below
427 my $z = new IO::Compress::Deflate $output [,OPTS]
428 or die "IO::Compress::Deflate failed: $DeflateError\n";
430 It returns an C<IO::Compress::Deflate> object on success and undef on failure.
431 The variable C<$DeflateError> will contain an error message on failure.
433 If you are running Perl 5.005 or better the object, C<$z>, returned from
434 IO::Compress::Deflate can be used exactly like an L<IO::File|IO::File> filehandle.
435 This means that all normal output file operations can be carried out
437 For example, to write to a compressed file/buffer you can use either of
440 $z->print("hello world\n");
441 print $z "hello world\n";
443 The mandatory parameter C<$output> is used to control the destination
444 of the compressed data. This parameter can take one of these forms.
450 If the C<$output> parameter is a simple scalar, it is assumed to be a
451 filename. This file will be opened for writing and the compressed data
452 will be written to it.
456 If the C<$output> parameter is a filehandle, the compressed data will be
458 The string '-' can be used as an alias for standard output.
460 =item A scalar reference
462 If C<$output> is a scalar reference, the compressed data will be stored
467 If the C<$output> parameter is any other type, C<IO::Compress::Deflate>::new will
470 =head2 Constructor Options
472 C<OPTS> is any combination of the following options:
476 =item C<< AutoClose => 0|1 >>
478 This option is only valid when the C<$output> parameter is a filehandle. If
479 specified, and the value is true, it will result in the C<$output> being
480 closed once either the C<close> method is called or the C<IO::Compress::Deflate>
483 This parameter defaults to 0.
485 =item C<< Append => 0|1 >>
487 Opens C<$output> in append mode.
489 The behaviour of this option is dependent on the type of C<$output>.
495 If C<$output> is a buffer and C<Append> is enabled, all compressed data
496 will be append to the end if C<$output>. Otherwise C<$output> will be
497 cleared before any data is written to it.
501 If C<$output> is a filename and C<Append> is enabled, the file will be
502 opened in append mode. Otherwise the contents of the file, if any, will be
503 truncated before any compressed data is written to it.
507 If C<$output> is a filehandle, the file pointer will be positioned to the
508 end of the file via a call to C<seek> before any compressed data is written
509 to it. Otherwise the file pointer will not be moved.
513 This parameter defaults to 0.
515 =item C<< Merge => 0|1 >>
517 This option is used to compress input data and append it to an existing
518 compressed data stream in C<$output>. The end result is a single compressed
519 data stream stored in C<$output>.
521 It is a fatal error to attempt to use this option when C<$output> is not an
522 RFC 1950 data stream.
524 There are a number of other limitations with the C<Merge> option:
530 This module needs to have been built with zlib 1.2.1 or better to work. A
531 fatal error will be thrown if C<Merge> is used with an older version of
536 If C<$output> is a file or a filehandle, it must be seekable.
540 This parameter defaults to 0.
544 Defines the compression level used by zlib. The value should either be
545 a number between 0 and 9 (0 means no compression and 9 is maximum
546 compression), or one of the symbolic constants defined below.
551 Z_DEFAULT_COMPRESSION
553 The default is Z_DEFAULT_COMPRESSION.
555 Note, these constants are not imported by C<IO::Compress::Deflate> by default.
557 use IO::Compress::Deflate qw(:strategy);
558 use IO::Compress::Deflate qw(:constants);
559 use IO::Compress::Deflate qw(:all);
563 Defines the strategy used to tune the compression. Use one of the symbolic
564 constants defined below.
572 The default is Z_DEFAULT_STRATEGY.
574 =item C<< Strict => 0|1 >>
576 This is a placeholder option.
593 Compresses and outputs the contents of the C<$data> parameter. This
594 has the same behaviour as the C<print> built-in.
596 Returns true if successful.
602 $z->printf($format, $data)
603 printf $z $format, $data
605 Compresses and outputs the contents of the C<$data> parameter.
607 Returns true if successful.
614 $z->syswrite $data, $length
615 $z->syswrite $data, $length, $offset
617 Compresses and outputs the contents of the C<$data> parameter.
619 Returns the number of uncompressed bytes written, or C<undef> if
627 $z->write $data, $length
628 $z->write $data, $length, $offset
630 Compresses and outputs the contents of the C<$data> parameter.
632 Returns the number of uncompressed bytes written, or C<undef> if
640 $z->flush($flush_type);
642 Flushes any pending compressed data to the output file/buffer.
644 This method takes an optional parameter, C<$flush_type>, that controls
645 how the flushing will be carried out. By default the C<$flush_type>
646 used is C<Z_FINISH>. Other valid values for C<$flush_type> are
647 C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
648 strongly recommended that you only set the C<flush_type> parameter if
649 you fully understand the implications of what it does - overuse of C<flush>
650 can seriously degrade the level of compression achieved. See the C<zlib>
651 documentation for details.
653 Returns true on success.
662 Returns the uncompressed file offset.
671 Returns true if the C<close> method has been called.
675 $z->seek($position, $whence);
676 seek($z, $position, $whence);
678 Provides a sub-set of the C<seek> functionality, with the restriction
679 that it is only legal to seek forward in the output file/buffer.
680 It is a fatal error to attempt to seek backward.
682 Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
684 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
685 SEEK_CUR or SEEK_END.
687 Returns 1 on success, 0 on failure.
696 This is a noop provided for completeness.
702 Returns true if the object currently refers to a opened file/buffer.
706 my $prev = $z->autoflush()
707 my $prev = $z->autoflush(EXPR)
709 If the C<$z> object is associated with a file or a filehandle, this method
710 returns the current autoflush setting for the underlying filehandle. If
711 C<EXPR> is present, and is non-zero, it will enable flushing after every
712 write/print operation.
714 If C<$z> is associated with a buffer, this method has no effect and always
717 B<Note> that the special variable C<$|> B<cannot> be used to set or
718 retrieve the autoflush setting.
720 =head2 input_line_number
722 $z->input_line_number()
723 $z->input_line_number(EXPR)
725 This method always returns C<undef> when compressing.
732 If the C<$z> object is associated with a file or a filehandle, C<fileno>
733 will return the underlying file descriptor. Once the C<close> method is
734 called C<fileno> will return C<undef>.
736 If the C<$z> object is is associated with a buffer, this method will return
744 Flushes any pending compressed data and then closes the output file/buffer.
746 For most versions of Perl this method will be automatically invoked if
747 the IO::Compress::Deflate object is destroyed (either explicitly or by the
748 variable with the reference to the object going out of scope). The
749 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
750 these cases, the C<close> method will be called automatically, but
751 not until global destruction of all live objects when the program is
754 Therefore, if you want your scripts to be able to run on all versions
755 of Perl, you should call C<close> explicitly and not rely on automatic
758 Returns true on success, otherwise 0.
760 If the C<AutoClose> option has been enabled when the IO::Compress::Deflate
761 object was created, and the object is associated with a file, the
762 underlying file will also be closed.
764 =head2 newStream([OPTS])
768 $z->newStream( [OPTS] )
770 Closes the current compressed data stream and starts a new one.
772 OPTS consists of any of the the options that are available when creating
775 See the L</"Constructor Options"> section for more details.
787 A number of symbolic constants are required by some methods in
788 C<IO::Compress::Deflate>. None are imported by default.
794 Imports C<deflate>, C<$DeflateError> and all symbolic
795 constants that can be used by C<IO::Compress::Deflate>. Same as doing this
797 use IO::Compress::Deflate qw(deflate $DeflateError :constants) ;
801 Import all symbolic constants. Same as doing this
803 use IO::Compress::Deflate qw(:flush :level :strategy) ;
807 These symbolic constants are used by the C<flush> method.
818 These symbolic constants are used by the C<Level> option in the constructor.
823 Z_DEFAULT_COMPRESSION
827 These symbolic constants are used by the C<Strategy> option in the constructor.
842 =head2 Apache::GZip Revisited
844 See L<IO::Compress::Zlib::FAQ|IO::Compress::Zlib::FAQ/"Apache::GZip Revisited">
848 =head2 Working with Net::FTP
850 See L<IO::Compress::Zlib::FAQ|IO::Compress::Zlib::FAQ/"Compressed files and Net::FTP">
854 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>
856 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
858 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
859 L<Archive::Tar|Archive::Tar>,
862 For RFC 1950, 1951 and 1952 see
863 F<http://www.faqs.org/rfcs/rfc1950.html>,
864 F<http://www.faqs.org/rfcs/rfc1951.html> and
865 F<http://www.faqs.org/rfcs/rfc1952.html>
867 The I<zlib> compression library was written by Jean-loup Gailly
868 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
870 The primary site for the I<zlib> compression library is
871 F<http://www.zlib.org>.
873 The primary site for gzip is F<http://www.gzip.org>.
877 This module was written by Paul Marquess, F<pmqs@cpan.org>.
879 =head1 MODIFICATION HISTORY
881 See the Changes file.
883 =head1 COPYRIGHT AND LICENSE
885 Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
887 This program is free software; you can redistribute it and/or
888 modify it under the same terms as Perl itself.