Profile of /project/perl/lib/IO/Uncompress/RawInflate.pm

File	/project/perl/lib/IO/Uncompress/RawInflate.pm
Statements Executed	32
Statement Execution Time	4.77ms

Subroutines — ordered by exclusive time
Exclusive Time	Inclusive Time	Subroutine
0s	0s	IO::Uncompress::RawInflate::::BEGINIO::Uncompress::RawInflate::BEGIN
0s	0s	IO::Uncompress::RawInflate::::_isRawIO::Uncompress::RawInflate::_isRaw
0s	0s	IO::Uncompress::RawInflate::::_isRawxIO::Uncompress::RawInflate::_isRawx
0s	0s	IO::Uncompress::RawInflate::chkTrailer
0s	0s	IO::Uncompress::RawInflate::::ckMagicIO::Uncompress::RawInflate::ckMagic
0s	0s	IO::Uncompress::RawInflate::::ckParamsIO::Uncompress::RawInflate::ckParams
0s	0s	IO::Uncompress::RawInflate::createDeflate
0s	0s	IO::Uncompress::RawInflate::getExtraParams
0s	0s	IO::Uncompress::RawInflate::inflateSync
0s	0s	IO::Uncompress::RawInflate::::mkUncompIO::Uncompress::RawInflate::mkUncomp
0s	0s	IO::Uncompress::RawInflate::::newIO::Uncompress::RawInflate::new
0s	0s	IO::Uncompress::RawInflate::rawinflate
0s	0s	IO::Uncompress::RawInflate::readHeader
0s	0s	IO::Uncompress::RawInflate::::scanIO::Uncompress::RawInflate::scan
0s	0s	IO::Uncompress::RawInflate::::zapIO::Uncompress::RawInflate::zap

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

Line	State ments	Time on line	Calls	Time in subs	Code
1					package IO::Uncompress::RawInflate ;
2					# for RFC1951
3
4	3	88µs	1	23µs	use strict ; # spent 23µs making 1 call to strict::import
5	3	77µs	1	114µs	use warnings; # spent 114µs making 1 call to warnings::import
6	3	96µs	1	14µs	use bytes; # spent 14µs making 1 call to bytes::import
7
8	3	397µs	2	1.59ms	use Compress::Raw::Zlib 2.005 ; # spent 1.37ms making 1 call to Exporter::import # spent 216µs making 1 call to UNIVERSAL::VERSION
9	3	372µs	2	1.12ms	use IO::Compress::Base::Common 2.005 qw(:Status createSelfTiedObject); # spent 903µs making 1 call to Exporter::import # spent 216µs making 1 call to UNIVERSAL::VERSION
10
11	3	654µs	2	364µs	use IO::Uncompress::Base 2.005 ; # spent 226µs making 1 call to UNIVERSAL::VERSION # spent 138µs making 1 call to Exporter::import
12	3	2.98ms	2	365µs	use IO::Uncompress::Adapter::Inflate 2.005 ; # spent 219µs making 1 call to UNIVERSAL::VERSION # spent 146µs making 1 call to Exporter::import
13
14
15
16
17	1	6µs			require Exporter ;
18	1	6µs			our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, %DEFLATE_CONSTANTS, $RawInflateError);
19
20	1	5µs			$VERSION = '2.005';
21	1	4µs			$RawInflateError = '';
22
23	1	11µs			@ISA = qw( Exporter IO::Uncompress::Base );
24	1	6µs			@EXPORT_OK = qw( $RawInflateError rawinflate ) ;
25	1	5µs			%DEFLATE_CONSTANTS = ();
26	1	9µs			%EXPORT_TAGS = %IO::Uncompress::Base::EXPORT_TAGS ;
27	1	7µs			push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
28	1	21µs	1	111µs	Exporter::export_ok_tags('all'); # spent 111µs making 1 call to Exporter::export_ok_tags
29
30
31
32					sub new
33					{
34					my $class = shift ;
35					my $obj = createSelfTiedObject($class, \$RawInflateError);
36					$obj->_create(undef, 0, @_);
37					}
38
39					sub rawinflate
40					{
41					my $obj = createSelfTiedObject(undef, \$RawInflateError);
42					return $obj->_inf(@_);
43					}
44
45					sub getExtraParams
46					{
47					return ();
48					}
49
50					sub ckParams
51					{
52					my $self = shift ;
53					my $got = shift ;
54
55					return 1;
56					}
57
58					sub mkUncomp
59					{
60					my $self = shift ;
61					my $class = shift ;
62					my $got = shift ;
63
64					my ($obj, $errstr, $errno) = IO::Uncompress::Adapter::Inflate::mkUncompObject(
65					$got->value('CRC32'),
66					$got->value('ADLER32'),
67					$got->value('Scan'),
68					);
69
70					return $self->saveErrorString(undef, $errstr, $errno)
71					if ! defined $obj;
72
73					*$self->{Uncomp} = $obj;
74
75					my $magic = $self->ckMagic()
76					or return 0;
77
78					*$self->{Info} = $self->readHeader($magic)
79					or return undef ;
80
81					return 1;
82
83					}
84
85
86					sub ckMagic
87					{
88					my $self = shift;
89
90					return $self->_isRaw() ;
91					}
92
93					sub readHeader
94					{
95					my $self = shift;
96					my $magic = shift ;
97
98					return {
99					'Type' => 'rfc1951',
100					'FingerprintLength' => 0,
101					'HeaderLength' => 0,
102					'TrailerLength' => 0,
103					'Header' => ''
104					};
105					}
106
107					sub chkTrailer
108					{
109					return STATUS_OK ;
110					}
111
112					sub _isRaw
113					{
114					my $self = shift ;
115
116					my $got = $self->_isRawx(@_);
117
118					if ($got) {
119					$self->{Pending} = $self->{HeaderPending} ;
120					}
121					else {
122					$self->pushBack(*$self->{HeaderPending});
123					*$self->{Uncomp}->reset();
124					}
125					*$self->{HeaderPending} = '';
126
127					return $got ;
128					}
129
130					sub _isRawx
131					{
132					my $self = shift ;
133					my $magic = shift ;
134
135					$magic = '' unless defined $magic ;
136
137					my $buffer = '';
138
139					$self->smartRead(\$buffer, *$self->{BlockSize}) >= 0
140					or return $self->saveErrorString(undef, "No data to read");
141
142					my $temp_buf = $magic . $buffer ;
143					*$self->{HeaderPending} = $temp_buf ;
144					$buffer = '';
145					my $status = *$self->{Uncomp}->uncompr(\$temp_buf, \$buffer, $self->smartEof()) ;
146					return $self->saveErrorString(undef, *$self->{Uncomp}{Error}, STATUS_ERROR)
147					if $status == STATUS_ERROR;
148
149					#my $buf_len = *$self->{Uncomp}->uncompressedBytes();
150					my $buf_len = length $buffer;
151
152					if ($status == STATUS_ENDSTREAM) {
153					if (*$self->{MultiStream}
154					&& (length $temp_buf \|\| ! $self->smartEof())){
155					*$self->{NewStream} = 1 ;
156					*$self->{EndStream} = 0 ;
157					$self->pushBack($temp_buf);
158					}
159					else {
160					*$self->{EndStream} = 1 ;
161					$self->pushBack($temp_buf);
162					}
163					}
164					*$self->{HeaderPending} = $buffer ;
165					*$self->{InflatedBytesRead} = $buf_len ;
166					*$self->{TotalInflatedBytesRead} += $buf_len ;
167					*$self->{Type} = 'rfc1951';
168
169					$self->saveStatus(STATUS_OK);
170
171					return {
172					'Type' => 'rfc1951',
173					'HeaderLength' => 0,
174					'TrailerLength' => 0,
175					'Header' => ''
176					};
177					}
178
179
180					sub inflateSync
181					{
182					my $self = shift ;
183
184					# inflateSync is a no-op in Plain mode
185					return 1
186					if *$self->{Plain} ;
187
188					return 0 if *$self->{Closed} ;
189					#return G_EOF if !length $self->{Pending} && $self->{EndStream} ;
190					return 0 if ! length $self->{Pending} && $self->{EndStream} ;
191
192					# Disable CRC check
193					*$self->{Strict} = 0 ;
194
195					my $status ;
196					while (1)
197					{
198					my $temp_buf ;
199
200					if (length *$self->{Pending} )
201					{
202					$temp_buf = *$self->{Pending} ;
203					*$self->{Pending} = '';
204					}
205					else
206					{
207					$status = $self->smartRead(\$temp_buf, *$self->{BlockSize}) ;
208					return $self->saveErrorString(0, "Error Reading Data")
209					if $status < 0 ;
210
211					if ($status == 0 ) {
212					*$self->{EndStream} = 1 ;
213					return $self->saveErrorString(0, "unexpected end of file", STATUS_ERROR);
214					}
215					}
216
217					$status = *$self->{Uncomp}->sync($temp_buf) ;
218
219					if ($status == STATUS_OK)
220					{
221					*$self->{Pending} .= $temp_buf ;
222					return 1 ;
223					}
224
225					last unless $status == STATUS_ERROR ;
226					}
227
228					return 0;
229					}
230
231					#sub performScan
232					#{
233					# my $self = shift ;
234					#
235					# my $status ;
236					# my $end_offset = 0;
237					#
238					# $status = $self->scan()
239					# #or return $self->saveErrorString(undef, "Error Scanning: $$error_ref", $self->errorNo) ;
240					# or return $self->saveErrorString(G_ERR, "Error Scanning: $status")
241					#
242					# $status = $self->zap($end_offset)
243					# or return $self->saveErrorString(G_ERR, "Error Zapping: $status");
244					# #or return $self->saveErrorString(undef, "Error Zapping: $$error_ref", $self->errorNo) ;
245					#
246					# #(*$obj->{Deflate}, $status) = $inf->createDeflate();
247					#
248					## $obj->{Header} = $inf->{Info}{Header};
249					## *$obj->{UnCompSize_32bit} =
250					## $obj->{BytesWritten} = $inf->{UnCompSize_32bit} ;
251					## $obj->{CompSize_32bit} = $inf->{CompSize_32bit} ;
252					#
253					#
254					## if ( $outType eq 'buffer')
255					## { substr( ${ *$self->{Buffer} }, $end_offset) = '' }
256					## elsif ($outType eq 'handle' \|\| $outType eq 'filename') {
257					## $self->{FH} = $inf->{FH} ;
258					## delete *$inf->{FH};
259					## *$obj->{FH}->flush() ;
260					## *$obj->{Handle} = 1 if $outType eq 'handle';
261					##
262					## #seek(*$obj->{FH}, $end_offset, SEEK_SET)
263					## *$obj->{FH}->seek($end_offset, SEEK_SET)
264					## or return $obj->saveErrorString(undef, $!, $!) ;
265					## }
266					#
267					#}
268
269					sub scan
270					{
271					my $self = shift ;
272
273					return 1 if *$self->{Closed} ;
274					return 1 if !length $self->{Pending} && $self->{EndStream} ;
275
276					my $buffer = '' ;
277					my $len = 0;
278
279					$len = $self->_raw_read(\$buffer, 1)
280					while ! *$self->{EndStream} && $len >= 0 ;
281
282					#return $len if $len < 0 ? $len : 0 ;
283					return $len < 0 ? 0 : 1 ;
284					}
285
286					sub zap
287					{
288					my $self = shift ;
289
290					my $headerLength = *$self->{Info}{HeaderLength};
291					my $block_offset = $headerLength + *$self->{Uncomp}->getLastBlockOffset();
292					$_[0] = $headerLength + *$self->{Uncomp}->getEndOffset();
293					#printf "# End $_[0], headerlen $headerLength \n";;
294					#printf "# block_offset $block_offset %x\n", $block_offset;
295					my $byte ;
296					( $self->smartSeek($block_offset) &&
297					$self->smartRead(\$byte, 1) )
298					or return $self->saveErrorString(0, $!, $!);
299
300					#printf "#byte is %x\n", unpack('C*',$byte);
301					*$self->{Uncomp}->resetLastBlockByte($byte);
302					#printf "#to byte is %x\n", unpack('C*',$byte);
303
304					( $self->smartSeek($block_offset) &&
305					$self->smartWrite($byte) )
306					or return $self->saveErrorString(0, $!, $!);
307
308					#$self->smartSeek($end_offset, 1);
309
310					return 1 ;
311					}
312
313					sub createDeflate
314					{
315					my $self = shift ;
316					my ($def, $status) = *$self->{Uncomp}->createDeflateStream(
317					-AppendOutput => 1,
318					-WindowBits => - MAX_WBITS,
319					-CRC32 => *$self->{Params}->value('CRC32'),
320					-ADLER32 => *$self->{Params}->value('ADLER32'),
321					);
322
323					return wantarray ? ($status, $def) : $def ;
324					}
325
326
327	1	28µs			1;
328
329					__END__
330
331
332					=head1 NAME
333
334
335
336					IO::Uncompress::RawInflate - Read RFC 1951 files/buffers
337
338
339
340					=head1 SYNOPSIS
341
342					use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
343
344					my $status = rawinflate $input => $output [,OPTS]
345					or die "rawinflate failed: $RawInflateError\n";
346
347					my $z = new IO::Uncompress::RawInflate $input [OPTS]
348					or die "rawinflate failed: $RawInflateError\n";
349
350					$status = $z->read($buffer)
351					$status = $z->read($buffer, $length)
352					$status = $z->read($buffer, $length, $offset)
353					$line = $z->getline()
354					$char = $z->getc()
355					$char = $z->ungetc()
356					$char = $z->opened()
357
358					$status = $z->inflateSync()
359
360					$data = $z->trailingData()
361					$status = $z->nextStream()
362					$data = $z->getHeaderInfo()
363					$z->tell()
364					$z->seek($position, $whence)
365					$z->binmode()
366					$z->fileno()
367					$z->eof()
368					$z->close()
369
370					$RawInflateError ;
371
372					# IO::File mode
373
374					<$z>
375					read($z, $buffer);
376					read($z, $buffer, $length);
377					read($z, $buffer, $length, $offset);
378					tell($z)
379					seek($z, $position, $whence)
380					binmode($z)
381					fileno($z)
382					eof($z)
383					close($z)
384
385
386					=head1 DESCRIPTION
387
388
389
390					This module provides a Perl interface that allows the reading of
391					files/buffers that conform to RFC 1951.
392
393					For writing RFC 1951 files/buffers, see the companion module IO::Compress::RawDeflate.
394
395
396
397
398
399					=head1 Functional Interface
400
401					A top-level function, C<rawinflate>, is provided to carry out
402					"one-shot" uncompression between buffers and/or files. For finer
403					control over the uncompression process, see the L</"OO Interface">
404					section.
405
406					use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
407
408					rawinflate $input => $output [,OPTS]
409					or die "rawinflate failed: $RawInflateError\n";
410
411
412
413					The functional interface needs Perl5.005 or better.
414
415
416					=head2 rawinflate $input => $output [, OPTS]
417
418
419					C<rawinflate> expects at least two parameters, C<$input> and C<$output>.
420
421					=head3 The C<$input> parameter
422
423					The parameter, C<$input>, is used to define the source of
424					the compressed data.
425
426					It can take one of the following forms:
427
428					=over 5
429
430					=item A filename
431
432					If the C<$input> parameter is a simple scalar, it is assumed to be a
433					filename. This file will be opened for reading and the input data
434					will be read from it.
435
436					=item A filehandle
437
438					If the C<$input> parameter is a filehandle, the input data will be
439					read from it.
440					The string '-' can be used as an alias for standard input.
441
442					=item A scalar reference
443
444					If C<$input> is a scalar reference, the input data will be read
445					from C<$$input>.
446
447					=item An array reference
448
449					If C<$input> is an array reference, each element in the array must be a
450					filename.
451
452					The input data will be read from each file in turn.
453
454					The complete array will be walked to ensure that it only
455					contains valid filenames before any data is uncompressed.
456
457
458
459					=item An Input FileGlob string
460
461					If C<$input> is a string that is delimited by the characters "<" and ">"
462					C<rawinflate> will assume that it is an I<input fileglob string>. The
463					input is the list of files that match the fileglob.
464
465					If the fileglob does not match any files ...
466
467					See L<File::GlobMapper\|File::GlobMapper> for more details.
468
469
470					=back
471
472					If the C<$input> parameter is any other type, C<undef> will be returned.
473
474
475
476					=head3 The C<$output> parameter
477
478					The parameter C<$output> is used to control the destination of the
479					uncompressed data. This parameter can take one of these forms.
480
481					=over 5
482
483					=item A filename
484
485					If the C<$output> parameter is a simple scalar, it is assumed to be a
486					filename. This file will be opened for writing and the uncompressed
487					data will be written to it.
488
489					=item A filehandle
490
491					If the C<$output> parameter is a filehandle, the uncompressed data
492					will be written to it.
493					The string '-' can be used as an alias for standard output.
494
495
496					=item A scalar reference
497
498					If C<$output> is a scalar reference, the uncompressed data will be
499					stored in C<$$output>.
500
501
502
503					=item An Array Reference
504
505					If C<$output> is an array reference, the uncompressed data will be
506					pushed onto the array.
507
508					=item An Output FileGlob
509
510					If C<$output> is a string that is delimited by the characters "<" and ">"
511					C<rawinflate> will assume that it is an I<output fileglob string>. The
512					output is the list of files that match the fileglob.
513
514					When C<$output> is an fileglob string, C<$input> must also be a fileglob
515					string. Anything else is an error.
516
517					=back
518
519					If the C<$output> parameter is any other type, C<undef> will be returned.
520
521
522
523					=head2 Notes
524
525
526					When C<$input> maps to multiple compressed files/buffers and C<$output> is
527					a single file/buffer, after uncompression C<$output> will contain a
528					concatenation of all the uncompressed data from each of the input
529					files/buffers.
530
531
532
533
534
535					=head2 Optional Parameters
536
537					Unless specified below, the optional parameters for C<rawinflate>,
538					C<OPTS>, are the same as those used with the OO interface defined in the
539					L</"Constructor Options"> section below.
540
541					=over 5
542
543					=item C<< AutoClose => 0\|1 >>
544
545					This option applies to any input or output data streams to
546					C<rawinflate> that are filehandles.
547
548					If C<AutoClose> is specified, and the value is true, it will result in all
549					input and/or output filehandles being closed once C<rawinflate> has
550					completed.
551
552					This parameter defaults to 0.
553
554
555					=item C<< BinModeOut => 0\|1 >>
556
557					When writing to a file or filehandle, set C<binmode> before writing to the
558					file.
559
560					Defaults to 0.
561
562
563
564
565
566					=item C<< Append => 0\|1 >>
567
568					TODO
569
570					=item C<< MultiStream => 0\|1 >>
571
572
573
574					This option is a no-op.
575
576
577
578
579
580					=item C<< TrailingData => $scalar >>
581
582					Returns the data, if any, that is present immediately after the compressed
583					data stream once uncompression is complete.
584
585					This option can be used when there is useful information immediately
586					following the compressed data stream, and you don't know the length of the
587					compressed data stream.
588
589					If the input is a buffer, C<trailingData> will return everything from the
590					end of the compressed data stream to the end of the buffer.
591
592					If the input is a filehandle, C<trailingData> will return the data that is
593					left in the filehandle input buffer once the end of the compressed data
594					stream has been reached. You can then use the filehandle to read the rest
595					of the input file.
596
597					Don't bother using C<trailingData> if the input is a filename.
598
599
600
601					If you know the length of the compressed data stream before you start
602					uncompressing, you can avoid having to use C<trailingData> by setting the
603					C<InputLength> option.
604
605
606
607					=back
608
609
610
611
612					=head2 Examples
613
614					To read the contents of the file C<file1.txt.1951> and write the
615					compressed data to the file C<file1.txt>.
616
617					use strict ;
618					use warnings ;
619					use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
620
621					my $input = "file1.txt.1951";
622					my $output = "file1.txt";
623					rawinflate $input => $output
624					or die "rawinflate failed: $RawInflateError\n";
625
626
627					To read from an existing Perl filehandle, C<$input>, and write the
628					uncompressed data to a buffer, C<$buffer>.
629
630					use strict ;
631					use warnings ;
632					use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
633					use IO::File ;
634
635					my $input = new IO::File "<file1.txt.1951"
636					or die "Cannot open 'file1.txt.1951': $!\n" ;
637					my $buffer ;
638					rawinflate $input => \$buffer
639					or die "rawinflate failed: $RawInflateError\n";
640
641					To uncompress all files in the directory "/my/home" that match "*.txt.1951" and store the compressed data in the same directory
642
643					use strict ;
644					use warnings ;
645					use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
646
647					rawinflate '</my/home/*.txt.1951>' => '</my/home/#1.txt>'
648					or die "rawinflate failed: $RawInflateError\n";
649
650					and if you want to compress each file one at a time, this will do the trick
651
652					use strict ;
653					use warnings ;
654					use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
655
656					for my $input ( glob "/my/home/*.txt.1951" )
657					{
658					my $output = $input;
659					$output =~ s/.1951// ;
660					rawinflate $input => $output
661					or die "Error compressing '$input': $RawInflateError\n";
662					}
663
664					=head1 OO Interface
665
666					=head2 Constructor
667
668					The format of the constructor for IO::Uncompress::RawInflate is shown below
669
670
671					my $z = new IO::Uncompress::RawInflate $input [OPTS]
672					or die "IO::Uncompress::RawInflate failed: $RawInflateError\n";
673
674					Returns an C<IO::Uncompress::RawInflate> object on success and undef on failure.
675					The variable C<$RawInflateError> will contain an error message on failure.
676
677					If you are running Perl 5.005 or better the object, C<$z>, returned from
678					IO::Uncompress::RawInflate can be used exactly like an L<IO::File\|IO::File> filehandle.
679					This means that all normal input file operations can be carried out with
680					C<$z>. For example, to read a line from a compressed file/buffer you can
681					use either of these forms
682
683					$line = $z->getline();
684					$line = <$z>;
685
686					The mandatory parameter C<$input> is used to determine the source of the
687					compressed data. This parameter can take one of three forms.
688
689					=over 5
690
691					=item A filename
692
693					If the C<$input> parameter is a scalar, it is assumed to be a filename. This
694					file will be opened for reading and the compressed data will be read from it.
695
696					=item A filehandle
697
698					If the C<$input> parameter is a filehandle, the compressed data will be
699					read from it.
700					The string '-' can be used as an alias for standard input.
701
702
703					=item A scalar reference
704
705					If C<$input> is a scalar reference, the compressed data will be read from
706					C<$$output>.
707
708					=back
709
710					=head2 Constructor Options
711
712
713					The option names defined below are case insensitive and can be optionally
714					prefixed by a '-'. So all of the following are valid
715
716					-AutoClose
717					-autoclose
718					AUTOCLOSE
719					autoclose
720
721					OPTS is a combination of the following options:
722
723					=over 5
724
725					=item C<< AutoClose => 0\|1 >>
726
727					This option is only valid when the C<$input> parameter is a filehandle. If
728					specified, and the value is true, it will result in the file being closed once
729					either the C<close> method is called or the IO::Uncompress::RawInflate object is
730					destroyed.
731
732					This parameter defaults to 0.
733
734					=item C<< MultiStream => 0\|1 >>
735
736
737
738					Allows multiple concatenated compressed streams to be treated as a single
739					compressed stream. Decompression will stop once either the end of the
740					file/buffer is reached, an error is encountered (premature eof, corrupt
741					compressed data) or the end of a stream is not immediately followed by the
742					start of another stream.
743
744					This parameter defaults to 0.
745
746
747					=item C<< Prime => $string >>
748
749					This option will uncompress the contents of C<$string> before processing the
750					input file/buffer.
751
752					This option can be useful when the compressed data is embedded in another
753					file/data structure and it is not possible to work out where the compressed
754					data begins without having to read the first few bytes. If this is the
755					case, the uncompression can be I<primed> with these bytes using this
756					option.
757
758					=item C<< Transparent => 0\|1 >>
759
760					If this option is set and the input file/buffer is not compressed data,
761					the module will allow reading of it anyway.
762
763					In addition, if the input file/buffer does contain compressed data and
764					there is non-compressed data immediately following it, setting this option
765					will make this module treat the whole file/bufffer as a single data stream.
766
767					This option defaults to 1.
768
769					=item C<< BlockSize => $num >>
770
771					When reading the compressed input data, IO::Uncompress::RawInflate will read it in
772					blocks of C<$num> bytes.
773
774					This option defaults to 4096.
775
776					=item C<< InputLength => $size >>
777
778					When present this option will limit the number of compressed bytes read
779					from the input file/buffer to C<$size>. This option can be used in the
780					situation where there is useful data directly after the compressed data
781					stream and you know beforehand the exact length of the compressed data
782					stream.
783
784					This option is mostly used when reading from a filehandle, in which case
785					the file pointer will be left pointing to the first byte directly after the
786					compressed data stream.
787
788
789
790					This option defaults to off.
791
792					=item C<< Append => 0\|1 >>
793
794					This option controls what the C<read> method does with uncompressed data.
795
796					If set to 1, all uncompressed data will be appended to the output parameter
797					of the C<read> method.
798
799					If set to 0, the contents of the output parameter of the C<read> method
800					will be overwritten by the uncompressed data.
801
802					Defaults to 0.
803
804					=item C<< Strict => 0\|1 >>
805
806
807
808					This option is a no-op.
809
810
811
812
813
814
815
816					=back
817
818					=head2 Examples
819
820					TODO
821
822					=head1 Methods
823
824					=head2 read
825
826					Usage is
827
828					$status = $z->read($buffer)
829
830					Reads a block of compressed data (the size the the compressed block is
831					determined by the C<Buffer> option in the constructor), uncompresses it and
832					writes any uncompressed data into C<$buffer>. If the C<Append> parameter is
833					set in the constructor, the uncompressed data will be appended to the
834					C<$buffer> parameter. Otherwise C<$buffer> will be overwritten.
835
836					Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
837					or a negative number on error.
838
839					=head2 read
840
841					Usage is
842
843					$status = $z->read($buffer, $length)
844					$status = $z->read($buffer, $length, $offset)
845
846					$status = read($z, $buffer, $length)
847					$status = read($z, $buffer, $length, $offset)
848
849					Attempt to read C<$length> bytes of uncompressed data into C<$buffer>.
850
851					The main difference between this form of the C<read> method and the
852					previous one, is that this one will attempt to return I<exactly> C<$length>
853					bytes. The only circumstances that this function will not is if end-of-file
854					or an IO error is encountered.
855
856					Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
857					or a negative number on error.
858
859
860					=head2 getline
861
862					Usage is
863
864					$line = $z->getline()
865					$line = <$z>
866
867					Reads a single line.
868
869					This method fully supports the use of of the variable C<$/> (or
870					C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use) to
871					determine what constitutes an end of line. Paragraph mode, record mode and
872					file slurp mode are all supported.
873
874
875					=head2 getc
876
877					Usage is
878
879					$char = $z->getc()
880
881					Read a single character.
882
883					=head2 ungetc
884
885					Usage is
886
887					$char = $z->ungetc($string)
888
889
890
891					=head2 inflateSync
892
893					Usage is
894
895					$status = $z->inflateSync()
896
897					TODO
898
899
900					=head2 getHeaderInfo
901
902					Usage is
903
904					$hdr = $z->getHeaderInfo();
905					@hdrs = $z->getHeaderInfo();
906
907					This method returns either a hash reference (in scalar context) or a list
908					or hash references (in array context) that contains information about each
909					of the header fields in the compressed data stream(s).
910
911
912
913
914					=head2 tell
915
916					Usage is
917
918					$z->tell()
919					tell $z
920
921					Returns the uncompressed file offset.
922
923					=head2 eof
924
925					Usage is
926
927					$z->eof();
928					eof($z);
929
930
931
932					Returns true if the end of the compressed input stream has been reached.
933
934
935
936					=head2 seek
937
938					$z->seek($position, $whence);
939					seek($z, $position, $whence);
940
941
942
943
944					Provides a sub-set of the C<seek> functionality, with the restriction
945					that it is only legal to seek forward in the input file/buffer.
946					It is a fatal error to attempt to seek backward.
947
948
949
950					The C<$whence> parameter takes one the usual values, namely SEEK_SET,
951					SEEK_CUR or SEEK_END.
952
953					Returns 1 on success, 0 on failure.
954
955					=head2 binmode
956
957					Usage is
958
959					$z->binmode
960					binmode $z ;
961
962					This is a noop provided for completeness.
963
964					=head2 opened
965
966					$z->opened()
967
968					Returns true if the object currently refers to a opened file/buffer.
969
970					=head2 autoflush
971
972					my $prev = $z->autoflush()
973					my $prev = $z->autoflush(EXPR)
974
975					If the C<$z> object is associated with a file or a filehandle, this method
976					returns the current autoflush setting for the underlying filehandle. If
977					C<EXPR> is present, and is non-zero, it will enable flushing after every
978					write/print operation.
979
980					If C<$z> is associated with a buffer, this method has no effect and always
981					returns C<undef>.
982
983					B<Note> that the special variable C<$\|> B<cannot> be used to set or
984					retrieve the autoflush setting.
985
986					=head2 input_line_number
987
988					$z->input_line_number()
989					$z->input_line_number(EXPR)
990
991
992
993					Returns the current uncompressed line number. If C<EXPR> is present it has
994					the effect of setting the line number. Note that setting the line number
995					does not change the current position within the file/buffer being read.
996
997					The contents of C<$/> are used to to determine what constitutes a line
998					terminator.
999
1000
1001
1002					=head2 fileno
1003
1004					$z->fileno()
1005					fileno($z)
1006
1007					If the C<$z> object is associated with a file or a filehandle, this method
1008					will return the underlying file descriptor.
1009
1010					If the C<$z> object is is associated with a buffer, this method will
1011					return undef.
1012
1013					=head2 close
1014
1015					$z->close() ;
1016					close $z ;
1017
1018
1019
1020					Closes the output file/buffer.
1021
1022
1023
1024					For most versions of Perl this method will be automatically invoked if
1025					the IO::Uncompress::RawInflate object is destroyed (either explicitly or by the
1026					variable with the reference to the object going out of scope). The
1027					exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
1028					these cases, the C<close> method will be called automatically, but
1029					not until global destruction of all live objects when the program is
1030					terminating.
1031
1032					Therefore, if you want your scripts to be able to run on all versions
1033					of Perl, you should call C<close> explicitly and not rely on automatic
1034					closing.
1035
1036					Returns true on success, otherwise 0.
1037
1038					If the C<AutoClose> option has been enabled when the IO::Uncompress::RawInflate
1039					object was created, and the object is associated with a file, the
1040					underlying file will also be closed.
1041
1042
1043
1044
1045					=head2 nextStream
1046
1047					Usage is
1048
1049					my $status = $z->nextStream();
1050
1051					Skips to the next compressed data stream in the input file/buffer. If a new
1052					compressed data stream is found, the eof marker will be cleared and C<$.>
1053					will be reset to 0.
1054
1055					Returns 1 if a new stream was found, 0 if none was found, and -1 if an
1056					error was encountered.
1057
1058					=head2 trailingData
1059
1060					Usage is
1061
1062					my $data = $z->trailingData();
1063
1064					Returns the data, if any, that is present immediately after the compressed
1065					data stream once uncompression is complete. It only makes sense to call
1066					this method once the end of the compressed data stream has been
1067					encountered.
1068
1069					This option can be used when there is useful information immediately
1070					following the compressed data stream, and you don't know the length of the
1071					compressed data stream.
1072
1073					If the input is a buffer, C<trailingData> will return everything from the
1074					end of the compressed data stream to the end of the buffer.
1075
1076					If the input is a filehandle, C<trailingData> will return the data that is
1077					left in the filehandle input buffer once the end of the compressed data
1078					stream has been reached. You can then use the filehandle to read the rest
1079					of the input file.
1080
1081					Don't bother using C<trailingData> if the input is a filename.
1082
1083
1084
1085					If you know the length of the compressed data stream before you start
1086					uncompressing, you can avoid having to use C<trailingData> by setting the
1087					C<InputLength> option in the constructor.
1088
1089					=head1 Importing
1090
1091					No symbolic constants are required by this IO::Uncompress::RawInflate at present.
1092
1093					=over 5
1094
1095					=item :all
1096
1097					Imports C<rawinflate> and C<$RawInflateError>.
1098					Same as doing this
1099
1100					use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
1101
1102					=back
1103
1104					=head1 EXAMPLES
1105
1106
1107
1108
1109					=head1 SEE ALSO
1110
1111					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::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>
1112
1113					L<Compress::Zlib::FAQ\|Compress::Zlib::FAQ>
1114
1115					L<File::GlobMapper\|File::GlobMapper>, L<Archive::Zip\|Archive::Zip>,
1116					L<Archive::Tar\|Archive::Tar>,
1117					L<IO::Zlib\|IO::Zlib>
1118
1119
1120					For RFC 1950, 1951 and 1952 see
1121					F<http://www.faqs.org/rfcs/rfc1950.html>,
1122					F<http://www.faqs.org/rfcs/rfc1951.html> and
1123					F<http://www.faqs.org/rfcs/rfc1952.html>
1124
1125					The I<zlib> compression library was written by Jean-loup Gailly
1126					F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1127
1128					The primary site for the I<zlib> compression library is
1129					F<http://www.zlib.org>.
1130
1131					The primary site for gzip is F<http://www.gzip.org>.
1132
1133
1134
1135
1136					=head1 AUTHOR
1137
1138					This module was written by Paul Marquess, F<pmqs@cpan.org>.
1139
1140
1141
1142					=head1 MODIFICATION HISTORY
1143
1144					See the Changes file.
1145
1146					=head1 COPYRIGHT AND LICENSE
1147
1148					Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
1149
1150					This program is free software; you can redistribute it and/or
1151					modify it under the same terms as Perl itself.
1152