← Index
NYTProf Performance Profile   « block view • line view • sub view »
For 05.Domain_and_Item.t
  Run on Tue May 4 17:21:41 2010
Reported on Tue May 4 17:22:20 2010

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