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 use constant WANT_GZIP => 16;
71 use constant WANT_GZIP_OR_ZLIB => 32;
75 ($constname = $AUTOLOAD) =~ s/.*:://;
76 my ($error, $val) = constant($constname);
77 Carp::croak $error if $error;
79 *{$AUTOLOAD} = sub { $val };
83 use constant FLAG_APPEND => 1 ;
84 use constant FLAG_CRC => 2 ;
85 use constant FLAG_ADLER => 4 ;
86 use constant FLAG_CONSUME_INPUT => 8 ;
90 XSLoader::load('Compress::Raw::Zlib', $XS_VERSION);
95 local @ISA = qw(DynaLoader);
96 bootstrap Compress::Raw::Zlib $XS_VERSION ;
100 use constant Parse_any => 0x01;
101 use constant Parse_unsigned => 0x02;
102 use constant Parse_signed => 0x04;
103 use constant Parse_boolean => 0x08;
104 use constant Parse_string => 0x10;
105 use constant Parse_custom => 0x12;
107 use constant Parse_store_ref => 0x100 ;
109 use constant OFF_PARSED => 0 ;
110 use constant OFF_TYPE => 1 ;
111 use constant OFF_DEFAULT => 2 ;
112 use constant OFF_FIXED => 3 ;
113 use constant OFF_FIRST_ONLY => 4 ;
114 use constant OFF_STICKY => 5 ;
120 my $level = shift || 0 ;
122 my $sub = (caller($level + 1))[3] ;
123 #local $Carp::CarpLevel = 1 ;
124 my $p = new Compress::Raw::Zlib::Parameters() ;
126 or croak "$sub: $p->{Error}" ;
132 sub Compress::Raw::Zlib::Parameters::new
136 my $obj = { Error => '',
140 #return bless $obj, ref($class) || $class || __PACKAGE__ ;
141 return bless $obj, 'Compress::Raw::Zlib::Parameters' ;
144 sub Compress::Raw::Zlib::Parameters::setError
148 my $retval = @_ ? shift : undef ;
150 $self->{Error} = $error ;
157 # return $self->{Error} ;
160 sub Compress::Raw::Zlib::Parameters::parse
164 my $default = shift ;
166 my $got = $self->{Got} ;
167 my $firstTime = keys %{ $got } == 0 ;
172 # Allow the options to be passed as a hash reference or
173 # as the complete hash.
179 return $self->setError("Expected even number of parameters, got 1")
180 if ! defined $href or ! ref $href or ref $href ne "HASH" ;
182 foreach my $key (keys %$href) {
183 push @entered, $key ;
184 push @entered, \$href->{$key} ;
189 return $self->setError("Expected even number of parameters, got $count")
192 for my $i (0.. $count / 2 - 1) {
193 push @entered, $_[2* $i] ;
194 push @entered, \$_[2* $i+1] ;
199 while (my ($key, $v) = each %$default)
201 croak "need 4 params [@$v]"
204 my ($first_only, $sticky, $type, $value) = @$v ;
206 $self->_checkType($key, \$value, $type, 0, \$x)
211 if ($firstTime || ! $sticky) {
212 $got->{$key} = [0, $type, $value, $x, $first_only, $sticky] ;
215 $got->{$key}[OFF_PARSED] = 0 ;
218 for my $i (0.. @entered / 2 - 1) {
219 my $key = $entered[2* $i] ;
220 my $value = $entered[2* $i+1] ;
222 #print "Key [$key] Value [$value]" ;
223 #print defined $$value ? "[$$value]\n" : "[undef]\n";
226 my $canonkey = lc $key;
228 if ($got->{$canonkey} && ($firstTime ||
229 ! $got->{$canonkey}[OFF_FIRST_ONLY] ))
231 my $type = $got->{$canonkey}[OFF_TYPE] ;
233 $self->_checkType($key, $value, $type, 1, \$s)
235 #$value = $$value unless $type & Parse_store_ref ;
237 $got->{$canonkey} = [1, $type, $value, $s] ;
240 { push (@Bad, $key) }
244 my ($bad) = join(", ", @Bad) ;
245 return $self->setError("unknown key value(s) @Bad") ;
251 sub Compress::Raw::Zlib::Parameters::_checkType
258 my $validate = shift ;
261 #local $Carp::CarpLevel = $level ;
262 #print "PARSE $type $key $value $validate $sub\n" ;
263 if ( $type & Parse_store_ref)
266 # if ref ${ $value } ;
274 if ($type & Parse_any)
279 elsif ($type & Parse_unsigned)
281 return $self->setError("Parameter '$key' must be an unsigned int, got 'undef'")
282 if $validate && ! defined $value ;
283 return $self->setError("Parameter '$key' must be an unsigned int, got '$value'")
284 if $validate && $value !~ /^\d+$/;
286 $$output = defined $value ? $value : 0 ;
289 elsif ($type & Parse_signed)
291 return $self->setError("Parameter '$key' must be a signed int, got 'undef'")
292 if $validate && ! defined $value ;
293 return $self->setError("Parameter '$key' must be a signed int, got '$value'")
294 if $validate && $value !~ /^-?\d+$/;
296 $$output = defined $value ? $value : 0 ;
299 elsif ($type & Parse_boolean)
301 return $self->setError("Parameter '$key' must be an int, got '$value'")
302 if $validate && defined $value && $value !~ /^\d*$/;
303 $$output = defined $value ? $value != 0 : 0 ;
306 elsif ($type & Parse_string)
308 $$output = defined $value ? $value : "" ;
318 sub Compress::Raw::Zlib::Parameters::parsed
323 return $self->{Got}{lc $name}[OFF_PARSED] ;
326 sub Compress::Raw::Zlib::Parameters::value
333 $self->{Got}{lc $name}[OFF_PARSED] = 1;
334 $self->{Got}{lc $name}[OFF_DEFAULT] = $_[0] ;
335 $self->{Got}{lc $name}[OFF_FIXED] = $_[0] ;
338 return $self->{Got}{lc $name}[OFF_FIXED] ;
341 sub Compress::Raw::Zlib::Deflate::new
344 my ($got) = ParseParameters(0,
346 'AppendOutput' => [1, 1, Parse_boolean, 0],
347 'CRC32' => [1, 1, Parse_boolean, 0],
348 'ADLER32' => [1, 1, Parse_boolean, 0],
349 'Bufsize' => [1, 1, Parse_unsigned, 4096],
351 'Level' => [1, 1, Parse_signed, Z_DEFAULT_COMPRESSION()],
352 'Method' => [1, 1, Parse_unsigned, Z_DEFLATED()],
353 'WindowBits' => [1, 1, Parse_signed, MAX_WBITS()],
354 'MemLevel' => [1, 1, Parse_unsigned, MAX_MEM_LEVEL()],
355 'Strategy' => [1, 1, Parse_unsigned, Z_DEFAULT_STRATEGY()],
356 'Dictionary' => [1, 1, Parse_any, ""],
360 croak "Compress::Raw::Zlib::Deflate::new: Bufsize must be >= 1, you specified " .
361 $got->value('Bufsize')
362 unless $got->value('Bufsize') >= 1;
365 $flags |= FLAG_APPEND if $got->value('AppendOutput') ;
366 $flags |= FLAG_CRC if $got->value('CRC32') ;
367 $flags |= FLAG_ADLER if $got->value('ADLER32') ;
369 my $windowBits = $got->value('WindowBits');
370 $windowBits += MAX_WBITS()
371 if ($windowBits & MAX_WBITS()) == 0 ;
374 $got->value('Level'),
375 $got->value('Method'),
377 $got->value('MemLevel'),
378 $got->value('Strategy'),
379 $got->value('Bufsize'),
380 $got->value('Dictionary')) ;
384 sub Compress::Raw::Zlib::Inflate::new
387 my ($got) = ParseParameters(0,
389 'AppendOutput' => [1, 1, Parse_boolean, 0],
390 'CRC32' => [1, 1, Parse_boolean, 0],
391 'ADLER32' => [1, 1, Parse_boolean, 0],
392 'ConsumeInput' => [1, 1, Parse_boolean, 1],
393 'Bufsize' => [1, 1, Parse_unsigned, 4096],
395 'WindowBits' => [1, 1, Parse_signed, MAX_WBITS()],
396 'Dictionary' => [1, 1, Parse_any, ""],
400 croak "Compress::Raw::Zlib::Inflate::new: Bufsize must be >= 1, you specified " .
401 $got->value('Bufsize')
402 unless $got->value('Bufsize') >= 1;
405 $flags |= FLAG_APPEND if $got->value('AppendOutput') ;
406 $flags |= FLAG_CRC if $got->value('CRC32') ;
407 $flags |= FLAG_ADLER if $got->value('ADLER32') ;
408 $flags |= FLAG_CONSUME_INPUT if $got->value('ConsumeInput') ;
410 my $windowBits = $got->value('WindowBits');
411 $windowBits += MAX_WBITS()
412 if ($windowBits & MAX_WBITS()) == 0 ;
414 _inflateInit($flags, $windowBits, $got->value('Bufsize'),
415 $got->value('Dictionary')) ;
418 sub Compress::Raw::Zlib::InflateScan::new
421 my ($got) = ParseParameters(0,
423 'CRC32' => [1, 1, Parse_boolean, 0],
424 'ADLER32' => [1, 1, Parse_boolean, 0],
425 'Bufsize' => [1, 1, Parse_unsigned, 4096],
427 'WindowBits' => [1, 1, Parse_signed, -MAX_WBITS()],
428 'Dictionary' => [1, 1, Parse_any, ""],
432 croak "Compress::Raw::Zlib::InflateScan::new: Bufsize must be >= 1, you specified " .
433 $got->value('Bufsize')
434 unless $got->value('Bufsize') >= 1;
437 #$flags |= FLAG_APPEND if $got->value('AppendOutput') ;
438 $flags |= FLAG_CRC if $got->value('CRC32') ;
439 $flags |= FLAG_ADLER if $got->value('ADLER32') ;
440 #$flags |= FLAG_CONSUME_INPUT if $got->value('ConsumeInput') ;
442 _inflateScanInit($flags, $got->value('WindowBits'), $got->value('Bufsize'),
446 sub Compress::Raw::Zlib::inflateScanStream::createDeflateStream
449 my ($got) = ParseParameters(0,
451 'AppendOutput' => [1, 1, Parse_boolean, 0],
452 'CRC32' => [1, 1, Parse_boolean, 0],
453 'ADLER32' => [1, 1, Parse_boolean, 0],
454 'Bufsize' => [1, 1, Parse_unsigned, 4096],
456 'Level' => [1, 1, Parse_signed, Z_DEFAULT_COMPRESSION()],
457 'Method' => [1, 1, Parse_unsigned, Z_DEFLATED()],
458 'WindowBits' => [1, 1, Parse_signed, - MAX_WBITS()],
459 'MemLevel' => [1, 1, Parse_unsigned, MAX_MEM_LEVEL()],
460 'Strategy' => [1, 1, Parse_unsigned, Z_DEFAULT_STRATEGY()],
463 croak "Compress::Raw::Zlib::InflateScan::createDeflateStream: Bufsize must be >= 1, you specified " .
464 $got->value('Bufsize')
465 unless $got->value('Bufsize') >= 1;
468 $flags |= FLAG_APPEND if $got->value('AppendOutput') ;
469 $flags |= FLAG_CRC if $got->value('CRC32') ;
470 $flags |= FLAG_ADLER if $got->value('ADLER32') ;
472 $pkg->_createDeflateStream($flags,
473 $got->value('Level'),
474 $got->value('Method'),
475 $got->value('WindowBits'),
476 $got->value('MemLevel'),
477 $got->value('Strategy'),
478 $got->value('Bufsize'),
483 sub Compress::Raw::Zlib::inflateScanStream::inflate
489 my $status = $self->scan(@_);
491 if ($status == Z_OK() && $_[2]) {
494 $status = $self->scan(\$byte, $_[1]) ;
500 sub Compress::Raw::Zlib::deflateStream::deflateParams
503 my ($got) = ParseParameters(0, {
504 'Level' => [1, 1, Parse_signed, undef],
505 'Strategy' => [1, 1, Parse_unsigned, undef],
506 'Bufsize' => [1, 1, Parse_unsigned, undef],
510 croak "Compress::Raw::Zlib::deflateParams needs Level and/or Strategy"
511 unless $got->parsed('Level') + $got->parsed('Strategy') +
512 $got->parsed('Bufsize');
514 croak "Compress::Raw::Zlib::Inflate::deflateParams: Bufsize must be >= 1, you specified " .
515 $got->value('Bufsize')
516 if $got->parsed('Bufsize') && $got->value('Bufsize') <= 1;
519 $flags |= 1 if $got->parsed('Level') ;
520 $flags |= 2 if $got->parsed('Strategy') ;
521 $flags |= 4 if $got->parsed('Bufsize') ;
523 $self->_deflateParams($flags, $got->value('Level'),
524 $got->value('Strategy'), $got->value('Bufsize'));
529 # Autoload methods go after __END__, and are processed by the autosplit program.
537 Compress::Raw::Zlib - Low-Level Interface to zlib compression library
541 use Compress::Raw::Zlib ;
543 ($d, $status) = new Compress::Raw::Zlib::Deflate( [OPT] ) ;
544 $status = $d->deflate($input, $output) ;
545 $status = $d->flush($output [, $flush_type]) ;
546 $d->deflateParams(OPTS) ;
547 $d->deflateTune(OPTS) ;
558 ($i, $status) = new Compress::Raw::Zlib::Inflate( [OPT] ) ;
559 $status = $i->inflate($input, $output [, $eof]) ;
560 $status = $i->inflateSync($input) ;
569 $crc = adler32($buffer [,$crc]) ;
570 $crc = crc32($buffer [,$crc]) ;
572 $crc = adler32_combine($crc1, $crc2, $len2)l
573 $crc = crc32_combine($adler1, $adler2, $len2)
580 The I<Compress::Raw::Zlib> module provides a Perl interface to the I<zlib>
581 compression library (see L</AUTHOR> for details about where to get
584 =head1 Compress::Raw::Zlib::Deflate
586 This section defines an interface that allows in-memory compression using
587 the I<deflate> interface provided by zlib.
589 Here is a definition of the interface available:
591 =head2 B<($d, $status) = new Compress::Raw::Zlib::Deflate( [OPT] ) >
593 Initialises a deflation object.
595 If you are familiar with the I<zlib> library, it combines the
596 features of the I<zlib> functions C<deflateInit>, C<deflateInit2>
597 and C<deflateSetDictionary>.
599 If successful, it will return the initialised deflation object, C<$d>
600 and a C<$status> of C<Z_OK> in a list context. In scalar context it
601 returns the deflation object, C<$d>, only.
603 If not successful, the returned deflation object, C<$d>, will be
604 I<undef> and C<$status> will hold the a I<zlib> error code.
606 The function optionally takes a number of named options specified as
607 C<< Name => value >> pairs. This allows individual options to be
608 tailored without having to specify them all in the parameter list.
610 For backward compatibility, it is also possible to pass the parameters
611 as a reference to a hash containing the name=>value pairs.
613 Below is a list of the valid options:
619 Defines the compression level. Valid values are 0 through 9,
620 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
621 C<Z_DEFAULT_COMPRESSION>.
623 The default is C<Z_DEFAULT_COMPRESSION>.
627 Defines the compression method. The only valid value at present (and
628 the default) is Z_DEFLATED.
632 To compress an RFC 1950 data stream, set C<WindowBits> to a positive
633 number between 8 and 15.
635 To compress an RFC 1951 data stream, set C<WindowBits> to C<-MAX_WBITS>.
637 To compress an RFC 1952 data stream (i.e. gzip), set C<WindowBits> to
640 For a definition of the meaning and valid values for C<WindowBits>
641 refer to the I<zlib> documentation for I<deflateInit2>.
643 Defaults to C<MAX_WBITS>.
647 For a definition of the meaning and valid values for C<MemLevel>
648 refer to the I<zlib> documentation for I<deflateInit2>.
650 Defaults to MAX_MEM_LEVEL.
654 Defines the strategy used to tune the compression. The valid values are
655 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED>, C<Z_RLE>, C<Z_FIXED> and
658 The default is Z_DEFAULT_STRATEGY.
662 When a dictionary is specified I<Compress::Raw::Zlib> will automatically
663 call C<deflateSetDictionary> directly after calling C<deflateInit>. The
664 Adler32 value for the dictionary can be obtained by calling the method
665 C<$d-E<gt>dict_adler()>.
667 The default is no dictionary.
671 Sets the initial size for the output buffer used by the C<$d-E<gt>deflate>
672 and C<$d-E<gt>flush> methods. If the buffer has to be
673 reallocated to increase the size, it will grow in increments of
676 The default buffer size is 4096.
678 =item B<-AppendOutput>
680 This option controls how data is written to the output buffer by the
681 C<$d-E<gt>deflate> and C<$d-E<gt>flush> methods.
683 If the C<AppendOutput> option is set to false, the output buffers in the
684 C<$d-E<gt>deflate> and C<$d-E<gt>flush> methods will be truncated before
685 uncompressed data is written to them.
687 If the option is set to true, uncompressed data will be appended to the
688 output buffer in the C<$d-E<gt>deflate> and C<$d-E<gt>flush> methods.
690 This option defaults to false.
694 If set to true, a crc32 checksum of the uncompressed data will be
695 calculated. Use the C<$d-E<gt>crc32> method to retrieve this value.
697 This option defaults to false.
701 If set to true, an adler32 checksum of the uncompressed data will be
702 calculated. Use the C<$d-E<gt>adler32> method to retrieve this value.
704 This option defaults to false.
708 Here is an example of using the C<Compress::Raw::Zlib::Deflate> optional
709 parameter list to override the default buffer size and compression
710 level. All other options will take their default values.
712 my $d = new Compress::Raw::Zlib::Deflate ( -Bufsize => 300,
713 -Level => Z_BEST_SPEED ) ;
715 =head2 B<$status = $d-E<gt>deflate($input, $output)>
717 Deflates the contents of C<$input> and writes the compressed data to
720 The C<$input> and C<$output> parameters can be either scalars or scalar
723 When finished, C<$input> will be completely processed (assuming there
724 were no errors). If the deflation was successful it writes the deflated
725 data to C<$output> and returns a status value of C<Z_OK>.
727 On error, it returns a I<zlib> error code.
729 If the C<AppendOutput> option is set to true in the constructor for
730 the C<$d> object, the compressed data will be appended to C<$output>. If
731 it is false, C<$output> will be truncated before any compressed data is
734 B<Note>: This method will not necessarily write compressed data to
735 C<$output> every time it is called. So do not assume that there has been
736 an error if the contents of C<$output> is empty on returning from
737 this method. As long as the return code from the method is C<Z_OK>,
738 the deflate has succeeded.
740 =head2 B<$status = $d-E<gt>flush($output [, $flush_type]) >
742 Typically used to finish the deflation. Any pending output will be
743 written to C<$output>.
745 Returns C<Z_OK> if successful.
747 Note that flushing can seriously degrade the compression ratio, so it
748 should only be used to terminate a decompression (using C<Z_FINISH>) or
749 when you want to create a I<full flush point> (using C<Z_FULL_FLUSH>).
751 By default the C<flush_type> used is C<Z_FINISH>. Other valid values
752 for C<flush_type> are C<Z_NO_FLUSH>, C<Z_PARTIAL_FLUSH>, C<Z_SYNC_FLUSH>
753 and C<Z_FULL_FLUSH>. It is strongly recommended that you only set the
754 C<flush_type> parameter if you fully understand the implications of
755 what it does. See the C<zlib> documentation for details.
757 If the C<AppendOutput> option is set to true in the constructor for
758 the C<$d> object, the compressed data will be appended to C<$output>. If
759 it is false, C<$output> will be truncated before any compressed data is
762 =head2 B<$status = $d-E<gt>deflateParams([OPT])>
764 Change settings for the deflate object C<$d>.
766 The list of the valid options is shown below. Options not specified
767 will remain unchanged.
773 Defines the compression level. Valid values are 0 through 9,
774 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
775 C<Z_DEFAULT_COMPRESSION>.
779 Defines the strategy used to tune the compression. The valid values are
780 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
784 Sets the initial size for the output buffer used by the C<$d-E<gt>deflate>
785 and C<$d-E<gt>flush> methods. If the buffer has to be
786 reallocated to increase the size, it will grow in increments of
791 =head2 B<$status = $d-E<gt>deflateTune($good_length, $max_lazy, $nice_length, $max_chain)>
793 Tune the internal settings for the deflate object C<$d>. This option is
794 only available if you are running zlib 1.2.2.3 or better.
796 Refer to the documentation in zlib.h for instructions on how to fly
799 =head2 B<$d-E<gt>dict_adler()>
801 Returns the adler32 value for the dictionary.
803 =head2 B<$d-E<gt>crc32()>
805 Returns the crc32 value for the uncompressed data to date.
807 If the C<CRC32> option is not enabled in the constructor for this object,
808 this method will always return 0;
810 =head2 B<$d-E<gt>adler32()>
812 Returns the adler32 value for the uncompressed data to date.
814 =head2 B<$d-E<gt>msg()>
816 Returns the last error message generated by zlib.
818 =head2 B<$d-E<gt>total_in()>
820 Returns the total number of bytes uncompressed bytes input to deflate.
822 =head2 B<$d-E<gt>total_out()>
824 Returns the total number of compressed bytes output from deflate.
826 =head2 B<$d-E<gt>get_Strategy()>
828 Returns the deflation strategy currently used. Valid values are
829 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
831 =head2 B<$d-E<gt>get_Level()>
833 Returns the compression level being used.
835 =head2 B<$d-E<gt>get_BufSize()>
837 Returns the buffer size used to carry out the compression.
841 Here is a trivial example of using C<deflate>. It simply reads standard
842 input, deflates it and writes it to standard output.
847 use Compress::Raw::Zlib ;
851 my $x = new Compress::Raw::Zlib::Deflate
852 or die "Cannot create a deflation stream\n" ;
854 my ($output, $status) ;
857 $status = $x->deflate($_, $output) ;
860 or die "deflation failed\n" ;
865 $status = $x->flush($output) ;
868 or die "deflation failed\n" ;
872 =head1 Compress::Raw::Zlib::Inflate
874 This section defines an interface that allows in-memory uncompression using
875 the I<inflate> interface provided by zlib.
877 Here is a definition of the interface:
879 =head2 B< ($i, $status) = new Compress::Raw::Zlib::Inflate( [OPT] ) >
881 Initialises an inflation object.
883 In a list context it returns the inflation object, C<$i>, and the
884 I<zlib> status code (C<$status>). In a scalar context it returns the
885 inflation object only.
887 If successful, C<$i> will hold the inflation object and C<$status> will
890 If not successful, C<$i> will be I<undef> and C<$status> will hold the
893 The function optionally takes a number of named options specified as
894 C<< -Name => value >> pairs. This allows individual options to be
895 tailored without having to specify them all in the parameter list.
897 For backward compatibility, it is also possible to pass the parameters
898 as a reference to a hash containing the C<< name=>value >> pairs.
900 Here is a list of the valid options:
906 To uncompress an RFC 1950 data stream, set C<WindowBits> to a positive
907 number between 8 and 15.
909 To uncompress an RFC 1951 data stream, set C<WindowBits> to C<-MAX_WBITS>.
911 To uncompress an RFC 1952 data stream (i.e. gzip), set C<WindowBits> to
914 To auto-detect and uncompress an RFC 1950 or RFC 1952 data stream (i.e.
915 gzip), set C<WindowBits> to C<WANT_GZIP_OR_ZLIB>.
917 For a full definition of the meaning and valid values for C<WindowBits>
918 refer to the I<zlib> documentation for I<inflateInit2>.
920 Defaults to C<MAX_WBITS>.
924 Sets the initial size for the output buffer used by the C<$i-E<gt>inflate>
925 method. If the output buffer in this method has to be reallocated to
926 increase the size, it will grow in increments of C<Bufsize>.
932 The default is no dictionary.
934 =item B<-AppendOutput>
936 This option controls how data is written to the output buffer by the
937 C<$i-E<gt>inflate> method.
939 If the option is set to false, the output buffer in the C<$i-E<gt>inflate>
940 method will be truncated before uncompressed data is written to it.
942 If the option is set to true, uncompressed data will be appended to the
943 output buffer by the C<$i-E<gt>inflate> method.
945 This option defaults to false.
949 If set to true, a crc32 checksum of the uncompressed data will be
950 calculated. Use the C<$i-E<gt>crc32> method to retrieve this value.
952 This option defaults to false.
956 If set to true, an adler32 checksum of the uncompressed data will be
957 calculated. Use the C<$i-E<gt>adler32> method to retrieve this value.
959 This option defaults to false.
961 =item B<-ConsumeInput>
963 If set to true, this option will remove compressed data from the input
964 buffer of the the C< $i-E<gt>inflate > method as the inflate progresses.
966 This option can be useful when you are processing compressed data that is
967 embedded in another file/buffer. In this case the data that immediately
968 follows the compressed stream will be left in the input buffer.
970 This option defaults to true.
974 Here is an example of using an optional parameter to override the default
977 my ($i, $status) = new Compress::Raw::Zlib::Inflate( -Bufsize => 300 ) ;
979 =head2 B< $status = $i-E<gt>inflate($input, $output [,$eof]) >
981 Inflates the complete contents of C<$input> and writes the uncompressed
982 data to C<$output>. The C<$input> and C<$output> parameters can either be
983 scalars or scalar references.
985 Returns C<Z_OK> if successful and C<Z_STREAM_END> if the end of the
986 compressed data has been successfully reached.
988 If not successful C<$status> will hold the I<zlib> error code.
990 If the C<ConsumeInput> option has been set to true when the
991 C<Compress::Raw::Zlib::Inflate> object is created, the C<$input> parameter
992 is modified by C<inflate>. On completion it will contain what remains
993 of the input buffer after inflation. In practice, this means that when
994 the return status is C<Z_OK> the C<$input> parameter will contain an
995 empty string, and when the return status is C<Z_STREAM_END> the C<$input>
996 parameter will contains what (if anything) was stored in the input buffer
997 after the deflated data stream.
999 This feature is useful when processing a file format that encapsulates
1000 a compressed data stream (e.g. gzip, zip) and there is useful data
1001 immediately after the deflation stream.
1003 If the C<AppendOutput> option is set to true in the constructor for
1004 this object, the uncompressed data will be appended to C<$output>. If
1005 it is false, C<$output> will be truncated before any uncompressed data
1008 The C<$eof> parameter needs a bit of explanation.
1010 Prior to version 1.2.0, zlib assumed that there was at least one trailing
1011 byte immediately after the compressed data stream when it was carrying out
1012 decompression. This normally isn't a problem because the majority of zlib
1013 applications guarantee that there will be data directly after the
1014 compressed data stream. For example, both gzip (RFC 1950) and zip both
1015 define trailing data that follows the compressed data stream.
1017 The C<$eof> parameter only needs to be used if B<all> of the following
1024 You are either using a copy of zlib that is older than version 1.2.0 or you
1025 want your application code to be able to run with as many different
1026 versions of zlib as possible.
1030 You have set the C<WindowBits> parameter to C<-MAX_WBITS> in the constructor
1031 for this object, i.e. you are uncompressing a raw deflated data stream
1036 There is no data immediately after the compressed data stream.
1040 If B<all> of these are the case, then you need to set the C<$eof> parameter
1041 to true on the final call (and only the final call) to C<$i-E<gt>inflate>.
1043 If you have built this module with zlib >= 1.2.0, the C<$eof> parameter is
1044 ignored. You can still set it if you want, but it won't be used behind the
1047 =head2 B<$status = $i-E<gt>inflateSync($input)>
1049 This method can be used to attempt to recover good data from a compressed
1050 data stream that is partially corrupt.
1051 It scans C<$input> until it reaches either a I<full flush point> or the
1054 If a I<full flush point> is found, C<Z_OK> is returned and C<$input>
1055 will be have all data up to the flush point removed. This data can then be
1056 passed to the C<$i-E<gt>inflate> method to be uncompressed.
1058 Any other return code means that a flush point was not found. If more
1059 data is available, C<inflateSync> can be called repeatedly with more
1060 compressed data until the flush point is found.
1062 Note I<full flush points> are not present by default in compressed
1063 data streams. They must have been added explicitly when the data stream
1064 was created by calling C<Compress::Deflate::flush> with C<Z_FULL_FLUSH>.
1066 =head2 B<$i-E<gt>dict_adler()>
1068 Returns the adler32 value for the dictionary.
1070 =head2 B<$i-E<gt>crc32()>
1072 Returns the crc32 value for the uncompressed data to date.
1074 If the C<CRC32> option is not enabled in the constructor for this object,
1075 this method will always return 0;
1077 =head2 B<$i-E<gt>adler32()>
1079 Returns the adler32 value for the uncompressed data to date.
1081 If the C<ADLER32> option is not enabled in the constructor for this object,
1082 this method will always return 0;
1084 =head2 B<$i-E<gt>msg()>
1086 Returns the last error message generated by zlib.
1088 =head2 B<$i-E<gt>total_in()>
1090 Returns the total number of bytes compressed bytes input to inflate.
1092 =head2 B<$i-E<gt>total_out()>
1094 Returns the total number of uncompressed bytes output from inflate.
1096 =head2 B<$d-E<gt>get_BufSize()>
1098 Returns the buffer size used to carry out the decompression.
1102 Here is an example of using C<inflate>.
1107 use Compress::Raw::Zlib;
1109 my $x = new Compress::Raw::Zlib::Inflate()
1110 or die "Cannot create a inflation stream\n" ;
1116 my ($output, $status) ;
1117 while (read(STDIN, $input, 4096))
1119 $status = $x->inflate(\$input, $output) ;
1122 if $status == Z_OK or $status == Z_STREAM_END ;
1124 last if $status != Z_OK ;
1127 die "inflation failed\n"
1128 unless $status == Z_STREAM_END ;
1130 =head1 CHECKSUM FUNCTIONS
1132 Two functions are provided by I<zlib> to calculate checksums. For the
1133 Perl interface, the order of the two parameters in both functions has
1134 been reversed. This allows both running checksums and one off
1135 calculations to be done.
1137 $crc = adler32($buffer [,$crc]) ;
1138 $crc = crc32($buffer [,$crc]) ;
1140 The buffer parameters can either be a scalar or a scalar reference.
1142 If the $crc parameters is C<undef>, the crc value will be reset.
1144 If you have built this module with zlib 1.2.3 or better, two more
1145 CRC-related functions are available.
1147 $crc = adler32_combine($crc1, $crc2, $len2)l
1148 $crc = crc32_combine($adler1, $adler2, $len2)
1150 These functions allow checksums to be merged.
1152 =head1 ACCESSING ZIP FILES
1154 Although it is possible (with some effort on your part) to use this
1155 module to access .zip files, there is a module on CPAN that will do all
1156 the hard work for you. Check out the C<Archive::Zip> module on CPAN at
1158 http://www.cpan.org/modules/by-module/Archive/Archive-Zip-*.tar.gz
1162 All the I<zlib> constants are automatically imported when you make use
1163 of I<Compress::Raw::Zlib>.
1167 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>
1169 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1171 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1172 L<Archive::Tar|Archive::Tar>,
1173 L<IO::Zlib|IO::Zlib>
1175 For RFC 1950, 1951 and 1952 see
1176 F<http://www.faqs.org/rfcs/rfc1950.html>,
1177 F<http://www.faqs.org/rfcs/rfc1951.html> and
1178 F<http://www.faqs.org/rfcs/rfc1952.html>
1180 The I<zlib> compression library was written by Jean-loup Gailly
1181 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1183 The primary site for the I<zlib> compression library is
1184 F<http://www.zlib.org>.
1186 The primary site for gzip is F<http://www.gzip.org>.
1190 This module was written by Paul Marquess, F<pmqs@cpan.org>.
1192 =head1 MODIFICATION HISTORY
1194 See the Changes file.
1196 =head1 COPYRIGHT AND LICENSE
1198 Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
1200 This program is free software; you can redistribute it and/or
1201 modify it under the same terms as Perl itself.