This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update Compress-Raw-Zlib to CPAN version 2.047
[perl5.git] / cpan / Compress-Raw-Zlib / lib / Compress / Raw / Zlib.pm
1
2 package Compress::Raw::Zlib;
3
4 require 5.006 ;
5 require Exporter;
6 use AutoLoader;
7 use Carp ;
8
9 use strict ;
10 use warnings ;
11 use bytes ;
12 our ($VERSION, $XS_VERSION, @ISA, @EXPORT, %EXPORT_TAGS, @EXPORT_OK, $AUTOLOAD, %DEFLATE_CONSTANTS, @DEFLATE_CONSTANTS );
13
14 $VERSION = '2.047';
15 $XS_VERSION = $VERSION; 
16 $VERSION = eval $VERSION;
17
18 @ISA = qw(Exporter);
19 %EXPORT_TAGS = ( flush     => [qw{  
20                                     Z_NO_FLUSH
21                                     Z_PARTIAL_FLUSH
22                                     Z_SYNC_FLUSH
23                                     Z_FULL_FLUSH
24                                     Z_FINISH
25                                     Z_BLOCK
26                               }],
27                  level     => [qw{  
28                                     Z_NO_COMPRESSION
29                                     Z_BEST_SPEED
30                                     Z_BEST_COMPRESSION
31                                     Z_DEFAULT_COMPRESSION
32                               }],
33                  strategy  => [qw{  
34                                     Z_FILTERED
35                                     Z_HUFFMAN_ONLY
36                                     Z_RLE
37                                     Z_FIXED
38                                     Z_DEFAULT_STRATEGY
39                               }],
40                  status   => [qw{  
41                                     Z_OK
42                                     Z_STREAM_END
43                                     Z_NEED_DICT
44                                     Z_ERRNO
45                                     Z_STREAM_ERROR
46                                     Z_DATA_ERROR  
47                                     Z_MEM_ERROR   
48                                     Z_BUF_ERROR 
49                                     Z_VERSION_ERROR 
50                               }],                              
51               );
52
53 %DEFLATE_CONSTANTS = %EXPORT_TAGS;
54
55 # Items to export into callers namespace by default. Note: do not export
56 # names by default without a very good reason. Use EXPORT_OK instead.
57 # Do not simply export all your public functions/methods/constants.
58 @DEFLATE_CONSTANTS = 
59 @EXPORT = qw(
60         ZLIB_VERSION
61         ZLIB_VERNUM
62
63         
64         OS_CODE
65
66         MAX_MEM_LEVEL
67         MAX_WBITS
68
69         Z_ASCII
70         Z_BEST_COMPRESSION
71         Z_BEST_SPEED
72         Z_BINARY
73         Z_BLOCK
74         Z_BUF_ERROR
75         Z_DATA_ERROR
76         Z_DEFAULT_COMPRESSION
77         Z_DEFAULT_STRATEGY
78         Z_DEFLATED
79         Z_ERRNO
80         Z_FILTERED
81         Z_FIXED
82         Z_FINISH
83         Z_FULL_FLUSH
84         Z_HUFFMAN_ONLY
85         Z_MEM_ERROR
86         Z_NEED_DICT
87         Z_NO_COMPRESSION
88         Z_NO_FLUSH
89         Z_NULL
90         Z_OK
91         Z_PARTIAL_FLUSH
92         Z_RLE
93         Z_STREAM_END
94         Z_STREAM_ERROR
95         Z_SYNC_FLUSH
96         Z_TREES
97         Z_UNKNOWN
98         Z_VERSION_ERROR
99
100         WANT_GZIP
101         WANT_GZIP_OR_ZLIB
102 );
103
104 push @EXPORT, qw(crc32 adler32 DEF_WBITS);
105
106 use constant WANT_GZIP           => 16;
107 use constant WANT_GZIP_OR_ZLIB   => 32;
108
109 sub AUTOLOAD {
110     my($constname);
111     ($constname = $AUTOLOAD) =~ s/.*:://;
112     my ($error, $val) = constant($constname);
113     Carp::croak $error if $error;
114     no strict 'refs';
115     *{$AUTOLOAD} = sub { $val };
116     goto &{$AUTOLOAD};
117 }
118
119 use constant FLAG_APPEND             => 1 ;
120 use constant FLAG_CRC                => 2 ;
121 use constant FLAG_ADLER              => 4 ;
122 use constant FLAG_CONSUME_INPUT      => 8 ;
123 use constant FLAG_LIMIT_OUTPUT       => 16 ;
124
125 eval {
126     require XSLoader;
127     XSLoader::load('Compress::Raw::Zlib', $XS_VERSION);
128     1;
129
130 or do {
131     require DynaLoader;
132     local @ISA = qw(DynaLoader);
133     bootstrap Compress::Raw::Zlib $XS_VERSION ; 
134 };
135  
136
137 use constant Parse_any      => 0x01;
138 use constant Parse_unsigned => 0x02;
139 use constant Parse_signed   => 0x04;
140 use constant Parse_boolean  => 0x08;
141 use constant Parse_string   => 0x10;
142 use constant Parse_custom   => 0x12;
143
144 use constant Parse_store_ref => 0x100 ;
145
146 use constant OFF_PARSED     => 0 ;
147 use constant OFF_TYPE       => 1 ;
148 use constant OFF_DEFAULT    => 2 ;
149 use constant OFF_FIXED      => 3 ;
150 use constant OFF_FIRST_ONLY => 4 ;
151 use constant OFF_STICKY     => 5 ;
152
153
154
155 sub ParseParameters
156 {
157     my $level = shift || 0 ; 
158
159     my $sub = (caller($level + 1))[3] ;
160     #local $Carp::CarpLevel = 1 ;
161     my $p = new Compress::Raw::Zlib::Parameters() ;
162     $p->parse(@_)
163         or croak "$sub: $p->{Error}" ;
164
165     return $p;
166 }
167
168
169 sub Compress::Raw::Zlib::Parameters::new
170 {
171     my $class = shift ;
172
173     my $obj = { Error => '',
174                 Got   => {},
175               } ;
176
177     #return bless $obj, ref($class) || $class || __PACKAGE__ ;
178     return bless $obj, 'Compress::Raw::Zlib::Parameters' ;
179 }
180
181 sub Compress::Raw::Zlib::Parameters::setError
182 {
183     my $self = shift ;
184     my $error = shift ;
185     my $retval = @_ ? shift : undef ;
186
187     $self->{Error} = $error ;
188     return $retval;
189 }
190           
191 #sub getError
192 #{
193 #    my $self = shift ;
194 #    return $self->{Error} ;
195 #}
196           
197 sub Compress::Raw::Zlib::Parameters::parse
198 {
199     my $self = shift ;
200
201     my $default = shift ;
202
203     my $got = $self->{Got} ;
204     my $firstTime = keys %{ $got } == 0 ;
205
206     my (@Bad) ;
207     my @entered = () ;
208
209     # Allow the options to be passed as a hash reference or
210     # as the complete hash.
211     if (@_ == 0) {
212         @entered = () ;
213     }
214     elsif (@_ == 1) {
215         my $href = $_[0] ;    
216         return $self->setError("Expected even number of parameters, got 1")
217             if ! defined $href or ! ref $href or ref $href ne "HASH" ;
218  
219         foreach my $key (keys %$href) {
220             push @entered, $key ;
221             push @entered, \$href->{$key} ;
222         }
223     }
224     else {
225         my $count = @_;
226         return $self->setError("Expected even number of parameters, got $count")
227             if $count % 2 != 0 ;
228         
229         for my $i (0.. $count / 2 - 1) {
230             push @entered, $_[2* $i] ;
231             push @entered, \$_[2* $i+1] ;
232         }
233     }
234
235
236     while (my ($key, $v) = each %$default)
237     {
238         croak "need 4 params [@$v]"
239             if @$v != 4 ;
240
241         my ($first_only, $sticky, $type, $value) = @$v ;
242         my $x ;
243         $self->_checkType($key, \$value, $type, 0, \$x) 
244             or return undef ;
245
246         $key = lc $key;
247
248         if ($firstTime || ! $sticky) {
249             $got->{$key} = [0, $type, $value, $x, $first_only, $sticky] ;
250         }
251
252         $got->{$key}[OFF_PARSED] = 0 ;
253     }
254
255     for my $i (0.. @entered / 2 - 1) {
256         my $key = $entered[2* $i] ;
257         my $value = $entered[2* $i+1] ;
258
259         #print "Key [$key] Value [$value]" ;
260         #print defined $$value ? "[$$value]\n" : "[undef]\n";
261
262         $key =~ s/^-// ;
263         my $canonkey = lc $key;
264  
265         if ($got->{$canonkey} && ($firstTime ||
266                                   ! $got->{$canonkey}[OFF_FIRST_ONLY]  ))
267         {
268             my $type = $got->{$canonkey}[OFF_TYPE] ;
269             my $s ;
270             $self->_checkType($key, $value, $type, 1, \$s)
271                 or return undef ;
272             #$value = $$value unless $type & Parse_store_ref ;
273             $value = $$value ;
274             $got->{$canonkey} = [1, $type, $value, $s] ;
275         }
276         else
277           { push (@Bad, $key) }
278     }
279  
280     if (@Bad) {
281         my ($bad) = join(", ", @Bad) ;
282         return $self->setError("unknown key value(s) @Bad") ;
283     }
284
285     return 1;
286 }
287
288 sub Compress::Raw::Zlib::Parameters::_checkType
289 {
290     my $self = shift ;
291
292     my $key   = shift ;
293     my $value = shift ;
294     my $type  = shift ;
295     my $validate  = shift ;
296     my $output  = shift;
297
298     #local $Carp::CarpLevel = $level ;
299     #print "PARSE $type $key $value $validate $sub\n" ;
300     if ( $type & Parse_store_ref)
301     {
302         #$value = $$value
303         #    if ref ${ $value } ;
304
305         $$output = $value ;
306         return 1;
307     }
308
309     $value = $$value ;
310
311     if ($type & Parse_any)
312     {
313         $$output = $value ;
314         return 1;
315     }
316     elsif ($type & Parse_unsigned)
317     {
318         return $self->setError("Parameter '$key' must be an unsigned int, got 'undef'")
319             if $validate && ! defined $value ;
320         return $self->setError("Parameter '$key' must be an unsigned int, got '$value'")
321             if $validate && $value !~ /^\d+$/;
322
323         $$output = defined $value ? $value : 0 ;    
324         return 1;
325     }
326     elsif ($type & Parse_signed)
327     {
328         return $self->setError("Parameter '$key' must be a signed int, got 'undef'")
329             if $validate && ! defined $value ;
330         return $self->setError("Parameter '$key' must be a signed int, got '$value'")
331             if $validate && $value !~ /^-?\d+$/;
332
333         $$output = defined $value ? $value : 0 ;    
334         return 1 ;
335     }
336     elsif ($type & Parse_boolean)
337     {
338         return $self->setError("Parameter '$key' must be an int, got '$value'")
339             if $validate && defined $value && $value !~ /^\d*$/;
340         $$output =  defined $value ? $value != 0 : 0 ;    
341         return 1;
342     }
343     elsif ($type & Parse_string)
344     {
345         $$output = defined $value ? $value : "" ;    
346         return 1;
347     }
348
349     $$output = $value ;
350     return 1;
351 }
352
353
354
355 sub Compress::Raw::Zlib::Parameters::parsed
356 {
357     my $self = shift ;
358     my $name = shift ;
359
360     return $self->{Got}{lc $name}[OFF_PARSED] ;
361 }
362
363 sub Compress::Raw::Zlib::Parameters::value
364 {
365     my $self = shift ;
366     my $name = shift ;
367
368     if (@_)
369     {
370         $self->{Got}{lc $name}[OFF_PARSED]  = 1;
371         $self->{Got}{lc $name}[OFF_DEFAULT] = $_[0] ;
372         $self->{Got}{lc $name}[OFF_FIXED]   = $_[0] ;
373     }
374
375     return $self->{Got}{lc $name}[OFF_FIXED] ;
376 }
377
378 sub Compress::Raw::Zlib::Deflate::new
379 {
380     my $pkg = shift ;
381     my ($got) = ParseParameters(0,
382             {
383                 'AppendOutput'  => [1, 1, Parse_boolean,  0],
384                 'CRC32'         => [1, 1, Parse_boolean,  0],
385                 'ADLER32'       => [1, 1, Parse_boolean,  0],
386                 'Bufsize'       => [1, 1, Parse_unsigned, 4096],
387  
388                 'Level'         => [1, 1, Parse_signed,   Z_DEFAULT_COMPRESSION()],
389                 'Method'        => [1, 1, Parse_unsigned, Z_DEFLATED()],
390                 'WindowBits'    => [1, 1, Parse_signed,   MAX_WBITS()],
391                 'MemLevel'      => [1, 1, Parse_unsigned, MAX_MEM_LEVEL()],
392                 'Strategy'      => [1, 1, Parse_unsigned, Z_DEFAULT_STRATEGY()],
393                 'Dictionary'    => [1, 1, Parse_any,      ""],
394             }, @_) ;
395
396
397     croak "Compress::Raw::Zlib::Deflate::new: Bufsize must be >= 1, you specified " . 
398             $got->value('Bufsize')
399         unless $got->value('Bufsize') >= 1;
400
401     my $flags = 0 ;
402     $flags |= FLAG_APPEND if $got->value('AppendOutput') ;
403     $flags |= FLAG_CRC    if $got->value('CRC32') ;
404     $flags |= FLAG_ADLER  if $got->value('ADLER32') ;
405
406     my $windowBits =  $got->value('WindowBits');
407     $windowBits += MAX_WBITS()
408         if ($windowBits & MAX_WBITS()) == 0 ;
409
410     _deflateInit($flags,
411                 $got->value('Level'), 
412                 $got->value('Method'), 
413                 $windowBits, 
414                 $got->value('MemLevel'), 
415                 $got->value('Strategy'), 
416                 $got->value('Bufsize'),
417                 $got->value('Dictionary')) ;
418
419 }
420
421 sub Compress::Raw::Zlib::deflateStream::STORABLE_freeze
422 {
423     my $type = ref shift;
424     croak "Cannot freeze $type object\n";
425 }
426
427 sub Compress::Raw::Zlib::deflateStream::STORABLE_thaw
428 {
429     my $type = ref shift;
430     croak "Cannot thaw $type object\n";
431 }
432
433
434 sub Compress::Raw::Zlib::Inflate::new
435 {
436     my $pkg = shift ;
437     my ($got) = ParseParameters(0,
438                     {
439                         'AppendOutput'  => [1, 1, Parse_boolean,  0],
440                         'LimitOutput'   => [1, 1, Parse_boolean,  0],
441                         'CRC32'         => [1, 1, Parse_boolean,  0],
442                         'ADLER32'       => [1, 1, Parse_boolean,  0],
443                         'ConsumeInput'  => [1, 1, Parse_boolean,  1],
444                         'Bufsize'       => [1, 1, Parse_unsigned, 4096],
445                  
446                         'WindowBits'    => [1, 1, Parse_signed,   MAX_WBITS()],
447                         'Dictionary'    => [1, 1, Parse_any,      ""],
448             }, @_) ;
449
450
451     croak "Compress::Raw::Zlib::Inflate::new: Bufsize must be >= 1, you specified " . 
452             $got->value('Bufsize')
453         unless $got->value('Bufsize') >= 1;
454
455     my $flags = 0 ;
456     $flags |= FLAG_APPEND if $got->value('AppendOutput') ;
457     $flags |= FLAG_CRC    if $got->value('CRC32') ;
458     $flags |= FLAG_ADLER  if $got->value('ADLER32') ;
459     $flags |= FLAG_CONSUME_INPUT if $got->value('ConsumeInput') ;
460     $flags |= FLAG_LIMIT_OUTPUT if $got->value('LimitOutput') ;
461
462
463     my $windowBits =  $got->value('WindowBits');
464     $windowBits += MAX_WBITS()
465         if ($windowBits & MAX_WBITS()) == 0 ;
466
467     _inflateInit($flags, $windowBits, $got->value('Bufsize'), 
468                  $got->value('Dictionary')) ;
469 }
470
471 sub Compress::Raw::Zlib::inflateStream::STORABLE_freeze
472 {
473     my $type = ref shift;
474     croak "Cannot freeze $type object\n";
475 }
476
477 sub Compress::Raw::Zlib::inflateStream::STORABLE_thaw
478 {
479     my $type = ref shift;
480     croak "Cannot thaw $type object\n";
481 }
482
483 sub Compress::Raw::Zlib::InflateScan::new
484 {
485     my $pkg = shift ;
486     my ($got) = ParseParameters(0,
487                     {
488                         'CRC32'         => [1, 1, Parse_boolean,  0],
489                         'ADLER32'       => [1, 1, Parse_boolean,  0],
490                         'Bufsize'       => [1, 1, Parse_unsigned, 4096],
491                  
492                         'WindowBits'    => [1, 1, Parse_signed,   -MAX_WBITS()],
493                         'Dictionary'    => [1, 1, Parse_any,      ""],
494             }, @_) ;
495
496
497     croak "Compress::Raw::Zlib::InflateScan::new: Bufsize must be >= 1, you specified " . 
498             $got->value('Bufsize')
499         unless $got->value('Bufsize') >= 1;
500
501     my $flags = 0 ;
502     #$flags |= FLAG_APPEND if $got->value('AppendOutput') ;
503     $flags |= FLAG_CRC    if $got->value('CRC32') ;
504     $flags |= FLAG_ADLER  if $got->value('ADLER32') ;
505     #$flags |= FLAG_CONSUME_INPUT if $got->value('ConsumeInput') ;
506
507     _inflateScanInit($flags, $got->value('WindowBits'), $got->value('Bufsize'), 
508                  '') ;
509 }
510
511 sub Compress::Raw::Zlib::inflateScanStream::createDeflateStream
512 {
513     my $pkg = shift ;
514     my ($got) = ParseParameters(0,
515             {
516                 'AppendOutput'  => [1, 1, Parse_boolean,  0],
517                 'CRC32'         => [1, 1, Parse_boolean,  0],
518                 'ADLER32'       => [1, 1, Parse_boolean,  0],
519                 'Bufsize'       => [1, 1, Parse_unsigned, 4096],
520  
521                 'Level'         => [1, 1, Parse_signed,   Z_DEFAULT_COMPRESSION()],
522                 'Method'        => [1, 1, Parse_unsigned, Z_DEFLATED()],
523                 'WindowBits'    => [1, 1, Parse_signed,   - MAX_WBITS()],
524                 'MemLevel'      => [1, 1, Parse_unsigned, MAX_MEM_LEVEL()],
525                 'Strategy'      => [1, 1, Parse_unsigned, Z_DEFAULT_STRATEGY()],
526             }, @_) ;
527
528     croak "Compress::Raw::Zlib::InflateScan::createDeflateStream: Bufsize must be >= 1, you specified " . 
529             $got->value('Bufsize')
530         unless $got->value('Bufsize') >= 1;
531
532     my $flags = 0 ;
533     $flags |= FLAG_APPEND if $got->value('AppendOutput') ;
534     $flags |= FLAG_CRC    if $got->value('CRC32') ;
535     $flags |= FLAG_ADLER  if $got->value('ADLER32') ;
536
537     $pkg->_createDeflateStream($flags,
538                 $got->value('Level'), 
539                 $got->value('Method'), 
540                 $got->value('WindowBits'), 
541                 $got->value('MemLevel'), 
542                 $got->value('Strategy'), 
543                 $got->value('Bufsize'),
544                 ) ;
545
546 }
547
548 sub Compress::Raw::Zlib::inflateScanStream::inflate
549 {
550     my $self = shift ;
551     my $buffer = $_[1];
552     my $eof = $_[2];
553
554     my $status = $self->scan(@_);
555
556     if ($status == Z_OK() && $_[2]) {
557         my $byte = ' ';
558         
559         $status = $self->scan(\$byte, $_[1]) ;
560     }
561     
562     return $status ;
563 }
564
565 sub Compress::Raw::Zlib::deflateStream::deflateParams
566 {
567     my $self = shift ;
568     my ($got) = ParseParameters(0, {
569                 'Level'      => [1, 1, Parse_signed,   undef],
570                 'Strategy'   => [1, 1, Parse_unsigned, undef],
571                 'Bufsize'    => [1, 1, Parse_unsigned, undef],
572                 }, 
573                 @_) ;
574
575     croak "Compress::Raw::Zlib::deflateParams needs Level and/or Strategy"
576         unless $got->parsed('Level') + $got->parsed('Strategy') +
577             $got->parsed('Bufsize');
578
579     croak "Compress::Raw::Zlib::Inflate::deflateParams: Bufsize must be >= 1, you specified " . 
580             $got->value('Bufsize')
581         if $got->parsed('Bufsize') && $got->value('Bufsize') <= 1;
582
583     my $flags = 0;
584     $flags |= 1 if $got->parsed('Level') ;
585     $flags |= 2 if $got->parsed('Strategy') ;
586     $flags |= 4 if $got->parsed('Bufsize') ;
587
588     $self->_deflateParams($flags, $got->value('Level'), 
589                           $got->value('Strategy'), $got->value('Bufsize'));
590
591 }
592
593
594 # Autoload methods go after __END__, and are processed by the autosplit program.
595
596 1;
597 __END__
598
599
600 =head1 NAME
601
602 Compress::Raw::Zlib - Low-Level Interface to zlib compression library
603
604 =head1 SYNOPSIS
605
606     use Compress::Raw::Zlib ;
607
608     ($d, $status) = new Compress::Raw::Zlib::Deflate( [OPT] ) ;
609     $status = $d->deflate($input, $output) ;
610     $status = $d->flush($output [, $flush_type]) ;
611     $d->deflateReset() ;
612     $d->deflateParams(OPTS) ;
613     $d->deflateTune(OPTS) ;
614     $d->dict_adler() ;
615     $d->crc32() ;
616     $d->adler32() ;
617     $d->total_in() ;
618     $d->total_out() ;
619     $d->msg() ;
620     $d->get_Strategy();
621     $d->get_Level();
622     $d->get_BufSize();
623
624     ($i, $status) = new Compress::Raw::Zlib::Inflate( [OPT] ) ;
625     $status = $i->inflate($input, $output [, $eof]) ;
626     $status = $i->inflateSync($input) ;
627     $i->inflateReset() ;
628     $i->dict_adler() ;
629     $d->crc32() ;
630     $d->adler32() ;
631     $i->total_in() ;
632     $i->total_out() ;
633     $i->msg() ;
634     $d->get_BufSize();
635
636     $crc = adler32($buffer [,$crc]) ;
637     $crc = crc32($buffer [,$crc]) ;
638
639     $crc = adler32_combine($crc1, $crc2, $len2)l
640     $crc = crc32_combine($adler1, $adler2, $len2)
641
642     my $version = Compress::Raw::Zlib::zlib_version();
643     my $flags = Compress::Raw::Zlib::zlibCompileFlags();
644
645 =head1 DESCRIPTION
646
647 The I<Compress::Raw::Zlib> module provides a Perl interface to the I<zlib>
648 compression library (see L</AUTHOR> for details about where to get
649 I<zlib>). 
650
651 =head1 Compress::Raw::Zlib::Deflate
652
653 This section defines an interface that allows in-memory compression using
654 the I<deflate> interface provided by zlib.
655
656 Here is a definition of the interface available:
657
658 =head2 B<($d, $status) = new Compress::Raw::Zlib::Deflate( [OPT] ) >
659
660 Initialises a deflation object. 
661
662 If you are familiar with the I<zlib> library, it combines the
663 features of the I<zlib> functions C<deflateInit>, C<deflateInit2>
664 and C<deflateSetDictionary>.
665
666 If successful, it will return the initialised deflation object, C<$d>
667 and a C<$status> of C<Z_OK> in a list context. In scalar context it
668 returns the deflation object, C<$d>, only.
669
670 If not successful, the returned deflation object, C<$d>, will be
671 I<undef> and C<$status> will hold the a I<zlib> error code.
672
673 The function optionally takes a number of named options specified as
674 C<< Name => value >> pairs. This allows individual options to be
675 tailored without having to specify them all in the parameter list.
676
677 For backward compatibility, it is also possible to pass the parameters
678 as a reference to a hash containing the name=>value pairs.
679
680 Below is a list of the valid options:
681
682 =over 5
683
684 =item B<-Level>
685
686 Defines the compression level. Valid values are 0 through 9,
687 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
688 C<Z_DEFAULT_COMPRESSION>.
689
690 The default is C<Z_DEFAULT_COMPRESSION>.
691
692 =item B<-Method>
693
694 Defines the compression method. The only valid value at present (and
695 the default) is C<Z_DEFLATED>.
696
697 =item B<-WindowBits>
698
699 To compress an RFC 1950 data stream, set C<WindowBits> to a positive
700 number between 8 and 15.
701
702 To compress an RFC 1951 data stream, set C<WindowBits> to C<-MAX_WBITS>.
703
704 To compress an RFC 1952 data stream (i.e. gzip), set C<WindowBits> to
705 C<WANT_GZIP>.
706
707 For a definition of the meaning and valid values for C<WindowBits>
708 refer to the I<zlib> documentation for I<deflateInit2>.
709
710 Defaults to C<MAX_WBITS>.
711
712 =item B<-MemLevel>
713
714 For a definition of the meaning and valid values for C<MemLevel>
715 refer to the I<zlib> documentation for I<deflateInit2>.
716
717 Defaults to MAX_MEM_LEVEL.
718
719 =item B<-Strategy>
720
721 Defines the strategy used to tune the compression. The valid values are
722 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED>, C<Z_RLE>, C<Z_FIXED> and
723 C<Z_HUFFMAN_ONLY>.
724
725 The default is C<Z_DEFAULT_STRATEGY>.
726
727 =item B<-Dictionary>
728
729 When a dictionary is specified I<Compress::Raw::Zlib> will automatically
730 call C<deflateSetDictionary> directly after calling C<deflateInit>. The
731 Adler32 value for the dictionary can be obtained by calling the method 
732 C<$d-E<gt>dict_adler()>.
733
734 The default is no dictionary.
735
736 =item B<-Bufsize>
737
738 Sets the initial size for the output buffer used by the C<$d-E<gt>deflate>
739 and C<$d-E<gt>flush> methods. If the buffer has to be
740 reallocated to increase the size, it will grow in increments of
741 C<Bufsize>.
742
743 The default buffer size is 4096.
744
745 =item B<-AppendOutput>
746
747 This option controls how data is written to the output buffer by the
748 C<$d-E<gt>deflate> and C<$d-E<gt>flush> methods.
749
750 If the C<AppendOutput> option is set to false, the output buffers in the
751 C<$d-E<gt>deflate> and C<$d-E<gt>flush>  methods will be truncated before
752 uncompressed data is written to them.
753
754 If the option is set to true, uncompressed data will be appended to the
755 output buffer in the C<$d-E<gt>deflate> and C<$d-E<gt>flush> methods.
756
757 This option defaults to false.
758
759 =item B<-CRC32>
760
761 If set to true, a crc32 checksum of the uncompressed data will be
762 calculated. Use the C<$d-E<gt>crc32> method to retrieve this value.
763
764 This option defaults to false.
765
766 =item B<-ADLER32>
767
768 If set to true, an adler32 checksum of the uncompressed data will be
769 calculated. Use the C<$d-E<gt>adler32> method to retrieve this value.
770
771 This option defaults to false.
772
773 =back
774
775 Here is an example of using the C<Compress::Raw::Zlib::Deflate> optional
776 parameter list to override the default buffer size and compression
777 level. All other options will take their default values.
778
779     my $d = new Compress::Raw::Zlib::Deflate ( -Bufsize => 300, 
780                                                -Level   => Z_BEST_SPEED ) ;
781
782 =head2 B<$status = $d-E<gt>deflate($input, $output)>
783
784 Deflates the contents of C<$input> and writes the compressed data to
785 C<$output>.
786
787 The C<$input> and C<$output> parameters can be either scalars or scalar
788 references.
789
790 When finished, C<$input> will be completely processed (assuming there
791 were no errors). If the deflation was successful it writes the deflated
792 data to C<$output> and returns a status value of C<Z_OK>.
793
794 On error, it returns a I<zlib> error code.
795
796 If the C<AppendOutput> option is set to true in the constructor for
797 the C<$d> object, the compressed data will be appended to C<$output>. If
798 it is false, C<$output> will be truncated before any compressed data is
799 written to it.
800
801 B<Note>: This method will not necessarily write compressed data to
802 C<$output> every time it is called. So do not assume that there has been
803 an error if the contents of C<$output> is empty on returning from
804 this method. As long as the return code from the method is C<Z_OK>,
805 the deflate has succeeded.
806
807 =head2 B<$status = $d-E<gt>flush($output [, $flush_type]) >
808
809 Typically used to finish the deflation. Any pending output will be
810 written to C<$output>.
811
812 Returns C<Z_OK> if successful.
813
814 Note that flushing can seriously degrade the compression ratio, so it
815 should only be used to terminate a decompression (using C<Z_FINISH>) or
816 when you want to create a I<full flush point> (using C<Z_FULL_FLUSH>).
817
818 By default the C<flush_type> used is C<Z_FINISH>. Other valid values
819 for C<flush_type> are C<Z_NO_FLUSH>, C<Z_PARTIAL_FLUSH>, C<Z_SYNC_FLUSH>
820 and C<Z_FULL_FLUSH>. It is strongly recommended that you only set the
821 C<flush_type> parameter if you fully understand the implications of
822 what it does. See the C<zlib> documentation for details.
823
824 If the C<AppendOutput> option is set to true in the constructor for
825 the C<$d> object, the compressed data will be appended to C<$output>. If
826 it is false, C<$output> will be truncated before any compressed data is
827 written to it.
828
829 =head2 B<$status = $d-E<gt>deflateReset() >
830
831 This method will reset the deflation object C<$d>. It can be used when you
832 are compressing multiple data streams and want to use the same object to
833 compress each of them. It should only be used once the previous data stream
834 has been flushed successfully, i.e. a call to C<< $d->flush(Z_FINISH) >> has
835 returned C<Z_OK>.
836
837 Returns C<Z_OK> if successful.
838
839 =head2 B<$status = $d-E<gt>deflateParams([OPT])>
840
841 Change settings for the deflate object C<$d>.
842
843 The list of the valid options is shown below. Options not specified
844 will remain unchanged.
845
846 =over 5
847
848 =item B<-Level>
849
850 Defines the compression level. Valid values are 0 through 9,
851 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
852 C<Z_DEFAULT_COMPRESSION>.
853
854 =item B<-Strategy>
855
856 Defines the strategy used to tune the compression. The valid values are
857 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>. 
858
859 =item B<-BufSize>
860
861 Sets the initial size for the output buffer used by the C<$d-E<gt>deflate>
862 and C<$d-E<gt>flush> methods. If the buffer has to be
863 reallocated to increase the size, it will grow in increments of
864 C<Bufsize>.
865
866 =back
867
868 =head2 B<$status = $d-E<gt>deflateTune($good_length, $max_lazy, $nice_length, $max_chain)>
869
870 Tune the internal settings for the deflate object C<$d>. This option is
871 only available if you are running zlib 1.2.2.3 or better.
872
873 Refer to the documentation in zlib.h for instructions on how to fly
874 C<deflateTune>.
875
876 =head2 B<$d-E<gt>dict_adler()>
877
878 Returns the adler32 value for the dictionary.
879
880 =head2 B<$d-E<gt>crc32()>
881
882 Returns the crc32 value for the uncompressed data to date. 
883
884 If the C<CRC32> option is not enabled in the constructor for this object,
885 this method will always return 0;
886
887 =head2 B<$d-E<gt>adler32()>
888
889 Returns the adler32 value for the uncompressed data to date. 
890
891 =head2 B<$d-E<gt>msg()>
892
893 Returns the last error message generated by zlib.
894
895 =head2 B<$d-E<gt>total_in()>
896
897 Returns the total number of bytes uncompressed bytes input to deflate.
898
899 =head2 B<$d-E<gt>total_out()>
900
901 Returns the total number of compressed bytes output from deflate.
902
903 =head2 B<$d-E<gt>get_Strategy()>
904
905 Returns the deflation strategy currently used. Valid values are
906 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>. 
907
908 =head2 B<$d-E<gt>get_Level()>
909
910 Returns the compression level being used. 
911
912 =head2 B<$d-E<gt>get_BufSize()>
913
914 Returns the buffer size used to carry out the compression.
915
916 =head2 Example
917
918 Here is a trivial example of using C<deflate>. It simply reads standard
919 input, deflates it and writes it to standard output.
920
921     use strict ;
922     use warnings ;
923
924     use Compress::Raw::Zlib ;
925
926     binmode STDIN;
927     binmode STDOUT;
928     my $x = new Compress::Raw::Zlib::Deflate
929        or die "Cannot create a deflation stream\n" ;
930
931     my ($output, $status) ;
932     while (<>)
933     {
934         $status = $x->deflate($_, $output) ;
935     
936         $status == Z_OK
937             or die "deflation failed\n" ;
938     
939         print $output ;
940     }
941     
942     $status = $x->flush($output) ;
943     
944     $status == Z_OK
945         or die "deflation failed\n" ;
946     
947     print $output ;
948
949 =head1 Compress::Raw::Zlib::Inflate
950
951 This section defines an interface that allows in-memory uncompression using
952 the I<inflate> interface provided by zlib.
953
954 Here is a definition of the interface:
955
956 =head2 B< ($i, $status) = new Compress::Raw::Zlib::Inflate( [OPT] ) >
957
958 Initialises an inflation object. 
959
960 In a list context it returns the inflation object, C<$i>, and the
961 I<zlib> status code (C<$status>). In a scalar context it returns the
962 inflation object only.
963
964 If successful, C<$i> will hold the inflation object and C<$status> will
965 be C<Z_OK>.
966
967 If not successful, C<$i> will be I<undef> and C<$status> will hold the
968 I<zlib> error code.
969
970 The function optionally takes a number of named options specified as
971 C<< -Name => value >> pairs. This allows individual options to be
972 tailored without having to specify them all in the parameter list.
973
974 For backward compatibility, it is also possible to pass the parameters
975 as a reference to a hash containing the C<< name=>value >> pairs.
976
977 Here is a list of the valid options:
978
979 =over 5
980
981 =item B<-WindowBits>
982
983 To uncompress an RFC 1950 data stream, set C<WindowBits> to a positive
984 number between 8 and 15.
985
986 To uncompress an RFC 1951 data stream, set C<WindowBits> to C<-MAX_WBITS>.
987
988 To uncompress an RFC 1952 data stream (i.e. gzip), set C<WindowBits> to
989 C<WANT_GZIP>.
990
991 To auto-detect and uncompress an RFC 1950 or RFC 1952 data stream (i.e.
992 gzip), set C<WindowBits> to C<WANT_GZIP_OR_ZLIB>.
993
994 For a full definition of the meaning and valid values for C<WindowBits>
995 refer to the I<zlib> documentation for I<inflateInit2>.
996
997 Defaults to C<MAX_WBITS>.
998
999 =item B<-Bufsize>
1000
1001 Sets the initial size for the output buffer used by the C<$i-E<gt>inflate>
1002 method. If the output buffer in this method has to be reallocated to
1003 increase the size, it will grow in increments of C<Bufsize>.
1004
1005 Default is 4096.
1006
1007 =item B<-Dictionary>
1008
1009 The default is no dictionary.
1010
1011 =item B<-AppendOutput>
1012
1013 This option controls how data is written to the output buffer by the
1014 C<$i-E<gt>inflate> method.
1015
1016 If the option is set to false, the output buffer in the C<$i-E<gt>inflate>
1017 method will be truncated before uncompressed data is written to it.
1018
1019 If the option is set to true, uncompressed data will be appended to the
1020 output buffer by the C<$i-E<gt>inflate> method.
1021
1022 This option defaults to false.
1023
1024 =item B<-CRC32>
1025
1026 If set to true, a crc32 checksum of the uncompressed data will be
1027 calculated. Use the C<$i-E<gt>crc32> method to retrieve this value.
1028
1029 This option defaults to false.
1030
1031 =item B<-ADLER32>
1032
1033 If set to true, an adler32 checksum of the uncompressed data will be
1034 calculated. Use the C<$i-E<gt>adler32> method to retrieve this value.
1035
1036 This option defaults to false.
1037
1038 =item B<-ConsumeInput>
1039
1040 If set to true, this option will remove compressed data from the input
1041 buffer of the C<< $i->inflate >> method as the inflate progresses.
1042
1043 This option can be useful when you are processing compressed data that is
1044 embedded in another file/buffer. In this case the data that immediately
1045 follows the compressed stream will be left in the input buffer.
1046
1047 This option defaults to true.
1048
1049 =item B<-LimitOutput>
1050
1051 The C<LimitOutput> option changes the behavior of the C<< $i->inflate >>
1052 method so that the amount of memory used by the output buffer can be
1053 limited. 
1054
1055 When C<LimitOutput> is used the size of the output buffer used will either
1056 be the value of the C<Bufsize> option or the amount of memory already
1057 allocated to C<$output>, whichever is larger. Predicting the output size
1058 available is tricky, so don't rely on getting an exact output buffer size.
1059
1060 When C<LimitOutout> is not specified C<< $i->inflate >> will use as much
1061 memory as it takes to write all the uncompressed data it creates by
1062 uncompressing the input buffer.
1063
1064 If C<LimitOutput> is enabled, the C<ConsumeInput> option will also be
1065 enabled.
1066
1067 This option defaults to false.
1068
1069 See L</The LimitOutput option> for a discussion on why C<LimitOutput> is
1070 needed and how to use it.
1071
1072 =back
1073
1074 Here is an example of using an optional parameter to override the default
1075 buffer size.
1076
1077     my ($i, $status) = new Compress::Raw::Zlib::Inflate( -Bufsize => 300 ) ;
1078
1079 =head2 B< $status = $i-E<gt>inflate($input, $output [,$eof]) >
1080
1081 Inflates the complete contents of C<$input> and writes the uncompressed
1082 data to C<$output>. The C<$input> and C<$output> parameters can either be
1083 scalars or scalar references.
1084
1085 Returns C<Z_OK> if successful and C<Z_STREAM_END> if the end of the
1086 compressed data has been successfully reached. 
1087
1088 If not successful C<$status> will hold the I<zlib> error code.
1089
1090 If the C<ConsumeInput> option has been set to true when the
1091 C<Compress::Raw::Zlib::Inflate> object is created, the C<$input> parameter
1092 is modified by C<inflate>. On completion it will contain what remains
1093 of the input buffer after inflation. In practice, this means that when
1094 the return status is C<Z_OK> the C<$input> parameter will contain an
1095 empty string, and when the return status is C<Z_STREAM_END> the C<$input>
1096 parameter will contains what (if anything) was stored in the input buffer
1097 after the deflated data stream.
1098
1099 This feature is useful when processing a file format that encapsulates
1100 a compressed data stream (e.g. gzip, zip) and there is useful data
1101 immediately after the deflation stream.
1102
1103 If the C<AppendOutput> option is set to true in the constructor for
1104 this object, the uncompressed data will be appended to C<$output>. If
1105 it is false, C<$output> will be truncated before any uncompressed data
1106 is written to it.
1107
1108 The C<$eof> parameter needs a bit of explanation. 
1109
1110 Prior to version 1.2.0, zlib assumed that there was at least one trailing
1111 byte immediately after the compressed data stream when it was carrying out
1112 decompression. This normally isn't a problem because the majority of zlib
1113 applications guarantee that there will be data directly after the
1114 compressed data stream.  For example, both gzip (RFC 1950) and zip both
1115 define trailing data that follows the compressed data stream.
1116
1117 The C<$eof> parameter only needs to be used if B<all> of the following
1118 conditions apply
1119
1120 =over 5
1121
1122 =item 1 
1123
1124 You are either using a copy of zlib that is older than version 1.2.0 or you
1125 want your application code to be able to run with as many different
1126 versions of zlib as possible.
1127
1128 =item 2
1129
1130 You have set the C<WindowBits> parameter to C<-MAX_WBITS> in the constructor
1131 for this object, i.e. you are uncompressing a raw deflated data stream
1132 (RFC 1951).
1133
1134 =item 3
1135
1136 There is no data immediately after the compressed data stream.
1137
1138 =back
1139
1140 If B<all> of these are the case, then you need to set the C<$eof> parameter
1141 to true on the final call (and only the final call) to C<$i-E<gt>inflate>. 
1142
1143 If you have built this module with zlib >= 1.2.0, the C<$eof> parameter is
1144 ignored. You can still set it if you want, but it won't be used behind the
1145 scenes.
1146
1147 =head2 B<$status = $i-E<gt>inflateSync($input)>
1148
1149 This method can be used to attempt to recover good data from a compressed
1150 data stream that is partially corrupt.
1151 It scans C<$input> until it reaches either a I<full flush point> or the
1152 end of the buffer.
1153
1154 If a I<full flush point> is found, C<Z_OK> is returned and C<$input>
1155 will be have all data up to the flush point removed. This data can then be
1156 passed to the C<$i-E<gt>inflate> method to be uncompressed.
1157
1158 Any other return code means that a flush point was not found. If more
1159 data is available, C<inflateSync> can be called repeatedly with more
1160 compressed data until the flush point is found.
1161
1162 Note I<full flush points> are not present by default in compressed
1163 data streams. They must have been added explicitly when the data stream
1164 was created by calling C<Compress::Deflate::flush>  with C<Z_FULL_FLUSH>.
1165
1166 =head2 B<$status = $i-E<gt>inflateReset() >
1167
1168 This method will reset the inflation object C<$i>. It can be used when you
1169 are uncompressing multiple data streams and want to use the same object to
1170 uncompress each of them. 
1171
1172 Returns C<Z_OK> if successful.
1173
1174 =head2 B<$i-E<gt>dict_adler()>
1175
1176 Returns the adler32 value for the dictionary.
1177
1178 =head2 B<$i-E<gt>crc32()>
1179
1180 Returns the crc32 value for the uncompressed data to date.
1181
1182 If the C<CRC32> option is not enabled in the constructor for this object,
1183 this method will always return 0;
1184
1185 =head2 B<$i-E<gt>adler32()>
1186
1187 Returns the adler32 value for the uncompressed data to date.
1188
1189 If the C<ADLER32> option is not enabled in the constructor for this object,
1190 this method will always return 0;
1191
1192 =head2 B<$i-E<gt>msg()>
1193
1194 Returns the last error message generated by zlib.
1195
1196 =head2 B<$i-E<gt>total_in()>
1197
1198 Returns the total number of bytes compressed bytes input to inflate.
1199
1200 =head2 B<$i-E<gt>total_out()>
1201
1202 Returns the total number of uncompressed bytes output from inflate.
1203
1204 =head2 B<$d-E<gt>get_BufSize()>
1205
1206 Returns the buffer size used to carry out the decompression.
1207
1208 =head2 Examples
1209
1210 Here is an example of using C<inflate>.
1211
1212     use strict ;
1213     use warnings ;
1214     
1215     use Compress::Raw::Zlib;
1216     
1217     my $x = new Compress::Raw::Zlib::Inflate()
1218        or die "Cannot create a inflation stream\n" ;
1219     
1220     my $input = '' ;
1221     binmode STDIN;
1222     binmode STDOUT;
1223     
1224     my ($output, $status) ;
1225     while (read(STDIN, $input, 4096))
1226     {
1227         $status = $x->inflate($input, $output) ;
1228     
1229         print $output ;
1230     
1231         last if $status != Z_OK ;
1232     }
1233     
1234     die "inflation failed\n"
1235         unless $status == Z_STREAM_END ;
1236
1237 The next example show how to use the C<LimitOutput> option. Notice the use
1238 of two nested loops in this case. The outer loop reads the data from the
1239 input source - STDIN and the inner loop repeatedly calls C<inflate> until
1240 C<$input> is exhausted, we get an error, or the end of the stream is
1241 reached. One point worth remembering is by using the C<LimitOutput> option
1242 you also get C<ConsumeInput> set as well - this makes the code below much
1243 simpler.
1244
1245     use strict ;
1246     use warnings ;
1247     
1248     use Compress::Raw::Zlib;
1249     
1250     my $x = new Compress::Raw::Zlib::Inflate(LimitOutput => 1)
1251        or die "Cannot create a inflation stream\n" ;
1252     
1253     my $input = '' ;
1254     binmode STDIN;
1255     binmode STDOUT;
1256     
1257     my ($output, $status) ;
1258
1259   OUTER:
1260     while (read(STDIN, $input, 4096))
1261     {
1262         do
1263         {
1264             $status = $x->inflate($input, $output) ;
1265
1266             print $output ;
1267
1268             last OUTER
1269                 unless $status == Z_OK || $status == Z_BUF_ERROR ;
1270         }
1271         while ($status == Z_OK && length $input);
1272     }
1273     
1274     die "inflation failed\n"
1275         unless $status == Z_STREAM_END ;
1276
1277 =head1 CHECKSUM FUNCTIONS
1278
1279 Two functions are provided by I<zlib> to calculate checksums. For the
1280 Perl interface, the order of the two parameters in both functions has
1281 been reversed. This allows both running checksums and one off
1282 calculations to be done.
1283
1284     $crc = adler32($buffer [,$crc]) ;
1285     $crc = crc32($buffer [,$crc]) ;
1286
1287 The buffer parameters can either be a scalar or a scalar reference.
1288
1289 If the $crc parameters is C<undef>, the crc value will be reset.
1290
1291 If you have built this module with zlib 1.2.3 or better, two more
1292 CRC-related functions are available.
1293
1294     $crc = adler32_combine($crc1, $crc2, $len2)l
1295     $crc = crc32_combine($adler1, $adler2, $len2)
1296
1297 These functions allow checksums to be merged.
1298
1299 =head1 Misc
1300
1301 =head2 my $version = Compress::Raw::Zlib::zlib_version();
1302
1303 Returns the version of the zlib library.
1304
1305 =head2  my $flags = Compress::Raw::Zlib::zlibCompileFlags();
1306
1307 Returns the flags indicating compile-time options that were used to build 
1308 the zlib library. See the zlib documentation for a description of the flags
1309 returned by C<zlibCompileFlags>.
1310
1311 Note that when the zlib sources are built along with this module the
1312 C<sprintf> flags (bits 24, 25 and 26) should be ignored.
1313
1314 If you are using zlib 1.2.0 or older, C<zlibCompileFlags> will return 0. 
1315
1316 =head1 The LimitOutput option.
1317
1318 By default C<< $i->inflate($input, $output) >> will uncompress I<all> data
1319 in C<$input> and write I<all> of the uncompressed data it has generated to
1320 C<$output>. This makes the interface to C<inflate> much simpler - if the
1321 method has uncompressed C<$input> successfully I<all> compressed data in
1322 C<$input> will have been dealt with. So if you are reading from an input
1323 source and uncompressing as you go the code will look something like this
1324
1325     use strict ;
1326     use warnings ;
1327     
1328     use Compress::Raw::Zlib;
1329     
1330     my $x = new Compress::Raw::Zlib::Inflate()
1331        or die "Cannot create a inflation stream\n" ;
1332     
1333     my $input = '' ;
1334     
1335     my ($output, $status) ;
1336     while (read(STDIN, $input, 4096))
1337     {
1338         $status = $x->inflate($input, $output) ;
1339     
1340         print $output ;
1341     
1342         last if $status != Z_OK ;
1343     }
1344     
1345     die "inflation failed\n"
1346         unless $status == Z_STREAM_END ;
1347
1348 The points to note are 
1349
1350 =over 5
1351
1352 =item *
1353
1354 The main processing loop in the code handles reading of compressed data
1355 from STDIN.
1356
1357 =item *
1358
1359 The status code returned from C<inflate> will only trigger termination of
1360 the main processing loop if it isn't C<Z_OK>. When C<LimitOutput> has not
1361 been used the C<Z_OK> status means means that the end of the compressed
1362 data stream has been reached or there has been an error in uncompression.
1363
1364 =item *
1365
1366 After the call to C<inflate> I<all> of the uncompressed data in C<$input>
1367 will have been processed. This means the subsequent call to C<read> can
1368 overwrite it's contents without any problem.
1369
1370 =back
1371
1372 For most use-cases the behavior described above is acceptable (this module
1373 and it's predecessor, C<Compress::Zlib>, have used it for over 10 years
1374 without an issue), but in a few very specific use-cases the amount of
1375 memory required for C<$output> can prohibitively large. For example, if the
1376 compressed data stream contains the same pattern repeated thousands of
1377 times, a relatively small compressed data stream can uncompress into
1378 hundreds of megabytes.  Remember C<inflate> will keep allocating memory
1379 until I<all> the uncompressed data has been written to the output buffer -
1380 the size of C<$output> is unbounded. 
1381
1382 The C<LimitOutput> option is designed to help with this use-case.
1383
1384 The main difference in your code when using C<LimitOutput> is having to
1385 deal with cases where the C<$input> parameter still contains some
1386 uncompressed data that C<inflate> hasn't processed yet. The status code
1387 returned from C<inflate> will be C<Z_OK> if uncompression took place and
1388 C<Z_BUF_ERROR> if the output buffer is full.
1389
1390 Below is typical code that shows how to use C<LimitOutput>.
1391
1392     use strict ;
1393     use warnings ;
1394     
1395     use Compress::Raw::Zlib;
1396     
1397     my $x = new Compress::Raw::Zlib::Inflate(LimitOutput => 1)
1398        or die "Cannot create a inflation stream\n" ;
1399     
1400     my $input = '' ;
1401     binmode STDIN;
1402     binmode STDOUT;
1403     
1404     my ($output, $status) ;
1405
1406   OUTER:
1407     while (read(STDIN, $input, 4096))
1408     {
1409         do
1410         {
1411             $status = $x->inflate($input, $output) ;
1412
1413             print $output ;
1414
1415             last OUTER
1416                 unless $status == Z_OK || $status == Z_BUF_ERROR ;
1417         }
1418         while ($status == Z_OK && length $input);
1419     }
1420     
1421     die "inflation failed\n"
1422         unless $status == Z_STREAM_END ;
1423
1424 Points to note this time:
1425
1426 =over 5
1427
1428 =item *
1429
1430 There are now two nested loops in the code: the outer loop for reading the
1431 compressed data from STDIN, as before; and the inner loop to carry out the
1432 uncompression.
1433
1434 =item *
1435
1436 There are two exit points from the inner uncompression loop.
1437
1438 Firstly when C<inflate> has returned a status other than C<Z_OK> or
1439 C<Z_BUF_ERROR>.  This means that either the end of the compressed data
1440 stream has been reached (C<Z_STREAM_END>) or there is an error in the
1441 compressed data. In either of these cases there is no point in continuing
1442 with reading the compressed data, so both loops are terminated.
1443
1444 The second exit point tests if there is any data left in the input buffer,
1445 C<$input> - remember that the C<ConsumeInput> option is automatically
1446 enabled when C<LimitOutput> is used.  When the input buffer has been
1447 exhausted, the outer loop can run again and overwrite a now empty
1448 C<$input>.
1449
1450 =back
1451
1452 =head1 ACCESSING ZIP FILES
1453
1454 Although it is possible (with some effort on your part) to use this module
1455 to access .zip files, there are other perl modules available that will
1456 do all the hard work for you. Check out C<Archive::Zip>,
1457 C<IO::Compress::Zip> and C<IO::Uncompress::Unzip>.
1458
1459 =head1 FAQ
1460
1461 =head2 Compatibility with Unix compress/uncompress.
1462
1463 This module is not compatible with Unix C<compress>.
1464
1465 If you have the C<uncompress> program available, you can use this to read
1466 compressed files
1467
1468     open F, "uncompress -c $filename |";
1469     while (<F>)
1470     {
1471         ...
1472
1473 Alternatively, if you have the C<gunzip> program available, you can use
1474 this to read compressed files
1475
1476     open F, "gunzip -c $filename |";
1477     while (<F>)
1478     {
1479         ...
1480
1481 and this to write compress files, if you have the C<compress> program
1482 available
1483
1484     open F, "| compress -c $filename ";
1485     print F "data";
1486     ...
1487     close F ;
1488
1489 =head2 Accessing .tar.Z files
1490
1491 See previous FAQ item.
1492
1493 If the C<Archive::Tar> module is installed and either the C<uncompress> or
1494 C<gunzip> programs are available, you can use one of these workarounds to
1495 read C<.tar.Z> files.
1496
1497 Firstly with C<uncompress>
1498
1499     use strict;
1500     use warnings;
1501     use Archive::Tar;
1502
1503     open F, "uncompress -c $filename |";
1504     my $tar = Archive::Tar->new(*F);
1505     ...
1506
1507 and this with C<gunzip>
1508
1509     use strict;
1510     use warnings;
1511     use Archive::Tar;
1512
1513     open F, "gunzip -c $filename |";
1514     my $tar = Archive::Tar->new(*F);
1515     ...
1516
1517 Similarly, if the C<compress> program is available, you can use this to
1518 write a C<.tar.Z> file
1519
1520     use strict;
1521     use warnings;
1522     use Archive::Tar;
1523     use IO::File;
1524
1525     my $fh = new IO::File "| compress -c >$filename";
1526     my $tar = Archive::Tar->new();
1527     ...
1528     $tar->write($fh);
1529     $fh->close ;
1530
1531 =head2 Zlib Library Version Support
1532
1533 By default C<Compress::Raw::Zlib> will build with a private copy of version
1534 1.2.5 of the zlib library. (See the F<README> file for details of
1535 how to override this behaviour)
1536
1537 If you decide to use a different version of the zlib library, you need to be
1538 aware of the following issues
1539
1540 =over 5
1541
1542 =item *
1543
1544 First off, you must have zlib 1.0.5 or better.
1545
1546 =item *
1547
1548 You need to have zlib 1.2.1 or better if you want to use the C<-Merge>
1549 option with C<IO::Compress::Gzip>, C<IO::Compress::Deflate> and
1550 C<IO::Compress::RawDeflate>.
1551
1552 =back
1553
1554 =head1 CONSTANTS
1555
1556 All the I<zlib> constants are automatically imported when you make use
1557 of I<Compress::Raw::Zlib>.
1558
1559 =head1 SEE ALSO
1560
1561 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::Lzma>, L<IO::Uncompress::UnLzma>, L<IO::Compress::Xz>, L<IO::Uncompress::UnXz>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
1562
1563 L<IO::Compress::FAQ|IO::Compress::FAQ>
1564
1565 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1566 L<Archive::Tar|Archive::Tar>,
1567 L<IO::Zlib|IO::Zlib>
1568
1569 For RFC 1950, 1951 and 1952 see 
1570 F<http://www.faqs.org/rfcs/rfc1950.html>,
1571 F<http://www.faqs.org/rfcs/rfc1951.html> and
1572 F<http://www.faqs.org/rfcs/rfc1952.html>
1573
1574 The I<zlib> compression library was written by Jean-loup Gailly
1575 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1576
1577 The primary site for the I<zlib> compression library is
1578 F<http://www.zlib.org>.
1579
1580 The primary site for gzip is F<http://www.gzip.org>.
1581
1582 =head1 AUTHOR
1583
1584 This module was written by Paul Marquess, F<pmqs@cpan.org>. 
1585
1586 =head1 MODIFICATION HISTORY
1587
1588 See the Changes file.
1589
1590 =head1 COPYRIGHT AND LICENSE
1591
1592 Copyright (c) 2005-2012 Paul Marquess. All rights reserved.
1593
1594 This program is free software; you can redistribute it and/or
1595 modify it under the same terms as Perl itself.
1596