File Coverage

blib/lib/Compress/Raw/Zlib.pm

Criterion	Covered	Total	%
statement	197	222	88.7
branch	68	102	66.7
condition	25	41	61.0
subroutine	36	38	94.7
pod	0	1	0.0
total	326	404	80.7

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