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