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