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