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_11';
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;
252 IO::Compress::RawDeflate - Write RFC 1951 files/buffers
258 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
261 my $status = rawdeflate $input => $output [,OPTS]
262 or die "rawdeflate failed: $RawDeflateError\n";
264 my $z = new IO::Compress::RawDeflate $output [,OPTS]
265 or die "rawdeflate failed: $RawDeflateError\n";
268 $z->printf($format, $string);
270 $z->syswrite($string [, $length, $offset]);
274 $z->seek($position, $whence);
279 $z->input_line_number();
280 $z->newStream( [OPTS] );
291 printf $z $format, $string;
294 seek $z, $position, $whence
304 B<WARNING -- This is a Beta release>.
308 =item * DO NOT use in production code.
310 =item * The documentation is incomplete in places.
312 =item * Parts of the interface defined here are tentative.
314 =item * Please report any problems you find.
321 This module provides a Perl interface that allows writing compressed
322 data to files or buffer as defined in RFC 1951.
328 Note that RFC 1951 data is not a good choice of compression format
329 to use in isolation, especially if you want to auto-detect it.
335 For reading RFC 1951 files/buffers, see the companion module
336 L<IO::Uncompress::RawInflate|IO::Uncompress::RawInflate>.
339 =head1 Functional Interface
341 A top-level function, C<rawdeflate>, is provided to carry out
342 "one-shot" compression between buffers and/or files. For finer
343 control over the compression process, see the L</"OO Interface">
346 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
348 rawdeflate $input => $output [,OPTS]
349 or die "rawdeflate failed: $RawDeflateError\n";
353 The functional interface needs Perl5.005 or better.
356 =head2 rawdeflate $input => $output [, OPTS]
359 C<rawdeflate> expects at least two parameters, C<$input> and C<$output>.
361 =head3 The C<$input> parameter
363 The parameter, C<$input>, is used to define the source of
364 the uncompressed data.
366 It can take one of the following forms:
372 If the C<$input> parameter is a simple scalar, it is assumed to be a
373 filename. This file will be opened for reading and the input data
374 will be read from it.
378 If the C<$input> parameter is a filehandle, the input data will be
380 The string '-' can be used as an alias for standard input.
382 =item A scalar reference
384 If C<$input> is a scalar reference, the input data will be read
387 =item An array reference
389 If C<$input> is an array reference, each element in the array must be a
392 The input data will be read from each file in turn.
394 The complete array will be walked to ensure that it only
395 contains valid filenames before any data is compressed.
399 =item An Input FileGlob string
401 If C<$input> is a string that is delimited by the characters "<" and ">"
402 C<rawdeflate> will assume that it is an I<input fileglob string>. The
403 input is the list of files that match the fileglob.
405 If the fileglob does not match any files ...
407 See L<File::GlobMapper|File::GlobMapper> for more details.
412 If the C<$input> parameter is any other type, C<undef> will be returned.
416 =head3 The C<$output> parameter
418 The parameter C<$output> is used to control the destination of the
419 compressed data. This parameter can take one of these forms.
425 If the C<$output> parameter is a simple scalar, it is assumed to be a
426 filename. This file will be opened for writing and the compressed
427 data will be written to it.
431 If the C<$output> parameter is a filehandle, the compressed data
432 will be written to it.
433 The string '-' can be used as an alias for standard output.
436 =item A scalar reference
438 If C<$output> is a scalar reference, the compressed data will be
439 stored in C<$$output>.
443 =item An Array Reference
445 If C<$output> is an array reference, the compressed data will be
446 pushed onto the array.
448 =item An Output FileGlob
450 If C<$output> is a string that is delimited by the characters "<" and ">"
451 C<rawdeflate> will assume that it is an I<output fileglob string>. The
452 output is the list of files that match the fileglob.
454 When C<$output> is an fileglob string, C<$input> must also be a fileglob
455 string. Anything else is an error.
459 If the C<$output> parameter is any other type, C<undef> will be returned.
465 When C<$input> maps to multiple files/buffers and C<$output> is a single
466 file/buffer the compressed input files/buffers will all be stored
467 in C<$output> as a single compressed stream.
471 =head2 Optional Parameters
473 Unless specified below, the optional parameters for C<rawdeflate>,
474 C<OPTS>, are the same as those used with the OO interface defined in the
475 L</"Constructor Options"> section below.
479 =item AutoClose =E<gt> 0|1
481 This option applies to any input or output data streams to
482 C<rawdeflate> that are filehandles.
484 If C<AutoClose> is specified, and the value is true, it will result in all
485 input and/or output filehandles being closed once C<rawdeflate> has
488 This parameter defaults to 0.
492 =item BinModeIn =E<gt> 0|1
494 When reading from a file or filehandle, set C<binmode> before reading.
502 =item -Append =E<gt> 0|1
513 To read the contents of the file C<file1.txt> and write the compressed
514 data to the file C<file1.txt.1951>.
518 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
520 my $input = "file1.txt";
521 rawdeflate $input => "$input.1951"
522 or die "rawdeflate failed: $RawDeflateError\n";
525 To read from an existing Perl filehandle, C<$input>, and write the
526 compressed data to a buffer, C<$buffer>.
530 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
533 my $input = new IO::File "<file1.txt"
534 or die "Cannot open 'file1.txt': $!\n" ;
536 rawdeflate $input => \$buffer
537 or die "rawdeflate failed: $RawDeflateError\n";
539 To compress all files in the directory "/my/home" that match "*.txt"
540 and store the compressed data in the same directory
544 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
546 rawdeflate '</my/home/*.txt>' => '<*.1951>'
547 or die "rawdeflate failed: $RawDeflateError\n";
549 and if you want to compress each file one at a time, this will do the trick
553 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
555 for my $input ( glob "/my/home/*.txt" )
557 my $output = "$input.1951" ;
558 rawdeflate $input => $output
559 or die "Error compressing '$input': $RawDeflateError\n";
567 The format of the constructor for C<IO::Compress::RawDeflate> is shown below
569 my $z = new IO::Compress::RawDeflate $output [,OPTS]
570 or die "IO::Compress::RawDeflate failed: $RawDeflateError\n";
572 It returns an C<IO::Compress::RawDeflate> object on success and undef on failure.
573 The variable C<$RawDeflateError> will contain an error message on failure.
575 If you are running Perl 5.005 or better the object, C<$z>, returned from
576 IO::Compress::RawDeflate can be used exactly like an L<IO::File|IO::File> filehandle.
577 This means that all normal output file operations can be carried out
579 For example, to write to a compressed file/buffer you can use either of
582 $z->print("hello world\n");
583 print $z "hello world\n";
585 The mandatory parameter C<$output> is used to control the destination
586 of the compressed data. This parameter can take one of these forms.
592 If the C<$output> parameter is a simple scalar, it is assumed to be a
593 filename. This file will be opened for writing and the compressed data
594 will be written to it.
598 If the C<$output> parameter is a filehandle, the compressed data will be
600 The string '-' can be used as an alias for standard output.
603 =item A scalar reference
605 If C<$output> is a scalar reference, the compressed data will be stored
610 If the C<$output> parameter is any other type, C<IO::Compress::RawDeflate>::new will
613 =head2 Constructor Options
615 C<OPTS> is any combination of the following options:
619 =item AutoClose =E<gt> 0|1
621 This option is only valid when the C<$output> parameter is a filehandle. If
622 specified, and the value is true, it will result in the C<$output> being
623 closed once either the C<close> method is called or the C<IO::Compress::RawDeflate>
626 This parameter defaults to 0.
628 =item Append =E<gt> 0|1
630 Opens C<$output> in append mode.
632 The behaviour of this option is dependent on the type of C<$output>.
638 If C<$output> is a buffer and C<Append> is enabled, all compressed data
639 will be append to the end if C<$output>. Otherwise C<$output> will be
640 cleared before any data is written to it.
644 If C<$output> is a filename and C<Append> is enabled, the file will be
645 opened in append mode. Otherwise the contents of the file, if any, will be
646 truncated before any compressed data is written to it.
650 If C<$output> is a filehandle, the file pointer will be positioned to the
651 end of the file via a call to C<seek> before any compressed data is written
652 to it. Otherwise the file pointer will not be moved.
656 This parameter defaults to 0.
662 =item Merge =E<gt> 0|1
664 This option is used to compress input data and append it to an existing
665 compressed data stream in C<$output>. The end result is a single compressed
666 data stream stored in C<$output>.
670 It is a fatal error to attempt to use this option when C<$output> is not an
671 RFC 1951 data stream.
675 There are a number of other limitations with the C<Merge> option:
681 This module needs to have been built with zlib 1.2.1 or better to work. A
682 fatal error will be thrown if C<Merge> is used with an older version of
687 If C<$output> is a file or a filehandle, it must be seekable.
692 This parameter defaults to 0.
698 Defines the compression level used by zlib. The value should either be
699 a number between 0 and 9 (0 means no compression and 9 is maximum
700 compression), or one of the symbolic constants defined below.
705 Z_DEFAULT_COMPRESSION
707 The default is Z_DEFAULT_COMPRESSION.
709 Note, these constants are not imported by C<IO::Compress::RawDeflate> by default.
711 use IO::Compress::RawDeflate qw(:strategy);
712 use IO::Compress::RawDeflate qw(:constants);
713 use IO::Compress::RawDeflate qw(:all);
717 Defines the strategy used to tune the compression. Use one of the symbolic
718 constants defined below.
726 The default is Z_DEFAULT_STRATEGY.
733 =item -Strict =E<gt> 0|1
737 This is a placeholder option.
756 Compresses and outputs the contents of the C<$data> parameter. This
757 has the same behaviour as the C<print> built-in.
759 Returns true if successful.
765 $z->printf($format, $data)
766 printf $z $format, $data
768 Compresses and outputs the contents of the C<$data> parameter.
770 Returns true if successful.
777 $z->syswrite $data, $length
778 $z->syswrite $data, $length, $offset
780 Compresses and outputs the contents of the C<$data> parameter.
782 Returns the number of uncompressed bytes written, or C<undef> if
790 $z->write $data, $length
791 $z->write $data, $length, $offset
793 Compresses and outputs the contents of the C<$data> parameter.
795 Returns the number of uncompressed bytes written, or C<undef> if
804 $z->flush($flush_type);
807 Flushes any pending compressed data to the output file/buffer.
810 This method takes an optional parameter, C<$flush_type>, that controls
811 how the flushing will be carried out. By default the C<$flush_type>
812 used is C<Z_FINISH>. Other valid values for C<$flush_type> are
813 C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
814 strongly recommended that you only set the C<flush_type> parameter if
815 you fully understand the implications of what it does - overuse of C<flush>
816 can seriously degrade the level of compression achieved. See the C<zlib>
817 documentation for details.
820 Returns true on success.
830 Returns the uncompressed file offset.
841 Returns true if the C<close> method has been called.
847 $z->seek($position, $whence);
848 seek($z, $position, $whence);
853 Provides a sub-set of the C<seek> functionality, with the restriction
854 that it is only legal to seek forward in the output file/buffer.
855 It is a fatal error to attempt to seek backward.
857 Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
861 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
862 SEEK_CUR or SEEK_END.
864 Returns 1 on success, 0 on failure.
873 This is a noop provided for completeness.
879 Returns true if the object currently refers to a opened file/buffer.
883 my $prev = $z->autoflush()
884 my $prev = $z->autoflush(EXPR)
886 If the C<$z> object is associated with a file or a filehandle, this method
887 returns the current autoflush setting for the underlying filehandle. If
888 C<EXPR> is present, and is non-zero, it will enable flushing after every
889 write/print operation.
891 If C<$z> is associated with a buffer, this method has no effect and always
894 B<Note> that the special variable C<$|> B<cannot> be used to set or
895 retrieve the autoflush setting.
897 =head2 input_line_number
899 $z->input_line_number()
900 $z->input_line_number(EXPR)
903 This method always returns C<undef> when compressing.
912 If the C<$z> object is associated with a file or a filehandle, this method
913 will return the underlying file descriptor.
915 If the C<$z> object is is associated with a buffer, this method will
925 Flushes any pending compressed data and then closes the output file/buffer.
929 For most versions of Perl this method will be automatically invoked if
930 the IO::Compress::RawDeflate object is destroyed (either explicitly or by the
931 variable with the reference to the object going out of scope). The
932 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
933 these cases, the C<close> method will be called automatically, but
934 not until global destruction of all live objects when the program is
937 Therefore, if you want your scripts to be able to run on all versions
938 of Perl, you should call C<close> explicitly and not rely on automatic
941 Returns true on success, otherwise 0.
943 If the C<AutoClose> option has been enabled when the IO::Compress::RawDeflate
944 object was created, and the object is associated with a file, the
945 underlying file will also be closed.
950 =head2 newStream([OPTS])
954 $z->newStream( [OPTS] )
956 Closes the current compressed data stream and starts a new one.
958 OPTS consists of the following sub-set of the the options that are
959 available when creating the C<$z> object,
984 A number of symbolic constants are required by some methods in
985 C<IO::Compress::RawDeflate>. None are imported by default.
994 Imports C<rawdeflate>, C<$RawDeflateError> and all symbolic
995 constants that can be used by C<IO::Compress::RawDeflate>. Same as doing this
997 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError :constants) ;
1001 Import all symbolic constants. Same as doing this
1004 use IO::Compress::RawDeflate qw(:flush :level :strategy) ;
1009 These symbolic constants are used by the C<flush> method.
1020 These symbolic constants are used by the C<Level> option in the constructor.
1025 Z_DEFAULT_COMPRESSION
1030 These symbolic constants are used by the C<Strategy> option in the constructor.
1056 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>
1058 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1060 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1061 L<Archive::Tar|Archive::Tar>,
1062 L<IO::Zlib|IO::Zlib>
1065 For RFC 1950, 1951 and 1952 see
1066 F<http://www.faqs.org/rfcs/rfc1950.html>,
1067 F<http://www.faqs.org/rfcs/rfc1951.html> and
1068 F<http://www.faqs.org/rfcs/rfc1952.html>
1070 The I<zlib> compression library was written by Jean-loup Gailly
1071 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1073 The primary site for the I<zlib> compression library is
1074 F<http://www.zlib.org>.
1076 The primary site for gzip is F<http://www.gzip.org>.
1083 This module was written by Paul Marquess, F<pmqs@cpan.org>.
1087 =head1 MODIFICATION HISTORY
1089 See the Changes file.
1091 =head1 COPYRIGHT AND LICENSE
1093 Copyright (c) 2005-2006 Paul Marquess. All rights reserved.
1095 This program is free software; you can redistribute it and/or
1096 modify it under the same terms as Perl itself.