← Index
NYTProf Performance Profile   « block view • line view • sub view »
For ddd2.pl
  Run on Tue May 25 16:52:24 2010
Reported on Tue May 25 16:56:46 2010

File /project/perl/lib/IO/Uncompress/RawInflate.pm
Statements Executed 32
Statement Execution Time 4.77ms
Subroutines — ordered by exclusive time
Calls P F Exclusive
Time
Inclusive
Time
Subroutine
0000s0sIO::Uncompress::RawInflate::::BEGINIO::Uncompress::RawInflate::BEGIN
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
4388µs123µsuse strict ;
# spent 23µs making 1 call to strict::import
5377µs1114µsuse warnings;
# spent 114µs making 1 call to warnings::import
6396µs114µsuse bytes;
# spent 14µs making 1 call to bytes::import
7
83397µs21.59msuse Compress::Raw::Zlib 2.005 ;
# spent 1.37ms making 1 call to Exporter::import # spent 216µs making 1 call to UNIVERSAL::VERSION
93372µs21.12msuse 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
113654µs2364µsuse IO::Uncompress::Base 2.005 ;
# spent 226µs making 1 call to UNIVERSAL::VERSION # spent 138µs making 1 call to Exporter::import
1232.98ms2365µsuse 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
1716µsrequire Exporter ;
1816µsour ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, %DEFLATE_CONSTANTS, $RawInflateError);
19
2015µs$VERSION = '2.005';
2114µs$RawInflateError = '';
22
23111µs@ISA = qw( Exporter IO::Uncompress::Base );
2416µs@EXPORT_OK = qw( $RawInflateError rawinflate ) ;
2515µs%DEFLATE_CONSTANTS = ();
2619µs%EXPORT_TAGS = %IO::Uncompress::Base::EXPORT_TAGS ;
2717µspush @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
28121µs1111µsExporter::export_ok_tags('all');
# spent 111µs making 1 call to Exporter::export_ok_tags
29
30
31
32sub new
33{
34 my $class = shift ;
35 my $obj = createSelfTiedObject($class, \$RawInflateError);
36 $obj->_create(undef, 0, @_);
37}
38
39sub rawinflate
40{
41 my $obj = createSelfTiedObject(undef, \$RawInflateError);
42 return $obj->_inf(@_);
43}
44
45sub getExtraParams
46{
47 return ();
48}
49
50sub ckParams
51{
52 my $self = shift ;
53 my $got = shift ;
54
55 return 1;
56}
57
58sub 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
86sub ckMagic
87{
88 my $self = shift;
89
90 return $self->_isRaw() ;
91}
92
93sub 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
107sub chkTrailer
108{
109 return STATUS_OK ;
110}
111
112sub _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
130sub _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
180sub 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
269sub 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
286sub 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
313sub 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
327128µs1;
328
329__END__
330
331
332=head1 NAME
333
334
335
336IO::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
390This module provides a Perl interface that allows the reading of
391files/buffers that conform to RFC 1951.
392
393For writing RFC 1951 files/buffers, see the companion module IO::Compress::RawDeflate.
394
395
396
397
398
399=head1 Functional Interface
400
401A top-level function, C<rawinflate>, is provided to carry out
402"one-shot" uncompression between buffers and/or files. For finer
403control over the uncompression process, see the L</"OO Interface">
404section.
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
413The functional interface needs Perl5.005 or better.
414
415
416=head2 rawinflate $input => $output [, OPTS]
417
418
419C<rawinflate> expects at least two parameters, C<$input> and C<$output>.
420
421=head3 The C<$input> parameter
422
423The parameter, C<$input>, is used to define the source of
424the compressed data.
425
426It can take one of the following forms:
427
428=over 5
429
430=item A filename
431
432If the C<$input> parameter is a simple scalar, it is assumed to be a
433filename. This file will be opened for reading and the input data
434will be read from it.
435
436=item A filehandle
437
438If the C<$input> parameter is a filehandle, the input data will be
439read from it.
440The string '-' can be used as an alias for standard input.
441
442=item A scalar reference
443
444If C<$input> is a scalar reference, the input data will be read
445from C<$$input>.
446
447=item An array reference
448
449If C<$input> is an array reference, each element in the array must be a
450filename.
451
452The input data will be read from each file in turn.
453
454The complete array will be walked to ensure that it only
455contains valid filenames before any data is uncompressed.
456
457
458
459=item An Input FileGlob string
460
461If C<$input> is a string that is delimited by the characters "<" and ">"
462C<rawinflate> will assume that it is an I<input fileglob string>. The
463input is the list of files that match the fileglob.
464
465If the fileglob does not match any files ...
466
467See L<File::GlobMapper|File::GlobMapper> for more details.
468
469
470=back
471
472If the C<$input> parameter is any other type, C<undef> will be returned.
473
474
475
476=head3 The C<$output> parameter
477
478The parameter C<$output> is used to control the destination of the
479uncompressed data. This parameter can take one of these forms.
480
481=over 5
482
483=item A filename
484
485If the C<$output> parameter is a simple scalar, it is assumed to be a
486filename. This file will be opened for writing and the uncompressed
487data will be written to it.
488
489=item A filehandle
490
491If the C<$output> parameter is a filehandle, the uncompressed data
492will be written to it.
493The string '-' can be used as an alias for standard output.
494
495
496=item A scalar reference
497
498If C<$output> is a scalar reference, the uncompressed data will be
499stored in C<$$output>.
500
501
502
503=item An Array Reference
504
505If C<$output> is an array reference, the uncompressed data will be
506pushed onto the array.
507
508=item An Output FileGlob
509
510If C<$output> is a string that is delimited by the characters "<" and ">"
511C<rawinflate> will assume that it is an I<output fileglob string>. The
512output is the list of files that match the fileglob.
513
514When C<$output> is an fileglob string, C<$input> must also be a fileglob
515string. Anything else is an error.
516
517=back
518
519If the C<$output> parameter is any other type, C<undef> will be returned.
520
521
522
523=head2 Notes
524
525
526When C<$input> maps to multiple compressed files/buffers and C<$output> is
527a single file/buffer, after uncompression C<$output> will contain a
528concatenation of all the uncompressed data from each of the input
529files/buffers.
530
531
532
533
534
535=head2 Optional Parameters
536
537Unless specified below, the optional parameters for C<rawinflate>,
538C<OPTS>, are the same as those used with the OO interface defined in the
539L</"Constructor Options"> section below.
540
541=over 5
542
543=item C<< AutoClose => 0|1 >>
544
545This option applies to any input or output data streams to
546C<rawinflate> that are filehandles.
547
548If C<AutoClose> is specified, and the value is true, it will result in all
549input and/or output filehandles being closed once C<rawinflate> has
550completed.
551
552This parameter defaults to 0.
553
554
555=item C<< BinModeOut => 0|1 >>
556
557When writing to a file or filehandle, set C<binmode> before writing to the
558file.
559
560Defaults to 0.
561
562
563
564
565
566=item C<< Append => 0|1 >>
567
568TODO
569
570=item C<< MultiStream => 0|1 >>
571
572
573
574This option is a no-op.
575
576
577
578
579
580=item C<< TrailingData => $scalar >>
581
582Returns the data, if any, that is present immediately after the compressed
583data stream once uncompression is complete.
584
585This option can be used when there is useful information immediately
586following the compressed data stream, and you don't know the length of the
587compressed data stream.
588
589If the input is a buffer, C<trailingData> will return everything from the
590end of the compressed data stream to the end of the buffer.
591
592If the input is a filehandle, C<trailingData> will return the data that is
593left in the filehandle input buffer once the end of the compressed data
594stream has been reached. You can then use the filehandle to read the rest
595of the input file.
596
597Don't bother using C<trailingData> if the input is a filename.
598
599
600
601If you know the length of the compressed data stream before you start
602uncompressing, you can avoid having to use C<trailingData> by setting the
603C<InputLength> option.
604
605
606
607=back
608
609
610
611
612=head2 Examples
613
614To read the contents of the file C<file1.txt.1951> and write the
615compressed 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
627To read from an existing Perl filehandle, C<$input>, and write the
628uncompressed 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
641To 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
650and 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
668The 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
674Returns an C<IO::Uncompress::RawInflate> object on success and undef on failure.
675The variable C<$RawInflateError> will contain an error message on failure.
676
677If you are running Perl 5.005 or better the object, C<$z>, returned from
678IO::Uncompress::RawInflate can be used exactly like an L<IO::File|IO::File> filehandle.
679This means that all normal input file operations can be carried out with
680C<$z>. For example, to read a line from a compressed file/buffer you can
681use either of these forms
682
683 $line = $z->getline();
684 $line = <$z>;
685
686The mandatory parameter C<$input> is used to determine the source of the
687compressed data. This parameter can take one of three forms.
688
689=over 5
690
691=item A filename
692
693If the C<$input> parameter is a scalar, it is assumed to be a filename. This
694file will be opened for reading and the compressed data will be read from it.
695
696=item A filehandle
697
698If the C<$input> parameter is a filehandle, the compressed data will be
699read from it.
700The string '-' can be used as an alias for standard input.
701
702
703=item A scalar reference
704
705If C<$input> is a scalar reference, the compressed data will be read from
706C<$$output>.
707
708=back
709
710=head2 Constructor Options
711
712
713The option names defined below are case insensitive and can be optionally
714prefixed by a '-'. So all of the following are valid
715
716 -AutoClose
717 -autoclose
718 AUTOCLOSE
719 autoclose
720
721OPTS is a combination of the following options:
722
723=over 5
724
725=item C<< AutoClose => 0|1 >>
726
727This option is only valid when the C<$input> parameter is a filehandle. If
728specified, and the value is true, it will result in the file being closed once
729either the C<close> method is called or the IO::Uncompress::RawInflate object is
730destroyed.
731
732This parameter defaults to 0.
733
734=item C<< MultiStream => 0|1 >>
735
736
737
738Allows multiple concatenated compressed streams to be treated as a single
739compressed stream. Decompression will stop once either the end of the
740file/buffer is reached, an error is encountered (premature eof, corrupt
741compressed data) or the end of a stream is not immediately followed by the
742start of another stream.
743
744This parameter defaults to 0.
745
746
747=item C<< Prime => $string >>
748
749This option will uncompress the contents of C<$string> before processing the
750input file/buffer.
751
752This option can be useful when the compressed data is embedded in another
753file/data structure and it is not possible to work out where the compressed
754data begins without having to read the first few bytes. If this is the
755case, the uncompression can be I<primed> with these bytes using this
756option.
757
758=item C<< Transparent => 0|1 >>
759
760If this option is set and the input file/buffer is not compressed data,
761the module will allow reading of it anyway.
762
763In addition, if the input file/buffer does contain compressed data and
764there is non-compressed data immediately following it, setting this option
765will make this module treat the whole file/bufffer as a single data stream.
766
767This option defaults to 1.
768
769=item C<< BlockSize => $num >>
770
771When reading the compressed input data, IO::Uncompress::RawInflate will read it in
772blocks of C<$num> bytes.
773
774This option defaults to 4096.
775
776=item C<< InputLength => $size >>
777
778When present this option will limit the number of compressed bytes read
779from the input file/buffer to C<$size>. This option can be used in the
780situation where there is useful data directly after the compressed data
781stream and you know beforehand the exact length of the compressed data
782stream.
783
784This option is mostly used when reading from a filehandle, in which case
785the file pointer will be left pointing to the first byte directly after the
786compressed data stream.
787
788
789
790This option defaults to off.
791
792=item C<< Append => 0|1 >>
793
794This option controls what the C<read> method does with uncompressed data.
795
796If set to 1, all uncompressed data will be appended to the output parameter
797of the C<read> method.
798
799If set to 0, the contents of the output parameter of the C<read> method
800will be overwritten by the uncompressed data.
801
802Defaults to 0.
803
804=item C<< Strict => 0|1 >>
805
806
807
808This option is a no-op.
809
810
811
812
813
814
815
816=back
817
818=head2 Examples
819
820TODO
821
822=head1 Methods
823
824=head2 read
825
826Usage is
827
828 $status = $z->read($buffer)
829
830Reads a block of compressed data (the size the the compressed block is
831determined by the C<Buffer> option in the constructor), uncompresses it and
832writes any uncompressed data into C<$buffer>. If the C<Append> parameter is
833set in the constructor, the uncompressed data will be appended to the
834C<$buffer> parameter. Otherwise C<$buffer> will be overwritten.
835
836Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
837or a negative number on error.
838
839=head2 read
840
841Usage 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
849Attempt to read C<$length> bytes of uncompressed data into C<$buffer>.
850
851The main difference between this form of the C<read> method and the
852previous one, is that this one will attempt to return I<exactly> C<$length>
853bytes. The only circumstances that this function will not is if end-of-file
854or an IO error is encountered.
855
856Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
857or a negative number on error.
858
859
860=head2 getline
861
862Usage is
863
864 $line = $z->getline()
865 $line = <$z>
866
867Reads a single line.
868
869This method fully supports the use of of the variable C<$/> (or
870C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use) to
871determine what constitutes an end of line. Paragraph mode, record mode and
872file slurp mode are all supported.
873
874
875=head2 getc
876
877Usage is
878
879 $char = $z->getc()
880
881Read a single character.
882
883=head2 ungetc
884
885Usage is
886
887 $char = $z->ungetc($string)
888
889
890
891=head2 inflateSync
892
893Usage is
894
895 $status = $z->inflateSync()
896
897TODO
898
899
900=head2 getHeaderInfo
901
902Usage is
903
904 $hdr = $z->getHeaderInfo();
905 @hdrs = $z->getHeaderInfo();
906
907This method returns either a hash reference (in scalar context) or a list
908or hash references (in array context) that contains information about each
909of the header fields in the compressed data stream(s).
910
911
912
913
914=head2 tell
915
916Usage is
917
918 $z->tell()
919 tell $z
920
921Returns the uncompressed file offset.
922
923=head2 eof
924
925Usage is
926
927 $z->eof();
928 eof($z);
929
930
931
932Returns 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
944Provides a sub-set of the C<seek> functionality, with the restriction
945that it is only legal to seek forward in the input file/buffer.
946It is a fatal error to attempt to seek backward.
947
948
949
950The C<$whence> parameter takes one the usual values, namely SEEK_SET,
951SEEK_CUR or SEEK_END.
952
953Returns 1 on success, 0 on failure.
954
955=head2 binmode
956
957Usage is
958
959 $z->binmode
960 binmode $z ;
961
962This is a noop provided for completeness.
963
964=head2 opened
965
966 $z->opened()
967
968Returns 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
975If the C<$z> object is associated with a file or a filehandle, this method
976returns the current autoflush setting for the underlying filehandle. If
977C<EXPR> is present, and is non-zero, it will enable flushing after every
978write/print operation.
979
980If C<$z> is associated with a buffer, this method has no effect and always
981returns C<undef>.
982
983B<Note> that the special variable C<$|> B<cannot> be used to set or
984retrieve the autoflush setting.
985
986=head2 input_line_number
987
988 $z->input_line_number()
989 $z->input_line_number(EXPR)
990
991
992
993Returns the current uncompressed line number. If C<EXPR> is present it has
994the effect of setting the line number. Note that setting the line number
995does not change the current position within the file/buffer being read.
996
997The contents of C<$/> are used to to determine what constitutes a line
998terminator.
999
1000
1001
1002=head2 fileno
1003
1004 $z->fileno()
1005 fileno($z)
1006
1007If the C<$z> object is associated with a file or a filehandle, this method
1008will return the underlying file descriptor.
1009
1010If the C<$z> object is is associated with a buffer, this method will
1011return undef.
1012
1013=head2 close
1014
1015 $z->close() ;
1016 close $z ;
1017
1018
1019
1020Closes the output file/buffer.
1021
1022
1023
1024For most versions of Perl this method will be automatically invoked if
1025the IO::Uncompress::RawInflate object is destroyed (either explicitly or by the
1026variable with the reference to the object going out of scope). The
1027exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
1028these cases, the C<close> method will be called automatically, but
1029not until global destruction of all live objects when the program is
1030terminating.
1031
1032Therefore, if you want your scripts to be able to run on all versions
1033of Perl, you should call C<close> explicitly and not rely on automatic
1034closing.
1035
1036Returns true on success, otherwise 0.
1037
1038If the C<AutoClose> option has been enabled when the IO::Uncompress::RawInflate
1039object was created, and the object is associated with a file, the
1040underlying file will also be closed.
1041
1042
1043
1044
1045=head2 nextStream
1046
1047Usage is
1048
1049 my $status = $z->nextStream();
1050
1051Skips to the next compressed data stream in the input file/buffer. If a new
1052compressed data stream is found, the eof marker will be cleared and C<$.>
1053will be reset to 0.
1054
1055Returns 1 if a new stream was found, 0 if none was found, and -1 if an
1056error was encountered.
1057
1058=head2 trailingData
1059
1060Usage is
1061
1062 my $data = $z->trailingData();
1063
1064Returns the data, if any, that is present immediately after the compressed
1065data stream once uncompression is complete. It only makes sense to call
1066this method once the end of the compressed data stream has been
1067encountered.
1068
1069This option can be used when there is useful information immediately
1070following the compressed data stream, and you don't know the length of the
1071compressed data stream.
1072
1073If the input is a buffer, C<trailingData> will return everything from the
1074end of the compressed data stream to the end of the buffer.
1075
1076If the input is a filehandle, C<trailingData> will return the data that is
1077left in the filehandle input buffer once the end of the compressed data
1078stream has been reached. You can then use the filehandle to read the rest
1079of the input file.
1080
1081Don't bother using C<trailingData> if the input is a filename.
1082
1083
1084
1085If you know the length of the compressed data stream before you start
1086uncompressing, you can avoid having to use C<trailingData> by setting the
1087C<InputLength> option in the constructor.
1088
1089=head1 Importing
1090
1091No symbolic constants are required by this IO::Uncompress::RawInflate at present.
1092
1093=over 5
1094
1095=item :all
1096
1097Imports C<rawinflate> and C<$RawInflateError>.
1098Same 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
1111L<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
1113L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1114
1115L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1116L<Archive::Tar|Archive::Tar>,
1117L<IO::Zlib|IO::Zlib>
1118
1119
1120For RFC 1950, 1951 and 1952 see
1121F<http://www.faqs.org/rfcs/rfc1950.html>,
1122F<http://www.faqs.org/rfcs/rfc1951.html> and
1123F<http://www.faqs.org/rfcs/rfc1952.html>
1124
1125The I<zlib> compression library was written by Jean-loup Gailly
1126F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1127
1128The primary site for the I<zlib> compression library is
1129F<http://www.zlib.org>.
1130
1131The primary site for gzip is F<http://www.gzip.org>.
1132
1133
1134
1135
1136=head1 AUTHOR
1137
1138This module was written by Paul Marquess, F<pmqs@cpan.org>.
1139
1140
1141
1142=head1 MODIFICATION HISTORY
1143
1144See the Changes file.
1145
1146=head1 COPYRIGHT AND LICENSE
1147
1148Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
1149
1150This program is free software; you can redistribute it and/or
1151modify it under the same terms as Perl itself.
1152