CPAN.pm 1.9205
[p5sagit/p5-mst-13.2.git] / ext / IO_Compress_Zlib / lib / IO / Uncompress / RawInflate.pm
CommitLineData
642e522c 1package IO::Uncompress::RawInflate ;
2# for RFC1951
3
4use strict ;
5use warnings;
a02d0f6f 6use bytes;
1a6a8453 7
d56f7e4c 8use Compress::Raw::Zlib 2.006 ;
9use IO::Compress::Base::Common 2.006 qw(:Status createSelfTiedObject);
1a6a8453 10
d56f7e4c 11use IO::Uncompress::Base 2.006 ;
12use IO::Uncompress::Adapter::Inflate 2.006 ;
1a6a8453 13
14
15
642e522c 16
17require Exporter ;
1a6a8453 18our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, %DEFLATE_CONSTANTS, $RawInflateError);
642e522c 19
d56f7e4c 20$VERSION = '2.006';
642e522c 21$RawInflateError = '';
22
1a6a8453 23@ISA = qw( Exporter IO::Uncompress::Base );
642e522c 24@EXPORT_OK = qw( $RawInflateError rawinflate ) ;
1a6a8453 25%DEFLATE_CONSTANTS = ();
26%EXPORT_TAGS = %IO::Uncompress::Base::EXPORT_TAGS ;
642e522c 27push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
28Exporter::export_ok_tags('all');
29
30
31
642e522c 32sub new
33{
1a6a8453 34 my $class = shift ;
35 my $obj = createSelfTiedObject($class, \$RawInflateError);
36 $obj->_create(undef, 0, @_);
642e522c 37}
38
39sub rawinflate
40{
1a6a8453 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
a02d0f6f 64 my ($obj, $errstr, $errno) = IO::Uncompress::Adapter::Inflate::mkUncompObject(
1a6a8453 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{
a02d0f6f 109 return STATUS_OK ;
1a6a8453 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 ;
642e522c 128}
129
1a6a8453 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
e7d45986 149 #my $buf_len = *$self->{Uncomp}->uncompressedBytes();
150 my $buf_len = length $buffer;
1a6a8453 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
642e522c 3271;
328
329__END__
330
331
332=head1 NAME
333
a02d0f6f 334
cb7abd7f 335
336IO::Uncompress::RawInflate - Read RFC 1951 files/buffers
337
642e522c 338
a02d0f6f 339
642e522c 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()
a02d0f6f 356 $char = $z->opened()
357
642e522c 358 $status = $z->inflateSync()
a02d0f6f 359
e7d45986 360 $data = $z->trailingData()
361 $status = $z->nextStream()
642e522c 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
1a6a8453 390This module provides a Perl interface that allows the reading of
642e522c 391files/buffers that conform to RFC 1951.
392
1a6a8453 393For writing RFC 1951 files/buffers, see the companion module IO::Compress::RawDeflate.
642e522c 394
395
396
cb7abd7f 397
398
642e522c 399=head1 Functional Interface
400
1a6a8453 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.
642e522c 405
406 use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
407
408 rawinflate $input => $output [,OPTS]
409 or die "rawinflate failed: $RawInflateError\n";
410
1a6a8453 411
642e522c 412
413The functional interface needs Perl5.005 or better.
414
415
416=head2 rawinflate $input => $output [, OPTS]
417
1a6a8453 418
419C<rawinflate> expects at least two parameters, C<$input> and C<$output>.
642e522c 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
1a6a8453 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
642e522c 454The complete array will be walked to ensure that it only
1a6a8453 455contains valid filenames before any data is uncompressed.
456
457
642e522c 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
1a6a8453 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.
642e522c 488
489=item A filehandle
490
1a6a8453 491If the C<$output> parameter is a filehandle, the uncompressed data
492will be written to it.
642e522c 493The string '-' can be used as an alias for standard output.
494
495
496=item A scalar reference
497
1a6a8453 498If C<$output> is a scalar reference, the uncompressed data will be
499stored in C<$$output>.
642e522c 500
501
642e522c 502
503=item An Array Reference
504
1a6a8453 505If C<$output> is an array reference, the uncompressed data will be
506pushed onto the array.
642e522c 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
642e522c 521
642e522c 522
523=head2 Notes
524
c70c1701 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
642e522c 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
e7d45986 543=item C<< AutoClose => 0|1 >>
642e522c 544
1a6a8453 545This option applies to any input or output data streams to
546C<rawinflate> that are filehandles.
642e522c 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
e7d45986 555=item C<< BinModeOut => 0|1 >>
1a6a8453 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
e7d45986 566=item C<< Append => 0|1 >>
642e522c 567
568TODO
569
e7d45986 570=item C<< MultiStream => 0|1 >>
1a6a8453 571
1a6a8453 572
258133d1 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.
1a6a8453 604
642e522c 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
1a6a8453 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
642e522c 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
e7d45986 725=item C<< AutoClose => 0|1 >>
642e522c 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
e7d45986 734=item C<< MultiStream => 0|1 >>
642e522c 735
736
737
f6fd7794 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.
642e522c 743
f6fd7794 744This parameter defaults to 0.
642e522c 745
746
e7d45986 747=item C<< Prime => $string >>
642e522c 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
1a6a8453 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.
642e522c 757
e7d45986 758=item C<< Transparent => 0|1 >>
642e522c 759
f6fd7794 760If this option is set and the input file/buffer is not compressed data,
642e522c 761the module will allow reading of it anyway.
762
f6fd7794 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
642e522c 767This option defaults to 1.
768
e7d45986 769=item C<< BlockSize => $num >>
642e522c 770
1a6a8453 771When reading the compressed input data, IO::Uncompress::RawInflate will read it in
772blocks of C<$num> bytes.
642e522c 773
774This option defaults to 4096.
775
e7d45986 776=item C<< InputLength => $size >>
642e522c 777
1a6a8453 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.
642e522c 783
1a6a8453 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
642e522c 786compressed data stream.
787
788
789
790This option defaults to off.
791
e7d45986 792=item C<< Append => 0|1 >>
642e522c 793
794This option controls what the C<read> method does with uncompressed data.
795
1a6a8453 796If set to 1, all uncompressed data will be appended to the output parameter
797of the C<read> method.
642e522c 798
1a6a8453 799If set to 0, the contents of the output parameter of the C<read> method
800will be overwritten by the uncompressed data.
642e522c 801
802Defaults to 0.
803
e7d45986 804=item C<< Strict => 0|1 >>
642e522c 805
806
807
808This option is a no-op.
809
810
811
812
813
a02d0f6f 814
258133d1 815
642e522c 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
1a6a8453 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.
642e522c 835
1a6a8453 836Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
837or a negative number on error.
642e522c 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
1a6a8453 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.
642e522c 855
1a6a8453 856Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
857or a negative number on error.
642e522c 858
859
860=head2 getline
861
862Usage is
863
864 $line = $z->getline()
865 $line = <$z>
866
867Reads a single line.
868
258133d1 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.
642e522c 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
a02d0f6f 890
642e522c 891=head2 inflateSync
892
893Usage is
894
895 $status = $z->inflateSync()
896
897TODO
898
a02d0f6f 899
642e522c 900=head2 getHeaderInfo
901
902Usage is
903
1a6a8453 904 $hdr = $z->getHeaderInfo();
905 @hdrs = $z->getHeaderInfo();
642e522c 906
1a6a8453 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).
642e522c 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
a02d0f6f 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
642e522c 1002=head2 fileno
1003
1004 $z->fileno()
1005 fileno($z)
1006
a02d0f6f 1007If the C<$z> object is associated with a file or a filehandle, this method
1008will return the underlying file descriptor.
642e522c 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
e7d45986 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
258133d1 1052compressed data stream is found, the eof marker will be cleared and C<$.>
1053will be reset to 0.
e7d45986 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
258133d1 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.
e7d45986 1088
642e522c 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
258133d1 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>
642e522c 1112
1113L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1114
a02d0f6f 1115L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1116L<Archive::Tar|Archive::Tar>,
642e522c 1117L<IO::Zlib|IO::Zlib>
1118
a02d0f6f 1119
642e522c 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
a02d0f6f 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
642e522c 1136=head1 AUTHOR
1137
cb7abd7f 1138This module was written by Paul Marquess, F<pmqs@cpan.org>.
642e522c 1139
642e522c 1140
642e522c 1141
1142=head1 MODIFICATION HISTORY
1143
1144See the Changes file.
1145
1146=head1 COPYRIGHT AND LICENSE
642e522c 1147
b0cda13f 1148Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
a02d0f6f 1149
642e522c 1150This program is free software; you can redistribute it and/or
1151modify it under the same terms as Perl itself.
1152