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