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.061 qw(:Status );
   8
   9 use IO::Uncompress::Base 2.061 ;
  10 use IO::Uncompress::Adapter::Bunzip2 2.061 ;
  11
  12 require Exporter ;
  13 our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $Bunzip2Error);
  14
  15 $VERSION = '2.061';
  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 => $output [,OPTS]
 205         or die "bunzip2 failed: $Bunzip2Error\n";
 206
 207 The functional interface needs Perl5.005 or better.
 208
 209 =head2 bunzip2 $input => $output [, OPTS]
 210
 211 C<bunzip2> expects at least two parameters, C<$input> and C<$output>.
 212
 213 =head3 The C<$input> parameter
 214
 215 The parameter, C<$input>, is used to define the source of
 216 the compressed data.
 217
 218 It can take one of the following forms:
 219
 220 =over 5
 221
 222 =item A filename
 223
 224 If the C<$input> parameter is a simple scalar, it is assumed to be a
 225 filename. This file will be opened for reading and the input data
 226 will be read from it.
 227
 228 =item A filehandle
 229
 230 If the C<$input> parameter is a filehandle, the input data will be
 231 read from it.
 232 The string '-' can be used as an alias for standard input.
 233
 234 =item A scalar reference
 235
 236 If C<$input> is a scalar reference, the input data will be read
 237 from C<$$input>.
 238
 239 =item An array reference
 240
 241 If C<$input> is an array reference, each element in the array must be a
 242 filename.
 243
 244 The input data will be read from each file in turn.
 245
 246 The complete array will be walked to ensure that it only
 247 contains valid filenames before any data is uncompressed.
 248
 249 =item An Input FileGlob string
 250
 251 If C<$input> is a string that is delimited by the characters "<" and ">"
 252 C<bunzip2> will assume that it is an I<input fileglob string>. The
 253 input is the list of files that match the fileglob.
 254
 255 If the fileglob does not match any files ...
 256
 257 See L<File::GlobMapper|File::GlobMapper> for more details.
 258
 259 =back
 260
 261 If the C<$input> parameter is any other type, C<undef> will be returned.
 262
 263 =head3 The C<$output> parameter
 264
 265 The parameter C<$output> is used to control the destination of the
 266 uncompressed data. This parameter can take one of these forms.
 267
 268 =over 5
 269
 270 =item A filename
 271
 272 If the C<$output> parameter is a simple scalar, it is assumed to be a
 273 filename.  This file will be opened for writing and the uncompressed
 274 data will be written to it.
 275
 276 =item A filehandle
 277
 278 If the C<$output> parameter is a filehandle, the uncompressed data
 279 will be written to it.
 280 The string '-' can be used as an alias for standard output.
 281
 282 =item A scalar reference
 283
 284 If C<$output> is a scalar reference, the uncompressed data will be
 285 stored in C<$$output>.
 286
 287 =item An Array Reference
 288
 289 If C<$output> is an array reference, the uncompressed data will be
 290 pushed onto the array.
 291
 292 =item An Output FileGlob
 293
 294 If C<$output> is a string that is delimited by the characters "<" and ">"
 295 C<bunzip2> will assume that it is an I<output fileglob string>. The
 296 output is the list of files that match the fileglob.
 297
 298 When C<$output> is an fileglob string, C<$input> must also be a fileglob
 299 string. Anything else is an error.
 300
 301 =back
 302
 303 If the C<$output> parameter is any other type, C<undef> will be returned.
 304
 305 =head2 Notes
 306
 307 When C<$input> maps to multiple compressed files/buffers and C<$output> is
 308 a single file/buffer, after uncompression C<$output> will contain a
 309 concatenation of all the uncompressed data from each of the input
 310 files/buffers.
 311
 312 =head2 Optional Parameters
 313
 314 Unless specified below, the optional parameters for C<bunzip2>,
 315 C<OPTS>, are the same as those used with the OO interface defined in the
 316 L</"Constructor Options"> section below.
 317
 318 =over 5
 319
 320 =item C<< AutoClose => 0|1 >>
 321
 322 This option applies to any input or output data streams to
 323 C<bunzip2> that are filehandles.
 324
 325 If C<AutoClose> is specified, and the value is true, it will result in all
 326 input and/or output filehandles being closed once C<bunzip2> has
 327 completed.
 328
 329 This parameter defaults to 0.
 330
 331 =item C<< BinModeOut => 0|1 >>
 332
 333 When writing to a file or filehandle, set C<binmode> before writing to the
 334 file.
 335
 336 Defaults to 0.
 337
 338 =item C<< Append => 0|1 >>
 339
 340 TODO
 341
 342 =item C<< MultiStream => 0|1 >>
 343
 344 If the input file/buffer contains multiple compressed data streams, this
 345 option will uncompress the whole lot as a single data stream.
 346
 347 Defaults to 0.
 348
 349 =item C<< TrailingData => $scalar >>
 350
 351 Returns the data, if any, that is present immediately after the compressed
 352 data stream once uncompression is complete.
 353
 354 This option can be used when there is useful information immediately
 355 following the compressed data stream, and you don't know the length of the
 356 compressed data stream.
 357
 358 If the input is a buffer, C<trailingData> will return everything from the
 359 end of the compressed data stream to the end of the buffer.
 360
 361 If the input is a filehandle, C<trailingData> will return the data that is
 362 left in the filehandle input buffer once the end of the compressed data
 363 stream has been reached. You can then use the filehandle to read the rest
 364 of the input file.
 365
 366 Don't bother using C<trailingData> if the input is a filename.
 367
 368 If you know the length of the compressed data stream before you start
 369 uncompressing, you can avoid having to use C<trailingData> by setting the
 370 C<InputLength> option.
 371
 372 =back
 373
 374 =head2 Examples
 375
 376 To read the contents of the file C<file1.txt.bz2> and write the
 377 compressed data to the file C<file1.txt>.
 378
 379     use strict ;
 380     use warnings ;
 381     use IO::Uncompress::Bunzip2 qw(bunzip2 $Bunzip2Error) ;
 382
 383     my $input = "file1.txt.bz2";
 384     my $output = "file1.txt";
 385     bunzip2 $input => $output
 386         or die "bunzip2 failed: $Bunzip2Error\n";
 387
 388 To read from an existing Perl filehandle, C<$input>, and write the
 389 uncompressed data to a buffer, C<$buffer>.
 390
 391     use strict ;
 392     use warnings ;
 393     use IO::Uncompress::Bunzip2 qw(bunzip2 $Bunzip2Error) ;
 394     use IO::File ;
 395
 396     my $input = new IO::File "<file1.txt.bz2"
 397         or die "Cannot open 'file1.txt.bz2': $!\n" ;
 398     my $buffer ;
 399     bunzip2 $input => \$buffer
 400         or die "bunzip2 failed: $Bunzip2Error\n";
 401
 402 To uncompress all files in the directory "/my/home" that match "*.txt.bz2" and store the compressed data in the same directory
 403
 404     use strict ;
 405     use warnings ;
 406     use IO::Uncompress::Bunzip2 qw(bunzip2 $Bunzip2Error) ;
 407
 408     bunzip2 '</my/home/*.txt.bz2>' => '</my/home/#1.txt>'
 409         or die "bunzip2 failed: $Bunzip2Error\n";
 410
 411 and if you want to compress each file one at a time, this will do the trick
 412
 413     use strict ;
 414     use warnings ;
 415     use IO::Uncompress::Bunzip2 qw(bunzip2 $Bunzip2Error) ;
 416
 417     for my $input ( glob "/my/home/*.txt.bz2" )
 418     {
 419         my $output = $input;
 420         $output =~ s/.bz2// ;
 421         bunzip2 $input => $output
 422             or die "Error compressing '$input': $Bunzip2Error\n";
 423     }
 424
 425 =head1 OO Interface
 426
 427 =head2 Constructor
 428
 429 The format of the constructor for IO::Uncompress::Bunzip2 is shown below
 430
 431     my $z = new IO::Uncompress::Bunzip2 $input [OPTS]
 432         or die "IO::Uncompress::Bunzip2 failed: $Bunzip2Error\n";
 433
 434 Returns an C<IO::Uncompress::Bunzip2> object on success and undef on failure.
 435 The variable C<$Bunzip2Error> will contain an error message on failure.
 436
 437 If you are running Perl 5.005 or better the object, C<$z>, returned from
 438 IO::Uncompress::Bunzip2 can be used exactly like an L<IO::File|IO::File> filehandle.
 439 This means that all normal input file operations can be carried out with
 440 C<$z>.  For example, to read a line from a compressed file/buffer you can
 441 use either of these forms
 442
 443     $line = $z->getline();
 444     $line = <$z>;
 445
 446 The mandatory parameter C<$input> is used to determine the source of the
 447 compressed data. This parameter can take one of three forms.
 448
 449 =over 5
 450
 451 =item A filename
 452
 453 If the C<$input> parameter is a scalar, it is assumed to be a filename. This
 454 file will be opened for reading and the compressed data will be read from it.
 455
 456 =item A filehandle
 457
 458 If the C<$input> parameter is a filehandle, the compressed data will be
 459 read from it.
 460 The string '-' can be used as an alias for standard input.
 461
 462 =item A scalar reference
 463
 464 If C<$input> is a scalar reference, the compressed data will be read from
 465 C<$$output>.
 466
 467 =back
 468
 469 =head2 Constructor Options
 470
 471 The option names defined below are case insensitive and can be optionally
 472 prefixed by a '-'.  So all of the following are valid
 473
 474     -AutoClose
 475     -autoclose
 476     AUTOCLOSE
 477     autoclose
 478
 479 OPTS is a combination of the following options:
 480
 481 =over 5
 482
 483 =item C<< AutoClose => 0|1 >>
 484
 485 This option is only valid when the C<$input> parameter is a filehandle. If
 486 specified, and the value is true, it will result in the file being closed once
 487 either the C<close> method is called or the IO::Uncompress::Bunzip2 object is
 488 destroyed.
 489
 490 This parameter defaults to 0.
 491
 492 =item C<< MultiStream => 0|1 >>
 493
 494 Allows multiple concatenated compressed streams to be treated as a single
 495 compressed stream. Decompression will stop once either the end of the
 496 file/buffer is reached, an error is encountered (premature eof, corrupt
 497 compressed data) or the end of a stream is not immediately followed by the
 498 start of another stream.
 499
 500 This parameter defaults to 0.
 501
 502 =item C<< Prime => $string >>
 503
 504 This option will uncompress the contents of C<$string> before processing the
 505 input file/buffer.
 506
 507 This option can be useful when the compressed data is embedded in another
 508 file/data structure and it is not possible to work out where the compressed
 509 data begins without having to read the first few bytes. If this is the
 510 case, the uncompression can be I<primed> with these bytes using this
 511 option.
 512
 513 =item C<< Transparent => 0|1 >>
 514
 515 If this option is set and the input file/buffer is not compressed data,
 516 the module will allow reading of it anyway.
 517
 518 In addition, if the input file/buffer does contain compressed data and
 519 there is non-compressed data immediately following it, setting this option
 520 will make this module treat the whole file/bufffer as a single data stream.
 521
 522 This option defaults to 1.
 523
 524 =item C<< BlockSize => $num >>
 525
 526 When reading the compressed input data, IO::Uncompress::Bunzip2 will read it in
 527 blocks of C<$num> bytes.
 528
 529 This option defaults to 4096.
 530
 531 =item C<< InputLength => $size >>
 532
 533 When present this option will limit the number of compressed bytes read
 534 from the input file/buffer to C<$size>. This option can be used in the
 535 situation where there is useful data directly after the compressed data
 536 stream and you know beforehand the exact length of the compressed data
 537 stream.
 538
 539 This option is mostly used when reading from a filehandle, in which case
 540 the file pointer will be left pointing to the first byte directly after the
 541 compressed data stream.
 542
 543 This option defaults to off.
 544
 545 =item C<< Append => 0|1 >>
 546
 547 This option controls what the C<read> method does with uncompressed data.
 548
 549 If set to 1, all uncompressed data will be appended to the output parameter
 550 of the C<read> method.
 551
 552 If set to 0, the contents of the output parameter of the C<read> method
 553 will be overwritten by the uncompressed data.
 554
 555 Defaults to 0.
 556
 557 =item C<< Strict => 0|1 >>
 558
 559 This option is a no-op.
 560
 561 =item C<< Small => 0|1 >>
 562
 563 When non-zero this options will make bzip2 use a decompression algorithm
 564 that uses less memory at the expense of increasing the amount of time
 565 taken for decompression.
 566
 567 Default is 0.
 568
 569 =back
 570
 571 =head2 Examples
 572
 573 TODO
 574
 575 =head1 Methods
 576
 577 =head2 read
 578
 579 Usage is
 580
 581     $status = $z->read($buffer)
 582
 583 Reads a block of compressed data (the size the the compressed block is
 584 determined by the C<Buffer> option in the constructor), uncompresses it and
 585 writes any uncompressed data into C<$buffer>. If the C<Append> parameter is
 586 set in the constructor, the uncompressed data will be appended to the
 587 C<$buffer> parameter. Otherwise C<$buffer> will be overwritten.
 588
 589 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
 590 or a negative number on error.
 591
 592 =head2 read
 593
 594 Usage is
 595
 596     $status = $z->read($buffer, $length)
 597     $status = $z->read($buffer, $length, $offset)
 598
 599     $status = read($z, $buffer, $length)
 600     $status = read($z, $buffer, $length, $offset)
 601
 602 Attempt to read C<$length> bytes of uncompressed data into C<$buffer>.
 603
 604 The main difference between this form of the C<read> method and the
 605 previous one, is that this one will attempt to return I<exactly> C<$length>
 606 bytes. The only circumstances that this function will not is if end-of-file
 607 or an IO error is encountered.
 608
 609 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
 610 or a negative number on error.
 611
 612 =head2 getline
 613
 614 Usage is
 615
 616     $line = $z->getline()
 617     $line = <$z>
 618
 619 Reads a single line.
 620
 621 This method fully supports the use of of the variable C<$/> (or
 622 C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use) to
 623 determine what constitutes an end of line. Paragraph mode, record mode and
 624 file slurp mode are all supported.
 625
 626 =head2 getc
 627
 628 Usage is
 629
 630     $char = $z->getc()
 631
 632 Read a single character.
 633
 634 =head2 ungetc
 635
 636 Usage is
 637
 638     $char = $z->ungetc($string)
 639
 640 =head2 getHeaderInfo
 641
 642 Usage is
 643
 644     $hdr  = $z->getHeaderInfo();
 645     @hdrs = $z->getHeaderInfo();
 646
 647 This method returns either a hash reference (in scalar context) or a list
 648 or hash references (in array context) that contains information about each
 649 of the header fields in the compressed data stream(s).
 650
 651 =head2 tell
 652
 653 Usage is
 654
 655     $z->tell()
 656     tell $z
 657
 658 Returns the uncompressed file offset.
 659
 660 =head2 eof
 661
 662 Usage is
 663
 664     $z->eof();
 665     eof($z);
 666
 667 Returns true if the end of the compressed input stream has been reached.
 668
 669 =head2 seek
 670
 671     $z->seek($position, $whence);
 672     seek($z, $position, $whence);
 673
 674 Provides a sub-set of the C<seek> functionality, with the restriction
 675 that it is only legal to seek forward in the input file/buffer.
 676 It is a fatal error to attempt to seek backward.
 677
 678 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
 679 SEEK_CUR or SEEK_END.
 680
 681 Returns 1 on success, 0 on failure.
 682
 683 =head2 binmode
 684
 685 Usage is
 686
 687     $z->binmode
 688     binmode $z ;
 689
 690 This is a noop provided for completeness.
 691
 692 =head2 opened
 693
 694     $z->opened()
 695
 696 Returns true if the object currently refers to a opened file/buffer.
 697
 698 =head2 autoflush
 699
 700     my $prev = $z->autoflush()
 701     my $prev = $z->autoflush(EXPR)
 702
 703 If the C<$z> object is associated with a file or a filehandle, this method
 704 returns the current autoflush setting for the underlying filehandle. If
 705 C<EXPR> is present, and is non-zero, it will enable flushing after every
 706 write/print operation.
 707
 708 If C<$z> is associated with a buffer, this method has no effect and always
 709 returns C<undef>.
 710
 711 B<Note> that the special variable C<$|> B<cannot> be used to set or
 712 retrieve the autoflush setting.
 713
 714 =head2 input_line_number
 715
 716     $z->input_line_number()
 717     $z->input_line_number(EXPR)
 718
 719 Returns the current uncompressed line number. If C<EXPR> is present it has
 720 the effect of setting the line number. Note that setting the line number
 721 does not change the current position within the file/buffer being read.
 722
 723 The contents of C<$/> are used to to determine what constitutes a line
 724 terminator.
 725
 726 =head2 fileno
 727
 728     $z->fileno()
 729     fileno($z)
 730
 731 If the C<$z> object is associated with a file or a filehandle, C<fileno>
 732 will return the underlying file descriptor. Once the C<close> method is
 733 called C<fileno> will return C<undef>.
 734
 735 If the C<$z> object is is associated with a buffer, this method will return
 736 C<undef>.
 737
 738 =head2 close
 739
 740     $z->close() ;
 741     close $z ;
 742
 743 Closes the output file/buffer.
 744
 745 For most versions of Perl this method will be automatically invoked if
 746 the IO::Uncompress::Bunzip2 object is destroyed (either explicitly or by the
 747 variable with the reference to the object going out of scope). The
 748 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
 749 these cases, the C<close> method will be called automatically, but
 750 not until global destruction of all live objects when the program is
 751 terminating.
 752
 753 Therefore, if you want your scripts to be able to run on all versions
 754 of Perl, you should call C<close> explicitly and not rely on automatic
 755 closing.
 756
 757 Returns true on success, otherwise 0.
 758
 759 If the C<AutoClose> option has been enabled when the IO::Uncompress::Bunzip2
 760 object was created, and the object is associated with a file, the
 761 underlying file will also be closed.
 762
 763 =head2 nextStream
 764
 765 Usage is
 766
 767     my $status = $z->nextStream();
 768
 769 Skips to the next compressed data stream in the input file/buffer. If a new
 770 compressed data stream is found, the eof marker will be cleared and C<$.>
 771 will be reset to 0.
 772
 773 Returns 1 if a new stream was found, 0 if none was found, and -1 if an
 774 error was encountered.
 775
 776 =head2 trailingData
 777
 778 Usage is
 779
 780     my $data = $z->trailingData();
 781
 782 Returns the data, if any, that is present immediately after the compressed
 783 data stream once uncompression is complete. It only makes sense to call
 784 this method once the end of the compressed data stream has been
 785 encountered.
 786
 787 This option can be used when there is useful information immediately
 788 following the compressed data stream, and you don't know the length of the
 789 compressed data stream.
 790
 791 If the input is a buffer, C<trailingData> will return everything from the
 792 end of the compressed data stream to the end of the buffer.
 793
 794 If the input is a filehandle, C<trailingData> will return the data that is
 795 left in the filehandle input buffer once the end of the compressed data
 796 stream has been reached. You can then use the filehandle to read the rest
 797 of the input file.
 798
 799 Don't bother using C<trailingData> if the input is a filename.
 800
 801 If you know the length of the compressed data stream before you start
 802 uncompressing, you can avoid having to use C<trailingData> by setting the
 803 C<InputLength> option in the constructor.
 804
 805 =head1 Importing
 806
 807 No symbolic constants are required by this IO::Uncompress::Bunzip2 at present.
 808
 809 =over 5
 810
 811 =item :all
 812
 813 Imports C<bunzip2> and C<$Bunzip2Error>.
 814 Same as doing this
 815
 816     use IO::Uncompress::Bunzip2 qw(bunzip2 $Bunzip2Error) ;
 817
 818 =back
 819
 820 =head1 EXAMPLES
 821
 822 =head2 Working with Net::FTP
 823
 824 See L<IO::Uncompress::Bunzip2::FAQ|IO::Uncompress::Bunzip2::FAQ/"Compressed files and Net::FTP">
 825
 826 =head1 SEE ALSO
 827
 828 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::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
 829
 830 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
 831
 832 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
 833 L<Archive::Tar|Archive::Tar>,
 834 L<IO::Zlib|IO::Zlib>
 835
 836 The primary site for the bzip2 program is F<http://www.bzip.org>.
 837
 838 See the module L<Compress::Bzip2|Compress::Bzip2>
 839
 840 =head1 AUTHOR
 841
 842 This module was written by Paul Marquess, F<pmqs@cpan.org>.
 843
 844 =head1 MODIFICATION HISTORY
 845
 846 See the Changes file.
 847
 848 =head1 COPYRIGHT AND LICENSE
 849
 850 Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
 851
 852 This program is free software; you can redistribute it and/or
 853 modify it under the same terms as Perl itself.
 854