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_12';
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.
251 For reading RFC 1950 files/buffers, see the companion module
252 L<IO::Uncompress::Inflate|IO::Uncompress::Inflate>.
255 =head1 Functional Interface
257 A top-level function, C<deflate>, is provided to carry out
258 "one-shot" compression between buffers and/or files. For finer
259 control over the compression process, see the L</"OO Interface">
262 use IO::Compress::Deflate qw(deflate $DeflateError) ;
264 deflate $input => $output [,OPTS]
265 or die "deflate failed: $DeflateError\n";
269 The functional interface needs Perl5.005 or better.
272 =head2 deflate $input => $output [, OPTS]
275 C<deflate> expects at least two parameters, C<$input> and C<$output>.
277 =head3 The C<$input> parameter
279 The parameter, C<$input>, is used to define the source of
280 the uncompressed data.
282 It can take one of the following forms:
288 If the C<$input> parameter is a simple scalar, it is assumed to be a
289 filename. This file will be opened for reading and the input data
290 will be read from it.
294 If the C<$input> parameter is a filehandle, the input data will be
296 The string '-' can be used as an alias for standard input.
298 =item A scalar reference
300 If C<$input> is a scalar reference, the input data will be read
303 =item An array reference
305 If C<$input> is an array reference, each element in the array must be a
308 The input data will be read from each file in turn.
310 The complete array will be walked to ensure that it only
311 contains valid filenames before any data is compressed.
315 =item An Input FileGlob string
317 If C<$input> is a string that is delimited by the characters "<" and ">"
318 C<deflate> will assume that it is an I<input fileglob string>. The
319 input is the list of files that match the fileglob.
321 If the fileglob does not match any files ...
323 See L<File::GlobMapper|File::GlobMapper> for more details.
328 If the C<$input> parameter is any other type, C<undef> will be returned.
332 =head3 The C<$output> parameter
334 The parameter C<$output> is used to control the destination of the
335 compressed data. This parameter can take one of these forms.
341 If the C<$output> parameter is a simple scalar, it is assumed to be a
342 filename. This file will be opened for writing and the compressed
343 data will be written to it.
347 If the C<$output> parameter is a filehandle, the compressed data
348 will be written to it.
349 The string '-' can be used as an alias for standard output.
352 =item A scalar reference
354 If C<$output> is a scalar reference, the compressed data will be
355 stored in C<$$output>.
359 =item An Array Reference
361 If C<$output> is an array reference, the compressed data will be
362 pushed onto the array.
364 =item An Output FileGlob
366 If C<$output> is a string that is delimited by the characters "<" and ">"
367 C<deflate> will assume that it is an I<output fileglob string>. The
368 output is the list of files that match the fileglob.
370 When C<$output> is an fileglob string, C<$input> must also be a fileglob
371 string. Anything else is an error.
375 If the C<$output> parameter is any other type, C<undef> will be returned.
383 When C<$input> maps to multiple files/buffers and C<$output> is a single
384 file/buffer the input files/buffers will be stored
385 in C<$output> as a concatenated series of compressed data streams.
392 =head2 Optional Parameters
394 Unless specified below, the optional parameters for C<deflate>,
395 C<OPTS>, are the same as those used with the OO interface defined in the
396 L</"Constructor Options"> section below.
400 =item AutoClose =E<gt> 0|1
402 This option applies to any input or output data streams to
403 C<deflate> that are filehandles.
405 If C<AutoClose> is specified, and the value is true, it will result in all
406 input and/or output filehandles being closed once C<deflate> has
409 This parameter defaults to 0.
413 =item BinModeIn =E<gt> 0|1
415 When reading from a file or filehandle, set C<binmode> before reading.
423 =item -Append =E<gt> 0|1
434 To read the contents of the file C<file1.txt> and write the compressed
435 data to the file C<file1.txt.1950>.
439 use IO::Compress::Deflate qw(deflate $DeflateError) ;
441 my $input = "file1.txt";
442 deflate $input => "$input.1950"
443 or die "deflate failed: $DeflateError\n";
446 To read from an existing Perl filehandle, C<$input>, and write the
447 compressed data to a buffer, C<$buffer>.
451 use IO::Compress::Deflate qw(deflate $DeflateError) ;
454 my $input = new IO::File "<file1.txt"
455 or die "Cannot open 'file1.txt': $!\n" ;
457 deflate $input => \$buffer
458 or die "deflate failed: $DeflateError\n";
460 To compress all files in the directory "/my/home" that match "*.txt"
461 and store the compressed data in the same directory
465 use IO::Compress::Deflate qw(deflate $DeflateError) ;
467 deflate '</my/home/*.txt>' => '<*.1950>'
468 or die "deflate failed: $DeflateError\n";
470 and if you want to compress each file one at a time, this will do the trick
474 use IO::Compress::Deflate qw(deflate $DeflateError) ;
476 for my $input ( glob "/my/home/*.txt" )
478 my $output = "$input.1950" ;
479 deflate $input => $output
480 or die "Error compressing '$input': $DeflateError\n";
488 The format of the constructor for C<IO::Compress::Deflate> is shown below
490 my $z = new IO::Compress::Deflate $output [,OPTS]
491 or die "IO::Compress::Deflate failed: $DeflateError\n";
493 It returns an C<IO::Compress::Deflate> object on success and undef on failure.
494 The variable C<$DeflateError> will contain an error message on failure.
496 If you are running Perl 5.005 or better the object, C<$z>, returned from
497 IO::Compress::Deflate can be used exactly like an L<IO::File|IO::File> filehandle.
498 This means that all normal output file operations can be carried out
500 For example, to write to a compressed file/buffer you can use either of
503 $z->print("hello world\n");
504 print $z "hello world\n";
506 The mandatory parameter C<$output> is used to control the destination
507 of the compressed data. This parameter can take one of these forms.
513 If the C<$output> parameter is a simple scalar, it is assumed to be a
514 filename. This file will be opened for writing and the compressed data
515 will be written to it.
519 If the C<$output> parameter is a filehandle, the compressed data will be
521 The string '-' can be used as an alias for standard output.
524 =item A scalar reference
526 If C<$output> is a scalar reference, the compressed data will be stored
531 If the C<$output> parameter is any other type, C<IO::Compress::Deflate>::new will
534 =head2 Constructor Options
536 C<OPTS> is any combination of the following options:
540 =item AutoClose =E<gt> 0|1
542 This option is only valid when the C<$output> parameter is a filehandle. If
543 specified, and the value is true, it will result in the C<$output> being
544 closed once either the C<close> method is called or the C<IO::Compress::Deflate>
547 This parameter defaults to 0.
549 =item Append =E<gt> 0|1
551 Opens C<$output> in append mode.
553 The behaviour of this option is dependent on the type of C<$output>.
559 If C<$output> is a buffer and C<Append> is enabled, all compressed data
560 will be append to the end if C<$output>. Otherwise C<$output> will be
561 cleared before any data is written to it.
565 If C<$output> is a filename and C<Append> is enabled, the file will be
566 opened in append mode. Otherwise the contents of the file, if any, will be
567 truncated before any compressed data is written to it.
571 If C<$output> is a filehandle, the file pointer will be positioned to the
572 end of the file via a call to C<seek> before any compressed data is written
573 to it. Otherwise the file pointer will not be moved.
577 This parameter defaults to 0.
583 =item Merge =E<gt> 0|1
585 This option is used to compress input data and append it to an existing
586 compressed data stream in C<$output>. The end result is a single compressed
587 data stream stored in C<$output>.
591 It is a fatal error to attempt to use this option when C<$output> is not an
592 RFC 1950 data stream.
596 There are a number of other limitations with the C<Merge> option:
602 This module needs to have been built with zlib 1.2.1 or better to work. A
603 fatal error will be thrown if C<Merge> is used with an older version of
608 If C<$output> is a file or a filehandle, it must be seekable.
613 This parameter defaults to 0.
619 Defines the compression level used by zlib. The value should either be
620 a number between 0 and 9 (0 means no compression and 9 is maximum
621 compression), or one of the symbolic constants defined below.
626 Z_DEFAULT_COMPRESSION
628 The default is Z_DEFAULT_COMPRESSION.
630 Note, these constants are not imported by C<IO::Compress::Deflate> by default.
632 use IO::Compress::Deflate qw(:strategy);
633 use IO::Compress::Deflate qw(:constants);
634 use IO::Compress::Deflate qw(:all);
638 Defines the strategy used to tune the compression. Use one of the symbolic
639 constants defined below.
647 The default is Z_DEFAULT_STRATEGY.
654 =item -Strict =E<gt> 0|1
658 This is a placeholder option.
677 Compresses and outputs the contents of the C<$data> parameter. This
678 has the same behaviour as the C<print> built-in.
680 Returns true if successful.
686 $z->printf($format, $data)
687 printf $z $format, $data
689 Compresses and outputs the contents of the C<$data> parameter.
691 Returns true if successful.
698 $z->syswrite $data, $length
699 $z->syswrite $data, $length, $offset
701 Compresses and outputs the contents of the C<$data> parameter.
703 Returns the number of uncompressed bytes written, or C<undef> if
711 $z->write $data, $length
712 $z->write $data, $length, $offset
714 Compresses and outputs the contents of the C<$data> parameter.
716 Returns the number of uncompressed bytes written, or C<undef> if
725 $z->flush($flush_type);
728 Flushes any pending compressed data to the output file/buffer.
731 This method takes an optional parameter, C<$flush_type>, that controls
732 how the flushing will be carried out. By default the C<$flush_type>
733 used is C<Z_FINISH>. Other valid values for C<$flush_type> are
734 C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
735 strongly recommended that you only set the C<flush_type> parameter if
736 you fully understand the implications of what it does - overuse of C<flush>
737 can seriously degrade the level of compression achieved. See the C<zlib>
738 documentation for details.
741 Returns true on success.
751 Returns the uncompressed file offset.
762 Returns true if the C<close> method has been called.
768 $z->seek($position, $whence);
769 seek($z, $position, $whence);
774 Provides a sub-set of the C<seek> functionality, with the restriction
775 that it is only legal to seek forward in the output file/buffer.
776 It is a fatal error to attempt to seek backward.
778 Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
782 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
783 SEEK_CUR or SEEK_END.
785 Returns 1 on success, 0 on failure.
794 This is a noop provided for completeness.
800 Returns true if the object currently refers to a opened file/buffer.
804 my $prev = $z->autoflush()
805 my $prev = $z->autoflush(EXPR)
807 If the C<$z> object is associated with a file or a filehandle, this method
808 returns the current autoflush setting for the underlying filehandle. If
809 C<EXPR> is present, and is non-zero, it will enable flushing after every
810 write/print operation.
812 If C<$z> is associated with a buffer, this method has no effect and always
815 B<Note> that the special variable C<$|> B<cannot> be used to set or
816 retrieve the autoflush setting.
818 =head2 input_line_number
820 $z->input_line_number()
821 $z->input_line_number(EXPR)
824 This method always returns C<undef> when compressing.
833 If the C<$z> object is associated with a file or a filehandle, this method
834 will return the underlying file descriptor.
836 If the C<$z> object is is associated with a buffer, this method will
846 Flushes any pending compressed data and then closes the output file/buffer.
850 For most versions of Perl this method will be automatically invoked if
851 the IO::Compress::Deflate object is destroyed (either explicitly or by the
852 variable with the reference to the object going out of scope). The
853 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
854 these cases, the C<close> method will be called automatically, but
855 not until global destruction of all live objects when the program is
858 Therefore, if you want your scripts to be able to run on all versions
859 of Perl, you should call C<close> explicitly and not rely on automatic
862 Returns true on success, otherwise 0.
864 If the C<AutoClose> option has been enabled when the IO::Compress::Deflate
865 object was created, and the object is associated with a file, the
866 underlying file will also be closed.
871 =head2 newStream([OPTS])
875 $z->newStream( [OPTS] )
877 Closes the current compressed data stream and starts a new one.
879 OPTS consists of the following sub-set of the the options that are
880 available when creating the C<$z> object,
905 A number of symbolic constants are required by some methods in
906 C<IO::Compress::Deflate>. None are imported by default.
915 Imports C<deflate>, C<$DeflateError> and all symbolic
916 constants that can be used by C<IO::Compress::Deflate>. Same as doing this
918 use IO::Compress::Deflate qw(deflate $DeflateError :constants) ;
922 Import all symbolic constants. Same as doing this
925 use IO::Compress::Deflate qw(:flush :level :strategy) ;
930 These symbolic constants are used by the C<flush> method.
941 These symbolic constants are used by the C<Level> option in the constructor.
946 Z_DEFAULT_COMPRESSION
951 These symbolic constants are used by the C<Strategy> option in the constructor.
977 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>
979 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
981 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
982 L<Archive::Tar|Archive::Tar>,
986 For RFC 1950, 1951 and 1952 see
987 F<http://www.faqs.org/rfcs/rfc1950.html>,
988 F<http://www.faqs.org/rfcs/rfc1951.html> and
989 F<http://www.faqs.org/rfcs/rfc1952.html>
991 The I<zlib> compression library was written by Jean-loup Gailly
992 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
994 The primary site for the I<zlib> compression library is
995 F<http://www.zlib.org>.
997 The primary site for gzip is F<http://www.gzip.org>.
1004 This module was written by Paul Marquess, F<pmqs@cpan.org>.
1008 =head1 MODIFICATION HISTORY
1010 See the Changes file.
1012 =head1 COPYRIGHT AND LICENSE
1014 Copyright (c) 2005-2006 Paul Marquess. All rights reserved.
1016 This program is free software; you can redistribute it and/or
1017 modify it under the same terms as Perl itself.