ext/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.011';
  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_UNKNOWN
  64         Z_VERSION_ERROR
  65 );
  66
  67
  68 sub AUTOLOAD {
  69     my($constname);
  70     ($constname = $AUTOLOAD) =~ s/.*:://;
  71     my ($error, $val) = constant($constname);
  72     Carp::croak $error if $error;
  73     no strict 'refs';
  74     *{$AUTOLOAD} = sub { $val };
  75     goto &{$AUTOLOAD};
  76 }
  77
  78 use constant FLAG_APPEND             => 1 ;
  79 use constant FLAG_CRC                => 2 ;
  80 use constant FLAG_ADLER              => 4 ;
  81 use constant FLAG_CONSUME_INPUT      => 8 ;
  82
  83 eval {
  84     require XSLoader;
  85     XSLoader::load('Compress::Raw::Zlib', $XS_VERSION);
  86     1;
  87 }
  88 or do {
  89     require DynaLoader;
  90     local @ISA = qw(DynaLoader);
  91     bootstrap Compress::Raw::Zlib $XS_VERSION ;
  92 };
  93
  94
  95 use constant Parse_any      => 0x01;
  96 use constant Parse_unsigned => 0x02;
  97 use constant Parse_signed   => 0x04;
  98 use constant Parse_boolean  => 0x08;
  99 use constant Parse_string   => 0x10;
 100 use constant Parse_custom   => 0x12;
 101
 102 use constant Parse_store_ref => 0x100 ;
 103
 104 use constant OFF_PARSED     => 0 ;
 105 use constant OFF_TYPE       => 1 ;
 106 use constant OFF_DEFAULT    => 2 ;
 107 use constant OFF_FIXED      => 3 ;
 108 use constant OFF_FIRST_ONLY => 4 ;
 109 use constant OFF_STICKY     => 5 ;
 110
 111
 112
 113 sub ParseParameters
 114 {
 115     my $level = shift || 0 ;
 116
 117     my $sub = (caller($level + 1))[3] ;
 118     #local $Carp::CarpLevel = 1 ;
 119     my $p = new Compress::Raw::Zlib::Parameters() ;
 120     $p->parse(@_)
 121         or croak "$sub: $p->{Error}" ;
 122
 123     return $p;
 124 }
 125
 126
 127 sub Compress::Raw::Zlib::Parameters::new
 128 {
 129     my $class = shift ;
 130
 131     my $obj = { Error => '',
 132                 Got   => {},
 133               } ;
 134
 135     #return bless $obj, ref($class) || $class || __PACKAGE__ ;
 136     return bless $obj, 'Compress::Raw::Zlib::Parameters' ;
 137 }
 138
 139 sub Compress::Raw::Zlib::Parameters::setError
 140 {
 141     my $self = shift ;
 142     my $error = shift ;
 143     my $retval = @_ ? shift : undef ;
 144
 145     $self->{Error} = $error ;
 146     return $retval;
 147 }
 148
 149 #sub getError
 150 #{
 151 #    my $self = shift ;
 152 #    return $self->{Error} ;
 153 #}
 154
 155 sub Compress::Raw::Zlib::Parameters::parse
 156 {
 157     my $self = shift ;
 158
 159     my $default = shift ;
 160
 161     my $got = $self->{Got} ;
 162     my $firstTime = keys %{ $got } == 0 ;
 163
 164     my (@Bad) ;
 165     my @entered = () ;
 166
 167     # Allow the options to be passed as a hash reference or
 168     # as the complete hash.
 169     if (@_ == 0) {
 170         @entered = () ;
 171     }
 172     elsif (@_ == 1) {
 173         my $href = $_[0] ;
 174         return $self->setError("Expected even number of parameters, got 1")
 175             if ! defined $href or ! ref $href or ref $href ne "HASH" ;
 176
 177         foreach my $key (keys %$href) {
 178             push @entered, $key ;
 179             push @entered, \$href->{$key} ;
 180         }
 181     }
 182     else {
 183         my $count = @_;
 184         return $self->setError("Expected even number of parameters, got $count")
 185             if $count % 2 != 0 ;
 186
 187         for my $i (0.. $count / 2 - 1) {
 188             push @entered, $_[2* $i] ;
 189             push @entered, \$_[2* $i+1] ;
 190         }
 191     }
 192
 193
 194     while (my ($key, $v) = each %$default)
 195     {
 196         croak "need 4 params [@$v]"
 197             if @$v != 4 ;
 198
 199         my ($first_only, $sticky, $type, $value) = @$v ;
 200         my $x ;
 201         $self->_checkType($key, \$value, $type, 0, \$x)
 202             or return undef ;
 203
 204         $key = lc $key;
 205
 206         if ($firstTime || ! $sticky) {
 207             $got->{$key} = [0, $type, $value, $x, $first_only, $sticky] ;
 208         }
 209
 210         $got->{$key}[OFF_PARSED] = 0 ;
 211     }
 212
 213     for my $i (0.. @entered / 2 - 1) {
 214         my $key = $entered[2* $i] ;
 215         my $value = $entered[2* $i+1] ;
 216
 217         #print "Key [$key] Value [$value]" ;
 218         #print defined $$value ? "[$$value]\n" : "[undef]\n";
 219
 220         $key =~ s/^-// ;
 221         my $canonkey = lc $key;
 222
 223         if ($got->{$canonkey} && ($firstTime ||
 224                                   ! $got->{$canonkey}[OFF_FIRST_ONLY]  ))
 225         {
 226             my $type = $got->{$canonkey}[OFF_TYPE] ;
 227             my $s ;
 228             $self->_checkType($key, $value, $type, 1, \$s)
 229                 or return undef ;
 230             #$value = $$value unless $type & Parse_store_ref ;
 231             $value = $$value ;
 232             $got->{$canonkey} = [1, $type, $value, $s] ;
 233         }
 234         else
 235           { push (@Bad, $key) }
 236     }
 237
 238     if (@Bad) {
 239         my ($bad) = join(", ", @Bad) ;
 240         return $self->setError("unknown key value(s) @Bad") ;
 241     }
 242
 243     return 1;
 244 }
 245
 246 sub Compress::Raw::Zlib::Parameters::_checkType
 247 {
 248     my $self = shift ;
 249
 250     my $key   = shift ;
 251     my $value = shift ;
 252     my $type  = shift ;
 253     my $validate  = shift ;
 254     my $output  = shift;
 255
 256     #local $Carp::CarpLevel = $level ;
 257     #print "PARSE $type $key $value $validate $sub\n" ;
 258     if ( $type & Parse_store_ref)
 259     {
 260         #$value = $$value
 261         #    if ref ${ $value } ;
 262
 263         $$output = $value ;
 264         return 1;
 265     }
 266
 267     $value = $$value ;
 268
 269     if ($type & Parse_any)
 270     {
 271         $$output = $value ;
 272         return 1;
 273     }
 274     elsif ($type & Parse_unsigned)
 275     {
 276         return $self->setError("Parameter '$key' must be an unsigned int, got 'undef'")
 277             if $validate && ! defined $value ;
 278         return $self->setError("Parameter '$key' must be an unsigned int, got '$value'")
 279             if $validate && $value !~ /^\d+$/;
 280
 281         $$output = defined $value ? $value : 0 ;
 282         return 1;
 283     }
 284     elsif ($type & Parse_signed)
 285     {
 286         return $self->setError("Parameter '$key' must be a signed int, got 'undef'")
 287             if $validate && ! defined $value ;
 288         return $self->setError("Parameter '$key' must be a signed int, got '$value'")
 289             if $validate && $value !~ /^-?\d+$/;
 290
 291         $$output = defined $value ? $value : 0 ;
 292         return 1 ;
 293     }
 294     elsif ($type & Parse_boolean)
 295     {
 296         return $self->setError("Parameter '$key' must be an int, got '$value'")
 297             if $validate && defined $value && $value !~ /^\d*$/;
 298         $$output =  defined $value ? $value != 0 : 0 ;
 299         return 1;
 300     }
 301     elsif ($type & Parse_string)
 302     {
 303         $$output = defined $value ? $value : "" ;
 304         return 1;
 305     }
 306
 307     $$output = $value ;
 308     return 1;
 309 }
 310
 311
 312
 313 sub Compress::Raw::Zlib::Parameters::parsed
 314 {
 315     my $self = shift ;
 316     my $name = shift ;
 317
 318     return $self->{Got}{lc $name}[OFF_PARSED] ;
 319 }
 320
 321 sub Compress::Raw::Zlib::Parameters::value
 322 {
 323     my $self = shift ;
 324     my $name = shift ;
 325
 326     if (@_)
 327     {
 328         $self->{Got}{lc $name}[OFF_PARSED]  = 1;
 329         $self->{Got}{lc $name}[OFF_DEFAULT] = $_[0] ;
 330         $self->{Got}{lc $name}[OFF_FIXED]   = $_[0] ;
 331     }
 332
 333     return $self->{Got}{lc $name}[OFF_FIXED] ;
 334 }
 335
 336 sub Compress::Raw::Zlib::Deflate::new
 337 {
 338     my $pkg = shift ;
 339     my ($got) = ParseParameters(0,
 340             {
 341                 'AppendOutput'  => [1, 1, Parse_boolean,  0],
 342                 'CRC32'         => [1, 1, Parse_boolean,  0],
 343                 'ADLER32'       => [1, 1, Parse_boolean,  0],
 344                 'Bufsize'       => [1, 1, Parse_unsigned, 4096],
 345
 346                 'Level'         => [1, 1, Parse_signed,   Z_DEFAULT_COMPRESSION()],
 347                 'Method'        => [1, 1, Parse_unsigned, Z_DEFLATED()],
 348                 'WindowBits'    => [1, 1, Parse_signed,   MAX_WBITS()],
 349                 'MemLevel'      => [1, 1, Parse_unsigned, MAX_MEM_LEVEL()],
 350                 'Strategy'      => [1, 1, Parse_unsigned, Z_DEFAULT_STRATEGY()],
 351                 'Dictionary'    => [1, 1, Parse_any,      ""],
 352             }, @_) ;
 353
 354
 355     croak "Compress::Raw::Zlib::Deflate::new: Bufsize must be >= 1, you specified " .
 356             $got->value('Bufsize')
 357         unless $got->value('Bufsize') >= 1;
 358
 359     my $flags = 0 ;
 360     $flags |= FLAG_APPEND if $got->value('AppendOutput') ;
 361     $flags |= FLAG_CRC    if $got->value('CRC32') ;
 362     $flags |= FLAG_ADLER  if $got->value('ADLER32') ;
 363
 364     _deflateInit($flags,
 365                 $got->value('Level'),
 366                 $got->value('Method'),
 367                 $got->value('WindowBits'),
 368                 $got->value('MemLevel'),
 369                 $got->value('Strategy'),
 370                 $got->value('Bufsize'),
 371                 $got->value('Dictionary')) ;
 372
 373 }
 374
 375 sub Compress::Raw::Zlib::Inflate::new
 376 {
 377     my $pkg = shift ;
 378     my ($got) = ParseParameters(0,
 379                     {
 380                         'AppendOutput'  => [1, 1, Parse_boolean,  0],
 381                         'CRC32'         => [1, 1, Parse_boolean,  0],
 382                         'ADLER32'       => [1, 1, Parse_boolean,  0],
 383                         'ConsumeInput'  => [1, 1, Parse_boolean,  1],
 384                         'Bufsize'       => [1, 1, Parse_unsigned, 4096],
 385
 386                         'WindowBits'    => [1, 1, Parse_signed,   MAX_WBITS()],
 387                         'Dictionary'    => [1, 1, Parse_any,      ""],
 388             }, @_) ;
 389
 390
 391     croak "Compress::Raw::Zlib::Inflate::new: Bufsize must be >= 1, you specified " .
 392             $got->value('Bufsize')
 393         unless $got->value('Bufsize') >= 1;
 394
 395     my $flags = 0 ;
 396     $flags |= FLAG_APPEND if $got->value('AppendOutput') ;
 397     $flags |= FLAG_CRC    if $got->value('CRC32') ;
 398     $flags |= FLAG_ADLER  if $got->value('ADLER32') ;
 399     $flags |= FLAG_CONSUME_INPUT if $got->value('ConsumeInput') ;
 400
 401     _inflateInit($flags, $got->value('WindowBits'), $got->value('Bufsize'),
 402                  $got->value('Dictionary')) ;
 403 }
 404
 405 sub Compress::Raw::Zlib::InflateScan::new
 406 {
 407     my $pkg = shift ;
 408     my ($got) = ParseParameters(0,
 409                     {
 410                         'CRC32'         => [1, 1, Parse_boolean,  0],
 411                         'ADLER32'       => [1, 1, Parse_boolean,  0],
 412                         'Bufsize'       => [1, 1, Parse_unsigned, 4096],
 413
 414                         'WindowBits'    => [1, 1, Parse_signed,   -MAX_WBITS()],
 415                         'Dictionary'    => [1, 1, Parse_any,      ""],
 416             }, @_) ;
 417
 418
 419     croak "Compress::Raw::Zlib::InflateScan::new: Bufsize must be >= 1, you specified " .
 420             $got->value('Bufsize')
 421         unless $got->value('Bufsize') >= 1;
 422
 423     my $flags = 0 ;
 424     #$flags |= FLAG_APPEND if $got->value('AppendOutput') ;
 425     $flags |= FLAG_CRC    if $got->value('CRC32') ;
 426     $flags |= FLAG_ADLER  if $got->value('ADLER32') ;
 427     #$flags |= FLAG_CONSUME_INPUT if $got->value('ConsumeInput') ;
 428
 429     _inflateScanInit($flags, $got->value('WindowBits'), $got->value('Bufsize'),
 430                  '') ;
 431 }
 432
 433 sub Compress::Raw::Zlib::inflateScanStream::createDeflateStream
 434 {
 435     my $pkg = shift ;
 436     my ($got) = ParseParameters(0,
 437             {
 438                 'AppendOutput'  => [1, 1, Parse_boolean,  0],
 439                 'CRC32'         => [1, 1, Parse_boolean,  0],
 440                 'ADLER32'       => [1, 1, Parse_boolean,  0],
 441                 'Bufsize'       => [1, 1, Parse_unsigned, 4096],
 442
 443                 'Level'         => [1, 1, Parse_signed,   Z_DEFAULT_COMPRESSION()],
 444                 'Method'        => [1, 1, Parse_unsigned, Z_DEFLATED()],
 445                 'WindowBits'    => [1, 1, Parse_signed,   - MAX_WBITS()],
 446                 'MemLevel'      => [1, 1, Parse_unsigned, MAX_MEM_LEVEL()],
 447                 'Strategy'      => [1, 1, Parse_unsigned, Z_DEFAULT_STRATEGY()],
 448             }, @_) ;
 449
 450     croak "Compress::Raw::Zlib::InflateScan::createDeflateStream: Bufsize must be >= 1, you specified " .
 451             $got->value('Bufsize')
 452         unless $got->value('Bufsize') >= 1;
 453
 454     my $flags = 0 ;
 455     $flags |= FLAG_APPEND if $got->value('AppendOutput') ;
 456     $flags |= FLAG_CRC    if $got->value('CRC32') ;
 457     $flags |= FLAG_ADLER  if $got->value('ADLER32') ;
 458
 459     $pkg->_createDeflateStream($flags,
 460                 $got->value('Level'),
 461                 $got->value('Method'),
 462                 $got->value('WindowBits'),
 463                 $got->value('MemLevel'),
 464                 $got->value('Strategy'),
 465                 $got->value('Bufsize'),
 466                 ) ;
 467
 468 }
 469
 470 sub Compress::Raw::Zlib::inflateScanStream::inflate
 471 {
 472     my $self = shift ;
 473     my $buffer = $_[1];
 474     my $eof = $_[2];
 475
 476     my $status = $self->scan(@_);
 477
 478     if ($status == Z_OK() && $_[2]) {
 479         my $byte = ' ';
 480
 481         $status = $self->scan(\$byte, $_[1]) ;
 482     }
 483
 484     return $status ;
 485 }
 486
 487 sub Compress::Raw::Zlib::deflateStream::deflateParams
 488 {
 489     my $self = shift ;
 490     my ($got) = ParseParameters(0, {
 491                 'Level'      => [1, 1, Parse_signed,   undef],
 492                 'Strategy'   => [1, 1, Parse_unsigned, undef],
 493                 'Bufsize'    => [1, 1, Parse_unsigned, undef],
 494                 },
 495                 @_) ;
 496
 497     croak "Compress::Raw::Zlib::deflateParams needs Level and/or Strategy"
 498         unless $got->parsed('Level') + $got->parsed('Strategy') +
 499             $got->parsed('Bufsize');
 500
 501     croak "Compress::Raw::Zlib::Inflate::deflateParams: Bufsize must be >= 1, you specified " .
 502             $got->value('Bufsize')
 503         if $got->parsed('Bufsize') && $got->value('Bufsize') <= 1;
 504
 505     my $flags = 0;
 506     $flags |= 1 if $got->parsed('Level') ;
 507     $flags |= 2 if $got->parsed('Strategy') ;
 508     $flags |= 4 if $got->parsed('Bufsize') ;
 509
 510     $self->_deflateParams($flags, $got->value('Level'),
 511                           $got->value('Strategy'), $got->value('Bufsize'));
 512
 513 }
 514
 515
 516 # Autoload methods go after __END__, and are processed by the autosplit program.
 517
 518 1;
 519 __END__
 520
 521
 522 =head1 NAME
 523
 524 Compress::Raw::Zlib - Low-Level Interface to zlib compression library
 525
 526 =head1 SYNOPSIS
 527
 528     use Compress::Raw::Zlib ;
 529
 530     ($d, $status) = new Compress::Raw::Zlib::Deflate( [OPT] ) ;
 531     $status = $d->deflate($input, $output) ;
 532     $status = $d->flush($output [, $flush_type]) ;
 533     $d->deflateParams(OPTS) ;
 534     $d->deflateTune(OPTS) ;
 535     $d->dict_adler() ;
 536     $d->crc32() ;
 537     $d->adler32() ;
 538     $d->total_in() ;
 539     $d->total_out() ;
 540     $d->msg() ;
 541     $d->get_Strategy();
 542     $d->get_Level();
 543     $d->get_BufSize();
 544
 545     ($i, $status) = new Compress::Raw::Zlib::Inflate( [OPT] ) ;
 546     $status = $i->inflate($input, $output [, $eof]) ;
 547     $status = $i->inflateSync($input) ;
 548     $i->dict_adler() ;
 549     $d->crc32() ;
 550     $d->adler32() ;
 551     $i->total_in() ;
 552     $i->total_out() ;
 553     $i->msg() ;
 554     $d->get_BufSize();
 555
 556     $crc = adler32($buffer [,$crc]) ;
 557     $crc = crc32($buffer [,$crc]) ;
 558
 559     $crc = adler32_combine($crc1, $crc2, $len2)l
 560     $crc = crc32_combine($adler1, $adler2, $len2)
 561
 562     ZLIB_VERSION
 563     ZLIB_VERNUM
 564
 565 =head1 DESCRIPTION
 566
 567 The I<Compress::Raw::Zlib> module provides a Perl interface to the I<zlib>
 568 compression library (see L</AUTHOR> for details about where to get
 569 I<zlib>).
 570
 571 =head1 Compress::Raw::Zlib::Deflate
 572
 573 This section defines an interface that allows in-memory compression using
 574 the I<deflate> interface provided by zlib.
 575
 576 Here is a definition of the interface available:
 577
 578 =head2 B<($d, $status) = new Compress::Raw::Zlib::Deflate( [OPT] ) >
 579
 580 Initialises a deflation object.
 581
 582 If you are familiar with the I<zlib> library, it combines the
 583 features of the I<zlib> functions C<deflateInit>, C<deflateInit2>
 584 and C<deflateSetDictionary>.
 585
 586 If successful, it will return the initialised deflation object, C<$d>
 587 and a C<$status> of C<Z_OK> in a list context. In scalar context it
 588 returns the deflation object, C<$d>, only.
 589
 590 If not successful, the returned deflation object, C<$d>, will be
 591 I<undef> and C<$status> will hold the a I<zlib> error code.
 592
 593 The function optionally takes a number of named options specified as
 594 C<< Name => value >> pairs. This allows individual options to be
 595 tailored without having to specify them all in the parameter list.
 596
 597 For backward compatibility, it is also possible to pass the parameters
 598 as a reference to a hash containing the name=>value pairs.
 599
 600 Below is a list of the valid options:
 601
 602 =over 5
 603
 604 =item B<-Level>
 605
 606 Defines the compression level. Valid values are 0 through 9,
 607 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
 608 C<Z_DEFAULT_COMPRESSION>.
 609
 610 The default is Z_DEFAULT_COMPRESSION.
 611
 612 =item B<-Method>
 613
 614 Defines the compression method. The only valid value at present (and
 615 the default) is Z_DEFLATED.
 616
 617 =item B<-WindowBits>
 618
 619 For a definition of the meaning and valid values for C<WindowBits>
 620 refer to the I<zlib> documentation for I<deflateInit2>.
 621
 622 Defaults to MAX_WBITS.
 623
 624 =item B<-MemLevel>
 625
 626 For a definition of the meaning and valid values for C<MemLevel>
 627 refer to the I<zlib> documentation for I<deflateInit2>.
 628
 629 Defaults to MAX_MEM_LEVEL.
 630
 631 =item B<-Strategy>
 632
 633 Defines the strategy used to tune the compression. The valid values are
 634 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED>, C<Z_RLE>, C<Z_FIXED> and
 635 C<Z_HUFFMAN_ONLY>.
 636
 637 The default is Z_DEFAULT_STRATEGY.
 638
 639 =item B<-Dictionary>
 640
 641 When a dictionary is specified I<Compress::Raw::Zlib> will automatically
 642 call C<deflateSetDictionary> directly after calling C<deflateInit>. The
 643 Adler32 value for the dictionary can be obtained by calling the method
 644 C<$d-E<gt>dict_adler()>.
 645
 646 The default is no dictionary.
 647
 648 =item B<-Bufsize>
 649
 650 Sets the initial size for the output buffer used by the C<$d-E<gt>deflate>
 651 and C<$d-E<gt>flush> methods. If the buffer has to be
 652 reallocated to increase the size, it will grow in increments of
 653 C<Bufsize>.
 654
 655 The default buffer size is 4096.
 656
 657 =item B<-AppendOutput>
 658
 659 This option controls how data is written to the output buffer by the
 660 C<$d-E<gt>deflate> and C<$d-E<gt>flush> methods.
 661
 662 If the C<AppendOutput> option is set to false, the output buffers in the
 663 C<$d-E<gt>deflate> and C<$d-E<gt>flush>  methods will be truncated before
 664 uncompressed data is written to them.
 665
 666 If the option is set to true, uncompressed data will be appended to the
 667 output buffer in the C<$d-E<gt>deflate> and C<$d-E<gt>flush> methods.
 668
 669 This option defaults to false.
 670
 671 =item B<-CRC32>
 672
 673 If set to true, a crc32 checksum of the uncompressed data will be
 674 calculated. Use the C<$d-E<gt>crc32> method to retrieve this value.
 675
 676 This option defaults to false.
 677
 678 =item B<-ADLER32>
 679
 680 If set to true, an adler32 checksum of the uncompressed data will be
 681 calculated. Use the C<$d-E<gt>adler32> method to retrieve this value.
 682
 683 This option defaults to false.
 684
 685 =back
 686
 687 Here is an example of using the C<Compress::Raw::Zlib::Deflate> optional
 688 parameter list to override the default buffer size and compression
 689 level. All other options will take their default values.
 690
 691     my $d = new Compress::Raw::Zlib::Deflate ( -Bufsize => 300,
 692                                                -Level   => Z_BEST_SPEED ) ;
 693
 694 =head2 B<$status = $d-E<gt>deflate($input, $output)>
 695
 696 Deflates the contents of C<$input> and writes the compressed data to
 697 C<$output>.
 698
 699 The C<$input> and C<$output> parameters can be either scalars or scalar
 700 references.
 701
 702 When finished, C<$input> will be completely processed (assuming there
 703 were no errors). If the deflation was successful it writes the deflated
 704 data to C<$output> and returns a status value of C<Z_OK>.
 705
 706 On error, it returns a I<zlib> error code.
 707
 708 If the C<AppendOutput> option is set to true in the constructor for
 709 the C<$d> object, the compressed data will be appended to C<$output>. If
 710 it is false, C<$output> will be truncated before any compressed data is
 711 written to it.
 712
 713 B<Note>: This method will not necessarily write compressed data to
 714 C<$output> every time it is called. So do not assume that there has been
 715 an error if the contents of C<$output> is empty on returning from
 716 this method. As long as the return code from the method is C<Z_OK>,
 717 the deflate has succeeded.
 718
 719 =head2 B<$status = $d-E<gt>flush($output [, $flush_type]) >
 720
 721 Typically used to finish the deflation. Any pending output will be
 722 written to C<$output>.
 723
 724 Returns C<Z_OK> if successful.
 725
 726 Note that flushing can seriously degrade the compression ratio, so it
 727 should only be used to terminate a decompression (using C<Z_FINISH>) or
 728 when you want to create a I<full flush point> (using C<Z_FULL_FLUSH>).
 729
 730 By default the C<flush_type> used is C<Z_FINISH>. Other valid values
 731 for C<flush_type> are C<Z_NO_FLUSH>, C<Z_PARTIAL_FLUSH>, C<Z_SYNC_FLUSH>
 732 and C<Z_FULL_FLUSH>. It is strongly recommended that you only set the
 733 C<flush_type> parameter if you fully understand the implications of
 734 what it does. See the C<zlib> documentation for details.
 735
 736 If the C<AppendOutput> option is set to true in the constructor for
 737 the C<$d> object, the compressed data will be appended to C<$output>. If
 738 it is false, C<$output> will be truncated before any compressed data is
 739 written to it.
 740
 741 =head2 B<$status = $d-E<gt>deflateParams([OPT])>
 742
 743 Change settings for the deflate object C<$d>.
 744
 745 The list of the valid options is shown below. Options not specified
 746 will remain unchanged.
 747
 748 =over 5
 749
 750 =item B<-Level>
 751
 752 Defines the compression level. Valid values are 0 through 9,
 753 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
 754 C<Z_DEFAULT_COMPRESSION>.
 755
 756 =item B<-Strategy>
 757
 758 Defines the strategy used to tune the compression. The valid values are
 759 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
 760
 761 =item B<-BufSize>
 762
 763 Sets the initial size for the output buffer used by the C<$d-E<gt>deflate>
 764 and C<$d-E<gt>flush> methods. If the buffer has to be
 765 reallocated to increase the size, it will grow in increments of
 766 C<Bufsize>.
 767
 768 =back
 769
 770 =head2 B<$status = $d-E<gt>deflateTune($good_length, $max_lazy, $nice_length, $max_chain)>
 771
 772 Tune the internal settings for the deflate object C<$d>. This option is
 773 only available if you are running zlib 1.2.2.3 or better.
 774
 775 Refer to the documentation in zlib.h for instructions on how to fly
 776 C<deflateTune>.
 777
 778 =head2 B<$d-E<gt>dict_adler()>
 779
 780 Returns the adler32 value for the dictionary.
 781
 782 =head2 B<$d-E<gt>crc32()>
 783
 784 Returns the crc32 value for the uncompressed data to date.
 785
 786 If the C<CRC32> option is not enabled in the constructor for this object,
 787 this method will always return 0;
 788
 789 =head2 B<$d-E<gt>adler32()>
 790
 791 Returns the adler32 value for the uncompressed data to date.
 792
 793 =head2 B<$d-E<gt>msg()>
 794
 795 Returns the last error message generated by zlib.
 796
 797 =head2 B<$d-E<gt>total_in()>
 798
 799 Returns the total number of bytes uncompressed bytes input to deflate.
 800
 801 =head2 B<$d-E<gt>total_out()>
 802
 803 Returns the total number of compressed bytes output from deflate.
 804
 805 =head2 B<$d-E<gt>get_Strategy()>
 806
 807 Returns the deflation strategy currently used. Valid values are
 808 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
 809
 810 =head2 B<$d-E<gt>get_Level()>
 811
 812 Returns the compression level being used.
 813
 814 =head2 B<$d-E<gt>get_BufSize()>
 815
 816 Returns the buffer size used to carry out the compression.
 817
 818 =head2 Example
 819
 820 Here is a trivial example of using C<deflate>. It simply reads standard
 821 input, deflates it and writes it to standard output.
 822
 823     use strict ;
 824     use warnings ;
 825
 826     use Compress::Raw::Zlib ;
 827
 828     binmode STDIN;
 829     binmode STDOUT;
 830     my $x = new Compress::Raw::Zlib::Deflate
 831        or die "Cannot create a deflation stream\n" ;
 832
 833     my ($output, $status) ;
 834     while (<>)
 835     {
 836         $status = $x->deflate($_, $output) ;
 837
 838         $status == Z_OK
 839             or die "deflation failed\n" ;
 840
 841         print $output ;
 842     }
 843
 844     $status = $x->flush($output) ;
 845
 846     $status == Z_OK
 847         or die "deflation failed\n" ;
 848
 849     print $output ;
 850
 851 =head1 Compress::Raw::Zlib::Inflate
 852
 853 This section defines an interface that allows in-memory uncompression using
 854 the I<inflate> interface provided by zlib.
 855
 856 Here is a definition of the interface:
 857
 858 =head2 B< ($i, $status) = new Compress::Raw::Zlib::Inflate( [OPT] ) >
 859
 860 Initialises an inflation object.
 861
 862 In a list context it returns the inflation object, C<$i>, and the
 863 I<zlib> status code (C<$status>). In a scalar context it returns the
 864 inflation object only.
 865
 866 If successful, C<$i> will hold the inflation object and C<$status> will
 867 be C<Z_OK>.
 868
 869 If not successful, C<$i> will be I<undef> and C<$status> will hold the
 870 I<zlib> error code.
 871
 872 The function optionally takes a number of named options specified as
 873 C<< -Name => value >> pairs. This allows individual options to be
 874 tailored without having to specify them all in the parameter list.
 875
 876 For backward compatibility, it is also possible to pass the parameters
 877 as a reference to a hash containing the C<< name=>value >> pairs.
 878
 879 Here is a list of the valid options:
 880
 881 =over 5
 882
 883 =item B<-WindowBits>
 884
 885 To uncompress an RFC 1950 data stream, set C<WindowBits> to a positive
 886 number.
 887
 888 To uncompress an RFC 1951 data stream, set C<WindowBits> to C<-MAX_WBITS>.
 889
 890 For a full definition of the meaning and valid values for C<WindowBits>
 891 refer to the I<zlib> documentation for I<inflateInit2>.
 892
 893 Defaults to MAX_WBITS.
 894
 895 =item B<-Bufsize>
 896
 897 Sets the initial size for the output buffer used by the C<$i-E<gt>inflate>
 898 method. If the output buffer in this method has to be reallocated to
 899 increase the size, it will grow in increments of C<Bufsize>.
 900
 901 Default is 4096.
 902
 903 =item B<-Dictionary>
 904
 905 The default is no dictionary.
 906
 907 =item B<-AppendOutput>
 908
 909 This option controls how data is written to the output buffer by the
 910 C<$i-E<gt>inflate> method.
 911
 912 If the option is set to false, the output buffer in the C<$i-E<gt>inflate>
 913 method will be truncated before uncompressed data is written to it.
 914
 915 If the option is set to true, uncompressed data will be appended to the
 916 output buffer by the C<$i-E<gt>inflate> method.
 917
 918 This option defaults to false.
 919
 920 =item B<-CRC32>
 921
 922 If set to true, a crc32 checksum of the uncompressed data will be
 923 calculated. Use the C<$i-E<gt>crc32> method to retrieve this value.
 924
 925 This option defaults to false.
 926
 927 =item B<-ADLER32>
 928
 929 If set to true, an adler32 checksum of the uncompressed data will be
 930 calculated. Use the C<$i-E<gt>adler32> method to retrieve this value.
 931
 932 This option defaults to false.
 933
 934 =item B<-ConsumeInput>
 935
 936 If set to true, this option will remove compressed data from the input
 937 buffer of the the C< $i-E<gt>inflate > method as the inflate progresses.
 938
 939 This option can be useful when you are processing compressed data that is
 940 embedded in another file/buffer. In this case the data that immediately
 941 follows the compressed stream will be left in the input buffer.
 942
 943 This option defaults to true.
 944
 945 =back
 946
 947 Here is an example of using an optional parameter to override the default
 948 buffer size.
 949
 950     my ($i, $status) = new Compress::Raw::Zlib::Inflate( -Bufsize => 300 ) ;
 951
 952 =head2 B< $status = $i-E<gt>inflate($input, $output [,$eof]) >
 953
 954 Inflates the complete contents of C<$input> and writes the uncompressed
 955 data to C<$output>. The C<$input> and C<$output> parameters can either be
 956 scalars or scalar references.
 957
 958 Returns C<Z_OK> if successful and C<Z_STREAM_END> if the end of the
 959 compressed data has been successfully reached.
 960
 961 If not successful C<$status> will hold the I<zlib> error code.
 962
 963 If the C<ConsumeInput> option has been set to true when the
 964 C<Compress::Raw::Zlib::Inflate> object is created, the C<$input> parameter
 965 is modified by C<inflate>. On completion it will contain what remains
 966 of the input buffer after inflation. In practice, this means that when
 967 the return status is C<Z_OK> the C<$input> parameter will contain an
 968 empty string, and when the return status is C<Z_STREAM_END> the C<$input>
 969 parameter will contains what (if anything) was stored in the input buffer
 970 after the deflated data stream.
 971
 972 This feature is useful when processing a file format that encapsulates
 973 a compressed data stream (e.g. gzip, zip) and there is useful data
 974 immediately after the deflation stream.
 975
 976 If the C<AppendOutput> option is set to true in the constructor for
 977 this object, the uncompressed data will be appended to C<$output>. If
 978 it is false, C<$output> will be truncated before any uncompressed data
 979 is written to it.
 980
 981 The C<$eof> parameter needs a bit of explanation.
 982
 983 Prior to version 1.2.0, zlib assumed that there was at least one trailing
 984 byte immediately after the compressed data stream when it was carrying out
 985 decompression. This normally isn't a problem because the majority of zlib
 986 applications guarantee that there will be data directly after the
 987 compressed data stream.  For example, both gzip (RFC 1950) and zip both
 988 define trailing data that follows the compressed data stream.
 989
 990 The C<$eof> parameter only needs to be used if B<all> of the following
 991 conditions apply
 992
 993 =over 5
 994
 995 =item 1
 996
 997 You are either using a copy of zlib that is older than version 1.2.0 or you
 998 want your application code to be able to run with as many different
 999 versions of zlib as possible.
1000
1001 =item 2
1002
1003 You have set the C<WindowBits> parameter to C<-MAX_WBITS> in the constructor
1004 for this object, i.e. you are uncompressing a raw deflated data stream
1005 (RFC 1951).
1006
1007 =item 3
1008
1009 There is no data immediately after the compressed data stream.
1010
1011 =back
1012
1013 If B<all> of these are the case, then you need to set the C<$eof> parameter
1014 to true on the final call (and only the final call) to C<$i-E<gt>inflate>.
1015
1016 If you have built this module with zlib >= 1.2.0, the C<$eof> parameter is
1017 ignored. You can still set it if you want, but it won't be used behind the
1018 scenes.
1019
1020 =head2 B<$status = $i-E<gt>inflateSync($input)>
1021
1022 This method can be used to attempt to recover good data from a compressed
1023 data stream that is partially corrupt.
1024 It scans C<$input> until it reaches either a I<full flush point> or the
1025 end of the buffer.
1026
1027 If a I<full flush point> is found, C<Z_OK> is returned and C<$input>
1028 will be have all data up to the flush point removed. This data can then be
1029 passed to the C<$i-E<gt>inflate> method to be uncompressed.
1030
1031 Any other return code means that a flush point was not found. If more
1032 data is available, C<inflateSync> can be called repeatedly with more
1033 compressed data until the flush point is found.
1034
1035 Note I<full flush points> are not present by default in compressed
1036 data streams. They must have been added explicitly when the data stream
1037 was created by calling C<Compress::Deflate::flush>  with C<Z_FULL_FLUSH>.
1038
1039 =head2 B<$i-E<gt>dict_adler()>
1040
1041 Returns the adler32 value for the dictionary.
1042
1043 =head2 B<$i-E<gt>crc32()>
1044
1045 Returns the crc32 value for the uncompressed data to date.
1046
1047 If the C<CRC32> option is not enabled in the constructor for this object,
1048 this method will always return 0;
1049
1050 =head2 B<$i-E<gt>adler32()>
1051
1052 Returns the adler32 value for the uncompressed data to date.
1053
1054 If the C<ADLER32> option is not enabled in the constructor for this object,
1055 this method will always return 0;
1056
1057 =head2 B<$i-E<gt>msg()>
1058
1059 Returns the last error message generated by zlib.
1060
1061 =head2 B<$i-E<gt>total_in()>
1062
1063 Returns the total number of bytes compressed bytes input to inflate.
1064
1065 =head2 B<$i-E<gt>total_out()>
1066
1067 Returns the total number of uncompressed bytes output from inflate.
1068
1069 =head2 B<$d-E<gt>get_BufSize()>
1070
1071 Returns the buffer size used to carry out the decompression.
1072
1073 =head2 Example
1074
1075 Here is an example of using C<inflate>.
1076
1077     use strict ;
1078     use warnings ;
1079
1080     use Compress::Raw::Zlib;
1081
1082     my $x = new Compress::Raw::Zlib::Inflate()
1083        or die "Cannot create a inflation stream\n" ;
1084
1085     my $input = '' ;
1086     binmode STDIN;
1087     binmode STDOUT;
1088
1089     my ($output, $status) ;
1090     while (read(STDIN, $input, 4096))
1091     {
1092         $status = $x->inflate(\$input, $output) ;
1093
1094         print $output
1095             if $status == Z_OK or $status == Z_STREAM_END ;
1096
1097         last if $status != Z_OK ;
1098     }
1099
1100     die "inflation failed\n"
1101         unless $status == Z_STREAM_END ;
1102
1103 =head1 CHECKSUM FUNCTIONS
1104
1105 Two functions are provided by I<zlib> to calculate checksums. For the
1106 Perl interface, the order of the two parameters in both functions has
1107 been reversed. This allows both running checksums and one off
1108 calculations to be done.
1109
1110     $crc = adler32($buffer [,$crc]) ;
1111     $crc = crc32($buffer [,$crc]) ;
1112
1113 The buffer parameters can either be a scalar or a scalar reference.
1114
1115 If the $crc parameters is C<undef>, the crc value will be reset.
1116
1117 If you have built this module with zlib 1.2.3 or better, two more
1118 CRC-related functions are available.
1119
1120     $crc = adler32_combine($crc1, $crc2, $len2)l
1121     $crc = crc32_combine($adler1, $adler2, $len2)
1122
1123 These functions allow checksums to be merged.
1124
1125 =head1 ACCESSING ZIP FILES
1126
1127 Although it is possible (with some effort on your part) to use this
1128 module to access .zip files, there is a module on CPAN that will do all
1129 the hard work for you. Check out the C<Archive::Zip> module on CPAN at
1130
1131     http://www.cpan.org/modules/by-module/Archive/Archive-Zip-*.tar.gz
1132
1133 =head1 CONSTANTS
1134
1135 All the I<zlib> constants are automatically imported when you make use
1136 of I<Compress::Raw::Zlib>.
1137
1138 =head1 SEE ALSO
1139
1140 L<Compress::Zlib>, L<IO::Compress::Gzip>, L<IO::Uncompress::Gunzip>, L<IO::Compress::Deflate>, L<IO::Uncompress::Inflate>, L<IO::Compress::RawDeflate>, L<IO::Uncompress::RawInflate>, L<IO::Compress::Bzip2>, L<IO::Uncompress::Bunzip2>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
1141
1142 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1143
1144 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1145 L<Archive::Tar|Archive::Tar>,
1146 L<IO::Zlib|IO::Zlib>
1147
1148 For RFC 1950, 1951 and 1952 see
1149 F<http://www.faqs.org/rfcs/rfc1950.html>,
1150 F<http://www.faqs.org/rfcs/rfc1951.html> and
1151 F<http://www.faqs.org/rfcs/rfc1952.html>
1152
1153 The I<zlib> compression library was written by Jean-loup Gailly
1154 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1155
1156 The primary site for the I<zlib> compression library is
1157 F<http://www.zlib.org>.
1158
1159 The primary site for gzip is F<http://www.gzip.org>.
1160
1161 =head1 AUTHOR
1162
1163 This module was written by Paul Marquess, F<pmqs@cpan.org>.
1164
1165 =head1 MODIFICATION HISTORY
1166
1167 See the Changes file.
1168
1169 =head1 COPYRIGHT AND LICENSE
1170
1171 Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
1172
1173 This program is free software; you can redistribute it and/or
1174 modify it under the same terms as Perl itself.
1175