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