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 | |
63ad731d |
16 | $VERSION = '2.001'; |
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 | |
571 | |
572 | |
573 | =head1 Compress::Raw::Zlib::Deflate |
574 | |
575 | This section defines an interface that allows in-memory compression using |
576 | the I<deflate> interface provided by zlib. |
577 | |
578 | Here is a definition of the interface available: |
579 | |
580 | |
581 | =head2 B<($d, $status) = new Compress::Raw::Zlib::Deflate( [OPT] ) > |
582 | |
583 | Initialises a deflation object. |
584 | |
585 | If you are familiar with the I<zlib> library, it combines the |
586 | features of the I<zlib> functions C<deflateInit>, C<deflateInit2> |
587 | and C<deflateSetDictionary>. |
588 | |
589 | If successful, it will return the initialised deflation object, C<$d> |
590 | and a C<$status> of C<Z_OK> in a list context. In scalar context it |
591 | returns the deflation object, C<$d>, only. |
592 | |
593 | If not successful, the returned deflation object, C<$d>, will be |
594 | I<undef> and C<$status> will hold the a I<zlib> error code. |
595 | |
596 | The function optionally takes a number of named options specified as |
e7d45986 |
597 | C<< Name => value >> pairs. This allows individual options to be |
25f0751f |
598 | tailored without having to specify them all in the parameter list. |
599 | |
600 | For backward compatibility, it is also possible to pass the parameters |
601 | as a reference to a hash containing the name=>value pairs. |
602 | |
603 | Below is a list of the valid options: |
604 | |
605 | =over 5 |
606 | |
607 | =item B<-Level> |
608 | |
609 | Defines the compression level. Valid values are 0 through 9, |
610 | C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and |
611 | C<Z_DEFAULT_COMPRESSION>. |
612 | |
e7d45986 |
613 | The default is Z_DEFAULT_COMPRESSION. |
25f0751f |
614 | |
615 | =item B<-Method> |
616 | |
617 | Defines the compression method. The only valid value at present (and |
e7d45986 |
618 | the default) is Z_DEFLATED. |
25f0751f |
619 | |
620 | =item B<-WindowBits> |
621 | |
622 | For a definition of the meaning and valid values for C<WindowBits> |
623 | refer to the I<zlib> documentation for I<deflateInit2>. |
624 | |
e7d45986 |
625 | Defaults to MAX_WBITS. |
25f0751f |
626 | |
627 | =item B<-MemLevel> |
628 | |
629 | For a definition of the meaning and valid values for C<MemLevel> |
630 | refer to the I<zlib> documentation for I<deflateInit2>. |
631 | |
e7d45986 |
632 | Defaults to MAX_MEM_LEVEL. |
25f0751f |
633 | |
634 | =item B<-Strategy> |
635 | |
636 | Defines the strategy used to tune the compression. The valid values are |
637 | C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED>, C<Z_RLE>, C<Z_FIXED> and |
638 | C<Z_HUFFMAN_ONLY>. |
639 | |
e7d45986 |
640 | The default is Z_DEFAULT_STRATEGY. |
25f0751f |
641 | |
642 | =item B<-Dictionary> |
643 | |
644 | When a dictionary is specified I<Compress::Raw::Zlib> will automatically |
645 | call C<deflateSetDictionary> directly after calling C<deflateInit>. The |
646 | Adler32 value for the dictionary can be obtained by calling the method |
647 | C<$d-E<gt>dict_adler()>. |
648 | |
649 | The default is no dictionary. |
650 | |
651 | =item B<-Bufsize> |
652 | |
653 | Sets the initial size for the output buffer used by the C<$d-E<gt>deflate> |
654 | and C<$d-E<gt>flush> methods. If the buffer has to be |
655 | reallocated to increase the size, it will grow in increments of |
656 | C<Bufsize>. |
657 | |
658 | The default buffer size is 4096. |
659 | |
660 | =item B<-AppendOutput> |
661 | |
662 | This option controls how data is written to the output buffer by the |
663 | C<$d-E<gt>deflate> and C<$d-E<gt>flush> methods. |
664 | |
665 | If the C<AppendOutput> option is set to false, the output buffers in the |
666 | C<$d-E<gt>deflate> and C<$d-E<gt>flush> methods will be truncated before |
667 | uncompressed data is written to them. |
668 | |
669 | If the option is set to true, uncompressed data will be appended to the |
670 | output buffer in the C<$d-E<gt>deflate> and C<$d-E<gt>flush> methods. |
671 | |
672 | This option defaults to false. |
673 | |
674 | =item B<-CRC32> |
675 | |
676 | If set to true, a crc32 checksum of the uncompressed data will be |
677 | calculated. Use the C<$d-E<gt>crc32> method to retrieve this value. |
678 | |
679 | This option defaults to false. |
680 | |
681 | |
682 | =item B<-ADLER32> |
683 | |
684 | If set to true, an adler32 checksum of the uncompressed data will be |
685 | calculated. Use the C<$d-E<gt>adler32> method to retrieve this value. |
686 | |
687 | This option defaults to false. |
688 | |
689 | |
690 | =back |
691 | |
692 | Here is an example of using the C<Compress::Raw::Zlib::Deflate> optional |
693 | parameter list to override the default buffer size and compression |
694 | level. All other options will take their default values. |
695 | |
696 | my $d = new Compress::Raw::Zlib::Deflate ( -Bufsize => 300, |
697 | -Level => Z_BEST_SPEED ) ; |
698 | |
699 | |
700 | =head2 B<$status = $d-E<gt>deflate($input, $output)> |
701 | |
702 | Deflates the contents of C<$input> and writes the compressed data to |
703 | C<$output>. |
704 | |
705 | The C<$input> and C<$output> parameters can be either scalars or scalar |
706 | references. |
707 | |
708 | When finished, C<$input> will be completely processed (assuming there |
709 | were no errors). If the deflation was successful it writes the deflated |
710 | data to C<$output> and returns a status value of C<Z_OK>. |
711 | |
712 | On error, it returns a I<zlib> error code. |
713 | |
714 | If the C<AppendOutput> option is set to true in the constructor for |
715 | the C<$d> object, the compressed data will be appended to C<$output>. If |
716 | it is false, C<$output> will be truncated before any compressed data is |
717 | written to it. |
718 | |
719 | B<Note>: This method will not necessarily write compressed data to |
720 | C<$output> every time it is called. So do not assume that there has been |
721 | an error if the contents of C<$output> is empty on returning from |
722 | this method. As long as the return code from the method is C<Z_OK>, |
723 | the deflate has succeeded. |
724 | |
725 | =head2 B<$status = $d-E<gt>flush($output [, $flush_type]) > |
726 | |
727 | Typically used to finish the deflation. Any pending output will be |
728 | written to C<$output>. |
729 | |
730 | Returns C<Z_OK> if successful. |
731 | |
732 | Note that flushing can seriously degrade the compression ratio, so it |
733 | should only be used to terminate a decompression (using C<Z_FINISH>) or |
734 | when you want to create a I<full flush point> (using C<Z_FULL_FLUSH>). |
735 | |
736 | By default the C<flush_type> used is C<Z_FINISH>. Other valid values |
737 | for C<flush_type> are C<Z_NO_FLUSH>, C<Z_PARTIAL_FLUSH>, C<Z_SYNC_FLUSH> |
738 | and C<Z_FULL_FLUSH>. It is strongly recommended that you only set the |
739 | C<flush_type> parameter if you fully understand the implications of |
740 | what it does. See the C<zlib> documentation for details. |
741 | |
742 | If the C<AppendOutput> option is set to true in the constructor for |
743 | the C<$d> object, the compressed data will be appended to C<$output>. If |
744 | it is false, C<$output> will be truncated before any compressed data is |
745 | written to it. |
746 | |
747 | =head2 B<$status = $d-E<gt>deflateParams([OPT])> |
748 | |
749 | Change settings for the deflate object C<$d>. |
750 | |
751 | The list of the valid options is shown below. Options not specified |
752 | will remain unchanged. |
753 | |
754 | |
755 | =over 5 |
756 | |
757 | =item B<-Level> |
758 | |
759 | Defines the compression level. Valid values are 0 through 9, |
760 | C<Z_NO_COMPRESSION>, C<Z_BEST_SPEED>, C<Z_BEST_COMPRESSION>, and |
761 | C<Z_DEFAULT_COMPRESSION>. |
762 | |
763 | =item B<-Strategy> |
764 | |
765 | Defines the strategy used to tune the compression. The valid values are |
766 | C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>. |
767 | |
768 | =item B<-BufSize> |
769 | |
770 | Sets the initial size for the output buffer used by the C<$d-E<gt>deflate> |
771 | and C<$d-E<gt>flush> methods. If the buffer has to be |
772 | reallocated to increase the size, it will grow in increments of |
773 | C<Bufsize>. |
774 | |
775 | |
776 | =back |
777 | |
778 | =head2 B<$status = $d-E<gt>deflateTune($good_length, $max_lazy, $nice_length, $max_chain)> |
779 | |
780 | Tune the internal settings for the deflate object C<$d>. This option is |
781 | only available if you are running zlib 1.2.2.3 or better. |
782 | |
783 | Refer to the documentation in zlib.h for instructions on how to fly |
784 | C<deflateTune>. |
785 | |
786 | =head2 B<$d-E<gt>dict_adler()> |
787 | |
788 | Returns the adler32 value for the dictionary. |
789 | |
790 | =head2 B<$d-E<gt>crc32()> |
791 | |
792 | Returns the crc32 value for the uncompressed data to date. |
793 | |
794 | If the C<CRC32> option is not enabled in the constructor for this object, |
795 | this method will always return 0; |
796 | |
797 | =head2 B<$d-E<gt>adler32()> |
798 | |
799 | Returns the adler32 value for the uncompressed data to date. |
800 | |
801 | =head2 B<$d-E<gt>msg()> |
802 | |
803 | Returns the last error message generated by zlib. |
804 | |
805 | =head2 B<$d-E<gt>total_in()> |
806 | |
807 | Returns the total number of bytes uncompressed bytes input to deflate. |
808 | |
809 | =head2 B<$d-E<gt>total_out()> |
810 | |
811 | Returns the total number of compressed bytes output from deflate. |
812 | |
813 | =head2 B<$d-E<gt>get_Strategy()> |
814 | |
815 | Returns the deflation strategy currently used. Valid values are |
816 | C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>. |
817 | |
818 | |
819 | =head2 B<$d-E<gt>get_Level()> |
820 | |
821 | Returns the compression level being used. |
822 | |
823 | =head2 B<$d-E<gt>get_BufSize()> |
824 | |
825 | Returns the buffer size used to carry out the compression. |
826 | |
827 | =head2 Example |
828 | |
829 | |
830 | Here is a trivial example of using C<deflate>. It simply reads standard |
831 | input, deflates it and writes it to standard output. |
832 | |
833 | use strict ; |
834 | use warnings ; |
835 | |
836 | use Compress::Raw::Zlib ; |
837 | |
838 | binmode STDIN; |
839 | binmode STDOUT; |
840 | my $x = new Compress::Raw::Zlib::Deflate |
841 | or die "Cannot create a deflation stream\n" ; |
842 | |
843 | my ($output, $status) ; |
844 | while (<>) |
845 | { |
846 | $status = $x->deflate($_, $output) ; |
847 | |
848 | $status == Z_OK |
849 | or die "deflation failed\n" ; |
850 | |
851 | print $output ; |
852 | } |
853 | |
854 | $status = $x->flush($output) ; |
855 | |
856 | $status == Z_OK |
857 | or die "deflation failed\n" ; |
858 | |
859 | print $output ; |
860 | |
861 | =head1 Compress::Raw::Zlib::Inflate |
862 | |
863 | This section defines an interface that allows in-memory uncompression using |
864 | the I<inflate> interface provided by zlib. |
865 | |
866 | Here is a definition of the interface: |
867 | |
868 | |
869 | =head2 B< ($i, $status) = new Compress::Raw::Zlib::Inflate( [OPT] ) > |
870 | |
871 | Initialises an inflation object. |
872 | |
873 | In a list context it returns the inflation object, C<$i>, and the |
874 | I<zlib> status code (C<$status>). In a scalar context it returns the |
875 | inflation object only. |
876 | |
877 | If successful, C<$i> will hold the inflation object and C<$status> will |
878 | be C<Z_OK>. |
879 | |
880 | If not successful, C<$i> will be I<undef> and C<$status> will hold the |
881 | I<zlib> error code. |
882 | |
883 | The function optionally takes a number of named options specified as |
e7d45986 |
884 | C<< -Name => value >> pairs. This allows individual options to be |
25f0751f |
885 | tailored without having to specify them all in the parameter list. |
886 | |
887 | For backward compatibility, it is also possible to pass the parameters |
e7d45986 |
888 | as a reference to a hash containing the C<< name=>value >> pairs. |
25f0751f |
889 | |
890 | Here is a list of the valid options: |
891 | |
892 | =over 5 |
893 | |
894 | =item B<-WindowBits> |
895 | |
896 | To uncompress an RFC 1950 data stream, set C<WindowBits> to a positive |
897 | number. |
898 | |
899 | To uncompress an RFC 1951 data stream, set C<WindowBits> to C<-MAX_WBITS>. |
900 | |
901 | For a full definition of the meaning and valid values for C<WindowBits> |
902 | refer to the I<zlib> documentation for I<inflateInit2>. |
903 | |
e7d45986 |
904 | Defaults to MAX_WBITS. |
25f0751f |
905 | |
906 | =item B<-Bufsize> |
907 | |
908 | Sets the initial size for the output buffer used by the C<$i-E<gt>inflate> |
909 | method. If the output buffer in this method has to be reallocated to |
910 | increase the size, it will grow in increments of C<Bufsize>. |
911 | |
912 | Default is 4096. |
913 | |
914 | =item B<-Dictionary> |
915 | |
916 | The default is no dictionary. |
917 | |
918 | =item B<-AppendOutput> |
919 | |
920 | This option controls how data is written to the output buffer by the |
921 | C<$i-E<gt>inflate> method. |
922 | |
923 | If the option is set to false, the output buffer in the C<$i-E<gt>inflate> |
924 | method will be truncated before uncompressed data is written to it. |
925 | |
926 | If the option is set to true, uncompressed data will be appended to the |
927 | output buffer by the C<$i-E<gt>inflate> method. |
928 | |
929 | This option defaults to false. |
930 | |
931 | |
932 | =item B<-CRC32> |
933 | |
934 | If set to true, a crc32 checksum of the uncompressed data will be |
935 | calculated. Use the C<$i-E<gt>crc32> method to retrieve this value. |
936 | |
937 | This option defaults to false. |
938 | |
939 | =item B<-ADLER32> |
940 | |
941 | If set to true, an adler32 checksum of the uncompressed data will be |
942 | calculated. Use the C<$i-E<gt>adler32> method to retrieve this value. |
943 | |
944 | This option defaults to false. |
945 | |
946 | =item B<-ConsumeInput> |
947 | |
948 | If set to true, this option will remove compressed data from the input |
949 | buffer of the the C< $i-E<gt>inflate > method as the inflate progresses. |
950 | |
951 | This option can be useful when you are processing compressed data that is |
952 | embedded in another file/buffer. In this case the data that immediately |
953 | follows the compressed stream will be left in the input buffer. |
954 | |
955 | This option defaults to true. |
956 | |
957 | =back |
958 | |
959 | Here is an example of using an optional parameter to override the default |
960 | buffer size. |
961 | |
962 | my ($i, $status) = new Compress::Raw::Zlib::Inflate( -Bufsize => 300 ) ; |
963 | |
964 | =head2 B< $status = $i-E<gt>inflate($input, $output [,$eof]) > |
965 | |
966 | Inflates the complete contents of C<$input> and writes the uncompressed |
967 | data to C<$output>. The C<$input> and C<$output> parameters can either be |
968 | scalars or scalar references. |
969 | |
970 | Returns C<Z_OK> if successful and C<Z_STREAM_END> if the end of the |
971 | compressed data has been successfully reached. |
972 | |
973 | If not successful C<$status> will hold the I<zlib> error code. |
974 | |
975 | If the C<ConsumeInput> option has been set to true when the |
976 | C<Compress::Raw::Zlib::Inflate> object is created, the C<$input> parameter |
977 | is modified by C<inflate>. On completion it will contain what remains |
978 | of the input buffer after inflation. In practice, this means that when |
979 | the return status is C<Z_OK> the C<$input> parameter will contain an |
980 | empty string, and when the return status is C<Z_STREAM_END> the C<$input> |
981 | parameter will contains what (if anything) was stored in the input buffer |
982 | after the deflated data stream. |
983 | |
984 | This feature is useful when processing a file format that encapsulates |
985 | a compressed data stream (e.g. gzip, zip) and there is useful data |
986 | immediately after the deflation stream. |
987 | |
988 | If the C<AppendOutput> option is set to true in the constructor for |
989 | this object, the uncompressed data will be appended to C<$output>. If |
990 | it is false, C<$output> will be truncated before any uncompressed data |
991 | is written to it. |
992 | |
993 | The C<$eof> parameter needs a bit of explanation. |
994 | |
995 | Prior to version 1.2.0, zlib assumed that there was at least one trailing |
996 | byte immediately after the compressed data stream when it was carrying out |
997 | decompression. This normally isn't a problem because the majority of zlib |
998 | applications guarantee that there will be data directly after the |
999 | compressed data stream. For example, both gzip (RFC 1950) and zip both |
1000 | define trailing data that follows the compressed data stream. |
1001 | |
1002 | The C<$eof> parameter only needs to be used if B<all> of the following |
1003 | conditions apply |
1004 | |
1005 | =over 5 |
1006 | |
1007 | =item 1 |
1008 | |
1009 | You are either using a copy of zlib that is older than version 1.2.0 or you |
1010 | want your application code to be able to run with as many different |
1011 | versions of zlib as possible. |
1012 | |
1013 | =item 2 |
1014 | |
1015 | You have set the C<WindowBits> parameter to C<-MAX_WBITS> in the constructor |
1016 | for this object, i.e. you are uncompressing a raw deflated data stream |
1017 | (RFC 1951). |
1018 | |
1019 | =item 3 |
1020 | |
1021 | There is no data immediately after the compressed data stream. |
1022 | |
1023 | =back |
1024 | |
1025 | If B<all> of these are the case, then you need to set the C<$eof> parameter |
1026 | to true on the final call (and only the final call) to C<$i-E<gt>inflate>. |
1027 | |
1028 | If you have built this module with zlib >= 1.2.0, the C<$eof> parameter is |
1029 | ignored. You can still set it if you want, but it won't be used behind the |
1030 | scenes. |
1031 | |
1032 | =head2 B<$status = $i-E<gt>inflateSync($input)> |
1033 | |
1034 | This method can be used to attempt to recover good data from a compressed |
1035 | data stream that is partially corrupt. |
1036 | It scans C<$input> until it reaches either a I<full flush point> or the |
1037 | end of the buffer. |
1038 | |
1039 | If a I<full flush point> is found, C<Z_OK> is returned and C<$input> |
1040 | will be have all data up to the flush point removed. This data can then be |
1041 | passed to the C<$i-E<gt>inflate> method to be uncompressed. |
1042 | |
1043 | Any other return code means that a flush point was not found. If more |
1044 | data is available, C<inflateSync> can be called repeatedly with more |
1045 | compressed data until the flush point is found. |
1046 | |
1047 | Note I<full flush points> are not present by default in compressed |
1048 | data streams. They must have been added explicitly when the data stream |
1049 | was created by calling C<Compress::Deflate::flush> with C<Z_FULL_FLUSH>. |
1050 | |
1051 | |
1052 | =head2 B<$i-E<gt>dict_adler()> |
1053 | |
1054 | Returns the adler32 value for the dictionary. |
1055 | |
1056 | =head2 B<$i-E<gt>crc32()> |
1057 | |
1058 | Returns the crc32 value for the uncompressed data to date. |
1059 | |
1060 | If the C<CRC32> option is not enabled in the constructor for this object, |
1061 | this method will always return 0; |
1062 | |
1063 | =head2 B<$i-E<gt>adler32()> |
1064 | |
1065 | Returns the adler32 value for the uncompressed data to date. |
1066 | |
1067 | If the C<ADLER32> option is not enabled in the constructor for this object, |
1068 | this method will always return 0; |
1069 | |
1070 | =head2 B<$i-E<gt>msg()> |
1071 | |
1072 | Returns the last error message generated by zlib. |
1073 | |
1074 | =head2 B<$i-E<gt>total_in()> |
1075 | |
1076 | Returns the total number of bytes compressed bytes input to inflate. |
1077 | |
1078 | =head2 B<$i-E<gt>total_out()> |
1079 | |
1080 | Returns the total number of uncompressed bytes output from inflate. |
1081 | |
1082 | =head2 B<$d-E<gt>get_BufSize()> |
1083 | |
1084 | Returns the buffer size used to carry out the decompression. |
1085 | |
1086 | =head2 Example |
1087 | |
1088 | Here is an example of using C<inflate>. |
1089 | |
1090 | use strict ; |
1091 | use warnings ; |
1092 | |
1093 | use Compress::Raw::Zlib; |
1094 | |
1095 | my $x = new Compress::Raw::Zlib::Inflate() |
1096 | or die "Cannot create a inflation stream\n" ; |
1097 | |
1098 | my $input = '' ; |
1099 | binmode STDIN; |
1100 | binmode STDOUT; |
1101 | |
1102 | my ($output, $status) ; |
1103 | while (read(STDIN, $input, 4096)) |
1104 | { |
1105 | $status = $x->inflate(\$input, $output) ; |
1106 | |
1107 | print $output |
1108 | if $status == Z_OK or $status == Z_STREAM_END ; |
1109 | |
1110 | last if $status != Z_OK ; |
1111 | } |
1112 | |
1113 | die "inflation failed\n" |
1114 | unless $status == Z_STREAM_END ; |
1115 | |
1116 | =head1 CHECKSUM FUNCTIONS |
1117 | |
1118 | Two functions are provided by I<zlib> to calculate checksums. For the |
1119 | Perl interface, the order of the two parameters in both functions has |
1120 | been reversed. This allows both running checksums and one off |
1121 | calculations to be done. |
1122 | |
1123 | $crc = adler32($buffer [,$crc]) ; |
1124 | $crc = crc32($buffer [,$crc]) ; |
1125 | |
1126 | The buffer parameters can either be a scalar or a scalar reference. |
1127 | |
1128 | If the $crc parameters is C<undef>, the crc value will be reset. |
1129 | |
1130 | If you have built this module with zlib 1.2.3 or better, two more |
1131 | CRC-related functions are available. |
1132 | |
1133 | $crc = adler32_combine($crc1, $crc2, $len2)l |
1134 | $crc = crc32_combine($adler1, $adler2, $len2) |
1135 | |
1136 | These functions allow checksums to be merged. |
1137 | |
1138 | =head1 ACCESSING ZIP FILES |
1139 | |
1140 | Although it is possible (with some effort on your part) to use this |
1141 | module to access .zip files, there is a module on CPAN that will do all |
1142 | the hard work for you. Check out the C<Archive::Zip> module on CPAN at |
1143 | |
1144 | http://www.cpan.org/modules/by-module/Archive/Archive-Zip-*.tar.gz |
1145 | |
1146 | |
1147 | =head1 CONSTANTS |
1148 | |
1149 | All the I<zlib> constants are automatically imported when you make use |
1150 | of I<Compress::Raw::Zlib>. |
1151 | |
1152 | |
1153 | =head1 SEE ALSO |
1154 | |
258133d1 |
1155 | L<Compress::Zlib>, L<IO::Compress::Gzip>, L<IO::Uncompress::Gunzip>, L<IO::Compress::Deflate>, L<IO::Uncompress::Inflate>, L<IO::Compress::RawDeflate>, L<IO::Uncompress::RawInflate>, L<IO::Compress::Bzip2>, L<IO::Uncompress::Bunzip2>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress> |
25f0751f |
1156 | |
1157 | L<Compress::Zlib::FAQ|Compress::Zlib::FAQ> |
1158 | |
1159 | L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>, |
1160 | L<Archive::Tar|Archive::Tar>, |
1161 | L<IO::Zlib|IO::Zlib> |
1162 | |
1163 | |
1164 | For RFC 1950, 1951 and 1952 see |
1165 | F<http://www.faqs.org/rfcs/rfc1950.html>, |
1166 | F<http://www.faqs.org/rfcs/rfc1951.html> and |
1167 | F<http://www.faqs.org/rfcs/rfc1952.html> |
1168 | |
1169 | The I<zlib> compression library was written by Jean-loup Gailly |
1170 | F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>. |
1171 | |
1172 | The primary site for the I<zlib> compression library is |
1173 | F<http://www.zlib.org>. |
1174 | |
1175 | The primary site for gzip is F<http://www.gzip.org>. |
1176 | |
1177 | |
1178 | |
1179 | |
25f0751f |
1180 | =head1 AUTHOR |
1181 | |
cb7abd7f |
1182 | This module was written by Paul Marquess, F<pmqs@cpan.org>. |
25f0751f |
1183 | |
1184 | |
1185 | |
1186 | =head1 MODIFICATION HISTORY |
1187 | |
1188 | See the Changes file. |
1189 | |
1190 | =head1 COPYRIGHT AND LICENSE |
25f0751f |
1191 | |
1192 | Copyright (c) 2005-2006 Paul Marquess. All rights reserved. |
1193 | |
1194 | This program is free software; you can redistribute it and/or |
1195 | modify it under the same terms as Perl itself. |
1196 | |
1197 | |
1198 | |