Update IO-Compress to CPAN version 2.069
[perl.git] / cpan / IO-Compress / lib / IO / Uncompress / Bunzip2.pm
1 package IO::Uncompress::Bunzip2 ;
2
3 use strict ;
4 use warnings;
5 use bytes;
6
7 use IO::Compress::Base::Common 2.069 qw(:Status );
8
9 use IO::Uncompress::Base 2.069 ;
10 use IO::Uncompress::Adapter::Bunzip2 2.069 ;
11
12 require Exporter ;
13 our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $Bunzip2Error);
14
15 $VERSION = '2.069';
16 $Bunzip2Error = '';
17
18 @ISA    = qw( Exporter IO::Uncompress::Base );
19 @EXPORT_OK = qw( $Bunzip2Error bunzip2 ) ;
20 #%EXPORT_TAGS = %IO::Uncompress::Base::EXPORT_TAGS ;
21 push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
22 #Exporter::export_ok_tags('all');
23
24
25 sub new
26 {
27     my $class = shift ;
28     my $obj = IO::Compress::Base::Common::createSelfTiedObject($class, \$Bunzip2Error);
29
30     $obj->_create(undef, 0, @_);
31 }
32
33 sub bunzip2
34 {
35     my $obj = IO::Compress::Base::Common::createSelfTiedObject(undef, \$Bunzip2Error);
36     return $obj->_inf(@_);
37 }
38
39 sub getExtraParams
40 {
41     return (
42             'verbosity'     => [IO::Compress::Base::Common::Parse_boolean,   0],
43             'small'         => [IO::Compress::Base::Common::Parse_boolean,   0],
44         );
45 }
46
47
48 sub ckParams
49 {
50     my $self = shift ;
51     my $got = shift ;
52
53     return 1;
54 }
55
56 sub mkUncomp
57 {
58     my $self = shift ;
59     my $got = shift ;
60
61      my $magic = $self->ckMagic()
62         or return 0;
63
64     *$self->{Info} = $self->readHeader($magic)
65         or return undef ;
66
67     my $Small     = $got->getValue('small');
68     my $Verbosity = $got->getValue('verbosity');
69
70     my ($obj, $errstr, $errno) =  IO::Uncompress::Adapter::Bunzip2::mkUncompObject(
71                                                     $Small, $Verbosity);
72
73     return $self->saveErrorString(undef, $errstr, $errno)
74         if ! defined $obj;
75     
76     *$self->{Uncomp} = $obj;
77
78     return 1;
79
80 }
81
82
83 sub ckMagic
84 {
85     my $self = shift;
86
87     my $magic ;
88     $self->smartReadExact(\$magic, 4);
89
90     *$self->{HeaderPending} = $magic ;
91     
92     return $self->HeaderError("Header size is " . 
93                                         4 . " bytes") 
94         if length $magic != 4;
95
96     return $self->HeaderError("Bad Magic.")
97         if ! isBzip2Magic($magic) ;
98                       
99         
100     *$self->{Type} = 'bzip2';
101     return $magic;
102 }
103
104 sub readHeader
105 {
106     my $self = shift;
107     my $magic = shift ;
108
109     $self->pushBack($magic);
110     *$self->{HeaderPending} = '';
111
112
113     return {
114         'Type'              => 'bzip2',
115         'FingerprintLength' => 4,
116         'HeaderLength'      => 4,
117         'TrailerLength'     => 0,
118         'Header'            => '$magic'
119         };
120     
121 }
122
123 sub chkTrailer
124 {
125     return STATUS_OK;
126 }
127
128
129
130 sub isBzip2Magic
131 {
132     my $buffer = shift ;
133     return $buffer =~ /^BZh\d$/;
134 }
135
136 1 ;
137
138 __END__
139
140
141 =head1 NAME
142
143 IO::Uncompress::Bunzip2 - Read bzip2 files/buffers
144
145 =head1 SYNOPSIS
146
147     use IO::Uncompress::Bunzip2 qw(bunzip2 $Bunzip2Error) ;
148
149     my $status = bunzip2 $input => $output [,OPTS]
150         or die "bunzip2 failed: $Bunzip2Error\n";
151
152     my $z = new IO::Uncompress::Bunzip2 $input [OPTS] 
153         or die "bunzip2 failed: $Bunzip2Error\n";
154
155     $status = $z->read($buffer)
156     $status = $z->read($buffer, $length)
157     $status = $z->read($buffer, $length, $offset)
158     $line = $z->getline()
159     $char = $z->getc()
160     $char = $z->ungetc()
161     $char = $z->opened()
162
163     $data = $z->trailingData()
164     $status = $z->nextStream()
165     $data = $z->getHeaderInfo()
166     $z->tell()
167     $z->seek($position, $whence)
168     $z->binmode()
169     $z->fileno()
170     $z->eof()
171     $z->close()
172
173     $Bunzip2Error ;
174
175     # IO::File mode
176
177     <$z>
178     read($z, $buffer);
179     read($z, $buffer, $length);
180     read($z, $buffer, $length, $offset);
181     tell($z)
182     seek($z, $position, $whence)
183     binmode($z)
184     fileno($z)
185     eof($z)
186     close($z)
187
188 =head1 DESCRIPTION
189
190 This module provides a Perl interface that allows the reading of
191 bzip2 files/buffers.
192
193 For writing bzip2 files/buffers, see the companion module IO::Compress::Bzip2.
194
195 =head1 Functional Interface
196
197 A top-level function, C<bunzip2>, is provided to carry out
198 "one-shot" uncompression between buffers and/or files. For finer
199 control over the uncompression process, see the L</"OO Interface">
200 section.
201
202     use IO::Uncompress::Bunzip2 qw(bunzip2 $Bunzip2Error) ;
203
204     bunzip2 $input_filename_or_reference => $output_filename_or_reference [,OPTS] 
205         or die "bunzip2 failed: $Bunzip2Error\n";
206
207 The functional interface needs Perl5.005 or better.
208
209 =head2 bunzip2 $input_filename_or_reference => $output_filename_or_reference [, OPTS]
210
211 C<bunzip2> expects at least two parameters,
212 C<$input_filename_or_reference> and C<$output_filename_or_reference>.
213
214 =head3 The C<$input_filename_or_reference> parameter
215
216 The parameter, C<$input_filename_or_reference>, is used to define the
217 source of the compressed data. 
218
219 It can take one of the following forms:
220
221 =over 5
222
223 =item A filename
224
225 If the <$input_filename_or_reference> parameter is a simple scalar, it is
226 assumed to be a filename. This file will be opened for reading and the
227 input data will be read from it.
228
229 =item A filehandle
230
231 If the C<$input_filename_or_reference> parameter is a filehandle, the input
232 data will be read from it.  The string '-' can be used as an alias for
233 standard input.
234
235 =item A scalar reference 
236
237 If C<$input_filename_or_reference> is a scalar reference, the input data
238 will be read from C<$$input_filename_or_reference>.
239
240 =item An array reference 
241
242 If C<$input_filename_or_reference> is an array reference, each element in
243 the array must be a filename.
244
245 The input data will be read from each file in turn. 
246
247 The complete array will be walked to ensure that it only
248 contains valid filenames before any data is uncompressed.
249
250 =item An Input FileGlob string
251
252 If C<$input_filename_or_reference> is a string that is delimited by the
253 characters "<" and ">" C<bunzip2> will assume that it is an 
254 I<input fileglob string>. The input is the list of files that match the 
255 fileglob.
256
257 See L<File::GlobMapper|File::GlobMapper> for more details.
258
259 =back
260
261 If the C<$input_filename_or_reference> parameter is any other type,
262 C<undef> will be returned.
263
264 =head3 The C<$output_filename_or_reference> parameter
265
266 The parameter C<$output_filename_or_reference> is used to control the
267 destination of the uncompressed data. This parameter can take one of
268 these forms.
269
270 =over 5
271
272 =item A filename
273
274 If the C<$output_filename_or_reference> parameter is a simple scalar, it is
275 assumed to be a filename.  This file will be opened for writing and the 
276 uncompressed data will be written to it.
277
278 =item A filehandle
279
280 If the C<$output_filename_or_reference> parameter is a filehandle, the
281 uncompressed data will be written to it.  The string '-' can be used as
282 an alias for standard output.
283
284 =item A scalar reference 
285
286 If C<$output_filename_or_reference> is a scalar reference, the
287 uncompressed data will be stored in C<$$output_filename_or_reference>.
288
289 =item An Array Reference
290
291 If C<$output_filename_or_reference> is an array reference, 
292 the uncompressed data will be pushed onto the array.
293
294 =item An Output FileGlob
295
296 If C<$output_filename_or_reference> is a string that is delimited by the
297 characters "<" and ">" C<bunzip2> will assume that it is an
298 I<output fileglob string>. The output is the list of files that match the
299 fileglob.
300
301 When C<$output_filename_or_reference> is an fileglob string,
302 C<$input_filename_or_reference> must also be a fileglob string. Anything
303 else is an error.
304
305 See L<File::GlobMapper|File::GlobMapper> for more details.
306
307 =back
308
309 If the C<$output_filename_or_reference> parameter is any other type,
310 C<undef> will be returned.
311
312 =head2 Notes
313
314 When C<$input_filename_or_reference> maps to multiple compressed
315 files/buffers and C<$output_filename_or_reference> is
316 a single file/buffer, after uncompression C<$output_filename_or_reference> will contain a
317 concatenation of all the uncompressed data from each of the input
318 files/buffers.
319
320 =head2 Optional Parameters
321
322 Unless specified below, the optional parameters for C<bunzip2>,
323 C<OPTS>, are the same as those used with the OO interface defined in the
324 L</"Constructor Options"> section below.
325
326 =over 5
327
328 =item C<< AutoClose => 0|1 >>
329
330 This option applies to any input or output data streams to 
331 C<bunzip2> that are filehandles.
332
333 If C<AutoClose> is specified, and the value is true, it will result in all
334 input and/or output filehandles being closed once C<bunzip2> has
335 completed.
336
337 This parameter defaults to 0.
338
339 =item C<< BinModeOut => 0|1 >>
340
341 When writing to a file or filehandle, set C<binmode> before writing to the
342 file.
343
344 Defaults to 0.
345
346 =item C<< Append => 0|1 >>
347
348 The behaviour of this option is dependent on the type of output data
349 stream.
350
351 =over 5
352
353 =item * A Buffer
354
355 If C<Append> is enabled, all uncompressed data will be append to the end of
356 the output buffer. Otherwise the output buffer will be cleared before any
357 uncompressed data is written to it.
358
359 =item * A Filename
360
361 If C<Append> is enabled, the file will be opened in append mode. Otherwise
362 the contents of the file, if any, will be truncated before any uncompressed
363 data is written to it.
364
365 =item * A Filehandle
366
367 If C<Append> is enabled, the filehandle will be positioned to the end of
368 the file via a call to C<seek> before any uncompressed data is
369 written to it.  Otherwise the file pointer will not be moved.
370
371 =back
372
373 When C<Append> is specified, and set to true, it will I<append> all uncompressed 
374 data to the output data stream.
375
376 So when the output is a filehandle it will carry out a seek to the eof
377 before writing any uncompressed data. If the output is a filename, it will be opened for
378 appending. If the output is a buffer, all uncompressed data will be
379 appended to the existing buffer.
380
381 Conversely when C<Append> is not specified, or it is present and is set to
382 false, it will operate as follows.
383
384 When the output is a filename, it will truncate the contents of the file
385 before writing any uncompressed data. If the output is a filehandle
386 its position will not be changed. If the output is a buffer, it will be
387 wiped before any uncompressed data is output.
388
389 Defaults to 0.
390
391 =item C<< MultiStream => 0|1 >>
392
393 If the input file/buffer contains multiple compressed data streams, this
394 option will uncompress the whole lot as a single data stream.
395
396 Defaults to 0.
397
398 =item C<< TrailingData => $scalar >>
399
400 Returns the data, if any, that is present immediately after the compressed
401 data stream once uncompression is complete. 
402
403 This option can be used when there is useful information immediately
404 following the compressed data stream, and you don't know the length of the
405 compressed data stream.
406
407 If the input is a buffer, C<trailingData> will return everything from the
408 end of the compressed data stream to the end of the buffer.
409
410 If the input is a filehandle, C<trailingData> will return the data that is
411 left in the filehandle input buffer once the end of the compressed data
412 stream has been reached. You can then use the filehandle to read the rest
413 of the input file. 
414
415 Don't bother using C<trailingData> if the input is a filename.
416
417 If you know the length of the compressed data stream before you start
418 uncompressing, you can avoid having to use C<trailingData> by setting the
419 C<InputLength> option.
420
421 =back
422
423 =head2 Examples
424
425 To read the contents of the file C<file1.txt.bz2> and write the
426 uncompressed data to the file C<file1.txt>.
427
428     use strict ;
429     use warnings ;
430     use IO::Uncompress::Bunzip2 qw(bunzip2 $Bunzip2Error) ;
431
432     my $input = "file1.txt.bz2";
433     my $output = "file1.txt";
434     bunzip2 $input => $output
435         or die "bunzip2 failed: $Bunzip2Error\n";
436
437 To read from an existing Perl filehandle, C<$input>, and write the
438 uncompressed data to a buffer, C<$buffer>.
439
440     use strict ;
441     use warnings ;
442     use IO::Uncompress::Bunzip2 qw(bunzip2 $Bunzip2Error) ;
443     use IO::File ;
444
445     my $input = new IO::File "<file1.txt.bz2"
446         or die "Cannot open 'file1.txt.bz2': $!\n" ;
447     my $buffer ;
448     bunzip2 $input => \$buffer 
449         or die "bunzip2 failed: $Bunzip2Error\n";
450
451 To uncompress all files in the directory "/my/home" that match "*.txt.bz2" and store the compressed data in the same directory
452
453     use strict ;
454     use warnings ;
455     use IO::Uncompress::Bunzip2 qw(bunzip2 $Bunzip2Error) ;
456
457     bunzip2 '</my/home/*.txt.bz2>' => '</my/home/#1.txt>'
458         or die "bunzip2 failed: $Bunzip2Error\n";
459
460 and if you want to compress each file one at a time, this will do the trick
461
462     use strict ;
463     use warnings ;
464     use IO::Uncompress::Bunzip2 qw(bunzip2 $Bunzip2Error) ;
465
466     for my $input ( glob "/my/home/*.txt.bz2" )
467     {
468         my $output = $input;
469         $output =~ s/.bz2// ;
470         bunzip2 $input => $output 
471             or die "Error compressing '$input': $Bunzip2Error\n";
472     }
473
474 =head1 OO Interface
475
476 =head2 Constructor
477
478 The format of the constructor for IO::Uncompress::Bunzip2 is shown below
479
480     my $z = new IO::Uncompress::Bunzip2 $input [OPTS]
481         or die "IO::Uncompress::Bunzip2 failed: $Bunzip2Error\n";
482
483 Returns an C<IO::Uncompress::Bunzip2> object on success and undef on failure.
484 The variable C<$Bunzip2Error> will contain an error message on failure.
485
486 If you are running Perl 5.005 or better the object, C<$z>, returned from
487 IO::Uncompress::Bunzip2 can be used exactly like an L<IO::File|IO::File> filehandle.
488 This means that all normal input file operations can be carried out with
489 C<$z>.  For example, to read a line from a compressed file/buffer you can
490 use either of these forms
491
492     $line = $z->getline();
493     $line = <$z>;
494
495 The mandatory parameter C<$input> is used to determine the source of the
496 compressed data. This parameter can take one of three forms.
497
498 =over 5
499
500 =item A filename
501
502 If the C<$input> parameter is a scalar, it is assumed to be a filename. This
503 file will be opened for reading and the compressed data will be read from it.
504
505 =item A filehandle
506
507 If the C<$input> parameter is a filehandle, the compressed data will be
508 read from it.
509 The string '-' can be used as an alias for standard input.
510
511 =item A scalar reference 
512
513 If C<$input> is a scalar reference, the compressed data will be read from
514 C<$$input>.
515
516 =back
517
518 =head2 Constructor Options
519
520 The option names defined below are case insensitive and can be optionally
521 prefixed by a '-'.  So all of the following are valid
522
523     -AutoClose
524     -autoclose
525     AUTOCLOSE
526     autoclose
527
528 OPTS is a combination of the following options:
529
530 =over 5
531
532 =item C<< AutoClose => 0|1 >>
533
534 This option is only valid when the C<$input> parameter is a filehandle. If
535 specified, and the value is true, it will result in the file being closed once
536 either the C<close> method is called or the IO::Uncompress::Bunzip2 object is
537 destroyed.
538
539 This parameter defaults to 0.
540
541 =item C<< MultiStream => 0|1 >>
542
543 Allows multiple concatenated compressed streams to be treated as a single
544 compressed stream. Decompression will stop once either the end of the
545 file/buffer is reached, an error is encountered (premature eof, corrupt
546 compressed data) or the end of a stream is not immediately followed by the
547 start of another stream.
548
549 This parameter defaults to 0.
550
551 =item C<< Prime => $string >>
552
553 This option will uncompress the contents of C<$string> before processing the
554 input file/buffer.
555
556 This option can be useful when the compressed data is embedded in another
557 file/data structure and it is not possible to work out where the compressed
558 data begins without having to read the first few bytes. If this is the
559 case, the uncompression can be I<primed> with these bytes using this
560 option.
561
562 =item C<< Transparent => 0|1 >>
563
564 If this option is set and the input file/buffer is not compressed data,
565 the module will allow reading of it anyway.
566
567 In addition, if the input file/buffer does contain compressed data and
568 there is non-compressed data immediately following it, setting this option
569 will make this module treat the whole file/buffer as a single data stream.
570
571 This option defaults to 1.
572
573 =item C<< BlockSize => $num >>
574
575 When reading the compressed input data, IO::Uncompress::Bunzip2 will read it in
576 blocks of C<$num> bytes.
577
578 This option defaults to 4096.
579
580 =item C<< InputLength => $size >>
581
582 When present this option will limit the number of compressed bytes read
583 from the input file/buffer to C<$size>. This option can be used in the
584 situation where there is useful data directly after the compressed data
585 stream and you know beforehand the exact length of the compressed data
586 stream. 
587
588 This option is mostly used when reading from a filehandle, in which case
589 the file pointer will be left pointing to the first byte directly after the
590 compressed data stream.
591
592 This option defaults to off.
593
594 =item C<< Append => 0|1 >>
595
596 This option controls what the C<read> method does with uncompressed data.
597
598 If set to 1, all uncompressed data will be appended to the output parameter
599 of the C<read> method.
600
601 If set to 0, the contents of the output parameter of the C<read> method
602 will be overwritten by the uncompressed data.
603
604 Defaults to 0.
605
606 =item C<< Strict => 0|1 >>
607
608 This option is a no-op.
609
610 =item C<< Small => 0|1 >>
611
612 When non-zero this options will make bzip2 use a decompression algorithm
613 that uses less memory at the expense of increasing the amount of time
614 taken for decompression. 
615
616 Default is 0.
617
618 =back
619
620 =head2 Examples
621
622 TODO
623
624 =head1 Methods 
625
626 =head2 read
627
628 Usage is
629
630     $status = $z->read($buffer)
631
632 Reads a block of compressed data (the size of the compressed block is
633 determined by the C<Buffer> option in the constructor), uncompresses it and
634 writes any uncompressed data into C<$buffer>. If the C<Append> parameter is
635 set in the constructor, the uncompressed data will be appended to the
636 C<$buffer> parameter. Otherwise C<$buffer> will be overwritten.
637
638 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
639 or a negative number on error.
640
641 =head2 read
642
643 Usage is
644
645     $status = $z->read($buffer, $length)
646     $status = $z->read($buffer, $length, $offset)
647
648     $status = read($z, $buffer, $length)
649     $status = read($z, $buffer, $length, $offset)
650
651 Attempt to read C<$length> bytes of uncompressed data into C<$buffer>.
652
653 The main difference between this form of the C<read> method and the
654 previous one, is that this one will attempt to return I<exactly> C<$length>
655 bytes. The only circumstances that this function will not is if end-of-file
656 or an IO error is encountered.
657
658 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
659 or a negative number on error.
660
661 =head2 getline
662
663 Usage is
664
665     $line = $z->getline()
666     $line = <$z>
667
668 Reads a single line. 
669
670 This method fully supports the use of the variable C<$/> (or
671 C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use) to
672 determine what constitutes an end of line. Paragraph mode, record mode and
673 file slurp mode are all supported. 
674
675 =head2 getc
676
677 Usage is 
678
679     $char = $z->getc()
680
681 Read a single character.
682
683 =head2 ungetc
684
685 Usage is
686
687     $char = $z->ungetc($string)
688
689 =head2 getHeaderInfo
690
691 Usage is
692
693     $hdr  = $z->getHeaderInfo();
694     @hdrs = $z->getHeaderInfo();
695
696 This method returns either a hash reference (in scalar context) or a list
697 or hash references (in array context) that contains information about each
698 of the header fields in the compressed data stream(s).
699
700 =head2 tell
701
702 Usage is
703
704     $z->tell()
705     tell $z
706
707 Returns the uncompressed file offset.
708
709 =head2 eof
710
711 Usage is
712
713     $z->eof();
714     eof($z);
715
716 Returns true if the end of the compressed input stream has been reached.
717
718 =head2 seek
719
720     $z->seek($position, $whence);
721     seek($z, $position, $whence);
722
723 Provides a sub-set of the C<seek> functionality, with the restriction
724 that it is only legal to seek forward in the input file/buffer.
725 It is a fatal error to attempt to seek backward.
726
727 Note that the implementation of C<seek> in this module does not provide
728 true random access to a compressed file/buffer. It  works by uncompressing
729 data from the current offset in the file/buffer until it reaches the
730 uncompressed offset specified in the parameters to C<seek>. For very small
731 files this may be acceptable behaviour. For large files it may cause an
732 unacceptable delay.
733
734 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
735 SEEK_CUR or SEEK_END.
736
737 Returns 1 on success, 0 on failure.
738
739 =head2 binmode
740
741 Usage is
742
743     $z->binmode
744     binmode $z ;
745
746 This is a noop provided for completeness.
747
748 =head2 opened
749
750     $z->opened()
751
752 Returns true if the object currently refers to a opened file/buffer. 
753
754 =head2 autoflush
755
756     my $prev = $z->autoflush()
757     my $prev = $z->autoflush(EXPR)
758
759 If the C<$z> object is associated with a file or a filehandle, this method
760 returns the current autoflush setting for the underlying filehandle. If
761 C<EXPR> is present, and is non-zero, it will enable flushing after every
762 write/print operation.
763
764 If C<$z> is associated with a buffer, this method has no effect and always
765 returns C<undef>.
766
767 B<Note> that the special variable C<$|> B<cannot> be used to set or
768 retrieve the autoflush setting.
769
770 =head2 input_line_number
771
772     $z->input_line_number()
773     $z->input_line_number(EXPR)
774
775 Returns the current uncompressed line number. If C<EXPR> is present it has
776 the effect of setting the line number. Note that setting the line number
777 does not change the current position within the file/buffer being read.
778
779 The contents of C<$/> are used to determine what constitutes a line
780 terminator.
781
782 =head2 fileno
783
784     $z->fileno()
785     fileno($z)
786
787 If the C<$z> object is associated with a file or a filehandle, C<fileno>
788 will return the underlying file descriptor. Once the C<close> method is
789 called C<fileno> will return C<undef>.
790
791 If the C<$z> object is associated with a buffer, this method will return
792 C<undef>.
793
794 =head2 close
795
796     $z->close() ;
797     close $z ;
798
799 Closes the output file/buffer. 
800
801 For most versions of Perl this method will be automatically invoked if
802 the IO::Uncompress::Bunzip2 object is destroyed (either explicitly or by the
803 variable with the reference to the object going out of scope). The
804 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
805 these cases, the C<close> method will be called automatically, but
806 not until global destruction of all live objects when the program is
807 terminating.
808
809 Therefore, if you want your scripts to be able to run on all versions
810 of Perl, you should call C<close> explicitly and not rely on automatic
811 closing.
812
813 Returns true on success, otherwise 0.
814
815 If the C<AutoClose> option has been enabled when the IO::Uncompress::Bunzip2
816 object was created, and the object is associated with a file, the
817 underlying file will also be closed.
818
819 =head2 nextStream
820
821 Usage is
822
823     my $status = $z->nextStream();
824
825 Skips to the next compressed data stream in the input file/buffer. If a new
826 compressed data stream is found, the eof marker will be cleared and C<$.>
827 will be reset to 0.
828
829 Returns 1 if a new stream was found, 0 if none was found, and -1 if an
830 error was encountered.
831
832 =head2 trailingData
833
834 Usage is
835
836     my $data = $z->trailingData();
837
838 Returns the data, if any, that is present immediately after the compressed
839 data stream once uncompression is complete. It only makes sense to call
840 this method once the end of the compressed data stream has been
841 encountered.
842
843 This option can be used when there is useful information immediately
844 following the compressed data stream, and you don't know the length of the
845 compressed data stream.
846
847 If the input is a buffer, C<trailingData> will return everything from the
848 end of the compressed data stream to the end of the buffer.
849
850 If the input is a filehandle, C<trailingData> will return the data that is
851 left in the filehandle input buffer once the end of the compressed data
852 stream has been reached. You can then use the filehandle to read the rest
853 of the input file. 
854
855 Don't bother using C<trailingData> if the input is a filename.
856
857 If you know the length of the compressed data stream before you start
858 uncompressing, you can avoid having to use C<trailingData> by setting the
859 C<InputLength> option in the constructor.
860
861 =head1 Importing 
862
863 No symbolic constants are required by this IO::Uncompress::Bunzip2 at present. 
864
865 =over 5
866
867 =item :all
868
869 Imports C<bunzip2> and C<$Bunzip2Error>.
870 Same as doing this
871
872     use IO::Uncompress::Bunzip2 qw(bunzip2 $Bunzip2Error) ;
873
874 =back
875
876 =head1 EXAMPLES
877
878 =head2 Working with Net::FTP
879
880 See L<IO::Compress::FAQ|IO::Compress::FAQ/"Compressed files and Net::FTP">
881
882 =head1 SEE ALSO
883
884 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::Uncompress::RawInflate>, L<IO::Compress::Bzip2>, 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>
885
886 L<IO::Compress::FAQ|IO::Compress::FAQ>
887
888 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
889 L<Archive::Tar|Archive::Tar>,
890 L<IO::Zlib|IO::Zlib>
891
892 The primary site for the bzip2 program is F<http://www.bzip.org>.
893
894 See the module L<Compress::Bzip2|Compress::Bzip2>
895
896 =head1 AUTHOR
897
898 This module was written by Paul Marquess, F<pmqs@cpan.org>. 
899
900 =head1 MODIFICATION HISTORY
901
902 See the Changes file.
903
904 =head1 COPYRIGHT AND LICENSE
905
906 Copyright (c) 2005-2015 Paul Marquess. All rights reserved.
907
908 This program is free software; you can redistribute it and/or
909 modify it under the same terms as Perl itself.
910