1 package IO::Compress::RawDeflate ;
10 use IO::Compress::Base 2.003 ;
11 use IO::Compress::Base::Common 2.003 qw(:Status createSelfTiedObject);
12 use IO::Compress::Adapter::Deflate 2.003 ;
17 our ($VERSION, @ISA, @EXPORT_OK, %DEFLATE_CONSTANTS, %EXPORT_TAGS, $RawDeflateError);
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 2.003 qw(:Parse);
145 use Compress::Raw::Zlib 2.003 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} = *$inf->{UnCompSize}->clone();
206 *$self->{CompSize} = *$inf->{CompSize}->clone();
208 #*$self->{CompSize} = new U64(0, *$self->{UnCompSize_32bit});
211 if ( $outType eq 'buffer')
212 { substr( ${ *$self->{Buffer} }, $end_offset) = '' }
213 elsif ($outType eq 'handle' || $outType eq 'filename') {
214 *$self->{FH} = *$inf->{FH} ;
216 *$self->{FH}->flush() ;
217 *$self->{Handle} = 1 if $outType eq 'handle';
219 #seek(*$self->{FH}, $end_offset, SEEK_SET)
220 *$self->{FH}->seek($end_offset, SEEK_SET)
221 or return $self->saveErrorString(undef, $!, $!) ;
227 #### zlib specific methods
234 my $strategy = shift ;
236 my $status = *$self->{Compress}->deflateParams(Level => $level, Strategy => $strategy) ;
237 return $self->saveErrorString(0, *$self->{Compress}{Error}, *$self->{Compress}{ErrorNo})
238 if $status == STATUS_ERROR;
254 IO::Compress::RawDeflate - Write RFC 1951 files/buffers
260 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
263 my $status = rawdeflate $input => $output [,OPTS]
264 or die "rawdeflate failed: $RawDeflateError\n";
266 my $z = new IO::Compress::RawDeflate $output [,OPTS]
267 or die "rawdeflate failed: $RawDeflateError\n";
270 $z->printf($format, $string);
272 $z->syswrite($string [, $length, $offset]);
276 $z->seek($position, $whence);
281 $z->input_line_number();
282 $z->newStream( [OPTS] );
293 printf $z $format, $string;
296 seek $z, $position, $whence
305 This module provides a Perl interface that allows writing compressed
306 data to files or buffer as defined in RFC 1951.
314 Note that RFC 1951 data is not a good choice of compression format
315 to use in isolation, especially if you want to auto-detect it.
321 For reading RFC 1951 files/buffers, see the companion module
322 L<IO::Uncompress::RawInflate|IO::Uncompress::RawInflate>.
325 =head1 Functional Interface
327 A top-level function, C<rawdeflate>, is provided to carry out
328 "one-shot" compression between buffers and/or files. For finer
329 control over the compression process, see the L</"OO Interface">
332 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
334 rawdeflate $input => $output [,OPTS]
335 or die "rawdeflate failed: $RawDeflateError\n";
339 The functional interface needs Perl5.005 or better.
342 =head2 rawdeflate $input => $output [, OPTS]
345 C<rawdeflate> expects at least two parameters, C<$input> and C<$output>.
347 =head3 The C<$input> parameter
349 The parameter, C<$input>, is used to define the source of
350 the uncompressed data.
352 It can take one of the following forms:
358 If the C<$input> parameter is a simple scalar, it is assumed to be a
359 filename. This file will be opened for reading and the input data
360 will be read from it.
364 If the C<$input> parameter is a filehandle, the input data will be
366 The string '-' can be used as an alias for standard input.
368 =item A scalar reference
370 If C<$input> is a scalar reference, the input data will be read
373 =item An array reference
375 If C<$input> is an array reference, each element in the array must be a
378 The input data will be read from each file in turn.
380 The complete array will be walked to ensure that it only
381 contains valid filenames before any data is compressed.
385 =item An Input FileGlob string
387 If C<$input> is a string that is delimited by the characters "<" and ">"
388 C<rawdeflate> will assume that it is an I<input fileglob string>. The
389 input is the list of files that match the fileglob.
391 If the fileglob does not match any files ...
393 See L<File::GlobMapper|File::GlobMapper> for more details.
398 If the C<$input> parameter is any other type, C<undef> will be returned.
402 =head3 The C<$output> parameter
404 The parameter C<$output> is used to control the destination of the
405 compressed data. This parameter can take one of these forms.
411 If the C<$output> parameter is a simple scalar, it is assumed to be a
412 filename. This file will be opened for writing and the compressed
413 data will be written to it.
417 If the C<$output> parameter is a filehandle, the compressed data
418 will be written to it.
419 The string '-' can be used as an alias for standard output.
422 =item A scalar reference
424 If C<$output> is a scalar reference, the compressed data will be
425 stored in C<$$output>.
429 =item An Array Reference
431 If C<$output> is an array reference, the compressed data will be
432 pushed onto the array.
434 =item An Output FileGlob
436 If C<$output> is a string that is delimited by the characters "<" and ">"
437 C<rawdeflate> will assume that it is an I<output fileglob string>. The
438 output is the list of files that match the fileglob.
440 When C<$output> is an fileglob string, C<$input> must also be a fileglob
441 string. Anything else is an error.
445 If the C<$output> parameter is any other type, C<undef> will be returned.
453 When C<$input> maps to multiple files/buffers and C<$output> is a single
454 file/buffer the input files/buffers will be stored
455 in C<$output> as a concatenated series of compressed data streams.
462 =head2 Optional Parameters
464 Unless specified below, the optional parameters for C<rawdeflate>,
465 C<OPTS>, are the same as those used with the OO interface defined in the
466 L</"Constructor Options"> section below.
470 =item C<< AutoClose => 0|1 >>
472 This option applies to any input or output data streams to
473 C<rawdeflate> that are filehandles.
475 If C<AutoClose> is specified, and the value is true, it will result in all
476 input and/or output filehandles being closed once C<rawdeflate> has
479 This parameter defaults to 0.
482 =item C<< BinModeIn => 0|1 >>
484 When reading from a file or filehandle, set C<binmode> before reading.
492 =item C<< Append => 0|1 >>
504 To read the contents of the file C<file1.txt> and write the compressed
505 data to the file C<file1.txt.1951>.
509 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
511 my $input = "file1.txt";
512 rawdeflate $input => "$input.1951"
513 or die "rawdeflate failed: $RawDeflateError\n";
516 To read from an existing Perl filehandle, C<$input>, and write the
517 compressed data to a buffer, C<$buffer>.
521 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
524 my $input = new IO::File "<file1.txt"
525 or die "Cannot open 'file1.txt': $!\n" ;
527 rawdeflate $input => \$buffer
528 or die "rawdeflate failed: $RawDeflateError\n";
530 To compress all files in the directory "/my/home" that match "*.txt"
531 and store the compressed data in the same directory
535 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
537 rawdeflate '</my/home/*.txt>' => '<*.1951>'
538 or die "rawdeflate failed: $RawDeflateError\n";
540 and if you want to compress each file one at a time, this will do the trick
544 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
546 for my $input ( glob "/my/home/*.txt" )
548 my $output = "$input.1951" ;
549 rawdeflate $input => $output
550 or die "Error compressing '$input': $RawDeflateError\n";
558 The format of the constructor for C<IO::Compress::RawDeflate> is shown below
560 my $z = new IO::Compress::RawDeflate $output [,OPTS]
561 or die "IO::Compress::RawDeflate failed: $RawDeflateError\n";
563 It returns an C<IO::Compress::RawDeflate> object on success and undef on failure.
564 The variable C<$RawDeflateError> will contain an error message on failure.
566 If you are running Perl 5.005 or better the object, C<$z>, returned from
567 IO::Compress::RawDeflate can be used exactly like an L<IO::File|IO::File> filehandle.
568 This means that all normal output file operations can be carried out
570 For example, to write to a compressed file/buffer you can use either of
573 $z->print("hello world\n");
574 print $z "hello world\n";
576 The mandatory parameter C<$output> is used to control the destination
577 of the compressed data. This parameter can take one of these forms.
583 If the C<$output> parameter is a simple scalar, it is assumed to be a
584 filename. This file will be opened for writing and the compressed data
585 will be written to it.
589 If the C<$output> parameter is a filehandle, the compressed data will be
591 The string '-' can be used as an alias for standard output.
594 =item A scalar reference
596 If C<$output> is a scalar reference, the compressed data will be stored
601 If the C<$output> parameter is any other type, C<IO::Compress::RawDeflate>::new will
604 =head2 Constructor Options
606 C<OPTS> is any combination of the following options:
610 =item C<< AutoClose => 0|1 >>
612 This option is only valid when the C<$output> parameter is a filehandle. If
613 specified, and the value is true, it will result in the C<$output> being
614 closed once either the C<close> method is called or the C<IO::Compress::RawDeflate>
617 This parameter defaults to 0.
619 =item C<< Append => 0|1 >>
621 Opens C<$output> in append mode.
623 The behaviour of this option is dependent on the type of C<$output>.
629 If C<$output> is a buffer and C<Append> is enabled, all compressed data
630 will be append to the end if C<$output>. Otherwise C<$output> will be
631 cleared before any data is written to it.
635 If C<$output> is a filename and C<Append> is enabled, the file will be
636 opened in append mode. Otherwise the contents of the file, if any, will be
637 truncated before any compressed data is written to it.
641 If C<$output> is a filehandle, the file pointer will be positioned to the
642 end of the file via a call to C<seek> before any compressed data is written
643 to it. Otherwise the file pointer will not be moved.
647 This parameter defaults to 0.
653 =item C<< Merge => 0|1 >>
655 This option is used to compress input data and append it to an existing
656 compressed data stream in C<$output>. The end result is a single compressed
657 data stream stored in C<$output>.
661 It is a fatal error to attempt to use this option when C<$output> is not an
662 RFC 1951 data stream.
666 There are a number of other limitations with the C<Merge> option:
672 This module needs to have been built with zlib 1.2.1 or better to work. A
673 fatal error will be thrown if C<Merge> is used with an older version of
678 If C<$output> is a file or a filehandle, it must be seekable.
683 This parameter defaults to 0.
689 Defines the compression level used by zlib. The value should either be
690 a number between 0 and 9 (0 means no compression and 9 is maximum
691 compression), or one of the symbolic constants defined below.
696 Z_DEFAULT_COMPRESSION
698 The default is Z_DEFAULT_COMPRESSION.
700 Note, these constants are not imported by C<IO::Compress::RawDeflate> by default.
702 use IO::Compress::RawDeflate qw(:strategy);
703 use IO::Compress::RawDeflate qw(:constants);
704 use IO::Compress::RawDeflate qw(:all);
708 Defines the strategy used to tune the compression. Use one of the symbolic
709 constants defined below.
717 The default is Z_DEFAULT_STRATEGY.
724 =item C<< Strict => 0|1 >>
728 This is a placeholder option.
747 Compresses and outputs the contents of the C<$data> parameter. This
748 has the same behaviour as the C<print> built-in.
750 Returns true if successful.
756 $z->printf($format, $data)
757 printf $z $format, $data
759 Compresses and outputs the contents of the C<$data> parameter.
761 Returns true if successful.
768 $z->syswrite $data, $length
769 $z->syswrite $data, $length, $offset
771 Compresses and outputs the contents of the C<$data> parameter.
773 Returns the number of uncompressed bytes written, or C<undef> if
781 $z->write $data, $length
782 $z->write $data, $length, $offset
784 Compresses and outputs the contents of the C<$data> parameter.
786 Returns the number of uncompressed bytes written, or C<undef> if
795 $z->flush($flush_type);
798 Flushes any pending compressed data to the output file/buffer.
801 This method takes an optional parameter, C<$flush_type>, that controls
802 how the flushing will be carried out. By default the C<$flush_type>
803 used is C<Z_FINISH>. Other valid values for C<$flush_type> are
804 C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
805 strongly recommended that you only set the C<flush_type> parameter if
806 you fully understand the implications of what it does - overuse of C<flush>
807 can seriously degrade the level of compression achieved. See the C<zlib>
808 documentation for details.
811 Returns true on success.
821 Returns the uncompressed file offset.
832 Returns true if the C<close> method has been called.
838 $z->seek($position, $whence);
839 seek($z, $position, $whence);
844 Provides a sub-set of the C<seek> functionality, with the restriction
845 that it is only legal to seek forward in the output file/buffer.
846 It is a fatal error to attempt to seek backward.
848 Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
852 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
853 SEEK_CUR or SEEK_END.
855 Returns 1 on success, 0 on failure.
864 This is a noop provided for completeness.
870 Returns true if the object currently refers to a opened file/buffer.
874 my $prev = $z->autoflush()
875 my $prev = $z->autoflush(EXPR)
877 If the C<$z> object is associated with a file or a filehandle, this method
878 returns the current autoflush setting for the underlying filehandle. If
879 C<EXPR> is present, and is non-zero, it will enable flushing after every
880 write/print operation.
882 If C<$z> is associated with a buffer, this method has no effect and always
885 B<Note> that the special variable C<$|> B<cannot> be used to set or
886 retrieve the autoflush setting.
888 =head2 input_line_number
890 $z->input_line_number()
891 $z->input_line_number(EXPR)
894 This method always returns C<undef> when compressing.
903 If the C<$z> object is associated with a file or a filehandle, this method
904 will return the underlying file descriptor.
906 If the C<$z> object is is associated with a buffer, this method will
916 Flushes any pending compressed data and then closes the output file/buffer.
920 For most versions of Perl this method will be automatically invoked if
921 the IO::Compress::RawDeflate object is destroyed (either explicitly or by the
922 variable with the reference to the object going out of scope). The
923 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
924 these cases, the C<close> method will be called automatically, but
925 not until global destruction of all live objects when the program is
928 Therefore, if you want your scripts to be able to run on all versions
929 of Perl, you should call C<close> explicitly and not rely on automatic
932 Returns true on success, otherwise 0.
934 If the C<AutoClose> option has been enabled when the IO::Compress::RawDeflate
935 object was created, and the object is associated with a file, the
936 underlying file will also be closed.
941 =head2 newStream([OPTS])
945 $z->newStream( [OPTS] )
947 Closes the current compressed data stream and starts a new one.
949 OPTS consists of any of the the options that are available when creating
952 See the L</"Constructor Options"> section for more details.
967 A number of symbolic constants are required by some methods in
968 C<IO::Compress::RawDeflate>. None are imported by default.
977 Imports C<rawdeflate>, C<$RawDeflateError> and all symbolic
978 constants that can be used by C<IO::Compress::RawDeflate>. Same as doing this
980 use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError :constants) ;
984 Import all symbolic constants. Same as doing this
987 use IO::Compress::RawDeflate qw(:flush :level :strategy) ;
992 These symbolic constants are used by the C<flush> method.
1003 These symbolic constants are used by the C<Level> option in the constructor.
1008 Z_DEFAULT_COMPRESSION
1013 These symbolic constants are used by the C<Strategy> option in the constructor.
1044 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::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
1046 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1048 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1049 L<Archive::Tar|Archive::Tar>,
1050 L<IO::Zlib|IO::Zlib>
1053 For RFC 1950, 1951 and 1952 see
1054 F<http://www.faqs.org/rfcs/rfc1950.html>,
1055 F<http://www.faqs.org/rfcs/rfc1951.html> and
1056 F<http://www.faqs.org/rfcs/rfc1952.html>
1058 The I<zlib> compression library was written by Jean-loup Gailly
1059 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1061 The primary site for the I<zlib> compression library is
1062 F<http://www.zlib.org>.
1064 The primary site for gzip is F<http://www.gzip.org>.
1071 This module was written by Paul Marquess, F<pmqs@cpan.org>.
1075 =head1 MODIFICATION HISTORY
1077 See the Changes file.
1079 =head1 COPYRIGHT AND LICENSE
1081 Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
1083 This program is free software; you can redistribute it and/or
1084 modify it under the same terms as Perl itself.