[ Index ] |
PHP Cross Reference of Unnamed Project |
[Summary view] [Print] [Text view]
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
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
Generated: Tue Mar 17 22:47:18 2015 | Cross-referenced by PHPXref 0.7.1 |