2 package Compress::Raw::Zlib;
9 #use Parse::Parameters;
14 our ($VERSION, $XS_VERSION, @ISA, @EXPORT, $AUTOLOAD);
17 $XS_VERSION = $VERSION;
18 $VERSION = eval $VERSION;
21 # Items to export into callers namespace by default. Note: do not export
22 # names by default without a very good reason. Use EXPORT_OK instead.
23 # Do not simply export all your public functions/methods/constants.
70 ($constname = $AUTOLOAD) =~ s/.*:://;
71 my ($error, $val) = constant($constname);
72 Carp::croak $error if $error;
74 *{$AUTOLOAD} = sub { $val };
78 use constant FLAG_APPEND => 1 ;
79 use constant FLAG_CRC => 2 ;
80 use constant FLAG_ADLER => 4 ;
81 use constant FLAG_CONSUME_INPUT => 8 ;
85 XSLoader::load('Compress::Raw::Zlib', $XS_VERSION);
90 local @ISA = qw(DynaLoader);
91 bootstrap Compress::Raw::Zlib $XS_VERSION ;
95 use constant Parse_any => 0x01;
96 use constant Parse_unsigned => 0x02;
97 use constant Parse_signed => 0x04;
98 use constant Parse_boolean => 0x08;
99 use constant Parse_string => 0x10;
100 use constant Parse_custom => 0x12;
102 use constant Parse_store_ref => 0x100 ;
104 use constant OFF_PARSED => 0 ;
105 use constant OFF_TYPE => 1 ;
106 use constant OFF_DEFAULT => 2 ;
107 use constant OFF_FIXED => 3 ;
108 use constant OFF_FIRST_ONLY => 4 ;
109 use constant OFF_STICKY => 5 ;
115 my $level = shift || 0 ;
117 my $sub = (caller($level + 1))[3] ;
118 #local $Carp::CarpLevel = 1 ;
119 my $p = new Compress::Raw::Zlib::Parameters() ;
121 or croak "$sub: $p->{Error}" ;
127 sub Compress::Raw::Zlib::Parameters::new
131 my $obj = { Error => '',
135 #return bless $obj, ref($class) || $class || __PACKAGE__ ;
136 return bless $obj, 'Compress::Raw::Zlib::Parameters' ;
139 sub Compress::Raw::Zlib::Parameters::setError
143 my $retval = @_ ? shift : undef ;
145 $self->{Error} = $error ;
152 # return $self->{Error} ;
155 sub Compress::Raw::Zlib::Parameters::parse
159 my $default = shift ;
161 my $got = $self->{Got} ;
162 my $firstTime = keys %{ $got } == 0 ;
167 # Allow the options to be passed as a hash reference or
168 # as the complete hash.
174 return $self->setError("Expected even number of parameters, got 1")
175 if ! defined $href or ! ref $href or ref $href ne "HASH" ;
177 foreach my $key (keys %$href) {
178 push @entered, $key ;
179 push @entered, \$href->{$key} ;
184 return $self->setError("Expected even number of parameters, got $count")
187 for my $i (0.. $count / 2 - 1) {
188 push @entered, $_[2* $i] ;
189 push @entered, \$_[2* $i+1] ;
194 while (my ($key, $v) = each %$default)
196 croak "need 4 params [@$v]"
199 my ($first_only, $sticky, $type, $value) = @$v ;
201 $self->_checkType($key, \$value, $type, 0, \$x)
206 if ($firstTime || ! $sticky) {
207 $got->{$key} = [0, $type, $value, $x, $first_only, $sticky] ;
210 $got->{$key}[OFF_PARSED] = 0 ;
213 for my $i (0.. @entered / 2 - 1) {
214 my $key = $entered[2* $i] ;
215 my $value = $entered[2* $i+1] ;
217 #print "Key [$key] Value [$value]" ;
218 #print defined $$value ? "[$$value]\n" : "[undef]\n";
221 my $canonkey = lc $key;
223 if ($got->{$canonkey} && ($firstTime ||
224 ! $got->{$canonkey}[OFF_FIRST_ONLY] ))
226 my $type = $got->{$canonkey}[OFF_TYPE] ;
228 $self->_checkType($key, $value, $type, 1, \$s)
230 #$value = $$value unless $type & Parse_store_ref ;
232 $got->{$canonkey} = [1, $type, $value, $s] ;
235 { push (@Bad, $key) }
239 my ($bad) = join(", ", @Bad) ;
240 return $self->setError("unknown key value(s) @Bad") ;
246 sub Compress::Raw::Zlib::Parameters::_checkType
253 my $validate = shift ;
256 #local $Carp::CarpLevel = $level ;
257 #print "PARSE $type $key $value $validate $sub\n" ;
258 if ( $type & Parse_store_ref)
261 # if ref ${ $value } ;
269 if ($type & Parse_any)
274 elsif ($type & Parse_unsigned)
276 return $self->setError("Parameter '$key' must be an unsigned int, got 'undef'")
277 if $validate && ! defined $value ;
278 return $self->setError("Parameter '$key' must be an unsigned int, got '$value'")
279 if $validate && $value !~ /^\d+$/;
281 $$output = defined $value ? $value : 0 ;
284 elsif ($type & Parse_signed)
286 return $self->setError("Parameter '$key' must be a signed int, got 'undef'")
287 if $validate && ! defined $value ;
288 return $self->setError("Parameter '$key' must be a signed int, got '$value'")
289 if $validate && $value !~ /^-?\d+$/;
291 $$output = defined $value ? $value : 0 ;
294 elsif ($type & Parse_boolean)
296 return $self->setError("Parameter '$key' must be an int, got '$value'")
297 if $validate && defined $value && $value !~ /^\d*$/;
298 $$output = defined $value ? $value != 0 : 0 ;
301 elsif ($type & Parse_string)
303 $$output = defined $value ? $value : "" ;
313 sub Compress::Raw::Zlib::Parameters::parsed
318 return $self->{Got}{lc $name}[OFF_PARSED] ;
321 sub Compress::Raw::Zlib::Parameters::value
328 $self->{Got}{lc $name}[OFF_PARSED] = 1;
329 $self->{Got}{lc $name}[OFF_DEFAULT] = $_[0] ;
330 $self->{Got}{lc $name}[OFF_FIXED] = $_[0] ;
333 return $self->{Got}{lc $name}[OFF_FIXED] ;
336 sub Compress::Raw::Zlib::Deflate::new
339 my ($got) = ParseParameters(0,
341 'AppendOutput' => [1, 1, Parse_boolean, 0],
342 'CRC32' => [1, 1, Parse_boolean, 0],
343 'ADLER32' => [1, 1, Parse_boolean, 0],
344 'Bufsize' => [1, 1, Parse_unsigned, 4096],
346 'Level' => [1, 1, Parse_signed, Z_DEFAULT_COMPRESSION()],
347 'Method' => [1, 1, Parse_unsigned, Z_DEFLATED()],
348 'WindowBits' => [1, 1, Parse_signed, MAX_WBITS()],
349 'MemLevel' => [1, 1, Parse_unsigned, MAX_MEM_LEVEL()],
350 'Strategy' => [1, 1, Parse_unsigned, Z_DEFAULT_STRATEGY()],
351 'Dictionary' => [1, 1, Parse_any, ""],
355 croak "Compress::Raw::Zlib::Deflate::new: Bufsize must be >= 1, you specified " .
356 $got->value('Bufsize')
357 unless $got->value('Bufsize') >= 1;
360 $flags |= FLAG_APPEND if $got->value('AppendOutput') ;
361 $flags |= FLAG_CRC if $got->value('CRC32') ;
362 $flags |= FLAG_ADLER if $got->value('ADLER32') ;
365 $got->value('Level'),
366 $got->value('Method'),
367 $got->value('WindowBits'),
368 $got->value('MemLevel'),
369 $got->value('Strategy'),
370 $got->value('Bufsize'),
371 $got->value('Dictionary')) ;
375 sub Compress::Raw::Zlib::Inflate::new
378 my ($got) = ParseParameters(0,
380 'AppendOutput' => [1, 1, Parse_boolean, 0],
381 'CRC32' => [1, 1, Parse_boolean, 0],
382 'ADLER32' => [1, 1, Parse_boolean, 0],
383 'ConsumeInput' => [1, 1, Parse_boolean, 1],
384 'Bufsize' => [1, 1, Parse_unsigned, 4096],
386 'WindowBits' => [1, 1, Parse_signed, MAX_WBITS()],
387 'Dictionary' => [1, 1, Parse_any, ""],
391 croak "Compress::Raw::Zlib::Inflate::new: Bufsize must be >= 1, you specified " .
392 $got->value('Bufsize')
393 unless $got->value('Bufsize') >= 1;
396 $flags |= FLAG_APPEND if $got->value('AppendOutput') ;
397 $flags |= FLAG_CRC if $got->value('CRC32') ;
398 $flags |= FLAG_ADLER if $got->value('ADLER32') ;
399 $flags |= FLAG_CONSUME_INPUT if $got->value('ConsumeInput') ;
401 _inflateInit($flags, $got->value('WindowBits'), $got->value('Bufsize'),
402 $got->value('Dictionary')) ;
405 sub Compress::Raw::Zlib::InflateScan::new
408 my ($got) = ParseParameters(0,
410 'CRC32' => [1, 1, Parse_boolean, 0],
411 'ADLER32' => [1, 1, Parse_boolean, 0],
412 'Bufsize' => [1, 1, Parse_unsigned, 4096],
414 'WindowBits' => [1, 1, Parse_signed, -MAX_WBITS()],
415 'Dictionary' => [1, 1, Parse_any, ""],
419 croak "Compress::Raw::Zlib::InflateScan::new: Bufsize must be >= 1, you specified " .
420 $got->value('Bufsize')
421 unless $got->value('Bufsize') >= 1;
424 #$flags |= FLAG_APPEND if $got->value('AppendOutput') ;
425 $flags |= FLAG_CRC if $got->value('CRC32') ;
426 $flags |= FLAG_ADLER if $got->value('ADLER32') ;
427 #$flags |= FLAG_CONSUME_INPUT if $got->value('ConsumeInput') ;
429 _inflateScanInit($flags, $got->value('WindowBits'), $got->value('Bufsize'),
433 sub Compress::Raw::Zlib::inflateScanStream::createDeflateStream
436 my ($got) = ParseParameters(0,
438 'AppendOutput' => [1, 1, Parse_boolean, 0],
439 'CRC32' => [1, 1, Parse_boolean, 0],
440 'ADLER32' => [1, 1, Parse_boolean, 0],
441 'Bufsize' => [1, 1, Parse_unsigned, 4096],
443 'Level' => [1, 1, Parse_signed, Z_DEFAULT_COMPRESSION()],
444 'Method' => [1, 1, Parse_unsigned, Z_DEFLATED()],
445 'WindowBits' => [1, 1, Parse_signed, - MAX_WBITS()],
446 'MemLevel' => [1, 1, Parse_unsigned, MAX_MEM_LEVEL()],
447 'Strategy' => [1, 1, Parse_unsigned, Z_DEFAULT_STRATEGY()],
450 croak "Compress::Raw::Zlib::InflateScan::createDeflateStream: Bufsize must be >= 1, you specified " .
451 $got->value('Bufsize')
452 unless $got->value('Bufsize') >= 1;
455 $flags |= FLAG_APPEND if $got->value('AppendOutput') ;
456 $flags |= FLAG_CRC if $got->value('CRC32') ;
457 $flags |= FLAG_ADLER if $got->value('ADLER32') ;
459 $pkg->_createDeflateStream($flags,
460 $got->value('Level'),
461 $got->value('Method'),
462 $got->value('WindowBits'),
463 $got->value('MemLevel'),
464 $got->value('Strategy'),
465 $got->value('Bufsize'),
470 sub Compress::Raw::Zlib::inflateScanStream::inflate
476 my $status = $self->scan(@_);
478 if ($status == Z_OK() && $_[2]) {
481 $status = $self->scan(\$byte, $_[1]) ;
487 sub Compress::Raw::Zlib::deflateStream::deflateParams
490 my ($got) = ParseParameters(0, {
491 'Level' => [1, 1, Parse_signed, undef],
492 'Strategy' => [1, 1, Parse_unsigned, undef],
493 'Bufsize' => [1, 1, Parse_unsigned, undef],
497 croak "Compress::Raw::Zlib::deflateParams needs Level and/or Strategy"
498 unless $got->parsed('Level') + $got->parsed('Strategy') +
499 $got->parsed('Bufsize');
501 croak "Compress::Raw::Zlib::Inflate::deflateParams: Bufsize must be >= 1, you specified " .
502 $got->value('Bufsize')
503 if $got->parsed('Bufsize') && $got->value('Bufsize') <= 1;
506 $flags |= 1 if $got->parsed('Level') ;
507 $flags |= 2 if $got->parsed('Strategy') ;
508 $flags |= 4 if $got->parsed('Bufsize') ;
510 $self->_deflateParams($flags, $got->value('Level'),
511 $got->value('Strategy'), $got->value('Bufsize'));
516 # Autoload methods go after __END__, and are processed by the autosplit program.
524 Compress::Raw::Zlib - Low-Level Interface to zlib compression library
528 use Compress::Raw::Zlib ;
530 ($d, $status) = new Compress::Raw::Zlib::Deflate( [OPT] ) ;
531 $status = $d->deflate($input, $output) ;
532 $status = $d->flush($output [, $flush_type]) ;
533 $d->deflateParams(OPTS) ;
534 $d->deflateTune(OPTS) ;
545 ($i, $status) = new Compress::Raw::Zlib::Inflate( [OPT] ) ;
546 $status = $i->inflate($input, $output [, $eof]) ;
547 $status = $i->inflateSync($input) ;
556 $crc = adler32($buffer [,$crc]) ;
557 $crc = crc32($buffer [,$crc]) ;
559 $crc = adler32_combine($crc1, $crc2, $len2)l
560 $crc = crc32_combine($adler1, $adler2, $len2)
567 The I<Compress::Raw::Zlib> module provides a Perl interface to the I<zlib>
568 compression library (see L</AUTHOR> for details about where to get
573 =head1 Compress::Raw::Zlib::Deflate
575 This section defines an interface that allows in-memory compression using
576 the I<deflate> interface provided by zlib.
578 Here is a definition of the interface available:
581 =head2 B<($d, $status) = new Compress::Raw::Zlib::Deflate( [OPT] ) >
583 Initialises a deflation object.
585 If you are familiar with the I<zlib> library, it combines the
586 features of the I<zlib> functions C<deflateInit>, C<deflateInit2>
587 and C<deflateSetDictionary>.
589 If successful, it will return the initialised deflation object, C<$d>
590 and a C<$status> of C<Z_OK> in a list context. In scalar context it
591 returns the deflation object, C<$d>, only.
593 If not successful, the returned deflation object, C<$d>, will be
594 I<undef> and C<$status> will hold the a I<zlib> error code.
596 The function optionally takes a number of named options specified as
597 C<< Name => value >> pairs. This allows individual options to be
598 tailored without having to specify them all in the parameter list.
600 For backward compatibility, it is also possible to pass the parameters
601 as a reference to a hash containing the name=>value pairs.
603 Below is a list of the valid options:
609 Defines the compression level. Valid values are 0 through 9,
610 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
611 C<Z_DEFAULT_COMPRESSION>.
613 The default is Z_DEFAULT_COMPRESSION.
617 Defines the compression method. The only valid value at present (and
618 the default) is Z_DEFLATED.
622 For a definition of the meaning and valid values for C<WindowBits>
623 refer to the I<zlib> documentation for I<deflateInit2>.
625 Defaults to MAX_WBITS.
629 For a definition of the meaning and valid values for C<MemLevel>
630 refer to the I<zlib> documentation for I<deflateInit2>.
632 Defaults to MAX_MEM_LEVEL.
636 Defines the strategy used to tune the compression. The valid values are
637 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED>, C<Z_RLE>, C<Z_FIXED> and
640 The default is Z_DEFAULT_STRATEGY.
644 When a dictionary is specified I<Compress::Raw::Zlib> will automatically
645 call C<deflateSetDictionary> directly after calling C<deflateInit>. The
646 Adler32 value for the dictionary can be obtained by calling the method
647 C<$d-E<gt>dict_adler()>.
649 The default is no dictionary.
653 Sets the initial size for the output buffer used by the C<$d-E<gt>deflate>
654 and C<$d-E<gt>flush> methods. If the buffer has to be
655 reallocated to increase the size, it will grow in increments of
658 The default buffer size is 4096.
660 =item B<-AppendOutput>
662 This option controls how data is written to the output buffer by the
663 C<$d-E<gt>deflate> and C<$d-E<gt>flush> methods.
665 If the C<AppendOutput> option is set to false, the output buffers in the
666 C<$d-E<gt>deflate> and C<$d-E<gt>flush> methods will be truncated before
667 uncompressed data is written to them.
669 If the option is set to true, uncompressed data will be appended to the
670 output buffer in the C<$d-E<gt>deflate> and C<$d-E<gt>flush> methods.
672 This option defaults to false.
676 If set to true, a crc32 checksum of the uncompressed data will be
677 calculated. Use the C<$d-E<gt>crc32> method to retrieve this value.
679 This option defaults to false.
684 If set to true, an adler32 checksum of the uncompressed data will be
685 calculated. Use the C<$d-E<gt>adler32> method to retrieve this value.
687 This option defaults to false.
692 Here is an example of using the C<Compress::Raw::Zlib::Deflate> optional
693 parameter list to override the default buffer size and compression
694 level. All other options will take their default values.
696 my $d = new Compress::Raw::Zlib::Deflate ( -Bufsize => 300,
697 -Level => Z_BEST_SPEED ) ;
700 =head2 B<$status = $d-E<gt>deflate($input, $output)>
702 Deflates the contents of C<$input> and writes the compressed data to
705 The C<$input> and C<$output> parameters can be either scalars or scalar
708 When finished, C<$input> will be completely processed (assuming there
709 were no errors). If the deflation was successful it writes the deflated
710 data to C<$output> and returns a status value of C<Z_OK>.
712 On error, it returns a I<zlib> error code.
714 If the C<AppendOutput> option is set to true in the constructor for
715 the C<$d> object, the compressed data will be appended to C<$output>. If
716 it is false, C<$output> will be truncated before any compressed data is
719 B<Note>: This method will not necessarily write compressed data to
720 C<$output> every time it is called. So do not assume that there has been
721 an error if the contents of C<$output> is empty on returning from
722 this method. As long as the return code from the method is C<Z_OK>,
723 the deflate has succeeded.
725 =head2 B<$status = $d-E<gt>flush($output [, $flush_type]) >
727 Typically used to finish the deflation. Any pending output will be
728 written to C<$output>.
730 Returns C<Z_OK> if successful.
732 Note that flushing can seriously degrade the compression ratio, so it
733 should only be used to terminate a decompression (using C<Z_FINISH>) or
734 when you want to create a I<full flush point> (using C<Z_FULL_FLUSH>).
736 By default the C<flush_type> used is C<Z_FINISH>. Other valid values
737 for C<flush_type> are C<Z_NO_FLUSH>, C<Z_PARTIAL_FLUSH>, C<Z_SYNC_FLUSH>
738 and C<Z_FULL_FLUSH>. It is strongly recommended that you only set the
739 C<flush_type> parameter if you fully understand the implications of
740 what it does. See the C<zlib> documentation for details.
742 If the C<AppendOutput> option is set to true in the constructor for
743 the C<$d> object, the compressed data will be appended to C<$output>. If
744 it is false, C<$output> will be truncated before any compressed data is
747 =head2 B<$status = $d-E<gt>deflateParams([OPT])>
749 Change settings for the deflate object C<$d>.
751 The list of the valid options is shown below. Options not specified
752 will remain unchanged.
759 Defines the compression level. Valid values are 0 through 9,
760 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
761 C<Z_DEFAULT_COMPRESSION>.
765 Defines the strategy used to tune the compression. The valid values are
766 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
770 Sets the initial size for the output buffer used by the C<$d-E<gt>deflate>
771 and C<$d-E<gt>flush> methods. If the buffer has to be
772 reallocated to increase the size, it will grow in increments of
778 =head2 B<$status = $d-E<gt>deflateTune($good_length, $max_lazy, $nice_length, $max_chain)>
780 Tune the internal settings for the deflate object C<$d>. This option is
781 only available if you are running zlib 1.2.2.3 or better.
783 Refer to the documentation in zlib.h for instructions on how to fly
786 =head2 B<$d-E<gt>dict_adler()>
788 Returns the adler32 value for the dictionary.
790 =head2 B<$d-E<gt>crc32()>
792 Returns the crc32 value for the uncompressed data to date.
794 If the C<CRC32> option is not enabled in the constructor for this object,
795 this method will always return 0;
797 =head2 B<$d-E<gt>adler32()>
799 Returns the adler32 value for the uncompressed data to date.
801 =head2 B<$d-E<gt>msg()>
803 Returns the last error message generated by zlib.
805 =head2 B<$d-E<gt>total_in()>
807 Returns the total number of bytes uncompressed bytes input to deflate.
809 =head2 B<$d-E<gt>total_out()>
811 Returns the total number of compressed bytes output from deflate.
813 =head2 B<$d-E<gt>get_Strategy()>
815 Returns the deflation strategy currently used. Valid values are
816 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
819 =head2 B<$d-E<gt>get_Level()>
821 Returns the compression level being used.
823 =head2 B<$d-E<gt>get_BufSize()>
825 Returns the buffer size used to carry out the compression.
830 Here is a trivial example of using C<deflate>. It simply reads standard
831 input, deflates it and writes it to standard output.
836 use Compress::Raw::Zlib ;
840 my $x = new Compress::Raw::Zlib::Deflate
841 or die "Cannot create a deflation stream\n" ;
843 my ($output, $status) ;
846 $status = $x->deflate($_, $output) ;
849 or die "deflation failed\n" ;
854 $status = $x->flush($output) ;
857 or die "deflation failed\n" ;
861 =head1 Compress::Raw::Zlib::Inflate
863 This section defines an interface that allows in-memory uncompression using
864 the I<inflate> interface provided by zlib.
866 Here is a definition of the interface:
869 =head2 B< ($i, $status) = new Compress::Raw::Zlib::Inflate( [OPT] ) >
871 Initialises an inflation object.
873 In a list context it returns the inflation object, C<$i>, and the
874 I<zlib> status code (C<$status>). In a scalar context it returns the
875 inflation object only.
877 If successful, C<$i> will hold the inflation object and C<$status> will
880 If not successful, C<$i> will be I<undef> and C<$status> will hold the
883 The function optionally takes a number of named options specified as
884 C<< -Name => value >> pairs. This allows individual options to be
885 tailored without having to specify them all in the parameter list.
887 For backward compatibility, it is also possible to pass the parameters
888 as a reference to a hash containing the C<< name=>value >> pairs.
890 Here is a list of the valid options:
896 To uncompress an RFC 1950 data stream, set C<WindowBits> to a positive
899 To uncompress an RFC 1951 data stream, set C<WindowBits> to C<-MAX_WBITS>.
901 For a full definition of the meaning and valid values for C<WindowBits>
902 refer to the I<zlib> documentation for I<inflateInit2>.
904 Defaults to MAX_WBITS.
908 Sets the initial size for the output buffer used by the C<$i-E<gt>inflate>
909 method. If the output buffer in this method has to be reallocated to
910 increase the size, it will grow in increments of C<Bufsize>.
916 The default is no dictionary.
918 =item B<-AppendOutput>
920 This option controls how data is written to the output buffer by the
921 C<$i-E<gt>inflate> method.
923 If the option is set to false, the output buffer in the C<$i-E<gt>inflate>
924 method will be truncated before uncompressed data is written to it.
926 If the option is set to true, uncompressed data will be appended to the
927 output buffer by the C<$i-E<gt>inflate> method.
929 This option defaults to false.
934 If set to true, a crc32 checksum of the uncompressed data will be
935 calculated. Use the C<$i-E<gt>crc32> method to retrieve this value.
937 This option defaults to false.
941 If set to true, an adler32 checksum of the uncompressed data will be
942 calculated. Use the C<$i-E<gt>adler32> method to retrieve this value.
944 This option defaults to false.
946 =item B<-ConsumeInput>
948 If set to true, this option will remove compressed data from the input
949 buffer of the the C< $i-E<gt>inflate > method as the inflate progresses.
951 This option can be useful when you are processing compressed data that is
952 embedded in another file/buffer. In this case the data that immediately
953 follows the compressed stream will be left in the input buffer.
955 This option defaults to true.
959 Here is an example of using an optional parameter to override the default
962 my ($i, $status) = new Compress::Raw::Zlib::Inflate( -Bufsize => 300 ) ;
964 =head2 B< $status = $i-E<gt>inflate($input, $output [,$eof]) >
966 Inflates the complete contents of C<$input> and writes the uncompressed
967 data to C<$output>. The C<$input> and C<$output> parameters can either be
968 scalars or scalar references.
970 Returns C<Z_OK> if successful and C<Z_STREAM_END> if the end of the
971 compressed data has been successfully reached.
973 If not successful C<$status> will hold the I<zlib> error code.
975 If the C<ConsumeInput> option has been set to true when the
976 C<Compress::Raw::Zlib::Inflate> object is created, the C<$input> parameter
977 is modified by C<inflate>. On completion it will contain what remains
978 of the input buffer after inflation. In practice, this means that when
979 the return status is C<Z_OK> the C<$input> parameter will contain an
980 empty string, and when the return status is C<Z_STREAM_END> the C<$input>
981 parameter will contains what (if anything) was stored in the input buffer
982 after the deflated data stream.
984 This feature is useful when processing a file format that encapsulates
985 a compressed data stream (e.g. gzip, zip) and there is useful data
986 immediately after the deflation stream.
988 If the C<AppendOutput> option is set to true in the constructor for
989 this object, the uncompressed data will be appended to C<$output>. If
990 it is false, C<$output> will be truncated before any uncompressed data
993 The C<$eof> parameter needs a bit of explanation.
995 Prior to version 1.2.0, zlib assumed that there was at least one trailing
996 byte immediately after the compressed data stream when it was carrying out
997 decompression. This normally isn't a problem because the majority of zlib
998 applications guarantee that there will be data directly after the
999 compressed data stream. For example, both gzip (RFC 1950) and zip both
1000 define trailing data that follows the compressed data stream.
1002 The C<$eof> parameter only needs to be used if B<all> of the following
1009 You are either using a copy of zlib that is older than version 1.2.0 or you
1010 want your application code to be able to run with as many different
1011 versions of zlib as possible.
1015 You have set the C<WindowBits> parameter to C<-MAX_WBITS> in the constructor
1016 for this object, i.e. you are uncompressing a raw deflated data stream
1021 There is no data immediately after the compressed data stream.
1025 If B<all> of these are the case, then you need to set the C<$eof> parameter
1026 to true on the final call (and only the final call) to C<$i-E<gt>inflate>.
1028 If you have built this module with zlib >= 1.2.0, the C<$eof> parameter is
1029 ignored. You can still set it if you want, but it won't be used behind the
1032 =head2 B<$status = $i-E<gt>inflateSync($input)>
1034 This method can be used to attempt to recover good data from a compressed
1035 data stream that is partially corrupt.
1036 It scans C<$input> until it reaches either a I<full flush point> or the
1039 If a I<full flush point> is found, C<Z_OK> is returned and C<$input>
1040 will be have all data up to the flush point removed. This data can then be
1041 passed to the C<$i-E<gt>inflate> method to be uncompressed.
1043 Any other return code means that a flush point was not found. If more
1044 data is available, C<inflateSync> can be called repeatedly with more
1045 compressed data until the flush point is found.
1047 Note I<full flush points> are not present by default in compressed
1048 data streams. They must have been added explicitly when the data stream
1049 was created by calling C<Compress::Deflate::flush> with C<Z_FULL_FLUSH>.
1052 =head2 B<$i-E<gt>dict_adler()>
1054 Returns the adler32 value for the dictionary.
1056 =head2 B<$i-E<gt>crc32()>
1058 Returns the crc32 value for the uncompressed data to date.
1060 If the C<CRC32> option is not enabled in the constructor for this object,
1061 this method will always return 0;
1063 =head2 B<$i-E<gt>adler32()>
1065 Returns the adler32 value for the uncompressed data to date.
1067 If the C<ADLER32> option is not enabled in the constructor for this object,
1068 this method will always return 0;
1070 =head2 B<$i-E<gt>msg()>
1072 Returns the last error message generated by zlib.
1074 =head2 B<$i-E<gt>total_in()>
1076 Returns the total number of bytes compressed bytes input to inflate.
1078 =head2 B<$i-E<gt>total_out()>
1080 Returns the total number of uncompressed bytes output from inflate.
1082 =head2 B<$d-E<gt>get_BufSize()>
1084 Returns the buffer size used to carry out the decompression.
1088 Here is an example of using C<inflate>.
1093 use Compress::Raw::Zlib;
1095 my $x = new Compress::Raw::Zlib::Inflate()
1096 or die "Cannot create a inflation stream\n" ;
1102 my ($output, $status) ;
1103 while (read(STDIN, $input, 4096))
1105 $status = $x->inflate(\$input, $output) ;
1108 if $status == Z_OK or $status == Z_STREAM_END ;
1110 last if $status != Z_OK ;
1113 die "inflation failed\n"
1114 unless $status == Z_STREAM_END ;
1116 =head1 CHECKSUM FUNCTIONS
1118 Two functions are provided by I<zlib> to calculate checksums. For the
1119 Perl interface, the order of the two parameters in both functions has
1120 been reversed. This allows both running checksums and one off
1121 calculations to be done.
1123 $crc = adler32($buffer [,$crc]) ;
1124 $crc = crc32($buffer [,$crc]) ;
1126 The buffer parameters can either be a scalar or a scalar reference.
1128 If the $crc parameters is C<undef>, the crc value will be reset.
1130 If you have built this module with zlib 1.2.3 or better, two more
1131 CRC-related functions are available.
1133 $crc = adler32_combine($crc1, $crc2, $len2)l
1134 $crc = crc32_combine($adler1, $adler2, $len2)
1136 These functions allow checksums to be merged.
1138 =head1 ACCESSING ZIP FILES
1140 Although it is possible (with some effort on your part) to use this
1141 module to access .zip files, there is a module on CPAN that will do all
1142 the hard work for you. Check out the C<Archive::Zip> module on CPAN at
1144 http://www.cpan.org/modules/by-module/Archive/Archive-Zip-*.tar.gz
1149 All the I<zlib> constants are automatically imported when you make use
1150 of I<Compress::Raw::Zlib>.
1155 L<Compress::Zlib>, L<IO::Compress::Gzip>, L<IO::Uncompress::Gunzip>, L<IO::Compress::Deflate>, 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::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
1157 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1159 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1160 L<Archive::Tar|Archive::Tar>,
1161 L<IO::Zlib|IO::Zlib>
1164 For RFC 1950, 1951 and 1952 see
1165 F<http://www.faqs.org/rfcs/rfc1950.html>,
1166 F<http://www.faqs.org/rfcs/rfc1951.html> and
1167 F<http://www.faqs.org/rfcs/rfc1952.html>
1169 The I<zlib> compression library was written by Jean-loup Gailly
1170 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1172 The primary site for the I<zlib> compression library is
1173 F<http://www.zlib.org>.
1175 The primary site for gzip is F<http://www.gzip.org>.
1182 This module was written by Paul Marquess, F<pmqs@cpan.org>.
1186 =head1 MODIFICATION HISTORY
1188 See the Changes file.
1190 =head1 COPYRIGHT AND LICENSE
1192 Copyright (c) 2005-2006 Paul Marquess. All rights reserved.
1194 This program is free software; you can redistribute it and/or
1195 modify it under the same terms as Perl itself.