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.004_01';
  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
 572
 573 =head1 Compress::Raw::Zlib::Deflate
 574
 575 This section defines an interface that allows in-memory compression using
 576 the I<deflate> interface provided by zlib.
 577
 578 Here is a definition of the interface available:
 579
 580
 581 =head2 B<($d, $status) = new Compress::Raw::Zlib::Deflate( [OPT] ) >
 582
 583 Initialises a deflation object.
 584
 585 If you are familiar with the I<zlib> library, it combines the
 586 features of the I<zlib> functions C<deflateInit>, C<deflateInit2>
 587 and C<deflateSetDictionary>.
 588
 589 If successful, it will return the initialised deflation object, C<$d>
 590 and a C<$status> of C<Z_OK> in a list context. In scalar context it
 591 returns the deflation object, C<$d>, only.
 592
 593 If not successful, the returned deflation object, C<$d>, will be
 594 I<undef> and C<$status> will hold the a I<zlib> error code.
 595
 596 The function optionally takes a number of named options specified as
 597 C<< Name => value >> pairs. This allows individual options to be
 598 tailored without having to specify them all in the parameter list.
 599
 600 For backward compatibility, it is also possible to pass the parameters
 601 as a reference to a hash containing the name=>value pairs.
 602
 603 Below is a list of the valid options:
 604
 605 =over 5
 606
 607 =item B<-Level>
 608
 609 Defines the compression level. Valid values are 0 through 9,
 610 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
 611 C<Z_DEFAULT_COMPRESSION>.
 612
 613 The default is Z_DEFAULT_COMPRESSION.
 614
 615 =item B<-Method>
 616
 617 Defines the compression method. The only valid value at present (and
 618 the default) is Z_DEFLATED.
 619
 620 =item B<-WindowBits>
 621
 622 For a definition of the meaning and valid values for C<WindowBits>
 623 refer to the I<zlib> documentation for I<deflateInit2>.
 624
 625 Defaults to MAX_WBITS.
 626
 627 =item B<-MemLevel>
 628
 629 For a definition of the meaning and valid values for C<MemLevel>
 630 refer to the I<zlib> documentation for I<deflateInit2>.
 631
 632 Defaults to MAX_MEM_LEVEL.
 633
 634 =item B<-Strategy>
 635
 636 Defines the strategy used to tune the compression. The valid values are
 637 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED>, C<Z_RLE>, C<Z_FIXED> and
 638 C<Z_HUFFMAN_ONLY>.
 639
 640 The default is Z_DEFAULT_STRATEGY.
 641
 642 =item B<-Dictionary>
 643
 644 When a dictionary is specified I<Compress::Raw::Zlib> will automatically
 645 call C<deflateSetDictionary> directly after calling C<deflateInit>. The
 646 Adler32 value for the dictionary can be obtained by calling the method
 647 C<$d-E<gt>dict_adler()>.
 648
 649 The default is no dictionary.
 650
 651 =item B<-Bufsize>
 652
 653 Sets the initial size for the output buffer used by the C<$d-E<gt>deflate>
 654 and C<$d-E<gt>flush> methods. If the buffer has to be
 655 reallocated to increase the size, it will grow in increments of
 656 C<Bufsize>.
 657
 658 The default buffer size is 4096.
 659
 660 =item B<-AppendOutput>
 661
 662 This option controls how data is written to the output buffer by the
 663 C<$d-E<gt>deflate> and C<$d-E<gt>flush> methods.
 664
 665 If the C<AppendOutput> option is set to false, the output buffers in the
 666 C<$d-E<gt>deflate> and C<$d-E<gt>flush>  methods will be truncated before
 667 uncompressed data is written to them.
 668
 669 If the option is set to true, uncompressed data will be appended to the
 670 output buffer in the C<$d-E<gt>deflate> and C<$d-E<gt>flush> methods.
 671
 672 This option defaults to false.
 673
 674 =item B<-CRC32>
 675
 676 If set to true, a crc32 checksum of the uncompressed data will be
 677 calculated. Use the C<$d-E<gt>crc32> method to retrieve this value.
 678
 679 This option defaults to false.
 680
 681
 682 =item B<-ADLER32>
 683
 684 If set to true, an adler32 checksum of the uncompressed data will be
 685 calculated. Use the C<$d-E<gt>adler32> method to retrieve this value.
 686
 687 This option defaults to false.
 688
 689
 690 =back
 691
 692 Here is an example of using the C<Compress::Raw::Zlib::Deflate> optional
 693 parameter list to override the default buffer size and compression
 694 level. All other options will take their default values.
 695
 696     my $d = new Compress::Raw::Zlib::Deflate ( -Bufsize => 300,
 697                                                -Level   => Z_BEST_SPEED ) ;
 698
 699
 700 =head2 B<$status = $d-E<gt>deflate($input, $output)>
 701
 702 Deflates the contents of C<$input> and writes the compressed data to
 703 C<$output>.
 704
 705 The C<$input> and C<$output> parameters can be either scalars or scalar
 706 references.
 707
 708 When finished, C<$input> will be completely processed (assuming there
 709 were no errors). If the deflation was successful it writes the deflated
 710 data to C<$output> and returns a status value of C<Z_OK>.
 711
 712 On error, it returns a I<zlib> error code.
 713
 714 If the C<AppendOutput> option is set to true in the constructor for
 715 the C<$d> object, the compressed data will be appended to C<$output>. If
 716 it is false, C<$output> will be truncated before any compressed data is
 717 written to it.
 718
 719 B<Note>: This method will not necessarily write compressed data to
 720 C<$output> every time it is called. So do not assume that there has been
 721 an error if the contents of C<$output> is empty on returning from
 722 this method. As long as the return code from the method is C<Z_OK>,
 723 the deflate has succeeded.
 724
 725 =head2 B<$status = $d-E<gt>flush($output [, $flush_type]) >
 726
 727 Typically used to finish the deflation. Any pending output will be
 728 written to C<$output>.
 729
 730 Returns C<Z_OK> if successful.
 731
 732 Note that flushing can seriously degrade the compression ratio, so it
 733 should only be used to terminate a decompression (using C<Z_FINISH>) or
 734 when you want to create a I<full flush point> (using C<Z_FULL_FLUSH>).
 735
 736 By default the C<flush_type> used is C<Z_FINISH>. Other valid values
 737 for C<flush_type> are C<Z_NO_FLUSH>, C<Z_PARTIAL_FLUSH>, C<Z_SYNC_FLUSH>
 738 and C<Z_FULL_FLUSH>. It is strongly recommended that you only set the
 739 C<flush_type> parameter if you fully understand the implications of
 740 what it does. See the C<zlib> documentation for details.
 741
 742 If the C<AppendOutput> option is set to true in the constructor for
 743 the C<$d> object, the compressed data will be appended to C<$output>. If
 744 it is false, C<$output> will be truncated before any compressed data is
 745 written to it.
 746
 747 =head2 B<$status = $d-E<gt>deflateParams([OPT])>
 748
 749 Change settings for the deflate object C<$d>.
 750
 751 The list of the valid options is shown below. Options not specified
 752 will remain unchanged.
 753
 754
 755 =over 5
 756
 757 =item B<-Level>
 758
 759 Defines the compression level. Valid values are 0 through 9,
 760 C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and
 761 C<Z_DEFAULT_COMPRESSION>.
 762
 763 =item B<-Strategy>
 764
 765 Defines the strategy used to tune the compression. The valid values are
 766 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
 767
 768 =item B<-BufSize>
 769
 770 Sets the initial size for the output buffer used by the C<$d-E<gt>deflate>
 771 and C<$d-E<gt>flush> methods. If the buffer has to be
 772 reallocated to increase the size, it will grow in increments of
 773 C<Bufsize>.
 774
 775
 776 =back
 777
 778 =head2 B<$status = $d-E<gt>deflateTune($good_length, $max_lazy, $nice_length, $max_chain)>
 779
 780 Tune the internal settings for the deflate object C<$d>. This option is
 781 only available if you are running zlib 1.2.2.3 or better.
 782
 783 Refer to the documentation in zlib.h for instructions on how to fly
 784 C<deflateTune>.
 785
 786 =head2 B<$d-E<gt>dict_adler()>
 787
 788 Returns the adler32 value for the dictionary.
 789
 790 =head2 B<$d-E<gt>crc32()>
 791
 792 Returns the crc32 value for the uncompressed data to date.
 793
 794 If the C<CRC32> option is not enabled in the constructor for this object,
 795 this method will always return 0;
 796
 797 =head2 B<$d-E<gt>adler32()>
 798
 799 Returns the adler32 value for the uncompressed data to date.
 800
 801 =head2 B<$d-E<gt>msg()>
 802
 803 Returns the last error message generated by zlib.
 804
 805 =head2 B<$d-E<gt>total_in()>
 806
 807 Returns the total number of bytes uncompressed bytes input to deflate.
 808
 809 =head2 B<$d-E<gt>total_out()>
 810
 811 Returns the total number of compressed bytes output from deflate.
 812
 813 =head2 B<$d-E<gt>get_Strategy()>
 814
 815 Returns the deflation strategy currently used. Valid values are
 816 C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
 817
 818
 819 =head2 B<$d-E<gt>get_Level()>
 820
 821 Returns the compression level being used.
 822
 823 =head2 B<$d-E<gt>get_BufSize()>
 824
 825 Returns the buffer size used to carry out the compression.
 826
 827 =head2 Example
 828
 829
 830 Here is a trivial example of using C<deflate>. It simply reads standard
 831 input, deflates it and writes it to standard output.
 832
 833     use strict ;
 834     use warnings ;
 835
 836     use Compress::Raw::Zlib ;
 837
 838     binmode STDIN;
 839     binmode STDOUT;
 840     my $x = new Compress::Raw::Zlib::Deflate
 841        or die "Cannot create a deflation stream\n" ;
 842
 843     my ($output, $status) ;
 844     while (<>)
 845     {
 846         $status = $x->deflate($_, $output) ;
 847
 848         $status == Z_OK
 849             or die "deflation failed\n" ;
 850
 851         print $output ;
 852     }
 853
 854     $status = $x->flush($output) ;
 855
 856     $status == Z_OK
 857         or die "deflation failed\n" ;
 858
 859     print $output ;
 860
 861 =head1 Compress::Raw::Zlib::Inflate
 862
 863 This section defines an interface that allows in-memory uncompression using
 864 the I<inflate> interface provided by zlib.
 865
 866 Here is a definition of the interface:
 867
 868
 869 =head2 B< ($i, $status) = new Compress::Raw::Zlib::Inflate( [OPT] ) >
 870
 871 Initialises an inflation object.
 872
 873 In a list context it returns the inflation object, C<$i>, and the
 874 I<zlib> status code (C<$status>). In a scalar context it returns the
 875 inflation object only.
 876
 877 If successful, C<$i> will hold the inflation object and C<$status> will
 878 be C<Z_OK>.
 879
 880 If not successful, C<$i> will be I<undef> and C<$status> will hold the
 881 I<zlib> error code.
 882
 883 The function optionally takes a number of named options specified as
 884 C<< -Name => value >> pairs. This allows individual options to be
 885 tailored without having to specify them all in the parameter list.
 886
 887 For backward compatibility, it is also possible to pass the parameters
 888 as a reference to a hash containing the C<< name=>value >> pairs.
 889
 890 Here is a list of the valid options:
 891
 892 =over 5
 893
 894 =item B<-WindowBits>
 895
 896 To uncompress an RFC 1950 data stream, set C<WindowBits> to a positive
 897 number.
 898
 899 To uncompress an RFC 1951 data stream, set C<WindowBits> to C<-MAX_WBITS>.
 900
 901 For a full definition of the meaning and valid values for C<WindowBits>
 902 refer to the I<zlib> documentation for I<inflateInit2>.
 903
 904 Defaults to MAX_WBITS.
 905
 906 =item B<-Bufsize>
 907
 908 Sets the initial size for the output buffer used by the C<$i-E<gt>inflate>
 909 method. If the output buffer in this method has to be reallocated to
 910 increase the size, it will grow in increments of C<Bufsize>.
 911
 912 Default is 4096.
 913
 914 =item B<-Dictionary>
 915
 916 The default is no dictionary.
 917
 918 =item B<-AppendOutput>
 919
 920 This option controls how data is written to the output buffer by the
 921 C<$i-E<gt>inflate> method.
 922
 923 If the option is set to false, the output buffer in the C<$i-E<gt>inflate>
 924 method will be truncated before uncompressed data is written to it.
 925
 926 If the option is set to true, uncompressed data will be appended to the
 927 output buffer by the C<$i-E<gt>inflate> method.
 928
 929 This option defaults to false.
 930
 931
 932 =item B<-CRC32>
 933
 934 If set to true, a crc32 checksum of the uncompressed data will be
 935 calculated. Use the C<$i-E<gt>crc32> method to retrieve this value.
 936
 937 This option defaults to false.
 938
 939 =item B<-ADLER32>
 940
 941 If set to true, an adler32 checksum of the uncompressed data will be
 942 calculated. Use the C<$i-E<gt>adler32> method to retrieve this value.
 943
 944 This option defaults to false.
 945
 946 =item B<-ConsumeInput>
 947
 948 If set to true, this option will remove compressed data from the input
 949 buffer of the the C< $i-E<gt>inflate > method as the inflate progresses.
 950
 951 This option can be useful when you are processing compressed data that is
 952 embedded in another file/buffer. In this case the data that immediately
 953 follows the compressed stream will be left in the input buffer.
 954
 955 This option defaults to true.
 956
 957 =back
 958
 959 Here is an example of using an optional parameter to override the default
 960 buffer size.
 961
 962     my ($i, $status) = new Compress::Raw::Zlib::Inflate( -Bufsize => 300 ) ;
 963
 964 =head2 B< $status = $i-E<gt>inflate($input, $output [,$eof]) >
 965
 966 Inflates the complete contents of C<$input> and writes the uncompressed
 967 data to C<$output>. The C<$input> and C<$output> parameters can either be
 968 scalars or scalar references.
 969
 970 Returns C<Z_OK> if successful and C<Z_STREAM_END> if the end of the
 971 compressed data has been successfully reached.
 972
 973 If not successful C<$status> will hold the I<zlib> error code.
 974
 975 If the C<ConsumeInput> option has been set to true when the
 976 C<Compress::Raw::Zlib::Inflate> object is created, the C<$input> parameter
 977 is modified by C<inflate>. On completion it will contain what remains
 978 of the input buffer after inflation. In practice, this means that when
 979 the return status is C<Z_OK> the C<$input> parameter will contain an
 980 empty string, and when the return status is C<Z_STREAM_END> the C<$input>
 981 parameter will contains what (if anything) was stored in the input buffer
 982 after the deflated data stream.
 983
 984 This feature is useful when processing a file format that encapsulates
 985 a compressed data stream (e.g. gzip, zip) and there is useful data
 986 immediately after the deflation stream.
 987
 988 If the C<AppendOutput> option is set to true in the constructor for
 989 this object, the uncompressed data will be appended to C<$output>. If
 990 it is false, C<$output> will be truncated before any uncompressed data
 991 is written to it.
 992
 993 The C<$eof> parameter needs a bit of explanation.
 994
 995 Prior to version 1.2.0, zlib assumed that there was at least one trailing
 996 byte immediately after the compressed data stream when it was carrying out
 997 decompression. This normally isn't a problem because the majority of zlib
 998 applications guarantee that there will be data directly after the
 999 compressed data stream.  For example, both gzip (RFC 1950) and zip both
1000 define trailing data that follows the compressed data stream.
1001
1002 The C<$eof> parameter only needs to be used if B<all> of the following
1003 conditions apply
1004
1005 =over 5
1006
1007 =item 1
1008
1009 You are either using a copy of zlib that is older than version 1.2.0 or you
1010 want your application code to be able to run with as many different
1011 versions of zlib as possible.
1012
1013 =item 2
1014
1015 You have set the C<WindowBits> parameter to C<-MAX_WBITS> in the constructor
1016 for this object, i.e. you are uncompressing a raw deflated data stream
1017 (RFC 1951).
1018
1019 =item 3
1020
1021 There is no data immediately after the compressed data stream.
1022
1023 =back
1024
1025 If B<all> of these are the case, then you need to set the C<$eof> parameter
1026 to true on the final call (and only the final call) to C<$i-E<gt>inflate>.
1027
1028 If you have built this module with zlib >= 1.2.0, the C<$eof> parameter is
1029 ignored. You can still set it if you want, but it won't be used behind the
1030 scenes.
1031
1032 =head2 B<$status = $i-E<gt>inflateSync($input)>
1033
1034 This method can be used to attempt to recover good data from a compressed
1035 data stream that is partially corrupt.
1036 It scans C<$input> until it reaches either a I<full flush point> or the
1037 end of the buffer.
1038
1039 If a I<full flush point> is found, C<Z_OK> is returned and C<$input>
1040 will be have all data up to the flush point removed. This data can then be
1041 passed to the C<$i-E<gt>inflate> method to be uncompressed.
1042
1043 Any other return code means that a flush point was not found. If more
1044 data is available, C<inflateSync> can be called repeatedly with more
1045 compressed data until the flush point is found.
1046
1047 Note I<full flush points> are not present by default in compressed
1048 data streams. They must have been added explicitly when the data stream
1049 was created by calling C<Compress::Deflate::flush>  with C<Z_FULL_FLUSH>.
1050
1051
1052 =head2 B<$i-E<gt>dict_adler()>
1053
1054 Returns the adler32 value for the dictionary.
1055
1056 =head2 B<$i-E<gt>crc32()>
1057
1058 Returns the crc32 value for the uncompressed data to date.
1059
1060 If the C<CRC32> option is not enabled in the constructor for this object,
1061 this method will always return 0;
1062
1063 =head2 B<$i-E<gt>adler32()>
1064
1065 Returns the adler32 value for the uncompressed data to date.
1066
1067 If the C<ADLER32> option is not enabled in the constructor for this object,
1068 this method will always return 0;
1069
1070 =head2 B<$i-E<gt>msg()>
1071
1072 Returns the last error message generated by zlib.
1073
1074 =head2 B<$i-E<gt>total_in()>
1075
1076 Returns the total number of bytes compressed bytes input to inflate.
1077
1078 =head2 B<$i-E<gt>total_out()>
1079
1080 Returns the total number of uncompressed bytes output from inflate.
1081
1082 =head2 B<$d-E<gt>get_BufSize()>
1083
1084 Returns the buffer size used to carry out the decompression.
1085
1086 =head2 Example
1087
1088 Here is an example of using C<inflate>.
1089
1090     use strict ;
1091     use warnings ;
1092
1093     use Compress::Raw::Zlib;
1094
1095     my $x = new Compress::Raw::Zlib::Inflate()
1096        or die "Cannot create a inflation stream\n" ;
1097
1098     my $input = '' ;
1099     binmode STDIN;
1100     binmode STDOUT;
1101
1102     my ($output, $status) ;
1103     while (read(STDIN, $input, 4096))
1104     {
1105         $status = $x->inflate(\$input, $output) ;
1106
1107         print $output
1108             if $status == Z_OK or $status == Z_STREAM_END ;
1109
1110         last if $status != Z_OK ;
1111     }
1112
1113     die "inflation failed\n"
1114         unless $status == Z_STREAM_END ;
1115
1116 =head1 CHECKSUM FUNCTIONS
1117
1118 Two functions are provided by I<zlib> to calculate checksums. For the
1119 Perl interface, the order of the two parameters in both functions has
1120 been reversed. This allows both running checksums and one off
1121 calculations to be done.
1122
1123     $crc = adler32($buffer [,$crc]) ;
1124     $crc = crc32($buffer [,$crc]) ;
1125
1126 The buffer parameters can either be a scalar or a scalar reference.
1127
1128 If the $crc parameters is C<undef>, the crc value will be reset.
1129
1130 If you have built this module with zlib 1.2.3 or better, two more
1131 CRC-related functions are available.
1132
1133     $crc = adler32_combine($crc1, $crc2, $len2)l
1134     $crc = crc32_combine($adler1, $adler2, $len2)
1135
1136 These functions allow checksums to be merged.
1137
1138 =head1 ACCESSING ZIP FILES
1139
1140 Although it is possible (with some effort on your part) to use this
1141 module to access .zip files, there is a module on CPAN that will do all
1142 the hard work for you. Check out the C<Archive::Zip> module on CPAN at
1143
1144     http://www.cpan.org/modules/by-module/Archive/Archive-Zip-*.tar.gz
1145
1146
1147 =head1 CONSTANTS
1148
1149 All the I<zlib> constants are automatically imported when you make use
1150 of I<Compress::Raw::Zlib>.
1151
1152
1153 =head1 SEE ALSO
1154
1155 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>
1156
1157 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1158
1159 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1160 L<Archive::Tar|Archive::Tar>,
1161 L<IO::Zlib|IO::Zlib>
1162
1163
1164 For RFC 1950, 1951 and 1952 see
1165 F<http://www.faqs.org/rfcs/rfc1950.html>,
1166 F<http://www.faqs.org/rfcs/rfc1951.html> and
1167 F<http://www.faqs.org/rfcs/rfc1952.html>
1168
1169 The I<zlib> compression library was written by Jean-loup Gailly
1170 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1171
1172 The primary site for the I<zlib> compression library is
1173 F<http://www.zlib.org>.
1174
1175 The primary site for gzip is F<http://www.gzip.org>.
1176
1177
1178
1179
1180 =head1 AUTHOR
1181
1182 This module was written by Paul Marquess, F<pmqs@cpan.org>.
1183
1184
1185
1186 =head1 MODIFICATION HISTORY
1187
1188 See the Changes file.
1189
1190 =head1 COPYRIGHT AND LICENSE
1191
1192 Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
1193
1194 This program is free software; you can redistribute it and/or
1195 modify it under the same terms as Perl itself.
1196
1197
1198