[ Index ]

PHP Cross Reference of Unnamed Project

title

Body

[close]

/se3-unattended/var/se3/unattended/install/linuxaux/opt/perl/lib/5.10.0/i586-linux-thread-multi/Compress/Raw/ -> Zlib.pm (source)

   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.008';
  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  


Generated: Tue Mar 17 22:47:18 2015 Cross-referenced by PHPXref 0.7.1