1 package IO::Compress::RawDeflate ;
10 use IO::Compress::Base;
11 use IO::Compress::Base::Common qw(:Status createSelfTiedObject);
12 use IO::Compress::Adapter::Deflate ;
17 our ($VERSION, @ISA, @EXPORT_OK, %DEFLATE_CONSTANTS, %EXPORT_TAGS, $RawDeflateError);
19 $VERSION = '2.000_08';
20 $RawDeflateError = '';
22 @ISA = qw(Exporter IO::Compress::Base);
23 @EXPORT_OK = qw( $RawDeflateError rawdeflate ) ;
24 push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
26 %EXPORT_TAGS = ( flush => [qw{
52 foreach (keys %EXPORT_TAGS )
54 push @{$EXPORT_TAGS{constants}},
58 $EXPORT_TAGS{all} = $EXPORT_TAGS{constants} ;
61 %DEFLATE_CONSTANTS = %EXPORT_TAGS;
63 Exporter::export_ok_tags('all');
71 my $obj = createSelfTiedObject($class, \$RawDeflateError);
73 return $obj->_create(undef, @_);
78 my $obj = createSelfTiedObject(undef, \$RawDeflateError);
79 return $obj->_def(@_);
96 my ($obj, $errstr, $errno) = IO::Compress::Adapter::Deflate::mkCompObject(
98 $got->value('Adler32'),
100 $got->value('Strategy')
103 return $self->saveErrorString(undef, $errstr, $errno)
137 return $self->getZlibParams();
144 use IO::Compress::Base::Common qw(:Parse);
145 use Compress::Raw::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;
251 IO::Compress::RawDeflate - Perl interface to write RFC 1951 files/buffers
256 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
259 my $status = rawdeflate $input => $output [,OPTS]
260 or die "rawdeflate failed: $RawDeflateError\n";
262 my $z = new IO::Compress::RawDeflate $output [,OPTS]
263 or die "rawdeflate failed: $RawDeflateError\n";
266 $z->printf($format, $string);
268 $z->syswrite($string [, $length, $offset]);
272 $z->seek($position, $whence);
277 $z->input_line_number();
278 $z->newStream( [OPTS] );
289 printf $z $format, $string;
292 seek $z, $position, $whence
302 B<WARNING -- This is a Beta release>.
306 =item * DO NOT use in production code.
308 =item * The documentation is incomplete in places.
310 =item * Parts of the interface defined here are tentative.
312 =item * Please report any problems you find.
319 This module provides a Perl interface that allows writing compressed
320 data to files or buffer as defined in RFC 1951.
326 Note that RFC 1951 data is not a good choice of compression format
327 to use in isolation, especially if you want to auto-detect it.
333 For reading RFC 1951 files/buffers, see the companion module
334 L<IO::Uncompress::RawInflate|IO::Uncompress::RawInflate>.
337 =head1 Functional Interface
339 A top-level function, C<rawdeflate>, is provided to carry out
340 "one-shot" compression between buffers and/or files. For finer
341 control over the compression process, see the L</"OO Interface">
344 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
346 rawdeflate $input => $output [,OPTS]
347 or die "rawdeflate failed: $RawDeflateError\n";
351 The functional interface needs Perl5.005 or better.
354 =head2 rawdeflate $input => $output [, OPTS]
357 C<rawdeflate> expects at least two parameters, C<$input> and C<$output>.
359 =head3 The C<$input> parameter
361 The parameter, C<$input>, is used to define the source of
362 the uncompressed data.
364 It can take one of the following forms:
370 If the C<$input> parameter is a simple scalar, it is assumed to be a
371 filename. This file will be opened for reading and the input data
372 will be read from it.
376 If the C<$input> parameter is a filehandle, the input data will be
378 The string '-' can be used as an alias for standard input.
380 =item A scalar reference
382 If C<$input> is a scalar reference, the input data will be read
385 =item An array reference
387 If C<$input> is an array reference, each element in the array must be a
390 The input data will be read from each file in turn.
392 The complete array will be walked to ensure that it only
393 contains valid filenames before any data is compressed.
397 =item An Input FileGlob string
399 If C<$input> is a string that is delimited by the characters "<" and ">"
400 C<rawdeflate> will assume that it is an I<input fileglob string>. The
401 input is the list of files that match the fileglob.
403 If the fileglob does not match any files ...
405 See L<File::GlobMapper|File::GlobMapper> for more details.
410 If the C<$input> parameter is any other type, C<undef> will be returned.
414 =head3 The C<$output> parameter
416 The parameter C<$output> is used to control the destination of the
417 compressed data. This parameter can take one of these forms.
423 If the C<$output> parameter is a simple scalar, it is assumed to be a
424 filename. This file will be opened for writing and the compressed
425 data will be written to it.
429 If the C<$output> parameter is a filehandle, the compressed data
430 will be written to it.
431 The string '-' can be used as an alias for standard output.
434 =item A scalar reference
436 If C<$output> is a scalar reference, the compressed data will be
437 stored in C<$$output>.
441 =item An Array Reference
443 If C<$output> is an array reference, the compressed data will be
444 pushed onto the array.
446 =item An Output FileGlob
448 If C<$output> is a string that is delimited by the characters "<" and ">"
449 C<rawdeflate> will assume that it is an I<output fileglob string>. The
450 output is the list of files that match the fileglob.
452 When C<$output> is an fileglob string, C<$input> must also be a fileglob
453 string. Anything else is an error.
457 If the C<$output> parameter is any other type, C<undef> will be returned.
463 When C<$input> maps to multiple files/buffers and C<$output> is a single
464 file/buffer the compressed input files/buffers will all be stored
465 in C<$output> as a single compressed stream.
469 =head2 Optional Parameters
471 Unless specified below, the optional parameters for C<rawdeflate>,
472 C<OPTS>, are the same as those used with the OO interface defined in the
473 L</"Constructor Options"> section below.
477 =item AutoClose =E<gt> 0|1
479 This option applies to any input or output data streams to
480 C<rawdeflate> that are filehandles.
482 If C<AutoClose> is specified, and the value is true, it will result in all
483 input and/or output filehandles being closed once C<rawdeflate> has
486 This parameter defaults to 0.
490 =item BinModeIn =E<gt> 0|1
492 When reading from a file or filehandle, set C<binmode> before reading.
500 =item -Append =E<gt> 0|1
511 To read the contents of the file C<file1.txt> and write the compressed
512 data to the file C<file1.txt.1951>.
516 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
518 my $input = "file1.txt";
519 rawdeflate $input => "$input.1951"
520 or die "rawdeflate failed: $RawDeflateError\n";
523 To read from an existing Perl filehandle, C<$input>, and write the
524 compressed data to a buffer, C<$buffer>.
528 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
531 my $input = new IO::File "<file1.txt"
532 or die "Cannot open 'file1.txt': $!\n" ;
534 rawdeflate $input => \$buffer
535 or die "rawdeflate failed: $RawDeflateError\n";
537 To compress all files in the directory "/my/home" that match "*.txt"
538 and store the compressed data in the same directory
542 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
544 rawdeflate '</my/home/*.txt>' => '<*.1951>'
545 or die "rawdeflate failed: $RawDeflateError\n";
547 and if you want to compress each file one at a time, this will do the trick
551 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
553 for my $input ( glob "/my/home/*.txt" )
555 my $output = "$input.1951" ;
556 rawdeflate $input => $output
557 or die "Error compressing '$input': $RawDeflateError\n";
565 The format of the constructor for C<IO::Compress::RawDeflate> is shown below
567 my $z = new IO::Compress::RawDeflate $output [,OPTS]
568 or die "IO::Compress::RawDeflate failed: $RawDeflateError\n";
570 It returns an C<IO::Compress::RawDeflate> object on success and undef on failure.
571 The variable C<$RawDeflateError> will contain an error message on failure.
573 If you are running Perl 5.005 or better the object, C<$z>, returned from
574 IO::Compress::RawDeflate can be used exactly like an L<IO::File|IO::File> filehandle.
575 This means that all normal output file operations can be carried out
577 For example, to write to a compressed file/buffer you can use either of
580 $z->print("hello world\n");
581 print $z "hello world\n";
583 The mandatory parameter C<$output> is used to control the destination
584 of the compressed data. This parameter can take one of these forms.
590 If the C<$output> parameter is a simple scalar, it is assumed to be a
591 filename. This file will be opened for writing and the compressed data
592 will be written to it.
596 If the C<$output> parameter is a filehandle, the compressed data will be
598 The string '-' can be used as an alias for standard output.
601 =item A scalar reference
603 If C<$output> is a scalar reference, the compressed data will be stored
608 If the C<$output> parameter is any other type, C<IO::Compress::RawDeflate>::new will
611 =head2 Constructor Options
613 C<OPTS> is any combination of the following options:
617 =item AutoClose =E<gt> 0|1
619 This option is only valid when the C<$output> parameter is a filehandle. If
620 specified, and the value is true, it will result in the C<$output> being
621 closed once either the C<close> method is called or the C<IO::Compress::RawDeflate>
624 This parameter defaults to 0.
626 =item Append =E<gt> 0|1
628 Opens C<$output> in append mode.
630 The behaviour of this option is dependent on the type of C<$output>.
636 If C<$output> is a buffer and C<Append> is enabled, all compressed data
637 will be append to the end if C<$output>. Otherwise C<$output> will be
638 cleared before any data is written to it.
642 If C<$output> is a filename and C<Append> is enabled, the file will be
643 opened in append mode. Otherwise the contents of the file, if any, will be
644 truncated before any compressed data is written to it.
648 If C<$output> is a filehandle, the file pointer will be positioned to the
649 end of the file via a call to C<seek> before any compressed data is written
650 to it. Otherwise the file pointer will not be moved.
654 This parameter defaults to 0.
660 =item -Merge =E<gt> 0|1
662 This option is used to compress input data and append it to an existing
663 compressed data stream in C<$output>. The end result is a single compressed
664 data stream stored in C<$output>.
668 It is a fatal error to attempt to use this option when C<$output> is not an
669 RFC 1951 data stream.
673 There are a number of other limitations with the C<Merge> option:
679 This module needs to have been built with zlib 1.2.1 or better to work. A
680 fatal error will be thrown if C<Merge> is used with an older version of
685 If C<$output> is a file or a filehandle, it must be seekable.
690 This parameter defaults to 0.
696 Defines the compression level used by zlib. The value should either be
697 a number between 0 and 9 (0 means no compression and 9 is maximum
698 compression), or one of the symbolic constants defined below.
703 Z_DEFAULT_COMPRESSION
705 The default is Z_DEFAULT_COMPRESSION.
707 Note, these constants are not imported by C<IO::Compress::RawDeflate> by default.
709 use IO::Compress::RawDeflate qw(:strategy);
710 use IO::Compress::RawDeflate qw(:constants);
711 use IO::Compress::RawDeflate qw(:all);
715 Defines the strategy used to tune the compression. Use one of the symbolic
716 constants defined below.
724 The default is Z_DEFAULT_STRATEGY.
731 =item -Strict =E<gt> 0|1
735 This is a placeholder option.
754 Compresses and outputs the contents of the C<$data> parameter. This
755 has the same behaviour as the C<print> built-in.
757 Returns true if successful.
763 $z->printf($format, $data)
764 printf $z $format, $data
766 Compresses and outputs the contents of the C<$data> parameter.
768 Returns true if successful.
775 $z->syswrite $data, $length
776 $z->syswrite $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->write $data, $length
789 $z->write $data, $length, $offset
791 Compresses and outputs the contents of the C<$data> parameter.
793 Returns the number of uncompressed bytes written, or C<undef> if
802 $z->flush($flush_type);
805 Flushes any pending compressed data to the output file/buffer.
808 This method takes an optional parameter, C<$flush_type>, that controls
809 how the flushing will be carried out. By default the C<$flush_type>
810 used is C<Z_FINISH>. Other valid values for C<$flush_type> are
811 C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
812 strongly recommended that you only set the C<flush_type> parameter if
813 you fully understand the implications of what it does - overuse of C<flush>
814 can seriously degrade the level of compression achieved. See the C<zlib>
815 documentation for details.
818 Returns true on success.
828 Returns the uncompressed file offset.
839 Returns true if the C<close> method has been called.
845 $z->seek($position, $whence);
846 seek($z, $position, $whence);
851 Provides a sub-set of the C<seek> functionality, with the restriction
852 that it is only legal to seek forward in the output file/buffer.
853 It is a fatal error to attempt to seek backward.
855 Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
859 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
860 SEEK_CUR or SEEK_END.
862 Returns 1 on success, 0 on failure.
871 This is a noop provided for completeness.
877 Returns true if the object currently refers to a opened file/buffer.
881 my $prev = $z->autoflush()
882 my $prev = $z->autoflush(EXPR)
884 If the C<$z> object is associated with a file or a filehandle, this method
885 returns the current autoflush setting for the underlying filehandle. If
886 C<EXPR> is present, and is non-zero, it will enable flushing after every
887 write/print operation.
889 If C<$z> is associated with a buffer, this method has no effect and always
892 B<Note> that the special variable C<$|> B<cannot> be used to set or
893 retrieve the autoflush setting.
895 =head2 input_line_number
897 $z->input_line_number()
898 $z->input_line_number(EXPR)
901 This method always returns C<undef> when compressing.
910 If the C<$z> object is associated with a file or a filehandle, this method
911 will return the underlying file descriptor.
913 If the C<$z> object is is associated with a buffer, this method will
923 Flushes any pending compressed data and then closes the output file/buffer.
927 For most versions of Perl this method will be automatically invoked if
928 the IO::Compress::RawDeflate object is destroyed (either explicitly or by the
929 variable with the reference to the object going out of scope). The
930 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
931 these cases, the C<close> method will be called automatically, but
932 not until global destruction of all live objects when the program is
935 Therefore, if you want your scripts to be able to run on all versions
936 of Perl, you should call C<close> explicitly and not rely on automatic
939 Returns true on success, otherwise 0.
941 If the C<AutoClose> option has been enabled when the IO::Compress::RawDeflate
942 object was created, and the object is associated with a file, the
943 underlying file will also be closed.
948 =head2 newStream([OPTS])
952 $z->newStream( [OPTS] )
954 Closes the current compressed data stream and starts a new one.
956 OPTS consists of the following sub-set of the the options that are
957 available when creating the C<$z> object,
982 A number of symbolic constants are required by some methods in
983 C<IO::Compress::RawDeflate>. None are imported by default.
992 Imports C<rawdeflate>, C<$RawDeflateError> and all symbolic
993 constants that can be used by C<IO::Compress::RawDeflate>. Same as doing this
995 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError :constants) ;
999 Import all symbolic constants. Same as doing this
1001 use IO::Compress::RawDeflate qw(:flush :level :strategy) ;
1005 These symbolic constants are used by the C<flush> method.
1016 These symbolic constants are used by the C<Level> option in the constructor.
1021 Z_DEFAULT_COMPRESSION
1026 These symbolic constants are used by the C<Strategy> option in the constructor.
1050 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::Compress::Bzip2>, L<IO::Uncompress::Bunzip2>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
1052 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1054 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1055 L<Archive::Tar|Archive::Tar>,
1056 L<IO::Zlib|IO::Zlib>
1059 For RFC 1950, 1951 and 1952 see
1060 F<http://www.faqs.org/rfcs/rfc1950.html>,
1061 F<http://www.faqs.org/rfcs/rfc1951.html> and
1062 F<http://www.faqs.org/rfcs/rfc1952.html>
1064 The I<zlib> compression library was written by Jean-loup Gailly
1065 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1067 The primary site for the I<zlib> compression library is
1068 F<http://www.zlib.org>.
1070 The primary site for gzip is F<http://www.gzip.org>.
1080 The I<IO::Compress::RawDeflate> module was written by Paul Marquess,
1085 =head1 MODIFICATION HISTORY
1087 See the Changes file.
1089 =head1 COPYRIGHT AND LICENSE
1092 Copyright (c) 2005-2006 Paul Marquess. All rights reserved.
1094 This program is free software; you can redistribute it and/or
1095 modify it under the same terms as Perl itself.