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