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