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_12';
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.
467 When C<$input> maps to multiple files/buffers and C<$output> is a single
468 file/buffer the input files/buffers will be stored
469 in C<$output> as a concatenated series of compressed data streams.
476 =head2 Optional Parameters
478 Unless specified below, the optional parameters for C<rawdeflate>,
479 C<OPTS>, are the same as those used with the OO interface defined in the
480 L</"Constructor Options"> section below.
484 =item AutoClose =E<gt> 0|1
486 This option applies to any input or output data streams to
487 C<rawdeflate> that are filehandles.
489 If C<AutoClose> is specified, and the value is true, it will result in all
490 input and/or output filehandles being closed once C<rawdeflate> has
493 This parameter defaults to 0.
497 =item BinModeIn =E<gt> 0|1
499 When reading from a file or filehandle, set C<binmode> before reading.
507 =item -Append =E<gt> 0|1
518 To read the contents of the file C<file1.txt> and write the compressed
519 data to the file C<file1.txt.1951>.
523 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
525 my $input = "file1.txt";
526 rawdeflate $input => "$input.1951"
527 or die "rawdeflate failed: $RawDeflateError\n";
530 To read from an existing Perl filehandle, C<$input>, and write the
531 compressed data to a buffer, C<$buffer>.
535 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
538 my $input = new IO::File "<file1.txt"
539 or die "Cannot open 'file1.txt': $!\n" ;
541 rawdeflate $input => \$buffer
542 or die "rawdeflate failed: $RawDeflateError\n";
544 To compress all files in the directory "/my/home" that match "*.txt"
545 and store the compressed data in the same directory
549 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
551 rawdeflate '</my/home/*.txt>' => '<*.1951>'
552 or die "rawdeflate failed: $RawDeflateError\n";
554 and if you want to compress each file one at a time, this will do the trick
558 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
560 for my $input ( glob "/my/home/*.txt" )
562 my $output = "$input.1951" ;
563 rawdeflate $input => $output
564 or die "Error compressing '$input': $RawDeflateError\n";
572 The format of the constructor for C<IO::Compress::RawDeflate> is shown below
574 my $z = new IO::Compress::RawDeflate $output [,OPTS]
575 or die "IO::Compress::RawDeflate failed: $RawDeflateError\n";
577 It returns an C<IO::Compress::RawDeflate> object on success and undef on failure.
578 The variable C<$RawDeflateError> will contain an error message on failure.
580 If you are running Perl 5.005 or better the object, C<$z>, returned from
581 IO::Compress::RawDeflate can be used exactly like an L<IO::File|IO::File> filehandle.
582 This means that all normal output file operations can be carried out
584 For example, to write to a compressed file/buffer you can use either of
587 $z->print("hello world\n");
588 print $z "hello world\n";
590 The mandatory parameter C<$output> is used to control the destination
591 of the compressed data. This parameter can take one of these forms.
597 If the C<$output> parameter is a simple scalar, it is assumed to be a
598 filename. This file will be opened for writing and the compressed data
599 will be written to it.
603 If the C<$output> parameter is a filehandle, the compressed data will be
605 The string '-' can be used as an alias for standard output.
608 =item A scalar reference
610 If C<$output> is a scalar reference, the compressed data will be stored
615 If the C<$output> parameter is any other type, C<IO::Compress::RawDeflate>::new will
618 =head2 Constructor Options
620 C<OPTS> is any combination of the following options:
624 =item AutoClose =E<gt> 0|1
626 This option is only valid when the C<$output> parameter is a filehandle. If
627 specified, and the value is true, it will result in the C<$output> being
628 closed once either the C<close> method is called or the C<IO::Compress::RawDeflate>
631 This parameter defaults to 0.
633 =item Append =E<gt> 0|1
635 Opens C<$output> in append mode.
637 The behaviour of this option is dependent on the type of C<$output>.
643 If C<$output> is a buffer and C<Append> is enabled, all compressed data
644 will be append to the end if C<$output>. Otherwise C<$output> will be
645 cleared before any data is written to it.
649 If C<$output> is a filename and C<Append> is enabled, the file will be
650 opened in append mode. Otherwise the contents of the file, if any, will be
651 truncated before any compressed data is written to it.
655 If C<$output> is a filehandle, the file pointer will be positioned to the
656 end of the file via a call to C<seek> before any compressed data is written
657 to it. Otherwise the file pointer will not be moved.
661 This parameter defaults to 0.
667 =item Merge =E<gt> 0|1
669 This option is used to compress input data and append it to an existing
670 compressed data stream in C<$output>. The end result is a single compressed
671 data stream stored in C<$output>.
675 It is a fatal error to attempt to use this option when C<$output> is not an
676 RFC 1951 data stream.
680 There are a number of other limitations with the C<Merge> option:
686 This module needs to have been built with zlib 1.2.1 or better to work. A
687 fatal error will be thrown if C<Merge> is used with an older version of
692 If C<$output> is a file or a filehandle, it must be seekable.
697 This parameter defaults to 0.
703 Defines the compression level used by zlib. The value should either be
704 a number between 0 and 9 (0 means no compression and 9 is maximum
705 compression), or one of the symbolic constants defined below.
710 Z_DEFAULT_COMPRESSION
712 The default is Z_DEFAULT_COMPRESSION.
714 Note, these constants are not imported by C<IO::Compress::RawDeflate> by default.
716 use IO::Compress::RawDeflate qw(:strategy);
717 use IO::Compress::RawDeflate qw(:constants);
718 use IO::Compress::RawDeflate qw(:all);
722 Defines the strategy used to tune the compression. Use one of the symbolic
723 constants defined below.
731 The default is Z_DEFAULT_STRATEGY.
738 =item -Strict =E<gt> 0|1
742 This is a placeholder option.
761 Compresses and outputs the contents of the C<$data> parameter. This
762 has the same behaviour as the C<print> built-in.
764 Returns true if successful.
770 $z->printf($format, $data)
771 printf $z $format, $data
773 Compresses and outputs the contents of the C<$data> parameter.
775 Returns true if successful.
782 $z->syswrite $data, $length
783 $z->syswrite $data, $length, $offset
785 Compresses and outputs the contents of the C<$data> parameter.
787 Returns the number of uncompressed bytes written, or C<undef> if
795 $z->write $data, $length
796 $z->write $data, $length, $offset
798 Compresses and outputs the contents of the C<$data> parameter.
800 Returns the number of uncompressed bytes written, or C<undef> if
809 $z->flush($flush_type);
812 Flushes any pending compressed data to the output file/buffer.
815 This method takes an optional parameter, C<$flush_type>, that controls
816 how the flushing will be carried out. By default the C<$flush_type>
817 used is C<Z_FINISH>. Other valid values for C<$flush_type> are
818 C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
819 strongly recommended that you only set the C<flush_type> parameter if
820 you fully understand the implications of what it does - overuse of C<flush>
821 can seriously degrade the level of compression achieved. See the C<zlib>
822 documentation for details.
825 Returns true on success.
835 Returns the uncompressed file offset.
846 Returns true if the C<close> method has been called.
852 $z->seek($position, $whence);
853 seek($z, $position, $whence);
858 Provides a sub-set of the C<seek> functionality, with the restriction
859 that it is only legal to seek forward in the output file/buffer.
860 It is a fatal error to attempt to seek backward.
862 Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
866 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
867 SEEK_CUR or SEEK_END.
869 Returns 1 on success, 0 on failure.
878 This is a noop provided for completeness.
884 Returns true if the object currently refers to a opened file/buffer.
888 my $prev = $z->autoflush()
889 my $prev = $z->autoflush(EXPR)
891 If the C<$z> object is associated with a file or a filehandle, this method
892 returns the current autoflush setting for the underlying filehandle. If
893 C<EXPR> is present, and is non-zero, it will enable flushing after every
894 write/print operation.
896 If C<$z> is associated with a buffer, this method has no effect and always
899 B<Note> that the special variable C<$|> B<cannot> be used to set or
900 retrieve the autoflush setting.
902 =head2 input_line_number
904 $z->input_line_number()
905 $z->input_line_number(EXPR)
908 This method always returns C<undef> when compressing.
917 If the C<$z> object is associated with a file or a filehandle, this method
918 will return the underlying file descriptor.
920 If the C<$z> object is is associated with a buffer, this method will
930 Flushes any pending compressed data and then closes the output file/buffer.
934 For most versions of Perl this method will be automatically invoked if
935 the IO::Compress::RawDeflate object is destroyed (either explicitly or by the
936 variable with the reference to the object going out of scope). The
937 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
938 these cases, the C<close> method will be called automatically, but
939 not until global destruction of all live objects when the program is
942 Therefore, if you want your scripts to be able to run on all versions
943 of Perl, you should call C<close> explicitly and not rely on automatic
946 Returns true on success, otherwise 0.
948 If the C<AutoClose> option has been enabled when the IO::Compress::RawDeflate
949 object was created, and the object is associated with a file, the
950 underlying file will also be closed.
955 =head2 newStream([OPTS])
959 $z->newStream( [OPTS] )
961 Closes the current compressed data stream and starts a new one.
963 OPTS consists of the following sub-set of the the options that are
964 available when creating the C<$z> object,
989 A number of symbolic constants are required by some methods in
990 C<IO::Compress::RawDeflate>. None are imported by default.
999 Imports C<rawdeflate>, C<$RawDeflateError> and all symbolic
1000 constants that can be used by C<IO::Compress::RawDeflate>. Same as doing this
1002 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError :constants) ;
1006 Import all symbolic constants. Same as doing this
1009 use IO::Compress::RawDeflate qw(:flush :level :strategy) ;
1014 These symbolic constants are used by the C<flush> method.
1025 These symbolic constants are used by the C<Level> option in the constructor.
1030 Z_DEFAULT_COMPRESSION
1035 These symbolic constants are used by the C<Strategy> option in the constructor.
1061 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>
1063 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1065 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1066 L<Archive::Tar|Archive::Tar>,
1067 L<IO::Zlib|IO::Zlib>
1070 For RFC 1950, 1951 and 1952 see
1071 F<http://www.faqs.org/rfcs/rfc1950.html>,
1072 F<http://www.faqs.org/rfcs/rfc1951.html> and
1073 F<http://www.faqs.org/rfcs/rfc1952.html>
1075 The I<zlib> compression library was written by Jean-loup Gailly
1076 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1078 The primary site for the I<zlib> compression library is
1079 F<http://www.zlib.org>.
1081 The primary site for gzip is F<http://www.gzip.org>.
1088 This module was written by Paul Marquess, F<pmqs@cpan.org>.
1092 =head1 MODIFICATION HISTORY
1094 See the Changes file.
1096 =head1 COPYRIGHT AND LICENSE
1098 Copyright (c) 2005-2006 Paul Marquess. All rights reserved.
1100 This program is free software; you can redistribute it and/or
1101 modify it under the same terms as Perl itself.