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