Profile of /project/perl/lib/Compress/Raw/Zlib.pm

File	/project/perl/lib/Compress/Raw/Zlib.pm
Statements Executed	82
Statement Execution Time	7.89ms

Subroutines — ordered by exclusive time
Exclusive Time	Inclusive Time	Subroutine
0s	0s	Compress::Raw::Zlib::::AUTOLOAD Compress::Raw::Zlib::AUTOLOAD
0s	0s	Compress::Raw::Zlib::::BEGIN Compress::Raw::Zlib::BEGIN
0s	0s	Compress::Raw::Zlib::Deflate::::new Compress::Raw::Zlib::Deflate::new
0s	0s	Compress::Raw::Zlib::Inflate::::new Compress::Raw::Zlib::Inflate::new
0s	0s	Compress::Raw::Zlib::InflateScan::::new Compress::Raw::Zlib::InflateScan::new
0s	0s	Compress::Raw::Zlib::Parameters::_checkType
0s	0s	Compress::Raw::Zlib::Parameters::::new Compress::Raw::Zlib::Parameters::new
0s	0s	Compress::Raw::Zlib::Parameters::parse
0s	0s	Compress::Raw::Zlib::Parameters::parsed
0s	0s	Compress::Raw::Zlib::Parameters::setError
0s	0s	Compress::Raw::Zlib::Parameters::value
0s	0s	Compress::Raw::Zlib::::ParseParameters Compress::Raw::Zlib::ParseParameters
0s	0s	Compress::Raw::Zlib::::__ANON__[:74] Compress::Raw::Zlib::__ANON__[:74]
0s	0s	Compress::Raw::Zlib::deflateStream::deflateParams
0s	0s	Compress::Raw::Zlib::inflateScanStream::createDeflateStream
0s	0s	Compress::Raw::Zlib::inflateScanStream::inflate

Call graph for these subroutines as a Graphviz dot language file.

Line	State ments	Time on line	Calls	Time in subs	Code
1
2					package Compress::Raw::Zlib;
3
4	1	5µs			require 5.004 ;
5	1	7µs			require Exporter;
6	3	100µs	1	393µs	use AutoLoader; # spent 393µs making 1 call to AutoLoader::import
7	3	98µs	1	248µs	use Carp ; # spent 248µs making 1 call to Exporter::import
8
9					#use Parse::Parameters;
10
11	3	76µs	1	22µs	use strict ; # spent 22µs making 1 call to strict::import
12	3	83µs	1	111µs	use warnings ; # spent 111µs making 1 call to warnings::import
13	3	413µs	1	14µs	use bytes ; # spent 14µs making 1 call to bytes::import
14	1	5µs			our ($VERSION, $XS_VERSION, @ISA, @EXPORT, $AUTOLOAD);
15
16	1	9µs			$VERSION = '2.005';
17	1	5µs			$XS_VERSION = $VERSION;
18	1	67µs			$VERSION = eval $VERSION;
19
20	1	9µs			@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	1	22µs			@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	3	314µs	1	100µs	no strict 'refs'; # spent 100µs making 1 call to strict::unimport
74					*{$AUTOLOAD} = sub { $val };
75					goto &{$AUTOLOAD};
76					}
77
78	3	103µs	1	195µs	use constant FLAG_APPEND => 1 ; # spent 195µs making 1 call to constant::import
79	3	119µs	1	186µs	use constant FLAG_CRC => 2 ; # spent 186µs making 1 call to constant::import
80	3	95µs	1	178µs	use constant FLAG_ADLER => 4 ; # spent 178µs making 1 call to constant::import
81	3	206µs	1	176µs	use constant FLAG_CONSUME_INPUT => 8 ; # spent 176µs making 1 call to constant::import
82
83					eval {
84					require XSLoader;
85					XSLoader::load('Compress::Raw::Zlib', $XS_VERSION); # spent 792µs making 1 call to XSLoader::load
86					1;
87					}
88	4	844µs			or do {
89					require DynaLoader;
90					local @ISA = qw(DynaLoader);
91					bootstrap Compress::Raw::Zlib $XS_VERSION ;
92					};
93
94
95	3	97µs	1	184µs	use constant Parse_any => 0x01; # spent 184µs making 1 call to constant::import
96	3	91µs	1	183µs	use constant Parse_unsigned => 0x02; # spent 183µs making 1 call to constant::import
97	3	104µs	1	178µs	use constant Parse_signed => 0x04; # spent 178µs making 1 call to constant::import
98	3	96µs	1	183µs	use constant Parse_boolean => 0x08; # spent 183µs making 1 call to constant::import
99	3	107µs	1	178µs	use constant Parse_string => 0x10; # spent 178µs making 1 call to constant::import
100	3	95µs	1	173µs	use constant Parse_custom => 0x12; # spent 173µs making 1 call to constant::import
101
102	3	92µs	1	170µs	use constant Parse_store_ref => 0x100 ; # spent 170µs making 1 call to constant::import
103
104	3	97µs	1	193µs	use constant OFF_PARSED => 0 ; # spent 193µs making 1 call to constant::import
105	3	92µs	1	171µs	use constant OFF_TYPE => 1 ; # spent 171µs making 1 call to constant::import
106	3	100µs	1	192µs	use constant OFF_DEFAULT => 2 ; # spent 192µs making 1 call to constant::import
107	3	93µs	1	177µs	use constant OFF_FIXED => 3 ; # spent 177µs making 1 call to constant::import
108	3	107µs	1	172µs	use constant OFF_FIRST_ONLY => 4 ; # spent 172µs making 1 call to constant::import
109	3	4.10ms	1	178µs	use constant OFF_STICKY => 5 ; # spent 178µs making 1 call to constant::import
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	44µs			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